Package org.gnome.soup

Class Message

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.soup.Message

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public final class Message
extends GObject

Represents an HTTP message being sent or received.

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

You would create a SoupMessage with Message() or fromUri(java.lang.String, org.gnome.glib.Uri), set up its fields appropriately, and send it.

Message:status-code will normally be a Status value, eg, Status.OK, though of course it might actually be an unknown status code. Message:reason-phrase is the actual text returned from the server, which may or may not correspond to the "standard" description of statusCode. 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 Message:reason-phrase in user-visible messages. Rather, you should look at 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 SoupMessage combines both the request and the response.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Message.AcceptCertificateCallback	Functional interface declaration of the AcceptCertificateCallback callback.
static interface	Message.AuthenticateCallback	Functional interface declaration of the AuthenticateCallback callback.
static class	Message.Builder<B extends Message.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	Message.ContentSniffedCallback	Functional interface declaration of the ContentSniffedCallback callback.
static interface	Message.FinishedCallback	Functional interface declaration of the FinishedCallback callback.
static interface	Message.GotBodyCallback	Functional interface declaration of the GotBodyCallback callback.
static interface	Message.GotBodyDataCallback	Functional interface declaration of the GotBodyDataCallback callback.
static interface	Message.GotHeadersCallback	Functional interface declaration of the GotHeadersCallback callback.
static interface	Message.GotInformationalCallback	Functional interface declaration of the GotInformationalCallback callback.
static interface	Message.HstsEnforcedCallback	Functional interface declaration of the HstsEnforcedCallback callback.
static class	Message.MessageClass
static interface	Message.NetworkEventCallback	Functional interface declaration of the NetworkEventCallback callback.
static interface	Message.RequestCertificateCallback	Functional interface declaration of the RequestCertificateCallback callback.
static interface	Message.RequestCertificatePasswordCallback	Functional interface declaration of the RequestCertificatePasswordCallback callback.
static interface	Message.RestartedCallback	Functional interface declaration of the RestartedCallback callback.
static interface	Message.StartingCallback	Functional interface declaration of the StartingCallback callback.
static interface	Message.WroteBodyCallback	Functional interface declaration of the WroteBodyCallback callback.
static interface	Message.WroteBodyDataCallback	Functional interface declaration of the WroteBodyDataCallback callback.
static interface	Message.WroteHeadersCallback	Functional interface declaration of the WroteHeadersCallback callback.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
Message()	Creates a new Message.
Message(MemorySegment address)	Create a Message proxy instance for the provided memory address.
Message(String method, String uriString)	Creates a new empty SoupMessage, which will connect to uri.

Method Summary

