Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

http.h File Reference


Detailed Description

HTTP routines.

Author:
Raphael Manfredi
Date:
2002-2003

#include "if/core/http.h"
#include "lib/host_addr.h"

Go to the source code of this file.

Data Structures

struct  http_extra_desc_t
struct  http_error_t
struct  http_buffer
 HTTP data buffered when it cannot be sent out immediately. More...


Defines

#define HTTP_PORT   80 /**< Registered HTTP port */
 Registered HTTP port.

#define he_msg   u.u_msg
#define he_cb   u.u_cbk.u_cb
#define he_arg   u.u_cbk.u_arg
#define HTTP_CBF_SMALL_REPLY   0x00000001 /**< Try to emit smallest reply */
 Try to emit smallest reply.

#define HTTP_CBF_BW_SATURATED   0x00000002 /**< Bandwidth is saturated */
 Bandwidth is saturated.

#define HTTP_CBF_BUSY_SIGNAL   0x00000004 /**< Sending back a 503 "busy" */
 Sending back a 503 "busy".

#define HTTP_CBF_SHOW_RANGES   0x00000008 /**< Show available ranges */
 Show available ranges.

#define HTTP_ASYNC_OK   0 /**< OK */
 OK.

#define HTTP_ASYNC_BAD_URL   1 /**< Invalid HTTP URL */
 Invalid HTTP URL.

#define HTTP_ASYNC_CONN_FAILED   2 /**< Connection failed */
 Connection failed.

#define HTTP_ASYNC_IO_ERROR   3 /**< I/O error */
 I/O error.

#define HTTP_ASYNC_REQ2BIG   4 /**< Request too big */
 Request too big.

#define HTTP_ASYNC_HEAD2BIG   5 /**< Header too big */
 Header too big.

#define HTTP_ASYNC_CANCELLED   6 /**< User cancel */
 User cancel.

#define HTTP_ASYNC_EOF   7 /**< Got EOF */
 Got EOF.

#define HTTP_ASYNC_BAD_STATUS   8 /**< Unparseable HTTP status */
 Unparseable HTTP status.

#define HTTP_ASYNC_NO_LOCATION   9 /**< Got moved status, but no location */
 Got moved status, but no location.

#define HTTP_ASYNC_CONN_TIMEOUT   10 /**< Connection timeout */
 Connection timeout.

#define HTTP_ASYNC_TIMEOUT   11 /**< Data timeout */
 Data timeout.

#define HTTP_ASYNC_NESTED   12 /**< Nested redirections */
 Nested redirections.

#define HTTP_ASYNC_BAD_LOCATION_URI   13 /**< Invalid URI in Location header */
 Invalid URI in Location header.

#define HTTP_ASYNC_CLOSED   14 /**< Connection was closed, all OK */
 Connection was closed, all OK.

#define HTTP_ASYNC_REDIRECTED   15 /**< Redirected, following disabled */
 Redirected, following disabled.

#define http_buffer_base(hb)   ((hb)->hb_arena)
#define http_buffer_length(hb)   ((hb)->hb_len)
#define http_buffer_read_base(hb)   ((hb)->hb_rptr)
#define http_buffer_unread(hb)   ((hb)->hb_end - (hb)->hb_rptr)
#define http_buffer_add_read(hb, tx)   do { (hb)->hb_rptr += (tx); } while (0)

Typedefs

typedef void(* http_status_cb_t )(gchar *buf, gint *retlen, gpointer arg, guint32 flags)
 The callback used to generate custom headers.

typedef gboolean(* http_header_cb_t )(gpointer h, struct header *header, gint code, const gchar *message)
 Callback used from asynchronous request to indicate that we got headers.

typedef void(* http_data_cb_t )(gpointer h, gchar *data, gint len)
 Callback used from asynchronous request to indicate that data is available.

typedef void(* http_error_cb_t )(gpointer h, http_errtype_t error, gpointer val)
 Callback used from asynchronous request to indicate that an error occurred.

typedef void(* http_user_free_t )(gpointer data)
 Callabck to free user opaque data.

typedef size_t(* http_op_request_t )(gpointer handle, gchar *buf, size_t len, const gchar *verb, const gchar *path, const gchar *host, guint16 port)
 Asynchronous operations that the user may redefine.

typedef void(* http_state_change_t )(gpointer handle, http_state_t newstate)
 Callback to notify about state changes in HTTP request.

typedef http_buffer http_buffer_t
 HTTP data buffered when it cannot be sent out immediately.


Enumerations

