Top | ![]() |
![]() |
![]() |
![]() |
void | (*InfXmppConnectionCrtCallback) () |
InfXmppConnection * | inf_xmpp_connection_new () |
gboolean | inf_xmpp_connection_get_tls_enabled () |
void | inf_xmpp_connection_set_certificate_callback () |
void | inf_xmpp_connection_certificate_verify_continue () |
void | inf_xmpp_connection_certificate_verify_cancel () |
void | inf_xmpp_connection_reset_sasl_authentication () |
gboolean | inf_xmpp_connection_retry_sasl_authentication () |
void | inf_xmpp_connection_set_sasl_error () |
const GError * | inf_xmpp_connection_get_sasl_error () |
InfCertificateCredentials * | credentials | Read / Write / Construct Only |
gchar * | local-hostname | Read / Write / Construct Only |
gchar * | remote-hostname | Read / Write / Construct Only |
InfSaslContext * | sasl-context | Read / Write / Construct Only |
gchar * | sasl-mechanisms | Read / Write / Construct Only |
InfXmppConnectionSecurityPolicy | security-policy | Read / Write / Construct Only |
InfXmppConnectionSite | site | Read / Write / Construct Only |
InfTcpConnection * | tcp-connection | Read / Write / Construct Only |
gboolean | tls-enabled | Read |
enum | InfXmppConnectionSite |
enum | InfXmppConnectionSecurityPolicy |
enum | InfXmppConnectionError |
enum | InfXmppConnectionStreamError |
enum | InfXmppConnectionAuthError |
struct | InfXmppConnection |
struct | InfXmppConnectionClass |
GEnum ├── InfXmppConnectionSecurityPolicy ╰── InfXmppConnectionSite GObject ╰── InfXmppConnection
void (*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp
,InfCertificateChain *chain
,gpointer user_data
);
InfXmppConnection * inf_xmpp_connection_new (InfTcpConnection *tcp
,InfXmppConnectionSite site
,const gchar *local_hostname
,const gchar *remote_hostname
,InfXmppConnectionSecurityPolicy security_policy
,InfCertificateCredentials *creds
,InfSaslContext *sasl_context
,const gchar *sasl_mechanisms
);
Creates a new InfXmppConnection with tcp
as communication channel. No
attempt is being made to open tcp
, if it is not already open. However,
communication is initiated as soon as tcp
gets into
INF_TCP_CONNECTION_CONNECTED
state, so you might still open it
lateron yourself.
local_hostname
specifies the hostname of the local host, and
remote_hostname
specifies the hostname of the remote host, as known to
the caller. These can be a string representation of the IP address of
tcp
, or a DNS name such as "example.com". local_hostname
can be NULL
in which case the host name as reported by g_get_host_name()
is used.
creds
may be NULL
in which case the connection creates the credentials
as soon as they are required. However, this only works if
site
is INF_XMPP_CONNECTION_CLIENT
or security_policy
is
INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED
(or both, of course). For
server connections creds
must contain a valid server certificate in case
security_policy
is not INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED
.
If sasl_context
is NULL
, InfXmppConnection uses a built-in context
that only supports ANONYMOUS authentication. In sasl_context
's
callback function, the InfXmppConnection for which the authentication
shall be performed can be accessed via the session_data
parameter of
InfSaslContextCallbackFunc.
If sasl_context
is not NULL
, then the sasl_mechanisms
parameter defines
what SASL mechanisms are used. On the server side, these are the mechanisms
offered to the client, and on the client side, these are the accepted
mechanisms (meaning that if a server does not offer any of these, the
connection will be closed). If sasl_context
is NULL
, then this parameter
is ignored. sasl_mechanisms
can be NULL
in which case all available
mechanisms are accepted or offered, respectively.
tcp |
The underlaying TCP connection to use. |
|
site |
Whether this is a XMPP client or server. |
|
local_hostname |
The hostname of the local host, or |
|
remote_hostname |
The hostname of the remote host. |
|
security_policy |
Whether to use (or offer, as a server) TLS. See InfXmppConnectionSecurityPolicy for the meaning of this parameter. |
|
creds |
Certificate credentials used to secure the communication. |
|
sasl_context |
A SASL context used for authentication. |
|
sasl_mechanisms |
A whitespace-separated list of SASL mechanisms to
accept/offer, or |
gboolean
inf_xmpp_connection_get_tls_enabled (InfXmppConnection *xmpp
);
Returns whether TLS encryption is enabled for xmpp
. This returns TRUE
as soon as the TLS handshake is completed but before the server certificate
was verified (see inf_xmpp_connection_set_certificate_callback()
).
void inf_xmpp_connection_set_certificate_callback (InfXmppConnection *xmpp
,InfXmppConnectionCrtCallback cb
,gpointer user_data
);
This function sets a callback that is called when the connection needs to verify the server's certificate. It does not need to respond immediately, but can, for example, show a dialog to a user and continue when the user finished with it.
When the certificate is trusted, then call
inf_xmpp_connection_certificate_verify_continue()
,
otherwise inf_xmpp_connection_certificate_verify_cancel()
. This can happen
in the callback or some time later. The connection process is stopped until
either of these functions is called.
If cb
is NULL
, or this function has not been called before a certificate
needs to be verified, then the certificate is always trusted.
void
inf_xmpp_connection_certificate_verify_continue
(InfXmppConnection *xmpp
);
Call this function when your callback set in
inf_xmpp_connection_set_certificate_callback()
was called and you do trust
the server's certificate. The connection process will then continue.
void
inf_xmpp_connection_certificate_verify_cancel
(InfXmppConnection *xmpp
);
Call this function when your callback set in
inf_xmpp_connection_set_certificate_callback()
was called and you do not
trust the server's certificate. The connection will then be closed with a
corresponding error.
void inf_xmpp_connection_reset_sasl_authentication (InfXmppConnection *xmpp
,InfSaslContext *new_context
,const gchar *new_mechanisms
);
Sets a new SASL context and mechanisms to use for authentication. This does
not have any effect if authentication has already been performed. This can
be useful if a server decides to use a stricter authentication policy and
gets away with its previous SASL context. If new_context
is NULL
, then a
built-in SASL context is used which only accepts anonymous authentication.
If the authentication is currently in progress then it is aborted. The
server sends an INF_XMPP_CONNECTION_AUTH_ERROR_TEMPORARY_AUTH_FAILURE
error to the client with INF_AUTHENTICATION_DETAIL_ERROR_TRY_AGAIN
detail
(see inf_xmpp_connection_get_sasl_error()
).
On the client side, if authentication is in progress, a request to abort
the authentication is sent to the server. The server will then reply with
an INF_XMPP_CONNECTION_AUTH_ERROR_ABORTED
error. In the signal handler of
the “error” signal you should reinitiate the authentication
with inf_xmpp_connection_retry_sasl_authentication()
or the connection will
be closed. It is also possible that the final authentication request has
already been sent, and the server replies with successful authentication
instead. In that case calling this function will have no effect apart from
closing and reopening the connection will use the new context and
mechanisms.
gboolean inf_xmpp_connection_retry_sasl_authentication (InfXmppConnection *xmpp
,GError **error
);
When SASL authentication failed then the “error” signal is emitted with an error from the INF_XMPP_CONNECTION_AUTH_ERROR domain. If the signal handler wants to retry authentication then it should call this function, possibly modifying the “sasl-mechanisms” property before. If this function is not called then the connection will terminate.
The function can fail if the server does not support any of the available
mechanisms given in “sasl-mechanisms”. If so, the function
returns FALSE
and error
is set.
void inf_xmpp_connection_set_sasl_error (InfXmppConnection *xmpp
,const GError *error
);
Sets the SASL error of xmpp
. The SASL error is an additional hint of what
went wrong during authentication. It should be set on the server side
in the gsasl callback checking the user authentication. If on the
client side “error” is emitted with an error from the
INF_XMPP_CONNECTION_AUTH_ERROR domain then
inf_xmpp_connection_get_sasl_error()
can be used to obtain more detailed
error information.
const GError *
inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp
);
Gets the SASL error of xmpp
. See inf_xmpp_connection_set_sasl_error()
.
“credentials”
property“credentials” InfCertificateCredentials *
The certificate credentials for GnuTLS.
Flags: Read / Write / Construct Only
“local-hostname”
property “local-hostname” gchar *
The hostname of the local host.
Flags: Read / Write / Construct Only
Default value: NULL
“remote-hostname”
property “remote-hostname” gchar *
The hostname of the remote host.
Flags: Read / Write / Construct Only
Default value: NULL
“sasl-context”
property“sasl-context” InfSaslContext *
The SASL context used for authentication.
Flags: Read / Write / Construct Only
“sasl-mechanisms”
property “sasl-mechanisms” gchar *
Whitespace separated list of SASL mechanisms to accept/offer.
Flags: Read / Write / Construct Only
Default value: NULL
“security-policy”
property“security-policy” InfXmppConnectionSecurityPolicy
How to choose whether to use (or offer, as a server) TLS.
Flags: Read / Write / Construct Only
Default value: INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS
“site”
property“site” InfXmppConnectionSite
Site of the connection (client or server).
Flags: Read / Write / Construct Only
Default value: INF_XMPP_CONNECTION_CLIENT
“tcp-connection”
property“tcp-connection” InfTcpConnection *
Underlaying TCP connection.
Flags: Read / Write / Construct Only