From 0c7e5a94182b8bf5b5be2fc58141466bf54d5812 Mon Sep 17 00:00:00 2001 From: Andy Green Date: Wed, 30 Dec 2015 14:53:50 +0800 Subject: [PATCH] doc improve docs around header access apis Signed-off-by: Andy Green --- lib/libwebsockets.h | 6 +++ lib/parsers.c | 44 ++++++++++++++++++ libwebsockets-api-doc.html | 111 ++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 160 insertions(+), 1 deletion(-) diff --git a/lib/libwebsockets.h b/lib/libwebsockets.h index 129f776..3199ec4 100644 --- a/lib/libwebsockets.h +++ b/lib/libwebsockets.h @@ -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 diff --git a/lib/parsers.c b/lib/parsers.c index ed36ecd..9df7a0e 100644 --- a/lib/parsers.c +++ b/lib/parsers.c @@ -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) { diff --git a/libwebsockets-api-doc.html b/libwebsockets-api-doc.html index 489f831..779c84e 100644 --- a/libwebsockets-api-doc.html +++ b/libwebsockets-api-doc.html @@ -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.
+

lws_hdr_fragment_length -

+int +lws_hdr_fragment_length +(struct lws * wsi, +enum lws_token_indexes h, +int frag_idx) +

Arguments

+
+
wsi +
websocket connection +
h +
which header index we are interested in +
frag_idx +
which fragment of h we want to get the length of +
+

Description

+
+The returned length does not include the space for a +terminating '\0' +
+
+

lws_hdr_total_length -

+int +lws_hdr_total_length +(struct lws * wsi, +enum lws_token_indexes h) +

Arguments

+
+
wsi +
websocket connection +
h +
which header index we are interested in +
+

Description

+
+The returned length does not include the space for a +terminating '\0' +
+
+

lws_hdr_copy_fragment -

+int +lws_hdr_copy_fragment +(struct lws * wsi, +char * dst, +int len, +enum lws_token_indexes h, +int frag_idx) +

Arguments

+
+
wsi +
websocket connection +
dst +
destination buffer +
len +
length of destination buffer +
h +
which header index we are interested in +
+

Description

+
+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. +
+
+

lws_hdr_copy -

+int +lws_hdr_copy +(struct lws * wsi, +char * dst, +int len, +enum lws_token_indexes h) +

Arguments

+
+
wsi +
websocket connection +
dst +
destination buffer +
len +
length of destination buffer +
h +
which header index we are interested in +
+

Description

+
+The buffer length len must include space for an additional +terminating '\0', or it will fail returning -1. +
+

lws_frame_is_binary -

int lws_frame_is_binary @@ -1363,7 +1453,7 @@ If proxy auth is required, use format
uid
user id to change to after setting listen socket, or -1.
options -
0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK +
0, or LWS_SERVER_OPTION_... bitfields
user
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.
+

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.

+LWS_EXTERN void +lws_close_reason +(struct lws * wsi, +enum lws_close_status status, +unsigned char * buf, +size_t len) +

Arguments

+
+
wsi +
The websocket connection to set the close reason on +
status +
A valid close status from websocket standard +
buf +
NULL or buffer containing up to 124 bytes of auxiliary data +
len +
Length of data in buf to send +
+
-- 2.7.4