enum  http_extra_type_t { HTTP_EXTRA_LINE, HTTP_EXTRA_CALLBACK, HTTP_EXTRA_BODY }
 http_send_status() additional header description: More...

enum  http_errtype_t { HTTP_ASYNC_SYSERR, HTTP_ASYNC_ERROR, HTTP_ASYNC_HEADER, HTTP_ASYNC_HTTP }
enum  http_url_error_t {
  HTTP_URL_OK = 0, HTTP_URL_NOT_HTTP, HTTP_URL_MULTIPLE_CREDENTIALS, HTTP_URL_BAD_CREDENTIALS,
  HTTP_URL_BAD_PORT_PARSING, HTTP_URL_BAD_PORT_RANGE, HTTP_URL_BAD_HOST_PART, HTTP_URL_HOSTNAME_UNKNOWN,
  HTTP_URL_MISSING_URI
}
 Error codes from http_url_parse(). More...


Functions

void http_timer (time_t now)
 Called from main timer to expire HTTP requests that take too long.

gboolean http_send_status (struct gnutella_socket *s, gint code, gboolean keep_alive, http_extra_desc_t *hev, gint hevcnt, const gchar *reason,...) G_GNUC_PRINTF(6
void http_hostname_add (gchar *buf, gint *retval, gpointer arg, guint32 flags)
 HTTP status callback.

gint http_status_parse (const gchar *line, const gchar *proto, const gchar **msg, guint *major, guint *minor)
 Parse protocol status line, and return the status code, and optionally a pointer within the string where the status message starts (if `msg' is a non-null pointer), and the protocol major/minor (if `major' and `minor' are non-null).

gboolean http_extract_version (const gchar *request, gint len, guint *major, guint *minor)
 Extract HTTP version major/minor out of the given request, whose string length is `len' bytes.

http_buffer_thttp_buffer_alloc (gchar *buf, size_t len, size_t written)
 Allocate HTTP buffer, capable of holding data at `buf', of `len' bytes, and whose `written' bytes have already been sent out.

void http_buffer_free (http_buffer_t *b)
 Dispose of HTTP buffer.

gint http_content_range_parse (const gchar *buf, filesize_t *start, filesize_t *end, filesize_t *total)
 Parses the content of a Content-Range header.

filesize_t http_range_size (const GSList *list)
void http_range_free (GSList *list)
 Free list of http_range_t objects.

GSList * http_range_parse (const gchar *field, const gchar *value, filesize_t size, const gchar *vendor)
 Parse a Range: header in the request, returning the list of ranges that are enumerated.

gboolean http_range_contains (GSList *ranges, filesize_t from, filesize_t to)
 Checks whether range contains the contiguous [from, to] interval.

const gchar * http_url_strerror (http_url_error_t errnum)
gboolean http_url_parse (const gchar *url, guint16 *port, const gchar **host, const gchar **path)
 Parse HTTP url and extract the IP/port we need to connect to.

gpointer http_async_get (gchar *url, http_header_cb_t header_ind, http_data_cb_t data_ind, http_error_cb_t error_ind)
 Starts an asynchronous HTTP GET request on the specified path.

gpointer http_async_get_addr (gchar *path, const host_addr_t, guint16 port, http_header_cb_t header_ind, http_data_cb_t data_ind, http_error_cb_t error_ind)
 Same as http_async_get(), but a path on the server is given and the IP and port to contact are given explicitly.

const gchar * http_async_strerror (guint errnum)
const gchar * http_async_info (gpointer handle, const gchar **req, gchar **path, host_addr_t *addr, guint16 *port)
 Get URL and request information, given opaque handle.

void http_async_connected (gpointer handle)
 Callback from the socket layer when the connection to the remote server is made.

void http_async_close (gpointer handle)
 Close request.

void http_async_cancel (gpointer handle)
 Cancel request (user request).

void http_async_error (gpointer handle, gint code)
 Cancel request (internal error).

http_state_t http_async_state (gpointer handle)
 Get the state of the HTTP request.

void http_async_set_opaque (gpointer handle, gpointer data, http_user_free_t fn)
 Set user-defined opaque data, which can optionally be freed via `fn' if a non-NULL function pointer is given.

gpointer http_async_get_opaque (gpointer handle)
 Retrieve user-defined opaque data.

void http_async_log_error (gpointer handle, http_errtype_t type, gpointer v)
 Default error indication callback which logs the error by listing the initial HTTP request and the reported error cause.

void http_async_log_error_dbg (gpointer handle, http_errtype_t type, gpointer v, guint32 dbg_level)
 Error indication callback which logs the error by listing the initial HTTP request and the reported error cause.

void http_async_on_state_change (gpointer handle, http_state_change_t fn)
 Defines callback to invoke when the request changes states.

void http_async_allow_redirects (gpointer handle, gboolean allow)
 Whether we should follow HTTP redirections (FALSE by default).

void http_async_set_op_request (gpointer handle, http_op_request_t op)
 Redefines the building of the HTTP request.

void http_close (void)
 Shutdown the HTTP module.


Variables

guint http_async_errno
 Used to return error codes during setup.

http_url_error_t http_url_errno
 Error from http_url_parse().


Define Documentation

#define he_arg   u.u_cbk.u_arg
 

#define he_cb   u.u_cbk.u_cb
 

#define he_msg   u.u_msg
 

#define HTTP_ASYNC_BAD_LOCATION_URI   13 /**< Invalid URI in Location header */
 

Invalid URI in Location header.

#define HTTP_ASYNC_BAD_STATUS   8 /**< Unparseable HTTP status */
 

Unparseable HTTP status.

#define HTTP_ASYNC_BAD_URL   1 /**< Invalid HTTP URL */
 

Invalid HTTP URL.

#define HTTP_ASYNC_CANCELLED   6 /**< User cancel */
 

User cancel.

#define HTTP_ASYNC_CLOSED   14 /**< Connection was closed, all OK */
 

Connection was closed, all OK.

#define HTTP_ASYNC_CONN_FAILED   2 /**< Connection failed */
 

Connection failed.

#define HTTP_ASYNC_CONN_TIMEOUT   10 /**< Connection timeout */
 

Connection timeout.

#define HTTP_ASYNC_EOF   7 /**< Got EOF */
 

Got EOF.

#define HTTP_ASYNC_HEAD2BIG   5 /**< Header too big */
 

Header too big.

#define HTTP_ASYNC_IO_ERROR   3 /**< I/O error */
 

I/O error.

#define HTTP_ASYNC_NESTED   12 /**< Nested redirections */
 

Nested redirections.

#define HTTP_ASYNC_NO_LOCATION   9 /**< Got moved status, but no location */
 

Got moved status, but no location.

#define HTTP_ASYNC_OK   0 /**< OK */
 

OK.

#define HTTP_ASYNC_REDIRECTED   15 /**< Redirected, following disabled */
 

Redirected, following disabled.

#define HTTP_ASYNC_REQ2BIG   4 /**< Request too big */
 

Request too big.

#define HTTP_ASYNC_TIMEOUT   11 /**< Data timeout */
 

Data timeout.

#define http_buffer_add_read hb,
tx   )     do { (hb)->hb_rptr += (tx); } while (0)
 

