WockyConnector

WockyConnector — Low-level XMPP connection generator.

Functions

Properties

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

Signals

Types and Values

Object Hierarchy

    GEnum
    ╰── WockyConnectorError
    GObject
    ╰── WockyConnector

Includes

#include <wocky/wocky-connector.h>

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 ─────┘

Functions

wocky_connector_error_quark ()

GQuark
wocky_connector_error_quark (void);

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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);

Types and Values

enum WockyConnectorError

The WockyConnector specific errors that can occur while connecting.

Members

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

 

struct WockyConnectorClass

struct WockyConnectorClass {
};

The class of a WockyConnector.

Property Details

The “auth-registry” property

  “auth-registry”            WockyAuthRegistry *

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

Flags: Read / Write / Construct Only


The “email” property

  “email”                    gchar *

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

Flags: Read / Write

Default value: NULL


The “encrypted-plain-auth-ok” property

  “encrypted-plain-auth-ok”  gboolean

Whether PLAINTEXT auth is ok when encrypted.

Flags: Read / Write / Construct

Default value: TRUE


The “features” property

  “features”                 WockyStanza *

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

Flags: Read


The “identity” property

  “identity”                 gchar *

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.

Flags: Read

Default value: NULL


The “jid” property

  “jid”                      gchar *

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

Flags: Read / Write

Default value: NULL


The “legacy” property

  “legacy”                   gboolean

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

Flags: Read / Write / Construct

Default value: FALSE


The “old-ssl” property

  “old-ssl”                  gboolean

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

Flags: Read / Write / Construct

Default value: FALSE


The “password” property

  “password”                 gchar *

XMPP Account password.

Flags: Read / Write

Default value: NULL


The “plaintext-auth-allowed” property

  “plaintext-auth-allowed”   gboolean

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

Flags: Read / Write / Construct

Default value: FALSE


The “resource” property

  “resource”                 gchar *

The resource (sans '/') for this connection. If NULL or the empty string, Wocky will let the server decide. Even if you specify a particular resource, the server may modify it.

Flags: Read / Write / Construct Only

Default value: NULL


The “session-id” property

  “session-id”               gchar *

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.

Flags: Read

Default value: NULL


The “tls-handler” property

  “tls-handler”              WockyTLSHandler *

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

Flags: Read / Write / Construct Only


The “tls-required” property

  “tls-required”             gboolean

Whether we require successful tls/ssl negotiation to continue.

Flags: Read / Write / Construct

Default value: TRUE


The “xmpp-port” property

  “xmpp-port”                guint

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)

Flags: Read / Write / Construct

Allowed values: <= 65535

Default value: 0


The “xmpp-server” property

  “xmpp-server”              gchar *

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.

Flags: Read / Write

Default value: NULL

Signal Details

The “connection-established” signal

void
user_function (WockyConnector    *connection,
               GSocketConnection *arg1,
               gpointer           user_data)

Emitted as soon as a connection to the remote server has been established. This can be useful if you want to do something unusual to the connection early in its lifetime not supported by the WockyConnector APIs.

As the connection process has only just started and the stream not even opened yet, no data must be sent over connection . This signal is merely intended to set esoteric socket options (such as TCP_NODELAY) on the connection.

Parameters

connection

the GSocketConnection

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last