|  |  |  | Wocky Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#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);
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 ─────┘ | 
#define WOCKY_CONNECTOR_ERROR (wocky_connector_error_quark ())
Get access to the error quark of the connector.
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 | 
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. | 
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). | 
| 
 | ( NULLto ignore) the user JID from the server is stored here. | 
| 
 | ( NULLto ignore) the Session ID is stored here. | 
| 
 | ( NULLto ignore) the GError (if any) is sored here. | 
| Returns : | a WockyXmppConnection instance (success), or NULL(failure). | 
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. | 
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). | 
| 
 | ( NULLto ignore) the JID in effect after connection is stored here. | 
| 
 | ( NULLto ignore) the Session ID after connection is stored here. | 
| 
 | ( NULLto ignore) the GError (if any) is stored here. | 
| Returns : | a WockyXmppConnection instance (success), or NULL(failure). | 
void wocky_connector_set_auth_registry (WockyConnector *self,WockyAuthRegistry *registry);
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). | 
| 
 | ( NULLto ignore) the GError (if any) is stored here. | 
| Returns : | a gboolean value TRUE(success), orFALSE(failure). |