## CamelNetworkService

CamelNetworkService

## Synopsis

                        CamelNetworkService;
    const gchar *       camel_network_service_get_service_name
                                                            (CamelNetworkService *service,
                                                             CamelNetworkSecurityMethod method);
    guint16             camel_network_service_get_default_port
                                                            (CamelNetworkService *service,
                                                             CamelNetworkSecurityMethod method);
    GSocketConnectable * camel_network_service_ref_connectable
                                                            (CamelNetworkService *service);
    void                camel_network_service_set_connectable
                                                            (CamelNetworkService *service,
                                                             GSocketConnectable *connectable);
    gboolean            camel_network_service_get_host_reachable
                                                            (CamelNetworkService *service);
    GIOStream *         camel_network_service_connect_sync  (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GIOStream *         camel_network_service_starttls      (CamelNetworkService *service,
                                                             GIOStream *base_stream,
                                                             GError **error);
    gboolean            camel_network_service_can_reach_sync
                                                            (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_network_service_can_reach     (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_network_service_can_reach_finish
                                                            (CamelNetworkService *service,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----CamelNetworkService

## Prerequisites

CamelNetworkService requires CamelService.

## Known Implementations

CamelNetworkService is implemented by CamelIMAPXStore, CamelNNTPStore, CamelPOP3Store and CamelSmtpTransport.

## Properties

      "connectable"              GSocketConnectable*   : Read / Write
      "host-reachable"           gboolean              : Read

## Description

## Details

### CamelNetworkService

    typedef struct _CamelNetworkService CamelNetworkService;

Since 3.2

### camel_network_service_get_service_name ()

    const gchar *       camel_network_service_get_service_name
                                                            (CamelNetworkService *service,
                                                             CamelNetworkSecurityMethod method);

Returns the standard network service name for `service` and the security method `method`, as defined in /etc/services. For example, the service name for unencrypted IMAP or encrypted IMAP using STARTTLS is "imap", but the service name for IMAP over SSL is "imaps".

`service` : | a CamelNetworkService
`method` : | a CamelNetworkSecurityMethod
Returns : | the network service name for `service` and `method`, or `NULL`

Since 3.2

### camel_network_service_get_default_port ()

    guint16             camel_network_service_get_default_port
                                                            (CamelNetworkService *service,
                                                             CamelNetworkSecurityMethod method);

Returns the default network port number for `service` and the security method `method`, as defined in /etc/services. For example, the default port for unencrypted IMAP or encrypted IMAP using STARTTLS is 143, but the default port for IMAP over SSL is 993.

`service` : | a CamelNetworkService
`method` : | a CamelNetworkSecurityMethod
Returns : | the default port number for `service` and `method`

Since 3.2

### camel_network_service_ref_connectable ()

    GSocketConnectable * camel_network_service_ref_connectable
                                                            (CamelNetworkService *service);

Returns the socket endpoint for the network service to which `service` is a client.

The returned GSocketConnectable is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`service` : | a CamelNetworkService
Returns : | a GSocketConnectable

Since 3.8

### camel_network_service_set_connectable ()

    void                camel_network_service_set_connectable
                                                            (CamelNetworkService *service,
                                                             GSocketConnectable *connectable);

Sets the socket endpoint for the network service to which `service` is a client. If `connectable` is `NULL`, a GSocketConnectable is derived from the `service`'s CamelNetworkSettings.

`service` : | a CamelNetworkService
`connectable` : | a GSocketConnectable, or `NULL`

Since 3.8

### camel_network_service_get_host_reachable ()

    gboolean            camel_network_service_get_host_reachable
                                                            (CamelNetworkService *service);

Returns `TRUE` if `service` believes that the host pointed to by "connectable" can be reached. This property is updated automatically as network conditions change.

`service` : | a CamelNetworkService
Returns : | whether the host is reachable

Since 3.8

### camel_network_service_connect_sync ()

    GIOStream *         camel_network_service_connect_sync  (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to establish a network connection to the server described by `service`, using the preferred "security-method" to secure the connection. If a connection cannot be established, or the connection attempt is cancelled, the function sets `error` and returns `NULL`.

`service` : | a CamelNetworkService
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | a GIOStream, or `NULL`

Since 3.2

### camel_network_service_starttls ()

    GIOStream *         camel_network_service_starttls      (CamelNetworkService *service,
                                                             GIOStream *base_stream,
                                                             GError **error);

Creates a GTlsClientConnection wrapping `base_stream`, which is assumed to communicate with the server identified by `service`'s "connectable".

This should typically be called after issuing a STARTTLS command to a server to initiate a Transport Layer Security handshake.

`service` : | a CamelNetworkService
`base_stream` : | a GIOStream
`error` : | return location for a GError, or `NULL`
Returns : | the new GTlsClientConnection, or `NULL` on error

Since 3.12

### camel_network_service_can_reach_sync ()

    gboolean            camel_network_service_can_reach_sync
                                                            (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to determine whether or not the host described by `service`'s "connectable" property can be reached, without actually trying to connect to it.

If `service` believes an attempt to connect will succeed, the function returns `TRUE`. Otherwise the function returns `FALSE` and sets `error` to an appropriate error (such as `G_IO_ERROR_HOST_UNREACHABLE`).

The function will also update the `service`'s "host-reachable" property based on the result.

`service` : | a CamelNetworkService
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | whether the host for `service` can be reached

Since 3.12

### camel_network_service_can_reach ()

    void                camel_network_service_can_reach     (CamelNetworkService *service,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously attempts to determine whether or not the host described by `service`'s "connectable" property can be reached, without actually trying to connect to it.

For more details, see `camel_network_service_can_reach_sync()`.

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

`service` : | a CamelNetworkService
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.12

### camel_network_service_can_reach_finish ()

    gboolean            camel_network_service_can_reach_finish
                                                            (CamelNetworkService *service,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_network_service_can_reach()`.

`service` : | a CamelNetworkService
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | whether the host for `service` can be reached

Since 3.12

## Property Details

### The `"connectable"` property

      "connectable"              GSocketConnectable*   : Read / Write

Socket endpoint of a network service.

### The `"host-reachable"` property

      "host-reachable"           gboolean              : Read

Whether the host is reachable.

Default value: FALSE