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:

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

Parameters:

buffer (bytes) – buffer to read into
boundary (object or None) – boundary to read until
boundary_len (int) – length of boundary in bytes
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
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:

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