Skip to content

Commit

Permalink
doc improve docs around header access apis
Browse files Browse the repository at this point in the history 
Signed-off-by: Andy Green <[email protected]>
  • Loading branch information
Andy Green committed Dec 30, 2015
1 parent 2b35e12 commit 0c7e5a9
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 1 deletion.
6 changes: 6 additions & 0 deletions lib/libwebsockets.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1616,6 +1616,12 @@ lws_get_library_version(void);
* During LWS_CALLBACK_HTTP when the URI path is delivered is the last time
* the http headers are still allocated, you can use these apis then to
* look at and copy out interesting header content (cookies, etc)
*
* Notice that the header total length reported does not include a terminating
* '\0', however you must allocate for it when using the _copy apis. So the
* length reported for a header containing "123" is 3, but you must provide
* a buffer of length 4 so that "123\0" may be copied into it, or the copy
* will fail with a nonzero return code.
*/

LWS_VISIBLE LWS_EXTERN int
Expand Down
44 changes: 44 additions & 0 deletions lib/parsers.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,16 @@ int lws_free_header_table(struct lws *wsi)
return 0;
}

/**
* lws_hdr_fragment_length: report length of a single fragment of a header
* The returned length does not include the space for a
* terminating '\0'
*
* @wsi: websocket connection
* @h: which header index we are interested in
* @frag_idx: which fragment of @h we want to get the length of
*/

LWS_VISIBLE int
lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, int frag_idx)
{
Expand All @@ -153,6 +163,15 @@ lws_hdr_fragment_length(struct lws *wsi, enum lws_token_indexes h, int frag_idx)
return 0;
}

/**
* lws_hdr_total_length: report length of all fragments of a header totalled up
* The returned length does not include the space for a
* terminating '\0'
*
* @wsi: websocket connection
* @h: which header index we are interested in
*/

LWS_VISIBLE int lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h)
{
int n;
Expand All @@ -169,6 +188,20 @@ LWS_VISIBLE int lws_hdr_total_length(struct lws *wsi, enum lws_token_indexes h)
return len;
}

/**
* lws_hdr_copy_fragment: copy a single fragment of the given header to a buffer
* The buffer length @len must include space for an additional
* terminating '\0', or it will fail returning -1.
* If the requested fragment index is not present, it fails
* returning -1.
*
* @wsi: websocket connection
* @dst: destination buffer
* @len: length of destination buffer
* @h: which header index we are interested in
* @frag_index: which fragment of @h we want to copy
*/

