Soup.Socket

g GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object Soup.Socket Soup.Socket GObject.Object->Soup.Socket Gio.Initable->Soup.Socket

Subclasses:

None

Methods

Inherited:

GObject.Object (37), Gio.Initable (2)

Structs:

GObject.ObjectClass (5)

connect_async (cancellable, callback, *user_data)

connect_sync (cancellable)

disconnect ()

get_fd ()

get_local_address ()

get_remote_address ()

is_connected ()

is_ssl ()

listen ()

read (buffer, cancellable)

read_until (buffer, boundary, boundary_len, cancellable)

start_proxy_ssl (ssl_host, cancellable)

start_ssl (cancellable)

write (buffer, cancellable)

Virtual Methods

Inherited:

GObject.Object (7), Gio.Initable (1)

do_disconnected ()

do_new_connection (new_sock)

do_readable ()

do_writable ()

Properties

Name

Type

Flags

Short Description

async-context

int

r/w/co

The GLib.MainContext to dispatch this socket’s async I/O in

fd

int

r/w/co

The socket’s file descriptor

gsocket

Gio.Socket

w/co

The socket’s underlying Gio.Socket

iostream

Gio.IOStream

w/co

The socket’s underlying Gio.IOStream

ipv6-only

bool

r/w

IPv6 only

is-server

bool

r

Whether or not the socket is a server socket

local-address

Soup.Address

r/w/co

Address of local end of socket

non-blocking

bool

r/w

Whether or not the socket uses non-blocking I/O

remote-address

Soup.Address

r/w/co

Address of remote end of socket

ssl-creds

int

r/w

SSL credential information, passed from the session to the SSL implementation

ssl-fallback

bool

r/w/co

Use SSLv3 instead of TLS (client-side only)

ssl-strict

bool

r/w/co

Whether certificate errors should be considered a connection error

timeout

int

r/w

Value in seconds to timeout a blocking I/O

tls-certificate

Gio.TlsCertificate

r

The peer’s TLS certificate

tls-errors

Gio.TlsCertificateFlags

r

Errors with the peer’s TLS certificate

trusted-certificate

bool

r

Whether the server certificate is trusted, if this is an SSL socket

use-thread-context

bool

r/w/co

Use GLib.MainContext.get_thread_default

Signals

Inherited:

GObject.Object (1)

Name

Short Description

disconnected

Emitted when the socket is disconnected, for whatever reason.

event

Emitted when a network-related event occurs.

new-connection

Emitted when a listening socket (set up with Soup.Socket.listen()) receives a new connection.

readable

Emitted when an async socket is readable.

writable

Emitted when an async socket is writable.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GObject.Object

r

Class Details

class Soup.Socket(**kwargs)
Bases:

GObject.Object, Gio.Initable

Abstract:

No

Structure:

Soup.SocketClass

connect_async(cancellable, callback, *user_data)
Parameters:

Begins asynchronously connecting to self's remote address. The socket will call callback when it succeeds or fails (but not before returning from this function).

If cancellable is non-None, it can be used to cancel the connection. callback will still be invoked in this case, with a status of Soup.Status.CANCELLED.

connect_sync(cancellable)
Parameters:

cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Returns:

a success or failure code.

Return type:

int

Attempt to synchronously connect self to its remote address.

If cancellable is non-None, it can be used to cancel the connection, in which case Soup.Socket.connect_sync() will return Soup.Status.CANCELLED.

disconnect()

Disconnects self. Any further read or write attempts on it will fail.

get_fd()
Returns:

self's file descriptor.

Return type:

int

Gets self's underlying file descriptor.

Note that fiddling with the file descriptor may break the Soup.Socket.

get_local_address()
Returns:

the Soup.Address

Return type:

Soup.Address

Returns the Soup.Address corresponding to the local end of self.

Calling this method on an unconnected socket is considered to be an error, and produces undefined results.

get_remote_address()
Returns:

the Soup.Address

Return type:

Soup.Address

Returns the Soup.Address corresponding to the remote end of self.

Calling this method on an unconnected socket is considered to be an error, and produces undefined results.

is_connected()
Returns:

True or False.

Return type:

bool

Tests if self is connected to another host

is_ssl()
Returns:

True if self has SSL credentials set

Return type:

bool

