gi-gio-2.0.35: Gio bindings

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

GI.Gio.Interfaces.DatagramBased

Contents

- Exported types
- Methods
  - conditionCheck
  - conditionWait
  - createSource
  - receiveMessages
  - sendMessages

Description

Interface for socket-like objects with datagram semantics.

A `GDatagramBased` is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by `Socket`, which wraps the UNIX socket API on UNIX and winsock2 on Windows.

`GDatagramBased` is entirely platform independent, and is intended to be used alongside higher-level networking APIs such as `IOStream`.

It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()` where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message.

Each `GDatagramBased` operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would successfully run you can call `datagramBasedConditionCheck` or `datagramBasedConditionWait`. You can also use `datagramBasedCreateSource` and attach it to a [struct`gLib`.MainContext] to get callbacks when I/O is possible.

When running a non-blocking operation applications should always be able to handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns `G_IO_ERROR_WOULD_BLOCK`.

As with `GSocket`, `GDatagramBased`s can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection before sending and receiving data through the `GDatagramBased` API. For connectionless socket types the target/source address is specified or received in each I/O operation.

Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe. To use a `GDatagramBased` concurrently from multiple threads, you must implement your own locking.

Since: 2.48

Synopsis

- newtype DatagramBased = DatagramBased (ManagedPtr DatagramBased)
- class (GObject o, IsDescendantOf DatagramBased o) => IsDatagramBased o
- toDatagramBased :: (MonadIO m, IsDatagramBased o) => o -> m DatagramBased
- datagramBasedConditionCheck :: (HasCallStack, MonadIO m, IsDatagramBased a) => a -> [IOCondition] -> m [IOCondition]
- datagramBasedConditionWait :: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) => a -> [IOCondition] -> Int64 -> Maybe b -> m ()
- datagramBasedCreateSource :: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) => a -> [IOCondition] -> Maybe b -> m Source
- datagramBasedReceiveMessages :: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) => a -> [InputMessage] -> Int32 -> Int64 -> Maybe b -> m Int32
- datagramBasedSendMessages :: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) => a -> [OutputMessage] -> Int32 -> Int64 -> Maybe b -> m Int32

# Exported types

newtype DatagramBased Source #

Memory-managed wrapper type.

Constructors

DatagramBased (ManagedPtr DatagramBased) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf DatagramBased o) => IsDatagramBased o Source #

Type class for types which can be safely cast to `DatagramBased`, for instance with `toDatagramBased`.

#### Instances

Instances details

(GObject o, IsDescendantOf DatagramBased o) => IsDatagramBased o Source # |
Instance details Defined in GI.Gio.Interfaces.DatagramBased

toDatagramBased :: (MonadIO m, IsDatagramBased o) => o -> m DatagramBased Source #

Cast to `DatagramBased`, 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, conditionCheck, conditionWait, createSource, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, receiveMessages, ref, refSink, runDispose, sendMessages, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## conditionCheck

datagramBasedConditionCheck Source #

Arguments

:: (HasCallStack, MonadIO m, IsDatagramBased a) |
=> a | `datagramBased`: a `DatagramBased`
-> [IOCondition] | `condition`: a `IOCondition` mask to check
-> m [IOCondition] | Returns: the `IOCondition` mask of the current state

Checks on the readiness of `datagramBased` to perform operations. The operations specified in `condition` are checked for and masked against the currently-satisfied conditions on `datagramBased`. The result is returned.

`IOConditionIn` will be set in the return value if data is available to read with `datagramBasedReceiveMessages`, or if the connection is closed remotely (EOS); and if the datagram_based has not been closed locally using some implementation-specific method (such as `socketClose` or `socketShutdown` with `shutdownRead` set, if it’s a `Socket`).

If the connection is shut down or closed (by calling `socketClose` or `socketShutdown` with `shutdownRead` set, if it’s a `Socket`, for example), all calls to this function will return `IOErrorEnumClosed`.

`IOConditionOut` will be set if it is expected that at least one byte can be sent using `datagramBasedSendMessages` without blocking. It will not be set if the datagram_based has been closed locally.

`IOConditionHup` will be set if the connection has been closed locally.

`IOConditionErr` will be set if there was an asynchronous error in transmitting data previously enqueued using `datagramBasedSendMessages`.

Note that on Windows, it is possible for an operation to return `IOErrorEnumWouldBlock` even immediately after `datagramBasedConditionCheck` has claimed that the `DatagramBased` is ready for writing. Rather than calling `datagramBasedConditionCheck` and then writing to the `DatagramBased` if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns `IOErrorEnumWouldBlock`.

It is meaningless to specify `IOConditionErr` or `IOConditionHup` in `condition`; these conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by `condition`.

This call never blocks.

Since: 2.48

## conditionWait

datagramBasedConditionWait Source #

Arguments

:: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) |
=> a | `datagramBased`: a `DatagramBased`
-> [IOCondition] | `condition`: a `IOCondition` mask to wait for
-> Int64 | `timeout`: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely
-> Maybe b | `cancellable`: a `Cancellable`
-> m () | (Can throw `GError`)

Waits for up to `timeout` microseconds for condition to become true on `datagramBased`. If the condition is met, `True` is returned.

If `cancellable` is cancelled before the condition is met, or if `timeout` is reached before the condition is met, then `False` is returned and `error` is set appropriately (`IOErrorEnumCancelled` or `IOErrorEnumTimedOut`).

Since: 2.48

## createSource

datagramBasedCreateSource Source #

Arguments

:: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) |
=> a | `datagramBased`: a `DatagramBased`
-> [IOCondition] | `condition`: a `IOCondition` mask to monitor
-> Maybe b | `cancellable`: a `Cancellable`
-> m Source | Returns: a newly allocated `Source`

Creates a `Source` that can be attached to a `MainContext` to monitor for the availability of the specified `condition` on the `DatagramBased`. The `Source` keeps a reference to the `datagramBased`.

The callback on the source is of the `DatagramBasedSourceFunc` type.

It is meaningless to specify `IOConditionErr` or `IOConditionHup` in `condition`; these conditions will always be reported in the callback if they are true.

If non-`Nothing`, `cancellable` can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using `cancellableIsCancelled`.

Since: 2.48

## receiveMessages

datagramBasedReceiveMessages Source #

Arguments

:: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) |
=> a | `datagramBased`: a `DatagramBased`
-> [InputMessage] | `messages`: an array of `InputMessage` structs
-> Int32 | `flags`: an int containing `SocketMsgFlags` flags for the overall operation
-> Int64 | `timeout`: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely
-> Maybe b | `cancellable`: a `GCancellable`
-> m Int32 | Returns: number of messages received, or -1 on error. Note that the number of messages received may be smaller than `numMessages` if `timeout` is zero or positive, if the peer closed the connection, or if `numMessages` was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. (Can throw `GError`)

Receive one or more data messages from `datagramBased` in one go.

`messages` must point to an array of `InputMessage` structs and `numMessages` must be the length of this array. Each `InputMessage` contains a pointer to an array of `InputVector` structs describing the buffers that the data received in each message will be written to.

`flags` modify how all messages are received. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in `InputMessage`.`flags`.

The other members of `InputMessage` are treated as described in its documentation.

If `timeout` is negative the call will block until `numMessages` have been received, the connection is closed remotely (EOS), `cancellable` is cancelled, or an error occurs.

If `timeout` is 0 the call will return up to `numMessages` without blocking, or `IOErrorEnumWouldBlock` if no messages are queued in the operating system to be received.

If `timeout` is positive the call will block on the same conditions as if `timeout` were negative. If the timeout is reached before any messages are received, `IOErrorEnumTimedOut` is returned, otherwise it will return the number of messages received before timing out. (Note: This is effectively the behaviour of `MSG_WAITFORONE` with `recvmmsg()`.)

To be notified when messages are available, wait for the `IOConditionIn` condition. Note though that you may still receive `IOErrorEnumWouldBlock` from `datagramBasedReceiveMessages` even if you were previously notified of a `IOConditionIn` condition.

If the remote peer closes the connection, any messages queued in the underlying receive buffer will be returned, and subsequent calls to `datagramBasedReceiveMessages` will return 0 (with no error set).

If the connection is shut down or closed (by calling `socketClose` or `socketShutdown` with `shutdownRead` set, if it’s a `Socket`, for example), all calls to this function will return `IOErrorEnumClosed`.

On error -1 is returned and `error` is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If `cancellable` is cancelled, `IOErrorEnumCancelled` is returned as with any other error.

Since: 2.48

## sendMessages

datagramBasedSendMessages Source #

Arguments

:: (HasCallStack, MonadIO m, IsDatagramBased a, IsCancellable b) |
=> a | `datagramBased`: a `DatagramBased`
-> [OutputMessage] | `messages`: an array of `OutputMessage` structs
-> Int32 | `flags`: an int containing `SocketMsgFlags` flags
-> Int64 | `timeout`: the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely
-> Maybe b | `cancellable`: a `GCancellable`
-> m Int32 | Returns: number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than `numMessages` if `timeout` is zero or positive, or if `numMessages` was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to send the remaining messages. (Can throw `GError`)

Send one or more data messages from `datagramBased` in one go.

`messages` must point to an array of `OutputMessage` structs and `numMessages` must be the length of this array. Each `OutputMessage` contains an address to send the data to, and a pointer to an array of `OutputVector` structs to describe the buffers that the data to be sent for each message will be gathered from.

`flags` modify how the message is sent. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too.

The other members of `OutputMessage` are treated as described in its documentation.

If `timeout` is negative the call will block until `numMessages` have been sent, `cancellable` is cancelled, or an error occurs.

If `timeout` is 0 the call will send up to `numMessages` without blocking, or will return `IOErrorEnumWouldBlock` if there is no space to send messages.

If `timeout` is positive the call will block on the same conditions as if `timeout` were negative. If the timeout is reached before any messages are sent, `IOErrorEnumTimedOut` is returned, otherwise it will return the number of messages sent before timing out.

To be notified when messages can be sent, wait for the `IOConditionOut` condition. Note though that you may still receive `IOErrorEnumWouldBlock` from `datagramBasedSendMessages` even if you were previously notified of a `IOConditionOut` condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

If the connection is shut down or closed (by calling `socketClose` or `socketShutdown` with `shutdownWrite` set, if it’s a `Socket`, for example), all calls to this function will return `IOErrorEnumClosed`.

On error -1 is returned and `error` is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If `cancellable` is cancelled, `IOErrorEnumCancelled` is returned as with any other error.

Since: 2.48