gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.SocketClient

Contents

- Exported types
- Methods
  - addApplicationProxy
  - connect
  - connectAsync
  - connectFinish
  - connectToHost
  - connectToHostAsync
  - connectToHostFinish
  - connectToService
  - connectToServiceAsync
  - connectToServiceFinish
  - connectToUri
  - connectToUriAsync
  - connectToUriFinish
  - getEnableProxy
  - getFamily
  - getLocalAddress
  - getProtocol
  - getProxyResolver
  - getSocketType
  - getTimeout
  - getTls
  - getTlsValidationFlags
  - new
  - setEnableProxy
  - setFamily
  - setLocalAddress
  - setProtocol
  - setProxyResolver
  - setSocketType
  - setTimeout
  - setTls
  - setTlsValidationFlags
- Properties
  - enableProxy
  - family
  - localAddress
  - protocol
  - proxyResolver
  - timeout
  - tls
  - tlsValidationFlags
  - type
- Signals
  - event

Description

`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

Synopsis

- newtype SocketClient = SocketClient (ManagedPtr SocketClient)
- class GObject o => IsSocketClient o
- toSocketClient :: (MonadIO m, IsSocketClient o) => o -> m SocketClient
- noSocketClient :: Maybe SocketClient
- socketClientAddApplicationProxy :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> Text -> m ()
- socketClientConnect :: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketConnectable b, IsCancellable c) => a -> b -> Maybe c -> m SocketConnection
- socketClientConnectAsync :: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketConnectable b, IsCancellable c) => a -> b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- socketClientConnectFinish :: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b) => a -> b -> m SocketConnection
- socketClientConnectToHost :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Word16 -> Maybe b -> m SocketConnection
- socketClientConnectToHostAsync :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Word16 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- socketClientConnectToHostFinish :: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b) => a -> b -> m SocketConnection
- socketClientConnectToService :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Text -> Maybe b -> m SocketConnection
- socketClientConnectToServiceAsync :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Text -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- socketClientConnectToServiceFinish :: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b) => a -> b -> m SocketConnection
- socketClientConnectToUri :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Word16 -> Maybe b -> m SocketConnection
- socketClientConnectToUriAsync :: (HasCallStack, MonadIO m, IsSocketClient a, IsCancellable b) => a -> Text -> Word16 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- socketClientConnectToUriFinish :: (HasCallStack, MonadIO m, IsSocketClient a, IsAsyncResult b) => a -> b -> m SocketConnection
- socketClientGetEnableProxy :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m Bool
- socketClientGetFamily :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m SocketFamily
- socketClientGetLocalAddress :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m SocketAddress
- socketClientGetProtocol :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m SocketProtocol
- socketClientGetProxyResolver :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m ProxyResolver
- socketClientGetSocketType :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m SocketType
- socketClientGetTimeout :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m Word32
- socketClientGetTls :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m Bool
- socketClientGetTlsValidationFlags :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> m [TlsCertificateFlags]
- socketClientNew :: (HasCallStack, MonadIO m) => m SocketClient
- socketClientSetEnableProxy :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> Bool -> m ()
- socketClientSetFamily :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> SocketFamily -> m ()
- socketClientSetLocalAddress :: (HasCallStack, MonadIO m, IsSocketClient a, IsSocketAddress b) => a -> Maybe b -> m ()
- socketClientSetProtocol :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> SocketProtocol -> m ()
- socketClientSetProxyResolver :: (HasCallStack, MonadIO m, IsSocketClient a, IsProxyResolver b) => a -> Maybe b -> m ()
- socketClientSetSocketType :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> SocketType -> m ()
- socketClientSetTimeout :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> Word32 -> m ()
- socketClientSetTls :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> Bool -> m ()
- socketClientSetTlsValidationFlags :: (HasCallStack, MonadIO m, IsSocketClient a) => a -> [TlsCertificateFlags] -> m ()
- constructSocketClientEnableProxy :: IsSocketClient o => Bool -> IO (GValueConstruct o)
- getSocketClientEnableProxy :: (MonadIO m, IsSocketClient o) => o -> m Bool
- setSocketClientEnableProxy :: (MonadIO m, IsSocketClient o) => o -> Bool -> m ()
- constructSocketClientFamily :: IsSocketClient o => SocketFamily -> IO (GValueConstruct o)
- getSocketClientFamily :: (MonadIO m, IsSocketClient o) => o -> m SocketFamily
- setSocketClientFamily :: (MonadIO m, IsSocketClient o) => o -> SocketFamily -> m ()
- clearSocketClientLocalAddress :: (MonadIO m, IsSocketClient o) => o -> m ()
- constructSocketClientLocalAddress :: (IsSocketClient o, IsSocketAddress a) => a -> IO (GValueConstruct o)
- getSocketClientLocalAddress :: (MonadIO m, IsSocketClient o) => o -> m SocketAddress
- setSocketClientLocalAddress :: (MonadIO m, IsSocketClient o, IsSocketAddress a) => o -> a -> m ()
- constructSocketClientProtocol :: IsSocketClient o => SocketProtocol -> IO (GValueConstruct o)
- getSocketClientProtocol :: (MonadIO m, IsSocketClient o) => o -> m SocketProtocol
- setSocketClientProtocol :: (MonadIO m, IsSocketClient o) => o -> SocketProtocol -> m ()
- clearSocketClientProxyResolver :: (MonadIO m, IsSocketClient o) => o -> m ()
- constructSocketClientProxyResolver :: (IsSocketClient o, IsProxyResolver a) => a -> IO (GValueConstruct o)
- getSocketClientProxyResolver :: (MonadIO m, IsSocketClient o) => o -> m ProxyResolver
- setSocketClientProxyResolver :: (MonadIO m, IsSocketClient o, IsProxyResolver a) => o -> a -> m ()
- constructSocketClientTimeout :: IsSocketClient o => Word32 -> IO (GValueConstruct o)
- getSocketClientTimeout :: (MonadIO m, IsSocketClient o) => o -> m Word32
- setSocketClientTimeout :: (MonadIO m, IsSocketClient o) => o -> Word32 -> m ()
- constructSocketClientTls :: IsSocketClient o => Bool -> IO (GValueConstruct o)
- getSocketClientTls :: (MonadIO m, IsSocketClient o) => o -> m Bool
- setSocketClientTls :: (MonadIO m, IsSocketClient o) => o -> Bool -> m ()
- constructSocketClientTlsValidationFlags :: IsSocketClient o => [TlsCertificateFlags] -> IO (GValueConstruct o)
- getSocketClientTlsValidationFlags :: (MonadIO m, IsSocketClient o) => o -> m [TlsCertificateFlags]
- setSocketClientTlsValidationFlags :: (MonadIO m, IsSocketClient o) => o -> [TlsCertificateFlags] -> m ()
- constructSocketClientType :: IsSocketClient o => SocketType -> IO (GValueConstruct o)
- getSocketClientType :: (MonadIO m, IsSocketClient o) => o -> m SocketType
- setSocketClientType :: (MonadIO m, IsSocketClient o) => o -> SocketType -> m ()
- type C_SocketClientEventCallback = Ptr () -> CUInt -> Ptr SocketConnectable -> Ptr IOStream -> Ptr () -> IO ()
- type SocketClientEventCallback = SocketClientEvent -> SocketConnectable -> Maybe IOStream -> IO ()
- afterSocketClientEvent :: (IsSocketClient a, MonadIO m) => a -> SocketClientEventCallback -> m SignalHandlerId
- genClosure_SocketClientEvent :: SocketClientEventCallback -> IO Closure
- mk_SocketClientEventCallback :: C_SocketClientEventCallback -> IO (FunPtr C_SocketClientEventCallback)
- noSocketClientEventCallback :: Maybe SocketClientEventCallback
- onSocketClientEvent :: (IsSocketClient a, MonadIO m) => a -> SocketClientEventCallback -> m SignalHandlerId
- wrap_SocketClientEventCallback :: SocketClientEventCallback -> C_SocketClientEventCallback

# Exported types

newtype SocketClient Source #

Memory-managed wrapper type.

Constructors

SocketClient (ManagedPtr SocketClient) |

Instances

GObject SocketClient Source # |
Instance details Defined in GI.Gio.Objects.SocketClient Methods gobjectType :: SocketClient -> IO GType Source #
IsObject SocketClient Source # |
Instance details Defined in GI.Gio.Objects.SocketClient
IsSocketClient SocketClient Source # |
Instance details Defined in GI.Gio.Objects.SocketClient

class GObject o => IsSocketClient o Source #

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

Instances

(GObject a, (UnknownAncestorError SocketClient a :: Constraint)) => IsSocketClient a Source # |
Instance details Defined in GI.Gio.Objects.SocketClient
IsSocketClient SocketClient Source # |
Instance details Defined in GI.Gio.Objects.SocketClient

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

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

noSocketClient :: Maybe SocketClient Source #

A convenience alias for `Nothing` :: `Maybe` `SocketClient`.

# Methods

## addApplicationProxy

socketClientAddApplicationProxy Source #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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) Source #

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

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 () Source #

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) Source #

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

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 () Source #

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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

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 () Source #

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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] Source #

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 () Source #

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) Source #

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

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 () Source #

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 () Source #

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

type SocketClientEventCallback Source #

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

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 :: SocketClientEventCallback -> IO Closure Source #

Wrap the callback into a `Closure`.

mk_SocketClientEventCallback :: C_SocketClientEventCallback -> IO (FunPtr C_SocketClientEventCallback) Source #

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

noSocketClientEventCallback :: Maybe SocketClientEventCallback Source #

A convenience synonym for ``Nothing` :: `Maybe` `SocketClientEventCallback``.

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

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

Wrap a `SocketClientEventCallback` into a `C_SocketClientEventCallback`.