Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Login

GLib::SocketClient

class GLib::SocketClient

GLib::SocketClient is a high-level utility class for connecting to a network host using a connection oriented socket type.

You create a GLib::SocketClient object, set any options you want, then call a sync or async connect operation, which returns a GLib::SocketConnection subclass on success.

The type of the GLib::SocketConnection object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a GLib::TcpConnection.

Class Methods

GLib::SocketClient.new
Creates a new GLib::SocketClient with the default options.

Instance Methods

connect(connectable, cancellable = nil)

Tries to resolve the connectable and make a network connection to it.

Upon a successful connection, a new GLib::SocketConnection is constructed and returned.

The type of the GLib::SocketConnection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a GLib::TcpConnection.

The socket created will be the same family as the the address that the connectable resolves to, unless family is set with GLib::SocketClient#family= or indirectly via GLib::SocketClient#local_address=. The socket type defaults to GLib::Socket::TYPE_STREAM, but can be set with GLib::SocketClient#socket_type=.

If a local address is specified with GLib::SocketClient#local_address= the socket will be bound to this address before connecting.

Since 2.22

connect_async(connectable, cancellable = nil){ |result| }

This is the asynchronous version of GLib::SocketClient#connect.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::SocketClient#connect_finish to get the result of the operation.

Since 2.22

connect_finish(result)

Finishes an async connect operation. See GLib::SocketClient#connect_async

A GLib::IO::Error is raised if connection failed.

Since 2.22

connect_to_host(host_and_port, default_port, cancellable = nil)

This is a helper function for GLib::SocketClient#connect.

Attempts to create a TCP connection to the named host.

host_and_port may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).

If no port override is given in host_and_port then default_port will be used as the port number to connect to.

In general, host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port overide if necessary) and default_port is expected to be provided by the application.

In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.

Upon a successful connection, a new GLib::SocketConnection is constructed and returned.

In the event of any failure (DNS error, service not found, no hosts connectable) a GLib::IO::Error is raised.

Since 2.22

connect_to_host_async(host_and_port, default_port, cancellable = nil){ |result| }

This is the asynchronous version of GLib::SocketClient#connect_to_host.

When the operation is finished, a GLib::AsyncResult will be yielded. You can then call GLib::SocketClient#connect_to_host_finish to get the result of the operation.

Since 2.22

  • host_and_port: The name and optionally the port of the host to connect to
  • default_port: The default port to connect to
  • cancellable: A GLib::Cancellable, or nil
  • result: A GLib::AsyncResult
  • Returns: self
connect_to_host_finish(result)

Finishes an async connect operation. See GLib::SocketClient#connect_to_host_async

A GLib::IO::Error is raised if connection failed.

Since 2.22

connect_to_service(domain, service, cancellable = nil)

Attempts to create a TCP connection to a service.

This call looks up the SRV record for service at domain for the “tcp” protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining.

Upon a successful connection, a new GLib::SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) a GLib::IO::Error is raised.

connect_to_service_async(domain, service, cancellable = nil){ |result| }

This is the asynchronous version of GLib::SocketClient#connect_to_service.

Since 2.22

connect_to_service_finish(result)

Finishes an async connect operation, see GLib::SocketClient#connect_to_service_async.

A GLib::IO::Error is raised if connection failed.

Since 2.22

enable_proxy=(enable_proxy)
Same as GLib::SocketClient#set_enable_proxy.
  • Returns: enable_proxy
enable_proxy?
Checks whether proxy support is enabled.
  • Returns: true if proxy support is enabled
family
Gets the sockets address family to use for socket construction.
  • Returns: The sockets address family to use for socket construction
family=(family)
Sets the sockets address family to use for socket construction.
  • family: The sockets address family to use for socket construction
  • Returns: family
local_address
Gets the local address constructed sockets will be bound to.
  • Returns: The local address constructed sockets will be bound to
local_address=(local_address)
Sets the local address constructed sockets will be bound to.
  • local_address: The local address constructed sockets will be bound to
  • Returns: local_address
protocol
Gets the protocol to use for socket construction, or 0 for default.
  • Returns: The protocol to use for socket construction, or 0 for default
protocol=(protocol)
Sets the protocol to use for socket construction, or 0 for default.
  • protocol: The protocol to use for socket construction, or 0 for default
  • Returns: protocol
set_enable_proxy(enable_proxy)
Enable or disable proxy support.
  • enable_proxy: true to enable proxy support
  • Returns: self
set_family(family)
Same as GLib::SocketClient#family=.
  • Returns: self
set_local_address(local_address)
Same as GLib::SocketClient#local_address=.
  • Returns: self
set_protocol(protocol)
Same as GLib::SocketClient#protocol=.
  • Returns: self
set_socket_type(type)

Sets the socket type of the socket client. The sockets created by this object will be of the specified type.

It doesn’t make sense to specify a type of GLib::Socket::TYPE_DATAGRAM, as GLib::SocketClient is used for connection oriented services.

Since 2.22

set_timeout(timeout)
Same as GLib::SocketClient#timeout=.
  • Returns: self
set_type(type)
Same as GLib::SocketClient#type=.
  • Returns: self
socket_type

Gets the socket type of the socket client. See GLib::SocketClient#socket_type= for details.

Since 2.22

socket_type=(type)
Same as GLib::SocketClient#set_socket_type.
  • Returns: type
timeout
Gets the I/O timeout for sockets, or 0 for none.
  • Returns: The I/O timeout for sockets, or 0 for none
timeout=(timeout)
Sets the I/O timeout for sockets, or 0 for none.
  • timeout: The I/O timeout for sockets, or 0 for none
  • Returns: timeout
type
Gets the sockets type to use for socket construction.
  • Returns: The sockets type to use for socket construction
type=(type)
Sets the sockets type to use for socket construction.
  • type: The sockets type to use for socket construction
  • Returns: Type

Properties

enable-proxy: true or false (Read/Write)

Enable proxy support

Default value: true

family: GLib::SocketFamily (Read/Write)

The sockets address family to use for socket construction

Default value: GLib::Socket::FAMILY_INVALID

local-address: GLib::SocketAddress (Read/Write)
The local address constructed sockets will be bound to
protocol: GLib::SocketProtocol (Read/Write)

The protocol to use for socket construction, or 0 for default

Default value: Glib::Socket::PROTOCOL_DEFAULT

timeout: Integer (Read/Write)

The I/O timeout for sockets, or 0 for none

Default value: 0

type: GSocketType (Read/Write)

The sockets type to use for socket construction

Default value: Glib::Socket::TYPE_STREAM

Last modified:2010/12/27 21:59:23
Keyword(s):
References:[index-ruby-glib2] [Ruby/GIO] [GLib::SocketConnection] [GLib::SocketClient] [index-ruby-gio2]