## InfXmppConnection InfXmppConnection |

## Synopsis

    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);

## Object Hierarchy

      GEnum
       +----InfXmppConnectionSite

      GEnum
       +----InfXmppConnectionSecurityPolicy

      GObject
       +----InfXmppConnection

## Implemented Interfaces

InfXmppConnection implements InfXmlConnection.

## Properties

      "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

## Description

## Details

### InfXmppConnectionCrtCallback ()

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

### enum InfXmppConnectionSite

    typedef enum {
      INF_XMPP_CONNECTION_SERVER,
      INF_XMPP_CONNECTION_CLIENT
    } InfXmppConnectionSite;

### enum InfXmppConnectionSecurityPolicy

    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;

### enum InfXmppConnectionError

    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;

### enum InfXmppConnectionStreamError

    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;

### enum InfXmppConnectionAuthError

    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

    typedef struct _InfXmppConnection InfXmppConnection;

### struct InfXmppConnectionClass

    struct InfXmppConnectionClass {
      GObjectClass parent_class;
    };

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

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

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

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

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

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

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

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

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

`xmpp` : | A InfXmppConnection.
Returns : | A pointer to a GError object owned by `xmpp`.

## Property Details

### The `"credentials"` property

      "credentials"              InfCertificateCredentials*  : Read / Write / Construct Only

The certificate credentials for GnuTLS.

### The `"local-hostname"` property

      "local-hostname"           gchar*                : Read / Write / Construct Only

The hostname of the local host.

Default value: NULL

### The `"remote-hostname"` property

      "remote-hostname"          gchar*                : Read / Write / Construct Only

The hostname of the remote host.

Default value: NULL

### The `"sasl-context"` property

      "sasl-context"             InfSaslContext*       : Read / Write / Construct Only

The SASL context used for authentication.

### The `"sasl-mechanisms"` property

      "sasl-mechanisms"          gchar*                : Read / Write / Construct Only

Whitespace separated list of SASL mechanisms to accept/offer.

Default value: NULL

### The `"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

### The `"site"` property

      "site"                     InfXmppConnectionSite  : Read / Write / Construct Only

Site of the connection (client or server).

Default value: INF_XMPP_CONNECTION_CLIENT

### The `"tcp-connection"` property

      "tcp-connection"           InfTcpConnection*     : Read / Write / Construct Only

Underlaying TCP connection.

### The `"tls-enabled"` property

      "tls-enabled"              gboolean              : Read

Whether TLS is enabled for the connection or not.

Default value: FALSE