From 9f4e9b064db9301c1eaa46e08e8ca8937175b3fb Mon Sep 17 00:00:00 2001 From: Andy Green Date: Tue, 22 Jan 2013 12:40:35 +0800 Subject: [PATCH] trac 3 document write and context_user Signed-off-by: Andy Green --- lib/Makefile.am | 4 +- lib/libwebsockets.c | 11 ++ libwebsockets-api-doc.html | 254 +++++++++++++++++++++++++++++---------------- 3 files changed, 179 insertions(+), 90 deletions(-) diff --git a/lib/Makefile.am b/lib/Makefile.am index d917a67..2421bc5 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -68,9 +68,7 @@ endif all-local: ../scripts/kernel-doc -html \ - libwebsockets.c \ - parsers.c \ - client-handshake.c \ + *.c \ libwebsockets.h \ > ../libwebsockets-api-doc.html diff --git a/lib/libwebsockets.c b/lib/libwebsockets.c index 4876099..188bb27 100644 --- a/lib/libwebsockets.c +++ b/lib/libwebsockets.c @@ -968,6 +968,17 @@ libwebsocket_context_destroy(struct libwebsocket_context *context) #endif } +/** + * libwebsocket_context_user() - get the user data associated with the whole context + * @context: Websocket context + * + * This returns the optional user allocation that can be attached to + * the context the sockets live in at context_create time. It's a way + * to let all sockets serviced in the same context share data without + * using globals statics in the user code. + */ + + LWS_EXTERN void * libwebsocket_context_user(struct libwebsocket_context *context) { diff --git a/libwebsockets-api-doc.html b/libwebsockets-api-doc.html index d910b2d..e240eed 100644 --- a/libwebsockets-api-doc.html +++ b/libwebsockets-api-doc.html @@ -1,3 +1,90 @@ +

libwebsocket_client_connect - Connect to another websocket server

+struct libwebsocket * +libwebsocket_client_connect +(struct libwebsocket_context * context, +const char * address, +int port, +int ssl_connection, +const char * path, +const char * host, +const char * origin, +const char * protocol, +int ietf_version_or_minus_one) +

Arguments

+
+
context +
Websocket context +
address +
Remote server address, eg, "myserver.com" +
port +
Port to connect to on the remote server, eg, 80 +
ssl_connection +
0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self +signed certs +
path +
Websocket path on server +
host +
Hostname on server +
origin +
Socket origin name +
protocol +
Comma-separated list of protocols being asked for from +the server, or just one. The server will pick the one it +likes best. +
ietf_version_or_minus_one +
-1 to ask to connect using the default, latest +protocol supported, or the specific protocol ordinal +
+

Description

+
+This function creates a connection to a remote server +
+
+

libwebsocket_client_connect_extended - Connect to another websocket server

+struct libwebsocket * +libwebsocket_client_connect_extended +(struct libwebsocket_context * context, +const char * address, +int port, +int ssl_connection, +const char * path, +const char * host, +const char * origin, +const char * protocol, +int ietf_version_or_minus_one, +void * userdata) +

Arguments

+
+
context +
Websocket context +
address +
Remote server address, eg, "myserver.com" +
port +
Port to connect to on the remote server, eg, 80 +
ssl_connection +
0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self +signed certs +
path +
Websocket path on server +
host +
Hostname on server +
origin +
Socket origin name +
protocol +
Comma-separated list of protocols being asked for from +the server, or just one. The server will pick the one it +likes best. +
ietf_version_or_minus_one +
-1 to ask to connect using the default, latest +protocol supported, or the specific protocol ordinal +
userdata +
Pre-allocated user data +
+

Description

+
+This function creates a connection to a remote server +
+

libwebsockets_hangup_on_client - Server calls to terminate client connection

void libwebsockets_hangup_on_client @@ -78,6 +165,23 @@ context. After calling this, any further use of the context is undefined.
+

libwebsocket_context_user - get the user data associated with the whole context

+LWS_EXTERN void * +libwebsocket_context_user +(struct libwebsocket_context * context) +

Arguments

+
+
context +
Websocket context +
+

Description

