WockyConnector

WockyConnector — Low-level XMPP connection generator.

Synopsis

#include <wocky/wocky-connector.h>

#define             WOCKY_CONNECTOR_ERROR
struct              WockyConnectorClass;
enum                WockyConnectorError;
void                wocky_connector_connect_async       (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);
WockyXmppConnection * wocky_connector_connect_finish    (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         gchar **jid,
                                                         gchar **sid,
                                                         GError **error);
GQuark              wocky_connector_error_quark         (void);
WockyConnector *    wocky_connector_new                 (const gchar *jid,
                                                         const gchar *pass,
                                                         const gchar *resource,
                                                         WockyAuthRegistry *auth_registry,
                                                         WockyTLSHandler *tls_handler);
void                wocky_connector_register_async      (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);
WockyXmppConnection * wocky_connector_register_finish   (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         gchar **jid,
                                                         gchar **sid,
                                                         GError **error);
void                wocky_connector_set_auth_registry   (WockyConnector *self,
                                                         WockyAuthRegistry *registry);
void                wocky_connector_unregister_async    (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);
gboolean            wocky_connector_unregister_finish   (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Object Hierarchy

  GEnum
   +----WockyConnectorError

Description

See: RFC3920 XEP-0077

Sends and receives WockyStanzas from an underlying GIOStream. negotiating TLS if possible and completing authentication with the server by the "most suitable" method available. Returns a WockyXmppConnection object to the user on successful completion.

Can also be used to register or unregister an account: When unregistering (cancelling) an account, a WockyXmppConnection is NOT returned - a gboolean value indicating success or failure is returned instead.

The WOCKY_DEBUG tag for this module is "connector".

The flow of control during connection is roughly as follows: (registration/cancellation flows are not represented with here)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
tcp_srv_connected
│
├→ tcp_host_connected
│  ↓
└→ maybe_old_ssl
   ↓
   xmpp_init ←─────────────────┬──┐
   ↓                           │  │
   xmpp_init_sent_cb           │  │
   ↓                           │  │
   xmpp_init_recv_cb           │  │
   │ ↓                         │  │
   │ xmpp_features_cb          │  │
   │ │ │ ↓                     │  │
   │ │ │ tls_module_secure_cb ─┘  │             ①
   │ │ ↓                      │             ↑
   │ │ sasl_request_auth      │             jabber_auth_done
   │ │ ↓                      │             ↑
   │ │ sasl_auth_done ────────┴─[no sasl]─→ jabber_request_auth
   │ ↓                                      ↑
   │ iq_bind_resource                       │
   │ ↓                                      │
   │ iq_bind_resource_sent_cb               │
   │ ↓                                      │
   │ iq_bind_resource_recv_cb               │
   │ ↓                                      │
   │ ①                                      │
   └──────────[old auth]────────────────────┘

   ①
   ↓
   establish_session ─────────→ success
   ↓                              ↑
   establish_session_sent_cb      │
   ↓                              │
   establish_session_recv_cb ─────┘

Details

WOCKY_CONNECTOR_ERROR

#define WOCKY_CONNECTOR_ERROR (wocky_connector_error_quark ())

Get access to the error quark of the connector.


struct WockyConnectorClass

struct WockyConnectorClass {
};

The class of a WockyConnector.


enum WockyConnectorError

typedef enum {
  WOCKY_CONNECTOR_ERROR_UNKNOWN,
  WOCKY_CONNECTOR_ERROR_IN_PROGRESS,
  WOCKY_CONNECTOR_ERROR_BAD_JID,
  WOCKY_CONNECTOR_ERROR_NON_XMPP_V1_SERVER,
  WOCKY_CONNECTOR_ERROR_BAD_FEATURES,
  WOCKY_CONNECTOR_ERROR_TLS_UNAVAILABLE,
  WOCKY_CONNECTOR_ERROR_TLS_REFUSED,
  WOCKY_CONNECTOR_ERROR_TLS_SESSION_FAILED,
  WOCKY_CONNECTOR_ERROR_BIND_UNAVAILABLE,
  WOCKY_CONNECTOR_ERROR_BIND_FAILED,
  WOCKY_CONNECTOR_ERROR_BIND_INVALID,
  WOCKY_CONNECTOR_ERROR_BIND_DENIED,
  WOCKY_CONNECTOR_ERROR_BIND_CONFLICT,
  WOCKY_CONNECTOR_ERROR_BIND_REJECTED,
  WOCKY_CONNECTOR_ERROR_SESSION_FAILED,
  WOCKY_CONNECTOR_ERROR_SESSION_DENIED,
  WOCKY_CONNECTOR_ERROR_SESSION_CONFLICT,
  WOCKY_CONNECTOR_ERROR_SESSION_REJECTED,
  WOCKY_CONNECTOR_ERROR_INSECURE,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_FAILED,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_UNAVAILABLE,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_UNSUPPORTED,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_EMPTY,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_CONFLICT,
  WOCKY_CONNECTOR_ERROR_REGISTRATION_REJECTED,
  WOCKY_CONNECTOR_ERROR_UNREGISTER_FAILED,
  WOCKY_CONNECTOR_ERROR_UNREGISTER_DENIED,
} WockyConnectorError;

The WockyConnector specific errors that can occur while connecting.

WOCKY_CONNECTOR_ERROR_UNKNOWN

Unexpected error condition

WOCKY_CONNECTOR_ERROR_IN_PROGRESS

Connection already underway

WOCKY_CONNECTOR_ERROR_BAD_JID

JID is invalid

WOCKY_CONNECTOR_ERROR_NON_XMPP_V1_SERVER

XMPP version < 1

WOCKY_CONNECTOR_ERROR_BAD_FEATURES

Feature stanza invalid

WOCKY_CONNECTOR_ERROR_TLS_UNAVAILABLE

TLS unavailable

WOCKY_CONNECTOR_ERROR_TLS_REFUSED

TLS refused by server

WOCKY_CONNECTOR_ERROR_TLS_SESSION_FAILED

TLS handshake failed

WOCKY_CONNECTOR_ERROR_BIND_UNAVAILABLE

Bind not available

WOCKY_CONNECTOR_ERROR_BIND_FAILED

Bind failed

WOCKY_CONNECTOR_ERROR_BIND_INVALID

Bind args invalid

WOCKY_CONNECTOR_ERROR_BIND_DENIED

Bind not allowed

WOCKY_CONNECTOR_ERROR_BIND_CONFLICT

Bind resource in use

WOCKY_CONNECTOR_ERROR_BIND_REJECTED

Bind error (generic)

WOCKY_CONNECTOR_ERROR_SESSION_FAILED

Session failed

WOCKY_CONNECTOR_ERROR_SESSION_DENIED

Session refused by server

WOCKY_CONNECTOR_ERROR_SESSION_CONFLICT

Session not allowed

WOCKY_CONNECTOR_ERROR_SESSION_REJECTED

Session error

WOCKY_CONNECTOR_ERROR_INSECURE

Insufficent security for requested operation

WOCKY_CONNECTOR_ERROR_REGISTRATION_FAILED

Account registration error

WOCKY_CONNECTOR_ERROR_REGISTRATION_UNAVAILABLE

Account registration not available

WOCKY_CONNECTOR_ERROR_REGISTRATION_UNSUPPORTED

Account registration not implemented

WOCKY_CONNECTOR_ERROR_REGISTRATION_EMPTY

Account registration makes no sense

WOCKY_CONNECTOR_ERROR_REGISTRATION_CONFLICT

Account already registered

WOCKY_CONNECTOR_ERROR_REGISTRATION_REJECTED

Account registration rejected

WOCKY_CONNECTOR_ERROR_UNREGISTER_FAILED

Account cancellation failed

WOCKY_CONNECTOR_ERROR_UNREGISTER_DENIED

Account cancellation refused

wocky_connector_connect_async ()

void                wocky_connector_connect_async       (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);

Connect to the account/server specified by the self. cb should invoke wocky_connector_connect_finish().

self :

a WockyConnector instance.

cancellable :

an GCancellable, or NULL

cb :

a GAsyncReadyCallback to call when the operation completes.

user_data :

a gpointer to pass to the callback.

wocky_connector_connect_finish ()

WockyXmppConnection * wocky_connector_connect_finish    (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         gchar **jid,
                                                         gchar **sid,
                                                         GError **error);

Called by the callback passed to wocky_connector_connect_async().

self :

a WockyConnector instance.

res :

a GAsyncResult (from your wocky_connector_connect_async() callback).

jid :

(NULL to ignore) the user JID from the server is stored here.

sid :

(NULL to ignore) the Session ID is stored here.

error :

(NULL to ignore) the GError (if any) is sored here.

Returns :

a WockyXmppConnection instance (success), or NULL (failure).

wocky_connector_error_quark ()

GQuark              wocky_connector_error_quark         (void);


wocky_connector_new ()

WockyConnector *    wocky_connector_new                 (const gchar *jid,
                                                         const gchar *pass,
                                                         const gchar *resource,
                                                         WockyAuthRegistry *auth_registry,
                                                         WockyTLSHandler *tls_handler);

Connect to the account/server specified by self. To set other WockyConnector properties, use g_object_new() instead.

jid :

a JID (user AT domain).

pass :

the password.

resource :

the resource (sans '/'), or NULL to autogenerate one.

auth_registry :

a WockyAuthRegistry, or NULL

tls_handler :

a WockyTLSHandler, or NULL

Returns :

a WockyConnector instance which can be used to connect to, register or cancel an account

wocky_connector_register_async ()

void                wocky_connector_register_async      (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);

Connect to the account/server specified by self, register (set up) the account there and then log in to it. cb should invoke wocky_connector_register_finish().

self :

a WockyConnector instance.

cancellable :

an GCancellable, or NULL

cb :

a GAsyncReadyCallback to call when the operation completes.

user_data :

a gpointer to pass to the callback cb.

wocky_connector_register_finish ()

WockyXmppConnection * wocky_connector_register_finish   (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         gchar **jid,
                                                         gchar **sid,
                                                         GError **error);

Called by the callback passed to wocky_connector_register_async().

self :

a WockyConnector instance.

res :

a GAsyncResult (from your wocky_connector_register_async() callback).

jid :

(NULL to ignore) the JID in effect after connection is stored here.

sid :

(NULL to ignore) the Session ID after connection is stored here.

error :

(NULL to ignore) the GError (if any) is stored here.

Returns :

a WockyXmppConnection instance (success), or NULL (failure).

wocky_connector_set_auth_registry ()

void                wocky_connector_set_auth_registry   (WockyConnector *self,
                                                         WockyAuthRegistry *registry);


wocky_connector_unregister_async ()

void                wocky_connector_unregister_async    (WockyConnector *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback cb,
                                                         gpointer user_data);

Connect to the account/server specified by self, and unregister (cancel) the account there. cb should invoke wocky_connector_unregister_finish().

self :

a WockyConnector instance.

cancellable :

an GCancellable, or NULL

cb :

a GAsyncReadyCallback to call when the operation completes.

user_data :

a gpointer to pass to the callback cb.

wocky_connector_unregister_finish ()

gboolean            wocky_connector_unregister_finish   (WockyConnector *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Called by the callback passed to wocky_connector_unregister_async().

self :

a WockyConnector instance.

res :

a GAsyncResult (from the wocky_connector_unregister_async() callback).

error :

(NULL to ignore) the GError (if any) is stored here.

Returns :

a gboolean value TRUE (success), or FALSE (failure).