Tests if self is doing (or has attempted to do) SSL.

listen()
Returns:

whether or not self is now listening.

Return type:

bool

Makes self start listening on its local address. When connections come in, self will emit #SoupSocket::new_connection.

read(buffer, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a Soup.SocketIOStatus, as described above (or Soup.SocketIOStatus.EOF if the socket is no longer connected, or Soup.SocketIOStatus.ERROR on any other error, in which case error will also be set).

nread:

on return, the number of bytes read into buffer

Return type:

(Soup.SocketIOStatus, nread: int)

Attempts to read up to len bytes from self into buffer. If some data is successfully read, Soup.Socket.read() will return Soup.SocketIOStatus.OK, and nread will contain the number of bytes actually read (which may be less than len).

If self is non-blocking, and no data is available, the return value will be Soup.SocketIOStatus.WOULD_BLOCK. In this case, the caller can connect to the Soup.Socket ::readable signal to know when there is more data to read. (NB: You MUST read all available data off the socket first. Soup.Socket ::readable is only emitted after Soup.Socket.read() returns Soup.SocketIOStatus.WOULD_BLOCK, and it is only emitted once. See the documentation for Soup.Socket :non-blocking.)

read_until(buffer, boundary, boundary_len, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

as for Soup.Socket.read()

nread:

on return, the number of bytes read into buffer

got_boundary:

on return, whether or not the data in buffer ends with the boundary string

Return type:

(Soup.SocketIOStatus, nread: int, got_boundary: bool)

Like Soup.Socket.read(), but reads no further than the first occurrence of boundary. (If the boundary is found, it will be included in the returned data, and got_boundary will be set to True.) Any data after the boundary will returned in future reads.

Soup.Socket.read_until() will almost always return fewer than len bytes: if the boundary is found, then it will only return the bytes up until the end of the boundary, and if the boundary is not found, then it will leave the last (boundary_len - 1) bytes in its internal buffer, in case they form the start of the boundary string. Thus, len normally needs to be at least 1 byte longer than boundary_len if you want to make any progress at all.

start_proxy_ssl(ssl_host, cancellable)
Parameters:
Returns:

success or failure

Return type:

bool

Starts using SSL on socket, expecting to find a host named ssl_host.

start_ssl(cancellable)
Parameters:

cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Returns:

success or failure

Return type:

bool

Starts using SSL on socket.

write(buffer, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a Soup.SocketIOStatus, as described above (or Soup.SocketIOStatus.EOF or Soup.SocketIOStatus.ERROR. error will be set if the return value is Soup.SocketIOStatus.ERROR.)

nwrote:

on return, number of bytes written

Return type:

(Soup.SocketIOStatus, nwrote: int)

Attempts to write len bytes from buffer to self. If some data is successfully written, the return status will be Soup.SocketIOStatus.OK, and nwrote will contain the number of bytes actually written (which may be less than len).

If self is non-blocking, and no data could be written right away, the return value will be Soup.SocketIOStatus.WOULD_BLOCK. In this case, the caller can connect to the Soup.Socket ::writable signal to know when more data can be written. (NB: Soup.Socket ::writable is only emitted after Soup.Socket.write() returns Soup.SocketIOStatus.WOULD_BLOCK, and it is only emitted once. See the documentation for Soup.Socket :non-blocking.)

do_disconnected() virtual
do_new_connection(new_sock) virtual
Parameters:

new_sock (Soup.Socket) –

do_readable() virtual
do_writable() virtual

Signal Details

Soup.Socket.signals.disconnected(socket)
Signal Name:

disconnected

Flags:

RUN_LAST

Parameters:

socket (Soup.Socket) – The object which received the signal

Emitted when the socket is disconnected, for whatever reason.

Soup.Socket.signals.event(socket, event, connection)
Signal Name:

event

Flags:

RUN_LAST

Parameters:

Emitted when a network-related event occurs. See Gio.SocketClient ::event for more details.

New in version 2.38.

Soup.Socket.signals.new_connection(socket, new)
Signal Name:

new-connection

Flags:

RUN_FIRST

Parameters:

Emitted when a listening socket (set up with Soup.Socket.listen()) receives a new connection.

You must ref the new if you want to keep it; otherwise it will be destroyed after the signal is emitted.

Soup.Socket.signals.readable(socket)
Signal Name:

readable

Flags:

RUN_LAST

Parameters:

socket (Soup.Socket) – The object which received the signal

Emitted when an async socket is readable. See Soup.Socket.read(), Soup.Socket.read_until() and Soup.Socket :non-blocking.

Soup.Socket.signals.writable(socket)
Signal Name:

writable

Flags:

RUN_LAST

Parameters:

socket (Soup.Socket) – The object which received the signal

Emitted when an async socket is writable. See Soup.Socket.write() and Soup.Socket :non-blocking.

Property Details

Soup.Socket.props.async_context
Name:

async-context

Type:

int

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The GLib.MainContext to dispatch this socket’s async I/O in

Soup.Socket.props.fd
Name:

fd

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The socket’s file descriptor

Soup.Socket.props.gsocket
Name:

gsocket

Type:

Gio.Socket

Default Value:

None

Flags:

WRITABLE, CONSTRUCT_ONLY

The socket’s underlying Gio.Socket

Soup.Socket.props.iostream
Name:

iostream

Type:

Gio.IOStream

Default Value:

None

Flags:

WRITABLE, CONSTRUCT_ONLY

The socket’s underlying Gio.IOStream

Soup.Socket.props.ipv6_only
Name:

ipv6-only

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE

IPv6 only

Soup.Socket.props.is_server
Name:

is-server

Type:

bool

Default Value:

False

Flags:

READABLE

Whether or not the socket is a server socket.

Note that for “ordinary” Soup.Sockets this will be set for both listening sockets and the sockets emitted by Soup.Socket ::new-connection, but for sockets created by setting Soup.Socket :fd, it will only be set for listening sockets.

Soup.Socket.props.local_address
Name:

local-address

Type:

Soup.Address

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Address of local end of socket

Soup.Socket.props.non_blocking
Name:

non-blocking

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether or not the socket uses non-blocking I/O.

Soup.Socket's I/O methods are designed around the idea of using a single codepath for both synchronous and asynchronous I/O. If you want to read off a Soup.Socket, the “correct” way to do it is to call Soup.Socket.read() or Soup.Socket.read_until() repeatedly until you have read everything you want. If it returns Soup.SocketIOStatus.WOULD_BLOCK at any point, stop reading and wait for it to emit the Soup.Socket ::readable signal. Then go back to the reading-as-much-as-you-can loop. Likewise, for writing to a Soup.Socket, you should call Soup.Socket.write() either until you have written everything, or it returns Soup.SocketIOStatus.WOULD_BLOCK (in which case you wait for Soup.Socket ::writable and then go back into the loop).

Code written this way will work correctly with both blocking and non-blocking sockets; blocking sockets will simply never return Soup.SocketIOStatus.WOULD_BLOCK, and so the code that handles that case just won’t get used for them.

Soup.Socket.props.remote_address
Name:

remote-address

Type:

Soup.Address

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Address of remote end of socket

Soup.Socket.props.ssl_creds
Name:

ssl-creds

Type:

int

Default Value:

None

Flags:

READABLE, WRITABLE

SSL credential information, passed from the session to the SSL implementation

Soup.Socket.props.ssl_fallback
Name:

ssl-fallback

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Use SSLv3 instead of TLS (client-side only)

Soup.Socket.props.ssl_strict
Name:

ssl-strict

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Whether certificate errors should be considered a connection error

Soup.Socket.props.timeout
Name:

timeout

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE

Value in seconds to timeout a blocking I/O

Soup.Socket.props.tls_certificate
Name:

tls-certificate

Type:

Gio.TlsCertificate

Default Value:

None

Flags:

READABLE

The peer’s TLS certificate

Soup.Socket.props.tls_errors
Name:

tls-errors

Type:

Gio.TlsCertificateFlags

Default Value:

Gio.TlsCertificateFlags.NO_FLAGS

Flags:

READABLE

Errors with the peer’s TLS certificate

Soup.Socket.props.trusted_certificate
Name:

trusted-certificate

Type:

bool

Default Value:

False

Flags:

READABLE

Whether the server certificate is trusted, if this is an SSL socket

Soup.Socket.props.use_thread_context
Name:

use-thread-context

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

Use GLib.MainContext.get_thread_default().

New in version 2.38.