soup-message

Name

soup-message -- 

Synopsis



enum        SoupKnownErrorCode;
enum        SoupErrorClass;
enum        SoupTransferStatus;
enum        SoupOwnership;
typedef     SoupDataBuffer;
struct      SoupMessage;
struct      SoupMessagePrivate;
void        (*SoupCallbackFn)               (SoupMessage *req,
                                             gpointer user_data);
SoupMessage* soup_message_new               (SoupContext *context,
                                             const gchar *method);
SoupMessage* soup_message_new_full          (SoupContext *context,
                                             const gchar *method,
                                             SoupOwnership req_owner,
                                             gchar *req_body,
                                             gulong req_length);
void        soup_message_free               (SoupMessage *req);
void        soup_message_cancel             (SoupMessage *req);
SoupErrorClass soup_message_send            (SoupMessage *msg);
void        soup_message_queue              (SoupMessage *req,
                                             SoupCallbackFn callback,
                                             gpointer user_data);
void        soup_message_set_request_header (SoupMessage *req,
                                             const gchar *name,
                                             const gchar *value);
const gchar* soup_message_get_request_header
                                            (SoupMessage *req,
                                             const gchar *name);
void        soup_message_set_response_header
                                            (SoupMessage *req,
                                             const gchar *name,
                                             const gchar *value);
const gchar* soup_message_get_response_header
                                            (SoupMessage *req,
                                             const gchar *name);
enum        SoupMessageFlags;
void        soup_message_set_flags          (SoupMessage *msg,
                                             guint flags);
guint       soup_message_get_flags          (SoupMessage *msg);

Description

Details

enum SoupKnownErrorCode

typedef enum {
	/*
	 * Transport Errors
	 */
	SOUP_ERROR_CANCELLED                = 1,
	SOUP_ERROR_CANT_CONNECT             = 2,
	SOUP_ERROR_CANT_CONNECT_PROXY       = 3,
	SOUP_ERROR_IO                       = 4,
	SOUP_ERROR_MALFORMED                = 5,
	SOUP_ERROR_CANT_AUTHENTICATE        = 6,
	SOUP_ERROR_CANT_AUTHENTICATE_PROXY  = 7,

	/*
	 * HTTP Response Codes
	 */
	SOUP_ERROR_CONTINUE                 = 100,
	SOUP_ERROR_PROTOCOL_SWITCH          = 101,
	SOUP_ERROR_DAV_PROCESSING           = 102,

	SOUP_ERROR_OK                       = 200,
	SOUP_ERROR_CREATED                  = 201,
	SOUP_ERROR_ACCEPTED                 = 202,
	SOUP_ERROR_NON_AUTHORITATIVE        = 203,
	SOUP_ERROR_NO_CONTENT               = 204,
	SOUP_ERROR_RESET_CONTENT            = 205,
	SOUP_ERROR_PARTIAL_CONTENT          = 206,
	SOUP_ERROR_DAV_MULTISTATUS          = 207,

	SOUP_ERROR_MULTIPLE_CHOICES         = 300,
	SOUP_ERROR_MOVED_PERMANANTLY        = 301,
	SOUP_ERROR_FOUND                    = 302,
	SOUP_ERROR_MOVED_TEMPORARILY        = SOUP_ERROR_FOUND,
	SOUP_ERROR_SEE_OTHER                = 303,
	SOUP_ERROR_NOT_MODIFIED             = 304,
	SOUP_ERROR_USE_PROXY                = 305,
	SOUP_ERROR_TEMPORARY_REDIRECT       = 307,

	SOUP_ERROR_BAD_REQUEST              = 400,
	SOUP_ERROR_UNAUTHORIZED             = 401,
	SOUP_ERROR_PAYMENT_REQUIRED         = 402,
	SOUP_ERROR_FORBIDDEN                = 403,
	SOUP_ERROR_NOT_FOUND                = 404,
	SOUP_ERROR_METHOD_NOT_ALLOWED       = 405,
	SOUP_ERROR_NOT_ACCEPTABLE           = 406,
	SOUP_ERROR_PROXY_UNAUTHORIZED       = 407,
	SOUP_ERROR_TIMED_OUT                = 408,
	SOUP_ERROR_CONFLICT                 = 409,
	SOUP_ERROR_GONE                     = 410,
	SOUP_ERROR_LENGTH_REQUIRED          = 411,
	SOUP_ERROR_PRECONDITION_FAILED      = 412,
	SOUP_ERROR_BODY_TOO_LARGE           = 413,
	SOUP_ERROR_URI_TOO_LARGE            = 414,
	SOUP_ERROR_UNKNOWN_MEDIA_TYPE       = 415,
	SOUP_ERROR_INVALID_RANGE            = 416,
	SOUP_ERROR_EXPECTATION_FAILED       = 417,
	SOUP_ERROR_DAV_UNPROCESSABLE        = 422,
	SOUP_ERROR_DAV_LOCKED               = 423,
	SOUP_ERROR_DAV_DEPENDENCY_FAILED    = 423,

	SOUP_ERROR_INTERNAL                 = 500,
	SOUP_ERROR_NOT_IMPLEMENTED          = 501,
	SOUP_ERROR_BAD_GATEWAY              = 502,
	SOUP_ERROR_SERVICE_UNAVAILABLE      = 503,
	SOUP_ERROR_GATEWAY_TIMEOUT          = 504,
	SOUP_ERROR_VERSION_UNSUPPORTED      = 505,
	SOUP_ERROR_DAV_OUT_OF_SPACE         = 507,
	SOUP_ERROR_NOT_EXTENDED             = 510,
} SoupKnownErrorCode;


