GI.Gio.Objects.SocketClient

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

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

The type of the 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 TcpConnection.

As SocketClient is a lightweight object, you don't need to cache it. You can just create a new one any time you need one.

Since: 2.22

Exported types

newtype SocketClient

Memory-managed wrapper type.

Constructors

SocketClient (ManagedPtr SocketClient)

Instances

GObject SocketClient

Defined in GI.Gio.Objects.SocketClient

Methods

gobjectType :: IO GType

HasParentTypes SocketClient

Defined in GI.Gio.Objects.SocketClient

type ParentTypes SocketClient

Defined in GI.Gio.Objects.SocketClient

type ParentTypes SocketClient = Object ': ([] :: [Type])

class (GObject o, IsDescendantOf SocketClient o) => IsSocketClient o

Type class for types which can be safely cast to SocketClient, for instance with toSocketClient.

Instances

(GObject o, IsDescendantOf SocketClient o) => IsSocketClient o

Defined in GI.Gio.Objects.SocketClient

toSocketClient :: (MonadIO m, IsSocketClient o) => o -> m SocketClient

Cast to SocketClient, for types for which this is known to be safe. For general casts, use castTo.

noSocketClient :: Maybe SocketClient

A convenience alias for Nothing :: Maybe SocketClient.

Methods

addApplicationProxy

socketClientAddApplicationProxy

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient

-> Text

protocol: The proxy protocol

-> m ()

Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the ProxyResolver, SocketClient will consider this protocol as supported but will not try to find a Proxy instance to handle handshaking. The application must check for this case by calling socketConnectionGetRemoteAddress on the returned SocketConnection, and seeing if it's a ProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself.

This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method.

When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake.

connect

socketClientConnect

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketConnectable b, IsCancellable c)

=> a

client: a SocketClient.

-> b

connectable: a SocketConnectable specifying the remote address.

-> Maybe c

cancellable: optional Cancellable object, Nothing to ignore.

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

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

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

The type of the 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 TcpConnection.

The socket created will be the same family as the address that the connectable resolves to, unless family is set with socketClientSetFamily or indirectly via socketClientSetLocalAddress. The socket type defaults to SocketTypeStream but can be set with socketClientSetSocketType.

If a local address is specified with socketClientSetLocalAddress the socket will be bound to this address before connecting.

Since: 2.22

connectAsync

socketClientConnectAsync

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketConnectable b, IsCancellable c)

=> a

client: a SocketClient

-> b

connectable: a SocketConnectable specifying the remote address.

-> Maybe c

cancellable: a Cancellable, or Nothing

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback

-> m ()

This is the asynchronous version of socketClientConnect.

When the operation is finished callback will be called. You can then call socketClientConnectFinish to get the result of the operation.

Since: 2.22

connectFinish

socketClientConnectFinish

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b)

=> a

client: a SocketClient.

-> b

result: a AsyncResult.

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

Finishes an async connect operation. See socketClientConnectAsync

Since: 2.22

connectToHost

socketClientConnectToHost

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketClient

-> Text

hostAndPort: the name and optionally port of the host to connect to

-> Word16

defaultPort: the default port to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

This is a helper function for socketClientConnect.

Attempts to create a TCP connection to the named host.

hostAndPort 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 hostAndPort then defaultPort will be used as the port number to connect to.

In general, hostAndPort is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and defaultPort 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 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) Nothing is returned and error (if non-Nothing) is set accordingly.

Since: 2.22

connectToHostAsync

socketClientConnectToHostAsync

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketClient

-> Text

hostAndPort: the name and optionally the port of the host to connect to

-> Word16

defaultPort: the default port to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback

-> m ()

This is the asynchronous version of socketClientConnectToHost.

When the operation is finished callback will be called. You can then call socketClientConnectToHostFinish to get the result of the operation.

Since: 2.22

connectToHostFinish

socketClientConnectToHostFinish

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b)

=> a

client: a SocketClient.

-> b

result: a AsyncResult.

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

Finishes an async connect operation. See socketClientConnectToHostAsync

Since: 2.22

connectToService

socketClientConnectToService

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketConnection

-> Text

domain: a domain name

