diff options
Diffstat (limited to 'docs/reference/src/api/msg')
23 files changed, 0 insertions, 940 deletions
diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md deleted file mode 100644 index 54d8d9b8..00000000 --- a/docs/reference/src/api/msg/index.md +++ /dev/null @@ -1,97 +0,0 @@ -# Messages - -Messages in Scalability Protocols are the fundamental unit of transmission -and reception, -as these protocols are fundamentally message-oriented. - -## {{i: Message object}} - -An `nng_msg` represents a single {{i:message}} sent between Scalability Protocols peers. - -Messages have a {{i:body}}, containing the application supplied -payload, and a {{i:header}}, containing protocol specific routing and similar -related information. - -> [!TIP] -> Only applications using [raw](../../overview/raw.md) mode need to -> access the message header. - -### Creating, Destroying and Using - -Messages are allocated using [`nng_msg_alloc()`](nng_msg_alloc.md), -and are deallocated using [`nng_msg_free()`](nng_msg_free.md). - -In addition there are other functions used to access message contents, -including adding data to either the beginning or end of the message, -automatic data conversion, and removing data from the beginning or end. - -### Performance Considerations - -While there are convenience wrappers for sending and receiving arrays of -bytes, using message objects directly when possible will give better -performance by reducing data copies and needless allocations. - -These functions are designed to try to avoid copying message contents -by making use of scratch areas at the beginning and end of the message. -These scratch areas, the "headroom" and "tailroom", are automatically -included when allocating a message. - -### Direct Use Forbidden - -The `nng_msg` structure is opaque, and applications should never try to -rely on the size of it, nor access internal members directly. -This insulates the application from changes in subsequent _NNG_ versions -that would affect the binary representation of the `nng_msg` itself. - -## Examples - -### Example 1: Preparing a message for use - -```c - #include <nng/nng.h> - - nng_msg *m; - if (nng_msg_alloc(&m, strlen("content") + 1) != 0) { - // handle error - } - strcpy(nng_msg_body(m), "content"); -``` - -### Example 2: Preallocating message content - -```c - if (nng_msg_alloc(&m, 1024) != 0) { - // handle error - } - while ((val64 = next_datum()) != 0) P - if (nng_msg_append_u64(m, val64) != 0) { - // handle error - } - } -``` - -## See Also - -[nng_aio_get_msg](../aio/nng_aio_get_msg.md), -[nng_aio_set_msg](../aio/nng_aio_set_msg.md), -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_dup](nng_msg_dup.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_clear](nng_msg_header_clear.md), -[nng_msg_header_insert](nng_msg_header_insert.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_set_pipe](nng_msg_set_pipe.md), -[nng_msg_trim](nng_msg_trim.md), -[nng_recvmsg](../socket/nng_recvmsg.md), -[nng_sendmsg](../socket/nng_sendmsg.md) diff --git a/docs/reference/src/api/msg/nng_msg_alloc.md b/docs/reference/src/api/msg/nng_msg_alloc.md deleted file mode 100644 index 163d193b..00000000 --- a/docs/reference/src/api/msg/nng_msg_alloc.md +++ /dev/null @@ -1,40 +0,0 @@ -# nng_msg_alloc - -## NAME - -nng_msg_alloc --- allocate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_alloc(nng_msg **msgp, size_t size); -``` - -## DESCRIPTION - -The `nng_msg_alloc()` function allocates a new message with body length _size_ -and stores the result in _msgp_. -Messages allocated with this function contain a body and optionally a header. -They are used with receive and transmit functions. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to allocate a message. - -## SEE ALSO - -[nng_msg_free](nng_msg_free.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_dup](nng_msg_dup.md), -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_append.md b/docs/reference/src/api/msg/nng_msg_append.md deleted file mode 100644 index 5807d3a6..00000000 --- a/docs/reference/src/api/msg/nng_msg_append.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_msg_append - -## NAME - -nng_msg_append --- append to message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_append(nng_msg *msg, const void *val, size_t size); -int nng_msg_append_u16(nng_msg *msg, uint16_t val16); -int nng_msg_append_u32(nng_msg *msg, uint32_t val32); -int nng_msg_append_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_append()` family of functions appends data to -the end of the body of message _msg_, reallocating it if necessary. -The first function appends _size_ bytes, copying them from _val_. -The remaining functions append the value specified (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_body.md b/docs/reference/src/api/msg/nng_msg_body.md deleted file mode 100644 index abd49c7f..00000000 --- a/docs/reference/src/api/msg/nng_msg_body.md +++ /dev/null @@ -1,47 +0,0 @@ -# nng_msg_body - -## NAME - -nng_msg_body --- return message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_body(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_body()` function returns a pointer to the start of the body -content of the message _msg_. - -> [!NOTE] -> The value returned by this is invalidated by a call to any of the -> functions that modify the message itself. -> Such functions are -> [`nng_msg_free()`](nng_msg_free.md), -> [`nng_msg_realloc()`](nng_msg_realloc.md), -> any of the [`nng_msg_trim()`](nng_msg_trim.md), -> [`nng_msg_chop()`](nng_msg_chop.md), -> [`nng_msg_append()`](nng_msg_append.md), -> or [`nng_msg_insert()`](nng_msg_insert.md) variants. - -## RETURN VALUES - -Pointer to start of message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_clear.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_capacity.md b/docs/reference/src/api/msg/nng_msg_capacity.md deleted file mode 100644 index 707a04e3..00000000 --- a/docs/reference/src/api/msg/nng_msg_capacity.md +++ /dev/null @@ -1,30 +0,0 @@ -# nng_msg_capacity - -## NAME - -nng_msg_capacity --- return message body length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_capacity(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_capacity()` returns the storage allocated for the body of message _msg_. -The capacity includes the current contents of the message and free space after it. -The message body may grow to capacity without performing any further allocations. - -## RETURN VALUES - -Allocated capacity for message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_reserve](nng_msg_reserve.md) -[nng_msg_body](nng_msg_body.md) diff --git a/docs/reference/src/api/msg/nng_msg_chop.md b/docs/reference/src/api/msg/nng_msg_chop.md deleted file mode 100644 index fc9a0df5..00000000 --- a/docs/reference/src/api/msg/nng_msg_chop.md +++ /dev/null @@ -1,47 +0,0 @@ -# nng_msg_chop - -## NAME - -nng_msg_chop --- remove data from end of message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_chop(nng_msg *msg, size_t size); -int nng_msg_chop_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_chop_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_chop()` family of functions removes data from -the end of the body of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native byte order. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_clear.md b/docs/reference/src/api/msg/nng_msg_clear.md deleted file mode 100644 index af25c072..00000000 --- a/docs/reference/src/api/msg/nng_msg_clear.md +++ /dev/null @@ -1,23 +0,0 @@ -# nng_msg_clear - -## NAME - -nng_msg_clear --- clear message body content - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_clear(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_clear()` function resets the body length of _msg_ to zero. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_reserve](nng_msg_reserve.md) diff --git a/docs/reference/src/api/msg/nng_msg_dup.md b/docs/reference/src/api/msg/nng_msg_dup.md deleted file mode 100644 index dae376e8..00000000 --- a/docs/reference/src/api/msg/nng_msg_dup.md +++ /dev/null @@ -1,34 +0,0 @@ -# nng_msg_dup - -## NAME - -nng_msg_dup --- duplicate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); -``` - -## DESCRIPTION - -The `nng_msg_dup()` makes a duplicate of the original message _orig_, and -saves the result in the location pointed by _dup_. -The actual message body and header content is copied, -but the duplicate may contain a -different amount of unused space than the original message. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to duplicate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_free](nng_msg_free.md) diff --git a/docs/reference/src/api/msg/nng_msg_free.md b/docs/reference/src/api/msg/nng_msg_free.md deleted file mode 100644 index 94887be0..00000000 --- a/docs/reference/src/api/msg/nng_msg_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_msg_free - -## NAME - -nng_msg_free --- free a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_free(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_free()` function deallocates the message _msg_ entirely. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_get_pipe.md b/docs/reference/src/api/msg/nng_msg_get_pipe.md deleted file mode 100644 index 5f935347..00000000 --- a/docs/reference/src/api/msg/nng_msg_get_pipe.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_msg_get_pipe - -## NAME - -nng_msg_get_pipe --- get pipe for message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -nng_pipe nng_msg_get_pipe(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_get_pipe()` returns the [`nng_pipe`](../conn/nng_pipe.md) object -associated with message _msg_. -On receive, this is the pipe from which a message was received. -On transmit, this would be the pipe that the message should be delivered -to, if a specific peer is required. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -The most usual use case for this is to obtain information about the peer -from which the message was received. -This can be used to provide different behaviors for different peers, such as -a higher level of authentication for peers located on an untrusted network. -The [`nng_pipe_get()`](../conn/nng_pipe_get.md) function -is useful in this situation. - -## RETURN VALUES - -This function returns the pipe associated with this message, which will -be a positive value. -If the pipe is non-positive, then that indicates that -no specific pipe is associated with the message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_set_pipe](nng_msg_set_pipe.md), -[nng_pipe_get](../conn/nng_pipe_get.md) diff --git a/docs/reference/src/api/msg/nng_msg_header.md b/docs/reference/src/api/msg/nng_msg_header.md deleted file mode 100644 index 7a75464d..00000000 --- a/docs/reference/src/api/msg/nng_msg_header.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header - -## NAME - -nng_msg_header --- return message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_header(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_header()` function returns a pointer to the start of the header -content of the message _msg_. - -> [!NOTE] -> The message header contains protocol-specific header content. Most -> applications should not need to access this content, but it is available -> for [raw](../../overview/raw.md) mode sockets. - -> [!NOTE] -> The value returned by this is invalidated by a call to any of the -> functions that modify the message or the header content. - -## RETURN VALUES - -Pointer to start of message header. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_append.md b/docs/reference/src/api/msg/nng_msg_header_append.md deleted file mode 100644 index f87649a5..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_append.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_append - -## NAME - -nng_msg_header_append --- append to message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_append_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_append_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_header_append()` family of functions appends data to -the end of the headers of message _msg_, reallocating it if necessary. -The first function appends _size_ bytes, copying them from _val_. - -The remaining functions append the value (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_chop.md b/docs/reference/src/api/msg/nng_msg_header_chop.md deleted file mode 100644 index 9419d88f..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_chop.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_chop - -## NAME - -nng_msg_header_chop --- remove data from end of message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_chop(nng_msg *msg, size_t size); -int nng_msg_header_chop_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_chop_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_header_chop()` family of functions removes -data from the end of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -These function return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_clear.md b/docs/reference/src/api/msg/nng_msg_header_clear.md deleted file mode 100644 index 7f3b8387..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_clear.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_msg_header_clear - -## NAME - -nng_msg_header_clear --- clear message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_header_clear(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_clear()` function resets the header length of _msg_ to zero. - -## SEE ALSO - -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_len](nng_msg_header_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_insert.md b/docs/reference/src/api/msg/nng_msg_header_insert.md deleted file mode 100644 index 07124fd9..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_insert.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_insert - -## NAME - -nng_msg_header_insert --- prepend to message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_header_insert()` family of functions -prepends data to the front of the headers of message _msg_, reallocating -if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md) -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_len.md b/docs/reference/src/api/msg/nng_msg_header_len.md deleted file mode 100644 index 51bbf537..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_len.md +++ /dev/null @@ -1,25 +0,0 @@ -# nng_msg_header_len - -## NAME - -nng_msg_header_len --- return message header length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_header_len(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_header_len()` returns the length of message header of _msg_. - -## RETURN VALUES - -Length of message header. - -## SEE ALSO - -[nng_msg_header](nng_msg_header) diff --git a/docs/reference/src/api/msg/nng_msg_header_trim.md b/docs/reference/src/api/msg/nng_msg_header_trim.md deleted file mode 100644 index ef596dbc..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_trim.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_trim - -## NAME - -nng_msg_header_trim --- remove data from start of message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_trim(nng_msg *msg, size_t size); -int nng_msg_header_trim_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_header_trim()` family of functions remove -data from the start of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions removes 2, 4, or 8 bytes, and stores them in the -value (such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md) -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), diff --git a/docs/reference/src/api/msg/nng_msg_insert.md b/docs/reference/src/api/msg/nng_msg_insert.md deleted file mode 100644 index a369d3c4..00000000 --- a/docs/reference/src/api/msg/nng_msg_insert.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_insert - -## NAME - -nng_msg_insert --- prepend to message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_insert()` family of functions prepends data to -the front of the body of message _msg_, reallocating it if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) -in network-byte order (big-endian). - -> [!TIP] -> These functions make use of space pre-allocated in front of the -> message body if available, so they can often avoid performing any reallocation. -> Applications should use these instead of reallocating and copying message -> content themselves, in order to benefit from this capability. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_len.md b/docs/reference/src/api/msg/nng_msg_len.md deleted file mode 100644 index c470955c..00000000 --- a/docs/reference/src/api/msg/nng_msg_len.md +++ /dev/null @@ -1,26 +0,0 @@ -# nng_msg_len - -## NAME - -nng_msg_len --- return message body length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_len(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_len()` returns the length of the body of message _msg_. - -## RETURN VALUES - -Length of message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc), -[nng_msg_body](nng_msg_body) diff --git a/docs/reference/src/api/msg/nng_msg_realloc.md b/docs/reference/src/api/msg/nng_msg_realloc.md deleted file mode 100644 index 66d113aa..00000000 --- a/docs/reference/src/api/msg/nng_msg_realloc.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_realloc(3) - -## NAME - -nng_msg_realloc --- reallocate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_realloc(nng_msg *msg, size_t size); -``` - -## DESCRIPTION - -The `nng_msg_realloc()` function re-allocates a message so that it has -a body of length _size_. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. -When appending many small pieces of data to a message using [`nng_msg_append()`](nng_msg_append.md), -allocations may be reduced by first using -[`nng_msg_reserve()`](nng_msg_reserve.md) -to create sufficient space. -In any case, reallocating or appending to a message is guaranteed to succeed if the resulting -body length is less than [`nng_msg_capacity()`](nng_msg_capacity.md). - -> [!NOTE] -> Pointers to message body and header content obtained prior to this -> function must not be in use, as the underlying memory used for the message -> may have changed, particularly if the message size is increasing. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_reserve.md b/docs/reference/src/api/msg/nng_msg_reserve.md deleted file mode 100644 index 2d96ac8b..00000000 --- a/docs/reference/src/api/msg/nng_msg_reserve.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_msg_reserve - -## NAME - -nng_msg_reserve --- reserve storage for a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_reserve(nng_msg *msg, size_t capacity); -``` - -## DESCRIPTION - -The `nng_msg_reserve()` function ensures a message has allocated enough storage -to accommodate a body of the given length. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -> [!TIP] -> Using this message before [`nng_msg_append()`](nng_msg_append.md) -> will prevent additional memory allocations until the message's length exceeds -> the alotted capacity. - -> [!IMPORTANT] -> Pointers to message body and header content obtained prior to this -> function must not be in use, as the underlying memory used for the message -> may have changed, particularly if the message capacity is increasing. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_set_pipe.md b/docs/reference/src/api/msg/nng_msg_set_pipe.md deleted file mode 100644 index 58f339ca..00000000 --- a/docs/reference/src/api/msg/nng_msg_set_pipe.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_msg_set_pipe - -## NAME - -nng_msg_set_pipe --- set pipe for message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); -``` - -## DESCRIPTION - -The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_. -This is most often useful when used with protocols that support directing -a message to a specific peer. -For example the [_PAIR_](../protocols/pair.md) version 1 protocol can do -this when `NNG_OPT_PAIR1_POLY` mode is set. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_get_pipe](nng_msg_get_pipe.md) diff --git a/docs/reference/src/api/msg/nng_msg_trim.md b/docs/reference/src/api/msg/nng_msg_trim.md deleted file mode 100644 index c0b8f694..00000000 --- a/docs/reference/src/api/msg/nng_msg_trim.md +++ /dev/null @@ -1,48 +0,0 @@ -# nng_msg_trim - -## NAME - -nng_msg_trim --- remove data from start of message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_trim(nng_msg *msg, size_t size); -int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_trim()` family of functions removes data from -the start of the body of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md) -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md) |