http.h

mms client

/*
 * http.h - HTTP protocol implementation
 *
 * This header file defines the interface to the HTTP implementation
 * in Kannel.
 * 
 * We implement both the client and the server side of the protocol.
 * We don't implement HTTP completely - only those parts that Kannel needs.
 * You may or may not be able to use this code for other projects. It has
 * not been a goal, but it might be possible, though you do need other
 * parts of Kannel's gwlib as well.
 * 
 * Initialization
 * ==============
 *
 * The library MUST be initialized by a call to http_init. Failure to
 * initialize means the library WILL NOT work. Note that the library
 * can't initialize itself implicitly, because it cannot reliably
 * create a mutex to protect the initialization. Therefore, it is the
 * caller's responsibility to call http_init exactly once (no more, no
 * less) at the beginning of the process, before any other thread makes
 * any calls to the library.
 * 
 * Client functionality
 * ====================
 * 
 * The library will invisibly keep the connections to HTTP servers open,
 * so that it is possible to make several HTTP requests over a single
 * TCP connection. This makes it much more efficient in high-load situations.
 * On the other hand, if one request takes long, the library will still
 * use several connections to the same server anyway.
 * 
 * The library user can specify an HTTP proxy to be used. There can be only
 * one proxy at a time, but it is possible to specify a list of hosts for
 * which the proxy is not used. The proxy can be changed at run time.
 * 
 * Server functionality
 * ====================
 * 
 * The library allows the implementation of an HTTP server by having
 * functions to specify which ports should be open, and receiving requests
 * from those ports.
 * 
 * Header manipulation
 * ===================
 * 
 * The library additionally has some functions for manipulating lists of
 * headers. These take a `List' (see gwlib/list.h) of Octstr's. The list
 * represents a list of headers in an HTTP request or reply. The functions
 * manipulate the list by adding and removing headers by name. It is a
 * very bad idea to manipulate the list without using the header
 * manipulation functions, however.
 *
 * Basic Authentication
 * ====================
 *
 * Basic Authentication is the standard way for a client to authenticate
 * itself to a server. It is done by adding an "Authorization" header
 * to the request. The interface in this header therefore doesn't mention
 * it, but the client and the server can do it by checking the headers
 * using the generic functions provided.
 *
 * Acknowledgements
 * ================
 *
 * Design: Lars Wirzenius, Richard Braakman
 * Implementation: Lars Wirzenius
 */


#ifndef HTTP_H
#define HTTP_H

#include "gwlib/list.h"
#include "gwlib/octstr.h"


/*
 * Well-known return values from HTTP servers. This is not a complete
 * list, but it includes the values that Kannel needs to handle
 * specially.
 */

enum {
	HTTP_OK				= 200,
	HTTP_CREATED			= 201,
	HTTP_ACCEPTED			= 202,
	HTTP_NO_CONTENT			= 204,
	HTTP_RESET_CONTENT		= 205,
	HTTP_MOVED_PERMANENTLY		= 301,
	HTTP_FOUND			= 302,
	HTTP_SEE_OTHER			= 303,
	HTTP_NOT_MODIFIED		= 304,
	HTTP_TEMPORARY_REDIRECT 	= 307,
    HTTP_BAD_REQUEST        = 400,
    HTTP_UNAUTHORIZED       = 401,
    HTTP_FORBIDDEN          = 403,
	HTTP_NOT_FOUND			= 404,
	HTTP_REQUEST_ENTITY_TOO_LARGE   = 413,
    HTTP_UNSUPPORTED_MEDIA_TYPE     = 415,
	HTTP_INTERNAL_SERVER_ERROR	= 500,
	HTTP_NOT_IMPLEMENTED		= 501,
	HTTP_BAD_GATEWAY		= 502
};

/*
 * Groupings of the status codes listed above.
 * See the http_status_class() function.
 */

enum {
	HTTP_STATUS_PROVISIONAL = 100,
	HTTP_STATUS_SUCCESSFUL = 200,
	HTTP_STATUS_REDIRECTION = 300,
	HTTP_STATUS_CLIENT_ERROR = 400,
	HTTP_STATUS_SERVER_ERROR = 500,
	HTTP_STATUS_UNKNOWN = 0
};


