Trait gio::prelude::SocketExt[−][src]

pub trait SocketExt: 'static {

Show methods    fn accept<P: IsA<Cancellable>>(
        &self, 
        cancellable: Option<&P>
    ) -> Result<Socket, Error>;

    fn bind<P: IsA<SocketAddress>>(
        &self, 
        address: &P, 
        allow_reuse: bool
    ) -> Result<(), Error>;

    fn check_connect_result(&self) -> Result<(), Error>;

    fn close(&self) -> Result<(), Error>;

    fn condition_check(&self, condition: IOCondition) -> IOCondition;

    fn condition_timed_wait<P: IsA<Cancellable>>(
        &self, 
        condition: IOCondition, 
        timeout_us: i64, 
        cancellable: Option<&P>
    ) -> Result<(), Error>;

    fn condition_wait<P: IsA<Cancellable>>(
        &self, 
        condition: IOCondition, 
        cancellable: Option<&P>
    ) -> Result<(), Error>;

    fn connect<P: IsA<SocketAddress>, Q: IsA<Cancellable>>(
        &self, 
        address: &P, 
        cancellable: Option<&Q>
    ) -> Result<(), Error>;

    fn connection_factory_create_connection(&self) -> SocketConnection;

    fn available_bytes(&self) -> isize;

    fn is_blocking(&self) -> bool;

    fn is_broadcast(&self) -> bool;

    fn credentials(&self) -> Result<Credentials, Error>;

    fn family(&self) -> SocketFamily;

    fn is_keepalive(&self) -> bool;

    fn listen_backlog(&self) -> i32;

    fn local_address(&self) -> Result<SocketAddress, Error>;

    fn is_multicast_loopback(&self) -> bool;

    fn multicast_ttl(&self) -> u32;

    fn option(&self, level: i32, optname: i32) -> Result<i32, Error>;

    fn protocol(&self) -> SocketProtocol;

    fn remote_address(&self) -> Result<SocketAddress, Error>;

    fn socket_type(&self) -> SocketType;

    fn timeout(&self) -> u32;

    fn ttl(&self) -> u32;

    fn is_closed(&self) -> bool;

    fn is_connected(&self) -> bool;

    fn join_multicast_group<P: IsA<InetAddress>>(
        &self, 
        group: &P, 
        source_specific: bool, 
        iface: Option<&str>
    ) -> Result<(), Error>;

    fn join_multicast_group_ssm<P: IsA<InetAddress>, Q: IsA<InetAddress>>(
        &self, 
        group: &P, 
        source_specific: Option<&Q>, 
        iface: Option<&str>
    ) -> Result<(), Error>;

    fn leave_multicast_group<P: IsA<InetAddress>>(
        &self, 
        group: &P, 
        source_specific: bool, 
        iface: Option<&str>
    ) -> Result<(), Error>;

    fn leave_multicast_group_ssm<P: IsA<InetAddress>, Q: IsA<InetAddress>>(
        &self, 
        group: &P, 
        source_specific: Option<&Q>, 
        iface: Option<&str>
    ) -> Result<(), Error>;

    fn listen(&self) -> Result<(), Error>;

    fn set_blocking(&self, blocking: bool);

    fn set_broadcast(&self, broadcast: bool);

    fn set_keepalive(&self, keepalive: bool);

    fn set_listen_backlog(&self, backlog: i32);

    fn set_multicast_loopback(&self, loopback: bool);

    fn set_multicast_ttl(&self, ttl: u32);

    fn set_option(
        &self, 
        level: i32, 
        optname: i32, 
        value: i32
    ) -> Result<(), Error>;

    fn set_timeout(&self, timeout: u32);

    fn set_ttl(&self, ttl: u32);

    fn shutdown(
        &self, 
        shutdown_read: bool, 
        shutdown_write: bool
    ) -> Result<(), Error>;

    fn speaks_ipv4(&self) -> bool;

    fn type_(&self) -> SocketType;

    fn connect_blocking_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_broadcast_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_keepalive_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_listen_backlog_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_local_address_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_multicast_loopback_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_multicast_ttl_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_remote_address_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_timeout_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

    fn connect_ttl_notify<F: Fn(&Self) + Send + 'static>(
        &self, 
        f: F
    ) -> SignalHandlerId;

}
Expand description

Trait containing all Socket methods.

Implementors

Socket

Required methods

Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a Socket object for it.

The self must be bound to a local address with bind() and must be listening for incoming connections (listen()).

If there are no outstanding connections then the operation will block or return IOErrorEnum::WouldBlock if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the glib::IOCondition::IN condition.

cancellable

a GCancellable or None

Returns

