stv0g/libwebsockets
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

doc improve docs around header access apis

Browse source 
Signed-off-by: Andy Green <andy.green@linaro.org>
This commit is contained in:
Andy Green 2015-12-30 14:53:50 +08:00
parent 2b35e123f4
commit 0c7e5a9418
3 changed files with 160 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
lib/libwebsockets.h
View file

@ -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

44
lib/parsers.c
View file

@ -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)
{
@ -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;
@ -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)
{
@ -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)
{

111
libwebsockets-api-doc.html
View file

@ -271,6 +271,96 @@ would call it with a timeout_ms of 0, so it returns immediately if
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>
@ -1363,7 +1453,7 @@ If proxy auth is required, use format
<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
@ -1398,3 +1488,22 @@ busy new incoming connections must wait for accept until one
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>