src/include/microspdy.h

/*
    This file is part of libmicrospdy
    Copyright Copyright (C) 2012, 2013 Christian Grothoff

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * @file microspdy.h
 * @brief public interface to libmicrospdy
 * @author Andrey Uzunov
 * @author Christian Grothoff
 *
 * All symbols defined in this header start with SPDY_.  libmisrospdy is a small
 * SPDY daemon library. The application can start multiple daemons
 * and they are independent.<p>
 *
 * The header file defines various constants used by the SPDY and the HTTP protocol.
 * This does not mean that the lib actually interprets all of these
 * values. Not everything is implemented. The provided constants are exported as a convenience
 * for users of the library.  The lib does not verify that provided
 * HTTP headers and if their values conform to the SPDY protocol,
 * it only checks if the required headers for the SPDY requests and
 * responses are provided.<p>
 *
 * The library uses just a single thread.<p>
 *
 * Before including "microspdy.h" you should add the necessary
 * includes to define the types used in this file (which headers are needed may
 * depend on your platform; for possible suggestions consult
 * "platform.h" in the libmicrospdy distribution).<p>
 *
 * All of the functions returning SPDY_YES/SPDY_NO return
 * SPDY_INPUT_ERROR when any of the parameters are invalid, e.g.
 * required parameter is NULL.<p>
 *
 * The library does not check if anything at the application layer --
 * requests and responses -- is correct. For example, it
 * is up to the user to check if a client is sending HTTP body but the
 * method is GET.<p>
 *
 * The SPDY flow control is just partially implemented: the receiving
 * window is updated, and the client is notified, to prevent a client
 * from stop sending POST body data, for example.
 */
#ifndef SPDY_MICROSPDY_H
#define SPDY_MICROSPDY_H

#include <zlib.h>
#include <stdbool.h>

/* While we generally would like users to use a configure-driven
   build process which detects which headers are present and
   hence works on any platform, we use "standard" includes here
   to build out-of-the-box for beginning users on common systems.

   Once you have a proper build system and go for more exotic
   platforms, you should define MHD_PLATFORM_H in some header that
   you always include *before* "microhttpd.h".  Then the following
   "standard" includes won't be used (which might be a good
   idea, especially on platforms where they do not exist). */
#ifndef MHD_PLATFORM_H
#include <unistd.h>
#include <stdarg.h>
#include <stdint.h>
#ifdef __MINGW32__
#include <ws2tcpip.h>
#else
#include <sys/time.h>
#include <sys/types.h>
#include <sys/socket.h>
#endif
#endif

#ifndef _MHD_EXTERN
#define _MHD_EXTERN extern
#endif

/**
 * return code for "YES".
 */
#define SPDY_YES 1

/**
 * return code for "NO".
 */
#define SPDY_NO 0

/**
 * return code for error when input parameters are wrong. To be returned
 * only by functions which return int. The others will return NULL on
 * input error.
 */
#define SPDY_INPUT_ERROR -1

/**
 * SPDY version supported by the lib.
 */
#define SPDY_VERSION 3

/**
 * The maximum allowed size (without 8 byte headers) of
 * SPDY frames (value length) is 8192. The lib will accept and
 * send frames with length at most this value here.
 */
#define SPDY_MAX_SUPPORTED_FRAME_SIZE 8192

/**
 * HTTP response codes.
 */
#define SPDY_HTTP_CONTINUE 100
#define SPDY_HTTP_SWITCHING_PROTOCOLS 101
#define SPDY_HTTP_PROCESSING 102

#define SPDY_HTTP_OK 200
#define SPDY_HTTP_CREATED 201
#define SPDY_HTTP_ACCEPTED 202
#define SPDY_HTTP_NON_AUTHORITATIVE_INFORMATION 203
#define SPDY_HTTP_NO_CONTENT 204
#define SPDY_HTTP_RESET_CONTENT 205
#define SPDY_HTTP_PARTIAL_CONTENT 206
#define SPDY_HTTP_MULTI_STATUS 207

#define SPDY_HTTP_MULTIPLE_CHOICES 300
#define SPDY_HTTP_MOVED_PERMANENTLY 301
#define SPDY_HTTP_FOUND 302
#define SPDY_HTTP_SEE_OTHER 303
#define SPDY_HTTP_NOT_MODIFIED 304
#define SPDY_HTTP_USE_PROXY 305
#define SPDY_HTTP_SWITCH_PROXY 306
#define SPDY_HTTP_TEMPORARY_REDIRECT 307

#define SPDY_HTTP_BAD_REQUEST 400
#define SPDY_HTTP_UNAUTHORIZED 401
#define SPDY_HTTP_PAYMENT_REQUIRED 402
#define SPDY_HTTP_FORBIDDEN 403
#define SPDY_HTTP_NOT_FOUND 404
#define SPDY_HTTP_METHOD_NOT_ALLOWED 405
#define SPDY_HTTP_METHOD_NOT_ACCEPTABLE 406
#define SPDY_HTTP_PROXY_AUTHENTICATION_REQUIRED 407
#define SPDY_HTTP_REQUEST_TIMEOUT 408
#define SPDY_HTTP_CONFLICT 409
#define SPDY_HTTP_GONE 410
#define SPDY_HTTP_LENGTH_REQUIRED 411
#define SPDY_HTTP_PRECONDITION_FAILED 412
#define SPDY_HTTP_REQUEST_ENTITY_TOO_LARGE 413
#define SPDY_HTTP_REQUEST_URI_TOO_LONG 414
#define SPDY_HTTP_UNSUPPORTED_MEDIA_TYPE 415
#define SPDY_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416
#define SPDY_HTTP_EXPECTATION_FAILED 417
#define SPDY_HTTP_UNPROCESSABLE_ENTITY 422
#define SPDY_HTTP_LOCKED 423
#define SPDY_HTTP_FAILED_DEPENDENCY 424
#define SPDY_HTTP_UNORDERED_COLLECTION 425
#define SPDY_HTTP_UPGRADE_REQUIRED 426
#define SPDY_HTTP_NO_RESPONSE 444
#define SPDY_HTTP_RETRY_WITH 449
#define SPDY_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450
#define SPDY_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451

