Package org.gnome.soup

Class WebsocketConnection

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.soup.WebsocketConnection

All Implemented Interfaces:

Proxy

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

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a Session and call Session.websocketConnectAsync(org.gnome.soup.Message, java.lang.String, java.lang.String[], int, org.gnome.gio.Cancellable, org.gnome.gio.AsyncReadyCallback). To accept WebSocket connections, create a Server and add a handler to it with Server.addWebsocketHandler(java.lang.String, java.lang.String, java.lang.String[], org.gnome.soup.ServerWebsocketCallback).

(Lower-level support is available via Soup.websocketClientPrepareHandshake(org.gnome.soup.Message, java.lang.String, java.lang.String[], org.gnome.gobject.TypeClass[]) and Soup.websocketClientVerifyHandshake(org.gnome.soup.Message, org.gnome.gobject.TypeClass[], org.javagi.base.Out<org.gnome.glib.List<org.gnome.soup.WebsocketExtension>>), for handling the client side of the WebSocket handshake, and Soup.websocketServerProcessHandshake(org.gnome.soup.ServerMessage, java.lang.String, java.lang.String[], org.gnome.gobject.TypeClass[], org.javagi.base.Out<org.gnome.glib.List<org.gnome.soup.WebsocketExtension>>) for handling the server side.)

SoupWebsocketConnection handles the details of WebSocket communication. You can use sendText(java.lang.String) and sendBinary(byte[]) to send data, and the WebsocketConnection::message signal to receive data. (SoupWebsocketConnection currently only supports asynchronous I/O.)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	WebsocketConnection.Builder<B extends WebsocketConnection.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	WebsocketConnection.ClosedCallback	Functional interface declaration of the ClosedCallback callback.
static interface	WebsocketConnection.ClosingCallback	Functional interface declaration of the ClosingCallback callback.
static interface	WebsocketConnection.ErrorCallback	Functional interface declaration of the ErrorCallback callback.
static interface	WebsocketConnection.MessageCallback	Functional interface declaration of the MessageCallback callback.
static interface	WebsocketConnection.PongCallback	Functional interface declaration of the PongCallback callback.
static class	WebsocketConnection.WebsocketConnectionClass	The abstract base class for WebsocketConnection.

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

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
WebsocketConnection()	Creates a new WebsocketConnection.
WebsocketConnection(MemorySegment address)	Create a WebsocketConnection proxy instance for the provided memory address.
WebsocketConnection(IOStream stream, Uri uri, WebsocketConnectionType type, @Nullable String origin, @Nullable String protocol, List<WebsocketExtension> extensions)	Creates a SoupWebsocketConnection on stream with the given active extensions.

Method Summary

