CamelNetworkService: Camel Reference Manual

## CamelNetworkService CamelNetworkService |

## Functions

const gchar * | camel_network_service_get_service_name ()
guint16 | camel_network_service_get_default_port ()
GSocketConnectable * | camel_network_service_ref_connectable ()
void | camel_network_service_set_connectable ()
gboolean | camel_network_service_get_host_reachable ()
GIOStream * | camel_network_service_connect_sync ()
GIOStream * | camel_network_service_starttls ()
gboolean | camel_network_service_can_reach_sync ()
void | camel_network_service_can_reach ()
gboolean | camel_network_service_can_reach_finish ()

## Properties

GSocketConnectable * | connectable | Read / Write
gboolean | host-reachable | Read

## Types and Values

| CamelNetworkService

## Object Hierarchy

        GInterface
        ╰── CamelNetworkService

## Prerequisites

CamelNetworkService requires

## Description

## Functions

### 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".

#### Parameters

service | a CamelNetworkService |
method | a CamelNetworkSecurityMethod |

#### Returns

the network service name for `service` and `method` , or `NULL`.

[nullable]

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.

#### Parameters

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.

#### Parameters

service | a CamelNetworkService |

#### Returns

a GSocketConnectable.

[transfer full]

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.

#### Parameters

service | a CamelNetworkService |
connectable | a GSocketConnectable, or `NULL`. | [nullable]

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.

#### Parameters

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`.

#### Parameters

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

#### Returns

a GIOStream, or `NULL` on error.

[transfer full]

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.

#### Parameters

service | a CamelNetworkService |
base_stream | a GIOStream |
error | return location for a GError, or `NULL` |

#### Returns

the new GTlsClientConnection, or `NULL` on error.

[transfer full][nullable]

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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

## Types and Values

### CamelNetworkService

    typedef struct _CamelNetworkService CamelNetworkService;

Since: 3.2

## Property Details

### The `“connectable”` property

      “connectable”              GSocketConnectable *

Socket endpoint of a network service

Owner: CamelNetworkService

Flags: Read / Write

### The `“host-reachable”` property

      “host-reachable”           gboolean

Whether the host is reachable

Owner: CamelNetworkService

Flags: Read

Default value: FALSE