#define SPDY_HTTP_INTERNAL_SERVER_ERROR 500
#define SPDY_HTTP_NOT_IMPLEMENTED 501
#define SPDY_HTTP_BAD_GATEWAY 502
#define SPDY_HTTP_SERVICE_UNAVAILABLE 503
#define SPDY_HTTP_GATEWAY_TIMEOUT 504
#define SPDY_HTTP_HTTP_VERSION_NOT_SUPPORTED 505
#define SPDY_HTTP_VARIANT_ALSO_NEGOTIATES 506
#define SPDY_HTTP_INSUFFICIENT_STORAGE 507
#define SPDY_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
#define SPDY_HTTP_NOT_EXTENDED 510

/**
 * HTTP headers are used in SPDY, but all of them MUST be lowercase.
 * Some are not valid in SPDY and MUST not be used
 */
#define SPDY_HTTP_HEADER_ACCEPT "accept"
#define SPDY_HTTP_HEADER_ACCEPT_CHARSET "accept-charset"
#define SPDY_HTTP_HEADER_ACCEPT_ENCODING "accept-encoding"
#define SPDY_HTTP_HEADER_ACCEPT_LANGUAGE "accept-language"
#define SPDY_HTTP_HEADER_ACCEPT_RANGES "accept-ranges"
#define SPDY_HTTP_HEADER_AGE "age"
#define SPDY_HTTP_HEADER_ALLOW "allow"
#define SPDY_HTTP_HEADER_AUTHORIZATION "authorization"
#define SPDY_HTTP_HEADER_CACHE_CONTROL "cache-control"
/* Connection header is forbidden in SPDY */
#define SPDY_HTTP_HEADER_CONNECTION "connection"
#define SPDY_HTTP_HEADER_CONTENT_ENCODING "content-encoding"
#define SPDY_HTTP_HEADER_CONTENT_LANGUAGE "content-language"
#define SPDY_HTTP_HEADER_CONTENT_LENGTH "content-length"
#define SPDY_HTTP_HEADER_CONTENT_LOCATION "content-location"
#define SPDY_HTTP_HEADER_CONTENT_MD5 "content-md5"
#define SPDY_HTTP_HEADER_CONTENT_RANGE "content-range"
#define SPDY_HTTP_HEADER_CONTENT_TYPE "content-type"
#define SPDY_HTTP_HEADER_COOKIE "cookie"
#define SPDY_HTTP_HEADER_DATE "date"
#define SPDY_HTTP_HEADER_ETAG "etag"
#define SPDY_HTTP_HEADER_EXPECT "expect"
#define SPDY_HTTP_HEADER_EXPIRES "expires"
#define SPDY_HTTP_HEADER_FROM "from"
/* Host header is forbidden in SPDY */
#define SPDY_HTTP_HEADER_HOST "host"
#define SPDY_HTTP_HEADER_IF_MATCH "if-match"
#define SPDY_HTTP_HEADER_IF_MODIFIED_SINCE "if-modified-since"
#define SPDY_HTTP_HEADER_IF_NONE_MATCH "if-none-match"
#define SPDY_HTTP_HEADER_IF_RANGE "if-range"
#define SPDY_HTTP_HEADER_IF_UNMODIFIED_SINCE "if-unmodified-since"
/* Keep-Alive header is forbidden in SPDY */
#define SPDY_HTTP_HEADER_KEEP_ALIVE "keep-alive"
#define SPDY_HTTP_HEADER_LAST_MODIFIED "last-modified"
#define SPDY_HTTP_HEADER_LOCATION "location"
#define SPDY_HTTP_HEADER_MAX_FORWARDS "max-forwards"
#define SPDY_HTTP_HEADER_PRAGMA "pragma"
#define SPDY_HTTP_HEADER_PROXY_AUTHENTICATE "proxy-authenticate"
#define SPDY_HTTP_HEADER_PROXY_AUTHORIZATION "proxy-authorization"
/* Proxy-Connection header is forbidden in SPDY */
#define SPDY_HTTP_HEADER_PROXY_CONNECTION "proxy-connection"
#define SPDY_HTTP_HEADER_RANGE "range"
#define SPDY_HTTP_HEADER_REFERER "referer"
#define SPDY_HTTP_HEADER_RETRY_AFTER "retry-after"
#define SPDY_HTTP_HEADER_SERVER "server"
#define SPDY_HTTP_HEADER_SET_COOKIE "set-cookie"
#define SPDY_HTTP_HEADER_SET_COOKIE2 "set-cookie2"
#define SPDY_HTTP_HEADER_TE "te"
#define SPDY_HTTP_HEADER_TRAILER "trailer"
/* Transfer-Encoding header is forbidden in SPDY */
#define SPDY_HTTP_HEADER_TRANSFER_ENCODING "transfer-encoding"
#define SPDY_HTTP_HEADER_UPGRADE "upgrade"
#define SPDY_HTTP_HEADER_USER_AGENT "user-agent"
#define SPDY_HTTP_HEADER_VARY "vary"
#define SPDY_HTTP_HEADER_VIA "via"
#define SPDY_HTTP_HEADER_WARNING "warning"
#define SPDY_HTTP_HEADER_WWW_AUTHENTICATE "www-authenticate"

/**
 * HTTP versions (a value must be provided in SPDY requests/responses).
 */
#define SPDY_HTTP_VERSION_1_0 "HTTP/1.0"
#define SPDY_HTTP_VERSION_1_1 "HTTP/1.1"

/**
 * HTTP methods
 */