Modifier and Type	Method	Description
void	addFlags(Set<MessageFlags> flags)	Adds flags to the set of msg's flags.
void	addFlags(MessageFlags... flags)	Adds flags to the set of msg's flags.
int	addHeaderHandler(String signal, String header, @Nullable Callback callback)	Adds a signal handler to this Message for signal.
int	addStatusCodeHandler(String signal, int statusCode, @Nullable Callback callback)	Adds a signal handler to this Message for signal.
protected Message	asParent()	Returns this instance as if it were its parent type.
static Message.Builder<? extends Message.Builder>	builder()	A Message.Builder object constructs a Message with the specified properties.
void	disableFeature(Type featureType)	Disables the actions of SessionFeatures with the given featureType (or a subclass of that type) on msg.
boolean	emitAcceptCertificate(@Nullable TlsCertificate tlsPeerCertificate, Set<TlsCertificateFlags> tlsPeerErrors)	Emits the "accept-certificate" signal.
boolean	emitAuthenticate(@Nullable Auth auth, boolean retrying)	Emits the "authenticate" signal.
void	emitContentSniffed(String type, @Nullable HashTable<String,String> params)	Emits the "content-sniffed" signal.
void	emitFinished()	Emits the "finished" signal.
void	emitGotBody()	Emits the "got-body" signal.
void	emitGotBodyData(int chunkSize)	Emits the "got-body-data" signal.
void	emitGotHeaders()	Emits the "got-headers" signal.
void	emitGotInformational()	Emits the "got-informational" signal.
void	emitHstsEnforced()	Emits the "hsts-enforced" signal.
void	emitNetworkEvent(SocketClientEvent event, @Nullable IOStream connection)	Emits the "network-event" signal.
boolean	emitRequestCertificate(@Nullable TlsClientConnection tlsConnection)	Emits the "request-certificate" signal.
boolean	emitRequestCertificatePassword(@Nullable TlsPassword tlsPassword)	Emits the "request-certificate-password" signal.
void	emitRestarted()	Emits the "restarted" signal.
void	emitStarting()	Emits the "starting" signal.
void	emitWroteBody()	Emits the "wrote-body" signal.
void	emitWroteBodyData(int chunkSize)	Emits the "wrote-body-data" signal.
void	emitWroteHeaders()	Emits the "wrote-headers" signal.
static Message	fromEncodedForm(String method, String uriString, String encodedForm)	Creates a new SoupMessage and sets it up to send the given encodedForm to uri via method. If method is "GET", it will include the form data into uri's query field, and if method is "POST" or "PUT", it will be set as request body.
static Message	fromMultipart(String uriString, Multipart multipart)	Creates a new SoupMessage and sets it up to send multipart to uriString via POST.
static Message	fromUri(String method, Uri uri)	Creates a new empty SoupMessage, which will connect to uri.
long	getConnectionId()	Returns the unique idenfier for the last connection used.
Uri	getFirstParty()	Gets msg's first-party GLib.Uri.
Set<MessageFlags>	getFlags()	Gets the flags on msg.
boolean	getForceHttp1()	Returns whether HTTP/1 version is currently demanded for the this Message send.
HTTPVersion	getHttpVersion()	Gets the HTTP version of msg.
boolean	getIsOptionsPing()	Gets whether this Message is intended to be used to send OPTIONS * to a server.
boolean	getIsTopLevelNavigation()	Returns if this message is set as a top level navigation.
String	getMethod()	Returns the method of this message.
@Nullable MessageMetrics	getMetrics()	Get the MessageMetrics of msg.
MessagePriority	getPriority()	Retrieves the MessagePriority.
@Nullable String	getReasonPhrase()	Returns the reason phrase for the status of this message.
@Nullable SocketAddress	getRemoteAddress()	Get the remote SocketAddress of the connection associated with the message.
MessageHeaders	getRequestHeaders()	Returns the headers sent with the request.
MessageHeaders	getResponseHeaders()	Returns the headers recieved with the response.
Uri	getSiteForCookies()	Gets msg's site for cookies GUri.
Status	getStatus()	Returns the set status of this message.
String	getTlsCiphersuiteName()	Gets the name of the TLS ciphersuite negotiated for msg's connection.
@Nullable TlsCertificate	getTlsPeerCertificate()	Gets the peer's TlsCertificate associated with msg's connection.
Set<TlsCertificateFlags>	getTlsPeerCertificateErrors()	Gets the errors associated with validating msg's TLS peer certificate.
TlsProtocolVersion	getTlsProtocolVersion()	Gets the TLS protocol version negotiated for msg's connection.
static @Nullable Type	getType()	Get the GType of the Message class
Uri	getUri()	Gets msg's URI.
boolean	isFeatureDisabled(Type featureType)	Get whether SessionFeatures of the given featureType (or a subclass of that type) are disabled on msg.
boolean	isKeepalive()	Determines whether or not msg's connection can be kept alive for further requests after processing msg.
SignalConnection<Message.AcceptCertificateCallback>	onAcceptCertificate(Message.AcceptCertificateCallback handler)	Emitted during the msg's connection TLS handshake after an unacceptable TLS certificate has been received.
SignalConnection<Message.AuthenticateCallback>	onAuthenticate(Message.AuthenticateCallback handler)	Emitted when the message requires authentication.
SignalConnection<Message.ContentSniffedCallback>	onContentSniffed(Message.ContentSniffedCallback handler)	This signal is emitted after Message::got-headers.
SignalConnection<Message.FinishedCallback>	onFinished(Message.FinishedCallback handler)	Emitted when all HTTP processing is finished for a message.
SignalConnection<Message.GotBodyCallback>	onGotBody(Message.GotBodyCallback handler)	Emitted after receiving the complete message response body.
SignalConnection<Message.GotBodyDataCallback>	onGotBodyData(Message.GotBodyDataCallback handler)	Emitted after reading a portion of the message body from the network.
SignalConnection<Message.GotHeadersCallback>	onGotHeaders(Message.GotHeadersCallback handler)	Emitted after receiving the Status-Line and response headers.
SignalConnection<Message.GotInformationalCallback>	onGotInformational(Message.GotInformationalCallback handler)	Emitted after receiving a 1xx (Informational) response for a (client-side) message.
SignalConnection<Message.HstsEnforcedCallback>	onHstsEnforced(Message.HstsEnforcedCallback handler)	Emitted when HSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.
SignalConnection<Message.NetworkEventCallback>	onNetworkEvent(Message.NetworkEventCallback handler)	Emitted to indicate that some network-related event related to msg has occurred.
SignalConnection<Message.RequestCertificateCallback>	onRequestCertificate(Message.RequestCertificateCallback handler)	Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate from the client.
SignalConnection<Message.RequestCertificatePasswordCallback>	onRequestCertificatePassword(Message.RequestCertificatePasswordCallback handler)	Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate password from the client.
SignalConnection<Message.RestartedCallback>	onRestarted(Message.RestartedCallback handler)	Emitted when a request that was already sent once is now being sent again.
SignalConnection<Message.StartingCallback>	onStarting(Message.StartingCallback handler)	Emitted just before a message is sent.
SignalConnection<Message.WroteBodyCallback>	onWroteBody(Message.WroteBodyCallback handler)	Emitted immediately after writing the complete body for a message.
SignalConnection<Message.WroteBodyDataCallback>	onWroteBodyData(Message.WroteBodyDataCallback handler)	Emitted immediately after writing a portion of the message body to the network.
SignalConnection<Message.WroteHeadersCallback>	onWroteHeaders(Message.WroteHeadersCallback handler)	Emitted immediately after writing the request headers for a message.
static Message	optionsPing(Uri baseUri)	Creates a new SoupMessage to send OPTIONS * to a server.
boolean	queryFlags(Set<MessageFlags> flags)	Queries if flags are present in the set of msg's flags.
boolean	queryFlags(MessageFlags... flags)	Queries if flags are present in the set of msg's flags.
void	removeFlags(Set<MessageFlags> flags)	Removes flags from the set of msg's flags.
void	removeFlags(MessageFlags... flags)	Removes flags from the set of msg's flags.
void	setFirstParty(Uri firstParty)	Sets firstParty as the main document GUri for msg.
void	setFlags(Set<MessageFlags> flags)	Sets the specified flags on msg.
void	setFlags(MessageFlags... flags)	Sets the specified flags on msg.
void	setForceHttp1(boolean value)	Sets whether HTTP/1 version should be used when sending this message.
void	setIsOptionsPing(boolean isOptionsPing)	Set whether this Message is intended to be used to send OPTIONS * to a server.
void	setIsTopLevelNavigation(boolean isTopLevelNavigation)	Sets whether the current request is a top-level navitation.
void	setMethod(String method)	Set msg's HTTP method to method.
void	setPriority(MessagePriority priority)	Sets the priority of a message.
void	setRequestBody(@Nullable String contentType, @Nullable InputStream stream, long contentLength)	Set the request body of a SoupMessage.
void	setRequestBodyFromBytes(@Nullable String contentType, byte @Nullable [] bytes)	Set the request body of a SoupMessage from GLib.Bytes.
void	setSiteForCookies(@Nullable Uri siteForCookies)	Sets siteForCookies as the policy URL for same-site cookies for msg.
void	setTlsClientCertificate(@Nullable TlsCertificate certificate)	Sets the certificate to be used by msg's connection when a client certificate is requested during the TLS handshake.
void	setUri(Uri uri)	Sets msg's URI to uri.
void	tlsClientCertificatePasswordRequestComplete()	Completes a certificate password request.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Message

