diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/SUMMARY.md | 11 | ||||
| -rw-r--r-- | docs/ref/api/msg.md | 274 | ||||
| -rw-r--r-- | docs/ref/api/msg/index.md | 8 | ||||
| -rw-r--r-- | docs/ref/api/msg/nng_msg.md | 146 | ||||
| -rw-r--r-- | docs/ref/api/msg/nng_msg_body.md | 112 | ||||
| -rw-r--r-- | docs/ref/api/msg/nng_msg_header.md | 94 | ||||
| -rw-r--r-- | docs/ref/api/msg/nng_msg_pipe.md | 40 |
7 files changed, 277 insertions, 408 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 9aee312b..dabdcf1f 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -6,14 +6,11 @@ - [API Reference](./api/index.md) - - [Messages](./api/msg/index.md) + - [Messages](./api/msg.md) - - [nng_msg](./api/msg/nng_msg.md) - - [nng_msg_body](./api/msg/nng_msg_body.md) - - [nng_msg_header](./api/msg/nng_msg_header.md) - - [nng_msg_pipe](./api/msg/nng_msg_pipe.md) + - [Time](./api/time.md) - - [Asynchronous I/O Operations](./api/aio/index.md) + - [Asynchronous Operations](./api/aio/index.md) - [nng_aio](./api/aio/nng_aio.md) - [aio_cancel](./api/aio/aio_cancel.md) @@ -26,8 +23,6 @@ - [Statistics](./api/stats.md) - - [Time](./api/time.md) - - [Utility Functions](./api/util/index.md) - [nng_alloc](./api/util/nng_alloc.md) diff --git a/docs/ref/api/msg.md b/docs/ref/api/msg.md new file mode 100644 index 00000000..569d4692 --- /dev/null +++ b/docs/ref/api/msg.md @@ -0,0 +1,274 @@ +# Messages + +Messages {{hi:messages}} in Scalability Protocols are the fundamental unit of +transmission and reception, as these protocols are fundamentally message-oriented. + +Messages have a [body][nng_msg_body]{{hi:message body}}, containing the application-supplied +payload, and a [header][nng_msg_header]{{hi:message header}}, containing protocol specific routing and similar +related information. + +> [!TIP] +> Only applications using [raw mode][raw] need to access the message header. +> Very few _NNG_ applications do this. + +## Message Structure + +```c +typedef struct nng_msg nng_msg; +``` + +The {{i:`nng_msg`}} structure represents a single message. It carries a body +and a header. + +### Create a Message + +```c +int nng_msg_alloc(nng_msg **msgp, size_t size); +``` + +The {{i:`nng_msg_alloc`}} function allocates a new message. +It takes a _size_ argument, and returns a message +with a preallocated body of that size in the _msgp_ parameter. + +If it succeeds, it returns zero, otherwise this function may return `NNG_ENOMEM`, +indicating that insufficient memory is available to allocate a new message. + +### Destroy a Message + +```c +void nng_msg_free(nng_msg *msg); +``` + +The {{i:`nng_msg_free`}} function deallocates a message. + +### Duplicate a Message + +```c +int nng_msg_dup(nng_msg **dup, nng_msg *msg); +``` + +The {{i:`nng_msg_dup`}} function duplicates the message _msg_, storing a pointer +to the new duplicate in _dup_. This function also returns zero on succes, or `NNG_ENOMEM` +if memory is exhausted. + +## Message Size and Capacity + +```c +size_t nng_msg_capacity(nng_msg *msg); +int nng_msg_realloc(nng_msg *msg, size_t size); +int nng_msg_reserve(nng_msg *msg, size_t capacity); +``` + +Messages have a certain amount of pre-reserved space, which may exceed the total +size of the message. This allows for content to be added to the message later, +without necessarily performing a reallocation. + +The {{i:`nng_msg_capacity`}} function returns the amount of prereserved space. +If a message size change is required, and the new size will fit within the capacity +reported by this function, then change will be done without a reallocation, and +likely without a data copy as well. + +> [!TIP] +> The capacity reported by `nng_msg_capacity` may not include reserved headroom, which +> is present to allow a very limited amount of content to be inserted in front of the +> message without requiring the rest of the message to be copied. + +The message size may be changed by use of the {{i:`nng_msg_realloc`}} function. This +function will reallocate the underlying memory for the message _msg_, +preserving contents while doing so. +If the new size is smaller than the original message, it will +truncate the message, but not perform any allocations. +If reallocation fails due to insufficient memory, then the original is left intact. +This function returns either zero, or `NNG_ENOMEM`. + +The {{i:`nng_msg_reserve`}} function ensures that the total message capacity +is at least _capacity_ bytes. Use of this function to ensure the total anticipated +capacity is present in the message may help prevent many small allocations. + +Both `nng_msg_realloc` and `nng_msg_reserve` return zero on success, or may return +`NNG_ENOMEM` if insufficient memory exists to preform allocation. + +> [!IMPORTANT] +> Any pointers to message content obtained before a call to `nng_msg_realloc` or +> `nng_msg_reserve` (or any other function that changes the message size) should be +> treated as invalid, as the locations pointed to may be deallocated by these functions. + +## Message Body + +```c +void *nng_msg_body(nng_msg *msg); +size_t nng_msg_len(nng_msg *msg); +``` + +The body and body length of _msg_ are returned by {{i:`nng_msg_body}}` and +{{i:`nng_msg_len`}}, respectively. + +### Clear the Body + +```c +void *nng_msg_clear(nng_msg *msg); +``` + +The {{i:`nng_msg_clear`}} simply resets the total message body length to zero, but does +not affect the capacity. It does not change the underlying bytes of the message. + +### Add to Body + +```c +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); + +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); +``` + +Appending data to a message body is done by using the {{i:`nng_msg_append`}} functions. +The base `nng_msg_append` function appends _size_ bytes of untyped data to the end of the +message. + +Use of the typed versions, ending in suffixes `_u16`, `_u32`, and `_u64` allows +for unsigned integers to be appended directly. The integers are encoded in network byte order, with +the most significant byte appearing first. The message body will by two, four, or eight +bytes accordingly. + +Data may inserted before the rest of the message body by using the {{i:`nng_msg_insert`}} functions. +This will attempt to use "headroom" in the message to avoid a data copy. +Otherwise they are like the `nng_msg_append` functions except that the put the data in front +of the messages instead of at the end. + +> [!TIP] +> Message headroom is limited, so `nng_msg_insert` is best used sparingly. +> It is much more efficient to build the message content from start to end +> using `nng_msg_append`. + +### Consume From Body + +```c +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); + +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); +``` + +The {{i:`nng_msg_chop`}} functions remove data from the end of the body of message _msg_, +reducing the message length by either _size_, or the appropriate value size. + +The {{i:`nng_msg_trim`}} functions remove data from the beginning of the message body of _msg_. +but are otherwise just like the `nng_msg_chop` functions. + +If the message is not big enough to remove requisite amount of bytes, these functions +return `NNG_EINVAL`. Otherwise they return zero. + +Additionally, functions with typed suffixes (`_u16`, `_u32`, `_u64`) decode the data and return it +through the appropriate _val_ pointer. + +The data is assumed to have been in network byte order in the message, but is returned in +the native machine byte order. The appropriate number of bytes is consumed for each of these types, +so two bytes for `_u16`, four bytes for `_u32`, and eight bytes for `_u64`. + +## Message Header + +```c +void *nng_msg_header(nng_msg *msg); +size_t nng_msg_header_len(nng_msg *msg); +``` + +The header and header length of _msg_ are returned by {{i:`nng_msg_header}}` and +{{i:`nng_msg_header_len`}}, respectively. + +The message headers are generally intended for limited use, to store protocol headers. + +> [!IMPORTANT] +> The message headers are for protocol and transport headers, and not for general +> application payloads. Misuse of the header may prevent the application from functioning +> properly. + +### Clear the Header + +```c +void *nng_msg_header_clear(nng_msg *msg); +``` + +The {{i:`nng_msg_header_clear`}} simply resets the total message header length to zero. + +### Append or Insert Header + +Appending data to a message header is done by using the {{i:`nng_msg_header_append`}} functions, +and inserting data in the header is done using the {{i:`nng_msg_header_insert`}} functions. + +These functions act just like the [`nng_msg_append`][nng_msg_append] and [`nng_msg_insert`][nng_msg_insert] +functions, except that they operate on the message header rather than the message body. + +### Consume from Header + +The {{i:`nng_msg_header_trim`}} functions remove data from the beginning of the message header, +and the {{i:`nng_msg_header_chop`}} functions remove data from the end of the message header. + +These functions act just like the [`nng_msg_trim`][nng_msg_trim] and [`nng_msg_chop`][nng_msg_chop] +functions, except that they operate the message header rather than the message body. + +## Message Pipe + +```c +nng_pipe nng_msg_get_pipe(nng_msg *msg); +void nng_msg_get_pipe(nng_msg *msg, nng_pipe p); +``` + +The {{i:`nng_msg_set_pipe`}} function sets the [pipe][pipe] associated with _msg_ to _p_. +This is most often useful when used with protocols that support directing +a message to a specific peer. +For example the [_PAIR_][pair] version 1 protocol can do +this when `NNG_OPT_PAIR1_POLY` mode is set. + +The {{i:`nng_msg_get_pipe`}} function returns the pipe that was previously set on the message _m_, +either directly by the application, or when the message was received by the protocol. + +> [!NOTE] +> Not all protocols support overriding the destination pipe. + +## 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 + } + } +``` + +[nng_msg_body]: #message-body +[nng_msg_header]: #message-header +[nng_msg_append]: #add-to-body +[nng_msg_insert]: #add-to-body +[nng_msg_trim]: #consume-from-body +[nng_msg_chop]: #consume-from-body +[nng_msg_header_append]: #append-or-insert-header +[raw]: TODO.md +[pair]: ../proto/pair.md +[pipe]: TODO.md diff --git a/docs/ref/api/msg/index.md b/docs/ref/api/msg/index.md deleted file mode 100644 index 72f277d3..00000000 --- a/docs/ref/api/msg/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Messages - -These interfaces deal with messages, used in the Scalability Protocols. - -- [nng_msg](./nng_msg.md) --- message -- [nng_msg_body](./nng_msg_body.md) --- message body -- [nng_msg_header](./nng_msg_header.md) --- message header -- [nng_msg_pipe](./nng_msg_pipe) --- message pipe diff --git a/docs/ref/api/msg/nng_msg.md b/docs/ref/api/msg/nng_msg.md deleted file mode 100644 index 3ab4d046..00000000 --- a/docs/ref/api/msg/nng_msg.md +++ /dev/null @@ -1,146 +0,0 @@ -# nng_msg - -## NAME - -nng_msg --- message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -typedef struct nng_msg nng_msg; - -int nng_msg_alloc(nng_msg **msgp, size_t size); -void nng_msg_free(nng_msg *msg); -int nng_msg_dup(nng_msg **dup, nng_msg *msg); -int nng_msg_realloc(nng_msg *msg, size_t size); -int nng_msg_reserve(nng_msg *msg, size_t capacity); -size_t nng_msg_capacity(nng_msg *msg); -``` - -## DESCRIPTION - -An {{i:`nng_msg`}} represents a single {{i:message}} sent between Scalability Protocols peers. - -Messages in Scalability Protocols are the fundamental unit of transmission and reception, -as these protocols are fundamentally message-oriented. - -> [!NOTE] -> 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. - -Messages have a [body][nng_msg_body]{{hi:body}}, containing the application-supplied -payload, and a [header][nng_msg_header]{{hi:header}}, containing protocol specific routing and similar -related information. - -> [!TIP] -> Only applications using [raw mode][raw] need to access the message header. - -### Creating and Destroying Messages - -Messages are allocated using {{i:`nng_msg_alloc`}}, -and are deallocated using {{i:`nng_msg_free`}}. - -The `nng_msg_alloc` function takes a _size_ argument, and returns a message -with a preallocated body of that size in the _msgp_ parameter. - -Messages can be deallocated when no longer needed using `nng_msg_free`. - -A message may be duplicated using the {{i:`nng_msg_dup`}} function, which can be useful -when a copy must be saved or modified. The contents of the duplicate message will -be the same, but the actual pointers may be different, and the amount of reserved -space may be different as well. - -### Message Size and Capacity - -The message size may be changed by use of the {{i:`nng_msg_realloc`}} function. This -function will reallocate the underlying memory for the message _msg_, -preserving contents while doing so. -If the new size is smaller than the original message, it will -truncate the message, but not perform any allocations. -If reallocation fails due to insufficient memory, then the original is left intact. - -If message growth is anticipated, the {{i:`nng_msg_reserve`}} function can be used -to ensure that the buffers underlying the message will be sufficient to hold a message -of at least _capacity_ bytes. The actual message {{i:capacity}} can be obtained using the -{{i:`nng_msg_capacity`}}. As long as the new size will not exceeed that capacity, -any functions that change the message will do so without an allocation, and are guaranteed -to succeed. - -> [!IMPORTANT] -> Any pointers to message content obtained before a call to `nng_msg_realloc` or -> `nng_msg_reserve` (or any other function that changes the message size) should be -> treated as invalid, as the locations pointed to may be deallocated by these functions. - -### 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 "{{i:headroom}}" and "{{i:tailroom}}", are automatically -included when allocating a message. - -Using `nng_msg_reserve` to ensure that adequate buffer space is available -in advance can reduce repeated allocations and data copies when modifying messages. - -## RETURN VALUES - -The `nng_msg_alloc`, `nng_msg_dup`, `nng_msg_realloc`, and `nng_msg_reserve` -functions return zero on success, or an error value on failure, typically `NNG_ENOMEM`. - -The `nng_msg_capacity` function returns the total body capacity of the message _msg_. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to perform the operation. - -## 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][nng_aio_get_msg], -[nng_msg_body][nng_msg_body], -[nng_msg_header][nng_msg_header], -[nng_msg_set_pipe][nng_msg_set_pipe], -[nng_recvmsg][nng_recvmsg], -[nng_sendmsg][nng_sendmsg] - -[nng_msg_body]: ./nng_msg_body.md -[nng_msg_header]: ./nng_msg_header.md -[nng_msg_set_pipe]: ./nng_msg_set_pipe.md -[nng_aio_get_msg]: TODO.md -[nng_aio_set_msg]: TODO.md -[nng_recvmsg]: TODO.md -[nng_sendmsg]: TODO.md -[raw]: TODO.md diff --git a/docs/ref/api/msg/nng_msg_body.md b/docs/ref/api/msg/nng_msg_body.md deleted file mode 100644 index 2942738a..00000000 --- a/docs/ref/api/msg/nng_msg_body.md +++ /dev/null @@ -1,112 +0,0 @@ -# nng_msg_body - -## NAME - -nng_msg_body --- message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_body(nng_msg *msg); -size_t nng_msg_len(nng_msg *msg); -void nng_msg_clear(nng_msg *msg); -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); -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); -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); -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 {{i:body}} of a message is the part of the message that is used -for the application payload, and does not normally include protocol -or transport-specific data. - -The `nng_msg_body` function returns a pointer to the start of the body -content of the message _msg_. - -The `nng_msg_len` function returns the length of the message body in bytes. - -> [!IMPORTANT] -> The value returned by `nng_msg_body` is invalidated by a call to any of the -> functions that modify the message itself. - -The rest of these functions allow modifying the message body. - -### Clearing the Message Body - -The message body can be entirely cleared using {{i:`nng_msg_clear`}}. -The underlying buffers are left intact, and the bytes may remain at their original values, so -this function should not be relied upon for zeroizing sensitive data. - -### Appending and Inserting Data - -Appending data to a message body is done by using the {{i:`nng_msg_append`}} functions. -The base `nng_msg_append` function appends _size_ bytes of untyped data to the end of the -message. - -> [!TIP] -> Using [`nng_msg_reserve`][nng_msg] to preallocate space before appending or inserting -> can reduce allocations and data copies, for a significant performance benefit. - -Use of the typed versions, ending in suffixes `_u16`, `_u32`, and `_u64` allows -for unsigned integers to be appended directly. The integers are encoded in network byte order, with -the most significant byte appearing first. The message body will by two, four, or eight -bytes accordingly. - -Data may inserted before the rest of the message body by using the {{i:`nng_msg_insert`}} functions. -This will attempt to use "headroom" in the message to avoid a data copy. - -> [!TIP] -> Message headroom is limited, so `nng_msg_insert` is best used sparingly. -> It is much more efficient to build the message content from start to end -> using `nng_msg_append`. - -Typed versions and the untyped base function behave similarly to the `nng_msg_append` functions. - -### Consuming Data - -The {{i:`nng_msg_trim`}} functions remove data from the beginning of the message body. -This is accomplished by incrementing the pointer to start of the message by the appropriate size. - -Additionally, functions with typed suffixes (`_u16`, `_u32`, `_u64`) allow the data obtained to be decoded and returned. -The data is assumed to have been in network byte order in the message, but is returned in -the native machine byte order. The appropriate number of bytes is consumed for each of these types, -so two bytes for `_u16`, four bytes for `_u32`, and eight bytes for `_u64`. - -The {{i:`nng_msg_chop`}} functions behave in a similar fashion, but consume data from the -end of the message body. - -## RETURN VALUES - -The `nng_msg_body` function returns a pointer to the start of the message body. -The `nng_msg_len` function returns the length of the message body in bytes. -The `nng_msg_clear` function does not return anything. -The remaining functions return zero on success, or a non-zero error value on failure. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory exists to grow the message. -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg][nng_msg], -[nng_msg_header][nng_msg_header] - -[nng_msg]: ./nng_msg.md -[nng_msg_header]: ./nng_msg_header.md diff --git a/docs/ref/api/msg/nng_msg_header.md b/docs/ref/api/msg/nng_msg_header.md deleted file mode 100644 index 7743684a..00000000 --- a/docs/ref/api/msg/nng_msg_header.md +++ /dev/null @@ -1,94 +0,0 @@ -# nng_msg_header - -## NAME - -nng_msg_header --- message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_header(nng_msg *msg); -size_t nng_msg_header_len(nng_msg *msg); -void nng_msg_header_clear(nng_msg *msg); -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); -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); -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); -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 {{i:header}} of a message contains protocol and transport-specific -header content. -Typically there is only a very limited amount of data stored in the message -headers, in order to allow more room for the message body data. Headers -should be considered overhead in the protocols where they appear. - -> [!TIP] -> Most applications should not need to access the message header content -> directly, unless they are working with [raw mode][raw] sockets. - -The `nng_msg_header` function returns a pointer to the start of the header -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 or the header content. - -### Clearing the Message Header - -The message headers can be entirely cleared using {{i:`nng_msg_header_clear`}}. -The underlying buffers are left intact, and the bytes may remain at their original values, so -this function should not be relied upon for zeroizing sensitive data. - -### Appending and Inserting Data - -Appending data to a message header is done by using the {{i:`nng_msg_header_append`}} functions, -and inserting data in the header is done using the {{i:`nng_msg_header_insert`}} functions. - -These functions act just like the [`nng_msg_append`][nng_msg_body] and [`nng_msg_insert`][nng_msg_body] -functions, except that they operate on the message header rather than the message body. - -### Consuming Data - -The {{i:`nng_msg_header_trim`}} functions remove data from the beginning of the message header, -and the {{i:`nng_msg_header_chop`}} functions remove data from the end of the message header. - -These functions act just like the [`nng_msg_trim`][nng_msg_body] and [`nng_msg_chop`][nng_msg_body] -functions, except that they operate the message header rather than the message body. - -## RETURN VALUES - -The `nng_msg_header` function returns a pointer to the start of the message header. -The `nng_msg_header_len` function returns the length of the message header in bytes. -The `nng_msg_header_clear` function does not return anything. -The remaining functions return zero on success, or a non-zero error value on failure. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory exists to grow the message. -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg][nng_msg], -[nng_msg_body][nng_msg_body], -[raw mode][raw] - -[nng_msg]: ./nng_msg.md -[nng_msg_body]: ./nng_msg_body.md -[raw]: TODO.md diff --git a/docs/ref/api/msg/nng_msg_pipe.md b/docs/ref/api/msg/nng_msg_pipe.md deleted file mode 100644 index ec6fe910..00000000 --- a/docs/ref/api/msg/nng_msg_pipe.md +++ /dev/null @@ -1,40 +0,0 @@ -# nng_msg_pipe - -## NAME - -nng_msg_pipe --- set or get pipe for message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -nng_pipe nng_msg_get_pipe(nng_msg *msg); -void nng_msg_get_pipe(nng_msg *msg, nng_pipe p); -``` - -## DESCRIPTION - -The {{i:`nng_msg_set_pipe`}} function sets the [pipe][pipe] associated with [message][msg] _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_][pair] version 1 protocol can do -this when `NNG_OPT_PAIR1_POLY` mode is set. - -The {{i:`nng_msg_get_pipe`}} function returns the pipe that was previously set on the message _m_, -either directly by the application, or when the message was received by the protocol. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -## RETURN VALUES - -The `nng_msg_get_pipe` function returns the pipe for the message _m_. - -## SEE ALSO - -[nng_msg][msg] - -[msg]: ./nng_msg.md -[pair]: TODO.md -[pipe]: TODO.md |