-> Text

service: the name of the service to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> m SocketConnection

Returns: a SocketConnection if successful, or Nothing on error (Can throw GError)

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 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) Nothing is returned and error (if non-Nothing) is set accordingly.

connectToServiceAsync

socketClientConnectToServiceAsync

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketClient

-> Text

domain: a domain name

-> Text

service: the name of the service to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback

-> m ()

This is the asynchronous version of socketClientConnectToService.

Since: 2.22

connectToServiceFinish

socketClientConnectToServiceFinish

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b)

=> a

client: a SocketClient.

-> b

result: a AsyncResult.

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

Finishes an async connect operation. See socketClientConnectToServiceAsync

Since: 2.22

connectToUri

socketClientConnectToUri

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketClient

-> Text

uri: A network URI

-> Word16

defaultPort: the default port to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

This is a helper function for socketClientConnect.

Attempts to create a TCP connection with a network URI.

uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, defaultPort will be used. TLS will be negotiated if SocketClient:tls is True. (SocketClient does not know to automatically assume TLS for certain URI schemes.)

Using this rather than socketClientConnect or socketClientConnectToHost allows SocketClient to determine when to use application-specific proxy protocols.

Upon a successful connection, a new 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) Nothing is returned and error (if non-Nothing) is set accordingly.

Since: 2.26

connectToUriAsync

socketClientConnectToUriAsync

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b)

=> a

client: a SocketClient

-> Text

uri: a network uri

-> Word16

defaultPort: the default port to connect to

-> Maybe b

cancellable: a Cancellable, or Nothing

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback

-> m ()

This is the asynchronous version of socketClientConnectToUri.

When the operation is finished callback will be called. You can then call socketClientConnectToUriFinish to get the result of the operation.

Since: 2.26

connectToUriFinish

socketClientConnectToUriFinish

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b)

=> a

client: a SocketClient.

-> b

result: a AsyncResult.

-> m SocketConnection

Returns: a SocketConnection on success, Nothing on error. (Can throw GError)

Finishes an async connect operation. See socketClientConnectToUriAsync

Since: 2.26

getEnableProxy

socketClientGetEnableProxy

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m Bool

Returns: whether proxying is enabled

Gets the proxy enable state; see socketClientSetEnableProxy

Since: 2.26

getFamily

socketClientGetFamily

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m SocketFamily

Returns: a SocketFamily

Gets the socket family of the socket client.

See socketClientSetFamily for details.

Since: 2.22

getLocalAddress

socketClientGetLocalAddress

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m SocketAddress

Returns: a SocketAddress or Nothing. Do not free.

Gets the local address of the socket client.

See socketClientSetLocalAddress for details.

Since: 2.22

getProtocol

socketClientGetProtocol

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient

-> m SocketProtocol

Returns: a SocketProtocol

Gets the protocol name type of the socket client.

See socketClientSetProtocol for details.

Since: 2.22

getProxyResolver

socketClientGetProxyResolver

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m ProxyResolver

Returns: The ProxyResolver being used by client.

Gets the ProxyResolver being used by client. Normally, this will be the resolver returned by proxyResolverGetDefault, but you can override it with socketClientSetProxyResolver.

Since: 2.36

getSocketType

socketClientGetSocketType

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m SocketType

Returns: a SocketFamily

Gets the socket type of the socket client.

See socketClientSetSocketType for details.

Since: 2.22

getTimeout

socketClientGetTimeout

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient

-> m Word32

Returns: the timeout in seconds

Gets the I/O timeout time for sockets created by client.

See socketClientSetTimeout for details.

Since: 2.26

getTls

socketClientGetTls

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m Bool

Returns: whether client uses TLS

Gets whether client creates TLS connections. See socketClientSetTls for details.

Since: 2.28

getTlsValidationFlags

socketClientGetTlsValidationFlags

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> m [TlsCertificateFlags]

Returns: the TLS validation flags

Gets the TLS validation flags used creating TLS connections via client.

Since: 2.28

new

socketClientNew

Arguments

:: (HasCallStack, MonadIO m)

=> m SocketClient

Returns: a SocketClient. Free the returned object with objectUnref.

