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

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

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]

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