Message
Object Hierarchy:
Description:
Represents an HTTP message being sent or received.
A Message represents an HTTP message that is being sent or received.
You would create a Message with [ctor@Message.new] or [ctor@Message.new_from_uri], set up its fields appropriately, and send it.
[property@Message:status-code] will normally be a [enum@Status] value, eg, soup_status_ok, though of course
it might actually be an unknown status code. [property@Message:reason-phrase] is the actual text returned from the server, which may or may not
correspond to the "standard" description of status_code
. At any rate, it is almost certainly not localized, and not very
descriptive even if it is in the user's language; you should not use [property@Message:reason-phrase] in user-visible messages. Rather, you
should look at [property@Message:status-code], and determine an end-user-appropriate message based on that and on what you were trying to do.
Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a Response. In libsoup, a Message combines both the request and the response.
Content:
Properties:
- public Uri first_party { get; set; }
The [struct@GLib.
- public MessageFlags flags { get; set; }
Various message options.
- public HTTPVersion http_version { get; }
The HTTP protocol version to use.
- public bool is_options_ping { get; set; }
Whether the message is an OPTIONS ping.
- public bool is_top_level_navigation { get; set; }
Set when the message is navigating between top level domains.
- public string method { get; set; }
The message's HTTP method.
- public MessagePriority priority { get; set; }
Sets the priority of the Message.
- public string reason_phrase { get; }
The HTTP response reason phrase.
- public SocketAddress remote_address { get; }
The remote [class@Gio.
- public MessageHeaders request_headers { get; }
The HTTP request headers.
- public MessageHeaders response_headers { get; }
The HTTP response headers.
- public Uri site_for_cookies { get; set; }
Site used to compare cookies against.
- public uint status_code { get; }
The HTTP response status code.
- public string tls_ciphersuite_name { get; }
The Name of TLS ciphersuite negotiated for this message connection.
- public TlsCertificate tls_peer_certificate { get; }
The peer's [class@Gio.
- public TlsCertificateFlags tls_peer_certificate_errors { get; }
The verification errors on [property@Message:tls-peer-certificate].
- public TlsProtocolVersion tls_protocol_version { get; }
The TLS protocol version negotiated for the message connection.
- public Uri uri { get; set; }
The message's Request-URI.
Creation methods:
- public Message (string method, string uri_string)
Creates a new empty Message, which will connect to
uri
. - public Message.from_encoded_form (string method, string uri_string, owned string encoded_form)
Creates a new Message and sets it up to send the given
encoded_form
touri
viamethod
. - public Message.from_multipart (string uri_string, Multipart multipart)
Creates a new Message and sets it up to send
multipart
touri_string
via POST. - public Message.from_uri (string method, Uri uri)
Creates a new empty Message, which will connect to
uri
. - public Message.options_ping (Uri base_uri)
Creates a new Message to send `OPTIONS *` to a server.
Methods:
- public void add_flags (MessageFlags flags)
Adds
flags
to the set of this 's flags. - public uint add_header_handler (string @signal, string header, Callback callback, void* user_data)
Adds a signal handler to this for
signal
. - public uint add_status_code_handler (string @signal, uint status_code, Callback callback, void* user_data)
Adds a signal handler to this for
signal
. - public void disable_feature (Type feature_type)
Disables the actions of [iface@SessionFeature]s with the given
feature_type
(or a subclass of that type) on this. - public uint64 get_connection_id ()
Returns the unique idenfier for the last connection used.
- public unowned Uri get_first_party ()
Gets this's first-party [struct@GLib.
- public MessageFlags get_flags ()
Gets the flags on this.
- public bool get_force_http1 ()
Returns whether HTTP/1 version is currently demanded for the this send.
- public HTTPVersion get_http_version ()
Gets the HTTP version of this.
- public bool get_is_options_ping ()
Gets whether this is intended to be used to send `OPTIONS *` to a server.
- public bool get_is_top_level_navigation ()
Returns if this message is set as a top level navigation.
- public unowned string get_method ()
Returns the method of this message.
- public unowned MessageMetrics? get_metrics ()
Get the [struct@MessageMetrics] of this.
- public MessagePriority get_priority ()
Retrieves the [enum@MessagePriority].
- public unowned string? get_reason_phrase ()
Returns the reason phrase for the status of this message.
- public unowned SocketAddress? get_remote_address ()
Get the remote [class@Gio.
- public unowned MessageHeaders get_request_headers ()
Returns the headers sent with the request.
- public unowned MessageHeaders get_response_headers ()
Returns the headers recieved with the response.
- public unowned Uri get_site_for_cookies ()
Gets this's site for cookies Uri.
- public Status get_status ()
Returns the set status of this message.
- public unowned string get_tls_ciphersuite_name ()
Gets the name of the TLS ciphersuite negotiated for this's connection.
- public unowned TlsCertificate? get_tls_peer_certificate ()
Gets the peer's [class@Gio.
- public TlsCertificateFlags get_tls_peer_certificate_errors ()
Gets the errors associated with validating this 's TLS peer certificate.
- public TlsProtocolVersion get_tls_protocol_version ()
Gets the TLS protocol version negotiated for this 's connection.
- public unowned Uri get_uri ()
Gets this's URI.
- public bool is_feature_disabled (Type feature_type)
Get whether [iface@SessionFeature]s of the given
feature_type
( or a subclass of that type) are disabled on this. - public bool is_keepalive ()
Determines whether or not this's connection can be kept alive for further requests after processing this.
- public bool query_flags (MessageFlags flags)
Queries if
flags
are present in the set of this's flags. - public void remove_flags (MessageFlags flags)
Removes
flags
from the set of this 's flags. - public void set_first_party (Uri first_party)
Sets
first_party
as the main document Uri for this. - public void set_flags (MessageFlags flags)
Sets the specified flags on this.
- public void set_force_http1 (bool value)
Sets whether HTTP/1 version should be used when sending this message.
- public void set_is_options_ping (bool is_options_ping)
Set whether this is intended to be used to send `OPTIONS *` to a server.
- public void set_is_top_level_navigation (bool is_top_level_navigation)
Sets whether the current request is a top-level navitation.
- public void set_method (string method)
Set this's HTTP method to
method
. - public void set_priority (MessagePriority priority)
Sets the priority of a message.
- public void set_request_body (string? content_type, InputStream? stream, ssize_t content_length)
Set the request body of a Message.
- public void set_request_body_from_bytes (string? content_type, Bytes? bytes)
Set the request body of a Message from [ struct@GLib.
- public void set_site_for_cookies (Uri? site_for_cookies)
Sets
site_for_cookies
as the policy URL for same-site cookies for this. - public void set_tls_client_certificate (TlsCertificate? certificate)
Sets the
certificate
to be used by this's connection when a client certificate is requested during the TLS handshake. - public void set_uri (Uri uri)
Sets this's URI to
uri
. - public void tls_client_certificate_password_request_complete ()
Completes a certificate password request.
Signals:
- public signal bool accept_certificate (TlsCertificate tls_peer_certificate, TlsCertificateFlags tls_peer_errors)
Emitted during the
msg
's connection TLS handshake after an unacceptable TLS certificate has been received. - public signal bool authenticate (Auth auth, bool retrying)
Emitted when the message requires authentication.
- public signal void content_sniffed (string type, HashTable<string,string> @params)
This signal is emitted after [signal@Message:
SoupMessage:got-headers
s]. - public signal void finished ()
Emitted when all HTTP processing is finished for a message.
- public signal void got_body ()
Emitted after receiving the complete message response body.
- public signal void got_body_data (uint chunk_size)
Emitted after reading a portion of the message body from the network.
- public signal void got_headers ()
Emitted after receiving the Status-Line and response headers.
- public signal void got_informational ()
Emitted after receiving a 1xx (Informational) response for a (client-side) message.
- public signal void hsts_enforced ()
Emitted when [class@HSTSEnforcer] has upgraded the protocol for
msg
to HTTPS as a result of matching its domain with a HSTS policy. - public signal void network_event (SocketClientEvent event, IOStream connection)
Emitted to indicate that some network-related event related to
msg
has occurred. - public signal bool request_certificate (TlsClientConnection tls_connection)
Emitted during the
msg
's connection TLS handshake whentls_connection
requests a certificate from the client. - public signal bool request_certificate_password (TlsPassword tls_password)
Emitted during the
msg
's connection TLS handshake whentls_connection
requests a certificate password from the client. - public signal void restarted ()
Emitted when a request that was already sent once is now being sent again.
- public signal void starting ()
Emitted just before a message is sent.
- public signal void wrote_body ()
Emitted immediately after writing the complete body for a message.
- public signal void wrote_body_data (uint chunk_size)
Emitted immediately after writing a portion of the message body to the network.
- public signal void wrote_headers ()
Emitted immediately after writing the request headers for a message.