Struct soup::WebsocketConnection

pub struct WebsocketConnection { /* private fields */ }

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a Session and call Session::websocket_connect_async(). To accept WebSocket connections, create a Server and add a handler to it with ServerExtManual::add_websocket_handler().

(Lower-level support is available via websocket_client_prepare_handshake() and websocket_client_verify_handshake(), for handling the client side of the WebSocket handshake, and websocket_server_process_handshake() for handling the server side.)

#SoupWebsocketConnection handles the details of WebSocket communication. You can use send_text() and WebsocketConnection::send_binary() to send data, and the message signal to receive data. (#SoupWebsocketConnection currently only supports asynchronous I/O.)

Properties

connection-type

The type of connection (client/server).

Readable | Writeable | Construct Only

extensions

List of WebsocketExtension objects that are active in the connection.

Readable | Writeable | Construct Only

io-stream

The underlying IO stream the WebSocket is communicating over.

The input and output streams must be pollable streams.

Readable | Writeable | Construct Only

keepalive-interval

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.

Readable | Writeable | Construct

keepalive-pong-timeout

Timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection. The WebSocket will be transitioned to a closed state when this happens.

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

Readable | Writeable | Construct

max-incoming-payload-size

The maximum payload size for incoming packets.

The protocol expects or 0 to not limit it.

Readable | Writeable | Construct

origin

The client’s Origin.

Readable | Writeable | Construct Only

protocol

The chosen protocol, or None if a protocol was not agreed upon.

Readable | Writeable | Construct Only

state

The current state of the WebSocket.

Readable

uri

The URI of the WebSocket.

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

Readable | Writeable | Construct Only

Signals

closed

Emitted when the connection has completely closed.

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

This signal will be emitted once.

closing

This signal will be emitted during an orderly close.

error

Emitted when an error occurred on the WebSocket.

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

message

Emitted when we receive a message from the peer.

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

pong

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

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

Implements

[trait@glib::ObjectExt], WebsocketConnectionExtManual

Implementations

impl WebsocketConnection

pub fn builder() -> WebsocketConnectionBuilder

Creates a new builder-pattern struct instance to construct WebsocketConnection objects.

This method returns an instance of WebsocketConnectionBuilder which can be used to create WebsocketConnection objects.

pub fn close(&self, code: c_ushort, data: Option<&str>)

Close the connection in an orderly fashion.

Note that until the 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::NoStatus a close message with no body (without code and data) is sent. Note that the @data must be UTF-8 valid.

code

close code

data

close data

pub fn close_code(&self) -> c_ushort

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.

pub fn close_data(&self) -> Option<GString>

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 None

pub fn connection_type(&self) -> WebsocketConnectionType

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

Returns

the connection type

pub fn extensions(&self) -> Vec<WebsocketExtension>

Get the extensions chosen via negotiation with the peer.

Returns

a #GList of #SoupWebsocketExtension objects

pub fn io_stream(&self) -> Option<IOStream>

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

Returns

the WebSocket’s I/O stream.

pub fn keepalive_interval(&self) -> u32

Gets the keepalive interval in seconds or 0 if disabled.

Returns

the keepalive interval.

pub fn max_incoming_payload_size(&self) -> u64

Gets the maximum payload size allowed for incoming packets.

Returns

the maximum payload size.

pub fn origin(&self) -> Option<GString>

Get the origin of the WebSocket.

Returns

the origin

pub fn protocol(&self) -> Option<GString>

Get the protocol chosen via negotiation with the peer.

Returns

the chosen protocol

pub fn state(&self) -> WebsocketState

Get the current state of the WebSocket.

Returns

the state

pub fn uri(&self) -> Option<Uri>

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

pub fn send_text(&self, text: &str)

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

If you need to send text messages containing None characters use WebsocketConnection::send_message() instead.

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

text

the message contents

pub fn set_keepalive_interval(&self, interval: u32)

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.

interval

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

pub fn set_max_incoming_payload_size(&self, max_incoming_payload_size: u64)

Sets the maximum payload size allowed for incoming packets.

It does not limit the outgoing packet size.

max_incoming_payload_size

the maximum payload size

pub fn connect_closed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when the connection has completely closed.

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

This signal will be emitted once.

pub fn connect_closing<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

This signal will be emitted during an orderly close.

pub fn connect_error<F: Fn(&Self, &Error) + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when an error occurred on the WebSocket.

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

error

the error that occured

pub fn connect_message<F: Fn(&Self, i32, &Bytes) + 'static>( &self, f: F ) -> SignalHandlerId

Emitted when we receive a message from the peer.

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

type_

the type of message contents

message

the message data

pub fn connect_pong<F: Fn(&Self, &Bytes) + 'static>( &self, f: F ) -> SignalHandlerId

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

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

message

the application data (if any)

pub fn connect_keepalive_interval_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_max_incoming_payload_size_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_state_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Trait Implementations

impl Clone for WebsocketConnection

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WebsocketConnection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for WebsocketConnection

type ParamSpec = ParamSpecObject

type SetValue = WebsocketConnection

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, WebsocketConnection>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for WebsocketConnection

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for WebsocketConnection

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for WebsocketConnection

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for WebsocketConnection

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for WebsocketConnection

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for WebsocketConnection

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for WebsocketConnection