Message

A #SoupMessage represents an HTTP message that is being sent or received.

For client-side usage, if you are using the traditional #SoupSession APIs (soup_session_queue_message() and soup_session_send_message()), you would create a #SoupMessage with soup_message_new() or soup_message_new_from_uri(), set up its fields appropriately, and send it. If you are using the newer #SoupRequest API, you would create a request with soup_session_request_http() or soup_session_request_http_uri(), and the returned #SoupRequestHTTP will already have an associated #SoupMessage that you can retrieve via soup_request_http_get_message().

For server-side usage, #SoupServer will create #SoupMessages automatically for incoming requests, which your application will receive via handlers.

Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is <emphasis>either</emphasis> a Request, <emphasis>or</emphasis> a Response. In libsoup, a #SoupMessage combines both the request and the response.

class Message : ObjectG {

SoupMessage* soupMessage;

SoupMessage* getMessageStruct(bool transferOwnership);

void* getStruct();

this(SoupMessage* soupMessage, bool ownedRef);

static GType getType();

this(string method, string uriString);

this(string method, URI uri);

uint addHeaderHandler(string signal, string header, GCallback callback, void* userData);

uint addStatusCodeHandler(string signal, uint statusCode, GCallback callback, void* userData);

void contentSniffed(string contentType, HashTable params);

void disableFeature(GType featureType);

void finished();

Address getAddress();

URI getFirstParty();

SoupMessageFlags getFlags();

SoupHTTPVersion getHttpVersion();

bool getHttpsStatus(TlsCertificate certificate, GTlsCertificateFlags errors);

bool getIsTopLevelNavigation();

SoupMessagePriority getPriority();

URI getSiteForCookies();

Request getSoupRequest();

URI getUri();

void gotBody();

void gotChunk(Buffer chunk);

void gotHeaders();

void gotInformational();

bool isFeatureDisabled(GType featureType);

bool isKeepalive();

void restarted();

void setChunkAllocator(SoupChunkAllocator allocator, void* userData, GDestroyNotify destroyNotify);

void setFirstParty(URI firstParty);

void setFlags(SoupMessageFlags flags);

void setHttpVersion(SoupHTTPVersion version_);

void setIsTopLevelNavigation(bool isTopLevelNavigation);

void setPriority(SoupMessagePriority priority);

void setRedirect(uint statusCode, string redirectUri);

void setRequest(string contentType, SoupMemoryUse reqUse, string reqBody);

void setResponse(string contentType, SoupMemoryUse respUse, string respBody);

void setSiteForCookies(URI siteForCookies);

void setStatus(uint statusCode);

void setStatusFull(uint statusCode, string reasonPhrase);

void setUri(URI uri);

void starting();

void wroteBody();

void wroteBodyData(Buffer chunk);

void wroteChunk();

void wroteHeaders();

void wroteInformational();

gulong addOnContentSniffed(void delegate(string, HashTable, Message) dlg, ConnectFlags connectFlags);

gulong addOnFinished(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnGotBody(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnGotChunk(void delegate(Buffer, Message) dlg, ConnectFlags connectFlags);

gulong addOnGotHeaders(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnGotInformational(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnNetwork(void delegate(GSocketClientEvent, IOStream, Message) dlg, ConnectFlags connectFlags);

gulong addOnRestarted(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnStarting(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnWroteBody(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnWroteBodyData(void delegate(Buffer, Message) dlg, ConnectFlags connectFlags);

gulong addOnWroteChunk(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnWroteHeaders(void delegate(Message) dlg, ConnectFlags connectFlags);

gulong addOnWroteInformational(void delegate(Message) dlg, ConnectFlags connectFlags);

}

Constructors

this this(SoupMessage* soupMessage, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string method, string uriString): Creates a new empty #SoupMessage, which will connect to @uri
this this(string method, URI uri): Creates a new empty #SoupMessage, which will connect to @uri

Members

Functions

addHeaderHandler uint addHeaderHandler(string signal, string header, GCallback callback, void* userData): Adds a signal handler to @msg for @signal, as with g_signal_connect(), but the @callback will only be run if @msg's incoming messages headers (that is, the <literal>request_headers</literal> for a client #SoupMessage, or the <literal>response_headers</literal> for a server #SoupMessage) contain a header named @header.
addOnContentSniffed gulong addOnContentSniffed(void delegate(string, HashTable, Message) dlg, ConnectFlags connectFlags): This signal is emitted after #SoupMessage::got-headers, and before the first #SoupMessage::got-chunk. If content sniffing is disabled, or no content sniffing will be performed, due to the sniffer deciding to trust the Content-Type sent by the server, this signal is emitted immediately after #SoupMessage::got-headers, and @type is %NULL.
addOnFinished gulong addOnFinished(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted when all HTTP processing is finished for a message. (After #SoupMessage::got_body for client-side messages, or after #SoupMessage::wrote_body for server-side messages.)
addOnGotBody gulong addOnGotBody(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted after receiving the complete message body. (For a server-side message, this means it has received the request body. For a client-side message, this means it has received the response body and is nearly done with the message.)
addOnGotChunk gulong addOnGotChunk(void delegate(Buffer, Message) dlg, ConnectFlags connectFlags): Emitted after receiving a chunk of a message body. Note that "chunk" in this context means any subpiece of the body, not necessarily the specific HTTP 1.1 chunks sent by the other side.
addOnGotHeaders gulong addOnGotHeaders(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted after receiving all message headers for a message. (For a client-side message, this is after receiving the Status-Line and response headers; for a server-side message, it is after receiving the Request-Line and request headers.)
addOnGotInformational gulong addOnGotInformational(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted after receiving a 1xx (Informational) response for a (client-side) message. The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done.
addOnNetwork gulong addOnNetwork(void delegate(GSocketClientEvent, IOStream, Message) dlg, ConnectFlags connectFlags): Emitted to indicate that some network-related event related to @msg has occurred. This essentially proxies the #GSocketClient::event signal, but only for events that occur while @msg "owns" the connection; if @msg is sent on an existing persistent connection, then this signal will not be emitted. (If you want to force the message to be sent on a new connection, set the %SOUP_MESSAGE_NEW_CONNECTION flag on it.)
addOnRestarted gulong addOnRestarted(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted when a request that was already sent once is now being sent again (eg, because the first attempt received a redirection response, or because we needed to use authentication).
addOnStarting gulong addOnStarting(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted just before a message is sent.
addOnWroteBody gulong addOnWroteBody(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted immediately after writing the complete body for a message. (For a client-side message, this means that libsoup is done writing and is now waiting for the response from the server. For a server-side message, this means that libsoup has finished writing the response and is nearly done with the message.)
addOnWroteBodyData gulong addOnWroteBodyData(void delegate(Buffer, Message) dlg, ConnectFlags connectFlags): Emitted immediately after writing a portion of the message body to the network.
addOnWroteChunk gulong addOnWroteChunk(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted immediately after writing a body chunk for a message.
addOnWroteHeaders gulong addOnWroteHeaders(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted immediately after writing the headers for a message. (For a client-side message, this is after writing the request headers; for a server-side message, it is after writing the response headers.)
addOnWroteInformational gulong addOnWroteInformational(void delegate(Message) dlg, ConnectFlags connectFlags): Emitted immediately after writing a 1xx (Informational) response for a (server-side) message.
addStatusCodeHandler uint addStatusCodeHandler(string signal, uint statusCode, GCallback callback, void* userData): Adds a signal handler to @msg for @signal, as with g_signal_connect(), but the @callback will only be run if @msg has the status @status_code.
contentSniffed void contentSniffed(string contentType, HashTable params)
disableFeature void disableFeature(GType featureType): This disables the actions of #SoupSessionFeatures with the given @feature_type (or a subclass of that type) on @msg, so that @msg is processed as though the feature(s) hadn't been added to the session. Eg, passing #SOUP_TYPE_CONTENT_SNIFFER for @feature_type will disable Content-Type sniffing on the message.
finished void finished()
getAddress Address getAddress(): Gets the address @msg's URI points to. After first setting the URI on a message, this will be unresolved, although the message's session will resolve it before sending the message.
getFirstParty URI getFirstParty(): Gets @msg's first-party #SoupURI
getFlags SoupMessageFlags getFlags(): Gets the flags on @msg
getHttpVersion SoupHTTPVersion getHttpVersion(): Gets the HTTP version of @msg. This is the minimum of the version from the request and the version from the response.
getHttpsStatus bool getHttpsStatus(TlsCertificate certificate, GTlsCertificateFlags errors): If @msg is using https (or attempted to use https but got %SOUP_STATUS_SSL_FAILED), this retrieves the #GTlsCertificate associated with its connection, and the #GTlsCertificateFlags showing what problems, if any, have been found with that certificate.
getIsTopLevelNavigation bool getIsTopLevelNavigation()
getMessageStruct SoupMessage* getMessageStruct(bool transferOwnership): Get the main Gtk struct
getPriority SoupMessagePriority getPriority(): Retrieves the #SoupMessagePriority. If not set this value defaults to #SOUP_MESSAGE_PRIORITY_NORMAL.
getSiteForCookies URI getSiteForCookies(): Gets @msg's site for cookies #SoupURI
getSoupRequest Request getSoupRequest(): If @msg is associated with a #SoupRequest, this returns that request. Otherwise it returns %NULL.
getStruct void* getStruct(): the main Gtk struct as a void*
getUri URI getUri(): Gets @msg's URI
gotBody void gotBody()
gotChunk void gotChunk(Buffer chunk)
gotHeaders void gotHeaders()
gotInformational void gotInformational()
isFeatureDisabled bool isFeatureDisabled(GType featureType): Get whether #SoupSessionFeatures of the given @feature_type (or a subclass of that type) are disabled on @msg. See soup_message_disable_feature().
isKeepalive bool isKeepalive(): Determines whether or not @msg's connection can be kept alive for further requests after processing @msg, based on the HTTP version, Connection header, etc.
restarted void restarted()
setChunkAllocator void setChunkAllocator(SoupChunkAllocator allocator, void* userData, GDestroyNotify destroyNotify): Sets an alternate chunk-allocation function to use when reading @msg's body when using the traditional (ie, non-#SoupRequest-based) API. Every time data is available to read, libsoup will call @allocator, which should return a #SoupBuffer. (See #SoupChunkAllocator for additional details.) Libsoup will then read data from the network into that buffer, and update the buffer's <literal>length</literal> to indicate how much data it read.
setFirstParty void setFirstParty(URI firstParty): Sets @first_party as the main document #SoupURI for @msg. For details of when and how this is used refer to the documentation for #SoupCookieJarAcceptPolicy.
setFlags void setFlags(SoupMessageFlags flags): Sets the specified flags on @msg.
setHttpVersion void setHttpVersion(SoupHTTPVersion version_): Sets the HTTP version on @msg. The default version is %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain functionality from being used.
setIsTopLevelNavigation void setIsTopLevelNavigation(bool isTopLevelNavigation): See the same-site spec for more information.
setPriority void setPriority(SoupMessagePriority priority): Sets the priority of a message. Note that this won't have any effect unless used before the message is added to the session's message processing queue.
setRedirect void setRedirect(uint statusCode, string redirectUri): Sets @msg's status_code to @status_code and adds a Location header pointing to @redirect_uri. Use this from a #SoupServer when you want to redirect the client to another URI.
setRequest void setRequest(string contentType, SoupMemoryUse reqUse, string reqBody): Convenience function to set the request body of a #SoupMessage. If @content_type is %NULL, the request body must be empty as well.
setResponse void setResponse(string contentType, SoupMemoryUse respUse, string respBody): Convenience function to set the response body of a #SoupMessage. If @content_type is %NULL, the response body must be empty as well.
setSiteForCookies void setSiteForCookies(URI siteForCookies): Sets @site_for_cookies as the policy URL for same-site cookies for @msg.
setStatus void setStatus(uint statusCode): Sets @msg's status code to @status_code. If @status_code is a known value, it will also set @msg's reason_phrase.
setStatusFull void setStatusFull(uint statusCode, string reasonPhrase): Sets @msg's status code and reason phrase.
setUri void setUri(URI uri): Sets @msg's URI to @uri. If @msg has already been sent and you want to re-send it with the new URI, you need to call soup_session_requeue_message().
starting void starting()
wroteBody void wroteBody()
wroteBodyData void wroteBodyData(Buffer chunk)
wroteChunk void wroteChunk()
wroteHeaders void wroteHeaders()
wroteInformational void wroteInformational()

Static functions

getType GType getType()

Variables

soupMessage SoupMessage* soupMessage;: the main Gtk struct

Meta

Source

See Implementation