#define SPDY_HTTP_METHOD_CONNECT "CONNECT"
#define SPDY_HTTP_METHOD_DELETE "DELETE"
#define SPDY_HTTP_METHOD_GET "GET"
#define SPDY_HTTP_METHOD_HEAD "HEAD"
#define SPDY_HTTP_METHOD_OPTIONS "OPTIONS"
#define SPDY_HTTP_METHOD_POST "POST"
#define SPDY_HTTP_METHOD_PUT "PUT"
#define SPDY_HTTP_METHOD_TRACE "TRACE"

/**
 * HTTP POST encodings, see also
 * http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4
 */
#define SPDY_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
#define SPDY_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"


/**
 * Handle for the daemon (listening on a socket).
 */
struct SPDY_Daemon;


/**
 * Handle for a SPDY session/connection.
 */
struct SPDY_Session;


/**
 * Handle for a SPDY request sent by a client. The structure has pointer
 * to the session's handler
 */
struct SPDY_Request;


/**
 * Handle for a response containing HTTP headers and data to be sent.
 * The structure has pointer to the session's handler
 * for this response.
 */
struct SPDY_Response;


/**
 * Collection of tuples of an HTTP header and values used in requests
 * and responses.
 */
struct SPDY_NameValue;


/**
 * Collection of tuples of a SPDY setting ID, value
 * and flags used to control the sessions.
 */
struct SPDY_Settings;


/**
 * SPDY IO sybsystem flags used by SPDY_init() and SPDY_deinit().<p>
 *
 * The values are used internally as flags, that is why they must be
 * powers of 2.
 */
enum SPDY_IO_SUBSYSTEM
{

  /**
   * No subsystem. For internal use.
   */
  SPDY_IO_SUBSYSTEM_NONE = 0,

  /**
   * Default TLS implementation provided by openSSL/libssl.
   */
  SPDY_IO_SUBSYSTEM_OPENSSL = 1,

  /**
   * No TLS is used.
   */
  SPDY_IO_SUBSYSTEM_RAW = 2
};


/**
 * SPDY daemon options. Passed in the varargs portion of
 * SPDY_start_daemon to customize the daemon. Each option must
 * be followed by a value of a specific type.<p>
 *
 * The values are used internally as flags, that is why they must be
 * powers of 2.
 */
enum SPDY_DAEMON_OPTION
{

  /**
   * No more options / last option.  This is used
   * to terminate the VARARGs list.
   */
  SPDY_DAEMON_OPTION_END = 0,

  /**
   * Set a custom timeout for all connections.  Must be followed by
   * a number of seconds, given as an 'unsigned int'.  Use
   * zero for no timeout.
   */
  SPDY_DAEMON_OPTION_SESSION_TIMEOUT = 1,

  /**
   * Bind daemon to the supplied sockaddr. This option must be
   * followed by a 'struct sockaddr *'.  The 'struct sockaddr*'
   * should point to a 'struct sockaddr_in6' or to a
   * 'struct sockaddr_in'.
   */
  SPDY_DAEMON_OPTION_SOCK_ADDR = 2,

  /**
   * Flags for the daemon. Must be followed by a SPDY_DAEMON_FLAG value
   * which is the result of bitwise OR of desired flags.
   */
  SPDY_DAEMON_OPTION_FLAGS = 4,

  /**
   * IO subsystem type used by daemon and all its sessions. If not set,
   * TLS provided by openssl is used. Must be followed by a
   * SPDY_IO_SUBSYSTEM value.
   */
  SPDY_DAEMON_OPTION_IO_SUBSYSTEM = 8,

  /**
   * Maximum number of frames to be written to the socket at once. The
   * library tries to send max_num_frames in a single call to SPDY_run
   * for a single session. This means no requests can be received nor
   * other sessions can send data as long the current one has enough
   * frames to send and there is no error on writing. Thus, a big value
   * will affect the performance. Small value gives fairnes for sessions.
   * Must be followed by a positive integer (uin32_t). If not set, the
   * default value 10 will be used.
   */
  SPDY_DAEMON_OPTION_MAX_NUM_FRAMES = 16
};


/**
 * Flags for starting SPDY daemon. They are used to set some settings
 * for the daemon, which do not require values.
 */
enum SPDY_DAEMON_FLAG
{
  /**
   * No flags selected.
   */
  SPDY_DAEMON_FLAG_NO = 0,

  /**
   * The server will bind only on IPv6 addresses. If the flag is set and
   * the daemon is provided with IPv4 address or IPv6 is not supported,
   * starting daemon will fail.
   */
  SPDY_DAEMON_FLAG_ONLY_IPV6 = 1,

  /**
   * All sessions' sockets will be set with TCP_NODELAY if the flag is
   * used. Option considered only by SPDY_IO_SUBSYSTEM_RAW.
   */
  SPDY_DAEMON_FLAG_NO_DELAY = 2
};


/**
 * SPDY settings IDs sent by both client and server in SPDY SETTINGS frame.
 * They affect the whole SPDY session. Defined in SPDY Protocol - Draft 3.
 */
enum SPDY_SETTINGS
{

  /**
   * Allows the sender to send its expected upload bandwidth on this
   * channel. This number is an estimate. The value should be the
   * integral number of kilobytes per second that the sender predicts
   * as an expected maximum upload channel capacity.
   */
  SPDY_SETTINGS_UPLOAD_BANDWIDTH = 1,

  /**
   * Allows the sender to send its expected download bandwidth on this
   * channel. This number is an estimate. The value should be the
   * integral number of kilobytes per second that the sender predicts as
   * an expected maximum download channel capacity.
   */
  SPDY_SETTINGS_DOWNLOAD_BANDWIDTH = 2,

  /**
   * Allows the sender to send its expected round-trip-time on this
   * channel. The round trip time is defined as the minimum amount of
   * time to send a control frame from this client to the remote and
   * receive a response. The value is represented in milliseconds.
   */
  SPDY_SETTINGS_ROUND_TRIP_TIME = 3,