public Message(MemorySegment address)

Create a Message proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Message

public Message(String method,
 String uriString)

Creates a new empty SoupMessage, which will connect to uri.

Parameters:

method - the HTTP method for the created request

uriString - the destination endpoint (as a string)

Message

public Message()

Creates a new Message.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Message class

Returns:

the GType

asParent

protected Message asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

fromEncodedForm

public static Message fromEncodedForm(String method,
 String uriString,
 String encodedForm)

Creates a new SoupMessage and sets it up to send the given encodedForm to uri via method. If method is "GET", it will include the form data into uri's query field, and if method is "POST" or "PUT", it will be set as request body.

This function takes the ownership of encodedForm, that will be released with GLib.free(java.lang.foreign.MemorySegment) when no longer in use. See also Soup.formEncode(java.lang.String, java.lang.Object...), Soup.formEncodeHash(org.gnome.glib.HashTable<java.lang.String, java.lang.String>) and Soup.formEncodeDatalist(org.gnome.glib.Data[]).

Parameters:

method - the HTTP method for the created request (GET, POST or PUT)

uriString - the destination endpoint (as a string)

encodedForm - a encoded form

Returns:

the new SoupMessage, or null if uriString could not be parsed or method is not "GET, "POST" or "PUT"

fromMultipart