Creates a new SocketClient with the default options.

Since: 2.22

setEnableProxy

socketClientSetEnableProxy

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> Bool

enable: whether to enable proxies

-> m ()

Sets whether or not client attempts to make connections via a proxy server. When enabled (the default), SocketClient will use a ProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation.

See also socketClientSetProxyResolver.

Since: 2.26

setFamily

socketClientSetFamily

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> SocketFamily

family: a SocketFamily

-> m ()

Sets the socket family of the socket client. If this is set to something other than SocketFamilyInvalid then the sockets created by this object will be of the specified family.

This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address.

Since: 2.22

setLocalAddress

socketClientSetLocalAddress

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketAddress b)

=> a

client: a SocketClient.

-> Maybe b

address: a SocketAddress, or Nothing

-> m ()

Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not Nothing) before connecting.

This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface.

Since: 2.22

setProtocol

socketClientSetProtocol

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> SocketProtocol

protocol: a SocketProtocol

-> m ()

Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol.

If protocol is 0 that means to use the default protocol for the socket family and type.

Since: 2.22

setProxyResolver

socketClientSetProxyResolver

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a, IsProxyResolver b)

=> a

client: a SocketClient.

-> Maybe b

proxyResolver: a ProxyResolver, or Nothing for the default.

-> m ()

Overrides the ProxyResolver used by client. You can call this if you want to use specific proxies, rather than using the system default proxy settings.

Note that whether or not the proxy resolver is actually used depends on the setting of SocketClient:enable-proxy, which is not changed by this function (but which is True by default)

Since: 2.36

setSocketType

socketClientSetSocketType

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> SocketType

type: a SocketType

-> m ()

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 SocketTypeDatagram, as GSocketClient is used for connection oriented services.

Since: 2.22

setTimeout

socketClientSetTimeout

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> Word32

timeout: the timeout

-> m ()

Sets the I/O timeout for sockets created by client. timeout is a time in seconds, or 0 for no timeout (the default).

The timeout value affects the initial connection attempt as well, so setting this may cause calls to socketClientConnect, etc, to fail with IOErrorEnumTimedOut.

Since: 2.26

setTls

socketClientSetTls

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> Bool

tls: whether to use TLS

-> m ()

Sets whether client creates TLS (aka SSL) connections. If tls is True, client will wrap its connections in a TlsClientConnection and perform a TLS handshake when connecting.

Note that since SocketClient must return a SocketConnection, but TlsClientConnection is not a SocketConnection, this actually wraps the resulting TlsClientConnection in a TcpWrapperConnection when returning it. You can use tcpWrapperConnectionGetBaseIoStream on the return value to extract the TlsClientConnection.

If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the TlsConnection::accept-certificate signal), you can connect to client's SocketClient::event signal and wait for it to be emitted with SocketClientEventTlsHandshaking, which will give you a chance to see the TlsClientConnection before the handshake starts.

Since: 2.28

setTlsValidationFlags

socketClientSetTlsValidationFlags

Arguments

:: (HasCallStack, MonadIO m, IsSocketClient a)

=> a

client: a SocketClient.

-> [TlsCertificateFlags]

flags: the validation flags

-> m ()

Sets the TLS validation flags used when creating TLS connections via client. The default value is TlsCertificateFlagsValidateAll.

Since: 2.28

Properties

enableProxy

No description available in the introspection data.

constructSocketClientEnableProxy :: IsSocketClient o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “enable-proxy” property. This is rarely needed directly, but it is used by new.

getSocketClientEnableProxy :: (MonadIO m, IsSocketClient o) => o -> m Bool

Get the value of the “enable-proxy” property. When overloading is enabled, this is equivalent to

get socketClient #enableProxy

setSocketClientEnableProxy :: (MonadIO m, IsSocketClient o) => o -> Bool -> m ()

Set the value of the “enable-proxy” property. When overloading is enabled, this is equivalent to

