docs: Document new HTTP header iteration options.

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc
index f7034987..bdd6989a 100644
--- a/docs/man/nng_ws.7.adoc
+++ b/docs/man/nng_ws.7.adoc
@@ -114,6 +114,30 @@ macro `NNG_OPT_WS_HEADER`, followed by the name of header field.
 
 Such options can be set on dialers and listener, and retrieved from pipes.
 
+((`NNG_OPT_WS_HEADER_NEXT`))::
+
+(bool) Reading this option advances the header iteration so that the values
+supplied by by `NNG_OPT_WS_HEADER_KEY` and `NNG_OPT_WS_HEADER_VALUE` represnt the
+next HTTP header.  This option is `true` if advancing succeeded, `false`
+if there are no more headers. This option is only valid on connected streams or pipes.
+
+((`NNG_OPT_WS_HEADER_RESET`)):
+
+(bool) Reset the HTTP header iteration so the next call to `NNG_OPT_WS_HEADER_NEXT`
+will start at the first HTTP header.
+
+((`NNG_OPT_WS_HEADER_KEY`)):
+
+(string) This option provides the HTTP header key or name for the currently
+selected HTTP header. It is invalid to read this until `NNG_OPT_WS_HEADER_NEXT` has
+been read with a `true` result.
+
+((`NNG_OPT_WS_HEADER_VALUE`)):
+
+(string) This option provides the HTTP header value of the currently selected
+HTTP header. It is invalid to read this until `NNG_OPT_WS_HEADER_NEXT` has
+been read with a `true` result.
+
 ((`NNG_OPT_WS_RECV_TEXT`))::
 
 (bool) Enable receiving of TEXT frames at the WebSocket layer.
diff --git a/include/nng/nng.h b/include/nng/nng.h
index 57283f00..c2c8125c 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -896,6 +896,14 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 // headers from the peer on a pipe.
 #define NNG_OPT_WS_HEADER "ws:header:"
 
+// These options allow for iterating over HTTP headers.  The iteration is
+// started and advances by getting NNG_OPT_WS_HEADER_NEXT (which returns a bool
+// that is true if there was a header, or false if no more headers are
+// available).  The HTTP_OPT_WS_HEADER_RESET is a boolean option that always
+// returns true. Reading it resets the iteration to the beginning.  The
+// NNG_OPT_WS_HEADER_KEY and NNG_OPT_WS_HEADER_VALUE options obtain the header
+// name and value for the current (established by NNG_OPT_WS_HEADER_NEXT) HTTP
+// header.
 #define NNG_OPT_WS_HEADER_NEXT "ws:hdr-next"
 #define NNG_OPT_WS_HEADER_RESET "ws:hdr-reset"
 #define NNG_OPT_WS_HEADER_KEY "ws:hdr-key"