#define http_buffer_base hb   )     ((hb)->hb_arena)
 

#define http_buffer_length hb   )     ((hb)->hb_len)
 

#define http_buffer_read_base hb   )     ((hb)->hb_rptr)
 

#define http_buffer_unread hb   )     ((hb)->hb_end - (hb)->hb_rptr)
 

#define HTTP_CBF_BUSY_SIGNAL   0x00000004 /**< Sending back a 503 "busy" */
 

Sending back a 503 "busy".

#define HTTP_CBF_BW_SATURATED   0x00000002 /**< Bandwidth is saturated */
 

Bandwidth is saturated.

#define HTTP_CBF_SHOW_RANGES   0x00000008 /**< Show available ranges */
 

Show available ranges.

#define HTTP_CBF_SMALL_REPLY   0x00000001 /**< Try to emit smallest reply */
 

Try to emit smallest reply.

#define HTTP_PORT   80 /**< Registered HTTP port */
 

Registered HTTP port.


Typedef Documentation

typedef struct http_buffer http_buffer_t
 

HTTP data buffered when it cannot be sent out immediately.

typedef void(* http_data_cb_t)(gpointer h, gchar *data, gint len)
 

Callback used from asynchronous request to indicate that data is available.

typedef void(* http_error_cb_t)(gpointer h, http_errtype_t error, gpointer val)
 

Callback used from asynchronous request to indicate that an error occurred.

The type of `val' depends on the `error'.

typedef gboolean(* http_header_cb_t)( gpointer h, struct header *header, gint code, const gchar *message)
 

Callback used from asynchronous request to indicate that we got headers.

Indicates whether we should continue or not, given the HTTP response code.

typedef size_t(* http_op_request_t)(gpointer handle, gchar *buf, size_t len, const gchar *verb, const gchar *path, const gchar *host, guint16 port)
 

Asynchronous operations that the user may redefine.