/*
 * Methods supported by this HTTP library.  Currently not public but
 * probably should be.
 */
enum {
	HTTP_METHOD_GET = 1,
	HTTP_METHOD_POST = 2,
	HTTP_METHOD_HEAD = 3
};

/*
 * A structure describing a CGI-BIN argument/variable.
 */
typedef struct {
	Octstr *name;
	Octstr *value;
} HTTPCGIVar;


/*
 * Initialization function. This MUST be called before any other function
 * declared in this header file.
 */
void http_init(void);


/*
 * Shutdown function. This MUST be called when no other function
 * declared in this header file will be called anymore.
 */
void http_shutdown(void);


/***********************************************************************
 * HTTP proxy interface.
 */


/*
 * Functions for controlling proxy use. http_use_proxy sets the proxy to
 * use; if another proxy was already in use, it is closed and forgotten
 * about as soon as all existing requests via it have been served.
 *
 * http_close_proxy closes the current proxy connection, after any
 * pending requests have been served.
 */
void http_use_proxy(Octstr *hostname, int port, List *exceptions,
    	    	    Octstr *username, Octstr *password);
void http_close_proxy(void);


/***********************************************************************
 * HTTP client interface.
 */


/*
 * Functions for doing a GET request. The difference is that _real follows
 * redirections, plain http_get does not. Return value is the status
 * code of the request as a numeric value, or -1 if a response from the
 * server was not received. If return value is not -1, reply_headers and
 * reply_body are set and MUST be destroyed by caller.
 *
 * XXX these are going away in the future
 */
int http_get_real(int method, Octstr *url, List *request_headers, 
                  Octstr **final_url, List **reply_headers, 
                  Octstr **reply_body);

/*
 * An identification for a caller of HTTP. This is used with
 * http_start_request, and http_receive_result to route results to the right
 * callers.
 *
 * Implementation note: We use a List as the type so that we can use
 * that list for communicating the results. This makes it unnecessary
 * to map the caller identifier to a List internally in the HTTP module.
 */
typedef List HTTPCaller;


/*
 * Create an HTTP caller identifier.
 */
HTTPCaller *http_caller_create(void);


/*
 * Destroy an HTTP caller identifier. Those that aren't destroyed
 * explicitly are destroyed by http_shutdown.
 */
void http_caller_destroy(HTTPCaller *caller);


/*
 * Signal to a caller (presumably waiting in http_receive_result) that
 * we're entering shutdown phase. This will make http_receive_result
 * no longer block if the queue is empty.
 */
void http_caller_signal_shutdown(HTTPCaller *caller);


/*
 * Start an HTTP request. It will be completed in the background, and
 * the result will eventually be received by http_receive_result.
 * http_receive_result will return the id parameter passed to this function,
 * and the caller can use this to keep track of which request and which
 * response belong together. If id is NULL, it is changed to a non-null
 * value (NULL replies from http_receive_result are reserved for cases
 * when it doesn't return a reply).
 *
 * If `body' is NULL, it is a GET request, otherwise as POST request.
 * If `follow' is true, HTTP redirections are followed, otherwise not.
 *
 * 'certkeyfile' defines a filename where openssl looks for a PEM-encoded
 * certificate and a private key, if openssl is compiled in and an https 
 * URL is used. It can be NULL, in which case none is used and thus there 
 * is no ssl authentication, unless you have set a global one with
 * use_global_certkey_file() from conn.c.
 */
void http_start_request(HTTPCaller *caller, int method, Octstr *url, 
                        List *headers, Octstr *body, int follow, void *id, 
    	    	    	Octstr *certkeyfile); 


/*
 * Get the result of a GET or a POST request. Returns either the id pointer
 * (the one passed to http_start request if non-NULL) or NULL if
 * http_caller_signal_shutdown has been called and there are no queued results.
 */
void *http_receive_result(HTTPCaller *caller, int *status, Octstr **final_url,
    	    	    	 List **headers, Octstr **body);


/***********************************************************************
 * HTTP server interface.
 */


/*
 * Data structure representing an HTTP client that has connected to
 * the server we implement. It is used to route responses correctly.