soup-message

Name

soup-message -- 

Synopsis



enum        SoupErrorCode;
enum        SoupTransferStatus;
enum        SoupOwnership;
typedef     SoupDataBuffer;
typedef     SoupAction;
struct      SoupMessage;
struct      SoupMessagePrivate;
void        (*SoupCallbackFn)               (SoupMessage *req,
                                             SoupErrorCode err,
                                             gpointer user_data);
SoupMessage* soup_message_new               (SoupContext *context,
                                             SoupAction action);
SoupMessage* soup_message_new_full          (SoupContext *context,
                                             SoupAction action,
                                             SoupOwnership req_owner,
                                             gchar *req_body,
                                             gulong req_length);
void        soup_message_free               (SoupMessage *req);
void        soup_message_cancel             (SoupMessage *req);
SoupErrorCode 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 SoupErrorCode

typedef enum {
	SOUP_ERROR_NONE = 0,
	SOUP_ERROR_CANCELLED,
	SOUP_ERROR_CANT_CONNECT,
	SOUP_ERROR_IO,
	SOUP_ERROR_MALFORMED_HEADER,
	SOUP_ERROR_CANT_AUTHENTICATE,
	SOUP_ERROR_HANDLER
} SoupErrorCode;


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;


SoupAction

typedef gchar * SoupAction;


struct SoupMessage

struct SoupMessage {
	SoupMessagePrivate *priv;

	SoupContext        *context;

	SoupTransferStatus  status;

	SoupAction          action;

	SoupDataBuffer      request;
	GHashTable         *request_headers;

	SoupDataBuffer      response;
	guint               response_code;
	gchar              *response_phrase;
	GHashTable         *response_headers;

	const gchar        *method;
};


struct SoupMessagePrivate

struct SoupMessagePrivate;


SoupCallbackFn ()

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

req : 
err : 
user_data : 


soup_message_new ()

SoupMessage* soup_message_new               (SoupContext *context,
                                             SoupAction action);

Creates a new empty SoupMessage, which will connect to the URL represented by context. The new message has a status of SOUP_STATUS_IDLE.

context : a SoupContext for the destination endpoint.
action : a string which will be used as the SOAPAction header for the created request.
Returns : the new SoupMessage.


soup_message_new_full ()

SoupMessage* soup_message_new_full          (SoupContext *context,
                                             SoupAction action,
                                             SoupOwnership req_owner,
                                             gchar *req_body,
                                             gulong req_length);

Creates a new SoupMessage, which will connect to the URL represented by context. The new message has a status of SOUP_STATUS_IDLE. The request data buffer will be filled from req_owner, req_body, and req_length respectively.

context : a SoupContext for the destination endpoint.
action : a string which will be used as the SOAPAction header for the created request.
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 ()

SoupErrorCode 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 SoupErrorCode of the error encountered while sending, or SOUP_ERROR_NONE.


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);

Adds a new transport header to be sent on an outgoing request. Passing a NULL value will remove the header name supplied.

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);

Lookup the 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);

Adds a new transport header to be sent on an outgoing response. Passing a NULL value will remove the header name supplied.

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);

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_REDIRECT      = (1 << 1),
	SOUP_MESSAGE_NO_COOKIE        = (1 << 2),
	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 :