From 144afd91c2a7a630f074c469b022584290a9e8a8 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 9 Nov 2024 09:25:22 -0800 Subject: [PATCH] Add nng_sub0_subscribe and friends. These are new functions that replace `NNG_OPT_SUBSCRIBE` and `NNG_OPT_UNSUBSCRIBE`. They are provided here as a transition aid before those options are removed in NNG 2.0. --- docs/man/libnng.3.adoc | 527 +++++++++++++++-------------- docs/man/nng_sub.7.adoc | 9 + docs/man/nng_sub_subscribe.3.adoc | 67 ++++ include/nng/protocol/pubsub0/sub.h | 7 + src/core/socket.c | 18 + src/core/socket.h | 6 +- src/sp/protocol/pubsub0/sub.c | 88 +++++ src/sp/protocol/pubsub0/sub_test.c | 45 +-- 8 files changed, 484 insertions(+), 283 deletions(-) create mode 100644 docs/man/nng_sub_subscribe.3.adoc diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index f1e14ac42..35d92a55e 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 a96c12170..95d7066e9 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 000000000..3b4d0edcc --- /dev/null +++ b/docs/man/nng_sub_subscribe.3.adoc @@ -0,0 +1,67 @@ += nng_sub_subscribe(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// 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 +#include + +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 81f50a80f..7ff63f74f 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 fb3227a0d..28d8ca797 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 343310cab..d4bf1a97b 100644 --- a/src/core/socket.h +++ b/src/core/socket.h @@ -1,5 +1,5 @@ // -// Copyright 2021 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // 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 ee9111539..e8db6db95 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 b830ae802..01995943b 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);