core/http.h File Reference

---

Detailed Description

HTTP routines.

Author:

Raphael Manfredi

Date:

2002-2003

#include "common.h"
#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.
#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.
#define	HTTP_CBF_BW_SATURATED   0x00000002
	Bandwidth is saturated.
#define	HTTP_CBF_BUSY_SIGNAL   0x00000004
	Sending back a 503 "busy".
#define	HTTP_CBF_SHOW_RANGES   0x00000008
	Show available ranges.
#define	HTTP_ASYNC_OK   0
	OK.
#define	HTTP_ASYNC_BAD_URL   1
	Invalid HTTP URL.
#define	HTTP_ASYNC_CONN_FAILED   2
	Connection failed.
#define	HTTP_ASYNC_IO_ERROR   3
	I/O error.
#define	HTTP_ASYNC_REQ2BIG   4
	Request too big.
#define	HTTP_ASYNC_HEAD2BIG   5
	Header too big.
#define	HTTP_ASYNC_CANCELLED   6
	User cancel.
#define	HTTP_ASYNC_EOF   7
	Got EOF.
#define	HTTP_ASYNC_BAD_STATUS   8
	Unparseable HTTP status.
#define	HTTP_ASYNC_NO_LOCATION   9
	Got moved status, but no location.
#define	HTTP_ASYNC_CONN_TIMEOUT   10
	Connection timeout.
#define	HTTP_ASYNC_TIMEOUT   11
	Data timeout.
#define	HTTP_ASYNC_NESTED   12
	Nested redirections.
#define	HTTP_ASYNC_BAD_LOCATION_URI   13
	Invalid URI in Location header.
#define	HTTP_ASYNC_CLOSED   14
	Connection was closed, all OK.
#define	HTTP_ASYNC_REDIRECTED   15
	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 size_t(*	http_status_cb_t )(gchar *buf, size_t size, gpointer arg, guint32 flags)
	The callback used to generate custom headers.
typedef gboolean(*	http_header_cb_t )(struct http_async *, struct header *, gint code, const gchar *message)
	Callback used from asynchronous request to indicate that we got headers.
typedef void(*	http_data_cb_t )(struct http_async *, gchar *data, gint len)
	Callback used from asynchronous request to indicate that data is available.
typedef void(*	http_error_cb_t )(struct http_async *, 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)
	Callback to free user opaque data.