a new Socket, or None on error. Free the returned object with g_object_unref().

When a socket is created it is attached to an address family, but it doesn’t have an address in this family. bind() assigns the address (sometimes called name) of the socket.

It is generally required to bind to a local address before you can receive connections. (See listen() and accept() ). In certain situations, you may also want to bind a socket that will be used to initiate connections, though this is not normally required.

If self is a TCP socket, then allow_reuse controls the setting of the SO_REUSEADDR socket option; normally it should be true for server sockets (sockets that you will eventually call accept() on), and false for client sockets. (Failing to set this flag on a server socket may cause bind() to return IOErrorEnum::AddressInUse if the server program is stopped and then immediately restarted.)

If self is a UDP socket, then allow_reuse determines whether or not other UDP sockets can be bound to the same address at the same time. In particular, you can have several UDP sockets bound to the same address, and they will all receive all of the multicast and broadcast packets sent to that address. (The behavior of unicast UDP packets to an address with multiple listeners is not defined.)

address

a SocketAddress specifying the local address.

allow_reuse

whether to allow reusing this address

Returns

true on success, false on error.

Checks and resets the pending connect error for the socket. This is used to check for errors when connect() is used in non-blocking mode.

Returns

true if no error, false otherwise, setting error to the error

Closes the socket, shutting down any active connection.

Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed to complete even if the close returns with no error.

Once the socket is closed, all other operations will return IOErrorEnum::Closed. Closing a socket multiple times will not return an error.

Sockets will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

Beware that due to the way that TCP works, it is possible for recently-sent data to be lost if either you close a socket while the glib::IOCondition::IN condition is set, or else if the remote connection tries to send something to you after you close the socket but before it has finished reading all of the data you sent. There is no easy generic way to avoid this problem; the easiest fix is to design the network protocol such that the client will never send data “out of turn”. Another solution is for the server to half-close the connection by calling shutdown() with only the shutdown_write flag set, and then wait for the client to notice this and close its side of the connection, after which the server can safely call close(). (This is what TcpConnection does if you call TcpConnectionExt::set_graceful_disconnect(). But of course, this only works if the client will close its connection after the server does.)

Returns

true on success, false on error

Checks on the readiness of self to perform operations. The operations specified in condition are checked for and masked against the currently-satisfied conditions on self. The result is returned.

Note that on Windows, it is possible for an operation to return IOErrorEnum::WouldBlock even immediately after condition_check() has claimed that the socket is ready for writing. Rather than calling condition_check() and then writing to the socket if it succeeds, it is generally better to simply try writing to the socket right away, and try again later if the initial attempt returns IOErrorEnum::WouldBlock.

It is meaningless to specify glib::IOCondition::ERR or glib::IOCondition::HUP in condition; these conditions will always be set in the output if they are true.

This call never blocks.

condition

a glib::IOCondition mask to check

Returns

the glib::IOCondition mask of the current state

Waits for up to timeout_us microseconds for condition to become true on self. If the condition is met, true is returned.

If cancellable is cancelled before the condition is met, or if timeout_us (or the socket’s property::Socket::timeout) is reached before the condition is met, then false is returned and error, if non-None, is set to the appropriate value (IOErrorEnum::Cancelled or IOErrorEnum::TimedOut).

If you don’t want a timeout, use condition_wait(). (Alternatively, you can pass -1 for timeout_us.)

Note that although timeout_us is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if timeout_us is not an exact number of milliseconds.

condition

a glib::IOCondition mask to wait for

timeout_us

the maximum time (in microseconds) to wait, or -1

cancellable

a Cancellable, or None

Returns

true if the condition was met, false otherwise

Waits for condition to become true on self. When the condition is met, true is returned.

If cancellable is cancelled before the condition is met, or if the socket has a timeout set and it is reached before the condition is met, then false is returned and error, if non-None, is set to the appropriate value (IOErrorEnum::Cancelled or IOErrorEnum::TimedOut).

See also condition_timed_wait().

condition

a glib::IOCondition mask to wait for

cancellable

a Cancellable, or None

Returns

true if the condition was met, false otherwise

Connect the socket to the specified remote address.

For connection oriented socket this generally means we attempt to make a connection to the address. For a connection-less socket it sets the default address for SocketExtManual::send() and discards all incoming datagrams from other sources.

Generally connection oriented sockets can only connect once, but connection-less sockets can connect multiple times to change the default address.

If the connect call needs to do network I/O it will block, unless non-blocking I/O is enabled. Then IOErrorEnum::Pending is returned and the user can be notified of the connection finishing by waiting for the G_IO_OUT condition. The result of the connection must then be checked with check_connect_result().

address