  /**
   * Allows the sender to inform the remote endpoint the maximum number
   * of concurrent streams which it will allow. By default there is no
   * limit. For implementors it is recommended that this value be no
   * smaller than 100.
   */
  SPDY_SETTINGS_MAX_CONCURRENT_STREAMS = 4,

  /**
   * Allows the sender to inform the remote endpoint of the current TCP
   * CWND value.
   */
  SPDY_SETTINGS_CURRENT_CWND = 5,

  /**
   * Allows the sender to inform the remote endpoint the retransmission
   * rate (bytes retransmitted / total bytes transmitted).
   */
  SPDY_SETTINGS_DOWNLOAD_RETRANS_RATE = 6,

  /**
   * Allows the sender to inform the remote endpoint the initial window
   * size (in bytes) for new streams.
   */
  SPDY_SETTINGS_INITIAL_WINDOW_SIZE = 7,

  /**
   * Allows the server to inform the client if the new size of the
   * client certificate vector.
   */
  SPDY_SETTINGS_CLIENT_CERTIFICATE_VECTOR_SIZE = 8
};


/**
 * Flags for each individual SPDY setting in the SPDY SETTINGS frame.
 * They affect only one setting to which they are set.
 * Defined in SPDY Protocol - Draft 3.
 */
enum SPDY_FLAG_SETTINGS
{

  /**
   * When set, the sender of this SETTINGS frame is requesting that the
   * recipient persist the ID/Value and return it in future SETTINGS
   * frames sent from the sender to this recipient. Because persistence
   * is only implemented on the client, this flag is only sent by the
   * server.
   */
  SPDY_FLAG_SETTINGS_PERSIST_VALUE = 1,

  /**
   * When set, the sender is notifying the recipient that this ID/Value
   * pair was previously sent to the sender by the recipient with the
   * #SPDY_FLAG_SETTINGS_PERSIST_VALUE, and the sender is returning it.
   * Because persistence is only implemented on the client, this flag is
   * only sent by the client.
   */
  SPDY_FLAG_SETTINGS_PERSISTED = 2
};


/**
 * Flag associated with a whole SPDY SETTINGS frame. Affect all the
 * settings in the frame. Defined in SPDY Protocol - Draft 3.
 */
enum SPDY_FLAG_SETTINGS_FRAME
{

  /**
   * When set, the client should clear any previously persisted SETTINGS
   * ID/Value pairs. If this frame contains ID/Value pairs with the
   * #SPDY_FLAG_SETTINGS_PERSIST_VALUE set, then the client will first
   * clear its existing, persisted settings, and then persist the values
   * with the flag set which are contained within this frame. Because
   * persistence is only implemented on the client, this flag can only
   * be used when the sender is the server.
   */
  SPDY_FLAG_SETTINGS_CLEAR_SETTINGS = 1
};


/**
 * SPDY settings function options. Passed in the varargs portion of
 * SPDY_SettingsReceivedCallback and SPDY_send_settings to customize
 * more the settings handling. Each option must
 * be followed by a value of a specific type.<p>
 *
 * The values are used internally as flags, that is why they must be
 * powers of 2.
 */
enum SPDY_SETTINGS_OPTION
{

  /**
   * No more options / last option.  This is used
   * to terminate the VARARGs list.
   */
  SPDY_SETTINGS_OPTION_END = 0
};


/**
 * Used as a parameter for SPDY_ResponseResultCallback and shows if the
 * response was actually written to the TLS socket or discarded by the
 * lib for any reason (and respectively the reason).
 */
enum SPDY_RESPONSE_RESULT
{

  /**
   * The lib has written the full response to the TLS socket.
   */
  SPDY_RESPONSE_RESULT_SUCCESS = 0,

  /**
   * The session is being closed, so the data is being discarded
   */
  SPDY_RESPONSE_RESULT_SESSION_CLOSED = 1,

  /**
   * The stream for this response has been closed. May happen when the
   * sender had sent first SYN_STREAM and after that RST_STREAM.
   */
  SPDY_RESPONSE_RESULT_STREAM_CLOSED = 2
};


/**
 * Callback for serious error condition. The default action is to print
 * an error message and abort().
 *
 * @param cls user specified value
 * @param file where the error occured
 * @param line where the error occured
 * @param reason error details message, may be NULL
 */
typedef void
(*SPDY_PanicCallback) (void * cls,
                       const char *file,
                       unsigned int line,
                       const char *reason);


/**
 * Callback for new SPDY session established by a client. Called
 * immediately after the TCP connection was established.
 *
 * @param cls client-defined closure
 * @param session handler for the new SPDY session
 */
typedef void
(*SPDY_NewSessionCallback) (void * cls,
                            struct SPDY_Session * session);


/**
 * Callback for closed session. Called after the TCP connection was
 * closed. In this callback function the user has the last
 * chance to access the SPDY_Session structure. After that the latter
 * will be cleaned!
 *
 * @param cls client-defined closure
 * @param session handler for the closed SPDY session
 * @param by_client #SPDY_YES if the session close was initiated by the
 * 					client;
 * 		    #SPDY_NO if closed by the server
 */
typedef void
(*SPDY_SessionClosedCallback) (void *cls,
                               struct SPDY_Session *session,
                               int by_client);


/**
 * Iterator over name-value pairs.
 *
 * @param cls client-defined closure
 * @param name of the pair
 * @param value of the pair
 * @return #SPDY_YES to continue iterating,
 *         #SPDY_NO to abort the iteration
 */
typedef int
(*SPDY_NameValueIterator) (void *cls,
                           const char *name,
                           const char * const * value,
                           int num_values);


