Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/pal/inc/socket_async.h

raw
1 // Copyright (c) Microsoft. All rights reserved.
2 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
4 /** @file socket_async.h
5 * @brief Abstracts non-blocking sockets.
6 */
7
8 #ifndef AZURE_SOCKET_ASYNC_H
9 #define AZURE_SOCKET_ASYNC_H
10
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14
15 #include <stdbool.h>
16 #include <stdint.h>
17 #include "azure_macro_utils/macro_utils.h"
18 #include "umock_c/umock_c_prod.h"
19
20 // socket_async exposes asynchronous socket operations while hiding OS-specifics. Committing to
21 // asynchronous operation also simplifies the interface compared to generic sockets.
22
23 #define SOCKET_ASYNC_INVALID_SOCKET -1
24
25 typedef struct
26 {
27 // Keepalive is disabled by default at the TCP level. If keepalive is desired, it
28 // is strongly recommended to use one of the higher level keepalive (ping) options rather
29 // than the TCP level because the higher level options provide server connection status
30 // in addition to keeping the connection open.
31 int keep_alive; // < 0 for system defaults, >= 0 to use supplied keep_alive, idle, interval, and count
32 int keep_idle; // seconds before first keepalive packet (ignored if keep_alive <= 0)
33 int keep_interval; // seconds between keepalive packets (ignored if keep_alive <= 0)
34 int keep_count; // number of times to try before declaring failure (ignored if keep_alive <= 0)
35 // It is acceptable to extend this struct by adding members for future enhancement,
36 // but existing members must not be altered to ensure back-compatibility.
37 } SOCKET_ASYNC_OPTIONS;
38 typedef SOCKET_ASYNC_OPTIONS* SOCKET_ASYNC_OPTIONS_HANDLE;
39
40 typedef int SOCKET_ASYNC_HANDLE;
41
42 /**
43 * @brief Create a non-blocking socket that is correctly configured for asynchronous use.
44 *
45 * @param sock Receives the created SOCKET_ASYNC_HANDLE.
46 *
47 * @param host_ipv4 The IPv4 of the SSL server to be contacted.
48 *
49 * @param port The port of the SSL server to use.
50 *
51 * @param is_UDP True for UDP, false for TCP.
52 *
53 * @param options A pointer to SOCKET_ASYNC_OPTIONS used during socket_async_create
54 * for TCP connections only. May be NULL. Ignored for UDP sockets.
55 * Need only exist for the duration of the socket_async_create call.
56 *
57 * @return @c The created and configured SOCKET_ASYNC_HANDLE if the API call is successful
58 * or SOCKET_ASYNC_INVALID_SOCKET in case it fails. Error logging is
59 * performed by the underlying concrete implementation, so no
60 * further error logging is necessary.
61 */
62 MOCKABLE_FUNCTION(, SOCKET_ASYNC_HANDLE, socket_async_create, uint32_t, host_ipv4, uint16_t, port, bool, is_UDP, SOCKET_ASYNC_OPTIONS_HANDLE, options);
63
64 /**
65 * @brief Check whether a newly-created socket_async has completed its initial connection.
66 *
67 * @param sock The created SOCKET_ASYNC_HANDLE to check for connection completion.
68 *
69 * @param is_created Receives the completion state if successful, set to false on failure.
70 *
71 * @return @c 0 if the API call is successful.
72 * MU_FAILURE means an unexpected error has occurred and the socket must be destroyed.
73 */
74 MOCKABLE_FUNCTION(, int, socket_async_is_create_complete, SOCKET_ASYNC_HANDLE, sock, bool*, is_complete);
75
76 /**
77 * @brief Send a message on the specified socket.
78 *
79 * @param sock The socket to be used.
80 *
81 * @param buffer The buffer containing the message to transmit.
82 *
83 * @param size The number of bytes to transmit.
84 *
85 * @param sent_count Receives the number of bytes transmitted. The N == 0
86 * case means normal operation but the socket's outgoing buffer was full.
87 *
88 * @return @c 0 if successful.
89 * MU_FAILURE means an unexpected error has occurred and the socket must be destroyed.
90 */
91 MOCKABLE_FUNCTION(, int, socket_async_send, SOCKET_ASYNC_HANDLE, sock, const void*, buffer, size_t, size, size_t*, sent_count);
92
93 /**
94 * @brief Receive a message on the specified socket.
95 *
96 * @param sock The socket to be used.
97 *
98 * @param buffer The buffer containing the message to receive.
99 *
100 * @param size The buffer size in bytes.
101 *
102 * @param received_count Receives the number of bytes received into the buffer.
103 *
104 * @return @c 0 if successful.
105 * MU_FAILURE means an unexpected error has occurred and the socket must be destroyed.
106 */
107 MOCKABLE_FUNCTION(, int, socket_async_receive, SOCKET_ASYNC_HANDLE, sock, void*, buffer, size_t, size, size_t*, received_count);
108
109
110 /**
111 * @brief Close the socket returned by socket_async_create.
112 *
113 * @param sock The socket to be destroyed (closed, in standard socket terms).
114 */
115 MOCKABLE_FUNCTION(, void, socket_async_destroy, SOCKET_ASYNC_HANDLE, sock);
116
117
118 #ifdef __cplusplus
119 }
120 #endif
121
122 #endif /* AZURE_SOCKET_ASYNC_H */