a SocketAddress specifying the remote address.

cancellable

a GCancellable or None

Returns

true if connected, false on error.

Creates a SocketConnection subclass of the right type for self.

Returns

a SocketConnection

Get the amount of data pending in the OS input buffer, without blocking.

If self is a UDP or SCTP socket, this will return the size of just the next packet, even if additional packets are buffered after that one.

Note that on Windows, this function is rather inefficient in the UDP case, and so if you know any plausible upper bound on the size of the incoming packet, it is better to just do a SocketExtManual::receive() with a buffer of that size, rather than calling available_bytes() first and then doing a receive of exactly the right size.

Returns

the number of bytes that can be read from the socket without blocking or truncating, or -1 on error.

Gets the blocking mode of the socket. For details on blocking I/O, see set_blocking().

Returns

true if blocking I/O is used, false otherwise.

Gets the broadcast setting on self; if true, it is possible to send packets to broadcast addresses.

Returns

the broadcast setting on self

Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for SocketFamily::Unix sockets).

If this operation isn’t supported on the OS, the method fails with the IOErrorEnum::NotSupported error. On Linux this is implemented by reading the SO_PEERCRED option on the underlying socket.

This method can be expected to be available on the following platforms:

  • Linux since GLib 2.26
  • OpenBSD since GLib 2.30
  • Solaris, Illumos and OpenSolaris since GLib 2.40
  • NetBSD since GLib 2.42
  • macOS, tvOS, iOS since GLib 2.66

Other ways to obtain credentials from a foreign peer includes the GUnixCredentialsMessage type and g_unix_connection_send_credentials() / g_unix_connection_receive_credentials() functions.

Returns

None if error is set, otherwise a Credentials object that must be freed with g_object_unref().

Gets the socket family of the socket.

Returns

a SocketFamily

Gets the keepalive mode of the socket. For details on this, see set_keepalive().

Returns

true if keepalive is active, false otherwise.

Gets the listen backlog setting of the socket. For details on this, see set_listen_backlog().

Returns

the maximum number of pending connections.

Try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting.

Returns

a SocketAddress or None on error. Free the returned object with g_object_unref().

Gets the multicast loopback setting on self; if true (the default), outgoing multicast packets will be looped back to multicast listeners on the same host.

Returns

the multicast loopback setting on self

Gets the multicast time-to-live setting on self; see set_multicast_ttl() for more details.

Returns

the multicast time-to-live setting on self

Gets the value of an integer-valued option on self, as with getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers.

Note that even for socket options that are a single byte in size, value is still a pointer to a gint variable, not a guchar; option() will handle the conversion internally.

level

the “API level” of the option (eg, SOL_SOCKET)

optname

the “name” of the option (eg, SO_BROADCAST)

Returns

success or failure. On failure, error will be set, and the system error value (errno or WSAGetLastError()) will still be set to the result of the getsockopt() call.

value

return location for the option value

Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned.

Returns

a protocol id, or -1 if unknown

Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected.

Returns

a SocketAddress or None on error. Free the returned object with g_object_unref().

Gets the socket type of the socket.

Returns

a SocketType

Gets the timeout setting of the socket. For details on this, see set_timeout().

Returns

the timeout in seconds

Gets the unicast time-to-live setting on self; see set_ttl() for more details.

Returns

the time-to-live setting on self

Checks whether a socket is closed.

Returns

true if socket is closed, false otherwise

Check whether the socket is connected. This is only useful for connection-oriented sockets.

If using shutdown(), this function will return true until the socket has been shut down for reading and writing. If you do a non-blocking connect, this function will not return true until after you call check_connect_result().

Returns

true if socket is connected, false otherwise.

Registers self to receive multicast messages sent to group. self must be a SocketType::Datagram socket, and must have been bound to an appropriate interface and port with bind().

If iface is None, the system will automatically pick an interface to bind to based on group.

If source_specific is true, source-specific multicast as defined in RFC 4604 is used. Note that on older platforms this may fail with a IOErrorEnum::NotSupported error.

To bind to a given source-specific multicast address, use join_multicast_group_ssm() instead.

group

a InetAddress specifying the group address to join.

source_specific

true if source-specific multicast should be used

iface

Name of the interface to use, or None

Returns

true on success, false on error.

This is supported on crate feature v2_56 only.

Registers self to receive multicast messages sent to group. self must be a SocketType::Datagram socket, and must have been bound to an appropriate interface and port with bind().

If iface is None, the system will automatically pick an interface to bind to based on group.

If source_specific is not None, use source-specific multicast as defined in RFC 4604. Note that on older platforms this may fail with a IOErrorEnum::NotSupported error.