/**
 * Callback for received SPDY request. The functions is called whenever
 * a reqest comes, but will also be called if more headers/trailers are
 * received.
 *
 * @param cls client-defined closure
 * @param request handler. The request object is required for
 * 			sending responses.
 * @param priority of the SPDY stream which the request was
 * 			sent over
 * @param method HTTP method
 * @param path HTTP path
 * @param version HTTP version just like in HTTP request/response:
 * 			"HTTP/1.0" or "HTTP/1.1" currently
 * @param host called host as in HTTP
 * @param scheme used ("http" or "https"). In SPDY 3 it is only "https".
 * @param headers other HTTP headers from the request
 * @param more a flag saying if more data related to the request is
 *        expected to be received. HTTP body may arrive (e.g. POST data);
 *        then SPDY_NewDataCallback will be called for the connection.
 *        It is also possible that more headers/trailers arrive;
 *        then the same callback will be invoked. The user should detect
 *        that it is not the first invocation of the function for that
 *        request.
 */
typedef void
(*SPDY_NewRequestCallback) (void *cls,
                            struct SPDY_Request *request,
                            uint8_t priority,
                            const char *method,
                            const char *path,
                            const char *version,
                            const char *host,
                            const char *scheme,
                            struct SPDY_NameValue *headers,
                            bool more);


/**
 * Callback for received new data chunk (HTTP body) from a given
 * request (e.g. POST data).
 *
 * @param cls client-defined closure
 * @param request handler
 * @param buf data chunk from the POST data
 * @param size the size of the data chunk 'buf' in bytes. Note that it
 *             may be 0.
 * @param more false if this is the last chunk from the data. Note:
 *             true does not mean that more data will come, exceptional
 *             situation is possible
 * @return #SPDY_YES to continue calling the function,
 *         #SPDY_NO to stop calling the function for this request
 */
typedef int
(*SPDY_NewDataCallback) (void *cls,
                         struct SPDY_Request *request,
                         const void *buf,
                         size_t size,
                         bool more);
// How about passing POST encoding information
// here as well?
//TODO


/**
 * Callback to be used with SPDY_build_response_with_callback. The
 * callback will be called when the lib wants to write to the TLS socket.
 * The application should provide the data to be sent.
 *
 * @param cls client-defined closure
 * @param max maximum number of bytes that are allowed to be written
 * 			to the buffer.
 * @param more true if more data will be sent (i.e. the function must
 * 				be calleed again),
 *             false if this is the last chunk, the lib will close
 * 				the stream
 * @return number of bytes written to buffer. On error the call MUST
 * 			return value less than 0 to indicate the library.
 */
typedef ssize_t
(*SPDY_ResponseCallback) (void *cls,
                          void *buffer,
                          size_t max,
                          bool *more);


/**
 * Callback to be called when the last bytes from the response was sent
 * to the client or when the response was discarded from the lib. This
 * callback is a very good place to discard the request and the response
 * objects, if they will not be reused (e.g., sending the same response
 * again). If the stream is closed it is safe to discard the request
 * object.
 *
 * @param cls client-defined closure
 * @param response handler to the response that was just sent
 * @param request handler to the request for which the response was sent
 * @param status shows if actually the response was sent or it was
 * 			discarded by the lib for any reason (e.g., closing session,
 * 			closing stream, stopping daemon, etc.). It is possible that
 * 			status indicates an error but parts of the response headers
 * 			and/or body (in one
 * 			or several frames) were already sent to the client.
 * @param streamopened indicates if the the stream for this request/
 * 			response pair is still opened. If yes, the server may want
 * 			to use SPDY push to send something additional to the client
 * 			and/or close the stream.
 */
typedef void
(*SPDY_ResponseResultCallback) (void * cls,
                                struct SPDY_Response *response,
                                struct SPDY_Request *request,
                                enum SPDY_RESPONSE_RESULT status,
                                bool streamopened);


/**
 * Callback to notify when SPDY ping response is received.
 *
 * @param session handler for which the ping request was sent
 * @param rtt the timespan between sending ping request and receiving it
 * 			from the library
 */
typedef void
(*SPDY_PingCallback) (void * cls,
                      struct SPDY_Session *session,
                      struct timeval *rtt);


/**
 * Iterator over settings ID/Value/Flags tuples.
 *
 * @param cls client-defined closure
 * @param id SPDY settings ID
 * @param value value for this setting
 * @param flags flags for this tuple; use
 * 			`enum SPDY_FLAG_SETTINGS`
 * @return #SPDY_YES to continue iterating,
 *         #SPDY_NO to abort the iteration
 */
typedef int
(*SPDY_SettingsIterator) (void *cls,
                          enum SPDY_SETTINGS id,
                          int32_t value,
                          uint8_t flags);


/**
 * Callback to notify when SPDY SETTINGS are received from the client.
 *
 * @param session handler for which settings are received
 * @param settings ID/value/flags tuples of the settings
 * @param flags for the whole settings frame; use
 * 			enum SPDY_FLAG_SETTINGS_FRAME
 * @param ... list of options (type-value pairs,
 *        terminated with #SPDY_SETTINGS_OPTION_END).
 */
typedef void
(*SPDY_SettingsReceivedCallback) (struct SPDY_Session *session,
                                  struct SPDY_Settings *settings,
                                  uint8_t flags,
                                  ...);


/* Global functions for the library */


/**
 * Init function for the whole library. It MUST be called before any
 * other function of the library to initialize things like TLS context
 * and possibly other stuff needed by the lib. Currently the call
 * always returns #SPDY_YES.
 *
 * @param io_subsystem the IO subsystem that will
 *        be initialized. Several can be used with bitwise OR. If no
 *        parameter is set, the default openssl subsystem will be used.
 * @return #SPDY_YES if the library was correctly initialized and its
 * 			functions can be used now;
 * 			#SPDY_NO on error
 */
_MHD_EXTERN int
(SPDY_init) (enum SPDY_IO_SUBSYSTEM io_subsystem, ...);
#define SPDY_init() SPDY_init (SPDY_IO_SUBSYSTEM_OPENSSL)


/**
 * Deinit function for the whole lib. It can be called after finishing
 * using the library. It frees and cleans up resources allocated in
 * SPDY_init. Currently the function does not do anything.
 */
