DEXTER_CHANNEL_ERROR

#define DEXTER_CHANNEL_ERROR dexter_channel_error_quark()

The error domain of the libdexter channel subsystem.

enum DexterChannelError

typedef enum {
  DEXTER_CHANNEL_ERROR_EADDRINUSE,
  DEXTER_CHANNEL_ERROR_EAGAIN,
  DEXTER_CHANNEL_ERROR_ECONNREFUSED,
  DEXTER_CHANNEL_ERROR_EINTR,
  DEXTER_CHANNEL_ERROR_ENETUNREACH,
  DEXTER_CHANNEL_ERROR_STATE,
  DEXTER_CHANNEL_ERROR_TIMEOUT,
  DEXTER_CHANNEL_ERROR_TLS_NOT_ENABLED,
  DEXTER_CHANNEL_ERROR_FAILED
} DexterChannelError;

Error codes for DexterChannel operations.

DexterChannel

typedef struct _DexterChannel DexterChannel;

Opaque type with no public members.

enum DexterChannelState

typedef enum {
  DEXTER_CHANNEL_STATE_OPEN,
  DEXTER_CHANNEL_STATE_ABORT,
  DEXTER_CHANNEL_STATE_NOCONN,
  DEXTER_CHANNEL_STATE_CLOSED,
} DexterChannelState;

All possible channel states.

enum DexterChannelEvent

typedef enum {
  DEXTER_CHANNEL_EVENT_OPEN,
  DEXTER_CHANNEL_EVENT_ABORT,
  DEXTER_CHANNEL_EVENT_NOCONN,
  DEXTER_CHANNEL_EVENT_CLOSED
} DexterChannelEvent;

All possible channel events.

DexterChannelEventCallback ()

void                (*DexterChannelEventCallback)       (DexterChannel *channel,
                                                         gint event);

Signature of callback function used to receive channel event notifications.

struct DexterChannelTLSSettings

struct DexterChannelTLSSettings {
  gchar    *cert_file;        /* ChannelTLSCertFile */ 
  gchar    *key_file;         /* ChannelTLSKeyFile */
  gchar    *trust_file;       /* ChannelTLSTrustFile */
  gchar    *crl_file;         /* ChannelTLSCrlFile  */
  gboolean  verify_hostname;  /* ChannelTLSVerifyHostname */
};

TLS settings that the channel will use when starting TLS. They are copied from the DexterChannelSettings structure provided to dexter_channel_new().

When this structure is seen within the context of a DexterChannelTLSStartCallback, you may change the elements as needed. For any non-NULL gchar elements that you want to change, you must first g_free() the element and then allocate a replacement string using a GLib string allocation api, e.g. g_strdup_printf(). The Library will free everything for you when the callback exits.

Since 0.2.0

DexterChannelTLSStartCallback ()

void                (*DexterChannelTLSStartCallback)    (DexterChannel *channel,
                                                         const struct sockaddr *server_sa,
                                                         socklen_t server_salen,
                                                         DexterChannelTLSSettings *tls_settings);

Signature of callback function used to adjust TLS settings, as needed for this server address, as TLS starts.

If specificed in dexter_channel_starttls(), this callback allows you to inspect the server socket address and adjust your channel TLS parameters as needed. In this manner you can decide which certificate, trust and revocation files to use based on the server you are connected to.

Since 0.2.0

enum DexterChannelSettingFlags

typedef enum {
  DEXTER_CHANNEL_SETTING_HOST                 = 1 << 0,
  DEXTER_CHANNEL_SETTING_SERVICE              = 1 << 1,
  DEXTER_CHANNEL_SETTING_SOCKET_OPTIONS       = 1 << 2,
  DEXTER_CHANNEL_SETTING_RECV_BUFFER_SIZE     = 1 << 3,
  DEXTER_CHANNEL_SETTING_TIMEOUT_MSECS        = 1 << 4,
  DEXTER_CHANNEL_SETTING_EVENT_CALLBACK       = 1 << 5,
  DEXTER_CHANNEL_SETTING_TLS_START_CALLBACK   = 1 << 6,
  DEXTER_CHANNEL_SETTING_TLS_CERT_FILE        = 1 << 7,
  DEXTER_CHANNEL_SETTING_TLS_KEY_FILE         = 1 << 8,
  DEXTER_CHANNEL_SETTING_TLS_TRUST_FILE       = 1 << 9,
  DEXTER_CHANNEL_SETTING_TLS_CRL_FILE         = 1 << 10,
  DEXTER_CHANNEL_SETTING_TLS_VERIFY_HOSTNAME  = 1 << 11
} DexterChannelSettingFlags;

