Package org.gnome.soup

Class ServerMessage

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.soup.ServerMessage

All Implemented Interfaces:

Proxy

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

An HTTP server request and response pair.

A SoupServerMessage represents an HTTP message that is being sent or received on a Server.

Server will create SoupServerMessages 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 either a Request, or a Response. In libsoup, a SoupServerMessage combines both the request and the response.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ServerMessage.AcceptCertificateCallback	Functional interface declaration of the AcceptCertificateCallback callback.
static class	ServerMessage.Builder<B extends ServerMessage.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	ServerMessage.ConnectedCallback	Functional interface declaration of the ConnectedCallback callback.
static interface	ServerMessage.DisconnectedCallback	Functional interface declaration of the DisconnectedCallback callback.
static interface	ServerMessage.FinishedCallback	Functional interface declaration of the FinishedCallback callback.
static interface	ServerMessage.GotBodyCallback	Functional interface declaration of the GotBodyCallback callback.
static interface	ServerMessage.GotChunkCallback	Functional interface declaration of the GotChunkCallback callback.
static interface	ServerMessage.GotHeadersCallback	Functional interface declaration of the GotHeadersCallback callback.
static class	ServerMessage.ServerMessageClass
static interface	ServerMessage.WroteBodyCallback	Functional interface declaration of the WroteBodyCallback callback.
static interface	ServerMessage.WroteBodyDataCallback	Functional interface declaration of the WroteBodyDataCallback callback.
static interface	ServerMessage.WroteChunkCallback	Functional interface declaration of the WroteChunkCallback callback.
static interface	ServerMessage.WroteHeadersCallback	Functional interface declaration of the WroteHeadersCallback callback.
static interface	ServerMessage.WroteInformationalCallback	Functional interface declaration of the WroteInformationalCallback callback.

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

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
ServerMessage()	Creates a new ServerMessage.
ServerMessage(MemorySegment address)	Create a ServerMessage proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected ServerMessage	asParent()	Returns this instance as if it were its parent type.
static ServerMessage.Builder<? extends ServerMessage.Builder>	builder()	A ServerMessage.Builder object constructs a ServerMessage with the specified properties.
boolean	emitAcceptCertificate(@Nullable TlsCertificate tlsPeerCertificate, Set<TlsCertificateFlags> tlsPeerErrors)	Emits the "accept-certificate" signal.
void	emitConnected()	Emits the "connected" signal.
void	emitDisconnected()	Emits the "disconnected" signal.
void	emitFinished()	Emits the "finished" signal.
void	emitGotBody()	Emits the "got-body" signal.
void	emitGotChunk(byte @Nullable [] chunk)	Emits the "got-chunk" signal.
void	emitGotHeaders()	Emits the "got-headers" signal.
void	emitWroteBody()	Emits the "wrote-body" signal.
void	emitWroteBodyData(int chunkSize)	Emits the "wrote-body-data" signal.
void	emitWroteChunk()	Emits the "wrote-chunk" signal.
void	emitWroteHeaders()	Emits the "wrote-headers" signal.
void	emitWroteInformational()	Emits the "wrote-informational" signal.
HTTPVersion	getHttpVersion()	Get the HTTP version of msg.
@Nullable SocketAddress	getLocalAddress()	Retrieves the SocketAddress associated with the local end of a connection.
String	getMethod()	Get the HTTP method of msg.
@Nullable String	getReasonPhrase()	Get the HTTP reason phrase of msg.
@Nullable SocketAddress	getRemoteAddress()	Retrieves the SocketAddress associated with the remote end of a connection.
@Nullable String	getRemoteHost()	Retrieves the IP address associated with the remote end of a connection.
MessageBody	getRequestBody()	Get the request body of msg.
MessageHeaders	getRequestHeaders()	Get the request headers of msg.
MessageBody	getResponseBody()	Get the response body of msg.
MessageHeaders	getResponseHeaders()	Get the response headers of msg.
@Nullable Socket	getSocket()	Retrieves the Socket that this ServerMessage is associated with.
int	getStatus()	Get the HTTP status code of msg.
@Nullable TlsCertificate	getTlsPeerCertificate()	Gets the peer's GTlsCertificate associated with msg's connection.
Set<TlsCertificateFlags>	getTlsPeerCertificateErrors()	Gets the errors associated with validating msg's TLS peer certificate.
static @Nullable Type	getType()	Get the GType of the ServerMessage class
Uri	getUri()	Get msg's URI.
boolean	isOptionsPing()	Gets if this ServerMessage represents an OPTIONS message with the path *.
SignalConnection<ServerMessage.AcceptCertificateCallback>	onAcceptCertificate(ServerMessage.AcceptCertificateCallback handler)	Emitted during the msg's connection TLS handshake after client TLS certificate has been received.
SignalConnection<ServerMessage.ConnectedCallback>	onConnected(ServerMessage.ConnectedCallback handler)	Emitted when the msg's socket is connected and the TLS handshake completed.
SignalConnection<ServerMessage.DisconnectedCallback>	onDisconnected(ServerMessage.DisconnectedCallback handler)	Emitted when the msg's socket is disconnected.
SignalConnection<ServerMessage.FinishedCallback>	onFinished(ServerMessage.FinishedCallback handler)	Emitted when all HTTP processing is finished for a message.
SignalConnection<ServerMessage.GotBodyCallback>	onGotBody(ServerMessage.GotBodyCallback handler)	Emitted after receiving the complete request body.
SignalConnection<ServerMessage.GotChunkCallback>	onGotChunk(ServerMessage.GotChunkCallback handler)	Emitted after receiving a chunk of a message body.
SignalConnection<ServerMessage.GotHeadersCallback>	onGotHeaders(ServerMessage.GotHeadersCallback handler)	Emitted after receiving the Request-Line and request headers.
SignalConnection<ServerMessage.WroteBodyCallback>	onWroteBody(ServerMessage.WroteBodyCallback handler)	Emitted immediately after writing the complete response body for a message.
SignalConnection<ServerMessage.WroteBodyDataCallback>	onWroteBodyData(ServerMessage.WroteBodyDataCallback handler)	Emitted immediately after writing a portion of the message body to the network.
SignalConnection<ServerMessage.WroteChunkCallback>	onWroteChunk(ServerMessage.WroteChunkCallback handler)	Emitted immediately after writing a body chunk for a message.
SignalConnection<ServerMessage.WroteHeadersCallback>	onWroteHeaders(ServerMessage.WroteHeadersCallback handler)	Emitted immediately after writing the response headers for a message.
SignalConnection<ServerMessage.WroteInformationalCallback>	onWroteInformational(ServerMessage.WroteInformationalCallback handler)	Emitted immediately after writing a 1xx (Informational) response.
void	pause()	Pauses I/O on msg.
void	setHttpVersion(HTTPVersion version)	Set the HTTP version of msg.
void	setRedirect(int statusCode, String redirectUri)	Sets msg's status_code to statusCode and adds a Location header pointing to redirectUri. Use this from a Server when you want to redirect the client to another URI.
void	setResponse(@Nullable String contentType, MemoryUse respUse, @org.jspecify.annotations.Nullable byte @Nullable [] respBody)	Convenience function to set the response body of a SoupServerMessage.
void	setStatus(int statusCode, @Nullable String reasonPhrase)	Sets msg's status code to statusCode.
IOStream	stealConnection()	"Steals" the HTTP connection associated with this ServerMessage from its SoupServer.
void	unpause()	Resumes I/O on msg.

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