_MHD_EXTERN void
SPDY_deinit (void);


/**
 * Sets the global error handler to a different implementation. "cb"
 * will only be called in the case of typically fatal, serious
 * internal consistency issues.  These issues should only arise in the
 * case of serious memory corruption or similar problems with the
 * architecture as well as failed assertions.  While "cb" is allowed to
 * return and the lib will then try to continue, this is never safe.
 *
 * The default implementation that is used if no panic function is set
 * simply prints an error message and calls "abort".  Alternative
 * implementations might call "exit" or other similar functions.
 *
 * @param cb new error handler
 * @param cls passed to error handler
 */
_MHD_EXTERN void
SPDY_set_panic_func (SPDY_PanicCallback cb,
                     void *cls);


/* Daemon functions */


/**
 * Start a SPDY webserver on the given port.
 *
 * @param port to bind to. The value is ignored if address structure
 * 			is passed as daemon option
 * @param certfile path to the certificate that will be used by server
 * @param keyfile path to the keyfile for the certificate
 * @param nscb callback called when a new SPDY session is
 * 			established	by a client
 * @param sccb callback called when a session is closed
 * @param nrcb callback called when a client sends request
 * @param npdcb callback called when HTTP body (POST data) is received
 * 			after request
 * @param cls common extra argument to all of the callbacks
 * @param ... list of options (type-value pairs,
 *        terminated with #SPDY_DAEMON_OPTION_END).
 * @return NULL on error, handle to daemon on success
 */
_MHD_EXTERN struct SPDY_Daemon *
SPDY_start_daemon (uint16_t port,
                   const char *certfile,
                   const char *keyfile,
                   SPDY_NewSessionCallback nscb,
                   SPDY_SessionClosedCallback sccb,
                   SPDY_NewRequestCallback nrcb,
                   SPDY_NewDataCallback npdcb,
                   void *cls,
                   ...);


/**
 * Shutdown the daemon. First all sessions are closed. It is NOT safe
 * to call this function in user callbacks.
 *
 * @param daemon to stop
 */
_MHD_EXTERN void
SPDY_stop_daemon (struct SPDY_Daemon *daemon);


/**
 * Obtain the select sets for this daemon. Only those are retrieved,
 * which some processing should be done for, i.e. not all sockets are
 * added to write_fd_set.<p>
 *
 * It is possible that there is
 * nothing to be read from a socket but there is data either in the
 * TLS subsystem's read buffers or in libmicrospdy's read buffers, which
 * waits for being processed. In such case the file descriptor will be
 * added to write_fd_set. Since it is very likely for the socket to be
 * ready for writing, the select used in the application's event loop
 * will return with success, SPDY_run will be called, the data will be
 * processed and maybe something will be written to the socket. Without
 * this behaviour, considering a proper event loop, data may stay in the
 * buffers, but run is never called.
 *
 * @param daemon to get sets from
 * @param read_fd_set read set
 * @param write_fd_set write set
 * @param except_fd_set except set
 * @return largest FD added to any of the sets
 */
_MHD_EXTERN int
SPDY_get_fdset (struct SPDY_Daemon *daemon,
                fd_set *read_fd_set,
                fd_set *write_fd_set,
                fd_set *except_fd_set);


/**
 * Obtain timeout value for select for this daemon. The returned value
 * is how long select
 * should at most block, not the timeout value set for connections.
 *
 * @param daemon to query for timeout
 * @param timeout will be set to the timeout value (in milliseconds)
 * @return #SPDY_YES on success
 *         #SPDY_NO if no connections exist that
 * 			would necessiate the use of a timeout right now
 */
_MHD_EXTERN int
SPDY_get_timeout (struct SPDY_Daemon *daemon,
                  unsigned long long *timeout);


/**
 * Run webserver operations. This method must be called in
 * the client event loop.
 *
 * @param daemon to run
 */
_MHD_EXTERN void
SPDY_run (struct SPDY_Daemon *daemon);


/* SPDY Session handling functions */


/**
 * Closes a SPDY session. SPDY clients and servers are expected to keep
 * sessions opened as long as possible. However, the server may want to
 * close some connections, e.g. if there are too many, to free some
 * resources. The function can also be used to close a specific session
 * if the client is not desired.
 *
 * @param session handler to be closed
 */
_MHD_EXTERN void
SPDY_close_session (struct SPDY_Session * session);


/**
 * Associate a void pointer with a session. The data accessible by the
 * pointer can later be used wherever the session handler is available.
 *
 * @param session handler
 * @param cls any data pointed by a pointer to be accessible later
 */
_MHD_EXTERN void
SPDY_set_cls_to_session (struct SPDY_Session *session,
                         void *cls);


/**
 * Retrieves the pointer associated with SPDY_set_cls_to_session().
 *
 * @param session handler to get its cls
 * @return same pointer added by SPDY_set_cls_to_session() or
 * 			NULL when nothing was associated
 */
_MHD_EXTERN void *
SPDY_get_cls_from_session (struct SPDY_Session *session);


/**
 * Retrieves the remote address of a given session.
 *
 * @param session handler to get its remote address
 * @param addr out parameter; pointing to remote address
 * @return length of the address structure
 */
_MHD_EXTERN socklen_t
SPDY_get_remote_addr (struct SPDY_Session *session,
                      struct sockaddr **addr);


/* SPDY name/value data structure handling functions */


/**
 * Create a new NameValue structure. It is needed for putting inside the
 * HTTP headers and their values for a response. The user should later
 * destroy alone the structure.
 *
 * @return handler to the new empty structure or NULL on error
 */
_MHD_EXTERN struct SPDY_NameValue *
SPDY_name_value_create (void);


/**
 * Add name/value pair to a NameValue structure. SPDY_NO will be returned
 * if the name/value pair is already in the structure. It is legal to
 * add different values for the same name.
 *
 * @param container structure to which the new pair is added
 * @param name for the value. Null-terminated string.
 * @param value the value itself. Null-terminated string.
 * @return #SPDY_NO on error or #SPDY_YES on success
 */