Flags to indicate which elements of DexterChannelSettings have data on them.

Since 0.2.0

struct DexterChannelSettings

struct DexterChannelSettings {
  DexterChannelSettingFlags     flags;
  gchar   *host;                /* ChannelHost */
  gchar   *service;             /* ChannelService */
  gchar   *socket_options;      /* ChannelSocketOptions */
  gint     recv_buffer_size;    /* ChannelRecvBufferSize */
  gint     timeout_msecs;       /* ChannelTimeoutMsecs */
  DexterChannelEventCallback    event_callback;         /* -- */
  DexterChannelTLSStartCallback tls_start_callback;     /* -- */
  gchar   *tls_cert_file;       /* ChannelTLSCertFile */
  gchar   *tls_key_file;        /* ChannelTLSKeyFile */
  gchar   *tls_trust_file;      /* ChannelTLSTrustFile */
  gchar   *tls_crl_file;        /* ChannelTLSCrlFile */
  gboolean tls_verify_hostname; /* ChannelTLSVerifyHostname */
};

Channel settings.

The flags element indicates which elements have user-supplied data.

Elements for which no flag is set, i.e. have no user-supplied data, will be set to a default: either from the configuration file, if available, or an internal default will be used.

Since 0.2.0

dexter_channel_new ()

DexterChannel *     dexter_channel_new                  (const DexterChannelSettings *settings);

Creates a channel using the supplied settings.

NULL may be indicated for settings, in which case the configuration file is used for all channel settings. Internal defaults are used for items not found in the configuration file.

No network calls are performed until the channel is opened with dexter_channel_open().

The channel must be freed when done with dexter_channel_free().

dexter_channel_open ()

gboolean            dexter_channel_open                 (DexterChannel *channel,
                                                         GError **error);

Opens the channel created with dexter_channel_new(). A new tcp/ip connection is established to the server for the channel. It remains open until dexter_channel_close() is called, the server disconnects, or a network error occurs.

In the event an open channel is broken due to a network or server problem, the channel will notify all objects running on channel and then the channel will transition to DEXTER_CHANNEL_STATE_NOCONN.

dexter_channel_close ()

gboolean            dexter_channel_close                (DexterChannel *channel,
                                                         GError **error);

Closes a DexterChannel previously opened with dexter_channel_open(). If the channel is already closed, no error occurs and TRUE is returned.

dexter_channel_greet ()

gboolean            dexter_channel_greet                (DexterChannel *channel,
                                                         GError **error);

Sends the protocol greeting on a DexterChannel previously opened with dexter_channel_open(). The greeting must be sent before using the channel, e.g. to create samplers.

dexter_channel_noop ()

gboolean            dexter_channel_noop                 (DexterChannel *channel,
                                                         GError **error);

Sends a "no operation" command over the DexterChannel to the connected server.

Since 0.2.0

dexter_channel_starttls ()

gboolean            dexter_channel_starttls             (DexterChannel *channel,
                                                         GError **error);

Initializes TLS over the currently opened channel.

Since 0.2.0

dexter_channel_part ()

gboolean            dexter_channel_part                 (DexterChannel *channel,
                                                         GError **error);

Sends protocol parting message on a DexterChannel over which dexter_channel_greet() has already been called. Should be called prior to dexter_channel_close().

dexter_channel_free ()

void                dexter_channel_free                 (DexterChannel *channel);

Frees a DexterChannel created with dexter_channel_new(). If the channel is not closed, it will be closed for you, although it is better form to use dexter_channel_close() before freeing the channel.

dexter_channel_get_state ()

gint                dexter_channel_get_state            (DexterChannel *channel);

Returns the current state of the channel.