Modifier and Type	Method	Description
protected WebsocketConnection	asParent()	Returns this instance as if it were its parent type.
static WebsocketConnection.Builder<? extends WebsocketConnection.Builder>	builder()	A WebsocketConnection.Builder object constructs a WebsocketConnection with the specified properties.
void	close(short code, @Nullable String data)	Close the connection in an orderly fashion.
void	emitClosed()	Emits the "closed" signal.
void	emitClosing()	Emits the "closing" signal.
void	emitError(@Nullable GError error)	Emits the "error" signal.
void	emitMessage(int type, byte @Nullable [] message)	Emits the "message" signal.
void	emitPong(byte @Nullable [] message)	Emits the "pong" signal.
short	getCloseCode()	Get the close code received from the WebSocket peer.
String	getCloseData()	Get the close data received from the WebSocket peer.
WebsocketConnectionType	getConnectionType()	Get the connection type (client/server) of the connection.
List<WebsocketExtension>	getExtensions()	Get the extensions chosen via negotiation with the peer.
IOStream	getIoStream()	Get the I/O stream the WebSocket is communicating over.
int	getKeepaliveInterval()	Gets the keepalive interval in seconds or 0 if disabled.
int	getKeepalivePongTimeout()	Gets the keepalive pong timeout in seconds or 0 if disabled.
long	getMaxIncomingPayloadSize()	Gets the maximum payload size allowed for incoming packets.
@Nullable String	getOrigin()	Get the origin of the WebSocket.
@Nullable String	getProtocol()	Get the protocol chosen via negotiation with the peer.
WebsocketState	getState()	Get the current state of the WebSocket.
static @Nullable Type	getType()	Get the GType of the WebsocketConnection class
Uri	getUri()	Get the URI of the WebSocket.
SignalConnection<WebsocketConnection.ClosedCallback>	onClosed(WebsocketConnection.ClosedCallback handler)	Emitted when the connection has completely closed.
SignalConnection<WebsocketConnection.ClosingCallback>	onClosing(WebsocketConnection.ClosingCallback handler)	This signal will be emitted during an orderly close.
SignalConnection<WebsocketConnection.ErrorCallback>	onError(WebsocketConnection.ErrorCallback handler)	Emitted when an error occurred on the WebSocket.
SignalConnection<WebsocketConnection.MessageCallback>	onMessage(WebsocketConnection.MessageCallback handler)	Emitted when we receive a message from the peer.
SignalConnection<WebsocketConnection.PongCallback>	onPong(WebsocketConnection.PongCallback handler)	Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.
void	sendBinary(@org.jspecify.annotations.Nullable byte @Nullable [] data)	Send a binary message to the peer.
void	sendMessage(WebsocketDataType type, byte[] message)	Send a message of the given type to the peer.
void	sendText(String text)	Send a null-terminated text (UTF-8) message to the peer.
void	setKeepaliveInterval(int interval)	Sets the interval in seconds on when to send a ping message which will serve as a keepalive message.
void	setKeepalivePongTimeout(int pongTimeout)	Set the timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection.
void	setMaxIncomingPayloadSize(long maxIncomingPayloadSize)	Sets the maximum payload size allowed for incoming packets.

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

WebsocketConnection

public WebsocketConnection(MemorySegment address)

Create a WebsocketConnection proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

WebsocketConnection

public WebsocketConnection(IOStream stream,
 Uri uri,
 WebsocketConnectionType type,
 @Nullable String origin,
 @Nullable String protocol,
 List<WebsocketExtension> extensions)

Creates a SoupWebsocketConnection on stream with the given active extensions.

This should be called after completing the handshake to begin using the WebSocket protocol.

Parameters:

stream - a GIOStream connected to the WebSocket server

uri - the URI of the connection

type - the type of connection (client/side)

origin - the Origin of the client

protocol - the subprotocol in use

extensions - a GList of SoupWebsocketExtension objects

WebsocketConnection

public WebsocketConnection()

Creates a new WebsocketConnection.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the WebsocketConnection class

Returns:

the GType

asParent

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

close

public void close(short code,
 @Nullable String data)

Close the connection in an orderly fashion.

Note that until the WebsocketConnection::closed signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.

The code and data are sent to the peer along with the close request. If code is WebsocketCloseCode.NO_STATUS a close message with no body (without code and data) is sent. Note that the data must be UTF-8 valid.

Parameters:

code - close code

data - close data

getCloseCode

public short getCloseCode()

Get the close code received from the WebSocket peer.

This only becomes valid once the WebSocket is in the WebsocketState.CLOSED state. The value will often be in the WebsocketCloseCode enumeration, but may also be an application defined close code.

Returns:

the close code or zero.

getCloseData

public String getCloseData()

Get the close data received from the WebSocket peer.

This only becomes valid once the WebSocket is in the WebsocketState.CLOSED state. The data may be freed once the main loop is run, so copy it if you need to keep it around.

Returns:

the close data or null

getConnectionType

public WebsocketConnectionType getConnectionType()

Get the connection type (client/server) of the connection.

Returns:

the connection type

getExtensions

public List<WebsocketExtension> getExtensions()

Get the extensions chosen via negotiation with the peer.

Returns:

a GList of SoupWebsocketExtension objects

getIoStream

public IOStream getIoStream()

Get the I/O stream the WebSocket is communicating over.

Returns:

the WebSocket's I/O stream.

getKeepaliveInterval

public int getKeepaliveInterval()

Gets the keepalive interval in seconds or 0 if disabled.

Returns:

the keepalive interval.

getKeepalivePongTimeout

public int getKeepalivePongTimeout()

Gets the keepalive pong timeout in seconds or 0 if disabled.

Returns:

the keepalive pong timeout.

Since:

3.6

getMaxIncomingPayloadSize

public long getMaxIncomingPayloadSize()