typedef void(* http_state_change_t)(gpointer handle, http_state_t newstate)
 

Callback to notify about state changes in HTTP request.

typedef void(* http_status_cb_t)( gchar *buf, gint *retlen, gpointer arg, guint32 flags)
 

The callback used to generate custom headers.

Parameters:
`buf' is where the callback can generate extra data.
`retlen' is initially filled with the room available in `buf'.
`arg' is user-supplied data.
`flags' are extra flags passed by callback invoker
The callback is expected to fill `buf' and return the length of written data into `retlen'.

typedef void(* http_user_free_t)(gpointer data)
 

Callabck to free user opaque data.


Enumeration Type Documentation

enum http_errtype_t
 

Enumeration values:
HTTP_ASYNC_SYSERR  System error, value is errno.
HTTP_ASYNC_ERROR  Internal error, value is error code.
HTTP_ASYNC_HEADER  Internal header error, value is error code.
HTTP_ASYNC_HTTP  HTTP error, value is http_error_t pointer.

enum http_extra_type_t
 

http_send_status() additional header description:

Enumeration values:
HTTP_EXTRA_LINE 
HTTP_EXTRA_CALLBACK 
HTTP_EXTRA_BODY 

enum http_url_error_t
 

Error codes from http_url_parse().

Enumeration values:
HTTP_URL_OK  All OK.
HTTP_URL_NOT_HTTP  Not an http URI.
HTTP_URL_MULTIPLE_CREDENTIALS  More than one "<user>:<password>".
HTTP_URL_BAD_CREDENTIALS  Truncated "<user>:<password>".
HTTP_URL_BAD_PORT_PARSING  Could not parse port.
HTTP_URL_BAD_PORT_RANGE  Port value is out of range.
HTTP_URL_BAD_HOST_PART  Could not parse host.
HTTP_URL_HOSTNAME_UNKNOWN  Could not resolve host into IP.
HTTP_URL_MISSING_URI  URL has no URI part.


Function Documentation

void http_async_allow_redirects gpointer  handle,
gboolean  allow
 

Whether we should follow HTTP redirections (FALSE by default).

void http_async_cancel gpointer  handle  ) 
 

Cancel request (user request).

void http_async_close gpointer  handle  ) 
 

Close request.

void http_async_connected gpointer  handle  ) 
 

Callback from the socket layer when the connection to the remote server is made.

void http_async_error gpointer  handle,
gint  code
 

Cancel request (internal error).

gpointer http_async_get gchar *  url,
http_header_cb_t  header_ind,
http_data_cb_t  data_ind,
http_error_cb_t  error_ind
 

Starts an asynchronous HTTP GET request on the specified path.

Returns:
a handle on the request if OK, NULL on error with the http_async_errno variable set before returning.
When data is available, `data_ind' will be called. When all data have been read, a final call to `data_ind' is made with no data. If there is no `data_ind' routine, the connection will be closed after reading the whole header.

On error, `error_ind' will be called, and upon return, the request will be automatically cancelled.

gpointer http_async_get_addr gchar *  path,
const  host_addr_t,
guint16  port,
http_header_cb_t  header_ind,
http_data_cb_t  data_ind,
http_error_cb_t  error_ind
 

Same as http_async_get(), but a path on the server is given and the IP and port to contact are given explicitly.

gpointer http_async_get_opaque gpointer  handle  ) 
 

Retrieve user-defined opaque data.

const gchar* http_async_info gpointer  handle,
const gchar **  req,
gchar **  path,
host_addr_t addr,
guint16 *  port
 

Get URL and request information, given opaque handle.

This can be used by client code to log request parameters.

Returns:
URL and fills `req' with the request type string (GET, POST, ...) if it is a non-NULL pointer, `path' with the request path, `addr' and `port' with the server address/port.

void http_async_log_error gpointer  handle,
http_errtype_t  type,
gpointer  v
 

Default error indication callback which logs the error by listing the initial HTTP request and the reported error cause.

void http_async_log_error_dbg gpointer  handle,
http_errtype_t  type,
gpointer  v,
guint32  dbg_level
 

Error indication callback which logs the error by listing the initial HTTP request and the reported error cause.

The specified debugging level is explicitly given.

void http_async_on_state_change gpointer  handle,
http_state_change_t  fn
 

Defines callback to invoke when the request changes states.

void http_async_set_op_request gpointer  handle,
http_op_request_t  op
 

Redefines the building of the HTTP request.

void http_async_set_opaque gpointer  handle,
gpointer  data,
http_user_free_t  fn
 