set socketClient [ #enableProxy := value ]

family

No description available in the introspection data.

constructSocketClientFamily :: IsSocketClient o => SocketFamily -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “family” property. This is rarely needed directly, but it is used by new.

getSocketClientFamily :: (MonadIO m, IsSocketClient o) => o -> m SocketFamily

Get the value of the “family” property. When overloading is enabled, this is equivalent to

get socketClient #family

setSocketClientFamily :: (MonadIO m, IsSocketClient o) => o -> SocketFamily -> m ()

Set the value of the “family” property. When overloading is enabled, this is equivalent to

set socketClient [ #family := value ]

localAddress

No description available in the introspection data.

clearSocketClientLocalAddress :: (MonadIO m, IsSocketClient o) => o -> m ()

Set the value of the “local-address” property to Nothing. When overloading is enabled, this is equivalent to

clear #localAddress

constructSocketClientLocalAddress :: (IsSocketClient o, IsSocketAddress a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “local-address” property. This is rarely needed directly, but it is used by new.

getSocketClientLocalAddress :: (MonadIO m, IsSocketClient o) => o -> m SocketAddress

Get the value of the “local-address” property. When overloading is enabled, this is equivalent to

get socketClient #localAddress

setSocketClientLocalAddress :: (MonadIO m, IsSocketClient o, IsSocketAddress a) => o -> a -> m ()

Set the value of the “local-address” property. When overloading is enabled, this is equivalent to

set socketClient [ #localAddress := value ]

protocol

No description available in the introspection data.

constructSocketClientProtocol :: IsSocketClient o => SocketProtocol -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “protocol” property. This is rarely needed directly, but it is used by new.

getSocketClientProtocol :: (MonadIO m, IsSocketClient o) => o -> m SocketProtocol

Get the value of the “protocol” property. When overloading is enabled, this is equivalent to

get socketClient #protocol

setSocketClientProtocol :: (MonadIO m, IsSocketClient o) => o -> SocketProtocol -> m ()

Set the value of the “protocol” property. When overloading is enabled, this is equivalent to

set socketClient [ #protocol := value ]

proxyResolver

The proxy resolver to use

Since: 2.36

clearSocketClientProxyResolver :: (MonadIO m, IsSocketClient o) => o -> m ()

Set the value of the “proxy-resolver” property to Nothing. When overloading is enabled, this is equivalent to

clear #proxyResolver

constructSocketClientProxyResolver :: (IsSocketClient o, IsProxyResolver a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “proxy-resolver” property. This is rarely needed directly, but it is used by new.

getSocketClientProxyResolver :: (MonadIO m, IsSocketClient o) => o -> m ProxyResolver

Get the value of the “proxy-resolver” property. When overloading is enabled, this is equivalent to

get socketClient #proxyResolver

setSocketClientProxyResolver :: (MonadIO m, IsSocketClient o, IsProxyResolver a) => o -> a -> m ()

Set the value of the “proxy-resolver” property. When overloading is enabled, this is equivalent to

set socketClient [ #proxyResolver := value ]

timeout

No description available in the introspection data.

constructSocketClientTimeout :: IsSocketClient o => Word32 -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “timeout” property. This is rarely needed directly, but it is used by new.

getSocketClientTimeout :: (MonadIO m, IsSocketClient o) => o -> m Word32

Get the value of the “timeout” property. When overloading is enabled, this is equivalent to

get socketClient #timeout

setSocketClientTimeout :: (MonadIO m, IsSocketClient o) => o -> Word32 -> m ()

Set the value of the “timeout” property. When overloading is enabled, this is equivalent to

set socketClient [ #timeout := value ]

tls

No description available in the introspection data.

constructSocketClientTls :: IsSocketClient o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “tls” property. This is rarely needed directly, but it is used by new.

getSocketClientTls :: (MonadIO m, IsSocketClient o) => o -> m Bool

Get the value of the “tls” property. When overloading is enabled, this is equivalent to

get socketClient #tls

setSocketClientTls :: (MonadIO m, IsSocketClient o) => o -> Bool -> m ()

Set the value of the “tls” property. When overloading is enabled, this is equivalent to

set socketClient [ #tls := value ]

tlsValidationFlags

No description available in the introspection data.

constructSocketClientTlsValidationFlags :: IsSocketClient o => [TlsCertificateFlags] -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “tls-validation-flags” property. This is rarely needed directly, but it is used by new.

getSocketClientTlsValidationFlags :: (MonadIO m, IsSocketClient o) => o -> m [TlsCertificateFlags]

Get the value of the “tls-validation-flags” property. When overloading is enabled, this is equivalent to

get socketClient #tlsValidationFlags

setSocketClientTlsValidationFlags :: (MonadIO m, IsSocketClient o) => o -> [TlsCertificateFlags] -> m ()

Set the value of the “tls-validation-flags” property. When overloading is enabled, this is equivalent to

set socketClient [ #tlsValidationFlags := value ]

type

No description available in the introspection data.

constructSocketClientType :: IsSocketClient o => SocketType -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “type” property. This is rarely needed directly, but it is used by new.

getSocketClientType :: (MonadIO m, IsSocketClient o) => o -> m SocketType

Get the value of the “type” property. When overloading is enabled, this is equivalent to

get socketClient #type

setSocketClientType :: (MonadIO m, IsSocketClient o) => o -> SocketType -> m ()

Set the value of the “type” property. When overloading is enabled, this is equivalent to

set socketClient [ #type := value ]

Signals

event

type C_SocketClientEventCallback = Ptr () -> CUInt -> Ptr SocketConnectable -> Ptr IOStream -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type SocketClientEventCallback

Arguments

 = SocketClientEvent

event: the event that is occurring

-> SocketConnectable

connectable: the SocketConnectable that event is occurring on

-> Maybe IOStream

connection: the current representation of the connection

-> IO ()

Emitted when client's activity on connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different event values are as follows:

• SocketClientEventResolving: client is about to look up connectable in DNS. connection will be Nothing.
• SocketClientEventResolved: client has successfully resolved connectable in DNS. connection will be Nothing.
• SocketClientEventConnecting: client is about to make a connection to a remote host; either a proxy server or the destination server itself. connection is the SocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via socketConnectionGetRemoteAddress.
• SocketClientEventConnected: client has successfully connected to a remote host. connection is the connected SocketConnection.
• SocketClientEventProxyNegotiating: client is about to negotiate with a proxy to get it to connect to connectable. connection is the SocketConnection to the proxy server.
• SocketClientEventProxyNegotiated: client has negotiated a connection to connectable through a proxy server. connection is the stream returned from proxyConnect, which may or may not be a SocketConnection.
• SocketClientEventTlsHandshaking: client is about to begin a TLS handshake. connection is a TlsClientConnection.
• SocketClientEventTlsHandshaked: client has successfully completed the TLS handshake. connection is a TlsClientConnection.
• SocketClientEventComplete: client has either successfully connected to connectable (in which case connection is the SocketConnection that it will be returning to the caller) or has failed (in which case connection is Nothing and the client is about to return an error).

Each event except SocketClientEventComplete may be emitted multiple times (or not at all) for a given connectable (in particular, if client ends up attempting to connect to more than one address). However, if client emits the SocketClient::event signal at all for a given connectable, that it will always emit it with SocketClientEventComplete when it is done.

Note that there may be additional SocketClientEvent values in the future; unrecognized event values should be ignored.

Since: 2.32

afterSocketClientEvent :: (IsSocketClient a, MonadIO m) => a -> SocketClientEventCallback -> m SignalHandlerId

Connect a signal handler for the “event” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after socketClient #event callback

genClosure_SocketClientEvent :: MonadIO m => SocketClientEventCallback -> m (GClosure C_SocketClientEventCallback)

Wrap the callback into a GClosure.

mk_SocketClientEventCallback :: C_SocketClientEventCallback -> IO (FunPtr C_SocketClientEventCallback)

Generate a function pointer callable from C code, from a C_SocketClientEventCallback.

noSocketClientEventCallback :: Maybe SocketClientEventCallback

A convenience synonym for Nothing :: Maybe SocketClientEventCallback.

onSocketClientEvent :: (IsSocketClient a, MonadIO m) => a -> SocketClientEventCallback -> m SignalHandlerId

Connect a signal handler for the “event” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on socketClient #event callback

wrap_SocketClientEventCallback :: SocketClientEventCallback -> C_SocketClientEventCallback

Wrap a SocketClientEventCallback into a C_SocketClientEventCallback.