DEXTER_SERVER_ERROR

#define DEXTER_SERVER_ERROR   dexter_server_error_quark()

The error domain of the libdexter server subsystem.

enum DexterServerError

typedef enum {
  DEXTER_SERVER_ERROR_EACCES,
  DEXTER_SERVER_ERROR_EADDRINUSE,
  DEXTER_SERVER_ERROR_EAGAIN,
  DEXTER_SERVER_ERROR_STATE,
  DEXTER_SERVER_ERROR_TLS_NOT_ENABLED,
  DEXTER_SERVER_ERROR_FAILED
} DexterServerError;

Error codes for dexter_server operations.

DexterServer

typedef struct _DexterServer DexterServer;

Opaque type with no public members.

enum DexterServerState

typedef enum {
  DEXTER_SERVER_STATE_STARTED,
  DEXTER_SERVER_STATE_STOPPED,
} DexterServerState;

All possible server states.

enum DexterServerTLSSupportFlag

typedef enum {
  DEXTER_SERVER_TLS_SUPPORT_NONE      = 0,
  DEXTER_SERVER_TLS_SUPPORT_AVAILABLE = 1,
  DEXTER_SERVER_TLS_SUPPORT_REQUIRED  = 2,
} DexterServerTLSSupportFlag;

Flag to set the level of TLS support offered by the server.

For DEXTER_SERVER_TLS_SUPPORT_AVAILABLE, the client may issue dexter_channel_starttls(), but is not required to do so.

For DEXTER_SERVER_TLS_SUPPORT_REQUIRED, the client must issue dexter_channel_starttls() after dexter_channel_greet(). The server will respond negatively to any channel operation, except dexter_channel_part(), until TLS is started by the client.

Since 0.2.0

enum DexterServerTLSClientCertFlag

typedef enum {
  DEXTER_SERVER_TLS_CLIENT_CERT_NONE      = 0,
  DEXTER_SERVER_TLS_CLIENT_CERT_REQUESTED = 1,
  DEXTER_SERVER_TLS_CLIENT_CERT_REQUIRED  = 2
} DexterServerTLSClientCertFlag;

Flag to set server requirements for client X.509 certificates.

Since 0.2.0

struct DexterServerTLSSettings

struct DexterServerTLSSettings {
  gchar   *cert_file;       /* ServerTLSCertFile */
  gchar   *key_file;        /* ServerTLSKeyFile */
  gchar   *trust_file;      /* ServerTLSTrustFile */
  gchar   *crl_file;        /* ServerTLSCrlFile */
  DexterServerTLSClientCertFlag client_cert_flag;  /* ServerTLSClientCertFlag */
  gboolean verify_hostname; /* ServerTLSVerifyHostname */
};

TLS settings that the server will use when starting TLS for a client. They are copied from the DexterServerSettings structure provided to dexter_server_new().

When this structure is seen within the context of a DexterServerTLSStartCallback, 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

DexterServerTLSStartCallback ()

void                (*DexterServerTLSStartCallback)     (DexterServer *server,
                                                         const struct sockaddr *client_sa,
                                                         socklen_t client_salen,
                                                         DexterServerTLSSettings *tls_settings);

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

If specificed in DexterServerTLSSettings, this callback allows you to inspect the client socket address and adjust your server TLS settings as needed for that client connection. In this manner you can decide which certificate, trust and revocation files to use based on the client, and whether or not that particular client must present X.509 certificates.

Since 0.2.0

enum DexterServerSettingFlags

typedef enum {
  DEXTER_SERVER_SETTING_HOST                 = 1 << 0,
  DEXTER_SERVER_SETTING_SERVICE              = 1 << 1,
  DEXTER_SERVER_SETTING_SOCKET_OPTIONS       = 1 << 2,
  DEXTER_SERVER_SETTING_MAX_BACKLOG          = 1 << 3,
  DEXTER_SERVER_SETTING_MAX_CLIENTS          = 1 << 4,
  DEXTER_SERVER_SETTING_RECV_BUFFER_SIZE     = 1 << 5,
  DEXTER_SERVER_SETTING_TLS_SUPPORT_FLAG     = 1 << 6,
  DEXTER_SERVER_SETTING_TLS_CLIENT_CERT_FLAG = 1 << 7,
  DEXTER_SERVER_SETTING_TLS_START_CALLBACK   = 1 << 8,
  DEXTER_SERVER_SETTING_TLS_CERT_FILE        = 1 << 9,
  DEXTER_SERVER_SETTING_TLS_KEY_FILE         = 1 << 10,
  DEXTER_SERVER_SETTING_TLS_TRUST_FILE       = 1 << 11,
  DEXTER_SERVER_SETTING_TLS_CRL_FILE         = 1 << 12,
  DEXTER_SERVER_SETTING_TLS_VERIFY_HOSTNAME  = 1 << 13
} DexterServerSettingFlags;

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

Since 0.2.0

struct DexterServerSettings

struct DexterServerSettings {
  DexterServerSettingFlags      flags;
  gchar   *host;                /* ServerHost */
  gchar   *service;             /* ServerService */
  gchar   *socket_options;      /* ServerSocketOptions */
  gint     max_backlog;         /* ServerMaxBacklog */
  gint     max_clients;         /* ServerMaxClients */
  gint     recv_buffer_size;    /* ServerRecvBufferSize */
  DexterServerTLSSupportFlag    tls_support_flag;       /* ServerTLSSupportFlag */
  DexterServerTLSClientCertFlag tls_client_cert_flag;   /* ServerTLSClientCertFlag */
  DexterServerTLSStartCallback  tls_start_callback;     /* -- */
  gchar   *tls_cert_file;       /* ServerTLSCertFile */
  gchar   *tls_key_file;        /* ServerTLSKeyFile */
  gchar   *tls_trust_file;      /* ServerTLSTrustFile */
  gchar   *tls_crl_file;        /* ServerTLSCrlFile */
  gboolean tls_verify_hostname; /* ServerTLSVerifyHostname */
};

Server 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_server_new ()

DexterServer *      dexter_server_new                   (const DexterServerSettings *settings);

Creates a server using the supplied settings.

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

No network calls are performed until the server is started with dexter_server_start().

The server must be freed when done with dexter_server_free().

dexter_server_start ()

gboolean            dexter_server_start                 (DexterServer *server,
                                                         GError **error);

Starts the server created with dexter_server_new().

The server is threaded, so control will pass immediately to the next statement in the program. The server will accept connections immediately and continue to accept connections until dexter_server_stop() is called.

dexter_server_stop ()

gboolean            dexter_server_stop                  (DexterServer *server,
                                                         GError **error);

Stops a DexterServer previously opened with dexter_channel_open().

No new connections will be accepted and existing connections are shutdown.

dexter_server_free ()

void                dexter_server_free                  (DexterServer *server);

Frees a DexterServer created with dexter_server_new().

If the server is started, it will be stopped for you, although it is better form to use dexter_server_stop() before freeing the server. Future versions may be stricter on this point.

dexter_server_get_state ()

gint                dexter_server_get_state             (DexterServer *server);

Returns the current state of the server.