public static Message fromMultipart(String uriString,
 Multipart multipart)

Creates a new SoupMessage and sets it up to send multipart to uriString via POST.

Parameters:

uriString - the destination endpoint

multipart - a SoupMultipart

Returns:

the new SoupMessage, or null if uriString could not be parsed

fromUri

public static Message fromUri(String method,
 Uri uri)

Creates a new empty SoupMessage, which will connect to uri.

Parameters:

method - the HTTP method for the created request

uri - the destination endpoint

Returns:

the new SoupMessage

optionsPing

public static Message optionsPing(Uri baseUri)

Creates a new SoupMessage to send OPTIONS * to a server. The path of baseUri will be ignored.

Parameters:

baseUri - the destination endpoint

Returns:

the new SoupMessage

addFlags

public void addFlags(Set<MessageFlags> flags)

Adds flags to the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

addFlags

public void addFlags(MessageFlags... flags)

Adds flags to the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

addHeaderHandler

public int addHeaderHandler(String signal,
 String header,
 @Nullable Callback callback)

Adds a signal handler to this Message for signal.

Similar to org.gnome.gobject.GObjects#signalConnect, but the callback will only be run if msg's incoming messages headers (that is, the request_headers) contain a header named header.

Parameters:

signal - signal to connect the handler to.

header - HTTP response header to match against

callback - the header handler

Returns:

the handler ID from org.gnome.gobject.GObjects#signalConnect

addStatusCodeHandler

public int addStatusCodeHandler(String signal,
 int statusCode,
 @Nullable Callback callback)

Adds a signal handler to this Message for signal.

Similar to org.gnome.gobject.GObjects#signalConnect, but the callback will only be run if this Message has the status statusCode.

signal must be a signal that will be emitted after msg's status is set (this means it can't be a "wrote" signal).

Parameters:

signal - signal to connect the handler to.

statusCode - status code to match against

callback - the header handler

Returns:

the handler ID from org.gnome.gobject.GObjects#signalConnect

disableFeature

public void disableFeature(Type featureType)

Disables the actions of SessionFeatures with the given featureType (or a subclass of that type) on msg.

this Message is processed as though the feature(s) hadn't been added to the session. Eg, passing SOUP_TYPE_CONTENT_SNIFFER for featureType will disable Content-Type sniffing on the message.

You must call this before queueing this Message on a session; calling it on a message that has already been queued is undefined. In particular, you cannot call this on a message that is being requeued after a redirect or authentication.

Parameters:

featureType - the GType of a SoupSessionFeature

getConnectionId

public long getConnectionId()

Returns the unique idenfier for the last connection used.

This may be 0 if it was a cached resource or it has not gotten a connection yet.

Returns:

An id or 0 if no connection.

getFirstParty

public Uri getFirstParty()

Gets msg's first-party GLib.Uri.

Returns:

the msg's first party GUri

getFlags

public Set<MessageFlags> getFlags()

Gets the flags on msg.

Returns:

the flags

getForceHttp1

public boolean getForceHttp1()

Returns whether HTTP/1 version is currently demanded for the this Message send.

Returns:

true, when HTTP/1 is demanded, false otherwise.

Since:

3.4

getHttpVersion

public HTTPVersion getHttpVersion()

Gets the HTTP version of msg.

This is the minimum of the version from the request and the version from the response.

Returns:

the HTTP version

getIsOptionsPing

public boolean getIsOptionsPing()

Gets whether this Message is intended to be used to send OPTIONS * to a server.

Returns:

true if the message is options ping, or false otherwise

getIsTopLevelNavigation

public boolean getIsTopLevelNavigation()

Returns if this message is set as a top level navigation.

Used for same-site policy checks.

Returns:

Whether the current request is a top-level navitation

getMethod

public String getMethod()

Returns the method of this message.

Returns:

A method such as SOUP_METHOD_GET

getMetrics

public @Nullable MessageMetrics getMetrics()

Get the MessageMetrics of msg.