ServerMessage

public ServerMessage(MemorySegment address)

Create a ServerMessage proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

ServerMessage

public ServerMessage()

Creates a new ServerMessage.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the ServerMessage class

Returns:

the GType

asParent

protected ServerMessage 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

getHttpVersion

public HTTPVersion getHttpVersion()

Get the HTTP version of msg.

Returns:

a SoupHTTPVersion.

getLocalAddress

public @Nullable SocketAddress getLocalAddress()

Retrieves the SocketAddress associated with the local end of a connection.

Returns:

the GSocketAddress associated with the local end of a connection, it may be null if you used Server.acceptIostream(org.gnome.gio.IOStream, org.gnome.gio.SocketAddress, org.gnome.gio.SocketAddress).

getMethod

public String getMethod()

Get the HTTP method of msg.

Returns:

the HTTP method.

getReasonPhrase

public @Nullable String getReasonPhrase()

Get the HTTP reason phrase of msg.

Returns:

the reason phrase.

getRemoteAddress

public @Nullable SocketAddress getRemoteAddress()

Retrieves the SocketAddress associated with the remote end of a connection.

Returns:

the GSocketAddress associated with the remote end of a connection, it may be null if you used Server.acceptIostream(org.gnome.gio.IOStream, org.gnome.gio.SocketAddress, org.gnome.gio.SocketAddress).