+
+This returns the optional user allocation that can be attached to +the context the sockets live in at context_create time. It's a way +to let all sockets serviced in the same context share data without +using globals statics in the user code. +
+

libwebsocket_service - Service any pending websocket activity

int libwebsocket_service @@ -390,6 +494,69 @@ log level defaults to "err" and "warn" contexts enabled only and emission on stderr.
+

libwebsocket_write - Apply protocol then write data to client

+int +libwebsocket_write +(struct libwebsocket * wsi, +unsigned char * buf, +size_t len, +enum libwebsocket_write_protocol protocol) +

Arguments

+
+
wsi +
Websocket instance (available from user callback) +
buf +
The data to send. For data being sent on a websocket +connection (ie, not default http), this buffer MUST have +LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE the pointer +and an additional LWS_SEND_BUFFER_POST_PADDING bytes valid +in the buffer after (buf + len). This is so the protocol +header and trailer data can be added in-situ. +
len +
Count of the data bytes in the payload starting from buf +
protocol +
Use LWS_WRITE_HTTP to reply to an http connection, and one +of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate +data on a websockets connection. Remember to allow the extra +bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT +are used. +
+

Description

+
+This function provides the way to issue data back to the client +for both http and websocket protocols. +

+In the case of sending using websocket protocol, be sure to allocate +valid storage before and after buf as explained above. This scheme +allows maximum efficiency of sending data and protocol in a single +packet while not burdening the user code with any protocol knowledge. +

+
+

libwebsockets_serve_http_file - Send a file back to the client using http

+int +libwebsockets_serve_http_file +(struct libwebsocket_context * context, +struct libwebsocket * wsi, +const char * file, +const char * content_type) +

Arguments

+
+
context +
libwebsockets context +
wsi +
Websocket instance (available from user callback) +
file +
The file to issue over http +
content_type +
The http content type, eg, text/html +
+

Description

+
+This function is intended to be called from the callback in response +to http requests from the client. It allows the callback to issue +local files down the http link in a single step. +
+

lws_frame_is_binary -

int lws_frame_is_binary @@ -429,93 +596,6 @@ when that is the case libwebsockets_remaining_packet_payload will return Many protocols won't care becuse their packets are always small.
-

libwebsocket_client_connect - Connect to another websocket server

-struct libwebsocket * -libwebsocket_client_connect -(struct libwebsocket_context * context, -const char * address, -int port, -int ssl_connection, -const char * path, -const char * host, -const char * origin, -const char * protocol, -int ietf_version_or_minus_one) -

Arguments

-
-
context -
Websocket context -
address -
Remote server address, eg, "myserver.com" -
port -
Port to connect to on the remote server, eg, 80 -
ssl_connection -
0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self -signed certs -
path -
Websocket path on server -
host -
Hostname on server -
origin -
Socket origin name -
protocol -
Comma-separated list of protocols being asked for from -the server, or just one. The server will pick the one it -likes best. -
ietf_version_or_minus_one -
-1 to ask to connect using the default, latest -protocol supported, or the specific protocol ordinal -
-

Description

-
-This function creates a connection to a remote server -
-
-

libwebsocket_client_connect_extended - Connect to another websocket server

-struct libwebsocket * -libwebsocket_client_connect_extended -(struct libwebsocket_context * context, -const char * address, -int port, -int ssl_connection, -const char * path, -const char * host, -const char * origin, -const char * protocol, -int ietf_version_or_minus_one, -void * userdata) -

Arguments

-
-
context -
Websocket context -
address -
Remote server address, eg, "myserver.com" -
port -
Port to connect to on the remote server, eg, 80 -
ssl_connection -
0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self -signed certs -
path -
Websocket path on server -
host -
Hostname on server -
origin -
Socket origin name -
protocol -
Comma-separated list of protocols being asked for from -the server, or just one. The server will pick the one it -likes best. -
ietf_version_or_minus_one -
-1 to ask to connect using the default, latest -protocol supported, or the specific protocol ordinal -
userdata -
Pre-allocated user data -
-

Description

-
-This function creates a connection to a remote server -
-

callback - User server actions

LWS_EXTERN int callback -- 2.7.4