If the flag MessageFlags.COLLECT_METRICS is not enabled for this Message this will return null.

Returns:

a SoupMessageMetrics

getPriority

public MessagePriority getPriority()

Retrieves the MessagePriority.

If not set this value defaults to SOUP_MESSAGE_PRIORITY_NORMAL.

Returns:

the priority of the message.

getReasonPhrase

public @Nullable String getReasonPhrase()

Returns the reason phrase for the status of this message.

Returns:

the phrase

getRemoteAddress

public @Nullable SocketAddress getRemoteAddress()

Get the remote SocketAddress of the connection associated with the message.

The returned address can be null if the connection hasn't been established yet, or the resource was loaded from the disk cache. In case of proxy connections, the remote address returned is a ProxyAddress. If Session:remote-connectable is set the returned address id for the connection to the session's remote connectable.

Returns:

a GSocketAddress or null if the connection hasn't been established

getRequestHeaders

public MessageHeaders getRequestHeaders()

Returns the headers sent with the request.

Returns:

The SoupMessageHeaders

getResponseHeaders

public MessageHeaders getResponseHeaders()

Returns the headers recieved with the response.

Returns:

The SoupMessageHeaders

getSiteForCookies

public Uri getSiteForCookies()

Gets msg's site for cookies GUri.

Returns:

the msg's site for cookies GUri

getStatus

public Status getStatus()

Returns the set status of this message.

Returns:

The SoupStatus

getTlsCiphersuiteName

public String getTlsCiphersuiteName()

Gets the name of the TLS ciphersuite negotiated for msg's connection.

Returns:

the name of the TLS ciphersuite, or null if msg's connection is not SSL.

getTlsPeerCertificate

public @Nullable TlsCertificate getTlsPeerCertificate()

Gets the peer's TlsCertificate associated with msg's connection.

Note that this is not set yet during the emission of Message::accept-certificate signal.

Returns:

msg's TLS peer certificate, or null if msg's connection is not SSL.

getTlsPeerCertificateErrors

public Set<TlsCertificateFlags> getTlsPeerCertificateErrors()

Gets the errors associated with validating msg's TLS peer certificate. Note that this is not set yet during the emission of Message::accept-certificate signal.

Returns:

a GTlsCertificateFlags with msg's TLS peer certificate errors.

getTlsProtocolVersion

public TlsProtocolVersion getTlsProtocolVersion()

Gets the TLS protocol version negotiated for msg's connection.

If the message connection is not SSL, TlsProtocolVersion.UNKNOWN is returned.

Returns:

a GTlsProtocolVersion

getUri

public Uri getUri()

Gets msg's URI.

Returns:

the URI this Message is targeted for.

isFeatureDisabled

public boolean isFeatureDisabled(Type featureType)

Get whether SessionFeatures of the given featureType (or a subclass of that type) are disabled on msg.

See disableFeature(org.gnome.glib.Type).

Parameters:

featureType - the GType of a SoupSessionFeature

Returns:

true if feature is disabled, or false otherwise.

isKeepalive

public boolean isKeepalive()

Determines whether or not msg's connection can be kept alive for further requests after processing msg.

The result is based on the HTTP version, Connection header, etc.

Returns:

true or false.

queryFlags

public boolean queryFlags(Set<MessageFlags> flags)

Queries if flags are present in the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

Returns:

true if flags are enabled in this Message

queryFlags

public boolean queryFlags(MessageFlags... flags)

Queries if flags are present in the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

Returns:

true if flags are enabled in this Message

removeFlags

public void removeFlags(Set<MessageFlags> flags)

Removes flags from the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

removeFlags

public void removeFlags(MessageFlags... flags)

Removes flags from the set of msg's flags.

Parameters:

flags - a set of SoupMessageFlags values

setFirstParty

public void setFirstParty(Uri firstParty)

Sets firstParty as the main document GUri for msg.

For details of when and how this is used refer to the documentation for CookieJarAcceptPolicy.

Parameters:

firstParty - the GUri for the msg's first party

setFlags

public void setFlags(Set<MessageFlags> flags)

Sets the specified flags on msg.

Parameters:

flags - a set of SoupMessageFlags values

setFlags

public void setFlags(MessageFlags... flags)

Sets the specified flags on msg.

Parameters:

flags - a set of SoupMessageFlags values

setForceHttp1

public void setForceHttp1(boolean value)

