1 /*
2     This file is part of libmicrospdy
3     Copyright Copyright (C) 2012, 2013 Christian Grothoff
4 
5     This program is free software: you can redistribute it and/or modify
6     it under the terms of the GNU General Public License as published by
7     the Free Software Foundation, either version 3 of the License, or
8     (at your option) any later version.
9 
10     This program is distributed in the hope that it will be useful,
11     but WITHOUT ANY WARRANTY; without even the implied warranty of
12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13     GNU General Public License for more details.
14 
15     You should have received a copy of the GNU General Public License
16     along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 /**
20  * @file microspdy.h
21  * @brief public interface to libmicrospdy
22  * @author Andrey Uzunov
23  * @author Christian Grothoff
24  *
25  * All symbols defined in this header start with SPDY_.  libmisrospdy is a small
26  * SPDY daemon library. The application can start multiple daemons
27  * and they are independent.<p>
28  *
29  * The header file defines various constants used by the SPDY and the HTTP protocol.
30  * This does not mean that the lib actually interprets all of these
31  * values. Not everything is implemented. The provided constants are exported as a convenience
32  * for users of the library.  The lib does not verify that provided
33  * HTTP headers and if their values conform to the SPDY protocol,
34  * it only checks if the required headers for the SPDY requests and
35  * responses are provided.<p>
36  *
37  * The library uses just a single thread.<p>
38  *
39  * Before including "microspdy.h" you should add the necessary
40  * includes to define the types used in this file (which headers are needed may
41  * depend on your platform; for possible suggestions consult
42  * "platform.h" in the libmicrospdy distribution).<p>
43  *
44  * All of the functions returning SPDY_YES/SPDY_NO return
45  * SPDY_INPUT_ERROR when any of the parameters are invalid, e.g.
46  * required parameter is NULL.<p>
47  *
48  * The library does not check if anything at the application layer --
49  * requests and responses -- is correct. For example, it
50  * is up to the user to check if a client is sending HTTP body but the
51  * method is GET.<p>
52  *
53  * The SPDY flow control is just partially implemented: the receiving
54  * window is updated, and the client is notified, to prevent a client
55  * from stop sending POST body data, for example.
56  */
57 #ifndef SPDY_MICROSPDY_H
58 #define SPDY_MICROSPDY_H
59 
60 #include <zlib.h>
61 #include <stdbool.h>
62 
63 /* While we generally would like users to use a configure-driven
64    build process which detects which headers are present and
65    hence works on any platform, we use "standard" includes here
66    to build out-of-the-box for beginning users on common systems.
67 
68    Once you have a proper build system and go for more exotic
69    platforms, you should define MHD_PLATFORM_H in some header that
70    you always include *before* "microhttpd.h".  Then the following
71    "standard" includes won't be used (which might be a good
72    idea, especially on platforms where they do not exist). */
73 #ifndef MHD_PLATFORM_H
74 #include <unistd.h>
75 #include <stdarg.h>
76 #include <stdint.h>
77 #ifdef __MINGW32__
78 #include <ws2tcpip.h>
79 #else
80 #include <sys/time.h>
81 #include <sys/types.h>
82 #include <sys/socket.h>
83 #endif
84 #endif
85 
86 #ifndef _MHD_EXTERN
87 #define _MHD_EXTERN extern
88 #endif
89 
90 /**
91  * return code for "YES".
92  */
93 #define SPDY_YES 1
94 
95 /**
96  * return code for "NO".
97  */
98 #define SPDY_NO 0
99 
100 /**
101  * return code for error when input parameters are wrong. To be returned
102  * only by functions which return int. The others will return NULL on
103  * input error.
104  */
105 #define SPDY_INPUT_ERROR -1
106 
107 /**
108  * SPDY version supported by the lib.
109  */
110 #define SPDY_VERSION 3
111 
112 /**
113  * The maximum allowed size (without 8 byte headers) of
114  * SPDY frames (value length) is 8192. The lib will accept and
115  * send frames with length at most this value here.
116  */
117 #define SPDY_MAX_SUPPORTED_FRAME_SIZE 8192
118 
119 /**
120  * HTTP response codes.
121  */
122 #define SPDY_HTTP_CONTINUE 100
123 #define SPDY_HTTP_SWITCHING_PROTOCOLS 101
124 #define SPDY_HTTP_PROCESSING 102
125 
126 #define SPDY_HTTP_OK 200
127 #define SPDY_HTTP_CREATED 201
128 #define SPDY_HTTP_ACCEPTED 202
129 #define SPDY_HTTP_NON_AUTHORITATIVE_INFORMATION 203
130 #define SPDY_HTTP_NO_CONTENT 204
131 #define SPDY_HTTP_RESET_CONTENT 205
132 #define SPDY_HTTP_PARTIAL_CONTENT 206
133 #define SPDY_HTTP_MULTI_STATUS 207
134 
135 #define SPDY_HTTP_MULTIPLE_CHOICES 300
136 #define SPDY_HTTP_MOVED_PERMANENTLY 301
137 #define SPDY_HTTP_FOUND 302
138 #define SPDY_HTTP_SEE_OTHER 303
139 #define SPDY_HTTP_NOT_MODIFIED 304
140 #define SPDY_HTTP_USE_PROXY 305
141 #define SPDY_HTTP_SWITCH_PROXY 306
142 #define SPDY_HTTP_TEMPORARY_REDIRECT 307
143 
144 #define SPDY_HTTP_BAD_REQUEST 400
145 #define SPDY_HTTP_UNAUTHORIZED 401
146 #define SPDY_HTTP_PAYMENT_REQUIRED 402
147 #define SPDY_HTTP_FORBIDDEN 403
148 #define SPDY_HTTP_NOT_FOUND 404
149 #define SPDY_HTTP_METHOD_NOT_ALLOWED 405
150 #define SPDY_HTTP_METHOD_NOT_ACCEPTABLE 406
151 #define SPDY_HTTP_PROXY_AUTHENTICATION_REQUIRED 407
152 #define SPDY_HTTP_REQUEST_TIMEOUT 408
153 #define SPDY_HTTP_CONFLICT 409
154 #define SPDY_HTTP_GONE 410
155 #define SPDY_HTTP_LENGTH_REQUIRED 411
156 #define SPDY_HTTP_PRECONDITION_FAILED 412
157 #define SPDY_HTTP_REQUEST_ENTITY_TOO_LARGE 413
158 #define SPDY_HTTP_REQUEST_URI_TOO_LONG 414
159 #define SPDY_HTTP_UNSUPPORTED_MEDIA_TYPE 415
160 #define SPDY_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416
161 #define SPDY_HTTP_EXPECTATION_FAILED 417
162 #define SPDY_HTTP_UNPROCESSABLE_ENTITY 422
163 #define SPDY_HTTP_LOCKED 423
164 #define SPDY_HTTP_FAILED_DEPENDENCY 424
165 #define SPDY_HTTP_UNORDERED_COLLECTION 425
166 #define SPDY_HTTP_UPGRADE_REQUIRED 426
167 #define SPDY_HTTP_NO_RESPONSE 444
168 #define SPDY_HTTP_RETRY_WITH 449
169 #define SPDY_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450
170 #define SPDY_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451
171 
172 #define SPDY_HTTP_INTERNAL_SERVER_ERROR 500
173 #define SPDY_HTTP_NOT_IMPLEMENTED 501
174 #define SPDY_HTTP_BAD_GATEWAY 502
175 #define SPDY_HTTP_SERVICE_UNAVAILABLE 503
176 #define SPDY_HTTP_GATEWAY_TIMEOUT 504
177 #define SPDY_HTTP_HTTP_VERSION_NOT_SUPPORTED 505
178 #define SPDY_HTTP_VARIANT_ALSO_NEGOTIATES 506
179 #define SPDY_HTTP_INSUFFICIENT_STORAGE 507
180 #define SPDY_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
181 #define SPDY_HTTP_NOT_EXTENDED 510
182 
183 /**
184  * HTTP headers are used in SPDY, but all of them MUST be lowercase.
185  * Some are not valid in SPDY and MUST not be used
186  */
187 #define SPDY_HTTP_HEADER_ACCEPT "accept"
188 #define SPDY_HTTP_HEADER_ACCEPT_CHARSET "accept-charset"
189 #define SPDY_HTTP_HEADER_ACCEPT_ENCODING "accept-encoding"
190 #define SPDY_HTTP_HEADER_ACCEPT_LANGUAGE "accept-language"
191 #define SPDY_HTTP_HEADER_ACCEPT_RANGES "accept-ranges"
192 #define SPDY_HTTP_HEADER_AGE "age"
193 #define SPDY_HTTP_HEADER_ALLOW "allow"
194 #define SPDY_HTTP_HEADER_AUTHORIZATION "authorization"
195 #define SPDY_HTTP_HEADER_CACHE_CONTROL "cache-control"
196 /* Connection header is forbidden in SPDY */
197 #define SPDY_HTTP_HEADER_CONNECTION "connection"
198 #define SPDY_HTTP_HEADER_CONTENT_ENCODING "content-encoding"
199 #define SPDY_HTTP_HEADER_CONTENT_LANGUAGE "content-language"
200 #define SPDY_HTTP_HEADER_CONTENT_LENGTH "content-length"
201 #define SPDY_HTTP_HEADER_CONTENT_LOCATION "content-location"
202 #define SPDY_HTTP_HEADER_CONTENT_MD5 "content-md5"
203 #define SPDY_HTTP_HEADER_CONTENT_RANGE "content-range"
204 #define SPDY_HTTP_HEADER_CONTENT_TYPE "content-type"
205 #define SPDY_HTTP_HEADER_COOKIE "cookie"
206 #define SPDY_HTTP_HEADER_DATE "date"
207 #define SPDY_HTTP_HEADER_ETAG "etag"
208 #define SPDY_HTTP_HEADER_EXPECT "expect"
209 #define SPDY_HTTP_HEADER_EXPIRES "expires"
210 #define SPDY_HTTP_HEADER_FROM "from"
211 /* Host header is forbidden in SPDY */
212 #define SPDY_HTTP_HEADER_HOST "host"
213 #define SPDY_HTTP_HEADER_IF_MATCH "if-match"
214 #define SPDY_HTTP_HEADER_IF_MODIFIED_SINCE "if-modified-since"
215 #define SPDY_HTTP_HEADER_IF_NONE_MATCH "if-none-match"
216 #define SPDY_HTTP_HEADER_IF_RANGE "if-range"
217 #define SPDY_HTTP_HEADER_IF_UNMODIFIED_SINCE "if-unmodified-since"
218 /* Keep-Alive header is forbidden in SPDY */
219 #define SPDY_HTTP_HEADER_KEEP_ALIVE "keep-alive"
220 #define SPDY_HTTP_HEADER_LAST_MODIFIED "last-modified"
221 #define SPDY_HTTP_HEADER_LOCATION "location"
222 #define SPDY_HTTP_HEADER_MAX_FORWARDS "max-forwards"
223 #define SPDY_HTTP_HEADER_PRAGMA "pragma"
224 #define SPDY_HTTP_HEADER_PROXY_AUTHENTICATE "proxy-authenticate"
225 #define SPDY_HTTP_HEADER_PROXY_AUTHORIZATION "proxy-authorization"
226 /* Proxy-Connection header is forbidden in SPDY */
227 #define SPDY_HTTP_HEADER_PROXY_CONNECTION "proxy-connection"
228 #define SPDY_HTTP_HEADER_RANGE "range"
229 #define SPDY_HTTP_HEADER_REFERER "referer"
230 #define SPDY_HTTP_HEADER_RETRY_AFTER "retry-after"
231 #define SPDY_HTTP_HEADER_SERVER "server"
232 #define SPDY_HTTP_HEADER_SET_COOKIE "set-cookie"
233 #define SPDY_HTTP_HEADER_SET_COOKIE2 "set-cookie2"
234 #define SPDY_HTTP_HEADER_TE "te"
235 #define SPDY_HTTP_HEADER_TRAILER "trailer"
236 /* Transfer-Encoding header is forbidden in SPDY */
237 #define SPDY_HTTP_HEADER_TRANSFER_ENCODING "transfer-encoding"
238 #define SPDY_HTTP_HEADER_UPGRADE "upgrade"
239 #define SPDY_HTTP_HEADER_USER_AGENT "user-agent"
240 #define SPDY_HTTP_HEADER_VARY "vary"
241 #define SPDY_HTTP_HEADER_VIA "via"
242 #define SPDY_HTTP_HEADER_WARNING "warning"
243 #define SPDY_HTTP_HEADER_WWW_AUTHENTICATE "www-authenticate"
244 
245 /**
246  * HTTP versions (a value must be provided in SPDY requests/responses).
247  */
248 #define SPDY_HTTP_VERSION_1_0 "HTTP/1.0"
249 #define SPDY_HTTP_VERSION_1_1 "HTTP/1.1"
250 
251 /**
252  * HTTP methods
253  */
254 #define SPDY_HTTP_METHOD_CONNECT "CONNECT"
255 #define SPDY_HTTP_METHOD_DELETE "DELETE"
256 #define SPDY_HTTP_METHOD_GET "GET"
257 #define SPDY_HTTP_METHOD_HEAD "HEAD"
258 #define SPDY_HTTP_METHOD_OPTIONS "OPTIONS"
259 #define SPDY_HTTP_METHOD_POST "POST"
260 #define SPDY_HTTP_METHOD_PUT "PUT"
261 #define SPDY_HTTP_METHOD_TRACE "TRACE"
262 
263 /**
264  * HTTP POST encodings, see also
265  * http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4
266  */
267 #define SPDY_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
268 #define SPDY_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"
269 
270 
271 /**
272  * Handle for the daemon (listening on a socket).
273  */
274 struct SPDY_Daemon;
275 
276 
277 /**
278  * Handle for a SPDY session/connection.
279  */
280 struct SPDY_Session;
281 
282 
283 /**
284  * Handle for a SPDY request sent by a client. The structure has pointer
285  * to the session's handler
286  */
287 struct SPDY_Request;
288 
289 
290 /**
291  * Handle for a response containing HTTP headers and data to be sent.
292  * The structure has pointer to the session's handler
293  * for this response.
294  */
295 struct SPDY_Response;
296 
297 
298 /**
299  * Collection of tuples of an HTTP header and values used in requests
300  * and responses.
301  */
302 struct SPDY_NameValue;
303 
304 
305 /**
306  * Collection of tuples of a SPDY setting ID, value
307  * and flags used to control the sessions.
308  */
309 struct SPDY_Settings;
310 
311 
312 /**
313  * SPDY IO sybsystem flags used by SPDY_init() and SPDY_deinit().<p>
314  *
315  * The values are used internally as flags, that is why they must be
316  * powers of 2.
317  */
318 enum SPDY_IO_SUBSYSTEM
319 {
320 
321   /**
322    * No subsystem. For internal use.
323    */
324   SPDY_IO_SUBSYSTEM_NONE = 0,
325 
326   /**
327    * Default TLS implementation provided by openSSL/libssl.
328    */
329   SPDY_IO_SUBSYSTEM_OPENSSL = 1,
330 
331   /**
332    * No TLS is used.
333    */
334   SPDY_IO_SUBSYSTEM_RAW = 2
335 };
336 
337 
338 /**
339  * SPDY daemon options. Passed in the varargs portion of
340  * SPDY_start_daemon to customize the daemon. Each option must
341  * be followed by a value of a specific type.<p>
342  *
343  * The values are used internally as flags, that is why they must be
344  * powers of 2.
345  */
346 enum SPDY_DAEMON_OPTION
347 {
348 
349   /**
350    * No more options / last option.  This is used
351    * to terminate the VARARGs list.
352    */
353   SPDY_DAEMON_OPTION_END = 0,
354 
355   /**
356    * Set a custom timeout for all connections.  Must be followed by
357    * a number of seconds, given as an 'unsigned int'.  Use
358    * zero for no timeout.
359    */
360   SPDY_DAEMON_OPTION_SESSION_TIMEOUT = 1,
361 
362   /**
363    * Bind daemon to the supplied sockaddr. This option must be
364    * followed by a 'struct sockaddr *'.  The 'struct sockaddr*'
365    * should point to a 'struct sockaddr_in6' or to a
366    * 'struct sockaddr_in'.
367    */
368   SPDY_DAEMON_OPTION_SOCK_ADDR = 2,
369 
370   /**
371    * Flags for the daemon. Must be followed by a SPDY_DAEMON_FLAG value
372    * which is the result of bitwise OR of desired flags.
373    */
374   SPDY_DAEMON_OPTION_FLAGS = 4,
375 
376   /**
377    * IO subsystem type used by daemon and all its sessions. If not set,
378    * TLS provided by openssl is used. Must be followed by a
379    * SPDY_IO_SUBSYSTEM value.
380    */
381   SPDY_DAEMON_OPTION_IO_SUBSYSTEM = 8,
382 
383   /**
384    * Maximum number of frames to be written to the socket at once. The
385    * library tries to send max_num_frames in a single call to SPDY_run
386    * for a single session. This means no requests can be received nor
387    * other sessions can send data as long the current one has enough
388    * frames to send and there is no error on writing. Thus, a big value
389    * will affect the performance. Small value gives fairnes for sessions.
390    * Must be followed by a positive integer (uin32_t). If not set, the
391    * default value 10 will be used.
392    */
393   SPDY_DAEMON_OPTION_MAX_NUM_FRAMES = 16
394 };
395 
396 
397 /**
398  * Flags for starting SPDY daemon. They are used to set some settings
399  * for the daemon, which do not require values.
400  */
401 enum SPDY_DAEMON_FLAG
402 {
403   /**
404    * No flags selected.
405    */
406   SPDY_DAEMON_FLAG_NO = 0,
407 
408   /**
409    * The server will bind only on IPv6 addresses. If the flag is set and
410    * the daemon is provided with IPv4 address or IPv6 is not supported,
411    * starting daemon will fail.
412    */
413   SPDY_DAEMON_FLAG_ONLY_IPV6 = 1,
414 
415   /**
416    * All sessions' sockets will be set with TCP_NODELAY if the flag is
417    * used. Option considered only by SPDY_IO_SUBSYSTEM_RAW.
418    */
419   SPDY_DAEMON_FLAG_NO_DELAY = 2
420 };
421 
422 
423 /**
424  * SPDY settings IDs sent by both client and server in SPDY SETTINGS frame.
425  * They affect the whole SPDY session. Defined in SPDY Protocol - Draft 3.
426  */
427 enum SPDY_SETTINGS
428 {
429 
430   /**
431    * Allows the sender to send its expected upload bandwidth on this
432    * channel. This number is an estimate. The value should be the
433    * integral number of kilobytes per second that the sender predicts
434    * as an expected maximum upload channel capacity.
435    */
436   SPDY_SETTINGS_UPLOAD_BANDWIDTH = 1,
437 
438   /**
439    * Allows the sender to send its expected download bandwidth on this
440    * channel. This number is an estimate. The value should be the
441    * integral number of kilobytes per second that the sender predicts as
442    * an expected maximum download channel capacity.
443    */
444   SPDY_SETTINGS_DOWNLOAD_BANDWIDTH = 2,
445 
446   /**
447    * Allows the sender to send its expected round-trip-time on this
448    * channel. The round trip time is defined as the minimum amount of
449    * time to send a control frame from this client to the remote and
450    * receive a response. The value is represented in milliseconds.
451    */
452   SPDY_SETTINGS_ROUND_TRIP_TIME = 3,
453 
454   /**
455    * Allows the sender to inform the remote endpoint the maximum number
456    * of concurrent streams which it will allow. By default there is no
457    * limit. For implementors it is recommended that this value be no
458    * smaller than 100.
459    */
460   SPDY_SETTINGS_MAX_CONCURRENT_STREAMS = 4,
461 
462   /**
463    * Allows the sender to inform the remote endpoint of the current TCP
464    * CWND value.
465    */
466   SPDY_SETTINGS_CURRENT_CWND = 5,
467 
468   /**
469    * Allows the sender to inform the remote endpoint the retransmission
470    * rate (bytes retransmitted / total bytes transmitted).
471    */
472   SPDY_SETTINGS_DOWNLOAD_RETRANS_RATE = 6,
473 
474   /**
475    * Allows the sender to inform the remote endpoint the initial window
476    * size (in bytes) for new streams.
477    */
478   SPDY_SETTINGS_INITIAL_WINDOW_SIZE = 7,
479 
480   /**
481    * Allows the server to inform the client if the new size of the
482    * client certificate vector.
483    */
484   SPDY_SETTINGS_CLIENT_CERTIFICATE_VECTOR_SIZE = 8
485 };
486 
487 
488 /**
489  * Flags for each individual SPDY setting in the SPDY SETTINGS frame.
490  * They affect only one setting to which they are set.
491  * Defined in SPDY Protocol - Draft 3.
492  */
493 enum SPDY_FLAG_SETTINGS
494 {
495 
496   /**
497    * When set, the sender of this SETTINGS frame is requesting that the
498    * recipient persist the ID/Value and return it in future SETTINGS
499    * frames sent from the sender to this recipient. Because persistence
500    * is only implemented on the client, this flag is only sent by the
501    * server.
502    */
503   SPDY_FLAG_SETTINGS_PERSIST_VALUE = 1,
504 
505   /**
506    * When set, the sender is notifying the recipient that this ID/Value
507    * pair was previously sent to the sender by the recipient with the
508    * #SPDY_FLAG_SETTINGS_PERSIST_VALUE, and the sender is returning it.
509    * Because persistence is only implemented on the client, this flag is
510    * only sent by the client.
511    */
512   SPDY_FLAG_SETTINGS_PERSISTED = 2
513 };
514 
515 
516 /**
517  * Flag associated with a whole SPDY SETTINGS frame. Affect all the
518  * settings in the frame. Defined in SPDY Protocol - Draft 3.
519  */
520 enum SPDY_FLAG_SETTINGS_FRAME
521 {
522 
523   /**
524    * When set, the client should clear any previously persisted SETTINGS
525    * ID/Value pairs. If this frame contains ID/Value pairs with the
526    * #SPDY_FLAG_SETTINGS_PERSIST_VALUE set, then the client will first
527    * clear its existing, persisted settings, and then persist the values
528    * with the flag set which are contained within this frame. Because
529    * persistence is only implemented on the client, this flag can only
530    * be used when the sender is the server.
531    */
532   SPDY_FLAG_SETTINGS_CLEAR_SETTINGS = 1
533 };
534 
535 
536 /**
537  * SPDY settings function options. Passed in the varargs portion of
538  * SPDY_SettingsReceivedCallback and SPDY_send_settings to customize
539  * more the settings handling. Each option must
540  * be followed by a value of a specific type.<p>
541  *
542  * The values are used internally as flags, that is why they must be
543  * powers of 2.
544  */
545 enum SPDY_SETTINGS_OPTION
546 {
547 
548   /**
549    * No more options / last option.  This is used
550    * to terminate the VARARGs list.
551    */
552   SPDY_SETTINGS_OPTION_END = 0
553 };
554 
555 
556 /**
557  * Used as a parameter for SPDY_ResponseResultCallback and shows if the
558  * response was actually written to the TLS socket or discarded by the
559  * lib for any reason (and respectively the reason).
560  */
561 enum SPDY_RESPONSE_RESULT
562 {
563 
564   /**
565    * The lib has written the full response to the TLS socket.
566    */
567   SPDY_RESPONSE_RESULT_SUCCESS = 0,
568 
569   /**
570    * The session is being closed, so the data is being discarded
571    */
572   SPDY_RESPONSE_RESULT_SESSION_CLOSED = 1,
573 
574   /**
575    * The stream for this response has been closed. May happen when the
576    * sender had sent first SYN_STREAM and after that RST_STREAM.
577    */
578   SPDY_RESPONSE_RESULT_STREAM_CLOSED = 2
579 };
580 
581 
582 /**
583  * Callback for serious error condition. The default action is to print
584  * an error message and abort().
585  *
586  * @param cls user specified value
587  * @param file where the error occured
588  * @param line where the error occured
589  * @param reason error details message, may be NULL
590  */
591 typedef void
592 (*SPDY_PanicCallback) (void * cls,
593                        const char *file,
594                        unsigned int line,
595                        const char *reason);
596 
597 
598 /**
599  * Callback for new SPDY session established by a client. Called
600  * immediately after the TCP connection was established.
601  *
602  * @param cls client-defined closure
603  * @param session handler for the new SPDY session
604  */
605 typedef void
606 (*SPDY_NewSessionCallback) (void * cls,
607                             struct SPDY_Session * session);
608 
609 
610 /**
611  * Callback for closed session. Called after the TCP connection was
612  * closed. In this callback function the user has the last
613  * chance to access the SPDY_Session structure. After that the latter
614  * will be cleaned!
615  *
616  * @param cls client-defined closure
617  * @param session handler for the closed SPDY session
618  * @param by_client #SPDY_YES if the session close was initiated by the
619  * 					client;
620  * 		    #SPDY_NO if closed by the server
621  */
622 typedef void
623 (*SPDY_SessionClosedCallback) (void *cls,
624                                struct SPDY_Session *session,
625                                int by_client);
626 
627 
628 /**
629  * Iterator over name-value pairs.
630  *
631  * @param cls client-defined closure
632  * @param name of the pair
633  * @param value of the pair
634  * @return #SPDY_YES to continue iterating,
635  *         #SPDY_NO to abort the iteration
636  */
637 typedef int
638 (*SPDY_NameValueIterator) (void *cls,
639                            const char *name,
640                            const char * const * value,
641                            int num_values);
642 
643 
644 /**
645  * Callback for received SPDY request. The functions is called whenever
646  * a reqest comes, but will also be called if more headers/trailers are
647  * received.
648  *
649  * @param cls client-defined closure
650  * @param request handler. The request object is required for
651  * 			sending responses.
652  * @param priority of the SPDY stream which the request was
653  * 			sent over
654  * @param method HTTP method
655  * @param path HTTP path
656  * @param version HTTP version just like in HTTP request/response:
657  * 			"HTTP/1.0" or "HTTP/1.1" currently
658  * @param host called host as in HTTP
659  * @param scheme used ("http" or "https"). In SPDY 3 it is only "https".
660  * @param headers other HTTP headers from the request
661  * @param more a flag saying if more data related to the request is
662  *        expected to be received. HTTP body may arrive (e.g. POST data);
663  *        then SPDY_NewDataCallback will be called for the connection.
664  *        It is also possible that more headers/trailers arrive;
665  *        then the same callback will be invoked. The user should detect
666  *        that it is not the first invocation of the function for that
667  *        request.
668  */
669 typedef void
670 (*SPDY_NewRequestCallback) (void *cls,
671                             struct SPDY_Request *request,
672                             uint8_t priority,
673                             const char *method,
674                             const char *path,
675                             const char *version,
676                             const char *host,
677                             const char *scheme,
678                             struct SPDY_NameValue *headers,
679                             bool more);
680 
681 
682 /**
683  * Callback for received new data chunk (HTTP body) from a given
684  * request (e.g. POST data).
685  *
686  * @param cls client-defined closure
687  * @param request handler
688  * @param buf data chunk from the POST data
689  * @param size the size of the data chunk 'buf' in bytes. Note that it
690  *             may be 0.
691  * @param more false if this is the last chunk from the data. Note:
692  *             true does not mean that more data will come, exceptional
693  *             situation is possible
694  * @return #SPDY_YES to continue calling the function,
695  *         #SPDY_NO to stop calling the function for this request
696  */
697 typedef int
698 (*SPDY_NewDataCallback) (void *cls,
699                          struct SPDY_Request *request,
700                          const void *buf,
701                          size_t size,
702                          bool more);
703 // How about passing POST encoding information
704 // here as well?
705 //TODO
706 
707 
708 /**
709  * Callback to be used with SPDY_build_response_with_callback. The
710  * callback will be called when the lib wants to write to the TLS socket.
711  * The application should provide the data to be sent.
712  *
713  * @param cls client-defined closure
714  * @param max maximum number of bytes that are allowed to be written
715  * 			to the buffer.
716  * @param more true if more data will be sent (i.e. the function must
717  * 				be calleed again),
718  *             false if this is the last chunk, the lib will close
719  * 				the stream
720  * @return number of bytes written to buffer. On error the call MUST
721  * 			return value less than 0 to indicate the library.
722  */
723 typedef ssize_t
724 (*SPDY_ResponseCallback) (void *cls,
725                           void *buffer,
726                           size_t max,
727                           bool *more);
728 
729 
730 /**
731  * Callback to be called when the last bytes from the response was sent
732  * to the client or when the response was discarded from the lib. This
733  * callback is a very good place to discard the request and the response
734  * objects, if they will not be reused (e.g., sending the same response
735  * again). If the stream is closed it is safe to discard the request
736  * object.
737  *
738  * @param cls client-defined closure
739  * @param response handler to the response that was just sent
740  * @param request handler to the request for which the response was sent
741  * @param status shows if actually the response was sent or it was
742  * 			discarded by the lib for any reason (e.g., closing session,
743  * 			closing stream, stopping daemon, etc.). It is possible that
744  * 			status indicates an error but parts of the response headers
745  * 			and/or body (in one
746  * 			or several frames) were already sent to the client.
747  * @param streamopened indicates if the the stream for this request/
748  * 			response pair is still opened. If yes, the server may want
749  * 			to use SPDY push to send something additional to the client
750  * 			and/or close the stream.
751  */
752 typedef void
753 (*SPDY_ResponseResultCallback) (void * cls,
754                                 struct SPDY_Response *response,
755                                 struct SPDY_Request *request,
756                                 enum SPDY_RESPONSE_RESULT status,
757                                 bool streamopened);
758 
759 
760 /**
761  * Callback to notify when SPDY ping response is received.
762  *
763  * @param session handler for which the ping request was sent
764  * @param rtt the timespan between sending ping request and receiving it
765  * 			from the library
766  */
767 typedef void
768 (*SPDY_PingCallback) (void * cls,
769                       struct SPDY_Session *session,
770                       struct timeval *rtt);
771 
772 
773 /**
774  * Iterator over settings ID/Value/Flags tuples.
775  *
776  * @param cls client-defined closure
777  * @param id SPDY settings ID
778  * @param value value for this setting
779  * @param flags flags for this tuple; use
780  * 			`enum SPDY_FLAG_SETTINGS`
781  * @return #SPDY_YES to continue iterating,
782  *         #SPDY_NO to abort the iteration
783  */
784 typedef int
785 (*SPDY_SettingsIterator) (void *cls,
786                           enum SPDY_SETTINGS id,
787                           int32_t value,
788                           uint8_t flags);
789 
790 
791 /**
792  * Callback to notify when SPDY SETTINGS are received from the client.
793  *
794  * @param session handler for which settings are received
795  * @param settings ID/value/flags tuples of the settings
796  * @param flags for the whole settings frame; use
797  * 			enum SPDY_FLAG_SETTINGS_FRAME
798  * @param ... list of options (type-value pairs,
799  *        terminated with #SPDY_SETTINGS_OPTION_END).
800  */
801 typedef void
802 (*SPDY_SettingsReceivedCallback) (struct SPDY_Session *session,
803                                   struct SPDY_Settings *settings,
804                                   uint8_t flags,
805                                   ...);
806 
807 
808 /* Global functions for the library */
809 
810 
811 /**
812  * Init function for the whole library. It MUST be called before any
813  * other function of the library to initialize things like TLS context
814  * and possibly other stuff needed by the lib. Currently the call
815  * always returns #SPDY_YES.
816  *
817  * @param io_subsystem the IO subsystem that will
818  *        be initialized. Several can be used with bitwise OR. If no
819  *        parameter is set, the default openssl subsystem will be used.
820  * @return #SPDY_YES if the library was correctly initialized and its
821  * 			functions can be used now;
822  * 			#SPDY_NO on error
823  */
824 _MHD_EXTERN int
825 (SPDY_init) (enum SPDY_IO_SUBSYSTEM io_subsystem, ...);
826 #define SPDY_init() SPDY_init (SPDY_IO_SUBSYSTEM_OPENSSL)
827 
828 
829 /**
830  * Deinit function for the whole lib. It can be called after finishing
831  * using the library. It frees and cleans up resources allocated in
832  * SPDY_init. Currently the function does not do anything.
833  */
834 _MHD_EXTERN void
835 SPDY_deinit (void);
836 
837 
838 /**
839  * Sets the global error handler to a different implementation. "cb"
840  * will only be called in the case of typically fatal, serious
841  * internal consistency issues.  These issues should only arise in the
842  * case of serious memory corruption or similar problems with the
843  * architecture as well as failed assertions.  While "cb" is allowed to
844  * return and the lib will then try to continue, this is never safe.
845  *
846  * The default implementation that is used if no panic function is set
847  * simply prints an error message and calls "abort".  Alternative
848  * implementations might call "exit" or other similar functions.
849  *
850  * @param cb new error handler
851  * @param cls passed to error handler
852  */
853 _MHD_EXTERN void
854 SPDY_set_panic_func (SPDY_PanicCallback cb,
855                      void *cls);
856 
857 
858 /* Daemon functions */
859 
860 
861 /**
862  * Start a SPDY webserver on the given port.
863  *
864  * @param port to bind to. The value is ignored if address structure
865  * 			is passed as daemon option
866  * @param certfile path to the certificate that will be used by server
867  * @param keyfile path to the keyfile for the certificate
868  * @param nscb callback called when a new SPDY session is
869  * 			established	by a client
870  * @param sccb callback called when a session is closed
871  * @param nrcb callback called when a client sends request
872  * @param npdcb callback called when HTTP body (POST data) is received
873  * 			after request
874  * @param cls common extra argument to all of the callbacks
875  * @param ... list of options (type-value pairs,
876  *        terminated with #SPDY_DAEMON_OPTION_END).
877  * @return NULL on error, handle to daemon on success
878  */
879 _MHD_EXTERN struct SPDY_Daemon *
880 SPDY_start_daemon (uint16_t port,
881                    const char *certfile,
882                    const char *keyfile,
883                    SPDY_NewSessionCallback nscb,
884                    SPDY_SessionClosedCallback sccb,
885                    SPDY_NewRequestCallback nrcb,
886                    SPDY_NewDataCallback npdcb,
887                    void *cls,
888                    ...);
889 
890 
891 /**
892  * Shutdown the daemon. First all sessions are closed. It is NOT safe
893  * to call this function in user callbacks.
894  *
895  * @param daemon to stop
896  */
897 _MHD_EXTERN void
898 SPDY_stop_daemon (struct SPDY_Daemon *daemon);
899 
900 
901 /**
902  * Obtain the select sets for this daemon. Only those are retrieved,
903  * which some processing should be done for, i.e. not all sockets are
904  * added to write_fd_set.<p>
905  *
906  * It is possible that there is
907  * nothing to be read from a socket but there is data either in the
908  * TLS subsystem's read buffers or in libmicrospdy's read buffers, which
909  * waits for being processed. In such case the file descriptor will be
910  * added to write_fd_set. Since it is very likely for the socket to be
911  * ready for writing, the select used in the application's event loop
912  * will return with success, SPDY_run will be called, the data will be
913  * processed and maybe something will be written to the socket. Without
914  * this behaviour, considering a proper event loop, data may stay in the
915  * buffers, but run is never called.
916  *
917  * @param daemon to get sets from
918  * @param read_fd_set read set
919  * @param write_fd_set write set
920  * @param except_fd_set except set
921  * @return largest FD added to any of the sets
922  */
923 _MHD_EXTERN int
924 SPDY_get_fdset (struct SPDY_Daemon *daemon,
925                 fd_set *read_fd_set,
926                 fd_set *write_fd_set,
927                 fd_set *except_fd_set);
928 
929 
930 /**
931  * Obtain timeout value for select for this daemon. The returned value
932  * is how long select
933  * should at most block, not the timeout value set for connections.
934  *
935  * @param daemon to query for timeout
936  * @param timeout will be set to the timeout value (in milliseconds)
937  * @return #SPDY_YES on success
938  *         #SPDY_NO if no connections exist that
939  * 			would necessiate the use of a timeout right now
940  */
941 _MHD_EXTERN int
942 SPDY_get_timeout (struct SPDY_Daemon *daemon,
943                   unsigned long long *timeout);
944 
945 
946 /**
947  * Run webserver operations. This method must be called in
948  * the client event loop.
949  *
950  * @param daemon to run
951  */
952 _MHD_EXTERN void
953 SPDY_run (struct SPDY_Daemon *daemon);
954 
955 
956 /* SPDY Session handling functions */
957 
958 
959 /**
960  * Closes a SPDY session. SPDY clients and servers are expected to keep
961  * sessions opened as long as possible. However, the server may want to
962  * close some connections, e.g. if there are too many, to free some
963  * resources. The function can also be used to close a specific session
964  * if the client is not desired.
965  *
966  * @param session handler to be closed
967  */
968 _MHD_EXTERN void
969 SPDY_close_session (struct SPDY_Session * session);
970 
971 
972 /**
973  * Associate a void pointer with a session. The data accessible by the
974  * pointer can later be used wherever the session handler is available.
975  *
976  * @param session handler
977  * @param cls any data pointed by a pointer to be accessible later
978  */
979 _MHD_EXTERN void
980 SPDY_set_cls_to_session (struct SPDY_Session *session,
981                          void *cls);
982 
983 
984 /**
985  * Retrieves the pointer associated with SPDY_set_cls_to_session().
986  *
987  * @param session handler to get its cls
988  * @return same pointer added by SPDY_set_cls_to_session() or
989  * 			NULL when nothing was associated
990  */
991 _MHD_EXTERN void *
992 SPDY_get_cls_from_session (struct SPDY_Session *session);
993 
994 
995 /**
996  * Retrieves the remote address of a given session.
997  *
998  * @param session handler to get its remote address
999  * @param addr out parameter; pointing to remote address
1000  * @return length of the address structure
1001  */
1002 _MHD_EXTERN socklen_t
1003 SPDY_get_remote_addr (struct SPDY_Session *session,
1004                       struct sockaddr **addr);
1005 
1006 
1007 /* SPDY name/value data structure handling functions */
1008 
1009 
1010 /**
1011  * Create a new NameValue structure. It is needed for putting inside the
1012  * HTTP headers and their values for a response. The user should later
1013  * destroy alone the structure.
1014  *
1015  * @return handler to the new empty structure or NULL on error
1016  */
1017 _MHD_EXTERN struct SPDY_NameValue *
1018 SPDY_name_value_create (void);
1019 
1020 
1021 /**
1022  * Add name/value pair to a NameValue structure. SPDY_NO will be returned
1023  * if the name/value pair is already in the structure. It is legal to
1024  * add different values for the same name.
1025  *
1026  * @param container structure to which the new pair is added
1027  * @param name for the value. Null-terminated string.
1028  * @param value the value itself. Null-terminated string.
1029  * @return #SPDY_NO on error or #SPDY_YES on success
1030  */
1031 _MHD_EXTERN int
1032 SPDY_name_value_add (struct SPDY_NameValue *container,
1033                      const char *name,
1034                      const char *value);
1035 
1036 
1037 /**
1038  * Lookup value for a name in a name/value structure.
1039  *
1040  * @param container structure in which to lookup
1041  * @param name the name to look for
1042  * @param num_values length of the returned array with values
1043  * @return NULL if no such item was found, or an array containing the
1044  * 			values
1045  */
1046 _MHD_EXTERN const char * const *
1047 SPDY_name_value_lookup (struct SPDY_NameValue *container,
1048                         const char *name,
1049                         int *num_values);
1050 
1051 
1052 /**
1053  * Iterate over name/value structure.
1054  *
1055  * @param container structure which to iterate over
1056  * @param iterator callback to call on each name/value pair;
1057  *        maybe NULL (then just count headers)
1058  * @param iterator_cls extra argument to @a iterator
1059  * @return number of entries iterated over
1060  */
1061 _MHD_EXTERN int
1062 SPDY_name_value_iterate (struct SPDY_NameValue *container,
1063                          SPDY_NameValueIterator iterator,
1064                          void *iterator_cls);
1065 
1066 
1067 /**
1068  * Destroy a NameValue structure. Use this function to destroy only
1069  * objects which, after passed to, will not be destroied by other
1070  * functions.
1071  *
1072  */
1073 _MHD_EXTERN void
1074 SPDY_name_value_destroy (struct SPDY_NameValue *container);
1075 
1076 
1077 /* SPDY request handling functions */
1078 
1079 
1080 /**
1081  * Gets the session responsible for the given
1082  * request.
1083  *
1084  * @param request for which the session is wanted
1085  * @return session handler for the request
1086  */
1087 _MHD_EXTERN struct SPDY_Session *
1088 SPDY_get_session_for_request (const struct SPDY_Request *request);
1089 
1090 
1091 /**
1092  * Associate a void pointer with a request. The data accessible by the
1093  * pointer can later be used wherever the request handler is available.
1094  *
1095  * @param request with which to associate a pointer
1096  * @param cls any data pointed by a pointer to be accessible later
1097  */
1098 _MHD_EXTERN void
1099 SPDY_set_cls_to_request (struct SPDY_Request *request,
1100                          void *cls);
1101 
1102 
1103 /**
1104  * Retrieves the pointer associated with the request by
1105  * SPDY_set_cls_to_request().
1106  *
1107  * @param request to get its cls
1108  * @return same pointer added by SPDY_set_cls_to_request() or
1109  * 			NULL when nothing was associated
1110  */
1111 _MHD_EXTERN void *
1112 SPDY_get_cls_from_request (struct SPDY_Request *request);
1113 
1114 
1115 /* SPDY response handling functions */
1116 
1117 
1118 /**
1119  * Create response object containing all needed headers and data. The
1120  * response object is not bound to a request, so it can be used multiple
1121  * times with SPDY_queue_response() and schould be
1122  * destroied by calling the SPDY_destroy_response().<p>
1123  *
1124  * Currently the library does not provide compression of the body data.
1125  * It is up to the user to pass already compressed data and the
1126  * appropriate headers to this function when desired.
1127  *
1128  * @param status HTTP status code for the response (e.g. 404)
1129  * @param statustext HTTP status message for the response, which will
1130  * 			be appended to the status code (e.g. "OK"). Can be NULL
1131  * @param version HTTP version for the response (e.g. "http/1.1")
1132  * @param headers name/value structure containing additional HTTP headers.
1133  *                Can be NULL. Can be used multiple times, it is up to
1134  *                the user to destoy the object when not needed anymore.
1135  * @param data the body of the response. The lib will make a copy of it,
1136  *             so it is up to the user to take care of the memory
1137  *             pointed by data
1138  * @param size length of @a data. It can be 0, then the lib will send only
1139  * 				headers
1140  * @return NULL on error, handle to response object on success
1141  */
1142 _MHD_EXTERN struct SPDY_Response *
1143 SPDY_build_response (int status,
1144                      const char *statustext,
1145                      const char *version,
1146                      struct SPDY_NameValue *headers,
1147                      const void *data,
1148                      size_t size);
1149 
1150 
1151 /**
1152  * Create response object containing all needed headers. The data will
1153  * be provided later when the lib calls the callback function (just
1154  * before writing it to the TLS socket). The
1155  * response object is not bound to a request, so it can be used multiple
1156  * times with SPDY_queue_response() and schould be
1157  * destroied by calling the SPDY_destroy_response().<p>
1158  *
1159  * Currently the library does not provide compression of the body data.
1160  * It is up to the user to pass already compressed data and the
1161  * appropriate headers to this function and the callback when desired.
1162  *
1163  * @param status HTTP status code for the response (e.g. 404)
1164  * @param statustext HTTP status message for the response, which will
1165  * 			be appended to the status code (e.g. "OK"). Can be NULL
1166  * @param version HTTP version for the response (e.g. "http/1.1")
1167  * @param headers name/value structure containing additional HTTP headers.
1168  *                Can be NULL. Can be used multiple times, it is up to
1169  *                the user to destoy the object when not needed anymore.
1170  * @param rcb callback to use to obtain response data
1171  * @param rcb_cls extra argument to @a rcb
1172  * @param block_size preferred block size for querying rcb (advisory only,
1173  *                   the lib will call rcb specifying the block size); clients
1174  *                   should pick a value that is appropriate for IO and
1175  *                   memory performance requirements. The function will
1176  *                   fail if the value is bigger than the maximum
1177  *                   supported value (SPDY_MAX_SUPPORTED_FRAME_SIZE).
1178  *                   Can be 0, then the lib will use
1179  *                   #SPDY_MAX_SUPPORTED_FRAME_SIZE instead.
1180  * @return NULL on error, handle to response object on success
1181  */
1182 _MHD_EXTERN struct SPDY_Response *
1183 SPDY_build_response_with_callback(int status,
1184                                   const char *statustext,
1185                                   const char *version,
1186                                   struct SPDY_NameValue *headers,
1187                                   SPDY_ResponseCallback rcb,
1188                                   void *rcb_cls,
1189                                   uint32_t block_size);
1190 
1191 
1192 /**
1193  * Queue response object to be sent to the client. A successfully queued
1194  * response may never be sent, e.g. when the stream gets closed. The
1195  * data will be added to the output queue. The call will fail, if the
1196  * output for this session
1197  * is closed (i.e. the session is closed, half or full) or the output
1198  * channel for the stream, on which the request was received, is closed
1199  * (i.e. the stream is closed, half or full).
1200  *
1201  * @param request object identifying the request to which the
1202  * 			response is returned
1203  * @param response object containg headers and data to be sent
1204  * @param closestream TRUE if the server does NOT intend to PUSH
1205  * 			something more associated to this request/response later,
1206  * 			FALSE otherwise
1207  * @param consider_priority if FALSE, the response will be added to the
1208  * 			end of the queue. If TRUE, the response will be added after
1209  * 			the last previously added response with priority of the
1210  * 			request grater or equal to that of the current one. This
1211  * 			means that the function should be called with TRUE each time
1212  * 			if one wants to be sure that the output queue behaves like
1213  * 			a priority queue
1214  * @param rrcb callback called when all the data was sent (last frame
1215  * 			from response) or when that frame was discarded (e.g. the
1216  * 			stream has been closed meanwhile)
1217  * @param rrcb_cls extra argument to @a rrcb
1218  * @return #SPDY_NO on error or #SPDY_YES on success
1219  */
1220 _MHD_EXTERN int
1221 SPDY_queue_response (struct SPDY_Request *request,
1222                      struct SPDY_Response *response,
1223                      bool closestream,
1224                      bool consider_priority,
1225                      SPDY_ResponseResultCallback rrcb,
1226                      void *rrcb_cls);
1227 
1228 
1229 /**
1230  * Destroy a response structure. It should be called for all objects
1231  * returned by SPDY_build_response*() functions to free the memory
1232  * associated with the prepared response. It is safe to call this
1233  * function not before being sure that the response will not be used by
1234  * the lib anymore, this means after SPDY_ResponseResultCallback
1235  * callbacks were called for all calls to SPDY_queue_response() passing
1236  * this response.
1237  *
1238  * @param response to destroy
1239  */
1240 _MHD_EXTERN void
1241 SPDY_destroy_response (struct SPDY_Response *response);
1242 
1243 
1244 /* SPDY settings ID/value data structure handling functions */
1245 
1246 
1247 /**
1248  * Create a new SettingsIDValue structure. It is needed for putting
1249  * inside tuples of SPDY option, flags and value for sending to the
1250  * client.
1251  *
1252  * @return hendler to the new empty structure or NULL on error
1253  */
1254 _MHD_EXTERN const struct SPDY_Settings *
1255 SPDY_settings_create (void);
1256 
1257 
1258 /**
1259  * Add or update a tuple to a SettingsIDValue structure.
1260  *
1261  * @param container structure to which the new tuple is added
1262  * @param id SPDY settings ID that will be sent. If this ID already in
1263  *           container, the tupple for it will be updated (value and/or
1264  *           flags). If it is not in the container, a new tupple will be
1265  *           added.
1266  * @param flags SPDY settings flags applied only to this setting
1267  * @param value of the setting
1268  * @return #SPDY_NO on error
1269  * 			or #SPDY_YES if a new setting was added
1270  */
1271 _MHD_EXTERN int
1272 SPDY_settings_add (struct SPDY_Settings *container,
1273                    enum SPDY_SETTINGS id,
1274                    enum SPDY_FLAG_SETTINGS flags,
1275                    int32_t value);
1276 
1277 
1278 /**
1279  * Lookup value and flags for an ID in a settings ID/value structure.
1280  *
1281  * @param container structure in which to lookup
1282  * @param id SPDY settings ID to search for
1283  * @param flags out param for SPDY settings flags for this setting;
1284  * 			check it against the flags in enum SPDY_FLAG_SETTINGS
1285  * @param value out param for the value of this setting
1286  * @return #SPDY_NO if the setting is not into the structure
1287  * 			or #SPDY_YES if it is into it
1288  */
1289 _MHD_EXTERN int
1290 SPDY_settings_lookup (const struct SPDY_Settings *container,
1291                       enum SPDY_SETTINGS id,
1292                       enum SPDY_FLAG_SETTINGS *flags,
1293                       int32_t *value);
1294 
1295 
1296 /**
1297  * Iterate over settings ID/value structure.
1298  *
1299  * @param container structure which to iterate over
1300  * @param iterator callback to call on each ID/value pair;
1301  *        maybe NULL (then just count number of settings)
1302  * @param iterator_cls extra argument to iterator
1303  * @return number of entries iterated over
1304  */
1305 _MHD_EXTERN int
1306 SPDY_settings_iterate (const struct SPDY_Settings *container,
1307                        SPDY_SettingsIterator iterator,
1308                        void *iterator_cls);
1309 
1310 
1311 /**
1312  * Destroy a settings ID/value structure. Use this function to destroy
1313  * only objects which, after passed to, will not be destroied by other
1314  * functions.
1315  *
1316  * @param container structure which to detroy
1317  */
1318 _MHD_EXTERN void
1319 SPDY_settings_destroy (struct SPDY_Settings * container);
1320 
1321 
1322 /* SPDY SETTINGS handling functions */
1323 
1324 
1325 /**
1326  * Send SPDY SETTINGS to the client. The call will return fail if there
1327  * in invald setting into the settings container (e.g. invalid setting
1328  * ID).
1329  *
1330  * @param session SPDY_Session handler for which settings are being sent
1331  * @param settings ID/value pairs of the settings to be sent.
1332  * 			Can be used multiple times, it is up to the user to destoy
1333  * 			the object when not needed anymore.
1334  * @param flags for the whole settings frame. They are valid for all tuples
1335  * @param ... list of options (type-value pairs,
1336  *        terminated with #SPDY_SETTINGS_OPTION_END).
1337  * @return SPDY_NO on error or SPDY_YES on
1338  * 			success
1339  */
1340 _MHD_EXTERN int
1341 SPDY_send_settings (struct SPDY_Session *session,
1342                     struct SPDY_Settings *settings,
1343                     enum SPDY_FLAG_SETTINGS_FRAME flags,
1344                     ...);
1345 
1346 
1347 /* SPDY misc functions */
1348 
1349 
1350 /**
1351  * Destroy a request structure. It should be called for all objects
1352  * received as a parameter in SPDY_NewRequestCallback to free the memory
1353  * associated with the request. It is safe to call this
1354  * function not before being sure that the request will not be used by
1355  * the lib anymore, this means after the stream, on which this request
1356  * had been sent, was closed and all SPDY_ResponseResultCallback
1357  * callbacks were called for all calls to SPDY_queue_response() passing
1358  * this request object.
1359  *
1360  * @param request to destroy
1361  */
1362 _MHD_EXTERN void
1363 SPDY_destroy_request (struct SPDY_Request * request);
1364 
1365 
1366 /**
1367  * Send SPDY ping to the client
1368  *
1369  * @param session handler for which the ping request is sent
1370  * @param rttcb callback called when ping response to the request is
1371  * 			received
1372  * @param rttcb_cls extra argument to @a rttcb
1373  * @return #SPDY_NO on error or #SPDY_YES on success
1374  */
1375 _MHD_EXTERN int
1376 SPDY_send_ping (struct SPDY_Session *session,
1377                 SPDY_PingCallback rttcb,
1378                 void *rttcb_cls);
1379 
1380 #endif
1381