typedef size_t(*	http_op_request_t )(struct http_async *, 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 )(struct http_async *, 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_content_encoding_t { HTTP_CONTENT_ENCODING_IDENTITY, HTTP_CONTENT_ENCODING_DEFLATE, HTTP_CONTENT_ENCODING_GZIP }
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_extra_callback_set (http_extra_desc_t *he, http_status_cb_t callback, gpointer user_arg)
void	http_extra_line_set (http_extra_desc_t *he, const gchar *msg)
void	http_extra_body_set (http_extra_desc_t *he, const gchar *body)
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
size_t	http_hostname_add (gchar *buf, size_t size, gpointer arg, guint32 flags)
	HTTP status callback.
size_t	http_retry_after_add (gchar *buf, size_t size, 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, size_t len, guint *major, guint *minor)
	Extract HTTP version major/minor out of the given request, whose string length is `len' bytes.
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.
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.
http_async *	http_async_get (const 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.
http_async *	http_async_get_addr (const 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)
const gchar *	http_async_strerror (guint errnum)
const gchar *	http_async_info (struct http_async *handle, const gchar **req, const gchar **path, host_addr_t *addr, guint16 *port)
	Get URL and request information, given opaque handle.
void	http_async_connected (struct http_async *handle)
	Callback from the socket layer when the connection to the remote server is made.
void	http_async_close (struct http_async *handle)
	Close request.
void	http_async_cancel (struct http_async *handle)
	Cancel request (user request).
void	http_async_error (struct http_async *handle, gint code)
	Cancel request (internal error).
http_state_t	http_async_state (struct http_async *handle)
	Get the state of the HTTP request.
void	http_async_set_opaque (struct http_async *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 (struct http_async *handle)
	Retrieve user-defined opaque data.
void	http_async_log_error (struct http_async *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 (struct http_async *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 (struct http_async *handle, http_state_change_t fn)
	Defines callback to invoke when the request changes states.
void	http_async_allow_redirects (struct http_async *handle, gboolean allow)
	Whether we should follow HTTP redirections (FALSE by default).
void	http_async_set_op_request (struct http_async *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.

#define HTTP_ASYNC_BAD_STATUS   8

Unparseable HTTP status.

#define HTTP_ASYNC_BAD_URL   1

Invalid HTTP URL.

#define HTTP_ASYNC_CANCELLED   6

User cancel.

#define HTTP_ASYNC_CLOSED   14

Connection was closed, all OK.

#define HTTP_ASYNC_CONN_FAILED   2

Connection failed.

#define HTTP_ASYNC_CONN_TIMEOUT   10

Connection timeout.

#define HTTP_ASYNC_EOF   7

Got EOF.

#define HTTP_ASYNC_HEAD2BIG   5

Header too big.

#define HTTP_ASYNC_IO_ERROR   3

I/O error.

#define HTTP_ASYNC_NESTED   12

Nested redirections.

#define HTTP_ASYNC_NO_LOCATION   9

Got moved status, but no location.

#define HTTP_ASYNC_OK   0

OK.

#define HTTP_ASYNC_REDIRECTED   15

Redirected, following disabled.

#define HTTP_ASYNC_REQ2BIG   4

Request too big.

#define HTTP_ASYNC_TIMEOUT   11

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".

#define HTTP_CBF_BW_SATURATED   0x00000002

Bandwidth is saturated.

#define HTTP_CBF_SHOW_RANGES   0x00000008

Show available ranges.

#define HTTP_CBF_SMALL_REPLY   0x00000001

Try to emit smallest reply.

#define HTTP_PORT   80

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)(struct http_async *, gchar *data, gint len)

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

typedef void(* http_error_cb_t)(struct http_async *, 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)(struct http_async *, struct 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)(struct http_async *, 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)(struct http_async *, http_state_t newstate)

Callback to notify about state changes in HTTP request.

typedef size_t(* http_status_cb_t)(gchar *buf, size_t size, gpointer arg, guint32 flags)

The callback used to generate custom headers. Parameters: `buf'  is where the callback can generate extra data. `size'  is the size of buf in bytes. `arg'  is user-supplied data. `flags'  are extra flags passed by callback invoker The callback is expected to fill `buf' and return the amount of bytes written to buf.

typedef void(* http_user_free_t)(gpointer data)

Callback to free user opaque data.

---

Enumeration Type Documentation

enum http_content_encoding_t

Enumeration values: HTTP_CONTENT_ENCODING_IDENTITY  HTTP_CONTENT_ENCODING_DEFLATE  HTTP_CONTENT_ENCODING_GZIP

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 (  struct http_async *  handle, gboolean  allow )

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

void http_async_cancel (  struct http_async *  handle  )

Cancel request (user request).

void http_async_close (  struct http_async *  handle  )

Close request.

void http_async_connected (  struct http_async *  handle  )

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

void http_async_error (  struct http_async *  handle, gint  code )

Cancel request (internal error).

struct http_async* http_async_get (  const 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.

struct http_async* http_async_get_addr (  const 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 )

gpointer http_async_get_opaque (  struct http_async *  handle  )

Retrieve user-defined opaque data.

const gchar* http_async_info (  struct http_async *  handle, const gchar **  req, const 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 (  struct http_async *  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 (  struct http_async *  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 (  struct http_async *  handle, http_state_change_t  fn )

Defines callback to invoke when the request changes states.

void http_async_set_op_request (  struct http_async *  handle, http_op_request_t  op )

Redefines the building of the HTTP request.

void http_async_set_opaque (  struct http_async *  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 (  struct http_async *  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.

void http_extra_body_set (  http_extra_desc_t *  he, const gchar *  body )  [inline, static]

void http_extra_callback_set (  http_extra_desc_t *  he, http_status_cb_t  callback, gpointer  user_arg )  [inline, static]

void http_extra_line_set (  http_extra_desc_t *  he, const gchar *  msg )  [inline, static]

gboolean http_extract_version (  const gchar *  request, size_t  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.

size_t http_hostname_add (  gchar *  buf, size_t  size, 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.

size_t http_retry_after_add (  gchar *  buf, size_t  size, gpointer  arg, guint32  unused_flags )

HTTP status callback. Add a Retry-After header.

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().

---