enum SoupErrorClass

typedef enum {
	SOUP_ERROR_CLASS_TRANSPORT = 1,
	SOUP_ERROR_CLASS_INFORMATIONAL,
	SOUP_ERROR_CLASS_SUCCESS,
	SOUP_ERROR_CLASS_REDIRECT,
	SOUP_ERROR_CLASS_CLIENT_ERROR,
	SOUP_ERROR_CLASS_SERVER_ERROR,
	SOUP_ERROR_CLASS_UNKNOWN,
	SOUP_ERROR_CLASS_HANDLER,
} SoupErrorClass;


enum SoupTransferStatus

typedef enum {
	SOUP_STATUS_IDLE = 0,
	SOUP_STATUS_QUEUED,
        SOUP_STATUS_CONNECTING,
	SOUP_STATUS_SENDING_REQUEST,
	SOUP_STATUS_READING_RESPONSE,
	SOUP_STATUS_FINISHED
} SoupTransferStatus;


enum SoupOwnership

typedef enum {
	SOUP_BUFFER_SYSTEM_OWNED = 0,
	SOUP_BUFFER_USER_OWNED,
	SOUP_BUFFER_STATIC
} SoupOwnership;


SoupDataBuffer

typedef struct {
	SoupOwnership  owner;
	gchar         *body;
	guint          length;
} SoupDataBuffer;


struct SoupMessage

struct SoupMessage {
	SoupMessagePrivate *priv;

	SoupContext        *context;
	SoupConnection     *connection;

	const gchar        *method;

	SoupTransferStatus  status;

	guint               errorcode;
	SoupErrorClass      errorclass;
	const gchar        *errorphrase;

	SoupDataBuffer      request;
	GHashTable         *request_headers;

	SoupDataBuffer      response;
	GHashTable         *response_headers;
};


struct SoupMessagePrivate

struct SoupMessagePrivate;


SoupCallbackFn ()

void        (*SoupCallbackFn)               (SoupMessage *req,
                                             gpointer user_data);

req :

user_data :


soup_message_new ()

SoupMessage* soup_message_new               (SoupContext *context,
                                             const gchar *method);

Creates a new empty SoupMessage, which will connect to the URL represented by context. A reference will be added to context.

The new message has a status of SOUP_STATUS_IDLE.

context :

a SoupContext for the destination endpoint.

method :

a string which will be used as the HTTP method for the created request, if NULL a GET request will be made.

Returns :

the new SoupMessage.


soup_message_new_full ()

SoupMessage* soup_message_new_full          (SoupContext *context,
                                             const gchar *method,
                                             SoupOwnership req_owner,
                                             gchar *req_body,
                                             gulong req_length);

Creates a new SoupMessage, which will connect to the URL represented by context. A reference is added to context. The request data buffer will be filled from req_owner, req_body, and req_length respectively.

The new message has a status of SOUP_STATUS_IDLE.

context :

a SoupContext for the destination endpoint.

method :

a string which will be used as the HTTP method for the created request, if NULL a GET request will be made..

req_owner :

the SoupOwnership of the passed data buffer.

req_body :

a data buffer containing the body of the message request.

req_length :

the byte length of req_body.

Returns :

the new SoupMessage.


