GSocketConnection

## GSocketConnection GSocketConnection — A socket connection |

## Synopsis

    #include <gio/gio.h>

                        GSocketConnection;
    GSocketAddress *    g_socket_connection_get_local_address
                                                            (GSocketConnection *connection,
                                                             GError **error);
    GSocketAddress *    g_socket_connection_get_remote_address
                                                            (GSocketConnection *connection,
                                                             GError **error);
    GSocket *           g_socket_connection_get_socket      (GSocketConnection *connection);

                        GTcpConnection;
    void                g_tcp_connection_set_graceful_disconnect
                                                            (GTcpConnection *connection,
                                                             gboolean graceful_disconnect);
    gboolean            g_tcp_connection_get_graceful_disconnect
                                                            (GTcpConnection *connection);

                        GUnixConnection;
    gint                g_unix_connection_receive_fd        (GUnixConnection *connection,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            g_unix_connection_send_fd           (GUnixConnection *connection,
                                                             gint fd,
                                                             GCancellable *cancellable,
                                                             GError **error);

    GSocketConnection * g_socket_connection_factory_create_connection
                                                            (GSocket *socket);
    GType               g_socket_connection_factory_lookup_type
                                                            (GSocketFamily family,
                                                             GSocketType type,
                                                             gint protocol_id);
    void                g_socket_connection_factory_register_type
                                                            (GType g_type,
                                                             GSocketFamily family,
                                                             GSocketType type,
                                                             gint protocol);

## Object Hierarchy

      GObject
       +----GIOStream
             +----GSocketConnection
                   +----GTcpConnection
                   +----GUnixConnection

      GObject
       +----GIOStream
             +----GSocketConnection
                   +----GTcpConnection

      GObject
       +----GIOStream
             +----GSocketConnection
                   +----GUnixConnection

## Properties

      "socket"                   GSocket*              : Read / Write / Construct Only
      "graceful-disconnect"      gboolean              : Read / Write

## Description

GSocketConnection is a GIOStream for a connected socket. They can be created either by GSocketClient when connecting to a host, or by GSocketListener when accepting a new client.

The type of the GSocketConnection object returned from these calls depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a GTcpConnection.

Chosing what type of object to construct is done with the socket connection factory, and it is possible for 3rd parties to register custom socket connection types for specific combination of socket family/type/protocol using `g_socket_connection_factory_register_type()`.

## Details

### GSocketConnection

    typedef struct _GSocketConnection GSocketConnection;

A socket connection GIOStream object for connection-oriented sockets.

Since 2.22

### g_socket_connection_get_local_address ()

    GSocketAddress *    g_socket_connection_get_local_address
                                                            (GSocketConnection *connection,
                                                             GError **error);

Try to get the local address of a socket connection.

`connection` : | a GSocketConnection
`error` : | GError for error reporting, or `NULL` to ignore.
Returns : | a GSocketAddress or `NULL` on error. Free the returned object with `g_object_unref()`.

Since 2.22

### g_socket_connection_get_remote_address ()

    GSocketAddress *    g_socket_connection_get_remote_address
                                                            (GSocketConnection *connection,
                                                             GError **error);

Try to get the remote address of a socket connection.

`connection` : | a GSocketConnection
`error` : | GError for error reporting, or `NULL` to ignore.
Returns : | a GSocketAddress or `NULL` on error. Free the returned object with `g_object_unref()`.

Since 2.22

### g_socket_connection_get_socket ()

    GSocket *           g_socket_connection_get_socket      (GSocketConnection *connection);

Gets the underlying GSocket object of the connection. This can be useful if you want to do something unusual on it not supported by the GSocketConnection APIs.

`connection` : | a GSocketConnection
Returns : | a GSocketAddress or `NULL` on error.

Since 2.22

### GTcpConnection

    typedef struct _GTcpConnection GTcpConnection;

A GSocketConnection for UNIX domain socket connections.

Since 2.22

### g_tcp_connection_set_graceful_disconnect ()

    void                g_tcp_connection_set_graceful_disconnect
                                                            (GTcpConnection *connection,
                                                             gboolean graceful_disconnect);

This enabled graceful disconnects on close. A graceful disconnect means that we signal the recieving end that the connection is terminated and wait for it to close the connection before closing the connection.

A graceful disconnect means that we can be sure that we successfully sent all the outstanding data to the other end, or get an error reported. However, it also means we have to wait for all the data to reach the other side and for it to acknowledge this by closing the socket, which may take a while. For this reason it is disabled by default.

`connection` : | a GTcpConnection
`graceful_disconnect` : | Whether to do graceful disconnects or not

Since 2.22

### g_tcp_connection_get_graceful_disconnect ()

    gboolean            g_tcp_connection_get_graceful_disconnect
                                                            (GTcpConnection *connection);

Checks if graceful disconnects are used. See `g_tcp_connection_set_graceful_disconnect()`.

`connection` : | a GTcpConnection
Returns : | `TRUE` if graceful disconnect is used on close, `FALSE` otherwise

Since 2.22

### GUnixConnection

    typedef struct _GUnixConnection GUnixConnection;

### g_unix_connection_receive_fd ()

    gint                g_unix_connection_receive_fd        (GUnixConnection *connection,
                                                             GCancellable *cancellable,
                                                             GError **error);

Receives a file descriptor from the sending end of the connection. The sending end has to call `g_unix_connection_send_fd()` 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.

`connection` : | a GUnixConnection
`cancellable` : | optional GCancellable object, `NULL` to ignore
`error` : | GError for error reporting, or `NULL` to ignore
Returns : | a file descriptor on success, -1 on error.

Since 2.22

### g_unix_connection_send_fd ()

    gboolean            g_unix_connection_send_fd           (GUnixConnection *connection,
                                                             gint fd,
                                                             GCancellable *cancellable,
                                                             GError **error);

Passes a file descriptor to the recieving side of the connection. The recieving end has to call `g_unix_connection_receive_fd()` 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.

`connection` : | a GUnixConnection
`fd` : | a file descriptor
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | GError for error reporting, or `NULL` to ignore.
Returns : | a `TRUE` on success, `NULL` on error.

Since 2.22

### g_socket_connection_factory_create_connection ()

    GSocketConnection * g_socket_connection_factory_create_connection
                                                            (GSocket *socket);

Creates a GSocketConnection subclass of the right type for `socket`.

`socket` : | a GSocket
Returns : | a GSocketConnection

Since 2.22

### g_socket_connection_factory_lookup_type ()

    GType               g_socket_connection_factory_lookup_type
                                                            (GSocketFamily family,
                                                             GSocketType type,
                                                             gint protocol_id);

Looks up the GType to be used when creating socket connections on sockets with the specified `family`,`type` and `protocol_id`.

If no type is registered, the GSocketConnection base type is returned.

`family` : | a GSocketFamily
`type` : | a GSocketType
`protocol_id` : | a protocol id
Returns : | a GType

Since 2.22

### g_socket_connection_factory_register_type ()

    void                g_socket_connection_factory_register_type
                                                            (GType g_type,
                                                             GSocketFamily family,
                                                             GSocketType type,
                                                             gint protocol);

Looks up the GType to be used when creating socket connections on sockets with the specified `family`,`type` and `protocol`.

If no type is registered, the GSocketConnection base type is returned.

`g_type` : | a GType, inheriting from `G_TYPE_SOCKET_CONNECTION`
`family` : | a GSocketFamily
`type` : | a GSocketType
`protocol` : | a protocol id

Since 2.22

## Property Details

### The `"socket"` property

      "socket"                   GSocket*              : Read / Write / Construct Only

The underlying GSocket.

### The `"graceful-disconnect"` property

      "graceful-disconnect"      gboolean              : Read / Write

Whether or not close does a graceful disconnect.

Default value: FALSE

## See Also

GIOStream, GSocketClient, GSocketListener