Gets the maximum payload size allowed for incoming packets.

Returns:

the maximum payload size.

getOrigin

public @Nullable String getOrigin()

Get the origin of the WebSocket.

Returns:

the origin

getProtocol

public @Nullable String getProtocol()

Get the protocol chosen via negotiation with the peer.

Returns:

the chosen protocol

getState

public WebsocketState getState()

Get the current state of the WebSocket.

Returns:

the state

getUri

public Uri getUri()

Get the URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

Returns:

the URI

sendBinary

public void sendBinary(@org.jspecify.annotations.Nullable byte @Nullable [] data)

Send a binary message to the peer.

If length is 0, data may be null.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

data - the message contents

sendMessage

public void sendMessage(WebsocketDataType type,
 byte[] message)

Send a message of the given type to the peer. Note that this method, allows to send text messages containing null characters.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

type - the type of message contents

message - the message data as GBytes

sendText

public void sendText(String text)

Send a null-terminated text (UTF-8) message to the peer.

If you need to send text messages containing null characters use sendMessage(org.gnome.soup.WebsocketDataType, byte[]) instead.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

text - the message contents

setKeepaliveInterval

public void setKeepaliveInterval(int interval)

Sets the interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

Parameters:

interval - the interval to send a ping message or 0 to disable it

setKeepalivePongTimeout

public void setKeepalivePongTimeout(int pongTimeout)

Set the timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection.

If set to 0 then the absence of pongs from keepalive pings is ignored.

Parameters:

pongTimeout - the timeout in seconds

Since:

3.6

setMaxIncomingPayloadSize

public void setMaxIncomingPayloadSize(long maxIncomingPayloadSize)

Sets the maximum payload size allowed for incoming packets.

It does not limit the outgoing packet size.

Parameters:

maxIncomingPayloadSize - the maximum payload size

onClosed

public SignalConnection<WebsocketConnection.ClosedCallback> onClosed(WebsocketConnection.ClosedCallback handler)

Emitted when the connection has completely closed.

This happens either due to an orderly close from the peer, one initiated via close(short, java.lang.String) or a fatal error condition that caused a close.

This signal will be emitted once.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• WebsocketConnection.ClosedCallback.run()

emitClosed

public void emitClosed()

Emits the "closed" signal. See onClosed(org.gnome.soup.WebsocketConnection.ClosedCallback).

onClosing

public SignalConnection<WebsocketConnection.ClosingCallback> onClosing(WebsocketConnection.ClosingCallback handler)

This signal will be emitted during an orderly close.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• WebsocketConnection.ClosingCallback.run()

emitClosing

public void emitClosing()

Emits the "closing" signal. See onClosing(org.gnome.soup.WebsocketConnection.ClosingCallback).

onError

public SignalConnection<WebsocketConnection.ErrorCallback> onError(WebsocketConnection.ErrorCallback handler)

Emitted when an error occurred on the WebSocket.

This may be fired multiple times. Fatal errors will be followed by the WebsocketConnection::closed signal being emitted.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• WebsocketConnection.ErrorCallback.run(org.gnome.glib.GError)

emitError

public void emitError(@Nullable GError error)

Emits the "error" signal. See onError(org.gnome.soup.WebsocketConnection.ErrorCallback).

onMessage

public SignalConnection<WebsocketConnection.MessageCallback> onMessage(WebsocketConnection.MessageCallback handler)

Emitted when we receive a message from the peer.

As a convenience, the message data will always be null-terminated, but the NUL byte will not be included in the length count.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• WebsocketConnection.MessageCallback.run(int, byte[])

emitMessage

public void emitMessage(int type,
 byte @Nullable [] message)

Emits the "message" signal. See onMessage(org.gnome.soup.WebsocketConnection.MessageCallback).

onPong

public SignalConnection<WebsocketConnection.PongCallback> onPong(WebsocketConnection.PongCallback handler)

Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.

As a convenience, the message data will always be null-terminated, but the NUL byte will not be included in the length count.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• WebsocketConnection.PongCallback.run(byte[])

emitPong

public void emitPong(byte @Nullable [] message)

Emits the "pong" signal. See onPong(org.gnome.soup.WebsocketConnection.PongCallback).

builder

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

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

Returns:

the builder object