11HTTP Parser
22===========
33
4- [ ![ Build Status] ( https://api. travis-ci.org/nodejs /http-parser.svg ?branch=master )] ( https://travis-ci.org/nodejs /http-parser )
4+ [ ![ Build Status] ( https://travis-ci.org/joyent /http-parser.png ?branch=master )] ( https://travis-ci.org/joyent /http-parser )
55
66This is a parser for HTTP messages written in C. It parses both requests and
77responses. The parser is designed to be used in performance HTTP
@@ -94,7 +94,7 @@ The Special Problem of Upgrade
9494------------------------------
9595
9696HTTP supports upgrading the connection to a different protocol. An
97- increasingly common example of this is the WebSocket protocol which sends
97+ increasingly common example of this is the Web Socket protocol which sends
9898a request like
9999
100100 GET /demo HTTP/1.1
@@ -106,8 +106,8 @@ a request like
106106
107107followed by non-HTTP data.
108108
109- (See [ RFC6455 ] ( https ://tools.ietf.org/html/rfc6455 ) for more information the
110- WebSocket protocol.)
109+ (See http ://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75
110+ information the Web Socket protocol.)
111111
112112To support this, the parser will treat this as a normal HTTP message without a
113113body, issuing both on_headers_complete and on_message_complete callbacks. However
@@ -137,69 +137,6 @@ There are two types of callbacks:
137137Callbacks must return 0 on success. Returning a non-zero value indicates
138138error to the parser, making it exit immediately.
139139
140- For cases where it is necessary to pass local information to/from a callback,
141- the ` http_parser ` object's ` data ` field can be used.
142- An example of such a case is when using threads to handle a socket connection,
143- parse a request, and then give a response over that socket. By instantiation
144- of a thread-local struct containing relevant data (e.g. accepted socket,
145- allocated memory for callbacks to write into, etc), a parser's callbacks are
146- able to communicate data between the scope of the thread and the scope of the
147- callback in a threadsafe manner. This allows http-parser to be used in
148- multi-threaded contexts.
149-
150- Example:
151- ```
152- typedef struct {
153- socket_t sock;
154- void* buffer;
155- int buf_len;
156- } custom_data_t;
157-
158-
159- int my_url_callback(http_parser* parser, const char *at, size_t length) {
160- /* access to thread local custom_data_t struct.
161- Use this access save parsed data for later use into thread local
162- buffer, or communicate over socket
163- */
164- parser->data;
165- ...
166- return 0;
167- }
168-
169- ...
170-
171- void http_parser_thread(socket_t sock) {
172- int nparsed = 0;
173- /* allocate memory for user data */
174- custom_data_t *my_data = malloc(sizeof(custom_data_t));
175-
176- /* some information for use by callbacks.
177- * achieves thread -> callback information flow */
178- my_data->sock = sock;
179-
180- /* instantiate a thread-local parser */
181- http_parser *parser = malloc(sizeof(http_parser));
182- http_parser_init(parser, HTTP_REQUEST); /* initialise parser */
183- /* this custom data reference is accessible through the reference to the
184- parser supplied to callback functions */
185- parser->data = my_data;
186-
187- http_parser_settings settings; / * set up callbacks */
188- settings.on_url = my_url_callback;
189-
190- /* execute parser */
191- nparsed = http_parser_execute(parser, &settings, buf, recved);
192-
193- ...
194- /* parsed information copied from callback.
195- can now perform action on data copied into thread-local memory from callbacks.
196- achieves callback -> thread information flow */
197- my_data->buffer;
198- ...
199- }
200-
201- ```
202-
203140In case you parse HTTP message in chunks (i.e. ` read() ` request line
204141from socket, parse, read half headers, parse, etc) your data callbacks
205142may be called more than once. Http-parser guarantees that data pointer is only
0 commit comments