## InfKeepalive

InfKeepalive — Platform-independent configuration of TCP keep-alive probes

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfKeepalive * | inf_keepalive_copy ()
void | inf_keepalive_free ()
gboolean | inf_keepalive_apply ()
void | inf_keepalive_load_default ()

## Types and Values

enum | InfKeepaliveMask
struct | InfKeepalive

## Object Hierarchy

        GBoxed
        ╰── InfKeepalive
        GFlags
        ╰── InfKeepaliveMask

## Includes

    #include <libinfinity/common/inf-keepalive.h>

## Description

The functions in this section can be used to enable and configure TCP keepalives in a platform-independent way. This allows to detect inactive connections, and to maintain some activity in case a firewall is dropping the connection after some inactivity.

Typically, these functions do not need to be called directly, but the keep-alive settings can be configured with `inf_tcp_connection_set_keepalive()`, `infd_tcp_server_set_keepalive()` and `inf_discovery_avahi_set_keepalive()`.

The InfKeepalive structure can be safely allocated on the stack and copied by value.

## Functions

### inf_keepalive_copy ()

    InfKeepalive *
    inf_keepalive_copy (const InfKeepalive *keepalive);

Makes a dynamically allocated copy of `keepalive` . This is typically not needed, since the structure can be copied by value, but might prove useful for language bindings.

#### Parameters

keepalive | The InfKeepalive to copy. |

#### Returns

A copy of `keepalive` . Free with `inf_keepalive_free()`.

[transfer full]

### inf_keepalive_free ()

    void
    inf_keepalive_free (InfKeepalive *keepalive);

Frees a InfKeepalive obtained with `inf_keepalive_copy()`.

#### Parameters

keepalive | A dynamically allocated InfKeepalive. |

### inf_keepalive_apply ()

    gboolean
    inf_keepalive_apply (const InfKeepalive *keepalive,
                         InfNativeSocket *socket,
                         InfKeepaliveMask current_mask,
                         GError **error);

Sets the keepalive settings of `keepalive` for the socket `socket` . This function abstracts away the platform-dependent configuration of keepalives.

If `current_mask` is not `INF_KEEPALIVE_ALL`, it can help this function to not do some unneccessary system calls.

#### Parameters

keepalive | A InfKeepalive. |
socket | The socket to which to apply the keepalive settings. | [in]
current_mask | The mask of currently applied keepalive settings on the socket, or `INF_KEEPALIVE_ALL` if unknown. |
error | Location for error information, if any, or `NULL`. |

#### Returns

`TRUE` on success or `FALSE` if an error occurred.

### inf_keepalive_load_default ()

    void
    inf_keepalive_load_default (InfKeepalive *keepalive,
                                InfKeepaliveMask mask);

This function attempts to obtain the default keepalive settings from the system. If it cannot obtain the default settings, the documented standard values for the host platform are used.

Only the values specified in `mask` are obtained, and other fields in `keepalive` are left untouched.

#### Parameters

keepalive | A InfKeepalive. | [inout]
mask | A mask that specifies which values to obtain. |

## Types and Values

### enum InfKeepaliveMask

This bitmask specifies which of the fields in InfKeepalive override the system defaults. For fields that are not enabled in the bitmask, the system default value is taken, and the corresponding field in InfKeepalive is ignored.

#### Members

INF_KEEPALIVE_ENABLED | Whether the keepalive mechanism is explicitly enabled or disabled. |
INF_KEEPALIVE_TIME | Whether the keepalive time is overriding the system default. |
INF_KEEPALIVE_INTERVAL | Whether the keepalive interval is overriding the system default. |
INF_KEEPALIVE_ALL | All previous values combined. |

### struct InfKeepalive

    struct InfKeepalive {
      InfKeepaliveMask mask;
      gboolean enabled;
      guint time;
      guint interval;
    };

This structure contains the settings to configure keep-alive on TCP connections.

#### Members

InfKeepaliveMask `mask`; | Which of the following settings are enabled. If a setting is disabled, then the system default is taken. |
gboolean `enabled`; | Whether sending keep-alive probes is enabled or not. |
guint `time`; | Time in seconds after which to send keep-alive probes. |
guint `interval`; | Time in seconds between keep-alive probes. |