diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/SUMMARY.md | 2 | ||||
| -rw-r--r-- | docs/ref/api/sock.md | 60 | ||||
| -rw-r--r-- | docs/ref/xref.md | 6 |
3 files changed, 68 insertions, 0 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index ed3e1233..0492f33e 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -8,6 +8,8 @@ - [Messages](./api/msg.md) + - [Sockets](./api/sock.md) + - [Memory](./api/memory.md) - [Time](./api/time.md) diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md new file mode 100644 index 00000000..3851ca5e --- /dev/null +++ b/docs/ref/api/sock.md @@ -0,0 +1,60 @@ +# Sockets + +Sockets {{hi:socket}} in Scalability Protocols provide the handle for communication +between peers. Sockets also encapsulate protocol specific semantics, such as +filtering subscriptions, or automatically retrying requests. + +## Socket Structure + +```c +#define NNG_SOCKET_INITIALIZER // opaque value + +typedef struct nng_socket_s nng_socket; +``` + +The {{i:`nng_socket`}} structure represents socket. This is a handle, and +the members of it are opaque. However, unlike a pointer, it is usually +passed by value. + +A socket may be initialized statically with the `NNG_SOCKET_INITIALIZER` macro, +to ensure that it cannot be confused with a valid open socket. + +## Socket Identity + +```c +int nng_socket_id(nng_socket s); +int nng_socket_raw(nng_socket s, bool *raw); +int nng_socket_proto_id(nng_socket s, uint16_t *proto); +int nng_socket_peer_id(nng_socket s, uint16_t *proto); +int nng_socket_proto_name(nng_socket s, const char **name); +int nng_socket_peer_name(nng_socket s, const char **name); +``` + +These functions are used to provide fundamental information about the socket _s_. +Most applications will not need to use these functions. + +The {{i:`nng_socket_id`}} function returns the numeric id, which will be a non-negative +value, associated with the socket. If the socket is uninitialized (has never been opened), +then the return value may be `-1`. + +The {{i:`nng_socket_proto_id`}} and {{i:`nng_socket_peer_id`}} functions provide the 16-bit +protocol identifier for the socket's protocol, and of the protocol peers will use when +communicating with the socket. + +The {{i:`nng_socket_proto_name`}} and {{i:`nng_socket_peer_name`}} functions provide the ASCII +names of the socket's protocol, and of the protocol peers of the socket use. +The value stored in _name_ is a fixed string located in program text, and must not be freed +or altered. It is guaranteed to remain valid while this library is present. + +The {{i:`nng_socket_raw`}} function determines whether the socket is in +[raw mode][raw] or not, storing `true` in _raw_ if it is, or `false` if it is not. + +## Examples + +### Example 1: Initializing a Socket + +```c +nng_socket s = NNG_SOCKET_INITIALIZER; +``` + +{{#include ../xref.md}} diff --git a/docs/ref/xref.md b/docs/ref/xref.md index e52cfc95..0eeb689d 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -66,6 +66,12 @@ [`nng_aio_result`]: /api/aio.md#result-of-operation [`nng_aio_count`]: /api/aio.md#result-of-operation [`nng_aio_set_timeout`]: /api/aio.md#set-timeout +[`nng_socket_id`]: /api/sock.md#socket-identity +[`nng_socket_raw`]: /api/sock.md#socket-identity +[`nng_socket_proto_id`]: /api/sock.md#socket-identity +[`nng_socket_proto_name`]: /api/sock.md#socket-identity +[`nng_socket_peer_id`]: /api/sock.md#socket-identity +[`nng_socket_peer_name`]: /api/sock.md#socket-identity [`nng_opts_parse`]: /api/cmd_opts.md#parse-command-line-options [`nng_aio_begin`]: /TODO.md [`nng_aio_defer`]: /TODO.md |