gi-gio-2.0.38: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.UnixConnection

Contents

- Exported types
- Methods
  - receiveCredentials
  - receiveCredentialsAsync
  - receiveCredentialsFinish
  - receiveFd
  - sendCredentials
  - sendCredentialsAsync
  - sendCredentialsFinish
  - sendFd

Description

This is the subclass of `SocketConnection` that is created for UNIX domain sockets.

It contains functions to do some of the UNIX socket specific functionality like passing file descriptors.

Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time.

Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when using it. This is no longer necessary since GLib 2.72.

Since: 2.22

Synopsis

- newtype UnixConnection = UnixConnection (ManagedPtr UnixConnection)
- class (GObject o, IsDescendantOf UnixConnection o) => IsUnixConnection o
- toUnixConnection :: (MonadIO m, IsUnixConnection o) => o -> m UnixConnection
- unixConnectionReceiveCredentials :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Maybe b -> m Credentials
- unixConnectionReceiveCredentialsAsync :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- unixConnectionReceiveCredentialsFinish :: (HasCallStack, MonadIO m, IsUnixConnection a, IsAsyncResult b) => a -> b -> m Credentials
- unixConnectionReceiveFd :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Maybe b -> m Int32
- unixConnectionSendCredentials :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Maybe b -> m ()
- unixConnectionSendCredentialsAsync :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- unixConnectionSendCredentialsFinish :: (HasCallStack, MonadIO m, IsUnixConnection a, IsAsyncResult b) => a -> b -> m ()
- unixConnectionSendFd :: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) => a -> Int32 -> Maybe b -> m ()

# Exported types

newtype UnixConnection Source #

Memory-managed wrapper type.

Constructors

UnixConnection (ManagedPtr UnixConnection) |

#### Instances

Instances details

Eq UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection Methods (==) :: UnixConnection -> UnixConnection -> Bool Source # (/=) :: UnixConnection -> UnixConnection -> Bool Source #
GObject UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection
ManagedPtrNewtype UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection Methods toManagedPtr :: UnixConnection -> ManagedPtr UnixConnection Source #
TypedObject UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection Methods glibType :: IO GType Source #
HasParentTypes UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection
IsGValue (Maybe UnixConnection) Source # | Convert `UnixConnection` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Objects.UnixConnection Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe UnixConnection -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe UnixConnection) Source #
type ParentTypes UnixConnection Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection type ParentTypes UnixConnection = '[SocketConnection, IOStream, Object]

class (GObject o, IsDescendantOf UnixConnection o) => IsUnixConnection o Source #

Type class for types which can be safely cast to `UnixConnection`, for instance with `toUnixConnection`.

#### Instances

Instances details

(GObject o, IsDescendantOf UnixConnection o) => IsUnixConnection o Source # |
Instance details Defined in GI.Gio.Objects.UnixConnection

toUnixConnection :: (MonadIO m, IsUnixConnection o) => o -> m UnixConnection Source #

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

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, clearPending, close, closeAsync, closeFinish, connect, connectAsync, connectFinish, forceFloating, freezeNotify, getv, hasPending, isClosed, isConnected, isFloating, notify, notifyByPspec, receiveCredentials, receiveCredentialsAsync, receiveCredentialsFinish, receiveFd, ref, refSink, runDispose, sendCredentials, sendCredentialsAsync, sendCredentialsFinish, sendFd, spliceAsync, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getInputStream, getLocalAddress, getOutputStream, getProperty, getQdata, getRemoteAddress, getSocket.

#### Setters

setData, setDataFull, setPending, setProperty.

## receiveCredentials

unixConnectionReceiveCredentials Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: A `UnixConnection`.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> m Credentials | Returns: Received credentials on success (free with `objectUnref`), `Nothing` if `error` is set. (Can throw `GError`)

Receives credentials from the sending end of the connection. The sending end has to call `unixConnectionSendCredentials` (or similar) for this to work.

As well as reading the credentials this also reads (and discards) a single byte from the stream, as this is required for credentials passing to work on some implementations.

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

- Linux since GLib 2.26
- FreeBSD since GLib 2.26
- GNU/kFreeBSD since GLib 2.36
- Solaris, Illumos and OpenSolaris since GLib 2.40
- GNU/Hurd since GLib 2.40

Other ways to exchange credentials with a foreign peer includes the `UnixCredentialsMessage` type and `socketGetCredentials` function.

Since: 2.26

## receiveCredentialsAsync

unixConnectionReceiveCredentialsAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: A `UnixConnection`.
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback` to call when the request is satisfied
-> m () |

Asynchronously receive credentials.

For more details, see `unixConnectionReceiveCredentials` which is the synchronous version of this call.

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

Since: 2.32

## receiveCredentialsFinish

unixConnectionReceiveCredentialsFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsAsyncResult b) |
=> a | `connection`: A `UnixConnection`.
-> b | `result`: a `AsyncResult`.
-> m Credentials | Returns: a `Credentials`, or `Nothing` on error. Free the returned object with `objectUnref`. (Can throw `GError`)

Finishes an asynchronous receive credentials operation started with `unixConnectionReceiveCredentialsAsync`.

Since: 2.32

## receiveFd

unixConnectionReceiveFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: a `UnixConnection`
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore
-> m Int32 | Returns: a file descriptor on success, -1 on error. (Can throw `GError`)

Receives a file descriptor from the sending end of the connection. The sending end has to call `unixConnectionSendFd` for this to work.

As well as reading the fd this also reads a single byte from the stream, as this is required for fd passing to work on some implementations.

Since: 2.22

## sendCredentials

unixConnectionSendCredentials Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: A `UnixConnection`.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> m () | (Can throw `GError`)

Passes the credentials of the current user the receiving side of the connection. The receiving end has to call `unixConnectionReceiveCredentials` (or similar) to accept the credentials.

As well as sending the credentials this also writes a single NUL byte to the stream, as this is required for credentials passing to work on some implementations.

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

- Linux since GLib 2.26
- FreeBSD since GLib 2.26
- GNU/kFreeBSD since GLib 2.36
- Solaris, Illumos and OpenSolaris since GLib 2.40
- GNU/Hurd since GLib 2.40

Other ways to exchange credentials with a foreign peer includes the `UnixCredentialsMessage` type and `socketGetCredentials` function.

Since: 2.26

## sendCredentialsAsync

unixConnectionSendCredentialsAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: A `UnixConnection`.
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback` to call when the request is satisfied
-> m () |

Asynchronously send credentials.

For more details, see `unixConnectionSendCredentials` which is the synchronous version of this call.

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

Since: 2.32

## sendCredentialsFinish

unixConnectionSendCredentialsFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsAsyncResult b) |
=> a | `connection`: A `UnixConnection`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

Finishes an asynchronous send credentials operation started with `unixConnectionSendCredentialsAsync`.

Since: 2.32

## sendFd

unixConnectionSendFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsUnixConnection a, IsCancellable b) |
=> a | `connection`: a `UnixConnection`
-> Int32 | `fd`: a file descriptor
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> m () | (Can throw `GError`)

Passes a file descriptor to the receiving side of the connection. The receiving end has to call `unixConnectionReceiveFd` to accept the file descriptor.

As well as sending the fd this also writes a single byte to the stream, as this is required for fd passing to work on some implementations.

Since: 2.22