diff options
Diffstat (limited to 'src/nng.h')
| -rw-r--r-- | src/nng.h | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/src/nng.h b/src/nng.h new file mode 100644 index 00000000..1075b95a --- /dev/null +++ b/src/nng.h @@ -0,0 +1,426 @@ +/* + * Copyright 2016 Garrett D'Amore <garrett@damore.org> + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom + * the Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included + * in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + * IN THE SOFTWARE. + */ + +#ifndef NNG_H +#define NNG_H + +/* + * NNG (nanomsg-ng) is a next generation implementation of the SP protocols. + * The APIs have changed, and there is no attempt to provide API compatibility + * with legacy libnanomsg. This file defines the library consumer-facing + * Public API. Use of definitions or declarations not found in this header file + * is specfically unsupported and strongly discouraged. + */ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <errno.h> +#include <stddef.h> +#include <stdint.h> + +/* + * NNG_DECL is used on declarations to deal with scope. + * For building Windows DLLs, it should be the appropriate + * __declspec(). (We recommend *not* building this library + * as a DLL, but instead linking it statically for your projects + * to minimize questions about link dependencies later.) + */ +#ifndef NNG_DECL +#define NNG_DECL extern +#endif + +/* + * Types common to nng. + */ +typedef struct nng_socket *nng_socket_t; +typedef struct nng_endpt *nng_endpt_t; +typedef struct nn_pipe *nng_pipe_t; +typedef struct nn_msg *nng_msg_t; +typedef struct nn_event *nng_event_t; +typedef struct nng_notify *nng_notify_t; +typedef struct nng_snapshot *nng_snapshot_t; +typedef struct nng_stat *nng_stat_t; + +/* + * nng_socket simply creates a socket of the given class. It returns an + * error code on failure, or zero on success. The socket starts in cooked + * mode. + */ +NNG_DECL int nng_socket_create(nng_socket_t *, int proto); + +/* + * nng_socket_close closes the socket, terminating all activity and + * closing any underlying connections and releasing any associated + * resources. Memory associated with the socket is freed, so it is an + * error to reference the socket in any way after this is called. Likewise, + * it is an error to reference any resources such as end points associated + * with the socket. + */ +NNG_DECL int nng_socket_close(nng_socket_t); + +/* + * nng_socket_setopt sets an option for a specific socket. + */ +NNG_DECL int nng_socket_setopt(nng_socket_t, int, void *, size_t); + +/* + * nng_socket_getopt obtains the option for a socket. + */ +NNG_DECL int nng_socket_getopt(nng_socket_t, int, void *, size_t *); + +/* + * nng_notify_register sets a notification callback. The callback will be + * called for any of the requested events. The callback can be deregistered + * by calling nng_notify_unregister with the same handle. These notification + * callbacks are executed on a separate thread, to avoid potential lock + * recursion. + */ +NNG_DECL nng_notify_t nng_notify_register(nng_socket_t, int, + void (*)(nng_socket_t, nng_event_t, void *), void *); +NNG_DECL int nng_notify_unregister(nng_socket_t, nng_notify_t); + +/* + * Event types. Sockets can have multiple different kind of events. + * Note that these are edge triggered -- therefore the status indicated + * may have changed since the notification occurred. + * + * NNG_EVENT_RECV - A message is ready for receive. + * NNG_EVENT_SEND - A message can be sent. + * NNG_EVENT_ERROR - An error condition on the socket occurred. + * NNG_EVENT_PIPE_ADD - A new pipe (connection) is added to the socket. + * The argument is an nn_pipe_t. + * NNG_EVENT_PIPE_RM - A pipe (connection) is removed from the socket. + * The argument is an nn_pipe_t. + * NNG_EVENT_ENDPT_ADD - An endpoint is added to the socket. + * The argument is an nn_endpt_t. + * NNG_EVENT_ENDPT_RM - An endpoint is removed from the socket. + * The argument is an nn_endpt_t. + */ +#define NNG_EVENT_BIT(x) (1U << (x)) +#define NNG_EVENT_RECV NNG_EVENT_BIT(0) +#define NNG_EVENT_SEND NNG_EVENT_BIT(1) +#define NNG_EVENT_ERROR NNG_EVENT_BIT(2) +#define NNG_EVENT_PIPE_ADD NNG_EVENT_BIT(3) +#define NNG_EVENT_PIPE_RM NNG_EVENT_BIT(4) +#define NNG_EVENT_ENDPT_ADD NNG_EVENT_BIT(5) +#define NNG_EVENT_ENDPT_RM NNG_EVENT_BIT(6) + +/* + * The following functions return more detailed information about the event. + * Some of the values will not make sense for some event types, in which case + * the value returned will be NULL. + */ +NNG_DECL int nng_event_type(nng_event_t); +NNG_DECL nng_socket_t nng_event_socket(nng_event_t); +NNG_DECL nng_endpt_t nng_event_endpt(nng_event_t); +NNG_DECL nng_pipe_t nng_event_pipe(nng_event_t); +NNG_DECL const char *nng_event_reason(nng_event_t); + +/* + * nng_socket_listen creates a listening endpoint with no special options, + * and starts it listening. It is functionally equivalent to the legacy + * nn_bind(). The underlying endpoint is returned back to the caller. + */ +NNG_DECL int nng_socket_listen(nng_endpt_t *, nng_socket_t, const char *); + +/* + * nng_socket_dial creates a dialing endpoint, with no special options, + * and starts it dialing. Dialers have at most one active connection at a + * time. This is similar to the legacy nn_connect(). The underlying endpoint + * is returned back to the caller. + */ +NNG_DECL int nng_socket_dial(nng_endpt_t *, nng_socket_t, const char *); + +/* + * nng_socket_endpt creates an endpoint on the socket, but does not + * start it either dialing or connecting. + */ +NNG_DECL int nng_socket_endpt(nng_endpt_t *, nng_socket_t, const char *); + +/* + * nng_endpt_dial starts the endpoint dialing. This is only possible if + * the endpoint is not already dialing or listening. + */ +NNG_DECL int nng_endpt_dial(nng_endpt_t); + +/* + * nng_endpt_listen starts the endpoint listening. This is only possible if + * the endpoint is not already dialing or listening. + */ +NNG_DECL int nng_endpt_listen(nng_endpt_t); + +/* + * nng_endpt_close closes the endpt, shutting down all underlying + * connections and releasing all associated resources. It is an error to + * refer to the endpoint after this is called. + */ +NNG_DECL int nng_endpt_close(nng_endpt_t); + +/* + * nng_endpt_setopt sets an option for a specific endpoint. Note + * endpoint options may not be altered on a running endpoint. + */ +NNG_DECL int nng_endpt_setopt(nng_endpt_t, int, void *, size_t); + +/* + * nng_endpt_getopt obtains the option for an endpoint. + */ +NNG_DECL int nng_endpt_getopt(nng_endpt_t, int, void *, size_t *); + +/* + * nng_strerror returns a human readable string associated with the error + * code supplied. + */ +NNG_DECL const char *nng_strerror(int); + +/* + * nng_send sends (or arranges to send) the data on the socket. Note that + * this function may (will!) return before any receiver has actually + * received the data. The return value will be zero to indicate that the + * socket has accepted the entire data for send, or an errno to indicate + * failure. The flags may include NNG_FLAG_NONBLOCK. + */ +NNG_DECL int nng_send(nng_socket_t, const void *, size_t, int); + +/* + * nng_recv receives message data into the socket, up to the supplied size. + * The actual size of the message data will be written to the value pointed + * to by size. The flags may include NNG_FLAG_NONBLOCK and NNG_FLAG_ALLOC. + * If NNG_FLAG_ALLOC is supplied then the library will allocate memory for + * the caller. In that case the pointer to the allocated will be stored + * instead of the data itself. The caller is responsible for freeing the + * associated memory with free(). + */ +NNG_DECL int nng_recv(nng_socket_t, void *, size_t *, int); + +/* + * nng_sendmsg is like nng_send, but offers up a message structure, which + * gives the ability to provide more control over the message, including + * providing backtrace information. It also can take a message that was + * obtain via nn_recvmsg, allowing for zero copy forwarding. + */ +NNG_DECL int nng_sendmsg(nng_socket_t, nng_msg_t, int); + +/* + * nng_recvmsg is like nng_recv, but is used to obtain a message structure + * as well as the data buffer. This can be used to obtain more information + * about where the message came from, access raw headers, etc. It also + * can be passed off directly to nng_sendmsg. + */ +NNG_DECL int nng_recvmsg(nng_socket_t, nng_msg_t *, int); + +/* + * Message API. + */ +NNG_DECL int nng_msg_alloc(nng_msg_t *, size_t); +NNG_DECL void nng_msg_free(nng_msg_t); +NNG_DECL const char *nng_msg_data(nng_msg_t); +NNG_DECL int nng_msg_realloc(nng_msg_t, size_t); +NNG_DECL void *nng_msg_header(nng_msg_t, size_t *); +NNG_DECL void *nng_msg_body(nng_msg_t, size_t *); +NNG_DECL int nng_msg_port(nng_msg_t, nng_pipe_t *); + +/* + * Pipe API. Generally pipes are only "observable" to applications, but + * we do permit an application to close a pipe. This can be useful, for + * example during a connection notification, to disconnect a pipe that + * is associated with an invalid or untrusted remote peer. + */ +NNG_DECL int nng_pipe_getopt(nng_pipe_t, int, void *, size_t *); +NNG_DECL int nng_pipe_close(nng_pipe_t); + +/* + * Protocol numbers. These are to be used with nng_socket_create(). + * These values are used on the wire, so must not be changed. The major + * number of the protocol is shifted left by 4 bits, and a subprotocol is + * assigned in the lower 4 bits. + * + * There are gaps in the list, which are obsolete or unsupported protocols. + * For now we assume that protocol numbers are never more than 16 bits. + */ +#define NNG_PROTO(major, minor) (((major) * 16) + (minor)) +#define NNG_PROTO_PAIR NNG_PROTO(1, 0) +#define NNG_PROTO_PUB NNG_PROTO(2, 0) +#define NNG_PROTO_SUB NNG_PROTO(2, 1) +#define NNG_PROTO_REQ NNG_PROTO(3, 0) +#define NNG_PROTO_REP NNG_PROTO(3, 1) +#define NNG_PROTO_PUSH NNG_PROTO(5, 0) +#define NNG_PROTO_PULL NNG_PROTO(5, 1) +#define NNG_PROTO_SURVEYOR NNG_PROTO(6, 2) +#define NNG_PROTO_RESPONDENT NNG_PROTO(6, 3) +#define NNG_PROTO_BUS NNG_PROTO(7, 0) +#define NNG_PROTO_STAR NNG_PROTO(100, 0) + +/* + * Options. We encode option numbers as follows: + * + * <level> - 0: socket, 1: transport + * <type> - zero (socket), or transport (8 bits) + * <code> - specific value (16 bits) + * + */ +#define NNG_OPT_SOCKET(c) (c) +#define NNG_OPT_TRANSPORT_OPT(t, c) (0x10000 | ((p) << 16) | (c)) + +#define NNG_OPT_RAW NNG_OPT_SOCKET(0) +#define NNG_OPT_LINGER NNG_OPT_SOCKET(1) +#define NNG_OPT_RCVBUF NNG_OPT_SOCKET(2) +#define NNG_OPT_SNDBUF NNG_OPT_SOCKET(3) +#define NNG_OPT_RCVTIMEO NNG_OPT_SOCKET(4) +#define NNG_OPT_SNDTIMEO NNG_OPT_SOCKET(5) +#define NNG_OPT_RECONN_TIME NNG_OPT_SOCKET(6) +#define NNG_OPT_RECONN_MAXTIME NNG_OPT_SOCKET(7) +#define NNG_OPT_RCVMAXSZ NNG_OPT_SOCKET(8) +#define NNG_OPT_MAXTTL NNG_OPT_SOCKET(9) +#define NNG_OPT_PROTOCOL NNG_OPT_SOCKET(10) +#define NNG_OPT_SUBSCRIBE NNG_OPT_SOCKET(11) +#define NNG_OPT_UNSUBSCRIBE NNG_OPT_SOCKET(12) +#define NNG_OPT_SURVEYTIME NNG_OPT_SOCKET(13) +#define NNG_OPT_RESENDTIME NNG_OPT_SOCKET(14) +#define NNG_OPT_TRANSPORT NNG_OPT_SOCKET(15) +#define NNG_OPT_LOCALADDR NNG_OPT_SOCKET(16) +#define NNG_OPT_REMOTEADDR NNG_OPT_SOCKET(17) +#define NNG_OPT_RECVFD NNG_OPT_SOCKET(18) +#define NNG_OPT_SENDFD NNG_OPT_SOCKET(19) + +/* XXX: TBD: priorities, socket names, ipv4only */ + +/* + * Statistics. These are for informational purposes only, and subject + * to change without notice. The API for accessing these is stable, + * but the individual statistic names, values, and meanings are all + * subject to change. + */ + +/* + * nng_snapshot_create creates a statistics snapshot. The snapshot + * object must be deallocated expressly by the user, and may persist beyond + * the lifetime of any socket object used to update it. Note that the + * values of the statistics are initially unset. + */ +NNG_DECL int nng_snapshot_create(nng_snapshot_t *); + +/* + * nng_snapshot_free frees a snapshot object. All statistic objects + * contained therein are destroyed as well. + */ +NNG_DECL void nng_snapshot_free(nng_snapshot_t); + +/* + * nng_snapshot_update updates a snapshot of all the statistics + * relevant to a particular socket. All prior values are overwritten. + * It is acceptable to use the same snapshot object with different + * sockets. + */ +NNG_DECL int nng_snapshot_update(nng_socket_t, nng_snapshot_t); + +/* + * nng_snapshot_iterate is used to iterate over the individual statistic + * objects inside the snapshot. Note that the statistic object, and the + * meta-data for the object (name, type, units) is fixed, and does not + * change for the entire life of the snapshot. Only the value + * is subject to change, and then only when a snapshot is updated. + * + * Iteration begins by providing NULL in the value referenced. Successive + * calls will update this value, returning NULL when no more statistics + * are available in the snapshot. + */ +NNG_DECL nng_stat_t nng_snapshot_iterate(nng_snapshot_t, nng_stat_t); + +/* + * nng_stat_name is used to determine the name of the statistic. + * This is a human readable name. Statistic names, as well as the presence + * or absence or semantic of any particular statistic are not part of any + * stable API, and may be changed without notice in future updates. + */ +NNG_DECL const char *nng_stat_name(nng_stat_t); + +/* + * nng_stat_type is used to determine the type of the statistic. + * At present, only NNG_STAT_TYPE_LEVEL and and NNG_STAT_TYPE_COUNTER + * are defined. Counters generally increment, and therefore changes in the + * value over time are likely more interesting than the actual level. Level + * values reflect some absolute state however, and should be presented to the + * user as is. + */ +NNG_DECL int nng_stat_type(nng_stat_t); +#define NNG_STAT_LEVEL 0 +#define NNG_STAT_COUNTER 1 + +/* + * nng_stat_unit provides information about the unit for the statistic, + * such as NNG_UNIT_BYTES or NNG_UNIT_BYTES. If no specific unit is + * applicable, such as a relative priority, then NN_UNIT_NONE is + * returned. + */ +NNG_DECL int nng_stat_unit(nng_stat_t); +#define NNG_UNIT_NONE 0 +#define NNG_UNIT_BYTES 1 +#define NNG_UNIT_MESSAGES 2 +#define NNG_UNIT_BOOLEAN 3 +#define NNG_UNIT_MILLIS 4 +#define NNG_UNIT_EVENTS 5 + +/* + * nng_stat_value returns returns the actual value of the statistic. + * Statistic values reflect their value at the time that the corresponding + * snapshot was updated, and are undefined until an update is performed. + */ +NNG_DECL int64_t nng_stat_value(nng_stat_t); + +/* + * Device functionality. This connects two sockets together in a device, + * which means that messages from one side are forwarded to the other. + */ +NNG_DECL int nng_device(nng_socket_t, nng_socket_t); + +/* + * Pollset functionality. TBD. (Note that I'd rather avoid this + * altogether, because I believe that the notification mechanism I've + * created offers a superior way to handle this. I don't think many + * direct consumers of nn_poll existed in the wild, except via nn_device(). + * I suspect that there not even many nn_device() consumers.) + */ + +/* + * Symbol name and visibility. TBD. The only symbols that really should + * be directly exported to runtimes IMO are the option symbols. And frankly + * they have enough special logic around them that it might be best not to + * automate the promotion of them to other APIs. This is an area open + * for discussion. + */ + +/* + * Error codes. These may happen to align to errnos used on your platform, + * but do not count on this. + */ +#define NNG_ENOMEM (-2) +#define NNG_EINVAL (-3) +#define NNG_EBUSY (-4) + +#ifdef __cplusplus +} +#endif + +#endif /* NNG_H */ |