![]() |
![]() |
![]() |
libinfinity-0.3 Reference Manual | ![]() |
---|---|---|---|---|
void (*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp, InfCertificateChain *chain, gpointer user_data); enum InfXmppConnectionSite; enum InfXmppConnectionSecurityPolicy; enum InfXmppConnectionError; enum InfXmppConnectionStreamError; enum InfXmppConnectionAuthError; InfXmppConnection; InfXmppConnectionClass; InfXmppConnection* inf_xmpp_connection_new (InfTcpConnection *tcp, InfXmppConnectionSite site, const gchar *local_hostname, const gchar *remote_hostname, InfXmppConnectionSecurityPolicy security_policy, gnutls_certificate_credentials_t cred, Gsasl *sasl_context, const gchar *sasl_mechanisms); 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);
"credentials" gpointer : Read / Write / Construct Only "local-hostname" gchar* : Read / Write / Construct Only "remote-hostname" gchar* : Read / Write / Construct Only "sasl-context" gpointer : 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
void (*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp, InfCertificateChain *chain, gpointer user_data);
|
|
|
|
|
typedef enum _InfXmppConnectionSite { INF_XMPP_CONNECTION_SERVER, INF_XMPP_CONNECTION_CLIENT } InfXmppConnectionSite;
typedef enum _InfXmppConnectionSecurityPolicy { /* 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 _InfXmppConnectionError { /* 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 _InfXmppConnectionStreamError { 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 _InfXmppConnectionAuthError { 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, gnutls_certificate_credentials_t cred, Gsasl *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.
cred
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 cred
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 the sasl_context
's
callback function, the InfXmppConnection for which the authentication
shall be performed can be retrieved with gsasl_session_hook_get()
.
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. |
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. |
"credentials"
property"credentials" gpointer : 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" gpointer : Read / Write / Construct Only
The GnuSASL 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.