WockyConnector

## WockyConnector WockyConnector — Low-level XMPP connection generator. |

## Synopsis

    #include <wocky/wocky-connector.h>

                        WockyConnector;
                        WockyConnectorClass;
                        WockyConnectorPrivate;
    enum                WockyConnectorError;
    GQuark              wocky_connector_error_quark         (void);
    #define             WOCKY_CONNECTOR_ERROR
    WockyXmppConnection * wocky_connector_connect_finish    (WockyConnector *self,
                                                             GAsyncResult *res,
                                                             gchar **jid,
                                                             gchar **sid,
                                                             GError **error);
    WockyXmppConnection * wocky_connector_register_finish   (WockyConnector *self,
                                                             GAsyncResult *res,
                                                             gchar **jid,
                                                             gchar **sid,
                                                             GError **error);
    void                wocky_connector_connect_async       (WockyConnector *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback cb,
                                                             gpointer user_data);
    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);
    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);
    void                wocky_connector_set_auth_registry   (WockyConnector *self,
                                                             WockyAuthRegistry *registry);

## Object Hierarchy

      GObject
       +----WockyConnector

## Properties

      "auth-registry"            WockyAuthRegistry*    : Read / Write / Construct Only
      "email"                    gchar*                : Read / Write
      "encrypted-plain-auth-ok"  gboolean              : Read / Write / Construct
      "features"                 WockyStanza*          : Read
      "identity"                 gchar*                : Read
      "jid"                      gchar*                : Read / Write
      "legacy"                   gboolean              : Read / Write / Construct
      "old-ssl"                  gboolean              : Read / Write / Construct
      "password"                 gchar*                : Read / Write
      "plaintext-auth-allowed"   gboolean              : Read / Write / Construct
      "resource"                 gchar*                : Read / Write / Construct Only
      "session-id"               gchar*                : Read
      "tls-handler"              WockyTLSHandler*      : Read / Write / Construct Only
      "tls-required"             gboolean              : Read / Write / Construct
      "xmpp-port"                guint                 : Read / Write / Construct
      "xmpp-server"              gchar*                : Read / Write

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

## Details

### WockyConnector

    typedef struct _WockyConnector WockyConnector;

### WockyConnectorClass

    typedef struct {
    } WockyConnectorClass;

The class of a WockyConnector.

### WockyConnectorPrivate

    typedef struct _WockyConnectorPrivate WockyConnectorPrivate;

### 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_error_quark ()

    GQuark              wocky_connector_error_quark         (void);

Returns : |

### WOCKY_CONNECTOR_ERROR

    #define WOCKY_CONNECTOR_ERROR (wocky_connector_error_quark ())

Get access to the error quark of the connector.

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

### wocky_connector_set_auth_registry ()

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

`self` : |
`registry` : |

## Property Details

### The `"auth-registry"` property

      "auth-registry"            WockyAuthRegistry*    : Read / Write / Construct Only

An authentication registry that holds handlers for different authentication mechanisms, arbitrates mechanism selection and relays challenges and responses between the handlers and the connection.

### The `"email"` property

      "email"                    gchar*                : Read / Write

The XMPP account's email address (optional, MAY be required by the server if we are registering an account, not required otherwise).

Default value: NULL

### The `"encrypted-plain-auth-ok"` property

      "encrypted-plain-auth-ok"  gboolean              : Read / Write / Construct

Whether PLAINTEXT auth is ok when encrypted.

Default value: TRUE

### The `"features"` property

      "features"                 WockyStanza*          : Read

A WockyStanza instance, the last WockyStanza instance received by the connector during the connection procedure (there may be several, the most recent one always being the one we should refer to).

### The `"identity"` property

      "identity"                 gchar*                : Read

JID + resource (a AT b SLASH c) that is in effect _after_ a successful resource binding operation. This is NOT guaranteed to be related to the JID specified in the original "jid" property. The resource, in particular, is often different, and with gtalk the domain is often different.

Default value: NULL

### The `"jid"` property

      "jid"                      gchar*                : Read / Write

The XMPP account's JID (with or without a /resource).

Default value: NULL

### The `"legacy"` property

      "legacy"                   gboolean              : Read / Write / Construct

Whether to attempt old-style (non-SASL) jabber auth.

Default value: FALSE

### The `"old-ssl"` property

      "old-ssl"                  gboolean              : Read / Write / Construct

Whether to use old-style SSL-at-connect-time encryption rather than the more modern STARTTLS approach.

Default value: FALSE

### The `"password"` property

      "password"                 gchar*                : Read / Write

XMPP Account password.

Default value: NULL

### The `"plaintext-auth-allowed"` property

      "plaintext-auth-allowed"   gboolean              : Read / Write / Construct

Whether auth info can be sent in the clear (eg PLAINTEXT auth). This is independent of any encryption (TLS, SSL) that has been negotiated.

Default value: FALSE

### The `"resource"` property

      "resource"                 gchar*                : Read / Write / Construct Only

The resource (sans '/') for this connection. Will be generated automatically if not set. May be altered by the server anyway upon successful binding.

Default value: NULL

### The `"session-id"` property

      "session-id"               gchar*                : Read

The Session ID supplied by the server upon successfully connecting. May be useful later on as some XEPs suggest this value should be used at various stages as part of a hash or as an ID.

Default value: NULL

### The `"tls-handler"` property

      "tls-handler"              WockyTLSHandler*      : Read / Write / Construct Only

A TLS handler that carries out the interactive verification of the TLS certitificates provided by the server.

### The `"tls-required"` property

      "tls-required"             gboolean              : Read / Write / Construct

Whether we require successful tls/ssl negotiation to continue.

Default value: TRUE

### The `"xmpp-port"` property

      "xmpp-port"                guint                 : Read / Write / Construct

Optional XMPP connect port. Any DNS SRV record will be ignored if this is set. (So the host will be either the WockyConnector:xmpp-server property or the domain part of the JID, in descending order of preference)

Allowed values: <= 65535

Default value: 0

### The `"xmpp-server"` property

      "xmpp-server"              gchar*                : Read / Write

Optional XMPP connect server. Any DNS SRV record and the host specified in "jid" will be ignored if this is set. May be a hostname (fully qualified or otherwise), a dotted quad or an ipv6 address.

Default value: NULL