net: coap_client: Document payload callback

Document the usage of the payload callback in the CoAP client
documentation page.

Signed-off-by: Robert Lubos <[email protected]>

Author: rlubos

doc/connectivity/networking/api/coap_client.rst

@@ -106,6 +106,52 @@ RFC7959 Figure 3: Block-Wise GET with Early Negotiation).
 
     ret = coap_client_req(&client, sock, &address, &req, -1);
 
+Optionally, the application can register a payload callback instead of providing a payload pointer
+for the CoAP upload. In such cases, the CoAP client library will call this callback when preparing
+a PUT/POST request, so that the application can provide the payload in blocks, instead of having to
+provide a single contiguous buffer with the entire payload. An example callback, providing the
+content of the Lorem Ipsum string can look like this:
+
+.. code-block:: c
+
+    static int lorem_ipsum_cb(size_t offset, const uint8_t **payload, size_t *len,
+                              bool *last_block, void *user_data)
+    {
+        size_t data_left;
+
+        if (offset > LOREM_IPSUM_STRLEN) {
+            return -EINVAL;
+        }
+
+        *payload = LOREM_IPSUM + offset;
+
+        data_left = LOREM_IPSUM_STRLEN - offset;
+        if (data_left <= *len) {
+            *len = data_left;
+            *last_block = true;
+        } else {
+            *last_block = false;
+        }
+
+        return 0;
+    }
+
+The callback can then be registered for the PUT/POST request instead of a payload pointer:
+
+.. code-block:: c
+
+    struct coap_client_request req = { 0 };
+
+    req.method = COAP_METHOD_PUT;
+    req.confirmable = true;
+    req.path = "lorem-ipsum";
+    req.fmt = COAP_CONTENT_FORMAT_TEXT_PLAIN;
+    req.cb = response_cb;
+	req.payload_cb = lore_ipsum_cb,
+
+    ret = coap_client_req(&client, sock, &address, &req, -1);
+
+
 API Reference
 *************