From 9b156d28f1a830cc7339ab9993991ef5dd0b0fed Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sat, 30 Mar 2024 15:57:15 -0700
Subject: Organization changes abound.

---
 docs/reference/src/msg/index.md | 99 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/reference/src/msg/index.md

(limited to 'docs/reference/src/msg/index.md')

diff --git a/docs/reference/src/msg/index.md b/docs/reference/src/msg/index.md
new file mode 100644
index 00000000..ed63b4d2
--- /dev/null
+++ b/docs/reference/src/msg/index.md
@@ -0,0 +1,99 @@
+# 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 mode][raw] need to
+> access the message header.
+
+### Creating, Destroying and Using
+
+Messages are allocated using [`nng_msg_alloc()`][nng_msg_alloc],
+and are deallocated using [`nng_msg_free()`][nng_msg_free].
+
+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 "{{i:headroom}}" and "{{i: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][nng_aio_get_msg],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_msg_alloc][nng_msg_alloc],
+[nng_msg_append][nng_msg_append],
+[nng_msg_body][nng_msg_body],
+[nng_msg_capacity][nng_msg_capacity],
+[nng_msg_dup][nng_msg_dup],
+[nng_msg_free][nng_msg_free],
+[nng_msg_header][nng_msg_header],
+[nng_msg_header_append][nng_msg_header_append],
+[nng_msg_header_chop][nng_msg_header_chop],
+[nng_msg_header_clear][nng_msg_header_clear],
+[nng_msg_header_insert][nng_msg_header_insert],
+[nng_msg_header_len][nng_msg_header_len],
+[nng_msg_header_trim][nng_msg_header_trim],
+[nng_msg_insert][nng_msg_insert],
+[nng_msg_len][nng_msg_len],
+[nng_msg_reserve][nng_msg_reserve],
+[nng_msg_realloc][nng_msg_realloc],
+[nng_msg_set_pipe][nng_msg_set_pipe],
+[nng_msg_trim][nng_msg_trim],
+[nng_recvmsg][nng_recvmsg],
+[nng_sendmsg][nng_sendmsg]
+
+{{#include ../refs.md}}
-- 
cgit v1.2.3-70-g09d2