Sets whether HTTP/1 version should be used when sending this message. Some connections can still override it, if needed.

Note the value is unset after the message send is finished.

Parameters:

value - value to set

Since:

3.4

setIsOptionsPing

public void setIsOptionsPing(boolean isOptionsPing)

Set whether this Message is intended to be used to send OPTIONS * to a server.

When set to true, the path of Message:uri will be ignored and Message:method set to SOUP_METHOD_OPTIONS.

Parameters:

isOptionsPing - the value to set

setIsTopLevelNavigation

public void setIsTopLevelNavigation(boolean isTopLevelNavigation)

Sets whether the current request is a top-level navitation.

See the same-site spec for more information.

Parameters:

isTopLevelNavigation - if true indicate the current request is a top-level navigation

setMethod

public void setMethod(String method)

Set msg's HTTP method to method.

Parameters:

method - the value to set

setPriority

public void setPriority(MessagePriority 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.

The message will be placed just before any other previously added message with lower priority (messages with the same priority are processed on a FIFO basis).

Setting priorities does not currently work with synchronous messages because in the synchronous/blocking case, priority ends up being determined semi-randomly by thread scheduling.

Parameters:

priority - the SoupMessagePriority

setRequestBody

public void setRequestBody(@Nullable String contentType,
 @Nullable InputStream stream,
 long contentLength)

Set the request body of a SoupMessage.

If contentType is null and stream is not null the Content-Type header will not be changed if present. The request body needs to be set again in case this Message is restarted (in case of redirection or authentication).

Parameters:

contentType - MIME Content-Type of the body, or null if unknown

stream - a GInputStream to read the request body from

contentLength - the byte length of stream or -1 if unknown

setRequestBodyFromBytes

public void setRequestBodyFromBytes(@Nullable String contentType,
 byte @Nullable [] bytes)

Set the request body of a SoupMessage from GLib.Bytes.

If contentType is null and bytes is not null the Content-Type header will not be changed if present. The request body needs to be set again in case this Message is restarted (in case of redirection or authentication).

Parameters:

contentType - MIME Content-Type of the body, or null if unknown

bytes - a GBytes with the request body data

setSiteForCookies

public void setSiteForCookies(@Nullable Uri siteForCookies)

Sets siteForCookies as the policy URL for same-site cookies for msg.

It is either the URL of the top-level document or null depending on whether the registrable domain of this document's URL matches the registrable domain of its parent's/opener's URL. For the top-level document it is set to the document's URL.

See the same-site spec for more information.

Parameters:

siteForCookies - the GUri for the msg's site for cookies

setTlsClientCertificate

public void setTlsClientCertificate(@Nullable TlsCertificate certificate)

Sets the certificate to be used by msg's connection when a client certificate is requested during the TLS handshake.

You can call this as a response to Message::request-certificate signal, or before the connection is started. If certificate is null the handshake will continue without providing a GTlsCertificate. Note that the TlsCertificate set by this function will be ignored if Session:tls-interaction is not null.

Parameters:

certificate - the GTlsCertificate to set, or null

setUri

public void setUri(Uri uri)

Sets msg's URI to uri.

If this Message has already been sent and you want to re-send it with the new URI, you need to send it again.

Parameters:

uri - the new GUri

tlsClientCertificatePasswordRequestComplete

public void tlsClientCertificatePasswordRequestComplete()

Completes a certificate password request.

You must call this as a response to Message::request-certificate-password signal, to notify this Message that the TlsPassword has already been updated.

onAcceptCertificate

public SignalConnection<Message.AcceptCertificateCallback> onAcceptCertificate(Message.AcceptCertificateCallback handler)

Emitted during the msg's connection TLS handshake after an unacceptable TLS certificate has been received.

You can return true to accept tlsCertificate despite tlsErrors.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.AcceptCertificateCallback.run(org.gnome.gio.TlsCertificate, java.util.Set<org.gnome.gio.TlsCertificateFlags>)

emitAcceptCertificate

public boolean emitAcceptCertificate(@Nullable TlsCertificate tlsPeerCertificate,
 Set<TlsCertificateFlags> tlsPeerErrors)

Emits the "accept-certificate" signal. See onAcceptCertificate(org.gnome.soup.Message.AcceptCertificateCallback).

onAuthenticate

public SignalConnection<Message.AuthenticateCallback> onAuthenticate(Message.AuthenticateCallback handler)

Emitted when the message requires authentication.

If credentials are available call Auth.authenticate(java.lang.String, java.lang.String) on auth. If these credentials fail, the signal will be emitted again, with retrying set to true, which will continue until you return without calling Auth.authenticate(java.lang.String, java.lang.String) on auth.

Note that this may be emitted before msg's body has been fully read.

You can authenticate auth asynchronously by calling GObject.ref() on auth and returning true. The operation will complete once either Auth.authenticate(java.lang.String, java.lang.String) or Auth.cancel() are called.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.AuthenticateCallback.run(org.gnome.soup.Auth, boolean)

emitAuthenticate

public boolean emitAuthenticate(@Nullable Auth auth,
 boolean retrying)

Emits the "authenticate" signal. See onAuthenticate(org.gnome.soup.Message.AuthenticateCallback).

onContentSniffed

public SignalConnection<Message.ContentSniffedCallback> onContentSniffed(Message.ContentSniffedCallback handler)

This signal is emitted after Message::got-headers.

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 Message::got-headers, and type is null.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.ContentSniffedCallback.run(java.lang.String, org.gnome.glib.HashTable<java.lang.String, java.lang.String>)

emitContentSniffed

public void emitContentSniffed(String type,
 @Nullable HashTable<String,String> params)

Emits the "content-sniffed" signal. See onContentSniffed(org.gnome.soup.Message.ContentSniffedCallback).

onFinished

public SignalConnection<Message.FinishedCallback> onFinished(Message.FinishedCallback handler)

Emitted when all HTTP processing is finished for a message.

(After Message::got_body).

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.FinishedCallback.run()

emitFinished

public void emitFinished()

Emits the "finished" signal. See onFinished(org.gnome.soup.Message.FinishedCallback).

onGotBody

public SignalConnection<Message.GotBodyCallback> onGotBody(Message.GotBodyCallback handler)

Emitted after receiving the complete message response body.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.GotBodyCallback.run()

emitGotBody

public void emitGotBody()

Emits the "got-body" signal. See onGotBody(org.gnome.soup.Message.GotBodyCallback).

onGotBodyData

public SignalConnection<Message.GotBodyDataCallback> onGotBodyData(Message.GotBodyDataCallback handler)

Emitted after reading a portion of the message body from the network.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

Since:

3.4

See Also:

• Message.GotBodyDataCallback.run(int)

emitGotBodyData

public void emitGotBodyData(int chunkSize)

Emits the "got-body-data" signal. See onGotBodyData(org.gnome.soup.Message.GotBodyDataCallback).

onGotHeaders

public SignalConnection<Message.GotHeadersCallback> onGotHeaders(Message.GotHeadersCallback handler)

Emitted after receiving the Status-Line and response headers.

See also addHeaderHandler(java.lang.String, java.lang.String, org.gnome.gobject.Callback) and addStatusCodeHandler(java.lang.String, int, org.gnome.gobject.Callback), which can be used to connect to a subset of emissions of this signal.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a Message::got-body handler rather than a Message::got_headers handler, so that the existing HTTP connection can be reused.)

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.GotHeadersCallback.run()