soup_message_free ()

void        soup_message_free               (SoupMessage *req);

Destroys the SoupMessage pointed to by req. Request and response headers are freed. Request and response data buffers are also freed if their ownership is SOUP_BUFFER_SYSTEM_OWNED. The message's destination context will be de-referenced.

req :

a SoupMessage to destroy.


soup_message_cancel ()

void        soup_message_cancel             (SoupMessage *req);

Cancel a running message, and issue completion callback with a SoupTransferStatus of SOUP_ERROR_CANCELLED. If not requeued by the completion callback, the msg will be destroyed.

req :

a SoupMessage currently being processed.


soup_message_send ()

SoupErrorClass soup_message_send            (SoupMessage *msg);

Syncronously send msg. This call will not return until the transfer is finished successfully or there is an unrecoverable error.

msg is not free'd upon return.

msg :

a SoupMessage.

Returns :

the SoupErrorClass of the error encountered while sending or reading the response.


soup_message_queue ()

void        soup_message_queue              (SoupMessage *req,
                                             SoupCallbackFn callback,
                                             gpointer user_data);

Queues the message req for sending. All messages are processed while the glib main loop runs. If this SoupMessage has been processed before, any resources related to the time it was last sent are freed.

If the response SoupDataBuffer has an owner of SOUP_BUFFER_USER_OWNED, the message will not be queued, and callback will be called with a SoupErrorCode of SOUP_ERROR_CANCELLED.

Upon message completetion, the callback specified in callback will be invoked. If after returning from this callback the message has not been requeued using soup_message_queue, soup_message_free will be called on req.

req :

a SoupMessage.

callback :

a SoupCallbackFn which will be called after the message completes or when an unrecoverable error occurs.

user_data :

a pointer passed to callback.


soup_message_set_request_header ()

void        soup_message_set_request_header (SoupMessage *req,
                                             const gchar *name,
                                             const gchar *value);

** DEPRECATED **

Adds a new transport header to be sent on an outgoing request. Passing a NULL value will remove all headers with a name equal to name.

req :

a SoupMessage.

name :

header name.

value :

header value.


soup_message_get_request_header ()

const gchar* soup_message_get_request_header
                                            (SoupMessage *req,
                                             const gchar *name);

** DEPRECATED **

Lookup the first transport request header with a key equal to name.

req :

a SoupMessage.

name :

header name.

Returns :

the header's value or NULL if not found.


soup_message_set_response_header ()

void        soup_message_set_response_header
                                            (SoupMessage *req,
                                             const gchar *name,
                                             const gchar *value);

** DEPRECATED **

Adds a new transport header to be sent on an outgoing response. Passing a NULL value will remove all headers with a name equal to name.

req :

a SoupMessage.

name :

header name.

value :

header value.


soup_message_get_response_header ()

const gchar* soup_message_get_response_header
                                            (SoupMessage *req,
                                             const gchar *name);

** DEPRECATED **

Lookup the transport response header with a key equal to name.

req :

a SoupMessage.

name :

header name.

Returns :

the header's value or NULL if not found.


enum SoupMessageFlags

typedef enum {
	/*
	 * SOUP_MESSAGE_NO_PIPELINE: 
	 * Use a currently unused connection or establish a new 
	 * connection when issuing this request.
	 */
	SOUP_MESSAGE_NO_PIPELINE      = (1 << 0),

	/*
	 * SOUP_MESSAGE_NO_REDIRECT: 
	 * Do not follow redirection responses.
	 */
	SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),

	/*
	 * SOUP_MESSAGE_NO_COOKIE:
	 * Do not send cookie information with request, and do not 
	 * store cookie information from the response.
	 */
	SOUP_MESSAGE_NO_COOKIE        = (1 << 2),

	/*
	 * SOUP_MESSAGE_OVERWRITE_CHUNKS:
	 * Downloaded data chunks should not be stored in the response 
	 * data buffer.  Instead only send data to SOUP_HANDLER_BODY_CHUNK 
	 * handlers, then truncate the data buffer.
	 *
	 * Useful when the response is expected to be very large, and 
	 * storage in memory is not desired.
	 */
	SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3)
} SoupMessageFlags;


soup_message_set_flags ()

void        soup_message_set_flags          (SoupMessage *msg,
                                             guint flags);

msg :

flags :


soup_message_get_flags ()

guint       soup_message_get_flags          (SoupMessage *msg);

msg :

Returns :