LWS_VISIBLE int lws_hdr_copy_fragment(struct lws *wsi, char *dst, int len,
enum lws_token_indexes h, int frag_idx)
{
Expand All @@ -192,6 +225,17 @@ LWS_VISIBLE int lws_hdr_copy_fragment(struct lws *wsi, char *dst, int len,
return wsi->u.hdr.ah->frags[f].len;
}

/**
* lws_hdr_copy: copy a single fragment of the given header to a buffer
* The buffer length @len must include space for an additional
* terminating '\0', or it will fail returning -1.
*
* @wsi: websocket connection
* @dst: destination buffer
* @len: length of destination buffer
* @h: which header index we are interested in
*/

LWS_VISIBLE int lws_hdr_copy(struct lws *wsi, char *dst, int len,
enum lws_token_indexes h)
{
Expand Down
111 changes: 110 additions & 1 deletion libwebsockets-api-doc.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,96 @@ <h3>Description</h3>
nothing is pending, or as soon as it services whatever was pending.
</blockquote>
<hr>
<h2>lws_hdr_fragment_length - </h2>
<i>int</i>
<b>lws_hdr_fragment_length</b>
(<i>struct lws *</i> <b>wsi</b>,
<i>enum lws_token_indexes</i> <b>h</b>,
<i>int</i> <b>frag_idx</b>)
<h3>Arguments</h3>
<dl>
<dt><b>wsi</b>
<dd>websocket connection
<dt><b>h</b>
<dd>which header index we are interested in
<dt><b>frag_idx</b>
<dd>which fragment of <tt><b>h</b></tt> we want to get the length of
</dl>
<h3>Description</h3>
<blockquote>
The returned length does not include the space for a
terminating '\0'
</blockquote>
<hr>
<h2>lws_hdr_total_length - </h2>
<i>int</i>
<b>lws_hdr_total_length</b>
(<i>struct lws *</i> <b>wsi</b>,
<i>enum lws_token_indexes</i> <b>h</b>)
<h3>Arguments</h3>
<dl>
<dt><b>wsi</b>
<dd>websocket connection
<dt><b>h</b>
<dd>which header index we are interested in
</dl>
<h3>Description</h3>
<blockquote>
The returned length does not include the space for a
terminating '\0'
</blockquote>
<hr>
<h2>lws_hdr_copy_fragment - </h2>
<i>int</i>
<b>lws_hdr_copy_fragment</b>
(<i>struct lws *</i> <b>wsi</b>,
<i>char *</i> <b>dst</b>,
<i>int</i> <b>len</b>,
<i>enum lws_token_indexes</i> <b>h</b>,
<i>int</i> <b>frag_idx</b>)
<h3>Arguments</h3>
<dl>
<dt><b>wsi</b>
<dd>websocket connection
<dt><b>dst</b>
<dd>destination buffer
<dt><b>len</b>
<dd>length of destination buffer
<dt><b>h</b>
<dd>which header index we are interested in
</dl>
<h3>Description</h3>
<blockquote>
The buffer length <tt><b>len</b></tt> must include space for an additional
terminating '\0', or it will fail returning -1.
If the requested fragment index is not present, it fails
returning -1.
</blockquote>
<hr>
<h2>lws_hdr_copy - </h2>
<i>int</i>
<b>lws_hdr_copy</b>
(<i>struct lws *</i> <b>wsi</b>,
<i>char *</i> <b>dst</b>,
<i>int</i> <b>len</b>,
<i>enum lws_token_indexes</i> <b>h</b>)
<h3>Arguments</h3>
<dl>
<dt><b>wsi</b>
<dd>websocket connection
<dt><b>dst</b>
<dd>destination buffer
<dt><b>len</b>
<dd>length of destination buffer
<dt><b>h</b>
<dd>which header index we are interested in
</dl>
<h3>Description</h3>
<blockquote>
The buffer length <tt><b>len</b></tt> must include space for an additional
terminating '\0', or it will fail returning -1.
</blockquote>
<hr>
<h2>lws_frame_is_binary - </h2>
<i>int</i>
<b>lws_frame_is_binary</b>
Expand Down Expand Up @@ -1363,7 +1453,7 @@ <h3>Members</h3>
<dt><b>uid</b>
<dd>user id to change to after setting listen socket, or -1.
<dt><b>options</b>
<dd>0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
<dd>0, or LWS_SERVER_OPTION_... bitfields
<dt><b>user</b>
<dd>optional user pointer that can be recovered via the context
pointer using lws_context_user
Expand Down Expand Up @@ -1398,3 +1488,22 @@ <h3>Members</h3>
becomes free.
</dl>
<hr>
<h2>lws_close_reason - Set reason and aux data to send with Close packet If you are going to return nonzero from the callback requesting the connection to close, you can optionally call this to set the reason the peer will be told if possible.</h2>
<i>LWS_EXTERN void</i>
<b>lws_close_reason</b>
(<i>struct lws *</i> <b>wsi</b>,
<i>enum lws_close_status</i> <b>status</b>,
<i>unsigned char *</i> <b>buf</b>,
<i>size_t</i> <b>len</b>)
<h3>Arguments</h3>
<dl>
<dt><b>wsi</b>
<dd>The websocket connection to set the close reason on
<dt><b>status</b>
<dd>A valid close status from websocket standard
<dt><b>buf</b>
<dd>NULL or buffer containing up to 124 bytes of auxiliary data
<dt><b>len</b>
<dd>Length of data in <tt><b>buf</b></tt> to send
</dl>
<hr>

0 comments on commit 0c7e5a9

Please sign in to comment.