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, got_boundary, 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:	cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`, or `None` callback (`Soup.SocketCallback`) – callback to call after connecting user_data (`object` or `None`) – data to pass to callback

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:

buffer (bytes) – buffer to read into
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

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, got_boundary, cancellable)¶

Parameters:

buffer (bytes) – buffer to read into
boundary (object or None) – boundary to read until
boundary_len (int) – length of boundary in bytes
got_boundary (bool) – on return, whether or not the data in buffer ends with the boundary string
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

as for Soup.Socket.read()

nread:	on return, the number of bytes read into buffer

Return type:

(Soup.SocketIOStatus, nread: int)

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:	ssl_host (`str`) – hostname of the SSL server cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
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:

buffer (bytes) – data to write
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

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:	socket (`Soup.Socket`) – The object which received the signal event (`Gio.SocketClientEvent`) – the event that occurred connection (`Gio.IOStream`) – the current connection state

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:	socket (`Soup.Socket`) – The object which received the signal new (`Soup.Socket`) – the new socket

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:	`0`
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.