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/http.html | 5 +++-- ref/api/pipe.html | 26 +++++++++++++++++++------- ref/api/stream.html | 14 +++++++------- 3 files changed, 29 insertions(+), 16 deletions(-) (limited to 'ref/api') diff --git a/ref/api/http.html b/ref/api/http.html index aac5ec43..67c7048e 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -410,7 +410,7 @@ for display to users.

Retrieving Headers

const char *nng_http_get_header(nng_http *conn, const char *key);
-bool nng_next_header(nng_http *conn, const char **keyp, const char **valuep, void **next);
+bool nng_http_next_header(nng_http *conn, const char **keyp, const char **valuep, void **next);

The nng_http_get_header returns the header value matching key that was received over conn, or NULL if no such header exists.

@@ -776,7 +776,8 @@ final argument is the nng_a it may simply let the framework do so on its behalf. The server will perform this step if the callback has not already done so.

Response headers may be set using nng_http_set_header, and request headers -may be accessed by using nng_http_get_header.

+may be accessed by using nng_http_get_header. They can also be iterated +over using nng_http_next_header

Likewise the request body may be accessed, using nng_http_get_body, and the response body may be set using either nng_http_set_body or nng_http_copy_body.

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.

diff --git a/ref/api/stream.html b/ref/api/stream.html index eba3053f..a39434c5 100644 --- a/ref/api/stream.html +++ b/ref/api/stream.html @@ -318,7 +318,7 @@ nng_err nng_stream_get_int(nng_stream *s, const char *opt, int *valp); nng_err nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp); nng_err nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp); nng_err nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp); -nng_err nng_stream_get_string(nng_stream *s, const char *opt, char **valp); +nng_err nng_stream_get_string(nng_stream *s, const char *opt, const char **valp);

@@ -330,8 +330,8 @@ These functions are used to obtain value of an option named opt from th 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_stream_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_stream_get_string, the string pointer is only guaranteed to be valid while the +stream exists. Callers should make a copy of the data if required before closing the stream.

Stream Factories

typedef struct nng_stream_dialer nng_stream_dialer;
 typedef struct nng_stream_listener nng_stream_listener;
@@ -459,14 +459,14 @@ nng_err nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, b
 nng_err nng_stream_dialer_get_int(nng_stream_dialer *dialer, const char *opt, int *valp);
 nng_err nng_stream_dialer_get_ms(nng_stream_dialer *dialer, const char *opt, nng_duration *valp);
 nng_err nng_stream_dialer_get_size(nng_stream_dialer *dialer, const char *opt, size_t *valp);
-nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, char **valp);
+nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, const char **valp);
 
 nng_err nng_stream_listener_get_addr(nng_stream_listener *listener, const char *opt, nng_sockaddr *valp);
 nng_err nng_stream_listener_get_bool(nng_stream_listener *listener, const char *opt, bool *valp);
 nng_err nng_stream_listener_get_int(nng_stream_listener *listener, const char *opt, int *valp);
 nng_err nng_stream_listener_get_ms(nng_stream_listener *listener, const char *opt, nng_duration *valp);
 nng_err nng_stream_listener_get_size(nng_stream_listener *listener, const char *opt, size_t *valp);
-nng_err nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, char **valp);
+nng_err nng_stream_listener_get_string(nng_stream_listener *listener, const char *opt, const char **valp);
 
 nng_err nng_stream_dialer_set_addr(nng_stream_dialer *dialer, const char *opt, const nng_sockaddr *val);
 nng_err nng_stream_dialer_set_bool(nng_stream_dialer *dialer, const char *opt, bool val);
@@ -511,8 +511,8 @@ The nng_stream_dialer_get_ and nng_stream_listener_get_nng_stream_dialer_set_ and nng_stream_listener_set_ function families change the value for the dialer or listener, taking it from val.

 
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_stream_dialer_get_string and nng_stream_listener_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_stream_dialer_get_string and nng_stream_listener_get_string, the memory holding
+the string is only valid as long as the associated object remains open.

 
In the case of nng_stream_dialer_set_string and nng_stream_listener_set_string, the string contents are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.

 
In the case of nng_stream_dialer_set_addr and nng_stream_listener_set_addr, the contents of addr are copied if necessary, so that the caller
-- 
cgit v1.2.3-70-g09d2