Top | ![]() |
![]() |
![]() |
![]() |
WockyAuthRegistry * | auth-registry | Read / Write / Construct Only |
gchar * | 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 |
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.
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 |
|
jid |
( |
|
sid |
( |
|
error |
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 |
|
jid |
( |
|
sid |
( |
|
error |
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 |
|
cb |
a GAsyncReadyCallback to call when the operation completes. |
|
user_data |
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.
jid |
a JID (user AT domain). |
|
pass |
the password. |
|
resource |
the resource (sans '/'), or NULL to autogenerate one. |
|
auth_registry |
a WockyAuthRegistry, or |
|
tls_handler |
a WockyTLSHandler, or |
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 |
|
cb |
a GAsyncReadyCallback to call when the operation completes. |
|
user_data |
a gpointer to pass to the callback |
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 |
|
cb |
a GAsyncReadyCallback to call when the operation completes. |
|
user_data |
a gpointer to pass to the callback |
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 |
|
error |
void wocky_connector_set_auth_registry (WockyConnector *self
,WockyAuthRegistry *registry
);
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 |
“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
“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
“encrypted-plain-auth-ok”
property“encrypted-plain-auth-ok” gboolean
Whether PLAINTEXT auth is ok when encrypted.
Flags: Read / Write / Construct
Default value: TRUE
“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
“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
“jid”
property“jid” gchar *
The XMPP account's JID (with or without a /resource).
Flags: Read / Write
Default value: NULL
“legacy”
property“legacy” gboolean
Whether to attempt old-style (non-SASL) jabber auth.
Flags: Read / Write / Construct
Default value: FALSE
“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
“password”
property“password” gchar *
XMPP Account password.
Flags: Read / Write
Default value: NULL
“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
“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
“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
“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
“tls-required”
property“tls-required” gboolean
Whether we require successful tls/ssl negotiation to continue.
Flags: Read / Write / Construct
Default value: TRUE
“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
“connection-established”
signalvoid 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.
Flags: Run Last