Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Back  Login

GLib::SocketClient Diff - Ruby-GNOME2 Project Website

  • Added parts are displayed like this.
  • Deleted parts are displayed like this.

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

== Object Hierarchy

* Object
  * GLib::Instantiatable
    * GLib::Object
      * GLib::SocketClient

== Class Methods

--- GLib::SocketClient.new

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

     * Returns: a new GLib::SocketClient

== 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

     * connectable: A GLib::SocketConnectable specifying the remote address
     * cancellable: Optional GLib::Cancellable object, nil to ignore
     * Returns: A GLib::SocketConnection on success, nil on error

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

     * connectable: A GLib::SocketConnectable specifying the remote address
     * cancellable: A GLib::Cancellable, or nil
     * result: A GLib::AsyncResult
     * Returns: self

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

     * result: A GLib::AsyncResult
     * Returns: A GLib::SocketConnection

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

     * host_and_port: The name and optionally port of the host to connect to
     * default_port: The default port to connect to
     * cancellable: A GLib::Cancellable, or nil
     * Returns: A GLib::SocketConnection

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

     * result: A GLib::AsyncResult
     * Returns: A GLib::SocketConnection on success

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

     * domain: A domain name
     * service: The name of the service to connect to
     * cancellable: A GLib::Cancellable, or nil
     * Returns: A GLib::SocketConnection

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

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

     Since 2.22

     * domain: A domain name
     * service: The name of the service to connect to
     * cancellable: A GLib::Cancellable, or nil
     * result: A GLib::AsyncResult
     * Returns: self

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

     * result: A GLib::AsyncResult
     * Returns: A GLib::SocketConnection

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

     * type: A GLib::SocketAddress::Type
     * Returns: self

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

     * Returns: A GLib::SocketAddress::Family

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

== See Also

== ChangeLog