| Wocky Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#include <wocky/wocky-connector.h> enum WockyConnectorError; GQuark wocky_connector_error_quark (void); #define WOCKY_CONNECTOR_ERROR struct WockyConnectorClass; 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);
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 ─────┘ |
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.
| Unexpected error condition | |
| Connection already underway | |
| JID is invalid | |
| XMPP version < 1 | |
| Feature stanza invalid | |
| TLS unavailable | |
| TLS refused by server | |
| TLS handshake failed | |
| Bind not available | |
| Bind failed | |
| Bind args invalid | |
| Bind not allowed | |
| Bind resource in use | |
| Bind error (generic) | |
| Session failed | |
| Session refused by server | |
| Session not allowed | |
| Session error | |
| Insufficent security for requested operation | |
| Account registration error | |
| Account registration not available | |
| Account registration not implemented | |
| Account registration makes no sense | |
| Account already registered | |
| Account registration rejected | |
| Account cancellation failed | |
| Account cancellation refused |
#define WOCKY_CONNECTOR_ERROR (wocky_connector_error_quark ())
Get access to the error quark of the connector.
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().
|
a WockyConnector instance. |
|
a GAsyncResult (from your wocky_connector_connect_async() callback). |
|
(NULL to ignore) the user JID from the server is stored here. |
|
(NULL to ignore) the Session ID is stored here. |
|
(NULL to ignore) the GError (if any) is sored here. |
Returns : |
a WockyXmppConnection instance (success), or NULL (failure). |
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().
|
a WockyConnector instance. |
|
a GAsyncResult (from your wocky_connector_register_async() callback). |
|
(NULL to ignore) the JID in effect after connection is stored here. |
|
(NULL to ignore) the Session ID after connection is stored here. |
|
(NULL to ignore) the GError (if any) is stored here. |
Returns : |
a WockyXmppConnection instance (success), or NULL (failure). |
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().
|
a WockyConnector instance. |
|
an GCancellable, or NULL
|
|
a GAsyncReadyCallback to call when the operation completes. |
|
a gpointer to pass to the callback. |
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.
|
a JID (user AT domain). |
|
the password. |
|
the resource (sans '/'), or NULL to autogenerate one. |
|
a WockyAuthRegistry, or NULL
|
|
a WockyTLSHandler, or NULL
|
Returns : |
a WockyConnector instance which can be used to connect to, register or cancel an account |
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().
|
a WockyConnector instance. |
|
an GCancellable, or NULL
|
|
a GAsyncReadyCallback to call when the operation completes. |
|
a gpointer to pass to the callback cb. |
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().
|
a WockyConnector instance. |
|
an GCancellable, or NULL
|
|
a GAsyncReadyCallback to call when the operation completes. |
|
a gpointer to pass to the callback cb. |
gboolean wocky_connector_unregister_finish (WockyConnector *self,GAsyncResult *res,GError **error);
Called by the callback passed to wocky_connector_unregister_async().
|
a WockyConnector instance. |
|
a GAsyncResult (from the wocky_connector_unregister_async() callback). |
|
(NULL to ignore) the GError (if any) is stored here. |
Returns : |
a gboolean value TRUE (success), or FALSE (failure). |
void wocky_connector_set_auth_registry (WockyConnector *self,WockyAuthRegistry *registry);