From 90b02493491e7ea6f962081efde4e29a1fd794c4 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 26 Mar 2024 07:55:58 -0700 Subject: More updates. --- docs/reference/src/api/msg/index.md | 96 ++++++++++++++++++++++ docs/reference/src/api/msg/nng_msg_alloc.md | 40 +++++++++ docs/reference/src/api/msg/nng_msg_append.md | 46 +++++++++++ docs/reference/src/api/msg/nng_msg_body.md | 47 +++++++++++ docs/reference/src/api/msg/nng_msg_capacity.md | 30 +++++++ docs/reference/src/api/msg/nng_msg_chop.md | 47 +++++++++++ docs/reference/src/api/msg/nng_msg_clear.md | 23 ++++++ docs/reference/src/api/msg/nng_msg_dup.md | 34 ++++++++ docs/reference/src/api/msg/nng_msg_free.md | 22 +++++ docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc | 60 ++++++++++++++ docs/reference/src/api/msg/nng_msg_header.3.adoc | 58 +++++++++++++ .../src/api/msg/nng_msg_header_append.3.adoc | 58 +++++++++++++ .../src/api/msg/nng_msg_header_chop.3.adoc | 58 +++++++++++++ .../src/api/msg/nng_msg_header_clear.3.adoc | 42 ++++++++++ .../src/api/msg/nng_msg_header_insert.3.adoc | 60 ++++++++++++++ .../src/api/msg/nng_msg_header_len.3.adoc | 43 ++++++++++ .../src/api/msg/nng_msg_header_trim.3.adoc | 59 +++++++++++++ docs/reference/src/api/msg/nng_msg_insert.3.adoc | 63 ++++++++++++++ docs/reference/src/api/msg/nng_msg_len.3.adoc | 43 ++++++++++ docs/reference/src/api/msg/nng_msg_realloc.3.adoc | 66 +++++++++++++++ docs/reference/src/api/msg/nng_msg_reserve.3.adoc | 63 ++++++++++++++ docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc | 50 +++++++++++ docs/reference/src/api/msg/nng_msg_trim.md | 48 +++++++++++ 23 files changed, 1156 insertions(+) create mode 100644 docs/reference/src/api/msg/index.md create mode 100644 docs/reference/src/api/msg/nng_msg_alloc.md create mode 100644 docs/reference/src/api/msg/nng_msg_append.md create mode 100644 docs/reference/src/api/msg/nng_msg_body.md create mode 100644 docs/reference/src/api/msg/nng_msg_capacity.md create mode 100644 docs/reference/src/api/msg/nng_msg_chop.md create mode 100644 docs/reference/src/api/msg/nng_msg_clear.md create mode 100644 docs/reference/src/api/msg/nng_msg_dup.md create mode 100644 docs/reference/src/api/msg/nng_msg_free.md create mode 100644 docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_append.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_chop.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_clear.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_insert.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_len.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_trim.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_insert.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_len.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_realloc.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_reserve.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_trim.md (limited to 'docs/reference/src/api/msg') diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md new file mode 100644 index 00000000..1a7bdabf --- /dev/null +++ b/docs/reference/src/api/msg/index.md @@ -0,0 +1,96 @@ +# 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_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 new file mode 100644 index 00000000..163d193b --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_alloc.md @@ -0,0 +1,40 @@ +# nng_msg_alloc + +## NAME + +nng_msg_alloc --- allocate a message + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..5807d3a6 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_append.md @@ -0,0 +1,46 @@ +# nng_msg_append + +## NAME + +nng_msg_append --- append to message body + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..abd49c7f --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_body.md @@ -0,0 +1,47 @@ +# nng_msg_body + +## NAME + +nng_msg_body --- return message body + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..707a04e3 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_capacity.md @@ -0,0 +1,30 @@ +# nng_msg_capacity + +## NAME + +nng_msg_capacity --- return message body length + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..fc9a0df5 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_chop.md @@ -0,0 +1,47 @@ +# nng_msg_chop + +## NAME + +nng_msg_chop --- remove data from end of message body + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..af25c072 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_clear.md @@ -0,0 +1,23 @@ +# nng_msg_clear + +## NAME + +nng_msg_clear --- clear message body content + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..dae376e8 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_dup.md @@ -0,0 +1,34 @@ +# nng_msg_dup + +## NAME + +nng_msg_dup --- duplicate a message + +## SYNOPSIS + +```c +#include + +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 new file mode 100644 index 00000000..94887be0 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_free.md @@ -0,0 +1,22 @@ +# nng_msg_free + +## NAME + +nng_msg_free --- free a message + +## SYNOPSIS + +```c +#include + +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.3.adoc b/docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc new file mode 100644 index 00000000..154f4c43 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc @@ -0,0 +1,60 @@ += nng_msg_get_pipe(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_get_pipe - get pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +nng_pipe nng_msg_get_pipe(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_get_pipe()` returns the xref:nng_pipe.5.adoc[`nng_pipe`] 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 xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] 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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header.3.adoc b/docs/reference/src/api/msg/nng_msg_header.3.adoc new file mode 100644 index 00000000..eac45ffd --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header - return message header + +== SYNOPSIS + +[source, c] +---- +#include + +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 mode sockets (set with the +xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`] option.) + +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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)] +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_append.3.adoc b/docs/reference/src/api/msg/nng_msg_header_append.3.adoc new file mode 100644 index 00000000..16badf0b --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_append.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_append(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_append - append to message header + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc b/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc new file mode 100644 index 00000000..454e9e51 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_chop(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_chop - remove data from end of message header + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc b/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc new file mode 100644 index 00000000..d00286ed --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc @@ -0,0 +1,42 @@ += nng_msg_header_clear(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_clear - clear message header + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_header_clear(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the header length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc b/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc new file mode 100644 index 00000000..a2bf0d63 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc @@ -0,0 +1,60 @@ += nng_msg_header_insert(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_insert - prepend to message header + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_len.3.adoc b/docs/reference/src/api/msg/nng_msg_header_len.3.adoc new file mode 100644 index 00000000..0a7b3613 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_header_len(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_len - return message header length + +== SYNOPSIS + +[source, c] +---- +#include + +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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc b/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc new file mode 100644 index 00000000..6df504ff --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc @@ -0,0 +1,59 @@ += nng_msg_header_trim(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_header_trim - remove data from start of message header + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_insert.3.adoc b/docs/reference/src/api/msg/nng_msg_insert.3.adoc new file mode 100644 index 00000000..25f98fce --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_insert.3.adoc @@ -0,0 +1,63 @@ += nng_msg_insert(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_insert - prepend to message body + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_len.3.adoc b/docs/reference/src/api/msg/nng_msg_len.3.adoc new file mode 100644 index 00000000..2a3dfe67 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_len(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_len - return message body length + +== SYNOPSIS + +[source, c] +---- +#include + +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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_realloc.3.adoc b/docs/reference/src/api/msg/nng_msg_realloc.3.adoc new file mode 100644 index 00000000..bf407289 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_realloc.3.adoc @@ -0,0 +1,66 @@ += nng_msg_realloc(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_realloc - reallocate a message + +== SYNOPSIS + +[source, c] +---- +#include + +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 xref:nng_msg_append.3.adoc[`nng_msg_append()`], +allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`] +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 xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. + +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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_reserve.3.adoc b/docs/reference/src/api/msg/nng_msg_reserve.3.adoc new file mode 100644 index 00000000..254c1e94 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_reserve.3.adoc @@ -0,0 +1,63 @@ += nng_msg_reserve(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_reserve - reserve storage for a message + +== SYNOPSIS + +[source, c] +---- +#include + +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 xref:nng_msg_append.3.adoc[`nng_msg_append()`] +will prevent additional memory allocations until the message's length exceeds +the alotted capacity. + +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 capacity is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc b/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc new file mode 100644 index 00000000..c95cc83f --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc @@ -0,0 +1,50 @@ += nng_msg_set_pipe(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_msg_set_pipe - set pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +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 xref:nng_pair.7.adoc[_pair_] version 1 protocol can do +this when `NNG_OPT_PAIR1_POLY` mode is set. + +NOTE: Not all protocols support overriding the destination pipe. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_trim.md b/docs/reference/src/api/msg/nng_msg_trim.md new file mode 100644 index 00000000..c0b8f694 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_trim.md @@ -0,0 +1,48 @@ +# nng_msg_trim + +## NAME + +nng_msg_trim --- remove data from start of message body + +## SYNOPSIS + +```c +#include + +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) -- cgit v1.2.3-70-g09d2