![]() |
![]() |
![]() |
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
);