emitGotHeaders

public void emitGotHeaders()

Emits the "got-headers" signal. See onGotHeaders(org.gnome.soup.Message.GotHeadersCallback).

onGotInformational

public SignalConnection<Message.GotInformationalCallback> onGotInformational(Message.GotInformationalCallback handler)

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.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.GotInformationalCallback.run()

emitGotInformational

public void emitGotInformational()

Emits the "got-informational" signal. See onGotInformational(org.gnome.soup.Message.GotInformationalCallback).

onHstsEnforced

public SignalConnection<Message.HstsEnforcedCallback> onHstsEnforced(Message.HstsEnforcedCallback handler)

Emitted when HSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.HstsEnforcedCallback.run()

emitHstsEnforced

public void emitHstsEnforced()

Emits the "hsts-enforced" signal. See onHstsEnforced(org.gnome.soup.Message.HstsEnforcedCallback).

onNetworkEvent

public SignalConnection<Message.NetworkEventCallback> onNetworkEvent(Message.NetworkEventCallback handler)

Emitted to indicate that some network-related event related to msg has occurred.

This essentially proxies the Gio.SocketClient::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 MessageFlags.NEW_CONNECTION flag on it.)

See Gio.SocketClient::event for more information on what the different values of event correspond to, and what connection will be in each case.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.NetworkEventCallback.run(org.gnome.gio.SocketClientEvent, org.gnome.gio.IOStream)

