WockyConnector

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