getRemoteHost

public @Nullable String getRemoteHost()

Retrieves the IP address associated with the remote end of a connection.

Returns:

the IP address associated with the remote end of a connection, it may be null if you used Server.acceptIostream(org.gnome.gio.IOStream, org.gnome.gio.SocketAddress, org.gnome.gio.SocketAddress).

getRequestBody

public MessageBody getRequestBody()

Get the request body of msg.

Returns:

a SoupMessageBody.

getRequestHeaders

public MessageHeaders getRequestHeaders()

Get the request headers of msg.

Returns:

a SoupMessageHeaders with the request headers.

getResponseBody

public MessageBody getResponseBody()

Get the response body of msg.

Returns:

a SoupMessageBody.

getResponseHeaders

public MessageHeaders getResponseHeaders()

Get the response headers of msg.

Returns:

a SoupMessageHeaders with the response headers.

getSocket

public @Nullable Socket getSocket()

Retrieves the Socket that this ServerMessage is associated with.

If you are using this method to observe when multiple requests are made on the same persistent HTTP connection (eg, as the ntlm-test test program does), you will need to pay attention to socket destruction as well (eg, by using weak references), so that you do not get fooled when the allocator reuses the memory address of a previously-destroyed socket to represent a new socket.

Returns:

the GSocket that this ServerMessage is associated with, null if you used Server.acceptIostream(org.gnome.gio.IOStream, org.gnome.gio.SocketAddress, org.gnome.gio.SocketAddress).

getStatus

public int getStatus()

Get the HTTP status code of msg.

Returns:

the HTTP status code.

getTlsPeerCertificate

public @Nullable TlsCertificate getTlsPeerCertificate()

Gets the peer's GTlsCertificate associated with msg's connection. Note that this is not set yet during the emission of SoupServerMessage::accept-certificate signal.

Returns:

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

Since:

3.2

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 SoupServerMessage::accept-certificate signal.

Returns:

a GTlsCertificateFlags with msg's TLS peer certificate errors.

Since:

3.2

getUri

public Uri getUri()

Get msg's URI.

Returns:

a GUri

isOptionsPing

public boolean isOptionsPing()

Gets if this ServerMessage represents an OPTIONS message with the path *.

Returns:

true if is an OPTIONS ping

pause

public void pause()

Pauses I/O on msg.

This can be used when you need to return from the server handler without having the full response ready yet. Use unpause() to resume I/O.

Since:

3.2

setHttpVersion

public void setHttpVersion(HTTPVersion version)

Set the HTTP version of msg.

Parameters:

version - a SoupHTTPVersion

setRedirect

public void setRedirect(int statusCode,
 String redirectUri)

Sets msg's status_code to statusCode and adds a Location header pointing to redirectUri. Use this from a Server when you want to redirect the client to another URI.

redirectUri can be a relative URI, in which case it is interpreted relative to msg's current URI. In particular, if redirectUri is just a path, it will replace the path *and query* of msg's URI.

Parameters:

statusCode - a 3xx status code

redirectUri - the URI to redirect this ServerMessage to

setResponse

public void setResponse(@Nullable String contentType,
 MemoryUse respUse,
 @org.jspecify.annotations.Nullable byte @Nullable [] respBody)

Convenience function to set the response body of a SoupServerMessage. If contentType is null, the response body must be empty as well.

Parameters:

contentType - MIME Content-Type of the body

respUse - a SoupMemoryUse describing how to handle respBody

respBody - a data buffer containing the body of the message response.

setStatus

public void setStatus(int statusCode,
 @Nullable String reasonPhrase)

Sets msg's status code to statusCode.

If statusCode is a known value and reasonPhrase is null, the reason_phrase will be set automatically.

Parameters:

statusCode - an HTTP status code

reasonPhrase - a reason phrase

stealConnection

public IOStream stealConnection()

