## GNIO Utilities

GNIO Utilities — Telepathy/GNIO utility functions

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

    GSocketAddress *    tp_g_socket_address_from_variant    (TpSocketAddressType type,
                                                             const GValue *variant,
                                                             GError **error);
    GValue *            tp_address_variant_from_g_socket_address
                                                            (GSocketAddress *address,
                                                             TpSocketAddressType *type,
                                                             GError **error);
    GSocketAddress *    tp_g_socket_address_from_g_variant  (TpSocketAddressType type,
                                                             GVariant *variant,
                                                             GError **error);
    GVariant *          tp_address_g_variant_from_g_socket_address
                                                            (GSocketAddress *address,
                                                             TpSocketAddressType *type,
                                                             GError **error);
    GCredentials *      tp_unix_connection_receive_credentials_with_byte
                                                            (GSocketConnection *connection,
                                                             guchar *byte,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tp_unix_connection_receive_credentials_with_byte_async
                                                            (GSocketConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GCredentials *      tp_unix_connection_receive_credentials_with_byte_finish
                                                            (GSocketConnection *connection,
                                                             GAsyncResult *result,
                                                             guchar *byte,
                                                             GError **error);
    gboolean            tp_unix_connection_send_credentials_with_byte
                                                            (GSocketConnection *connection,
                                                             guchar byte,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tp_unix_connection_send_credentials_with_byte_async
                                                            (GSocketConnection *connection,
                                                             guchar byte,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_unix_connection_send_credentials_with_byte_finish
                                                            (GSocketConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

## Description

Utility functions for interacting between Telepathy and GNIO.

Telepathy uses address variants stored in GValue boxes for communicating network socket addresses over D-Bus to and from the Connection Manager (for instance when using the file transfer and stream tube APIs).

This API provides translation between GSocketAddress subtypes and a GValue that can be used by telepathy-glib. GInetSocketAddress is used for IPv4/IPv6 and GUnixSocketAddress for UNIX sockets (only available on platforms with gio-unix).

## Details

### tp_g_socket_address_from_variant ()

    GSocketAddress *    tp_g_socket_address_from_variant    (TpSocketAddressType type,
                                                             const GValue *variant,
                                                             GError **error);

Converts an address variant stored in a GValue into a GSocketAddress that can be used to make a socket connection with GIO.

`type` : | a Telepathy socket address type
`variant` : | an initialised GValue containing an address variant, as encoded by dbus-glib
`error` : | return location for a GError (or NULL)
Returns : | a newly allocated GSocketAddress for the given variant, or NULL on error

### tp_address_variant_from_g_socket_address ()

    GValue *            tp_address_variant_from_g_socket_address
                                                            (GSocketAddress *address,
                                                             TpSocketAddressType *type,
                                                             GError **error);

Converts a GSocketAddress to a GValue address variant that can be used with Telepathy and dbus-glib.

`address` : | a GSocketAddress to convert
`type` : | optional return of the Telepathy socket type (or NULL)
`error` : | return location for a GError (or NULL)
Returns : | a newly allocated GValue, free with `tp_g_value_slice_free()`

### tp_g_socket_address_from_g_variant ()

    GSocketAddress *    tp_g_socket_address_from_g_variant  (TpSocketAddressType type,
                                                             GVariant *variant,
                                                             GError **error);

Converts an address variant stored in a GVariant into a GSocketAddress that can be used to make a socket connection with GIO.

If `variant` is a floating reference, this function takes ownership of it.

`type` : | a Telepathy socket address type
`variant` : | a socket address as encoded by Telepathy according to `type`
`error` : | return location for a GError (or `NULL`)
Returns : | a newly allocated GSocketAddress for the given variant, or `NULL` on error

Since 0.19.10

### tp_address_g_variant_from_g_socket_address ()

    GVariant *          tp_address_g_variant_from_g_socket_address
                                                            (GSocketAddress *address,
                                                             TpSocketAddressType *type,
                                                             GError **error);

Converts a GSocketAddress to a GVariant address variant that can be used with Telepathy.

`address` : | a GSocketAddress to convert
`type` : | optional return of the Telepathy socket type (or NULL)
`error` : | return location for a GError (or NULL)
Returns : | a new variant with a floating reference, or `NULL`. [transfer none]

Since 0.19.10

### tp_unix_connection_receive_credentials_with_byte ()

    GCredentials *      tp_unix_connection_receive_credentials_with_byte
                                                            (GSocketConnection *connection,
                                                             guchar *byte,
                                                             GCancellable *cancellable,
                                                             GError **error);

A variant of `g_unix_connection_receive_credentials()` allowing you to get the byte which has been received with the credentials.

`connection` : | a GUnixConnection
`byte` : | if not `NULL`, used to return the byte. [out]
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`error` : | a GError to fill
Returns : | Received credentials on success (free with `g_object_unref()`), `NULL` if error is set. [transfer full]

Since 0.13.2

### tp_unix_connection_receive_credentials_with_byte_async ()

    void                tp_unix_connection_receive_credentials_with_byte_async
                                                            (GSocketConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously receive credentials.

For more details, see `tp_unix_connection_receive_credentials_with_byte()` which is the synchronous version of this call.

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

`connection` : | A GUnixConnection.
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to callback function. [closure]

Since 0.17.5

### tp_unix_connection_receive_credentials_with_byte_finish ()

    GCredentials *      tp_unix_connection_receive_credentials_with_byte_finish
                                                            (GSocketConnection *connection,
                                                             GAsyncResult *result,
                                                             guchar *byte,
                                                             GError **error);

Finishes an asynchronous receive credentials operation started with `tp_unix_connection_receive_credentials_with_byte_async()`.

`connection` : | A GUnixConnection.
`result` : | a GAsyncResult.
`byte` : | if not `NULL`, used to return the byte. [out]
`error` : | a GError, or `NULL`
Returns : | a GCredentials, or `NULL` on error. Free the returned object with `g_object_unref()`. [transfer full]

Since 0.17.5

### tp_unix_connection_send_credentials_with_byte ()

    gboolean            tp_unix_connection_send_credentials_with_byte
                                                            (GSocketConnection *connection,
                                                             guchar byte,
                                                             GCancellable *cancellable,
                                                             GError **error);

A variant of `g_unix_connection_send_credentials()` allowing you to choose the byte which is send with the credentials

`connection` : | a GUnixConnection
`byte` : | the byte to send with the credentials
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`error` : | a GError to fill
Returns : | `TRUE` on success, `FALSE` if error is set.

Since 0.13.2

### tp_unix_connection_send_credentials_with_byte_async ()

    void                tp_unix_connection_send_credentials_with_byte_async
                                                            (GSocketConnection *connection,
                                                             guchar byte,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously send credentials.

For more details, see `tp_unix_connection_send_credentials_with_byte()` which is the synchronous version of this call.

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

`connection` : | A GUnixConnection.
`byte` : | the byte to send with the credentials
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to callback function. [closure]

Since 0.17.5

### tp_unix_connection_send_credentials_with_byte_finish ()

    gboolean            tp_unix_connection_send_credentials_with_byte_finish
                                                            (GSocketConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous send credentials operation started with `tp_unix_connection_send_credentials_with_byte_async()`.

`connection` : | A GUnixConnection.
`result` : | a GAsyncResult.
`error` : | a GError, or `NULL`
Returns : | `TRUE` if the operation was successful, otherwise `FALSE`.

Since 0.17.5