_MHD_EXTERN int
SPDY_name_value_add (struct SPDY_NameValue *container,
                     const char *name,
                     const char *value);


/**
 * Lookup value for a name in a name/value structure.
 *
 * @param container structure in which to lookup
 * @param name the name to look for
 * @param num_values length of the returned array with values
 * @return NULL if no such item was found, or an array containing the
 * 			values
 */
_MHD_EXTERN const char * const *
SPDY_name_value_lookup (struct SPDY_NameValue *container,
                        const char *name,
                        int *num_values);


/**
 * Iterate over name/value structure.
 *
 * @param container structure which to iterate over
 * @param iterator callback to call on each name/value pair;
 *        maybe NULL (then just count headers)
 * @param iterator_cls extra argument to @a iterator
 * @return number of entries iterated over
 */
_MHD_EXTERN int
SPDY_name_value_iterate (struct SPDY_NameValue *container,
                         SPDY_NameValueIterator iterator,
                         void *iterator_cls);


/**
 * Destroy a NameValue structure. Use this function to destroy only
 * objects which, after passed to, will not be destroied by other
 * functions.
 *
 */
_MHD_EXTERN void
SPDY_name_value_destroy (struct SPDY_NameValue *container);


/* SPDY request handling functions */


/**
 * Gets the session responsible for the given
 * request.
 *
 * @param request for which the session is wanted
 * @return session handler for the request
 */
_MHD_EXTERN struct SPDY_Session *
SPDY_get_session_for_request (const struct SPDY_Request *request);


/**
 * Associate a void pointer with a request. The data accessible by the
 * pointer can later be used wherever the request handler is available.
 *
 * @param request with which to associate a pointer
 * @param cls any data pointed by a pointer to be accessible later
 */
_MHD_EXTERN void
SPDY_set_cls_to_request (struct SPDY_Request *request,
                         void *cls);


/**
 * Retrieves the pointer associated with the request by
 * SPDY_set_cls_to_request().
 *
 * @param request to get its cls
 * @return same pointer added by SPDY_set_cls_to_request() or
 * 			NULL when nothing was associated
 */
_MHD_EXTERN void *
SPDY_get_cls_from_request (struct SPDY_Request *request);


/* SPDY response handling functions */


/**
 * Create response object containing all needed headers and data. The
 * response object is not bound to a request, so it can be used multiple
 * times with SPDY_queue_response() and schould be
 * destroied by calling the SPDY_destroy_response().<p>
 *
 * Currently the library does not provide compression of the body data.
 * It is up to the user to pass already compressed data and the
 * appropriate headers to this function when desired.
 *
 * @param status HTTP status code for the response (e.g. 404)
 * @param statustext HTTP status message for the response, which will
 * 			be appended to the status code (e.g. "OK"). Can be NULL
 * @param version HTTP version for the response (e.g. "http/1.1")
 * @param headers name/value structure containing additional HTTP headers.
 *                Can be NULL. Can be used multiple times, it is up to
 *                the user to destoy the object when not needed anymore.
 * @param data the body of the response. The lib will make a copy of it,
 *             so it is up to the user to take care of the memory
 *             pointed by data
 * @param size length of @a data. It can be 0, then the lib will send only
 * 				headers
 * @return NULL on error, handle to response object on success
 */
_MHD_EXTERN struct SPDY_Response *
SPDY_build_response (int status,
                     const char *statustext,
                     const char *version,
                     struct SPDY_NameValue *headers,
                     const void *data,
                     size_t size);


/**
 * Create response object containing all needed headers. The data will
 * be provided later when the lib calls the callback function (just
 * before writing it to the TLS socket). The
 * response object is not bound to a request, so it can be used multiple
 * times with SPDY_queue_response() and schould be
 * destroied by calling the SPDY_destroy_response().<p>
 *
 * Currently the library does not provide compression of the body data.
 * It is up to the user to pass already compressed data and the
 * appropriate headers to this function and the callback when desired.
 *
 * @param status HTTP status code for the response (e.g. 404)
 * @param statustext HTTP status message for the response, which will
 * 			be appended to the status code (e.g. "OK"). Can be NULL
 * @param version HTTP version for the response (e.g. "http/1.1")
 * @param headers name/value structure containing additional HTTP headers.
 *                Can be NULL. Can be used multiple times, it is up to
 *                the user to destoy the object when not needed anymore.
 * @param rcb callback to use to obtain response data
 * @param rcb_cls extra argument to @a rcb
 * @param block_size preferred block size for querying rcb (advisory only,
 *                   the lib will call rcb specifying the block size); clients
 *                   should pick a value that is appropriate for IO and
 *                   memory performance requirements. The function will
 *                   fail if the value is bigger than the maximum
 *                   supported value (SPDY_MAX_SUPPORTED_FRAME_SIZE).
 *                   Can be 0, then the lib will use
 *                   #SPDY_MAX_SUPPORTED_FRAME_SIZE instead.
 * @return NULL on error, handle to response object on success
 */
_MHD_EXTERN struct SPDY_Response *
SPDY_build_response_with_callback(int status,
                                  const char *statustext,
                                  const char *version,
                                  struct SPDY_NameValue *headers,
                                  SPDY_ResponseCallback rcb,
                                  void *rcb_cls,
                                  uint32_t block_size);


