http.h

mms client

 */
typedef struct HTTPClient HTTPClient;


/*
 * Open an HTTP server at a given port. Return -1 for errors (invalid
 * port number, etc), 0 for OK. This will also start a background thread
 * to listen for connections to that port and read the requests from them.
 * Second boolean variable indicates if the HTTP server should be started 
 * for SSL-enabled connections.
 */
int http_open_port(int port, int ssl);


/*
 * Same as above, but bind to a specific interface.
 */
int http_open_port_if(int port, int ssl, Octstr *interface);


/*
 * Accept a request from a client to the specified open port. Return NULL
 * if the port is closed, otherwise a pointer to a client descriptor.
 * Return the IP number (as a string) and other related information about
 * the request via arguments if function return value is non-NULL. The
 * caller is responsible for destroying the values returned via arguments,
 * the caller descriptor is destroyed by http_send_reply.
 *
 * The requests are actually read by a background thread handled by the
 * HTTP implementation, so it is not necessary by the HTTP user to have
 * many threads to be fast. The HTTP user should use a single thread,
 * unless requests can block.
 */
HTTPClient *http_accept_request(int port, Octstr **client_ip, 
    	    	    	    	Octstr **url, List **headers, Octstr **body,
				List **cgivars);


/*
 * Send a reply to a previously accepted request. The caller is responsible
 * for destroying the headers and body after the call to http_send_reply
 * finishes. This allows using them in several replies in an efficient way.
 */
void http_send_reply(HTTPClient *client, int status, List *headers, 
    	    	     Octstr *body);


/*
 * Don't send a reply to a previously accepted request, but only close
 * the connection to the client. This can be used to reject requests from
 * clients that are not authorized to access us.
 */
void http_close_client(HTTPClient *client);


/*
 * Close a currently open port and stop corresponding background threads.
 */
void http_close_port(int port);


/*
 * Close all currently open ports and stop background threads.
 */
void http_close_all_ports(void);


/*
 * Destroy a list of HTTPCGIVar objects.
 */
void http_destroy_cgiargs(List *args);


/*
 * Return reference to CGI argument 'name', or NULL if not matching.
 */
Octstr *http_cgi_variable(List *list, char *name);


/***********************************************************************
 * HTTP header interface.
 */


/*
 * Functions for manipulating a list of headers. You can use a list of
 * headers returned by one of the functions above, or create an empty
 * list with http_create_empty_headers. Use http_destroy_headers to
 * destroy a list of headers (not just the list, but the headers
 * themselves). You can also use http_parse_header_string to create a list:
 * it takes a textual representation of headers as an Octstr and returns
 * the corresponding List. http_generate_header_string goes the other
 * way.
 *
 * Once you have a list of headers, you can use http_header_add and the
 * other functions to manipulate it.
 */
List *http_create_empty_headers(void);
void http_destroy_headers(List *headers);
void http_header_add(List *headers, char *name, char *contents);
void http_header_get(List *headers, long i, Octstr **name, Octstr **value);
List *http_header_duplicate(List *headers);
void http_header_pack(List *headers);
void http_append_headers(List *to, List *from);
Octstr *http_header_value(List *headers, Octstr *header);


/*
 * Append all headers from new_headers to old_headers.  Headers from
 * new_headers _replace_ the ones in old_headers if they have the same
 * name.  For example, if you have:
 * old_headers
 *    Accept: text/html
 *    Accept: text/plain
 *    Accept: image/jpeg
 *    Accept-Language: en
 * new_headers
 *    Accept: text/html
 *    Accept: text/plain
 * then after the operation, old_headers will have
 *    Accept-Language: en
 *    Accept: text/html
 *    Accept: text/plain
 */
void http_header_combine(List *old_headers, List *new_headers);

/*
 * Return the length of the quoted-string (a HTTP field element)
 * starting at position pos in the header.  Return -1 if there
 * is no quoted-string at that position.
 */
long http_header_quoted_string_len(Octstr *header, long pos);


/*
 * Take the value part of a header that has a format that allows
 * multiple comma-separated elements, and split it into a list of
 * those elements.  Note that the function may have surprising
 * results for values of headers that are not in this format.
 */
List *http_header_split_value(Octstr *value);


/*
 * The same as http_header_split_value, except that it splits 
 * headers containing 'credentials' or 'challenge' lists, which
 * have a slightly different format.  It also normalizes the list
 * elements, so that parameters are introduced with ';'.
 */
List *http_header_split_auth_value(Octstr *value);


/*
 * Remove all headers with name 'name' from the list.  Return the
 * number of headers removed.
 */
long http_header_remove_all(List *headers, char *name);


/*
 * Remove the hop-by-hop headers from a header list.  These are the
 * headers that describe a specific connection, not anything about
 * the content.  RFC2616 section 13.5.1 defines these.
 */
void http_remove_hop_headers(List *headers);


/*
 * Update the headers to reflect that a transformation has been
 * applied to the entity body.
 */
void http_header_mark_transformation(List *headers, Octstr *new_body, 
    	    	    	    	     Octstr *new_type);


/*
 * Find the first header called `name' in `headers'. Returns its contents
 * as a new Octet string, which the caller must free. Return NULL for
 * not found.
 */
Octstr *http_header_find_first(List *headers, char *name);
List *http_header_find_all(List *headers, char *name);


/*
 * Find the Content-Type header and returns the type and charset.
 */
void http_header_get_content_type(List *headers, Octstr **type, 
	Octstr **charset);


/*
 * Do the headers indicate that MIME type `type' is accepted?
 */
int http_type_accepted(List *headers, char *type);


/*
 * Dump the contents of a header list with debug.
 */
void http_header_dump(List *headers);

/* 
 * Ditto with cgi variables. Do not panic, when an empty are found from the 
 * list.
 */
void http_cgivar_dump(List *cgiargs);

/*
 * Check for acceptable charset
 */
int http_charset_accepted(List *headers, char *charset);


/*
 * Add Basic Authentication headers headers.
 */
void http_add_basic_auth(List *headers, Octstr *username, Octstr *password);


/*
 * Return the general class of a status code.  For example, all
 * 2xx codes are HTTP_STATUS_SUCCESSFUL.  See the list at the top
 * of this file.
 */
int http_status_class(int code);


/*
 * Return the HTTP_METHOD_xxx enum code for a Octstr containing 
 * the HTTP method name.
 */
int http_name2method(Octstr *method);


/*
 * Return the char containing the HTTP method name.
 */
char *http_method2name(int method);


/* 
 * MJ - ASL make this function more widely available 
 */
 
/*
 * Parse the URL to get the hostname and the port to connect to and the
 * path within the host.
 *
 * Return -1 if the URL seems malformed.
 *
 * We assume HTTP URLs of the form specified in "3.2.2 http URL" in
 * RFC 2616:
 * 
 *  http_URL = "http:" "//" [ userid : password "@"] host [ ":" port ] [ abs_path [ "?" query ]] 
 */
int parse_url(Octstr *url, Octstr **host, long *port, Octstr **path, 
		     int *ssl, Octstr **username, Octstr **password);


#endif