summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/man/libnng.3.adoc527
-rw-r--r--docs/man/nng_sub.7.adoc9
-rw-r--r--docs/man/nng_sub_subscribe.3.adoc67
-rw-r--r--include/nng/protocol/pubsub0/sub.h7
-rw-r--r--src/core/socket.c18
-rw-r--r--src/core/socket.h6
-rw-r--r--src/sp/protocol/pubsub0/sub.c88
-rw-r--r--src/sp/protocol/pubsub0/sub_test.c45
8 files changed, 484 insertions, 283 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index f1e14ac4..35d92a55 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -31,12 +31,12 @@ It provides a C language API.
The following common functions exist in _libnng_.
|===
-|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory
-|xref:nng_free.3.adoc[nng_free()]|free memory
-|xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string
-|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description
-|xref:nng_strfree.3.adoc[nng_strfree()]|free string
-|xref:nng_version.3.adoc[nng_version()]|report library version
+|xref:nng_alloc.3.adoc[nng_alloc]|allocate memory
+|xref:nng_free.3.adoc[nng_free]|free memory
+|xref:nng_strdup.3.adoc[nng_strdup]|duplicate string
+|xref:nng_strerror.3.adoc[nng_strerror]|return an error description
+|xref:nng_strfree.3.adoc[nng_strfree]|free string
+|xref:nng_version.3.adoc[nng_version]|report library version
|===
=== Socket Functions
@@ -44,19 +44,20 @@ The following common functions exist in _libnng_.
The following functions operate on sockets.
|===
-|xref:nng_close.3.adoc[nng_close()]|close socket
-|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer
-|xref:nng_getopt.3.adoc[nng_getopt()]|get socket option
-|xref:nng_listen.3.adoc[nng_listen()]|create and start listener
-|xref:nng_recv.3.adoc[nng_recv()]|receive data
-|xref:nng_send.3.adoc[nng_send()]|send data
-|xref:nng_setopt.3.adoc[nng_setopt()]|set socket option
-|xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option
-|xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier
-|xref:nng_socket_raw.3.adoc[nng_socket_raw()]|is the socket raw
-|xref:nng_socket_proto_id.3.adoc[nng_socket_raw()]|get the socket protocol identifier
-|xref:nng_socket_proto_name.3.adoc[nng_socket_raw()]|get the socket protocol name
-|xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option
+|xref:nng_close.3.adoc[nng_close]|close socket
+|xref:nng_dial.3.adoc[nng_dial]|create and start dialer
+|xref:nng_getopt.3.adoc[nng_getopt]|get socket option
+|xref:nng_listen.3.adoc[nng_listen]|create and start listener
+|xref:nng_recv.3.adoc[nng_recv]|receive data
+|xref:nng_send.3.adoc[nng_send]|send data
+|xref:nng_setopt.3.adoc[nng_setopt]|set socket option (DEPRECATED)
+|xref:nng_socket_get.3.adoc[nng_socket_get]|get socket option
+|xref:nng_socket_id.3.adoc[nng_socket_id]|get numeric socket identifier
+|xref:nng_socket_raw.3.adoc[nng_socket_raw]|is the socket raw
+|xref:nng_socket_proto_id.3.adoc[nng_socket_proto_id]|get the socket protocol identifier
+|xref:nng_socket_proto_name.3.adoc[nng_socket_proto_name]|get the socket protocol name
+|xref:nng_socket_set.3.adoc[nng_socket_set]|set socket option
+|xref:nng_sub_susbcribe.3.adoc[nng_sub_subscribe]|manage subscriptions
|===
=== Connection Management
@@ -65,32 +66,32 @@ The following functions are used with either listeners, or dialers.
Listeners accept incoming connection requests, and dialers make them.
|===
-|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer
-|xref:nng_dialer_close.3.adoc[nng_dialer_close()]|close dialer
-|xref:nng_dialer_create.3.adoc[nng_dialer_create()]|create dialer
-|xref:nng_dialer_get.3.adoc[nng_dialer_get()]|get dialer option
-|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt()]|get dialer option
-|xref:nng_dialer_id.3.adoc[nng_dialer_id()]|get numeric dialer identifier
-|xref:nng_dialer_set.3.adoc[nng_dialer_set()]|set dialer option
-|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt()]|set dialer option
-|xref:nng_dialer_start.3.adoc[nng_dialer_start()]|start dialer
-|xref:nng_listen.3.adoc[nng_listen()]|create and start listener
-|xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener
-|xref:nng_listener_create.3.adoc[nng_listener_create()]|create listener
-|xref:nng_listener_get.3.adoc[nng_listener_get()]|get listener option
-|xref:nng_listener_getopt.3.adoc[nng_listener_getopt()]|get listener option
-|xref:nng_listener_id.3.adoc[nng_listener_id()]|get numeric listener identifier
-|xref:nng_listener_set.3.adoc[nng_listener_set()]|set listener option
-|xref:nng_listener_setopt.3.adoc[nng_listener_setopt()]|set listener option
-|xref:nng_listener_start.3.adoc[nng_listener_start()]|start listener
-|xref:nng_pipe_close.3.adoc[nng_pipe_close()]|close pipe
-|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer()]|return dialer that created pipe
-|xref:nng_pipe_get.3.adoc[nng_pipe_get()]|get pipe option
-|xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt()]|get pipe option
-|xref:nng_pipe_id.3.adoc[nng_pipe_id()]|get numeric pipe identifier
-|xref:nng_pipe_listener.3.adoc[nng_pipe_listener()]|return listener that created pipe
-|xref:nng_pipe_notify.3.adoc[nng_pipe_notify()]|register pipe notification callback
-|xref:nng_pipe_socket.3.adoc[nng_pipe_socket()]|return owning socket for pipe
+|xref:nng_dial.3.adoc[nng_dial]|create and start dialer
+|xref:nng_dialer_close.3.adoc[nng_dialer_close]|close dialer
+|xref:nng_dialer_create.3.adoc[nng_dialer_create]|create dialer
+|xref:nng_dialer_get.3.adoc[nng_dialer_get]|get dialer option
+|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt]|get dialer option (DEPRECATED)
+|xref:nng_dialer_id.3.adoc[nng_dialer_id]|get numeric dialer identifier
+|xref:nng_dialer_set.3.adoc[nng_dialer_set]|set dialer option
+|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt]|set dialer option (DEPRECATED)
+|xref:nng_dialer_start.3.adoc[nng_dialer_start]|start dialer
+|xref:nng_listen.3.adoc[nng_listen]|create and start listener
+|xref:nng_listener_close.3.adoc[nng_listener_close]|close listener
+|xref:nng_listener_create.3.adoc[nng_listener_create]|create listener
+|xref:nng_listener_get.3.adoc[nng_listener_get]|get listener option
+|xref:nng_listener_getopt.3.adoc[nng_listener_getopt]|get listener option (DEPRECATED)
+|xref:nng_listener_id.3.adoc[nng_listener_id]|get numeric listener identifier
+|xref:nng_listener_set.3.adoc[nng_listener_set]|set listener option
+|xref:nng_listener_setopt.3.adoc[nng_listener_setopt]|set listener option (DEPRECATED)
+|xref:nng_listener_start.3.adoc[nng_listener_start]|start listener
+|xref:nng_pipe_close.3.adoc[nng_pipe_close]|close pipe
+|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer]|return dialer that created pipe
+|xref:nng_pipe_get.3.adoc[nng_pipe_get]|get pipe option
+|xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt]|get pipe option (DEPRECATED)
+|xref:nng_pipe_id.3.adoc[nng_pipe_id]|get numeric pipe identifier
+|xref:nng_pipe_listener.3.adoc[nng_pipe_listener]|return listener that created pipe
+|xref:nng_pipe_notify.3.adoc[nng_pipe_notify]|register pipe notification callback
+|xref:nng_pipe_socket.3.adoc[nng_pipe_socket]|return owning socket for pipe
|===
=== Message Handling Functions
@@ -104,23 +105,23 @@ user-payload and the header carries protocol specific header information.
Most applications will only interact with the body.
|===
-|xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message
-|xref:nng_msg_append.3.adoc[nng_msg_append()]|append to message body
-|xref:nng_msg_body.3.adoc[nng_msg_body()]|return message body
-|xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body
-|xref:nng_msg_chop.3.adoc[nng_msg_chop()]|remove data from end of message body
-|xref:nng_msg_clear.3.adoc[nng_msg_clear()]|clear message body
-|xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message
-|xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message
-|xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe()]|get pipe for message
-|xref:nng_msg_insert.3.adoc[nng_msg_insert()]|prepend to message body
-|xref:nng_msg_len.3.adoc[nng_msg_len()]|return the message body length
-|xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message
-|xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body
-|xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe()]|set pipe for message
-|xref:nng_msg_trim.3.adoc[nng_msg_trim()]|remove data from start of message body
-|xref:nng_recvmsg.3.adoc[nng_recvmsg()]|receive a message
-|xref:nng_sendmsg.3.adoc[nng_sendmsg()]|send a message
+|xref:nng_msg_alloc.3.adoc[nng_msg_alloc]|allocate a message
+|xref:nng_msg_append.3.adoc[nng_msg_append]|append to message body
+|xref:nng_msg_body.3.adoc[nng_msg_body]|return message body
+|xref:nng_msg_capacity.3.adoc[nng_msg_capacity]|return capacity allocated for message body
+|xref:nng_msg_chop.3.adoc[nng_msg_chop]|remove data from end of message body
+|xref:nng_msg_clear.3.adoc[nng_msg_clear]|clear message body
+|xref:nng_msg_dup.3.adoc[nng_msg_dup]|duplicate a message
+|xref:nng_msg_free.3.adoc[nng_msg_free]|free a message
+|xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe]|get pipe for message
+|xref:nng_msg_insert.3.adoc[nng_msg_insert]|prepend to message body
+|xref:nng_msg_len.3.adoc[nng_msg_len]|return the message body length
+|xref:nng_msg_realloc.3.adoc[nng_msg_realloc]|reallocate a message
+|xref:nng_msg_reserve.3.adoc[nng_msg_reserve]|reserve storage for message body
+|xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe]|set pipe for message
+|xref:nng_msg_trim.3.adoc[nng_msg_trim]|remove data from start of message body
+|xref:nng_recvmsg.3.adoc[nng_recvmsg]|receive a message
+|xref:nng_sendmsg.3.adoc[nng_sendmsg]|send a message
|===
==== Message Header Handling
@@ -130,19 +131,19 @@ used to carry protocol-specific content. However, applications which use raw
mode may need to access the header of messages.
|===
-|xref:nng_msg_header.3.adoc[nng_msg_header()]|return message header
-|xref:nng_msg_header_append.3.adoc[nng_msg_header_append()]|append to message header
-|xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop()]|remove data from end of message header
-|xref:nng_msg_header_clear.3.adoc[nng_msg_header_clear()]|clear message header
-|xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert()]|prepend to message header
-|xref:nng_msg_header_len.3.adoc[nng_msg_header_len()]|return the message header length
-|xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim()]|remove data from start of message header
+|xref:nng_msg_header.3.adoc[nng_msg_header]|return message header
+|xref:nng_msg_header_append.3.adoc[nng_msg_header_append]|append to message header
+|xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop]|remove data from end of message header
+|xref:nng_msg_header_clear.3.adoc[nng_msg_header_clear]|clear message header
+|xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert]|prepend to message header
+|xref:nng_msg_header_len.3.adoc[nng_msg_header_len]|return the message header length
+|xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim]|remove data from start of message header
|===
=== Asynchronous Operations
Most applications will interact with _NNG_ synchronously; that is that
-functions such as xref:nng_send.3.adoc[`nng_send()`] will block the calling
+functions such as xref:nng_send.3.adoc[`nng_send`] will block the calling
thread until the operation has completed.
NOTE: Synchronous operations which send messages may return before the
@@ -164,30 +165,30 @@ Only a single asynchronous operation may be associated with an
The following functions are used in the asynchronous model:
|===
-|xref:nng_aio_abort.3.adoc[nng_aio_abort()]|abort asynchronous I/O operation
-|xref:nng_aio_alloc.3.adoc[nng_aio_alloc()]|allocate asynchronous I/O handle
-|xref:nng_aio_begin.3.adoc[nng_aio_begin()]|begin asynchronous I/O operation
-|xref:nng_aio_busy.3.adoc[nng_aio_busy()]|test if asynchronous I/O is busy
-|xref:nng_aio_cancel.3.adoc[nng_aio_cancel()]|cancel asynchronous I/O operation
-|xref:nng_aio_count.3.adoc[nng_aio_count()]|return number of bytes transferred
-|xref:nng_aio_defer.3.adoc[nng_aio_defer()]|defer asynchronous I/O operation
-|xref:nng_aio_finish.3.adoc[nng_aio_finish()]|finish asynchronous I/O operation
-|xref:nng_aio_free.3.adoc[nng_aio_free()]|free asynchronous I/O handle
-|xref:nng_aio_get_input.3.adoc[nng_aio_get_input()]|return input parameter
-|xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg()]|get message from an asynchronous receive
-|xref:nng_aio_get_output.3.adoc[nng_aio_get_output()]|return output result
-|xref:nng_aio_free.3.adoc[nng_aio_reap()]|reap asynchronous I/O handle
-|xref:nng_aio_result.3.adoc[nng_aio_result()]|return result of asynchronous operation
-|xref:nng_aio_set_input.3.adoc[nng_aio_set_input()]|set input parameter
-|xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov()]|set scatter/gather vector
-|xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg()]|set message for an asynchronous send
-|xref:nng_aio_set_output.3.adoc[nng_aio_set_output()]|set output result
-|xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout()]|set asynchronous I/O timeout
-|xref:nng_aio_stop.3.adoc[nng_aio_stop()]|stop asynchronous I/O operation
-|xref:nng_aio_wait.3.adoc[nng_aio_wait()]|wait for asynchronous I/O operation
-|xref:nng_recv_aio.3.adoc[nng_recv_aio()]|receive message asynchronously
-|xref:nng_send_aio.3.adoc[nng_send_aio()]|send message asynchronously
-|xref:nng_sleep_aio.3.adoc[nng_sleep_aio()]|sleep asynchronously
+|xref:nng_aio_abort.3.adoc[nng_aio_abort]|abort asynchronous I/O operation
+|xref:nng_aio_alloc.3.adoc[nng_aio_alloc]|allocate asynchronous I/O handle
+|xref:nng_aio_begin.3.adoc[nng_aio_begin]|begin asynchronous I/O operation
+|xref:nng_aio_busy.3.adoc[nng_aio_busy]|test if asynchronous I/O is busy
+|xref:nng_aio_cancel.3.adoc[nng_aio_cancel]|cancel asynchronous I/O operation
+|xref:nng_aio_count.3.adoc[nng_aio_count]|return number of bytes transferred
+|xref:nng_aio_defer.3.adoc[nng_aio_defer]|defer asynchronous I/O operation
+|xref:nng_aio_finish.3.adoc[nng_aio_finish]|finish asynchronous I/O operation
+|xref:nng_aio_free.3.adoc[nng_aio_free]|free asynchronous I/O handle
+|xref:nng_aio_get_input.3.adoc[nng_aio_get_input]|return input parameter
+|xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg]|get message from an asynchronous receive
+|xref:nng_aio_get_output.3.adoc[nng_aio_get_output]|return output result
+|xref:nng_aio_free.3.adoc[nng_aio_reap]|reap asynchronous I/O handle
+|xref:nng_aio_result.3.adoc[nng_aio_result]|return result of asynchronous operation
+|xref:nng_aio_set_input.3.adoc[nng_aio_set_input]|set input parameter
+|xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov]|set scatter/gather vector
+|xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg]|set message for an asynchronous send
+|xref:nng_aio_set_output.3.adoc[nng_aio_set_output]|set output result
+|xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout]|set asynchronous I/O timeout
+|xref:nng_aio_stop.3.adoc[nng_aio_stop]|stop asynchronous I/O operation
+|xref:nng_aio_wait.3.adoc[nng_aio_wait]|wait for asynchronous I/O operation
+|xref:nng_recv_aio.3.adoc[nng_recv_aio]|receive message asynchronously
+|xref:nng_send_aio.3.adoc[nng_send_aio]|send message asynchronously
+|xref:nng_sleep_aio.3.adoc[nng_sleep_aio]|sleep asynchronously
|===
=== Protocols
@@ -195,30 +196,32 @@ The following functions are used in the asynchronous model:
The following functions are used to construct a socket with a specific protocol:
|===
-|xref:nng_bus_open.3.adoc[nng_bus_open()]|open a bus socket
-|xref:nng_pair_open.3.adoc[nng_pair_open()]|open a pair socket
-|xref:nng_pub_open.3.adoc[nng_pub_open()]|open a pub socket
-|xref:nng_pull_open.3.adoc[nng_pull_open()]|open a pull socket
-|xref:nng_push_open.3.adoc[nng_push_open()]|open a push socket
-|xref:nng_rep_open.3.adoc[nng_rep_open()]|open a rep socket
-|xref:nng_req_open.3.adoc[nng_req_open()]|open a req socket
-|xref:nng_respondent_open.3.adoc[nng_respondent_open()]|open a respondent socket
-|xref:nng_sub_open.3.adoc[nng_sub_open()]|open a sub socket
-|xref:nng_surveyor_open.3.adoc[nng_surveyor_open()]|open a surveyor socket
+|xref:nng_bus_open.3.adoc[nng_bus_open]|open a bus socket
+|xref:nng_pair_open.3.adoc[nng_pair_open]|open a pair socket
+|xref:nng_pub_open.3.adoc[nng_pub_open]|open a pub socket
+|xref:nng_pull_open.3.adoc[nng_pull_open]|open a pull socket
+|xref:nng_push_open.3.adoc[nng_push_open]|open a push socket
+|xref:nng_rep_open.3.adoc[nng_rep_open]|open a rep socket
+|xref:nng_req_open.3.adoc[nng_req_open]|open a req socket
+|xref:nng_respondent_open.3.adoc[nng_respondent_open]|open a respondent socket
+|xref:nng_sub_open.3.adoc[nng_sub_open]|open a sub socket
+|xref:nng_surveyor_open.3.adoc[nng_surveyor_open]|open a surveyor socket
|===
=== Transports
The following functions are used to register a transport for use.
+This is no longer necessary, and applications should not call these
+functions anymore.
|===
-| xref:nng_inproc_register.3.adoc[nng_inproc_register()]|register inproc transport
-| xref:nng_ipc_register.3.adoc[nng_ipc_register()]|register IPC transport
-| xref:nng_tcp_register.3.adoc[nng_tcp_register()]|register TCP transport
-| xref:nng_tls_register.3.adoc[nng_tls_register()]|register TLS transport
-| xref:nng_ws_register.3.adoc[nng_ws_register()]|register WebSocket transport
-| xref:nng_wss_register.3.adoc[nng_wss_register()]|register WebSocket Secure transport
-| xref:nng_zt_register.3.adoc[nng_zt_register()]|register ZeroTier transport
+| xref:nng_inproc_register.3.adoc[nng_inproc_register]|register inproc transport (DEPRECATED)
+| xref:nng_ipc_register.3.adoc[nng_ipc_register]|register IPC transport (DEPRECATED)
+| xref:nng_tcp_register.3.adoc[nng_tcp_register]|register TCP transport (DEPRECATED)
+| xref:nng_tls_register.3.adoc[nng_tls_register]|register TLS transport (DEPRECATED)
+| xref:nng_ws_register.3.adoc[nng_ws_register]|register WebSocket transport (DEPRECATED)
+| xref:nng_wss_register.3.adoc[nng_wss_register]|register WebSocket Secure transport (DEPRECATED)
+| xref:nng_zt_register.3.adoc[nng_zt_register]|register ZeroTier transport (DEPRECATED)
|===
=== Protocol Contexts
@@ -229,17 +232,17 @@ This can allow multiple contexts to be created on a single socket for
concurrent applications.
|===
-|xref:nng_ctx_close.3.adoc[nng_ctx_close()]|close context
-|xref:nng_ctx_get.3.adoc[nng_ctx_get()]|get context option
-|xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt()]|get context option
-|xref:nng_ctx_id.3.adoc[nng_ctx_id()]|get numeric context identifier
-|xref:nng_ctx_open.3.adoc[nng_ctx_open()]|create context
-|xref:nng_ctx_recv.3.adoc[nng_ctx_recv()]|receive message using context asynchronously
-|xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg()]|receive a message using context
-|xref:nng_ctx_send.3.adoc[nng_ctx_send()]|send message using context asynchronously
-|xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg()]|send a message using context
-|xref:nng_ctx_set.3.adoc[nng_ctx_set()]|set context option
-|xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt()]|set context option
+|xref:nng_ctx_close.3.adoc[nng_ctx_close]|close context
+|xref:nng_ctx_get.3.adoc[nng_ctx_get]|get context option
+|xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt]|get context option (DEPRECATED)
+|xref:nng_ctx_id.3.adoc[nng_ctx_id]|get numeric context identifier
+|xref:nng_ctx_open.3.adoc[nng_ctx_open]|create context
+|xref:nng_ctx_recv.3.adoc[nng_ctx_recv]|receive message using context asynchronously
+|xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg]|receive a message using context
+|xref:nng_ctx_send.3.adoc[nng_ctx_send]|send message using context asynchronously
+|xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg]|send a message using context
+|xref:nng_ctx_set.3.adoc[nng_ctx_set]|set context option
+|xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt]|set context option (DEPRECATED)
|===
=== Devices, Relays
@@ -248,7 +251,7 @@ The following function family is used to create forwarders or relayers
that route messages from one socket to another.
|===
-|xref:nng_device.3.adoc[nng_device()]|message forwarding device
+|xref:nng_device.3.adoc[nng_device]|message forwarding device
|===
=== Statistics
@@ -257,22 +260,22 @@ The following functions provide access to statistics which can be used
to observe program behaviors and as an aid in troubleshooting.
|===
-|xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value
-|xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic
-|xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description
-|xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name
-|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics
-|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics
-|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics
-|xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name
-|xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic
-|xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value
-|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp
-|xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type
-|xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit
-|xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value
-|xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics
-|xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics
+|xref:nng_stat_bool.3.adoc[nng_stat_bool]|get statistic Boolean value
+|xref:nng_stat_child.3.adoc[nng_stat_child]|get child statistic
+|xref:nng_stat_desc.3.adoc[nng_stat_name]|get statistic description
+|xref:nng_stat_find.3.adoc[nng_stat_find]|find statistic by name
+|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer]|find dialer statistics
+|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener]|find listener statistics
+|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket]|find socket statistics
+|xref:nng_stat_name.3.adoc[nng_stat_name]|get statistic name
+|xref:nng_stat_next.3.adoc[nng_stat_next]|get next statistic
+|xref:nng_stat_string.3.adoc[nng_stat_string]|get statistic string value
+|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp]|get statistic timestamp
+|xref:nng_stat_type.3.adoc[nng_stat_type]|get statistic type
+|xref:nng_stat_unit.3.adoc[nng_stat_unit]|get statistic unit
+|xref:nng_stat_value.3.adoc[nng_stat_value]|get statistic numeric value
+|xref:nng_stats_free.3.adoc[nng_stats_free]|free statistics
+|xref:nng_stats_get.3.adoc[nng_stats_get]|get statistics
|===
=== URL Object
@@ -281,9 +284,9 @@ Common functionality is supplied for parsing and handling
universal resource locators (URLS).
|===
-|xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure
-|xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure
-|xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string
+|xref:nng_url_clone.3.adoc[nng_url_clone]|clone URL structure
+|xref:nng_url_free.3.adoc[nng_url_free]|free URL structure
+|xref:nng_url_parse.3.adoc[nng_url_parse]|create URL structure from string
|===
=== Logging Support
@@ -291,10 +294,10 @@ universal resource locators (URLS).
Common functionality for message logging.
|===
-|xref:nng_log.3.adoc[nng_log()]|log a message
-|xref:nng_log_facility.3.adoc[nng_log_set_facility()]|set log facility
-|xref:nng_log_level.3.adoc[nng_log_set_level()]|set log level
-|xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler
+|xref:nng_log.3.adoc[nng_log]|log a message
+|xref:nng_log_facility.3.adoc[nng_log_set_facility]|set log facility
+|xref:nng_log_level.3.adoc[nng_log_set_level]|set log level
+|xref:nng_log_logger.3.adoc[nng_log_set_logger]|set logging handler
|===
=== Supplemental API
@@ -304,25 +307,25 @@ network applications with _NNG_, but they are made available
as a convenience to aid in creating portable applications.
|===
-|xref:nng_clock.3supp.adoc[nng_clock()]|get time
-|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable
-|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable
-|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout
-|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition
-|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters
-|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter
+|xref:nng_clock.3supp.adoc[nng_clock]|get time
+|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc]|allocate condition variable
+|xref:nng_cv_free.3supp.adoc[nng_cv_free]|free condition variable
+|xref:nng_cv_until.3supp.adoc[nng_cv_until]|wait for condition or timeout
+|xref:nng_cv_wait.3supp.adoc[nng_cv_wait]|wait for condition
+|xref:nng_cv_wake.3supp.adoc[nng_cv_wake]|wake all waiters
+|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1]|wake one waiter
|xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table
-|xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds
-|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex
-|xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex
-|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex
-|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex
-|xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options
-|xref:nng_random.3supp.adoc[nng_random()]|get random number
-|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets
-|xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread
-|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread
-|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name
+|xref:nng_msleep.3supp.adoc[nng_msleep]|sleep for milliseconds
+|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc]|allocate mutex
+|xref:nng_mtx_free.3supp.adoc[nng_mtx_free]|free mutex
+|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock]|lock mutex
+|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock]|unlock mutex
+|xref:nng_opts_parse.3supp.adoc[nng_opts_parse]|parse command line options
+|xref:nng_random.3supp.adoc[nng_random]|get random number
+|xref:nng_socket_pair.3supp.adoc[nng_socket_pair]|create connected pair of BSD sockets
+|xref:nng_thread_create.3supp.adoc[nng_thread_create]|create thread
+|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy]|reap thread
+|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name]|set thread name
|===
=== Byte Streams
@@ -339,25 +342,25 @@ xref:nng_stream_dialer.5.adoc[`nng_stream_dialer`] or
xref:nng_stream_listener.5.adoc[`nng_stream_listener`] objects.
|===
-|xref:nng_stream_close.3str.adoc[nng_stream_close()]|close byte stream
-|xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc()]|allocate byte stream dialer
-|xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close()]|close byte stream dialer
-|xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial()]|initiate outgoing byte stream
-|xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free()]|free byte stream dialer
-|xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get()]|get option from byte stream dialer
-|xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set()]|set option on byte stream dialer
-|xref:nng_stream_free.3str.adoc[nng_stream_free()]|free byte stream
-|xref:nng_stream_get.3str.adoc[nng_stream_get()]|get option from byte stream
-|xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept()]|accept incoming byte stream
-|xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc()]|allocate byte stream listener
-|xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close()]|close byte stream listener
-|xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free()]|free byte stream listener
-|xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get()]|get option from byte stream listener
-|xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen()]|bind byte stream listener to address
-|xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set()]|set option on byte stream listener
-|xref:nng_stream_recv.3str.adoc[nng_stream_recv()]|receive from byte stream
-|xref:nng_stream_send.3str.adoc[nng_stream_send()]|send to byte stream
-|xref:nng_stream_set.3str.adoc[nng_stream_set()]|set option on byte stream
+|xref:nng_stream_close.3str.adoc[nng_stream_close]|close byte stream
+|xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc]|allocate byte stream dialer
+|xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close]|close byte stream dialer
+|xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial]|initiate outgoing byte stream
+|xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free]|free byte stream dialer
+|xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get]|get option from byte stream dialer
+|xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set]|set option on byte stream dialer
+|xref:nng_stream_free.3str.adoc[nng_stream_free]|free byte stream
+|xref:nng_stream_get.3str.adoc[nng_stream_get]|get option from byte stream
+|xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept]|accept incoming byte stream
+|xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc]|allocate byte stream listener
+|xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close]|close byte stream listener
+|xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free]|free byte stream listener
+|xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get]|get option from byte stream listener
+|xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen]|bind byte stream listener to address
+|xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set]|set option on byte stream listener
+|xref:nng_stream_recv.3str.adoc[nng_stream_recv]|receive from byte stream
+|xref:nng_stream_send.3str.adoc[nng_stream_send]|send to byte stream
+|xref:nng_stream_set.3str.adoc[nng_stream_set]|set option on byte stream
|===
=== HTTP Support
@@ -373,48 +376,48 @@ The following functions are used to work with HTTP requests, responses,
and connections.
|===
-|xref:nng_http_conn_close.3http.adoc[nng_http_conn_close()]|close HTTP connection
-|xref:nng_http_conn_read.3http.adoc[nng_http_conn_read()]|read from HTTP connection
-|xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all()]|read all from HTTP connection
-|xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req()]|read HTTP request
-|xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res()]|read HTTP response
-|xref:nng_http_conn_write.3http.adoc[nng_http_conn_write()]|write to HTTP connection
-|xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all()]|write all to HTTP connection
-|xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req()]|write HTTP request
-|xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res()]|write HTTP response
-|xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header()]|add HTTP request header
-|xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc()]|allocate HTTP request structure
-|xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data()]|copy HTTP request body
-|xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header()]|delete HTTP request header
-|xref:nng_http_req_free.3http.adoc[nng_http_req_free()]|free HTTP request structure
-|xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data()]|get HTTP request body
-|xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header()]|return HTTP request header
-|xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method()]|return HTTP request method
-|xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri()]|return HTTP request URI
-|xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version()]|return HTTP request protocol version
-|xref:nng_http_req_reset.3http.adoc[nng_http_req_reset()]|reset HTTP request structure
-|xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data()]|set HTTP request body
-|xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header()]|set HTTP request header
-|xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method()]|set HTTP request method
-|xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri()]|set HTTP request URI
-|xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version()]|set HTTP request protocol version
-|xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header()]|add HTTP response header
-|xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc()]|allocate HTTP response structure
-|xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error()]|allocate HTTP error response
-|xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data()]|copy HTTP response body
-|xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header()]|delete HTTP response header
-|xref:nng_http_res_free.3http.adoc[nng_http_res_free()]|free HTTP response structure
-|xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data()]|get HTTP response body
-|xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header()]|return HTTP response header
-|xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason()]|return HTTP response reason
-|xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status()]|return HTTP response status
-|xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version()]|return HTTP response protocol version
-|xref:nng_http_res_reset.3http.adoc[nng_http_res_reset()]|reset HTTP response structure
-|xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data()]|set HTTP response body
-|xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header()]|set HTTP response header
-|xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason()]|set HTTP response reason
-|xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status()]|set HTTP response status
-|xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version()]|set HTTP response protocol version
+|xref:nng_http_conn_close.3http.adoc[nng_http_conn_close]|close HTTP connection
+|xref:nng_http_conn_read.3http.adoc[nng_http_conn_read]|read from HTTP connection
+|xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all]|read all from HTTP connection
+|xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req]|read HTTP request
+|xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res]|read HTTP response
+|xref:nng_http_conn_write.3http.adoc[nng_http_conn_write]|write to HTTP connection
+|xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all]|write all to HTTP connection
+|xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req]|write HTTP request
+|xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res]|write HTTP response
+|xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header]|add HTTP request header
+|xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc]|allocate HTTP request structure
+|xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data]|copy HTTP request body
+|xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header]|delete HTTP request header
+|xref:nng_http_req_free.3http.adoc[nng_http_req_free]|free HTTP request structure
+|xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data]|get HTTP request body
+|xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header]|return HTTP request header
+|xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method]|return HTTP request method
+|xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri]|return HTTP request URI
+|xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version]|return HTTP request protocol version
+|xref:nng_http_req_reset.3http.adoc[nng_http_req_reset]|reset HTTP request structure
+|xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data]|set HTTP request body
+|xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header]|set HTTP request header
+|xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method]|set HTTP request method
+|xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri]|set HTTP request URI
+|xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version]|set HTTP request protocol version
+|xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header]|add HTTP response header
+|xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc]|allocate HTTP response structure
+|xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error]|allocate HTTP error response
+|xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data]|copy HTTP response body
+|xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header]|delete HTTP response header
+|xref:nng_http_res_free.3http.adoc[nng_http_res_free]|free HTTP response structure
+|xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data]|get HTTP response body
+|xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header]|return HTTP response header
+|xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason]|return HTTP response reason
+|xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status]|return HTTP response status
+|xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version]|return HTTP response protocol version
+|xref:nng_http_res_reset.3http.adoc[nng_http_res_reset]|reset HTTP response structure
+|xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data]|set HTTP response body
+|xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header]|set HTTP response header
+|xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason]|set HTTP response reason
+|xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status]|set HTTP response status
+|xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version]|set HTTP response protocol version
|===
==== HTTP Client Functions
@@ -422,13 +425,13 @@ and connections.
These functions are intended for use with HTTP client applications.
|===
-|xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc()]|allocate HTTP client
-|xref:nng_http_client_connect.3http.adoc[nng_http_client_connect()]|establish HTTP client connection
-|xref:nng_http_client_free.3http.adoc[nng_http_client_free()]|free HTTP client
-|xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls()]|get HTTP client TLS configuration
-|xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls()]|set HTTP client TLS configuration
-|xref:nng_http_client_transact.3http.adoc[nng_http_client_transact()]|perform one HTTP transaction
-|xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact()]|perform one HTTP transaction on connection
+|xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc]|allocate HTTP client
+|xref:nng_http_client_connect.3http.adoc[nng_http_client_connect]|establish HTTP client connection
+|xref:nng_http_client_free.3http.adoc[nng_http_client_free]|free HTTP client
+|xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls]|get HTTP client TLS configuration
+|xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls]|set HTTP client TLS configuration
+|xref:nng_http_client_transact.3http.adoc[nng_http_client_transact]|perform one HTTP transaction
+|xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact]|perform one HTTP transaction on connection
|===
==== HTTP Server Functions
@@ -436,27 +439,27 @@ These functions are intended for use with HTTP client applications.
These functions are intended for use with HTTP server applications.
|===
-|xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc()]|allocate HTTP server handler
-|xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body()]|set HTTP handler to collect request body
-|xref:nng_http_handler_free.3http.adoc[nng_http_handler_free()]|free HTTP server handler
-|xref:nng_http_handler_get_data.3http.adoc[nng_http_handler_get_data()]|return extra data for HTTP handler
-|xref:nng_http_handler_set_data.3http.adoc[nng_http_handler_set_data()]|set extra data for HTTP handler
-|xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host()]|set host for HTTP handler
-|xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method()]|set HTTP handler method
-|xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree()]|set HTTP handler to match trees
-|xref:nng_http_hijack.3http.adoc[nng_http_hijack()]|hijack HTTP server connection
-|xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler()]|add HTTP server handler
-|xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler()]|delete HTTP server handler
-|xref:nng_http_server_get_addr.3http.adoc[nng_http_server_get_addr()]|get HTTP server address
-|xref:nng_http_server_get_tls.3http.adoc[nng_http_server_get_tls()]|get HTTP server TLS configuration
-|xref:nng_http_server_hold.3http.adoc[nng_http_server_hold()]|get and hold HTTP server instance
-|xref:nng_http_server_release.3http.adoc[nng_http_server_release()]|release HTTP server instance
-|xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file()]|set custom HTTP error file
-|xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page()]|set custom HTTP error page
-|xref:nng_http_server_set_tls.3http.adoc[nng_http_server_set_tls()]|set HTTP server TLS configuration
-|xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error()]|use HTTP server error page
-|xref:nng_http_server_start.3http.adoc[nng_http_server_start()]|start HTTP server
-|xref:nng_http_server_stop.3http.adoc[nng_http_server_stop()]|stop HTTP server
+|xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc]|allocate HTTP server handler
+|xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body]|set HTTP handler to collect request body
+|xref:nng_http_handler_free.3http.adoc[nng_http_handler_free]|free HTTP server handler
+|xref:nng_http_handler_get_data.3http.adoc[nng_http_handler_get_data]|return extra data for HTTP handler
+|xref:nng_http_handler_set_data.3http.adoc[nng_http_handler_set_data]|set extra data for HTTP handler
+|xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host]|set host for HTTP handler
+|xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method]|set HTTP handler method
+|xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree]|set HTTP handler to match trees
+|xref:nng_http_hijack.3http.adoc[nng_http_hijack]|hijack HTTP server connection
+|xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler]|add HTTP server handler
+|xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler]|delete HTTP server handler
+|xref:nng_http_server_get_addr.3http.adoc[nng_http_server_get_addr]|get HTTP server address
+|xref:nng_http_server_get_tls.3http.adoc[nng_http_server_get_tls]|get HTTP server TLS configuration
+|xref:nng_http_server_hold.3http.adoc[nng_http_server_hold]|get and hold HTTP server instance
+|xref:nng_http_server_release.3http.adoc[nng_http_server_release]|release HTTP server instance
+|xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file]|set custom HTTP error file
+|xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page]|set custom HTTP error page
+|xref:nng_http_server_set_tls.3http.adoc[nng_http_server_set_tls]|set HTTP server TLS configuration
+|xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error]|use HTTP server error page
+|xref:nng_http_server_start.3http.adoc[nng_http_server_start]|start HTTP server
+|xref:nng_http_server_stop.3http.adoc[nng_http_server_stop]|stop HTTP server
|===
=== TLS Configuration Objects
@@ -469,15 +472,15 @@ NOTE: These functions will only be present if the library has been built
with TLS support.
|===
-|xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc()]|allocate TLS configuration
-|xref:nng_tls_config_auth_mode.3tls.adoc[nng_tls_config_auth_mode()]|set authentication mode
-|xref:nng_tls_config_ca_chain.3tls.adoc[nng_tls_config_ca_chain()]|set certificate authority chain
-|xref:nng_tls_config_ca_file.3tls.adoc[nng_tls_config_ca_file()]|load certificate authority from file
-|xref:nng_tls_config_cert_key_file.3tls.adoc[nng_tls_config_cert_key_file()]|load own certificate and key from file
-|xref:nng_tls_config_psk.3tls.adoc[nng_tls_config_psk()]|set pre-shared key and identity
-|xref:nng_tls_config_own_cert.3tls.adoc[nng_tls_config_own_cert()]|set own certificate and key
-|xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free()]|free TLS configuration
-|xref:nng_tls_config_server_name.3tls.adoc[nng_tls_config_server_name()]|set remote server name
+|xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc]|allocate TLS configuration
+|xref:nng_tls_config_auth_mode.3tls.adoc[nng_tls_config_auth_mode]|set authentication mode
+|xref:nng_tls_config_ca_chain.3tls.adoc[nng_tls_config_ca_chain]|set certificate authority chain
+|xref:nng_tls_config_ca_file.3tls.adoc[nng_tls_config_ca_file]|load certificate authority from file
+|xref:nng_tls_config_cert_key_file.3tls.adoc[nng_tls_config_cert_key_file]|load own certificate and key from file
+|xref:nng_tls_config_psk.3tls.adoc[nng_tls_config_psk]|set pre-shared key and identity
+|xref:nng_tls_config_own_cert.3tls.adoc[nng_tls_config_own_cert]|set own certificate and key
+|xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free]|free TLS configuration
+|xref:nng_tls_config_server_name.3tls.adoc[nng_tls_config_server_name]|set remote server name
|===
diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc
index a96c1217..95d7066e 100644
--- a/docs/man/nng_sub.7.adoc
+++ b/docs/man/nng_sub.7.adoc
@@ -65,6 +65,10 @@ The following protocol-specific options are available.
message is accepted. If no topic matches, then the message is
discarded.
+
+NOTE: This option is deprecated. New applications should use
+xref:nng_sub_subscribe.3.adoc[`nng_sub0_socket_subscribe`] or `nng_sub0_ctx_subscribe`
+functions.
++
NOTE: This option is a byte array. Thus if you use
xref:nng_setopt.3.adoc[`nng_setopt_string()`] the `NUL` terminator byte will
be included in the topic.
@@ -79,6 +83,10 @@ TIP: To receive all messages, an empty topic (zero length) can be used.
This option, also write-only, removes a topic from the subscription list.
Note that if the topic was not previously subscribed to with
`NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result.
+ +
+ NOTE: This option is deprecated. New applications should use
+ xref:nng_sub_subscribe.3.adoc[`nng_sub0_socket_unsubscribe`] or `nng_sub0_ctx_unsubscribe`
+ functions.
((`NNG_OPT_SUB_PREFNEW`))::
@@ -95,5 +103,6 @@ The _sub_ protocol has no protocol-specific headers.
[.text-left]
xref:nng_sub_open.3.adoc[nng_sub_open(3)],
+xref:nng_sub_subscribe.3.adoc[nng_sub_subscribe(3)],
xref:nng_pub.7.adoc[nng_pub(7)],
xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_sub_subscribe.3.adoc b/docs/man/nng_sub_subscribe.3.adoc
new file mode 100644
index 00000000..3b4d0edc
--- /dev/null
+++ b/docs/man/nng_sub_subscribe.3.adoc
@@ -0,0 +1,67 @@
+= nng_sub_subscribe(3)
+//
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt). A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_sub_subscribe - manage SUB subscriptions
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+#include <nng/protocol/pubsub0/sub.h>
+
+int nng_sub0_socket_subscribe(nng_socket s, const void *buf, size_t sz);
+
+int nng_sub0_socket_unsubscribe(nng_socket s, const void *buf, size_t sz);
+
+int nng_sub0_ctx_subscribe(nng_ctx c, const void *buf, size_t sz);
+
+int nng_sub0_ctx_unsubscribe(nng_ctx c, const void *buf, size_t sz);
+----
+
+== DESCRIPTION
+
+These functions are used to subscribe, or unsubscribe, message topics
+on either the xref:nng_sub.7.adoc[_sub_] version 0 socket _s_,
+or the _sub_ version 0 context _c_.
+
+Message topics are used to filter messages. The first _sz_ bytes of an
+incoming message is compared against _buf_, and if equal the message
+is accepted and will be available for receiving.
+
+Multiple topics may be registered for the same socket or context, and
+incoming messages will be forwarded to the application if any of the topics match.
+
+TIP: To disable filtering altogether, the _buf_ may be `NULL` if _sz_ is zero.
+In this case, all messages will be forwarded to the application.
+
+TIP: These functions should be used instead of the `NNG_OPT_SUB_SUBSCRIBE` and
+`NNG_OPT_SUB_UNSUBSCRIBE` options.
+
+== RETURN VALUES
+
+These functions return 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_ENOTSUP`:: The protocol is not supported.
+`NNG_ENOENT`:: The topic is not subscribed.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng_pub.7.adoc[nng_pub(7)],
+xref:nng_sub.7.adoc[nng_sub(7)],
+xref:nng.7.adoc[nng(7)]
diff --git a/include/nng/protocol/pubsub0/sub.h b/include/nng/protocol/pubsub0/sub.h
index 81f50a80..7ff63f74 100644
--- a/include/nng/protocol/pubsub0/sub.h
+++ b/include/nng/protocol/pubsub0/sub.h
@@ -19,6 +19,13 @@ NNG_DECL int nng_sub0_open(nng_socket *);
NNG_DECL int nng_sub0_open_raw(nng_socket *);
+NNG_DECL int nng_sub0_socket_subscribe(
+ nng_socket id, const void *buf, size_t sz);
+NNG_DECL int nng_sub0_socket_unsubscribe(
+ nng_socket id, const void *buf, size_t sz);
+NNG_DECL int nng_sub0_ctx_subscribe(nng_ctx id, const void *buf, size_t sz);
+NNG_DECL int nng_sub0_ctx_unsubscribe(nng_ctx id, const void *buf, size_t sz);
+
#ifndef nng_sub_open
#define nng_sub_open nng_sub0_open
#endif
diff --git a/src/core/socket.c b/src/core/socket.c
index bf550a24..241b0401 100644
--- a/src/core/socket.c
+++ b/src/core/socket.c
@@ -889,12 +889,30 @@ nni_sock_proto_pipe_ops(nni_sock *sock)
return (&sock->s_pipe_ops);
}
+struct nni_proto_sock_ops *
+nni_sock_proto_ops(nni_sock *sock)
+{
+ return (&sock->s_sock_ops);
+}
+
+struct nni_proto_ctx_ops *
+nni_ctx_proto_ops(nni_ctx *ctx)
+{
+ return (&ctx->c_ops);
+}
+
void *
nni_sock_proto_data(nni_sock *sock)
{
return (sock->s_data);
}
+void *
+nni_ctx_proto_data(nni_ctx *ctx)
+{
+ return (ctx->c_data);
+}
+
int
nni_sock_add_listener(nni_sock *s, nni_listener *l)
{
diff --git a/src/core/socket.h b/src/core/socket.h
index 343310ca..d4bf1a97 100644
--- a/src/core/socket.h
+++ b/src/core/socket.h
@@ -1,5 +1,5 @@
//
-// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This software is supplied under the terms of the MIT License, a
@@ -26,7 +26,9 @@ extern bool nni_sock_raw(nni_sock *);
extern void *nni_sock_proto_data(nni_sock *);
extern void nni_sock_add_stat(nni_sock *, nni_stat_item *);
+extern struct nni_proto_sock_ops *nni_sock_proto_ops(nni_sock *);
extern struct nni_proto_pipe_ops *nni_sock_proto_pipe_ops(nni_sock *);
+extern struct nni_proto_ctx_ops *nni_ctx_proto_ops(nni_ctx *);
extern int nni_sock_setopt(
nni_sock *, const char *, const void *, size_t, nni_opt_type);
@@ -89,6 +91,8 @@ extern void nni_ctx_close(nni_ctx *);
// nni_ctx_id returns the context ID, which can be used with nni_ctx_find.
extern uint32_t nni_ctx_id(nni_ctx *);
+extern void *nni_ctx_proto_data(nni_ctx *);
+
// nni_ctx_recv receives asynchronously.
extern void nni_ctx_recv(nni_ctx *, nni_aio *);
diff --git a/src/sp/protocol/pubsub0/sub.c b/src/sp/protocol/pubsub0/sub.c
index ee911153..e8db6db9 100644
--- a/src/sp/protocol/pubsub0/sub.c
+++ b/src/sp/protocol/pubsub0/sub.c
@@ -718,6 +718,94 @@ static nni_option sub0_sock_options[] = {
},
};
+int
+nng_sub0_socket_subscribe(nng_socket id, const void *buf, size_t sz)
+{
+ int rv;
+ nni_sock *s;
+ sub0_sock *sock;
+
+ if (((rv = nni_init()) != 0) ||
+ ((rv = nni_sock_find(&s, id.id)) != 0)) {
+ return (rv);
+ }
+ // validate the socket type
+ if (nni_sock_proto_ops(s)->sock_init != sub0_sock_init) {
+ nni_sock_rele(s);
+ return (NNG_ENOTSUP);
+ }
+ sock = nni_sock_proto_data(s);
+ rv = sub0_ctx_subscribe(&sock->master, buf, sz, NNI_TYPE_OPAQUE);
+ nni_sock_rele(s);
+ return (rv);
+}
+
+int
+nng_sub0_socket_unsubscribe(nng_socket id, const void *buf, size_t sz)
+{
+ int rv;
+ nni_sock *s;
+ sub0_sock *sock;
+
+ if (((rv = nni_init()) != 0) ||
+ ((rv = nni_sock_find(&s, id.id)) != 0)) {
+ return (rv);
+ }
+ // validate the socket type
+ if (nni_sock_proto_ops(s)->sock_init != sub0_sock_init) {
+ nni_sock_rele(s);
+ return (NNG_ENOTSUP);
+ }
+ sock = nni_sock_proto_data(s);
+ rv = sub0_ctx_unsubscribe(&sock->master, buf, sz, NNI_TYPE_OPAQUE);
+ nni_sock_rele(s);
+ return (rv);
+}
+
+int
+nng_sub0_ctx_subscribe(nng_ctx id, const void *buf, size_t sz)
+{
+ int rv;
+ nni_ctx *c;
+ sub0_ctx *ctx;
+
+ if (((rv = nni_init()) != 0) ||
+ ((rv = nni_ctx_find(&c, id.id, false)) != 0)) {
+ return (rv);
+ }
+ // validate the socket type
+ if (nni_ctx_proto_ops(c)->ctx_init != sub0_ctx_init) {
+ nni_ctx_rele(c);
+ return (NNG_ENOTSUP);
+ }
+ ctx = nni_ctx_proto_data(c);
+ rv = sub0_ctx_subscribe(ctx, buf, sz, NNI_TYPE_OPAQUE);
+ nni_ctx_rele(c);
+ return (rv);
+}
+
+int
+nng_sub0_ctx_unsubscribe(nng_ctx id, const void *buf, size_t sz)
+{
+ int rv;
+ nni_ctx *c;
+ sub0_ctx *ctx;
+
+ if (((rv = nni_init()) != 0) ||
+ ((rv = nni_ctx_find(&c, id.id, false)) != 0)) {
+ return (rv);
+ }
+ // validate the socket type
+ if (nni_ctx_proto_ops(c)->ctx_init != sub0_ctx_init) {
+ nni_ctx_rele(c);
+ return (NNG_ENOTSUP);
+ }
+ ctx = nni_ctx_proto_data(c);
+ rv = sub0_ctx_unsubscribe(ctx, buf, sz, NNI_TYPE_OPAQUE);
+ nni_ctx_rele(c);
+ return (rv);
+}
+
static nni_proto_sock_ops sub0_sock_ops = {
.sock_size = sizeof(sub0_sock),
.sock_init = sub0_sock_init,
diff --git a/src/sp/protocol/pubsub0/sub_test.c b/src/sp/protocol/pubsub0/sub_test.c
index b830ae80..01995943 100644
--- a/src/sp/protocol/pubsub0/sub_test.c
+++ b/src/sp/protocol/pubsub0/sub_test.c
@@ -14,7 +14,7 @@ test_sub_identity(void)
{
nng_socket s;
int p;
- char * n;
+ char *n;
NUTS_PASS(nng_sub0_open(&s));
NUTS_PASS(nng_socket_get_int(s, NNG_OPT_PROTO, &p));
@@ -45,8 +45,8 @@ test_sub_context_cannot_send(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_msg * m;
- nng_aio * aio;
+ nng_msg *m;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_ctx_open(&ctx, sub));
@@ -121,8 +121,8 @@ test_sub_recv_late(void)
int fd;
nng_socket pub;
nng_socket sub;
- nng_aio * aio;
- nng_msg * msg;
+ nng_aio *aio;
+ nng_msg *msg;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_pub0_open(&pub));
@@ -180,9 +180,9 @@ void
test_sub_validate_peer(void)
{
nng_socket s1, s2;
- nng_stat * stats;
- nng_stat * reject;
- char * addr;
+ nng_stat *stats;
+ nng_stat *reject;
+ char *addr;
NUTS_ADDR(addr, "inproc");
@@ -212,7 +212,7 @@ test_sub_recv_ctx_closed(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_aio * aio;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_ctx_open(&ctx, sub));
NUTS_PASS(nng_aio_alloc(&aio, NULL, NULL));
@@ -229,7 +229,7 @@ test_sub_ctx_recv_aio_stopped(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_aio * aio;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_aio_alloc(&aio, NULL, NULL));
@@ -249,7 +249,7 @@ test_sub_close_context_recv(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_aio * aio;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_ctx_open(&ctx, sub));
@@ -269,7 +269,7 @@ test_sub_ctx_recv_nonblock(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_aio * aio;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_ctx_open(&ctx, sub));
@@ -289,7 +289,7 @@ test_sub_ctx_recv_cancel(void)
{
nng_socket sub;
nng_ctx ctx;
- nng_aio * aio;
+ nng_aio *aio;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_ctx_open(&ctx, sub));
@@ -354,6 +354,9 @@ test_sub_subscribe_option(void)
NUTS_PASS(nng_socket_set_int(sub, opt, 32));
sz = sizeof(v);
NUTS_FAIL(nng_socket_get(sub, opt, &v, &sz), NNG_EWRITEONLY);
+ NUTS_PASS(nng_sub0_socket_subscribe(sub, "abc", 3));
+ NUTS_PASS(nng_sub0_socket_subscribe(sub, "abc", 3));
+ NUTS_PASS(nng_sub0_socket_unsubscribe(sub, "abc", 3));
NUTS_CLOSE(sub);
}
@@ -413,7 +416,7 @@ test_sub_drop_new(void)
{
nng_socket sub;
nng_socket pub;
- nng_msg * msg;
+ nng_msg *msg;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_pub0_open(&pub));
@@ -439,7 +442,7 @@ test_sub_drop_old(void)
{
nng_socket sub;
nng_socket pub;
- nng_msg * msg;
+ nng_msg *msg;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_pub0_open(&pub));
@@ -485,7 +488,7 @@ test_sub_filter(void)
NUTS_PASS(nng_send(pub, "def", 3, 0));
NUTS_PASS(nng_send(pub, "de", 2, 0)); // will not go through
NUTS_PASS(nng_send(pub, "abc123", 6, 0));
- NUTS_PASS(nng_send(pub, "xzy", 3, 0)); // does not match
+ NUTS_PASS(nng_send(pub, "xzy", 3, 0)); // does not match
NUTS_PASS(nng_send(pub, "ghi-drop", 7, 0)); // dropped by unsub
NUTS_PASS(nng_send(pub, "jkl-mno", 6, 0));
@@ -517,9 +520,9 @@ test_sub_multi_context(void)
nng_socket pub;
nng_ctx c1;
nng_ctx c2;
- nng_aio * aio1;
- nng_aio * aio2;
- nng_msg * m;
+ nng_aio *aio1;
+ nng_aio *aio2;
+ nng_msg *m;
NUTS_PASS(nng_sub0_open(&sub));
NUTS_PASS(nng_pub0_open(&pub));
@@ -532,7 +535,9 @@ test_sub_multi_context(void)
NUTS_PASS(nng_ctx_set(c1, NNG_OPT_SUB_SUBSCRIBE, "all", 3));
NUTS_PASS(nng_ctx_set(c2, NNG_OPT_SUB_SUBSCRIBE, "two", 3));
- NUTS_PASS(nng_ctx_set(c2, NNG_OPT_SUB_SUBSCRIBE, "all", 3));
+ NUTS_PASS(nng_sub0_ctx_subscribe(c2, "all", 3));
+ NUTS_PASS(nng_sub0_ctx_subscribe(c2, "junk", 4));
+ NUTS_PASS(nng_sub0_ctx_unsubscribe(c2, "junk", 4));
nng_aio_set_timeout(aio1, 100);
nng_aio_set_timeout(aio2, 100);
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-18 07:12:46 +0000