"Steals" the HTTP connection associated with this ServerMessage from its SoupServer. This happens immediately, regardless of the current state of the connection; if the response to this ServerMessage has not yet finished being sent, then it will be discarded; you can steal the connection from a ServerMessage::wrote-informational or ServerMessage::wrote-body signal handler if you need to wait for part or all of the response to be sent.

Note that when calling this function from C, this ServerMessage will most likely be freed as a side effect.

Returns:

the GIOStream formerly associated with this ServerMessage (or null if this ServerMessage was no longer associated with a connection). No guarantees are made about what kind of GIOStream is returned.

unpause

public void unpause()

Resumes I/O on msg.

Use this to resume after calling pause(), or after adding a new chunk to a chunked response. I/O won't actually resume until you return to the main loop.

Since:

3.2

onAcceptCertificate

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

Emitted during the msg's connection TLS handshake after client 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:

• ServerMessage.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.ServerMessage.AcceptCertificateCallback).

onConnected

public SignalConnection<ServerMessage.ConnectedCallback> onConnected(ServerMessage.ConnectedCallback handler)

Emitted when the msg's socket is connected and the TLS handshake completed.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.ConnectedCallback.run()

emitConnected

public void emitConnected()

Emits the "connected" signal. See onConnected(org.gnome.soup.ServerMessage.ConnectedCallback).

onDisconnected

public SignalConnection<ServerMessage.DisconnectedCallback> onDisconnected(ServerMessage.DisconnectedCallback handler)

Emitted when the msg's socket is disconnected.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.DisconnectedCallback.run()

emitDisconnected

public void emitDisconnected()

Emits the "disconnected" signal. See onDisconnected(org.gnome.soup.ServerMessage.DisconnectedCallback).

onFinished

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

Emitted when all HTTP processing is finished for a message. (After ServerMessage::wrote-body).

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.FinishedCallback.run()

emitFinished

public void emitFinished()

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

onGotBody

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

Emitted after receiving the complete request body.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.GotBodyCallback.run()

emitGotBody

public void emitGotBody()

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

onGotChunk

public SignalConnection<ServerMessage.GotChunkCallback> onGotChunk(ServerMessage.GotChunkCallback handler)

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.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.GotChunkCallback.run(byte[])

emitGotChunk

public void emitGotChunk(byte @Nullable [] chunk)

Emits the "got-chunk" signal. See onGotChunk(org.gnome.soup.ServerMessage.GotChunkCallback).

onGotHeaders

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

Emitted after receiving the Request-Line and request headers.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.GotHeadersCallback.run()

emitGotHeaders

public void emitGotHeaders()

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

onWroteBody

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

Emitted immediately after writing the complete response body for a message.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.WroteBodyCallback.run()

emitWroteBody

public void emitWroteBody()

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

onWroteBodyData

public SignalConnection<ServerMessage.WroteBodyDataCallback> onWroteBodyData(ServerMessage.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:

• ServerMessage.WroteBodyDataCallback.run(int)

emitWroteBodyData

public void emitWroteBodyData(int chunkSize)

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

onWroteChunk

public SignalConnection<ServerMessage.WroteChunkCallback> onWroteChunk(ServerMessage.WroteChunkCallback handler)

Emitted immediately after writing a body chunk for a message.

Note that this signal is not parallel to ServerMessage::got-chunk; it is emitted only when a complete chunk (added with MessageBody.append(byte[]) or MessageBody.appendBytes(byte[]) has been written. To get more useful continuous progress information, use ServerMessage::wrote-body-data.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.WroteChunkCallback.run()

emitWroteChunk

public void emitWroteChunk()

Emits the "wrote-chunk" signal. See onWroteChunk(org.gnome.soup.ServerMessage.WroteChunkCallback).

onWroteHeaders

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

Emitted immediately after writing the response headers for a message.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.WroteHeadersCallback.run()

emitWroteHeaders

public void emitWroteHeaders()

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

onWroteInformational

public SignalConnection<ServerMessage.WroteInformationalCallback> onWroteInformational(ServerMessage.WroteInformationalCallback handler)

Emitted immediately after writing a 1xx (Informational) response.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• ServerMessage.WroteInformationalCallback.run()

emitWroteInformational

public void emitWroteInformational()

Emits the "wrote-informational" signal. See onWroteInformational(org.gnome.soup.ServerMessage.WroteInformationalCallback).

builder

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

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

Returns:

the builder object