add-kernel-doc-script-and-generated-api.txt

Signed-off-by: Andy Green <andy@warmcat.com>

Makefile

@@ -7,6 +7,8 @@ all:
 	
 	gcc $(CFLAGS) test-server.c
 	gcc  test-server.o ./libwebsockets.so -o test-server
+	./kernel-doc -text libwebsockets.c test-server.c > \
+		libwebsockets-api-doc.txt
 
 clean:
 	rm -f *.o *.so test-server

README-test-server

@@ -1,8 +1,8 @@
 Using test-server as a quickstart
 ---------------------------------
 
-# make
-# ./test-server
+$ make
+$ ./test-server
 
 should be enough to get a test server listening on port 7861.
 

libwebsockets-api-doc.txt

@@ -0,0 +1,137 @@
+Name:
+
+libwebsocket_create_server - Create the listening websockets server
+
+Synopsis:
+
+int libwebsocket_create_server (int port,
+                                int (*callback) (struct libwebsocket *, 			enum libwebsocket_callback_reasons, void *, size_t,
+                                int protocol);
+
+Arguments:
+
+port
+	Port to listen on
+
+callback
+	The callback in user code to perform actual serving
+
+protocol
+	Which version of the websockets protocol (currently 76)
+
+
+Description:
+
+This function forks to create the listening socket and takes care
+of all initialization in one step.
+
+The callback function is called for a handful of events including
+http requests coming in, websocket connections becoming
+established, and data arriving; it's also called periodically to allow
+async transmission.
+
+The server created is a simple http server by default; part of the
+websocket standard is upgrading this http connection to a websocket one.
+
+This allows the same server to provide files like scripts and favicon /
+images or whatever over http and dynamic data over websockets all in
+one place; they're all handled in the user callback.
+
+
+Name:
+
+libwebsocket_get_uri - Return the URI path being requested
+
+Synopsis:
+
+const char * libwebsocket_get_uri (struct libwebsocket * wsi);
+
+Arguments:
+
+wsi
+	Websocket instance
+
+
+Description:
+
+The user code can find out the local path being opened from this
+call, it's valid on HTTP or established websocket connections.
+If the client opened the connection with "http://127.0.0.1/xyz/abc.d"
+then this call will return a pointer to "/xyz/abc.d"
+
+
+Name:
+
+libwebsocket_write - Apply protocol then write data to client
+
+Synopsis:
+
+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.
+
+
+Name:
+
+libwebsockets_serve_http_file - Send a file back to the client using http
+
+Synopsis:
+
+int libwebsockets_serve_http_file (struct libwebsocket * wsi,
+                                   const char * file,
+                                   const char * content_type);
+
+Arguments:
+
+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.
+
+

libwebsockets.c

@@ -1,3 +1,8 @@
+/*
+ * libwebsockets Copyright 2010 Andy Green <andy@warmcat.com>
+ * licensed under GPL2
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

libwebsockets.h

@@ -18,34 +18,6 @@ enum libwebsocket_write_protocol {
 
 struct libwebsocket;
 
-/**
- * libwebsocket_callback() - User server actions
- * @wsi:	Opaque websocket instance pointer
- * @reason:	The reason for the call
- * @in:		Pointer used for some callback reasons
- * @len:	Length set for some callback reasons
- * 
- * 	This callback is the way the user controls what is served.  All the
- * 	protocol detail is hidden and handled by the library.
- * 
- * 	LWS_CALLBACK_ESTABLISHED:  after successful websocket handshake
- * 	LWS_CALLBACK_CLOSED: when the websocket session ends
- * 	LWS_CALLBACK_SEND: opportunity to send to client (you would use
- * 				libwebsocket_write() taking care about the
- * 				special buffer requirements
- * 	LWS_CALLBACK_RECEIVE: data has appeared for the server, it can be
- * 				found at *in and is len bytes long
- * 	LWS_CALLBACK_HTTP: an http request has come from a client that is not
- * 				asking to upgrade the connection to a websocket
- * 				one.  This is a chance to serve http content,
- * 				for example, to send a script to the client
- * 				which will then open the websockets connection.
- * 				libwebsocket_get_uri() lets you find out the
- * 				URI path requested and 
- * 				libwebsockets_serve_http_file() makes it very
- * 				simple to send back a file to the client.
- */
-
 extern int libwebsocket_create_server(int port,
 		  int (*callback)(struct libwebsocket *wsi,
 				  enum libwebsocket_callback_reasons reason,

test-server.c

@@ -9,18 +9,40 @@
 /*
  * libwebsocket Example server  Copyright 2010 Andy Green <andy@warmcat.com>
  * 
+ * Licensed under GPL2
+ * 
  * Shows how to use libwebsocket 
  */
 
 static int port = 7681;
 static int ws_protocol = 76;
 
-/*
- * libwebsockets needs this one callback in your server application, it's
- * called for a handful of different reasons during the connection lifecycle.
+ /**
+ * libwebsocket_callback() - User server actions
+ * @wsi:	Opaque websocket instance pointer
+ * @reason:	The reason for the call
+ * @in:		Pointer used for some callback reasons
+ * @len:	Length set for some callback reasons
  * 
- * All the serving actions occur in the callback but the websocket protocol
- * stuff is already handled by the library.
+ * 	This callback is the way the user controls what is served.  All the
+ * 	protocol detail is hidden and handled by the library.
+ * 
+ * 	LWS_CALLBACK_ESTABLISHED:  after successful websocket handshake
+ * 	LWS_CALLBACK_CLOSED: when the websocket session ends
+ * 	LWS_CALLBACK_SEND: opportunity to send to client (you would use
+ * 				libwebsocket_write() taking care about the
+ * 				special buffer requirements
+ * 	LWS_CALLBACK_RECEIVE: data has appeared for the server, it can be
+ * 				found at *in and is len bytes long
+ * 	LWS_CALLBACK_HTTP: an http request has come from a client that is not
+ * 				asking to upgrade the connection to a websocket
+ * 				one.  This is a chance to serve http content,
+ * 				for example, to send a script to the client
+ * 				which will then open the websockets connection.
+ * 				libwebsocket_get_uri() lets you find out the
+ * 				URI path requested and 
+ * 				libwebsockets_serve_http_file() makes it very
+ * 				simple to send back a file to the client.
  */
 
 static int websocket_callback(struct libwebsocket * wsi,