From 321a372a0c6d859f47e1099a76b13fee8d9efe88 Mon Sep 17 00:00:00 2001 From: gdamore Date: Wed, 8 Oct 2025 21:54:34 +0000 Subject: deploy: af596b6ccf14b4d2fc2f5c6ef04870186d99d828 --- ref/api/pipe.html | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'ref/api/pipe.html') diff --git a/ref/api/pipe.html b/ref/api/pipe.html index 8167c9f4..5f7f5efd 100644 --- a/ref/api/pipe.html +++ b/ref/api/pipe.html @@ -331,7 +331,10 @@ nng_err nng_pipe_get_int(nng_pipe p, const char *opt, int *valp); nng_err nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *valp); nng_err nng_pipe_get_size(nng_pipe p, const char *opt, size_t *valp); nng_err nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *valp); -nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp); +nng_err nng_pipe_get_string(nng_pipe p, const char *opt, const char **valp); +nng_err nng_pipe_get_strcpy(nng_pipe p, const char *opt, char *val, size_t len); +nng_err nng_pipe_get_strdup(nng_pipe p, const char *opt, char **valp); +nng_err nng_pipe_get_strlen(nng_pipe p, const char *opt, size_t *lenp);

@@ -339,12 +342,21 @@ nng_err nng_pipe_get_string(nng_pipe p, const char *opt, char **valp); + + These functions are used to obtain value of an option named opt from the pipe p, and store it in the location referenced by valp.

These functions access an option as a specific type. The transport layer will have details about which options are available, and which type they may be accessed using.

-

In the case of nng_pipe_get_string, the string is created as if by nng_strdup, and must be freed by -the caller using nng_strfree when no longer needed.

+

In the case of nng_pipe_get_string, the underlying string may only be valid for as long as the pipe is valid. +Thus, this function can only be safely called in a pipe event callback set up with nng_pipe_notify.

+

The nng_pipe_get_strdup function is like nng_pipe_get_string, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using nng_strfree.

+

The nng_pipe_get_strcpy function is also like nng_pipe_get_string, but it makes a copy into a buffer +supplied by the caller. The buffer is passed in val, and the size of the buffer is passed in len. +The value of len must be large enough to hold the string and the terminating zero byte.

+

The nng_pipe_get_strlen function is used to obtain the length of the string. This can be useful +to find the size of the buffer needed by the nng_pipe_get_strcpy function for a property. +Note that like strlen, this size does not account for the zero byte to terminate the string.

Pipe Notifications

typedef enum {
         NNG_PIPE_EV_ADD_PRE,
@@ -356,7 +368,7 @@ typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *);
 
 nng_err nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg);
-

The nng_pipe_notify function registers the callback function cb +

The nng_pipe_notify function registers the callback function cb to be called whenever the pipe event specified by ev occurs on the socket s. The callback cb will be passed arg as its final argument.

@@ -365,9 +377,9 @@ Each event may have at most one callback registered. Registering a callback implicitly unregisters any previously registered.

The following pipe events are supported:

- - - + + +
EventDescription
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.
NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.
NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.

-- cgit v1.2.3-70-g09d2