InfXmppConnection

InfXmppConnection

Functions

Properties

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

Types and Values

Object Hierarchy

    GEnum
    ├── InfXmppConnectionSecurityPolicy
    ╰── InfXmppConnectionSite
    GObject
    ╰── InfXmppConnection

Implemented Interfaces

InfXmppConnection implements InfXmlConnection.

Description

Functions

InfXmppConnectionCrtCallback ()

void
(*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp,
                                 InfCertificateChain *chain,
                                 gpointer user_data);


inf_xmpp_connection_new ()

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.

Parameters

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 NULL.

 

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 NULL.

 

Returns

A new InfXmppConnection.


inf_xmpp_connection_get_tls_enabled ()

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()).

Parameters

xmpp

A InfXmppConnection.

 

Returns

TRUE if TLS is enabled and FALSE otherwise.


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.

Parameters

xmpp

A InfXmppConnection.

 

cb

Function to be called to verify the server certificate, or NULL.

 

user_data

Additional data to pass to the callback function.

 

inf_xmpp_connection_certificate_verify_continue ()

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.

Parameters

xmpp

A InfXmppConnection.

 

inf_xmpp_connection_certificate_verify_cancel ()

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.

Parameters

xmpp

A InfXmppConnection.

 

inf_xmpp_connection_reset_sasl_authentication ()

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.

Parameters

xmpp

A InfXmppConnection.

 

new_context

The new sasl context to set, or NULL.

 

new_mechanisms

Allowed SASL mechanisms to use. Ignored if new_context is NULL.

 

inf_xmpp_connection_retry_sasl_authentication ()

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.

Parameters

xmpp

A InfXmppConnection.

 

error

Location to store error information, if any.

 

Returns

TRUE if auth retry is being performed, FALSE otherwise.


inf_xmpp_connection_set_sasl_error ()

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.

Parameters

xmpp

A InfXmppConnection.

 

error

The SASL error to set.

 

inf_xmpp_connection_get_sasl_error ()

const GError *
inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp);

Gets the SASL error of xmpp . See inf_xmpp_connection_set_sasl_error().

Parameters

xmpp

A InfXmppConnection.

 

Returns

A pointer to a GError object owned by xmpp .

Types and Values

enum InfXmppConnectionSite

Members

INF_XMPP_CONNECTION_SERVER

   

INF_XMPP_CONNECTION_CLIENT

   

enum InfXmppConnectionSecurityPolicy

Members

INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED

   

INF_XMPP_CONNECTION_SECURITY_ONLY_TLS

   

INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_UNSECURED

   

INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS

   

enum InfXmppConnectionError

Members

INF_XMPP_CONNECTION_ERROR_TLS_UNSUPPORTED

   

INF_XMPP_CONNECTION_ERROR_TLS_REQUIRED

   

INF_XMPP_CONNECTION_ERROR_TLS_FAILURE

   

INF_XMPP_CONNECTION_ERROR_NO_CERTIFICATE_PROVIDED

   

INF_XMPP_CONNECTION_ERROR_CERTIFICATE_NOT_TRUSTED

   

INF_XMPP_CONNECTION_ERROR_AUTHENTICATION_UNSUPPORTED

   

INF_XMPP_CONNECTION_ERROR_NO_SUITABLE_MECHANISM

   

INF_XMPP_CONNECTION_ERROR_FAILED

   

enum InfXmppConnectionStreamError

Members

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

   

enum InfXmppConnectionAuthError

Members

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

   

struct InfXmppConnection

struct InfXmppConnection;


struct InfXmppConnectionClass

struct InfXmppConnectionClass {
  GObjectClass parent_class;
};

Property Details

The “credentials” property

  “credentials”              InfCertificateCredentials *

The certificate credentials for GnuTLS.

Flags: Read / Write / Construct Only


The “local-hostname” property

  “local-hostname”           gchar *

The hostname of the local host.

Flags: Read / Write / Construct Only

Default value: NULL


The “remote-hostname” property

  “remote-hostname”          gchar *

The hostname of the remote host.

Flags: Read / Write / Construct Only

Default value: NULL


The “sasl-context” property

  “sasl-context”             InfSaslContext *

The SASL context used for authentication.

Flags: Read / Write / Construct Only


The “sasl-mechanisms” property

  “sasl-mechanisms”          gchar *

Whitespace separated list of SASL mechanisms to accept/offer.

Flags: Read / Write / Construct Only

Default value: NULL


The “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


The “site” property

  “site”                     InfXmppConnectionSite

Site of the connection (client or server).

Flags: Read / Write / Construct Only

Default value: INF_XMPP_CONNECTION_CLIENT


The “tcp-connection” property

  “tcp-connection”           InfTcpConnection *

Underlaying TCP connection.

Flags: Read / Write / Construct Only


The “tls-enabled” property

  “tls-enabled”              gboolean

Whether TLS is enabled for the connection or not.

Flags: Read

Default value: FALSE