Note that this function can be called multiple times for the same group with different source_specific in order to receive multicast packets from more than one source.

group

a InetAddress specifying the group address to join.

source_specific

a InetAddress specifying the source-specific multicast address or None to ignore.

iface

Name of the interface to use, or None

Returns

true on success, false on error.

Removes self from the multicast group defined by group, iface, and source_specific (which must all have the same values they had when you joined the group).

self remains bound to its address and port, and can still receive unicast messages after calling this.

To unbind to a given source-specific multicast address, use leave_multicast_group_ssm() instead.

group

a InetAddress specifying the group address to leave.

source_specific

true if source-specific multicast was used

iface

Interface used

Returns

true on success, false on error.

This is supported on crate feature v2_56 only.

Removes self from the multicast group defined by group, iface, and source_specific (which must all have the same values they had when you joined the group).

self remains bound to its address and port, and can still receive unicast messages after calling this.

group

a InetAddress specifying the group address to leave.

source_specific

a InetAddress specifying the source-specific multicast address or None to ignore.

iface

Name of the interface to use, or None

Returns

true on success, false on error.

Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using accept().

Before calling this the socket must be bound to a local address using bind().

To set the maximum amount of outstanding clients, use set_listen_backlog().

Returns

true on success, false on error.

Sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In non-blocking mode all functions return results immediately or with a IOErrorEnum::WouldBlock error.

All sockets are created in blocking mode. However, note that the platform level socket is always non-blocking, and blocking mode is a GSocket level feature.

blocking

Whether to use blocking I/O or not.

Sets whether self should allow sending to broadcast addresses. This is false by default.

broadcast

whether self should allow sending to broadcast addresses

Sets or unsets the SO_KEEPALIVE flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of time passes with no data being exchanged. If the system is unable to verify the presence of the remote endpoint, it will automatically close the connection.

This option is only functional on certain kinds of sockets. (Notably, SocketProtocol::Tcp sockets.)

The exact time between pings is system- and protocol-dependent, but will normally be at least two hours. Most commonly, you would set this flag on a server socket if you want to allow clients to remain idle for long periods of time, but also want to ensure that connections are eventually garbage-collected if clients crash or become unreachable.

keepalive

Value for the keepalive flag

Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused.

Note that this must be called before listen() and has no effect if called after that.

backlog

the maximum number of pending connections.

Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is true by default.

loopback

whether self should receive messages sent to its multicast groups from the local host

Sets the time-to-live for outgoing multicast datagrams on self. By default, this is 1, meaning that multicast packets will not leave the local network.

ttl

the time-to-live value for all multicast datagrams on self

Sets the value of an integer-valued option on self, as with setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers.

level

the “API level” of the option (eg, SOL_SOCKET)

optname

the “name” of the option (eg, SO_BROADCAST)

value

the value to set the option to

Returns

success or failure. On failure, error will be set, and the system error value (errno or WSAGetLastError()) will still be set to the result of the setsockopt() call.

Sets the time in seconds after which I/O operations on self will time out if they have not yet completed.

On a blocking socket, this means that any blocking Socket operation will time out after timeout seconds of inactivity, returning IOErrorEnum::TimedOut.

On a non-blocking socket, calls to condition_wait() will also fail with IOErrorEnum::TimedOut after the given time. Sources created with g_socket_create_source() will trigger after timeout seconds of inactivity, with the requested condition set, at which point calling SocketExtManual::receive(), SocketExtManual::send(), check_connect_result(), etc, will fail with IOErrorEnum::TimedOut.

If timeout is 0 (the default), operations will never time out on their own.

Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset.

timeout

the timeout for self, in seconds, or 0 for none

Sets the time-to-live for outgoing unicast packets on self. By default the platform-specific default value is used.

ttl

the time-to-live value for all unicast packets on self

Shut down part or all of a full-duplex connection.

If shutdown_read is true then the receiving side of the connection is shut down, and further reading is disallowed.

If shutdown_write is true then the sending side of the connection is shut down, and further writing is disallowed.

It is allowed for both shutdown_read and shutdown_write to be true.

One example where it is useful to shut down only one side of a connection is graceful disconnect for TCP connections where you close the sending side, then wait for the other side to close the connection, thus ensuring that the other side saw all sent data.

shutdown_read

whether to shut down the read side

shutdown_write

whether to shut down the write side

Returns

true on success, false on error

Checks if a socket is capable of speaking IPv4.

IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also capable of speaking IPv4. See RFC 3493 section 3.7 for more information.

No other types of sockets are currently considered as being capable of speaking IPv4.

Returns

true if this socket can be used with IPv4.

[src]
fn type_(&self) -> SocketType

Implementors