![]() |
![]() |
![]() |
libinfinity-0.5 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
void (*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp
,InfCertificateChain *chain
,gpointer user_data
); enum InfXmppConnectionSite; enum InfXmppConnectionSecurityPolicy; enum InfXmppConnectionError; enum InfXmppConnectionStreamError; enum InfXmppConnectionAuthError; InfXmppConnection; struct InfXmppConnectionClass; 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
); gboolean inf_xmpp_connection_get_tls_enabled (InfXmppConnection *xmpp
); void inf_xmpp_connection_set_certificate_callback (InfXmppConnection *xmpp
,InfXmppConnectionCrtCallback cb
,gpointer user_data
); void inf_xmpp_connection_certificate_verify_continue (InfXmppConnection *xmpp
); void inf_xmpp_connection_certificate_verify_cancel (InfXmppConnection *xmpp
); void inf_xmpp_connection_reset_sasl_authentication (InfXmppConnection *xmpp
,InfSaslContext *new_context
,const gchar *new_mechanisms
); gboolean inf_xmpp_connection_retry_sasl_authentication (InfXmppConnection *xmpp
,GError **error
); void inf_xmpp_connection_set_sasl_error (InfXmppConnection *xmpp
,const GError *error
); const GError * inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp
);
GEnum +----InfXmppConnectionSite
GEnum +----InfXmppConnectionSecurityPolicy
GObject +----InfXmppConnection
"credentials" InfCertificateCredentials* : Read / Write / Construct Only "local-hostname" gchar* : Read / Write / Construct Only "remote-hostname" gchar* : Read / Write / Construct Only "sasl-context" InfSaslContext* : Read / Write / Construct Only "sasl-mechanisms" gchar* : Read / Write / Construct Only "security-policy" InfXmppConnectionSecurityPolicy : Read / Write / Construct Only "site" InfXmppConnectionSite : Read / Write / Construct Only "tcp-connection" InfTcpConnection* : Read / Write / Construct Only "tls-enabled" gboolean : Read
void (*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp
,InfCertificateChain *chain
,gpointer user_data
);
typedef enum { INF_XMPP_CONNECTION_SERVER, INF_XMPP_CONNECTION_CLIENT } InfXmppConnectionSite;
typedef enum { /* Server: Do not offer TLS. * Client: Only connect if TLS is not required. */ INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED, /* Server: Require TLS. * Client: Only connect if TLS is available. */ INF_XMPP_CONNECTION_SECURITY_ONLY_TLS, /* Server: Offer both. * Client: Use unsecured communication unless TLS is required */ INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_UNSECURED, /* Server: Offer both. * Client: Use TLS-secured communication unless TLS is not available. */ INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS } InfXmppConnectionSecurityPolicy;
typedef enum { /* Server does not support TLS */ INF_XMPP_CONNECTION_ERROR_TLS_UNSUPPORTED, /* The server requires TLS, but we don't want TLS */ INF_XMPP_CONNECTION_ERROR_TLS_REQUIRED, /* Got <failure> as response to <starttls> */ INF_XMPP_CONNECTION_ERROR_TLS_FAILURE, /* The server did not provide a certificate */ INF_XMPP_CONNECTION_ERROR_NO_CERTIFICATE_PROVIDED, /* The server certificate is not trusted */ INF_XMPP_CONNECTION_ERROR_CERTIFICATE_NOT_TRUSTED, /* Server does not provide authentication mechanisms */ INF_XMPP_CONNECTION_ERROR_AUTHENTICATION_UNSUPPORTED, /* Server does not offer a suitable machnism */ INF_XMPP_CONNECTION_ERROR_NO_SUITABLE_MECHANISM, INF_XMPP_CONNECTION_ERROR_FAILED } InfXmppConnectionError;
typedef enum { INF_XMPP_CONNECTION_STREAM_ERROR_BAD_FORMAT, INF_XMPP_CONNECTION_STREAM_ERROR_BAD_NAMESPACE_PREFIX, INF_XMPP_CONNECTION_STREAM_ERROR_CONFLICT, INF_XMPP_CONNECTION_STREAM_ERROR_CONNECTION_TIMEOUT, INF_XMPP_CONNECTION_STREAM_ERROR_HOST_GONE, INF_XMPP_CONNECTION_STREAM_ERROR_HOST_UNKNOWN, INF_XMPP_CONNECTION_STREAM_ERROR_IMPROPER_ADDRESSING, INF_XMPP_CONNECTION_STREAM_ERROR_INTERNAL_SERVER_ERROR, INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_FROM, INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_ID, INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_NAMESPACE, INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_XML, INF_XMPP_CONNECTION_STREAM_ERROR_NOT_AUTHORIZED, INF_XMPP_CONNECTION_STREAM_ERROR_POLICY_VIOLATION, INF_XMPP_CONNECTION_STREAM_ERROR_REMOTE_CONNECTION_FAILED, INF_XMPP_CONNECTION_STREAM_ERROR_RESOURCE_CONSTRAINT, INF_XMPP_CONNECTION_STREAM_ERROR_RESTRICTED_XML, INF_XMPP_CONNECTION_STREAM_ERROR_SEE_OTHER_HOST, INF_XMPP_CONNECTION_STREAM_ERROR_SYSTEM_SHUTDOWN, INF_XMPP_CONNECTION_STREAM_ERROR_UNDEFINED_CONDITION, INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_ENCODING, INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_STANZA_TYPE, INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_VERSION, INF_XMPP_CONNECTION_STREAM_ERROR_XML_NOT_WELL_FORMED, INF_XMPP_CONNECTION_STREAM_ERROR_FAILED } InfXmppConnectionStreamError;
typedef enum { INF_XMPP_CONNECTION_AUTH_ERROR_ABORTED, INF_XMPP_CONNECTION_AUTH_ERROR_INCORRECT_ENCODING, INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_AUTHZID, INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_MECHANISM, INF_XMPP_CONNECTION_AUTH_ERROR_MECHANISM_TOO_WEAK, INF_XMPP_CONNECTION_AUTH_ERROR_NOT_AUTHORIZED, INF_XMPP_CONNECTION_AUTH_ERROR_TEMPORARY_AUTH_FAILURE, INF_XMPP_CONNECTION_AUTH_ERROR_FAILED } InfXmppConnectionAuthError;
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.
|
The underlaying TCP connection to use. |
|
Whether this is a XMPP client or server. |
|
The hostname of the local host, or NULL . |
|
The hostname of the remote host. |
|
Whether to use (or offer, as a server) TLS. See InfXmppConnectionSecurityPolicy for the meaning of this parameter. |
|
Certificate credentials used to secure the communication. |
|
A SASL context used for authentication. |
|
A whitespace-separated list of SASL mechanisms to
accept/offer, or NULL . |
Returns : |
A new InfXmppConnection. |
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()
).
|
A InfXmppConnection. |
Returns : |
TRUE if TLS is enabled and FALSE otherwise. |
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.
|
A InfXmppConnection. |
|
Function to be called to verify the server certificate, or NULL . |
|
Additional data to pass to the callback function. |
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.
|
A InfXmppConnection. |
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.
|
A InfXmppConnection. |
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.
|
A InfXmppConnection. |
|
The new sasl context to set, or NULL . |
|
Allowed SASL mechanisms to use. Ignored if new_context
is NULL . |
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.
|
A InfXmppConnection. |
|
Location to store error information, if any. |
Returns : |
TRUE if auth retry is being performed, FALSE otherwise. |
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.
|
A InfXmppConnection. |
|
The SASL error to set. |
const GError * inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp
);
Gets the SASL error of xmpp
. See inf_xmpp_connection_set_sasl_error()
.
|
A InfXmppConnection. |
Returns : |
A pointer to a GError object owned by xmpp . |
"credentials"
property"credentials" InfCertificateCredentials* : Read / Write / Construct Only
The certificate credentials for GnuTLS.
"local-hostname"
property"local-hostname" gchar* : Read / Write / Construct Only
The hostname of the local host.
Default value: NULL
"remote-hostname"
property"remote-hostname" gchar* : Read / Write / Construct Only
The hostname of the remote host.
Default value: NULL
"sasl-context"
property"sasl-context" InfSaslContext* : Read / Write / Construct Only
The SASL context used for authentication.
"sasl-mechanisms"
property"sasl-mechanisms" gchar* : Read / Write / Construct Only
Whitespace separated list of SASL mechanisms to accept/offer.
Default value: NULL
"security-policy"
property"security-policy" InfXmppConnectionSecurityPolicy : Read / Write / Construct Only
How to choose whether to use (or offer, as a server) TLS.
Default value: INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS
"site"
property"site" InfXmppConnectionSite : Read / Write / Construct Only
Site of the connection (client or server).
Default value: INF_XMPP_CONNECTION_CLIENT
"tcp-connection"
property"tcp-connection" InfTcpConnection* : Read / Write / Construct Only
Underlaying TCP connection.
"tls-enabled"
property"tls-enabled" gboolean : Read
Whether TLS is enabled for the connection or not.
Default value: FALSE