1 // 2 // Copyright 2021 Staysail Systems, Inc. <info@staysail.tech> 3 // Copyright 2018 Capitar IT Group BV <info@capitar.com> 4 // 5 // This software is supplied under the terms of the MIT License, a 6 // copy of which should be located in the distribution where this 7 // file was obtained (LICENSE.txt). A copy of the license may also be 8 // found online at https://opensource.org/licenses/MIT. 9 // 10 11 #ifndef NNG_NNG_H 12 #define NNG_NNG_H 13 14 // NNG (nanomsg-next-gen) is an improved implementation of the SP protocols. 15 // The APIs have changed, and there is no attempt to provide API compatibility 16 // with legacy libnanomsg. This file defines the library consumer-facing 17 // Public API. Use of definitions or declarations not found in this header 18 // file is specifically unsupported and strongly discouraged. 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include <stdbool.h> 25 #include <stddef.h> 26 #include <stdint.h> 27 28 // NNG_DECL is used on declarations to deal with scope. 29 // For building Windows DLLs, it should be the appropriate __declspec(). 30 // For shared libraries with platforms that support hidden visibility, 31 // it should evaluate to __attribute__((visibility("default"))). 32 #ifndef NNG_DECL 33 #if defined(_WIN32) && !defined(NNG_STATIC_LIB) 34 #if defined(NNG_SHARED_LIB) 35 #define NNG_DECL __declspec(dllexport) 36 #else 37 #define NNG_DECL __declspec(dllimport) 38 #endif // NNG_SHARED_LIB 39 #else 40 #if defined(NNG_SHARED_LIB) && defined(NNG_HIDDEN_VISIBILITY) 41 #define NNG_DECL __attribute__((visibility("default"))) 42 #else 43 #define NNG_DECL extern 44 #endif 45 #endif // _WIN32 && !NNG_STATIC_LIB 46 #endif // NNG_DECL 47 48 // NNG Library & API version. 49 // We use SemVer, and these versions are about the API, and 50 // may not necessarily match the ABI versions. 51 #define NNG_MAJOR_VERSION 1 52 #define NNG_MINOR_VERSION 5 53 #define NNG_PATCH_VERSION 2 54 #define NNG_RELEASE_SUFFIX "" // if non-empty, this is a pre-release 55 56 // Maximum length of a socket address. This includes the terminating NUL. 57 // This limit is built into other implementations, so do not change it. 58 // Note that some transports are quite happy to let you use addresses 59 // in excess of this, but if you do you may not be able to communicate 60 // with other implementations. 61 #define NNG_MAXADDRLEN (128) 62 63 // NNG_PROTOCOL_NUMBER is used by protocol headers to calculate their 64 // protocol number from a major and minor number. Applications should 65 // probably not need to use this. 66 #define NNG_PROTOCOL_NUMBER(maj, min) (((x) *16) + (y)) 67 68 // Types common to nng. 69 70 // Identifiers are wrapped in a structure to improve compiler validation 71 // of incorrect passing. This gives us strong type checking. Modern 72 // compilers compile passing these by value to identical code as passing 73 // the integer type (at least with optimization applied). Please do not 74 // access the ID member directly. 75 76 typedef struct nng_ctx_s { 77 uint32_t id; 78 } nng_ctx; 79 80 typedef struct nng_dialer_s { 81 uint32_t id; 82 } nng_dialer; 83 84 typedef struct nng_listener_s { 85 uint32_t id; 86 } nng_listener; 87 88 typedef struct nng_pipe_s { 89 uint32_t id; 90 } nng_pipe; 91 92 typedef struct nng_socket_s { 93 uint32_t id; 94 } nng_socket; 95 96 typedef int32_t nng_duration; // in milliseconds 97 typedef struct nng_msg nng_msg; 98 typedef struct nng_stat nng_stat; 99 typedef struct nng_aio nng_aio; 100 101 // Initializers. 102 // clang-format off 103 #define NNG_PIPE_INITIALIZER { 0 } 104 #define NNG_SOCKET_INITIALIZER { 0 } 105 #define NNG_DIALER_INITIALIZER { 0 } 106 #define NNG_LISTENER_INITIALIZER { 0 } 107 #define NNG_CTX_INITIALIZER { 0 } 108 // clang-format on 109 110 // Some address details. This is in some ways like a traditional sockets 111 // sockaddr, but we have our own to cope with our unique families, etc. 112 // The details of this structure are directly exposed to applications. 113 // These structures can be obtained via property lookups, etc. 114 struct nng_sockaddr_inproc { 115 uint16_t sa_family; 116 char sa_name[NNG_MAXADDRLEN]; 117 }; 118 119 struct nng_sockaddr_path { 120 uint16_t sa_family; 121 char sa_path[NNG_MAXADDRLEN]; 122 }; 123 124 struct nng_sockaddr_in6 { 125 uint16_t sa_family; 126 uint16_t sa_port; 127 uint8_t sa_addr[16]; 128 uint32_t sa_scope; 129 }; 130 struct nng_sockaddr_in { 131 uint16_t sa_family; 132 uint16_t sa_port; 133 uint32_t sa_addr; 134 }; 135 136 struct nng_sockaddr_zt { 137 uint16_t sa_family; 138 uint64_t sa_nwid; 139 uint64_t sa_nodeid; 140 uint32_t sa_port; 141 }; 142 143 struct nng_sockaddr_abstract { 144 uint16_t sa_family; 145 uint16_t sa_len; // will be 0 - 107 max. 146 uint8_t sa_name[107]; // 108 linux/windows, without leading NUL 147 }; 148 149 // nng_sockaddr_storage is the the size required to store any nng_sockaddr. 150 // This size must not change, and no individual nng_sockaddr type may grow 151 // larger than this without breaking binary compatibility. 152 struct nng_sockaddr_storage { 153 uint16_t sa_family; 154 uint64_t sa_pad[16]; 155 }; 156 157 typedef struct nng_sockaddr_inproc nng_sockaddr_inproc; 158 typedef struct nng_sockaddr_path nng_sockaddr_path; 159 typedef struct nng_sockaddr_path nng_sockaddr_ipc; 160 typedef struct nng_sockaddr_in nng_sockaddr_in; 161 typedef struct nng_sockaddr_in6 nng_sockaddr_in6; 162 typedef struct nng_sockaddr_zt nng_sockaddr_zt; 163 typedef struct nng_sockaddr_abstract nng_sockaddr_abstract; 164 typedef struct nng_sockaddr_storage nng_sockaddr_storage; 165 166 typedef union nng_sockaddr { 167 uint16_t s_family; 168 nng_sockaddr_ipc s_ipc; 169 nng_sockaddr_inproc s_inproc; 170 nng_sockaddr_in6 s_in6; 171 nng_sockaddr_in s_in; 172 nng_sockaddr_zt s_zt; 173 nng_sockaddr_abstract s_abstract; 174 nng_sockaddr_storage s_storage; 175 } nng_sockaddr; 176 177 enum nng_sockaddr_family { 178 NNG_AF_UNSPEC = 0, 179 NNG_AF_INPROC = 1, 180 NNG_AF_IPC = 2, 181 NNG_AF_INET = 3, 182 NNG_AF_INET6 = 4, 183 NNG_AF_ZT = 5, // ZeroTier 184 NNG_AF_ABSTRACT = 6 185 }; 186 187 // Scatter/gather I/O. 188 typedef struct nng_iov { 189 void * iov_buf; 190 size_t iov_len; 191 } nng_iov; 192 193 // Some definitions for durations used with timeouts. 194 #define NNG_DURATION_INFINITE (-1) 195 #define NNG_DURATION_DEFAULT (-2) 196 #define NNG_DURATION_ZERO (0) 197 198 // nng_fini is used to terminate the library, freeing certain global resources. 199 // This should only be called during atexit() or just before dlclose(). 200 // THIS FUNCTION MUST NOT BE CALLED CONCURRENTLY WITH ANY OTHER FUNCTION 201 // IN THIS LIBRARY; IT IS NOT REENTRANT OR THREADSAFE. 202 // 203 // For most cases, this call is unnecessary, but it is provided to assist 204 // when debugging with memory checkers (e.g. valgrind). Calling this 205 // function prevents global library resources from being reported incorrectly 206 // as memory leaks. In those cases, we recommend doing this with atexit(). 207 NNG_DECL void nng_fini(void); 208 209 // nng_close closes the socket, terminating all activity and 210 // closing any underlying connections and releasing any associated 211 // resources. 212 NNG_DECL int nng_close(nng_socket); 213 214 // nng_socket_id returns the positive socket id for the socket, or -1 215 // if the socket is not valid. 216 NNG_DECL int nng_socket_id(nng_socket); 217 218 NNG_DECL int nng_socket_set(nng_socket, const char *, const void *, size_t); 219 NNG_DECL int nng_socket_set_bool(nng_socket, const char *, bool); 220 NNG_DECL int nng_socket_set_int(nng_socket, const char *, int); 221 NNG_DECL int nng_socket_set_size(nng_socket, const char *, size_t); 222 NNG_DECL int nng_socket_set_uint64(nng_socket, const char *, uint64_t); 223 NNG_DECL int nng_socket_set_string(nng_socket, const char *, const char *); 224 NNG_DECL int nng_socket_set_ptr(nng_socket, const char *, void *); 225 NNG_DECL int nng_socket_set_ms(nng_socket, const char *, nng_duration); 226 NNG_DECL int nng_socket_set_addr( 227 nng_socket, const char *, const nng_sockaddr *); 228 229 NNG_DECL int nng_socket_get(nng_socket, const char *, void *, size_t *); 230 NNG_DECL int nng_socket_get_bool(nng_socket, const char *, bool *); 231 NNG_DECL int nng_socket_get_int(nng_socket, const char *, int *); 232 NNG_DECL int nng_socket_get_size(nng_socket, const char *, size_t *); 233 NNG_DECL int nng_socket_get_uint64(nng_socket, const char *, uint64_t *); 234 NNG_DECL int nng_socket_get_string(nng_socket, const char *, char **); 235 NNG_DECL int nng_socket_get_ptr(nng_socket, const char *, void **); 236 NNG_DECL int nng_socket_get_ms(nng_socket, const char *, nng_duration *); 237 NNG_DECL int nng_socket_get_addr(nng_socket, const char *, nng_sockaddr *); 238 239 // Arguably the pipe callback functions could be handled as an option, 240 // but with the need to specify an argument, we find it best to unify 241 // this as a separate function to pass in the argument and the callback. 242 // Only one callback can be set on a given socket, and there is no way 243 // to retrieve the old value. 244 typedef enum { 245 NNG_PIPE_EV_ADD_PRE, // Called just before pipe added to socket 246 NNG_PIPE_EV_ADD_POST, // Called just after pipe added to socket 247 NNG_PIPE_EV_REM_POST, // Called just after pipe removed from socket 248 NNG_PIPE_EV_NUM, // Used internally, must be last. 249 } nng_pipe_ev; 250 251 typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *); 252 253 // nng_pipe_notify registers a callback to be executed when the 254 // given event is triggered. To watch for different events, register 255 // multiple times. Each event can have at most one callback registered. 256 NNG_DECL int nng_pipe_notify(nng_socket, nng_pipe_ev, nng_pipe_cb, void *); 257 258 // nng_listen creates a listening endpoint with no special options, 259 // and starts it listening. It is functionally equivalent to the legacy 260 // nn_bind(). The underlying endpoint is returned back to the caller in the 261 // endpoint pointer, if it is not NULL. The flags are ignored at present. 262 NNG_DECL int nng_listen(nng_socket, const char *, nng_listener *, int); 263 264 // nng_dial creates a dialing endpoint, with no special options, and 265 // starts it dialing. Dialers have at most one active connection at a time 266 // This is similar to the legacy nn_connect(). The underlying endpoint 267 // is returned back to the caller in the endpoint pointer, if it is not NULL. 268 // The flags may be NNG_FLAG_NONBLOCK to indicate that the first attempt to 269 // dial will be made in the background, returning control to the caller 270 // immediately. In this case, if the connection fails, the function will 271 // keep retrying in the background. (If the connection is dropped in either 272 // case, it will still be reconnected in the background -- only the initial 273 // connection attempt is normally synchronous.) 274 NNG_DECL int nng_dial(nng_socket, const char *, nng_dialer *, int); 275 276 // nng_dialer_create creates a new dialer, that is not yet started. 277 NNG_DECL int nng_dialer_create(nng_dialer *, nng_socket, const char *); 278 279 // nng_listener_create creates a new listener, that is not yet started. 280 NNG_DECL int nng_listener_create(nng_listener *, nng_socket, const char *); 281 282 // nng_dialer_start starts the endpoint dialing. This is only possible if 283 // the dialer is not already dialing. 284 NNG_DECL int nng_dialer_start(nng_dialer, int); 285 286 // nng_listener_start starts the endpoint listening. This is only possible if 287 // the listener is not already listening. 288 NNG_DECL int nng_listener_start(nng_listener, int); 289 290 // nng_dialer_close closes the dialer, shutting down all underlying 291 // connections and releasing all associated resources. 292 NNG_DECL int nng_dialer_close(nng_dialer); 293 294 // nng_listener_close closes the listener, shutting down all underlying 295 // connections and releasing all associated resources. 296 NNG_DECL int nng_listener_close(nng_listener); 297 298 // nng_dialer_id returns the positive dialer ID, or -1 if the dialer is 299 // invalid. 300 NNG_DECL int nng_dialer_id(nng_dialer); 301 302 // nng_listener_id returns the positive listener ID, or -1 if the listener is 303 // invalid. 304 NNG_DECL int nng_listener_id(nng_listener); 305 306 NNG_DECL int nng_dialer_set(nng_dialer, const char *, const void *, size_t); 307 NNG_DECL int nng_dialer_set_bool(nng_dialer, const char *, bool); 308 NNG_DECL int nng_dialer_set_int(nng_dialer, const char *, int); 309 NNG_DECL int nng_dialer_set_size(nng_dialer, const char *, size_t); 310 NNG_DECL int nng_dialer_set_uint64(nng_dialer, const char *, uint64_t); 311 NNG_DECL int nng_dialer_set_string(nng_dialer, const char *, const char *); 312 NNG_DECL int nng_dialer_set_ptr(nng_dialer, const char *, void *); 313 NNG_DECL int nng_dialer_set_ms(nng_dialer, const char *, nng_duration); 314 NNG_DECL int nng_dialer_set_addr( 315 nng_dialer, const char *, const nng_sockaddr *); 316 317 NNG_DECL int nng_dialer_get(nng_dialer, const char *, void *, size_t *); 318 NNG_DECL int nng_dialer_get_bool(nng_dialer, const char *, bool *); 319 NNG_DECL int nng_dialer_get_int(nng_dialer, const char *, int *); 320 NNG_DECL int nng_dialer_get_size(nng_dialer, const char *, size_t *); 321 NNG_DECL int nng_dialer_get_uint64(nng_dialer, const char *, uint64_t *); 322 NNG_DECL int nng_dialer_get_string(nng_dialer, const char *, char **); 323 NNG_DECL int nng_dialer_get_ptr(nng_dialer, const char *, void **); 324 NNG_DECL int nng_dialer_get_ms(nng_dialer, const char *, nng_duration *); 325 NNG_DECL int nng_dialer_get_addr(nng_dialer, const char *, nng_sockaddr *); 326 327 NNG_DECL int nng_listener_set( 328 nng_listener, const char *, const void *, size_t); 329 NNG_DECL int nng_listener_set_bool(nng_listener, const char *, bool); 330 NNG_DECL int nng_listener_set_int(nng_listener, const char *, int); 331 NNG_DECL int nng_listener_set_size(nng_listener, const char *, size_t); 332 NNG_DECL int nng_listener_set_uint64(nng_listener, const char *, uint64_t); 333 NNG_DECL int nng_listener_set_string(nng_listener, const char *, const char *); 334 NNG_DECL int nng_listener_set_ptr(nng_listener, const char *, void *); 335 NNG_DECL int nng_listener_set_ms(nng_listener, const char *, nng_duration); 336 NNG_DECL int nng_listener_set_addr( 337 nng_listener, const char *, const nng_sockaddr *); 338 339 NNG_DECL int nng_listener_get(nng_listener, const char *, void *, size_t *); 340 NNG_DECL int nng_listener_get_bool(nng_listener, const char *, bool *); 341 NNG_DECL int nng_listener_get_int(nng_listener, const char *, int *); 342 NNG_DECL int nng_listener_get_size(nng_listener, const char *, size_t *); 343 NNG_DECL int nng_listener_get_uint64(nng_listener, const char *, uint64_t *); 344 NNG_DECL int nng_listener_get_string(nng_listener, const char *, char **); 345 NNG_DECL int nng_listener_get_ptr(nng_listener, const char *, void **); 346 NNG_DECL int nng_listener_get_ms(nng_listener, const char *, nng_duration *); 347 NNG_DECL int nng_listener_get_addr(nng_listener, const char *, nng_sockaddr *); 348 349 // nng_strerror returns a human readable string associated with the error 350 // code supplied. 351 NNG_DECL const char *nng_strerror(int); 352 353 // nng_send sends (or arranges to send) the data on the socket. Note that 354 // this function may (will!) return before any receiver has actually 355 // received the data. The return value will be zero to indicate that the 356 // socket has accepted the entire data for send, or an errno to indicate 357 // failure. The flags may include NNG_FLAG_NONBLOCK or NNG_FLAG_ALLOC. 358 // If the flag includes NNG_FLAG_ALLOC, then the function will call 359 // nng_free() on the supplied pointer & size on success. (If the call 360 // fails then the memory is not freed.) 361 NNG_DECL int nng_send(nng_socket, void *, size_t, int); 362 363 // nng_recv receives message data into the socket, up to the supplied size. 364 // The actual size of the message data will be written to the value pointed 365 // to by size. The flags may include NNG_FLAG_NONBLOCK and NNG_FLAG_ALLOC. 366 // If NNG_FLAG_ALLOC is supplied then the library will allocate memory for 367 // the caller. In that case the pointer to the allocated will be stored 368 // instead of the data itself. The caller is responsible for freeing the 369 // associated memory with nng_free(). 370 NNG_DECL int nng_recv(nng_socket, void *, size_t *, int); 371 372 // nng_sendmsg is like nng_send, but offers up a message structure, which 373 // gives the ability to provide more control over the message, including 374 // providing backtrace information. It also can take a message that was 375 // obtain via nn_recvmsg, allowing for zero copy forwarding. 376 NNG_DECL int nng_sendmsg(nng_socket, nng_msg *, int); 377 378 // nng_recvmsg is like nng_recv, but is used to obtain a message structure 379 // as well as the data buffer. This can be used to obtain more information 380 // about where the message came from, access raw headers, etc. It also 381 // can be passed off directly to nng_sendmsg. 382 NNG_DECL int nng_recvmsg(nng_socket, nng_msg **, int); 383 384 // nng_send_aio sends data on the socket asynchronously. As with nng_send, 385 // the completion may be executed before the data has actually been delivered, 386 // but only when it is accepted for delivery. The supplied AIO must have 387 // been initialized, and have an associated message. The message will be 388 // "owned" by the socket if the operation completes successfully. Otherwise 389 // the caller is responsible for freeing it. 390 NNG_DECL void nng_send_aio(nng_socket, nng_aio *); 391 392 // nng_recv_aio receives data on the socket asynchronously. On a successful 393 // result, the AIO will have an associated message, that can be obtained 394 // with nng_aio_get_msg(). The caller takes ownership of the message at 395 // this point. 396 NNG_DECL void nng_recv_aio(nng_socket, nng_aio *); 397 398 // Context support. User contexts are not supported by all protocols, 399 // but for those that do, they give a way to create multiple contexts 400 // on a single socket, each of which runs the protocol's state machinery 401 // independently, offering a way to achieve concurrent protocol support 402 // without resorting to raw mode sockets. See the protocol specific 403 // documentation for further details. (Note that at this time, only 404 // asynchronous send/recv are supported for contexts, but its easy enough 405 // to make synchronous versions with nng_aio_wait().) Note that nng_close 406 // of the parent socket will *block* as long as any contexts are open. 407 408 // nng_ctx_open creates a context. This returns NNG_ENOTSUP if the 409 // protocol implementation does not support separate contexts. 410 NNG_DECL int nng_ctx_open(nng_ctx *, nng_socket); 411 412 // nng_ctx_close closes the context. 413 NNG_DECL int nng_ctx_close(nng_ctx); 414 415 // nng_ctx_id returns the numeric id for the context; this will be 416 // a positive value for a valid context, or < 0 for an invalid context. 417 // A valid context is not necessarily an *open* context. 418 NNG_DECL int nng_ctx_id(nng_ctx); 419 420 // nng_ctx_recv receives asynchronously. It works like nng_recv_aio, but 421 // uses a local context instead of the socket global context. 422 NNG_DECL void nng_ctx_recv(nng_ctx, nng_aio *); 423 424 // nng_ctx_send sends asynchronously. It works like nng_send_aio, but 425 // uses a local context instead of the socket global context. 426 NNG_DECL void nng_ctx_send(nng_ctx, nng_aio *); 427 428 NNG_DECL int nng_ctx_get(nng_ctx, const char *, void *, size_t *); 429 NNG_DECL int nng_ctx_get_bool(nng_ctx, const char *, bool *); 430 NNG_DECL int nng_ctx_get_int(nng_ctx, const char *, int *); 431 NNG_DECL int nng_ctx_get_size(nng_ctx, const char *, size_t *); 432 NNG_DECL int nng_ctx_get_uint64(nng_ctx, const char *, uint64_t *); 433 NNG_DECL int nng_ctx_get_string(nng_ctx, const char *, char **); 434 NNG_DECL int nng_ctx_get_ptr(nng_ctx, const char *, void **); 435 NNG_DECL int nng_ctx_get_ms(nng_ctx, const char *, nng_duration *); 436 NNG_DECL int nng_ctx_get_addr(nng_ctx, const char *, nng_sockaddr *); 437 438 NNG_DECL int nng_ctx_set(nng_ctx, const char *, const void *, size_t); 439 NNG_DECL int nng_ctx_set_bool(nng_ctx, const char *, bool); 440 NNG_DECL int nng_ctx_set_int(nng_ctx, const char *, int); 441 NNG_DECL int nng_ctx_set_size(nng_ctx, const char *, size_t); 442 NNG_DECL int nng_ctx_set_uint64(nng_ctx, const char *, uint64_t); 443 NNG_DECL int nng_ctx_set_string(nng_ctx, const char *, const char *); 444 NNG_DECL int nng_ctx_set_ptr(nng_ctx, const char *, void *); 445 NNG_DECL int nng_ctx_set_ms(nng_ctx, const char *, nng_duration); 446 NNG_DECL int nng_ctx_set_addr(nng_ctx, const char *, const nng_sockaddr *); 447 448 // nng_alloc is used to allocate memory. It's intended purpose is for 449 // allocating memory suitable for message buffers with nng_send(). 450 // Applications that need memory for other purposes should use their platform 451 // specific API. 452 NNG_DECL void *nng_alloc(size_t); 453 454 // nng_free is used to free memory allocated with nng_alloc, which includes 455 // memory allocated by nng_recv() when the NNG_FLAG_ALLOC message is supplied. 456 // As the application is required to keep track of the size of memory, this 457 // is probably less convenient for general uses than the C library malloc and 458 // calloc. 459 NNG_DECL void nng_free(void *, size_t); 460 461 // nng_strdup duplicates the source string, using nng_alloc. The result 462 // should be freed with nng_strfree (or nng_free(strlen(s)+1)). 463 NNG_DECL char *nng_strdup(const char *); 464 465 // nng_strfree is equivalent to nng_free(strlen(s)+1). 466 NNG_DECL void nng_strfree(char *); 467 468 // Async IO API. AIO structures can be thought of as "handles" to 469 // support asynchronous operations. They contain the completion callback, and 470 // a pointer to consumer data. This is similar to how overlapped I/O 471 // works in Windows, when used with a completion callback. 472 // 473 // AIO structures can carry up to 4 distinct input values, and up to 474 // 4 distinct output values, and up to 4 distinct "private state" values. 475 // The meaning of the inputs and the outputs are determined by the 476 // I/O functions being called. 477 478 // nng_aio_alloc allocates a new AIO, and associated the completion 479 // callback and its opaque argument. If NULL is supplied for the 480 // callback, then the caller must use nng_aio_wait() to wait for the 481 // operation to complete. If the completion callback is not NULL, then 482 // when a submitted operation completes (or is canceled or fails) the 483 // callback will be executed, generally in a different thread, with no 484 // locks held. 485 NNG_DECL int nng_aio_alloc(nng_aio **, void (*)(void *), void *); 486 487 // nng_aio_free frees the AIO and any associated resources. 488 // It *must not* be in use at the time it is freed. 489 NNG_DECL void nng_aio_free(nng_aio *); 490 491 // nng_aio_reap is like nng_aio_free, but calls it from a background 492 // reaper thread. This can be useful to free aio objects from aio 493 // callbacks (e.g. when the result of the callback is to discard 494 // the object in question.) The aio object must be in further use 495 // when this is called. 496 NNG_DECL void nng_aio_reap(nng_aio *); 497 498 // nng_aio_stop stops any outstanding operation, and waits for the 499 // AIO to be free, including for the callback to have completed 500 // execution. Therefore the caller must NOT hold any locks that 501 // are acquired in the callback, or deadlock will occur. 502 NNG_DECL void nng_aio_stop(nng_aio *); 503 504 // nng_aio_result returns the status/result of the operation. This 505 // will be zero on successful completion, or an nng error code on 506 // failure. 507 NNG_DECL int nng_aio_result(nng_aio *); 508 509 // nng_aio_count returns the number of bytes transferred for certain 510 // I/O operations. This is meaningless for other operations (e.g. 511 // DNS lookups or TCP connection setup). 512 NNG_DECL size_t nng_aio_count(nng_aio *); 513 514 // nng_aio_cancel attempts to cancel any in-progress I/O operation. 515 // The AIO callback will still be executed, but if the cancellation is 516 // successful then the status will be NNG_ECANCELED. 517 NNG_DECL void nng_aio_cancel(nng_aio *); 518 519 // nng_aio_abort is like nng_aio_cancel, but allows for a different 520 // error result to be returned. 521 NNG_DECL void nng_aio_abort(nng_aio *, int); 522 523 // nng_aio_wait waits synchronously for any pending operation to complete. 524 // It also waits for the callback to have completed execution. Therefore, 525 // the caller of this function must not hold any locks acquired by the 526 // callback or deadlock may occur. 527 NNG_DECL void nng_aio_wait(nng_aio *); 528 529 // nng_aio_set_msg sets the message structure to use for asynchronous 530 // message send operations. 531 NNG_DECL void nng_aio_set_msg(nng_aio *, nng_msg *); 532 533 // nng_aio_get_msg returns the message structure associated with a completed 534 // receive operation. 535 NNG_DECL nng_msg *nng_aio_get_msg(nng_aio *); 536 537 // nng_aio_set_input sets an input parameter at the given index. 538 NNG_DECL int nng_aio_set_input(nng_aio *, unsigned, void *); 539 540 // nng_aio_get_input retrieves the input parameter at the given index. 541 NNG_DECL void *nng_aio_get_input(nng_aio *, unsigned); 542 543 // nng_aio_set_output sets an output result at the given index. 544 NNG_DECL int nng_aio_set_output(nng_aio *, unsigned, void *); 545 546 // nng_aio_get_output retrieves the output result at the given index. 547 NNG_DECL void *nng_aio_get_output(nng_aio *, unsigned); 548 549 // nng_aio_set_timeout sets a timeout on the AIO. This should be called for 550 // operations that should time out after a period. The timeout should be 551 // either a positive number of milliseconds, or NNG_DURATION_INFINITE to 552 // indicate that the operation has no timeout. A poll may be done by 553 // specifying NNG_DURATION_ZERO. The value NNG_DURATION_DEFAULT indicates 554 // that any socket specific timeout should be used. 555 NNG_DECL void nng_aio_set_timeout(nng_aio *, nng_duration); 556 557 // nng_aio_set_iov sets a scatter/gather vector on the aio. The iov array 558 // itself is copied. Data members (the memory regions referenced) *may* be 559 // copied as well, depending on the operation. This operation is guaranteed 560 // to succeed if n <= 4, otherwise it may fail due to NNG_ENOMEM. 561 NNG_DECL int nng_aio_set_iov(nng_aio *, unsigned, const nng_iov *); 562 563 // nng_aio_begin is called by the provider to mark the operation as 564 // beginning. If it returns false, then the provider must take no 565 // further action on the aio. 566 NNG_DECL bool nng_aio_begin(nng_aio *); 567 568 // nng_aio_finish is used to "finish" an asynchronous operation. 569 // It should only be called by "providers" (such as HTTP server API users). 570 // The argument is the value that nng_aio_result() should return. 571 // IMPORTANT: Callers must ensure that this is called EXACTLY ONCE on any 572 // given aio. 573 NNG_DECL void nng_aio_finish(nng_aio *, int); 574 575 // nng_aio_defer is used to register a cancellation routine, and indicate 576 // that the operation will be completed asynchronously. It must only be 577 // called once per operation on an aio, and must only be called by providers. 578 // If the operation is canceled by the consumer, the cancellation callback 579 // will be called. The provider *must* still ensure that the nng_aio_finish() 580 // function is called EXACTLY ONCE. If the operation cannot be canceled 581 // for any reason, the cancellation callback should do nothing. The 582 // final argument is passed to the cancelfn. The final argument of the 583 // cancellation function is the error number (will not be zero) corresponding 584 // to the reason for cancellation, e.g. NNG_ETIMEDOUT or NNG_ECANCELED. 585 typedef void (*nng_aio_cancelfn)(nng_aio *, void *, int); 586 NNG_DECL void nng_aio_defer(nng_aio *, nng_aio_cancelfn, void *); 587 588 // nng_aio_sleep does a "sleeping" operation, basically does nothing 589 // but wait for the specified number of milliseconds to expire, then 590 // calls the callback. This returns 0, rather than NNG_ETIMEDOUT. 591 NNG_DECL void nng_sleep_aio(nng_duration, nng_aio *); 592 593 // Message API. 594 NNG_DECL int nng_msg_alloc(nng_msg **, size_t); 595 NNG_DECL void nng_msg_free(nng_msg *); 596 NNG_DECL int nng_msg_realloc(nng_msg *, size_t); 597 NNG_DECL int nng_msg_reserve(nng_msg *, size_t); 598 NNG_DECL size_t nng_msg_capacity(nng_msg *); 599 NNG_DECL void * nng_msg_header(nng_msg *); 600 NNG_DECL size_t nng_msg_header_len(const nng_msg *); 601 NNG_DECL void * nng_msg_body(nng_msg *); 602 NNG_DECL size_t nng_msg_len(const nng_msg *); 603 NNG_DECL int nng_msg_append(nng_msg *, const void *, size_t); 604 NNG_DECL int nng_msg_insert(nng_msg *, const void *, size_t); 605 NNG_DECL int nng_msg_trim(nng_msg *, size_t); 606 NNG_DECL int nng_msg_chop(nng_msg *, size_t); 607 NNG_DECL int nng_msg_header_append(nng_msg *, const void *, size_t); 608 NNG_DECL int nng_msg_header_insert(nng_msg *, const void *, size_t); 609 NNG_DECL int nng_msg_header_trim(nng_msg *, size_t); 610 NNG_DECL int nng_msg_header_chop(nng_msg *, size_t); 611 NNG_DECL int nng_msg_header_append_u16(nng_msg *, uint16_t); 612 NNG_DECL int nng_msg_header_append_u32(nng_msg *, uint32_t); 613 NNG_DECL int nng_msg_header_append_u64(nng_msg *, uint64_t); 614 NNG_DECL int nng_msg_header_insert_u16(nng_msg *, uint16_t); 615 NNG_DECL int nng_msg_header_insert_u32(nng_msg *, uint32_t); 616 NNG_DECL int nng_msg_header_insert_u64(nng_msg *, uint64_t); 617 NNG_DECL int nng_msg_header_chop_u16(nng_msg *, uint16_t *); 618 NNG_DECL int nng_msg_header_chop_u32(nng_msg *, uint32_t *); 619 NNG_DECL int nng_msg_header_chop_u64(nng_msg *, uint64_t *); 620 NNG_DECL int nng_msg_header_trim_u16(nng_msg *, uint16_t *); 621 NNG_DECL int nng_msg_header_trim_u32(nng_msg *, uint32_t *); 622 NNG_DECL int nng_msg_header_trim_u64(nng_msg *, uint64_t *); 623 NNG_DECL int nng_msg_append_u16(nng_msg *, uint16_t); 624 NNG_DECL int nng_msg_append_u32(nng_msg *, uint32_t); 625 NNG_DECL int nng_msg_append_u64(nng_msg *, uint64_t); 626 NNG_DECL int nng_msg_insert_u16(nng_msg *, uint16_t); 627 NNG_DECL int nng_msg_insert_u32(nng_msg *, uint32_t); 628 NNG_DECL int nng_msg_insert_u64(nng_msg *, uint64_t); 629 NNG_DECL int nng_msg_chop_u16(nng_msg *, uint16_t *); 630 NNG_DECL int nng_msg_chop_u32(nng_msg *, uint32_t *); 631 NNG_DECL int nng_msg_chop_u64(nng_msg *, uint64_t *); 632 NNG_DECL int nng_msg_trim_u16(nng_msg *, uint16_t *); 633 NNG_DECL int nng_msg_trim_u32(nng_msg *, uint32_t *); 634 NNG_DECL int nng_msg_trim_u64(nng_msg *, uint64_t *); 635 NNG_DECL int nng_msg_dup(nng_msg **, const nng_msg *); 636 NNG_DECL void nng_msg_clear(nng_msg *); 637 NNG_DECL void nng_msg_header_clear(nng_msg *); 638 NNG_DECL void nng_msg_set_pipe(nng_msg *, nng_pipe); 639 NNG_DECL nng_pipe nng_msg_get_pipe(const nng_msg *); 640 641 // Pipe API. Generally pipes are only "observable" to applications, but 642 // we do permit an application to close a pipe. This can be useful, for 643 // example during a connection notification, to disconnect a pipe that 644 // is associated with an invalid or untrusted remote peer. 645 NNG_DECL int nng_pipe_get(nng_pipe, const char *, void *, size_t *); 646 NNG_DECL int nng_pipe_get_bool(nng_pipe, const char *, bool *); 647 NNG_DECL int nng_pipe_get_int(nng_pipe, const char *, int *); 648 NNG_DECL int nng_pipe_get_ms(nng_pipe, const char *, nng_duration *); 649 NNG_DECL int nng_pipe_get_size(nng_pipe, const char *, size_t *); 650 NNG_DECL int nng_pipe_get_uint64(nng_pipe, const char *, uint64_t *); 651 NNG_DECL int nng_pipe_get_string(nng_pipe, const char *, char **); 652 NNG_DECL int nng_pipe_get_ptr(nng_pipe, const char *, void **); 653 NNG_DECL int nng_pipe_get_addr(nng_pipe, const char *, nng_sockaddr *); 654 655 NNG_DECL int nng_pipe_close(nng_pipe); 656 NNG_DECL int nng_pipe_id(nng_pipe); 657 NNG_DECL nng_socket nng_pipe_socket(nng_pipe); 658 NNG_DECL nng_dialer nng_pipe_dialer(nng_pipe); 659 NNG_DECL nng_listener nng_pipe_listener(nng_pipe); 660 661 // Flags. 662 #define NNG_FLAG_ALLOC 1u // Recv to allocate receive buffer 663 #define NNG_FLAG_NONBLOCK 2u // Non-blocking operations 664 665 // Options. 666 #define NNG_OPT_SOCKNAME "socket-name" 667 #define NNG_OPT_RAW "raw" 668 #define NNG_OPT_PROTO "protocol" 669 #define NNG_OPT_PROTONAME "protocol-name" 670 #define NNG_OPT_PEER "peer" 671 #define NNG_OPT_PEERNAME "peer-name" 672 #define NNG_OPT_RECVBUF "recv-buffer" 673 #define NNG_OPT_SENDBUF "send-buffer" 674 #define NNG_OPT_RECVFD "recv-fd" 675 #define NNG_OPT_SENDFD "send-fd" 676 #define NNG_OPT_RECVTIMEO "recv-timeout" 677 #define NNG_OPT_SENDTIMEO "send-timeout" 678 #define NNG_OPT_LOCADDR "local-address" 679 #define NNG_OPT_REMADDR "remote-address" 680 #define NNG_OPT_URL "url" 681 #define NNG_OPT_MAXTTL "ttl-max" 682 #define NNG_OPT_RECVMAXSZ "recv-size-max" 683 #define NNG_OPT_RECONNMINT "reconnect-time-min" 684 #define NNG_OPT_RECONNMAXT "reconnect-time-max" 685 686 // TLS options are only used when the underlying transport supports TLS. 687 688 // NNG_OPT_TLS_CONFIG is a pointer to an nng_tls_config object. Generally 689 // this can used with endpoints, although once an endpoint is started, or 690 // once a configuration is used, the value becomes read-only. Note that 691 // when configuring the object, a hold is placed on the TLS configuration, 692 // using a reference count. When retrieving the object, no such hold is 693 // placed, and so the caller must take care not to use the associated object 694 // after the endpoint it is associated with is closed. 695 #define NNG_OPT_TLS_CONFIG "tls-config" 696 697 // NNG_OPT_TLS_AUTH_MODE is a write-only integer (int) option that specifies 698 // whether peer authentication is needed. The option can take one of the 699 // values of NNG_TLS_AUTH_MODE_NONE, NNG_TLS_AUTH_MODE_OPTIONAL, or 700 // NNG_TLS_AUTH_MODE_REQUIRED. The default is typically NNG_TLS_AUTH_MODE_NONE 701 // for listeners, and NNG_TLS_AUTH_MODE_REQUIRED for dialers. If set to 702 // REQUIRED, then connections will be rejected if the peer cannot be verified. 703 // If set to OPTIONAL, then a verification step takes place, but the connection 704 // is still permitted. (The result can be checked with NNG_OPT_TLS_VERIFIED). 705 #define NNG_OPT_TLS_AUTH_MODE "tls-authmode" 706 707 // NNG_OPT_TLS_CERT_KEY_FILE names a single file that contains a certificate 708 // and key identifying the endpoint. This is a write-only value. This can be 709 // set multiple times for times for different keys/certs corresponding to 710 // different algorithms on listeners, whereas dialers only support one. The 711 // file must contain both cert and key as PEM blocks, and the key must 712 // not be encrypted. (If more flexibility is needed, use the TLS configuration 713 // directly, via NNG_OPT_TLS_CONFIG.) 714 #define NNG_OPT_TLS_CERT_KEY_FILE "tls-cert-key-file" 715 716 // NNG_OPT_TLS_CA_FILE names a single file that contains certificate(s) for a 717 // CA, and optionally CRLs, which are used to validate the peer's certificate. 718 // This is a write-only value, but multiple CAs can be loaded by setting this 719 // multiple times. 720 #define NNG_OPT_TLS_CA_FILE "tls-ca-file" 721 722 // NNG_OPT_TLS_SERVER_NAME is a write-only string that can typically be 723 // set on dialers to check the CN of the server for a match. This 724 // can also affect SNI (server name indication). It usually has no effect 725 // on listeners. 726 #define NNG_OPT_TLS_SERVER_NAME "tls-server-name" 727 728 // NNG_OPT_TLS_VERIFIED returns a boolean indicating whether the peer has 729 // been verified (true) or not (false). Typically this is read-only, and 730 // only available for pipes. This option may return incorrect results if 731 // peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`. 732 #define NNG_OPT_TLS_VERIFIED "tls-verified" 733 734 // TCP options. These may be supported on various transports that use 735 // TCP underneath such as TLS, or not. 736 737 // TCP nodelay disables the use of Nagle, so that messages are sent 738 // as soon as data is available. This tends to reduce latency, but 739 // can come at the cost of extra messages being sent, and may have 740 // a detrimental effect on performance. For most uses, we recommend 741 // enabling this. (Disable it if you are on a very slow network.) 742 // This is a boolean. 743 #define NNG_OPT_TCP_NODELAY "tcp-nodelay" 744 745 // TCP keepalive causes the underlying transport to send keep-alive 746 // messages, and keep the session active. Keepalives are zero length 747 // messages with the ACK flag turned on. If we don't get an ACK back, 748 // then we know the other side is gone. This is useful for detecting 749 // dead peers, and is also used to prevent disconnections caused by 750 // middle boxes thinking the session has gone idle (e.g. keeping NAT 751 // state current). This is a boolean. 752 #define NNG_OPT_TCP_KEEPALIVE "tcp-keepalive" 753 754 // Local TCP port number. This is used on a listener, and is intended 755 // to be used after starting the listener in combination with a wildcard 756 // (0) local port. This determines the actual ephemeral port that was 757 // selected and bound. The value is provided as an int, but only the 758 // low order 16 bits will be set. This is provided in native byte order, 759 // which makes it more convenient than using the NNG_OPT_LOCADDR option. 760 #define NNG_OPT_TCP_BOUND_PORT "tcp-bound-port" 761 762 // IPC options. These will largely vary depending on the platform, 763 // as POSIX systems have very different options than Windows. 764 765 // Security Descriptor. This option may only be set on listeners 766 // on the Windows platform, where the object is a pointer to a 767 // a Windows SECURITY_DESCRIPTOR. 768 #define NNG_OPT_IPC_SECURITY_DESCRIPTOR "ipc:security-descriptor" 769 770 // Permissions bits. This option is only valid for listeners on 771 // POSIX platforms and others that honor UNIX style permission bits. 772 // Note that some platforms may not honor the permissions here, although 773 // at least Linux and macOS seem to do so. Check before you rely on 774 // this for security. 775 #define NNG_OPT_IPC_PERMISSIONS "ipc:permissions" 776 777 // Peer UID. This is only available on POSIX style systems. 778 #define NNG_OPT_IPC_PEER_UID "ipc:peer-uid" 779 780 // Peer GID (primary group). This is only available on POSIX style systems. 781 #define NNG_OPT_IPC_PEER_GID "ipc:peer-gid" 782 783 // Peer process ID. Available on Windows, Linux, and SunOS. 784 // In theory we could obtain this with the first message sent, 785 // but we have elected not to do this for now. (Nice RFE for a FreeBSD 786 // guru though.) 787 #define NNG_OPT_IPC_PEER_PID "ipc:peer-pid" 788 789 // Peer Zone ID. Only on SunOS systems. (Linux containers have no 790 // definable kernel identity; they are a user-land fabrication made up 791 // from various pieces of different namespaces. FreeBSD does have 792 // something called JailIDs, but it isn't obvious how to determine this, 793 // or even if processes can use IPC across jail boundaries.) 794 #define NNG_OPT_IPC_PEER_ZONEID "ipc:peer-zoneid" 795 796 // WebSocket Options. 797 798 // NNG_OPT_WS_REQUEST_HEADERS is a string containing the 799 // request headers, formatted as CRLF terminated lines. 800 #define NNG_OPT_WS_REQUEST_HEADERS "ws:request-headers" 801 802 // NNG_OPT_WS_RESPONSE_HEADERS is a string containing the 803 // response headers, formatted as CRLF terminated lines. 804 #define NNG_OPT_WS_RESPONSE_HEADERS "ws:response-headers" 805 806 // NNG_OPT_WS_REQUEST_HEADER is a prefix, for a dynamic 807 // property name. This allows direct access to any named header. 808 // Concatenate this with the name of the property (case is not sensitive). 809 // Only the first such header is returned. 810 #define NNG_OPT_WS_RESPONSE_HEADER "ws:response-header:" 811 812 // NNG_OPT_WS_RESPONSE_HEADER is like NNG_OPT_REQUEST_HEADER, but used for 813 // accessing the request headers. 814 #define NNG_OPT_WS_REQUEST_HEADER "ws:request-header:" 815 816 // NNG_OPT_WS_REQUEST_URI is used to obtain the URI sent by the client. 817 // This can be useful when a handler supports an entire directory tree. 818 #define NNG_OPT_WS_REQUEST_URI "ws:request-uri" 819 820 // NNG_OPT_WS_SENDMAXFRAME is used to configure the fragmentation size 821 // used for frames. This has a default value of 64k. Large values 822 // are good for throughput, but penalize latency. They also require 823 // additional buffering on the peer. This value must not be larger 824 // than what the peer will accept, and unfortunately there is no way 825 // to negotiate this. 826 #define NNG_OPT_WS_SENDMAXFRAME "ws:txframe-max" 827 828 // NNG_OPT_WS_RECVMAXFRAME is the largest frame we will accept. This should 829 // probably not be larger than NNG_OPT_RECVMAXSZ. If the sender attempts 830 // to send more data than this in a single message, it will be dropped. 831 #define NNG_OPT_WS_RECVMAXFRAME "ws:rxframe-max" 832 833 // NNG_OPT_WS_PROTOCOL is the "websocket sub-protocol" -- it's a string. 834 // This is also known as the Sec-WebSocket-Protocol header. It is treated 835 // specially. This is part of the websocket handshake. 836 #define NNG_OPT_WS_PROTOCOL "ws:protocol" 837 838 // NNG_OPT_WS_SEND_TEXT is a boolean used to tell the WS stream 839 // transport to send text messages. This is not supported for the 840 // core WebSocket transport, but when using streams it might be useful 841 // to speak with 3rd party WebSocket applications. This mode should 842 // not be used unless absolutely required. No validation of the message 843 // contents is performed by NNG; applications are expected to honor 844 // the requirement to send only valid UTF-8. (Compliant applications 845 // will close the socket if they see this message type with invalid UTF-8.) 846 #define NNG_OPT_WS_SEND_TEXT "ws:send-text" 847 848 // NNG_OPT_WS_RECV_TEXT is a boolean that enables NNG to receive 849 // TEXT frames. This is only useful for stream mode applications -- 850 // SP protocol requires the use of binary frames. Note also that 851 // NNG does not validate the message contents for valid UTF-8; this 852 // means it will not be conformant with RFC-6455 on it's own. Applications 853 // that need this should check the message contents themselves, and 854 // close the connection if invalid UTF-8 is received. This option 855 // should not be used unless required to communication with 3rd party 856 // peers that cannot be coerced into sending binary frames. 857 #define NNG_OPT_WS_RECV_TEXT "ws:recv-text" 858 859 // XXX: TBD: priorities, ipv4only 860 861 // Statistics. These are for informational purposes only, and subject 862 // to change without notice. The API for accessing these is stable, 863 // but the individual statistic names, values, and meanings are all 864 // subject to change. 865 866 // nng_stats_get takes a snapshot of the entire set of statistics. 867 // While the operation can be somewhat expensive (allocations), it 868 // is done in a way that minimizes impact to running operations. 869 // Note that the statistics are provided as a tree, with parents 870 // used for grouping, and with child statistics underneath. The 871 // top stat returned will be of type NNG_STAT_SCOPE with name "". 872 // Applications may choose to consider this root scope as "root", if 873 // the empty string is not suitable. 874 NNG_DECL int nng_stats_get(nng_stat **); 875 876 // nng_stats_free frees a previous list of snapshots. This should only 877 // be called on the parent statistic that obtained via nng_stats_get. 878 NNG_DECL void nng_stats_free(nng_stat *); 879 880 // nng_stats_dump is a debugging function that dumps the entire set of 881 // statistics to stdout. 882 NNG_DECL void nng_stats_dump(nng_stat *); 883 884 // nng_stat_next finds the next sibling for the current stat. If there 885 // are no more siblings, it returns NULL. 886 NNG_DECL nng_stat *nng_stat_next(nng_stat *); 887 888 // nng_stat_child finds the first child of the current stat. If no children 889 // exist, then NULL is returned. 890 NNG_DECL nng_stat *nng_stat_child(nng_stat *); 891 892 // nng_stat_name is used to determine the name of the statistic. 893 // This is a human readable name. Statistic names, as well as the presence 894 // or absence or semantic of any particular statistic are not part of any 895 // stable API, and may be changed without notice in future updates. 896 NNG_DECL const char *nng_stat_name(nng_stat *); 897 898 // nng_stat_type is used to determine the type of the statistic. 899 // Counters generally increment, and therefore changes in the value over 900 // time are likely more interesting than the actual level. Level 901 // values reflect some absolute state however, and should be presented to the 902 // user as is. 903 NNG_DECL int nng_stat_type(nng_stat *); 904 905 // nng_stat_find is used to find a specific named statistic within 906 // a statistic tree. NULL is returned if no such statistic exists. 907 NNG_DECL nng_stat *nng_stat_find(nng_stat *, const char *); 908 909 // nng_stat_find_socket is used to find the stats for the given socket. 910 NNG_DECL nng_stat *nng_stat_find_socket(nng_stat *, nng_socket); 911 912 // nng_stat_find_dialer is used to find the stats for the given dialer. 913 NNG_DECL nng_stat *nng_stat_find_dialer(nng_stat *, nng_dialer); 914 915 // nng_stat_find_listener is used to find the stats for the given listener. 916 NNG_DECL nng_stat *nng_stat_find_listener(nng_stat *, nng_listener); 917 918 enum nng_stat_type_enum { 919 NNG_STAT_SCOPE = 0, // Stat is for scoping, and carries no value 920 NNG_STAT_LEVEL = 1, // Numeric "absolute" value, diffs meaningless 921 NNG_STAT_COUNTER = 2, // Incrementing value (diffs are meaningful) 922 NNG_STAT_STRING = 3, // Value is a string 923 NNG_STAT_BOOLEAN = 4, // Value is a boolean 924 NNG_STAT_ID = 5, // Value is a numeric ID 925 }; 926 927 // nng_stat_unit provides information about the unit for the statistic, 928 // such as NNG_UNIT_BYTES or NNG_UNIT_BYTES. If no specific unit is 929 // applicable, such as a relative priority, then NN_UNIT_NONE is returned. 930 NNG_DECL int nng_stat_unit(nng_stat *); 931 932 enum nng_unit_enum { 933 NNG_UNIT_NONE = 0, // No special units 934 NNG_UNIT_BYTES = 1, // Bytes, e.g. bytes sent, etc. 935 NNG_UNIT_MESSAGES = 2, // Messages, one per message 936 NNG_UNIT_MILLIS = 3, // Milliseconds 937 NNG_UNIT_EVENTS = 4 // Some other type of event 938 }; 939 940 // nng_stat_value returns returns the actual value of the statistic. 941 // Statistic values reflect their value at the time that the corresponding 942 // snapshot was updated, and are undefined until an update is performed. 943 NNG_DECL uint64_t nng_stat_value(nng_stat *); 944 945 // nng_stat_value returns returns the actual value of the statistic. 946 // Statistic values reflect their value at the time that the corresponding 947 // snapshot was updated, and are undefined until an update is performed. 948 NNG_DECL bool nng_stat_bool(nng_stat *); 949 950 // nng_stat_string returns the string associated with a string statistic, 951 // or NULL if the statistic is not part of the string. The value returned 952 // is valid until the associated statistic is freed. 953 NNG_DECL const char *nng_stat_string(nng_stat *); 954 955 // nng_stat_desc returns a human readable description of the statistic. 956 // This may be useful for display in diagnostic interfaces, etc. 957 NNG_DECL const char *nng_stat_desc(nng_stat *); 958 959 // nng_stat_timestamp returns a timestamp (milliseconds) when the statistic 960 // was captured. The base offset is the same as used by nng_clock(). 961 // We don't use nng_time though, because that's in the supplemental header. 962 NNG_DECL uint64_t nng_stat_timestamp(nng_stat *); 963 964 // Device functionality. This connects two sockets together in a device, 965 // which means that messages from one side are forwarded to the other. 966 NNG_DECL int nng_device(nng_socket, nng_socket); 967 968 // Symbol name and visibility. TBD. The only symbols that really should 969 // be directly exported to runtimes IMO are the option symbols. And frankly 970 // they have enough special logic around them that it might be best not to 971 // automate the promotion of them to other APIs. This is an area open 972 // for discussion. 973 974 // Error codes. These generally have different values from UNIX errnos, 975 // so take care about converting them. The one exception is that 0 is 976 // unambiguously "success". 977 // 978 // NNG_SYSERR is a special code, which allows us to wrap errors from the 979 // underlying operating system. We generally prefer to map errors to one 980 // of the above, but if we cannot, then we just encode an error this way. 981 // The bit is large enough to accommodate all known UNIX and Win32 error 982 // codes. We try hard to match things semantically to one of our standard 983 // errors. For example, a connection reset or aborted we treat as a 984 // closed connection, because that's basically what it means. (The remote 985 // peer closed the connection.) For certain kinds of resource exhaustion 986 // we treat it the same as memory. But for files, etc. that's OS-specific, 987 // and we use the generic below. Some of the above error codes we use 988 // internally, and the application should never see (e.g. NNG_EINTR). 989 // 990 // NNG_ETRANERR is like ESYSERR, but is used to wrap transport specific 991 // errors, from different transports. It should only be used when none 992 // of the other options are available. 993 994 enum nng_errno_enum { 995 NNG_EINTR = 1, 996 NNG_ENOMEM = 2, 997 NNG_EINVAL = 3, 998 NNG_EBUSY = 4, 999 NNG_ETIMEDOUT = 5, 1000 NNG_ECONNREFUSED = 6, 1001 NNG_ECLOSED = 7, 1002 NNG_EAGAIN = 8, 1003 NNG_ENOTSUP = 9, 1004 NNG_EADDRINUSE = 10, 1005 NNG_ESTATE = 11, 1006 NNG_ENOENT = 12, 1007 NNG_EPROTO = 13, 1008 NNG_EUNREACHABLE = 14, 1009 NNG_EADDRINVAL = 15, 1010 NNG_EPERM = 16, 1011 NNG_EMSGSIZE = 17, 1012 NNG_ECONNABORTED = 18, 1013 NNG_ECONNRESET = 19, 1014 NNG_ECANCELED = 20, 1015 NNG_ENOFILES = 21, 1016 NNG_ENOSPC = 22, 1017 NNG_EEXIST = 23, 1018 NNG_EREADONLY = 24, 1019 NNG_EWRITEONLY = 25, 1020 NNG_ECRYPTO = 26, 1021 NNG_EPEERAUTH = 27, 1022 NNG_ENOARG = 28, 1023 NNG_EAMBIGUOUS = 29, 1024 NNG_EBADTYPE = 30, 1025 NNG_ECONNSHUT = 31, 1026 NNG_EINTERNAL = 1000, 1027 NNG_ESYSERR = 0x10000000, 1028 NNG_ETRANERR = 0x20000000 1029 }; 1030 1031 // URL support. We frequently want to process a URL, and these methods 1032 // give us a convenient way of doing so. 1033 1034 typedef struct nng_url { 1035 char *u_rawurl; // never NULL 1036 char *u_scheme; // never NULL 1037 char *u_userinfo; // will be NULL if not specified 1038 char *u_host; // including colon and port 1039 char *u_hostname; // name only, will be "" if not specified 1040 char *u_port; // port, will be "" if not specified 1041 char *u_path; // path, will be "" if not specified 1042 char *u_query; // without '?', will be NULL if not specified 1043 char *u_fragment; // without '#', will be NULL if not specified 1044 char *u_requri; // includes query and fragment, "" if not specified 1045 } nng_url; 1046 1047 // nng_url_parse parses a URL string into a structured form. 1048 // Note that the u_port member will be filled out with a numeric 1049 // port if one isn't specified and a default port is appropriate for 1050 // the scheme. The URL structure is allocated, along with individual 1051 // members. It can be freed with nng_url_free. 1052 NNG_DECL int nng_url_parse(nng_url **, const char *); 1053 1054 // nng_url_free frees a URL structure that was created by nng_url_parse(). 1055 NNG_DECL void nng_url_free(nng_url *); 1056 1057 // nng_url_clone clones a URL structure. 1058 NNG_DECL int nng_url_clone(nng_url **, const nng_url *); 1059 1060 // nng_version returns the library version as a human readable string. 1061 NNG_DECL const char *nng_version(void); 1062 1063 // nng_stream operations permit direct access to low level streams, 1064 // which can have a variety of uses. Internally most of the transports 1065 // are built on top of these. Streams are created by other dialers or 1066 // listeners. The API for creating dialers and listeners varies. 1067 1068 typedef struct nng_stream nng_stream; 1069 typedef struct nng_stream_dialer nng_stream_dialer; 1070 typedef struct nng_stream_listener nng_stream_listener; 1071 1072 NNG_DECL void nng_stream_free(nng_stream *); 1073 NNG_DECL void nng_stream_close(nng_stream *); 1074 NNG_DECL void nng_stream_send(nng_stream *, nng_aio *); 1075 NNG_DECL void nng_stream_recv(nng_stream *, nng_aio *); 1076 NNG_DECL int nng_stream_get(nng_stream *, const char *, void *, size_t *); 1077 NNG_DECL int nng_stream_get_bool(nng_stream *, const char *, bool *); 1078 NNG_DECL int nng_stream_get_int(nng_stream *, const char *, int *); 1079 NNG_DECL int nng_stream_get_ms(nng_stream *, const char *, nng_duration *); 1080 NNG_DECL int nng_stream_get_size(nng_stream *, const char *, size_t *); 1081 NNG_DECL int nng_stream_get_uint64(nng_stream *, const char *, uint64_t *); 1082 NNG_DECL int nng_stream_get_string(nng_stream *, const char *, char **); 1083 NNG_DECL int nng_stream_get_ptr(nng_stream *, const char *, void **); 1084 NNG_DECL int nng_stream_get_addr(nng_stream *, const char *, nng_sockaddr *); 1085 NNG_DECL int nng_stream_set(nng_stream *, const char *, const void *, size_t); 1086 NNG_DECL int nng_stream_set_bool(nng_stream *, const char *, bool); 1087 NNG_DECL int nng_stream_set_int(nng_stream *, const char *, int); 1088 NNG_DECL int nng_stream_set_ms(nng_stream *, const char *, nng_duration); 1089 NNG_DECL int nng_stream_set_size(nng_stream *, const char *, size_t); 1090 NNG_DECL int nng_stream_set_uint64(nng_stream *, const char *, uint64_t); 1091 NNG_DECL int nng_stream_set_string(nng_stream *, const char *, const char *); 1092 NNG_DECL int nng_stream_set_ptr(nng_stream *, const char *, void *); 1093 NNG_DECL int nng_stream_set_addr( 1094 nng_stream *, const char *, const nng_sockaddr *); 1095 1096 NNG_DECL int nng_stream_dialer_alloc(nng_stream_dialer **, const char *); 1097 NNG_DECL int nng_stream_dialer_alloc_url( 1098 nng_stream_dialer **, const nng_url *); 1099 NNG_DECL void nng_stream_dialer_free(nng_stream_dialer *); 1100 NNG_DECL void nng_stream_dialer_close(nng_stream_dialer *); 1101 NNG_DECL void nng_stream_dialer_dial(nng_stream_dialer *, nng_aio *); 1102 NNG_DECL int nng_stream_dialer_set( 1103 nng_stream_dialer *, const char *, const void *, size_t); 1104 NNG_DECL int nng_stream_dialer_get( 1105 nng_stream_dialer *, const char *, void *, size_t *); 1106 NNG_DECL int nng_stream_dialer_get_bool( 1107 nng_stream_dialer *, const char *, bool *); 1108 NNG_DECL int nng_stream_dialer_get_int( 1109 nng_stream_dialer *, const char *, int *); 1110 NNG_DECL int nng_stream_dialer_get_ms( 1111 nng_stream_dialer *, const char *, nng_duration *); 1112 NNG_DECL int nng_stream_dialer_get_size( 1113 nng_stream_dialer *, const char *, size_t *); 1114 NNG_DECL int nng_stream_dialer_get_uint64( 1115 nng_stream_dialer *, const char *, uint64_t *); 1116 NNG_DECL int nng_stream_dialer_get_string( 1117 nng_stream_dialer *, const char *, char **); 1118 NNG_DECL int nng_stream_dialer_get_ptr( 1119 nng_stream_dialer *, const char *, void **); 1120 NNG_DECL int nng_stream_dialer_get_addr( 1121 nng_stream_dialer *, const char *, nng_sockaddr *); 1122 NNG_DECL int nng_stream_dialer_set_bool( 1123 nng_stream_dialer *, const char *, bool); 1124 NNG_DECL int nng_stream_dialer_set_int(nng_stream_dialer *, const char *, int); 1125 NNG_DECL int nng_stream_dialer_set_ms( 1126 nng_stream_dialer *, const char *, nng_duration); 1127 NNG_DECL int nng_stream_dialer_set_size( 1128 nng_stream_dialer *, const char *, size_t); 1129 NNG_DECL int nng_stream_dialer_set_uint64( 1130 nng_stream_dialer *, const char *, uint64_t); 1131 NNG_DECL int nng_stream_dialer_set_string( 1132 nng_stream_dialer *, const char *, const char *); 1133 NNG_DECL int nng_stream_dialer_set_ptr( 1134 nng_stream_dialer *, const char *, void *); 1135 NNG_DECL int nng_stream_dialer_set_addr( 1136 nng_stream_dialer *, const char *, const nng_sockaddr *); 1137 1138 NNG_DECL int nng_stream_listener_alloc(nng_stream_listener **, const char *); 1139 NNG_DECL int nng_stream_listener_alloc_url( 1140 nng_stream_listener **, const nng_url *); 1141 NNG_DECL void nng_stream_listener_free(nng_stream_listener *); 1142 NNG_DECL void nng_stream_listener_close(nng_stream_listener *); 1143 NNG_DECL int nng_stream_listener_listen(nng_stream_listener *); 1144 NNG_DECL void nng_stream_listener_accept(nng_stream_listener *, nng_aio *); 1145 NNG_DECL int nng_stream_listener_set( 1146 nng_stream_listener *, const char *, const void *, size_t); 1147 NNG_DECL int nng_stream_listener_get( 1148 nng_stream_listener *, const char *, void *, size_t *); 1149 NNG_DECL int nng_stream_listener_get_bool( 1150 nng_stream_listener *, const char *, bool *); 1151 NNG_DECL int nng_stream_listener_get_int( 1152 nng_stream_listener *, const char *, int *); 1153 NNG_DECL int nng_stream_listener_get_ms( 1154 nng_stream_listener *, const char *, nng_duration *); 1155 NNG_DECL int nng_stream_listener_get_size( 1156 nng_stream_listener *, const char *, size_t *); 1157 NNG_DECL int nng_stream_listener_get_uint64( 1158 nng_stream_listener *, const char *, uint64_t *); 1159 NNG_DECL int nng_stream_listener_get_string( 1160 nng_stream_listener *, const char *, char **); 1161 NNG_DECL int nng_stream_listener_get_ptr( 1162 nng_stream_listener *, const char *, void **); 1163 NNG_DECL int nng_stream_listener_get_addr( 1164 nng_stream_listener *, const char *, nng_sockaddr *); 1165 NNG_DECL int nng_stream_listener_set_bool( 1166 nng_stream_listener *, const char *, bool); 1167 NNG_DECL int nng_stream_listener_set_int( 1168 nng_stream_listener *, const char *, int); 1169 NNG_DECL int nng_stream_listener_set_ms( 1170 nng_stream_listener *, const char *, nng_duration); 1171 NNG_DECL int nng_stream_listener_set_size( 1172 nng_stream_listener *, const char *, size_t); 1173 NNG_DECL int nng_stream_listener_set_uint64( 1174 nng_stream_listener *, const char *, uint64_t); 1175 NNG_DECL int nng_stream_listener_set_string( 1176 nng_stream_listener *, const char *, const char *); 1177 NNG_DECL int nng_stream_listener_set_ptr( 1178 nng_stream_listener *, const char *, void *); 1179 NNG_DECL int nng_stream_listener_set_addr( 1180 nng_stream_listener *, const char *, const nng_sockaddr *); 1181 1182 1183 #ifndef NNG_ELIDE_DEPRECATED 1184 // These are legacy APIs that have been deprecated. 1185 // Their use is strongly discouraged. 1186 1187 // nng_msg_getopt is defunct, and should not be used by programs. It 1188 // always returns NNG_ENOTSUP. 1189 NNG_DECL int nng_msg_getopt(nng_msg *, int, void *, size_t *); 1190 1191 // Socket options. Use nng_socket_get and nng_socket_set isnetadl 1192 NNG_DECL int nng_getopt(nng_socket, const char *, void *, size_t *); 1193 NNG_DECL int nng_getopt_bool(nng_socket, const char *, bool *); 1194 NNG_DECL int nng_getopt_int(nng_socket, const char *, int *); 1195 NNG_DECL int nng_getopt_ms(nng_socket, const char *, nng_duration *); 1196 NNG_DECL int nng_getopt_size(nng_socket, const char *, size_t *); 1197 NNG_DECL int nng_getopt_uint64(nng_socket, const char *, uint64_t *); 1198 NNG_DECL int nng_getopt_ptr(nng_socket, const char *, void **); 1199 NNG_DECL int nng_getopt_string(nng_socket, const char *, char **); 1200 NNG_DECL int nng_setopt(nng_socket, const char *, const void *, size_t); 1201 NNG_DECL int nng_setopt_bool(nng_socket, const char *, bool); 1202 NNG_DECL int nng_setopt_int(nng_socket, const char *, int); 1203 NNG_DECL int nng_setopt_ms(nng_socket, const char *, nng_duration); 1204 NNG_DECL int nng_setopt_size(nng_socket, const char *, size_t); 1205 NNG_DECL int nng_setopt_uint64(nng_socket, const char *, uint64_t); 1206 NNG_DECL int nng_setopt_string(nng_socket, const char *, const char *); 1207 NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *); 1208 1209 // Context options. Use nng_ctx_get and nng_ctx_set instead. 1210 NNG_DECL int nng_ctx_getopt(nng_ctx, const char *, void *, size_t *); 1211 NNG_DECL int nng_ctx_getopt_bool(nng_ctx, const char *, bool *); 1212 NNG_DECL int nng_ctx_getopt_int(nng_ctx, const char *, int *); 1213 NNG_DECL int nng_ctx_getopt_ms(nng_ctx, const char *, nng_duration *); 1214 NNG_DECL int nng_ctx_getopt_size(nng_ctx, const char *, size_t *); 1215 NNG_DECL int nng_ctx_setopt(nng_ctx, const char *, const void *, size_t); 1216 NNG_DECL int nng_ctx_setopt_bool(nng_ctx, const char *, bool); 1217 NNG_DECL int nng_ctx_setopt_int(nng_ctx, const char *, int); 1218 NNG_DECL int nng_ctx_setopt_ms(nng_ctx, const char *, nng_duration); 1219 NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t); 1220 1221 // Dialer options. Use nng_dialer_get and nng_dialer_set instead. 1222 NNG_DECL int nng_dialer_getopt(nng_dialer, const char *, void *, size_t *); 1223 NNG_DECL int nng_dialer_getopt_bool(nng_dialer, const char *, bool *); 1224 NNG_DECL int nng_dialer_getopt_int(nng_dialer, const char *, int *); 1225 NNG_DECL int nng_dialer_getopt_ms(nng_dialer, const char *, nng_duration *); 1226 NNG_DECL int nng_dialer_getopt_size(nng_dialer, const char *, size_t *); 1227 NNG_DECL int nng_dialer_getopt_sockaddr( 1228 nng_dialer, const char *, nng_sockaddr *); 1229 NNG_DECL int nng_dialer_getopt_uint64(nng_dialer, const char *, uint64_t *); 1230 NNG_DECL int nng_dialer_getopt_ptr(nng_dialer, const char *, void **); 1231 NNG_DECL int nng_dialer_getopt_string(nng_dialer, const char *, char **); 1232 NNG_DECL int nng_dialer_setopt(nng_dialer, const char *, const void *, size_t); 1233 NNG_DECL int nng_dialer_setopt_bool(nng_dialer, const char *, bool); 1234 NNG_DECL int nng_dialer_setopt_int(nng_dialer, const char *, int); 1235 NNG_DECL int nng_dialer_setopt_ms(nng_dialer, const char *, nng_duration); 1236 NNG_DECL int nng_dialer_setopt_size(nng_dialer, const char *, size_t); 1237 NNG_DECL int nng_dialer_setopt_uint64(nng_dialer, const char *, uint64_t); 1238 NNG_DECL int nng_dialer_setopt_ptr(nng_dialer, const char *, void *); 1239 NNG_DECL int nng_dialer_setopt_string(nng_dialer, const char *, const char *); 1240 1241 // Listener options. Use nng_listener_get and nng_listener_set instead. 1242 NNG_DECL int nng_listener_getopt(nng_listener, const char *, void *, size_t *); 1243 NNG_DECL int nng_listener_getopt_bool(nng_listener, const char *, bool *); 1244 NNG_DECL int nng_listener_getopt_int(nng_listener, const char *, int *); 1245 NNG_DECL int nng_listener_getopt_ms( 1246 nng_listener, const char *, nng_duration *); 1247 NNG_DECL int nng_listener_getopt_size(nng_listener, const char *, size_t *); 1248 NNG_DECL int nng_listener_getopt_sockaddr( 1249 nng_listener, const char *, nng_sockaddr *); 1250 NNG_DECL int nng_listener_getopt_uint64( 1251 nng_listener, const char *, uint64_t *); 1252 NNG_DECL int nng_listener_getopt_ptr(nng_listener, const char *, void **); 1253 NNG_DECL int nng_listener_getopt_string(nng_listener, const char *, char **); 1254 NNG_DECL int nng_listener_setopt( 1255 nng_listener, const char *, const void *, size_t); 1256 NNG_DECL int nng_listener_setopt_bool(nng_listener, const char *, bool); 1257 NNG_DECL int nng_listener_setopt_int(nng_listener, const char *, int); 1258 NNG_DECL int nng_listener_setopt_ms(nng_listener, const char *, nng_duration); 1259 NNG_DECL int nng_listener_setopt_size(nng_listener, const char *, size_t); 1260 NNG_DECL int nng_listener_setopt_uint64(nng_listener, const char *, uint64_t); 1261 NNG_DECL int nng_listener_setopt_ptr(nng_listener, const char *, void *); 1262 NNG_DECL int nng_listener_setopt_string( 1263 nng_listener, const char *, const char *); 1264 1265 // Pipe options. Use nng_pipe_get instead. 1266 NNG_DECL int nng_pipe_getopt(nng_pipe, const char *, void *, size_t *); 1267 NNG_DECL int nng_pipe_getopt_bool(nng_pipe, const char *, bool *); 1268 NNG_DECL int nng_pipe_getopt_int(nng_pipe, const char *, int *); 1269 NNG_DECL int nng_pipe_getopt_ms(nng_pipe, const char *, nng_duration *); 1270 NNG_DECL int nng_pipe_getopt_size(nng_pipe, const char *, size_t *); 1271 NNG_DECL int nng_pipe_getopt_sockaddr(nng_pipe, const char *, nng_sockaddr *); 1272 NNG_DECL int nng_pipe_getopt_uint64(nng_pipe, const char *, uint64_t *); 1273 NNG_DECL int nng_pipe_getopt_ptr(nng_pipe, const char *, void **); 1274 NNG_DECL int nng_pipe_getopt_string(nng_pipe, const char *, char **); 1275 1276 // nng_closeall closes all open sockets. Do not call this from 1277 // a library; it will affect all sockets. 1278 NNG_DECL void nng_closeall(void); 1279 1280 #endif 1281 1282 #ifdef __cplusplus 1283 } 1284 #endif 1285 1286 #endif // NNG_NNG_H 1287