Set user-defined opaque data, which can optionally be freed via `fn' if a non-NULL function pointer is given.

http_state_t http_async_state gpointer  handle  ) 
 

Get the state of the HTTP request.

const gchar* http_async_strerror guint  errnum  ) 
 

Returns:
human-readable error string corresponding to error code `errnum'.

http_buffer_t* http_buffer_alloc gchar *  buf,
size_t  len,
size_t  written
 

Allocate HTTP buffer, capable of holding data at `buf', of `len' bytes, and whose `written' bytes have already been sent out.

void http_buffer_free http_buffer_t b  ) 
 

Dispose of HTTP buffer.

void http_close void   ) 
 

Shutdown the HTTP module.

gint http_content_range_parse const gchar *  buf,
filesize_t start,
filesize_t end,
filesize_t total
 

Parses the content of a Content-Range header.

Parameters:
buf should point the payload of a Content-Range header
start will be set to the ``start'' offset
end will be set to the ``end'' offset
total will be set to the ``total'' size of the requested object.
Returns:
-1 on error, zero on success.

gboolean http_extract_version const gchar *  request,
gint  len,
guint *  major,
guint *  minor
 

Extract HTTP version major/minor out of the given request, whose string length is `len' bytes.

Returns:
TRUE when we identified the "HTTP/x.x" trailing string, filling major and minor accordingly.

void http_hostname_add gchar *  buf,
gint *  retval,
gpointer  unused_arg,
guint32  flags
 

HTTP status callback.

Add an X-Hostname line bearing the fully qualified hostname.

gboolean http_range_contains GSList *  ranges,
filesize_t  from,
filesize_t  to
 

Checks whether range contains the contiguous [from, to] interval.

void http_range_free GSList *  list  ) 
 

Free list of http_range_t objects.

GSList* http_range_parse const gchar *  field,
const gchar *  value,
filesize_t  size,
const gchar *  vendor
 

Parse a Range: header in the request, returning the list of ranges that are enumerated.

Invalid ranges are ignored.

Only "bytes" ranges are supported.

When parsing a "bytes=" style, it means it's a request, so we allow negative ranges. Otherwise, for "bytes " specifications, it's a reply and we ignore negative ranges.

`size' gives the length of the resource, to resolve negative ranges and make sure we don't have ranges that extend past that size.

The `field' and `vendor' arguments are only there to log errors, if any.

Returns:
a sorted list of http_range_t objects.

filesize_t http_range_size const GSList *  list  ) 
 

Returns:
total size of all the ranges.

gboolean http_send_status struct gnutella_socket s,
gint  code,
gboolean  keep_alive,
http_extra_desc_t hev,
gint  hevcnt,
const gchar *  reason,
... 
 

gint http_status_parse const gchar *  line,
const gchar *  proto,
const gchar **  msg,
guint *  major,
guint *  minor
 

Parse protocol status line, and return the status code, and optionally a pointer within the string where the status message starts (if `msg' is a non-null pointer), and the protocol major/minor (if `major' and `minor' are non-null).

If `proto' is non-null, then when there is a leading protocol string in the reply, it must be equal to `proto'.

Returns:
-1 if it fails to parse the status line correctly, the status code otherwise.
We recognize the following status lines:

  • ZZZ 403 message (major=0, minor=0)
  • ZZZ/2.3 403 message (major=2, minor=3)
  • 403 message (major=0, minor=0)

We don't yet handle "SMTP-like continuations":

  • 403-message line #1
  • 403-message line #2
  • 403 last message line

There is no way to return the value of "ZZZ" via this routine.

Attention:
NB: this routine is also used to parse GNUTELLA status codes, since they follow the same pattern as HTTP status codes.

void http_timer time_t  now  ) 
 

Called from main timer to expire HTTP requests that take too long.

gboolean http_url_parse const gchar *  url,
guint16 *  port,
const gchar **  host,
const gchar **  path
 

Parse HTTP url and extract the IP/port we need to connect to.

Also identifies the start of the path to request on the server.

Returns:
TRUE if the URL was correctly parsed, with `port', 'host' and `path' filled if they are non-NULL, FALSE otherwise. The variable `http_url_errno' is set accordingly.

const gchar* http_url_strerror http_url_error_t  errnum  ) 
 

Returns:
human-readable error string corresponding to error code `errnum'.


Variable Documentation

guint http_async_errno
 

Used to return error codes during setup.

http_url_error_t http_url_errno
 

Error from http_url_parse().


Generated on Sun Feb 12 10:50:03 2006 for Gtk-Gnutella by doxygen 1.3.6