/**
 * Queue response object to be sent to the client. A successfully queued
 * response may never be sent, e.g. when the stream gets closed. The
 * data will be added to the output queue. The call will fail, if the
 * output for this session
 * is closed (i.e. the session is closed, half or full) or the output
 * channel for the stream, on which the request was received, is closed
 * (i.e. the stream is closed, half or full).
 *
 * @param request object identifying the request to which the
 * 			response is returned
 * @param response object containg headers and data to be sent
 * @param closestream TRUE if the server does NOT intend to PUSH
 * 			something more associated to this request/response later,
 * 			FALSE otherwise
 * @param consider_priority if FALSE, the response will be added to the
 * 			end of the queue. If TRUE, the response will be added after
 * 			the last previously added response with priority of the
 * 			request grater or equal to that of the current one. This
 * 			means that the function should be called with TRUE each time
 * 			if one wants to be sure that the output queue behaves like
 * 			a priority queue
 * @param rrcb callback called when all the data was sent (last frame
 * 			from response) or when that frame was discarded (e.g. the
 * 			stream has been closed meanwhile)
 * @param rrcb_cls extra argument to @a rrcb
 * @return #SPDY_NO on error or #SPDY_YES on success
 */
_MHD_EXTERN int
SPDY_queue_response (struct SPDY_Request *request,
                     struct SPDY_Response *response,
                     bool closestream,
                     bool consider_priority,
                     SPDY_ResponseResultCallback rrcb,
                     void *rrcb_cls);


/**
 * Destroy a response structure. It should be called for all objects
 * returned by SPDY_build_response*() functions to free the memory
 * associated with the prepared response. It is safe to call this
 * function not before being sure that the response will not be used by
 * the lib anymore, this means after SPDY_ResponseResultCallback
 * callbacks were called for all calls to SPDY_queue_response() passing
 * this response.
 *
 * @param response to destroy
 */
_MHD_EXTERN void
SPDY_destroy_response (struct SPDY_Response *response);


/* SPDY settings ID/value data structure handling functions */


/**
 * Create a new SettingsIDValue structure. It is needed for putting
 * inside tuples of SPDY option, flags and value for sending to the
 * client.
 *
 * @return hendler to the new empty structure or NULL on error
 */
_MHD_EXTERN const struct SPDY_Settings *
SPDY_settings_create (void);


/**
 * Add or update a tuple to a SettingsIDValue structure.
 *
 * @param container structure to which the new tuple is added
 * @param id SPDY settings ID that will be sent. If this ID already in
 *           container, the tupple for it will be updated (value and/or
 *           flags). If it is not in the container, a new tupple will be
 *           added.
 * @param flags SPDY settings flags applied only to this setting
 * @param value of the setting
 * @return #SPDY_NO on error
 * 			or #SPDY_YES if a new setting was added
 */
_MHD_EXTERN int
SPDY_settings_add (struct SPDY_Settings *container,
                   enum SPDY_SETTINGS id,
                   enum SPDY_FLAG_SETTINGS flags,
                   int32_t value);


/**
 * Lookup value and flags for an ID in a settings ID/value structure.
 *
 * @param container structure in which to lookup
 * @param id SPDY settings ID to search for
 * @param flags out param for SPDY settings flags for this setting;
 * 			check it against the flags in enum SPDY_FLAG_SETTINGS
 * @param value out param for the value of this setting
 * @return #SPDY_NO if the setting is not into the structure
 * 			or #SPDY_YES if it is into it
 */
_MHD_EXTERN int
SPDY_settings_lookup (const struct SPDY_Settings *container,
                      enum SPDY_SETTINGS id,
                      enum SPDY_FLAG_SETTINGS *flags,
                      int32_t *value);


/**
 * Iterate over settings ID/value structure.
 *
 * @param container structure which to iterate over
 * @param iterator callback to call on each ID/value pair;
 *        maybe NULL (then just count number of settings)
 * @param iterator_cls extra argument to iterator
 * @return number of entries iterated over
 */
_MHD_EXTERN int
SPDY_settings_iterate (const struct SPDY_Settings *container,
                       SPDY_SettingsIterator iterator,
                       void *iterator_cls);


/**
 * Destroy a settings ID/value structure. Use this function to destroy
 * only objects which, after passed to, will not be destroied by other
 * functions.
 *
 * @param container structure which to detroy
 */
_MHD_EXTERN void
SPDY_settings_destroy (struct SPDY_Settings * container);


/* SPDY SETTINGS handling functions */


/**
 * Send SPDY SETTINGS to the client. The call will return fail if there
 * in invald setting into the settings container (e.g. invalid setting
 * ID).
 *
 * @param session SPDY_Session handler for which settings are being sent
 * @param settings ID/value pairs of the settings to be sent.
 * 			Can be used multiple times, it is up to the user to destoy
 * 			the object when not needed anymore.
 * @param flags for the whole settings frame. They are valid for all tuples
 * @param ... list of options (type-value pairs,
 *        terminated with #SPDY_SETTINGS_OPTION_END).
 * @return SPDY_NO on error or SPDY_YES on
 * 			success
 */
_MHD_EXTERN int
SPDY_send_settings (struct SPDY_Session *session,
                    struct SPDY_Settings *settings,
                    enum SPDY_FLAG_SETTINGS_FRAME flags,
                    ...);


/* SPDY misc functions */


/**
 * Destroy a request structure. It should be called for all objects
 * received as a parameter in SPDY_NewRequestCallback to free the memory
 * associated with the request. It is safe to call this
 * function not before being sure that the request will not be used by
 * the lib anymore, this means after the stream, on which this request
 * had been sent, was closed and all SPDY_ResponseResultCallback
 * callbacks were called for all calls to SPDY_queue_response() passing
 * this request object.
 *
 * @param request to destroy
 */
_MHD_EXTERN void
SPDY_destroy_request (struct SPDY_Request * request);


/**
 * Send SPDY ping to the client
 *
 * @param session handler for which the ping request is sent
 * @param rttcb callback called when ping response to the request is
 * 			received
 * @param rttcb_cls extra argument to @a rttcb
 * @return #SPDY_NO on error or #SPDY_YES on success
 */
_MHD_EXTERN int
SPDY_send_ping (struct SPDY_Session *session,
                SPDY_PingCallback rttcb,
                void *rttcb_cls);

#endif