emitNetworkEvent

public void emitNetworkEvent(SocketClientEvent event,
 @Nullable IOStream connection)

Emits the "network-event" signal. See onNetworkEvent(org.gnome.soup.Message.NetworkEventCallback).

onRequestCertificate

public SignalConnection<Message.RequestCertificateCallback> onRequestCertificate(Message.RequestCertificateCallback handler)

Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate from the client.

You can set the client certificate by calling setTlsClientCertificate(org.gnome.gio.TlsCertificate) and returning true. It's possible to handle the request asynchornously by returning true and call setTlsClientCertificate(org.gnome.gio.TlsCertificate) later once the certificate is available. Note that this signal is not emitted if Session:tls-interaction was set, or if setTlsClientCertificate(org.gnome.gio.TlsCertificate) was called before the connection TLS handshake started.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.RequestCertificateCallback.run(org.gnome.gio.TlsClientConnection)

emitRequestCertificate

public boolean emitRequestCertificate(@Nullable TlsClientConnection tlsConnection)

Emits the "request-certificate" signal. See onRequestCertificate(org.gnome.soup.Message.RequestCertificateCallback).

onRequestCertificatePassword

public SignalConnection<Message.RequestCertificatePasswordCallback> onRequestCertificatePassword(Message.RequestCertificatePasswordCallback handler)

Emitted during the msg's connection TLS handshake when tlsConnection requests a certificate password from the client.

You can set the certificate password on password, then call tlsClientCertificatePasswordRequestComplete() and return true to handle the signal synchronously. It's possible to handle the request asynchornously by calling GObject.ref() on password, then returning true and call tlsClientCertificatePasswordRequestComplete() later after setting the password on password. Note that this signal is not emitted if Session:tls-interaction was set.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.RequestCertificatePasswordCallback.run(org.gnome.gio.TlsPassword)

emitRequestCertificatePassword

public boolean emitRequestCertificatePassword(@Nullable TlsPassword tlsPassword)

Emits the "request-certificate-password" signal. See onRequestCertificatePassword(org.gnome.soup.Message.RequestCertificatePasswordCallback).

onRestarted

public SignalConnection<Message.RestartedCallback> onRestarted(Message.RestartedCallback handler)

Emitted when a request that was already sent once is now being sent again.

e.g. because the first attempt received a redirection response, or because we needed to use authentication.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.RestartedCallback.run()

emitRestarted

public void emitRestarted()

Emits the "restarted" signal. See onRestarted(org.gnome.soup.Message.RestartedCallback).

onStarting

public SignalConnection<Message.StartingCallback> onStarting(Message.StartingCallback handler)

Emitted just before a message is sent.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.StartingCallback.run()

emitStarting

public void emitStarting()

Emits the "starting" signal. See onStarting(org.gnome.soup.Message.StartingCallback).

onWroteBody

public SignalConnection<Message.WroteBodyCallback> onWroteBody(Message.WroteBodyCallback handler)

Emitted immediately after writing the complete body for a message.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.WroteBodyCallback.run()

emitWroteBody

public void emitWroteBody()

Emits the "wrote-body" signal. See onWroteBody(org.gnome.soup.Message.WroteBodyCallback).

onWroteBodyData

public SignalConnection<Message.WroteBodyDataCallback> onWroteBodyData(Message.WroteBodyDataCallback handler)

Emitted immediately after writing a portion of the message body to the network.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.WroteBodyDataCallback.run(int)

emitWroteBodyData

public void emitWroteBodyData(int chunkSize)

Emits the "wrote-body-data" signal. See onWroteBodyData(org.gnome.soup.Message.WroteBodyDataCallback).

onWroteHeaders

public SignalConnection<Message.WroteHeadersCallback> onWroteHeaders(Message.WroteHeadersCallback handler)

Emitted immediately after writing the request headers for a message.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Message.WroteHeadersCallback.run()

emitWroteHeaders

public void emitWroteHeaders()

Emits the "wrote-headers" signal. See onWroteHeaders(org.gnome.soup.Message.WroteHeadersCallback).

builder

public static Message.Builder<? extends Message.Builder> builder()

A Message.Builder object constructs a Message with the specified properties. Use the various set...() methods to set properties, and finish construction with Message.Builder.build().

Returns:

the builder object