Channel Authentication interfaces

Channel Authentication interfaces — client-side wrappers for authentication channels

Synopsis

#include <telepathy-glib/channel.h>

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_abort_sasl
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Reason,
                                                         const gchar *in_Debug_Message,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_abort_sasl callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_accept_sasl
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_accept_sasl callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_respond
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Response_Data,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_respond callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_start_mechanism
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Mechanism,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_start_mechanism_with_data
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Mechanism,
                                                         const GArray *in_Initial_Data,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism_with_data callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_sasl_authentication_callback_for_abort_sasl)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_sasl_authentication_callback_for_accept_sasl)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_sasl_authentication_callback_for_respond)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism_with_data)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_interface_sasl_authentication_connect_to_new_challenge
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_sasl_authentication_signal_callback_new_challenge callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_channel_interface_sasl_authentication_connect_to_sasl_status_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_sasl_authentication_signal_callback_sasl_status_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Description

The ServerAuthentication channel type represents a request for client/UI processes to carry out authentication with a server.

Details

tp_cli_channel_interface_sasl_authentication_call_abort_sasl ()

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_abort_sasl
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Reason,
                                                         const gchar *in_Debug_Message,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_abort_sasl callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AbortSASL method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Abort the current authentication try.</p> <p>If the current status is SASL_Status_Server_Failed or SASL_Status_Client_Failed, this method returns successfully, but has no further effect. If the current status is SASL_Status_Succeeded or SASL_Status_Client_Accepted then NotAvailable is raised. Otherwise, it changes the channel's state to SASL_Status_Client_Failed, with an appropriate error name and reason code.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Reason :

Used to pass an 'in' argument: Reason for abort. (TpSASLAbortReason)

in_Debug_Message :

Used to pass an 'in' argument: Debug message for abort.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_sasl_authentication_call_accept_sasl ()

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_accept_sasl
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_accept_sasl callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AcceptSASL method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If the channel's status is SASL_Status_Server_Succeeded, this method confirms successful authentication and advances the status of the channel to SASL_Status_Succeeded.</p> <p>If the channel's status is SASL_Status_In_Progress, calling this method indicates that the last <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact additional data sent after a successful SASL negotiation, and declares that from the client's point of view, authentication was successful. This advances the state of the channel to SASL_Status_Client_Accepted.</p> <p>In mechanisms where the server authenticates itself to the client, calling this method indicates that the client considers this to have been successful. In the case of <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> channels, this means that the connection manager MAY continue to connect, and MAY advance the <tp:dbus-ref namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_sasl_authentication_call_respond ()

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_respond
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Response_Data,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_respond callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Respond method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Send a response to the the last challenge received via <tp:member-ref>NewChallenge</tp:member-ref>.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Response_Data :

Used to pass an 'in' argument: The response data.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_sasl_authentication_call_start_mechanism ()

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_start_mechanism
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Mechanism,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a StartMechanism method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start an authentication try using <var>Mechanism</var>, without sending initial data (an &quot;initial response&quot; as defined in RFC 4422).</p> <tp:rationale> <p>This method is appropriate for mechanisms where the client cannot send anything until it receives a challenge from the server, such as <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> in &quot;initial authentication&quot; mode.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Mechanism :

Used to pass an 'in' argument: The chosen mechanism.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_sasl_authentication_call_start_mechanism_with_data ()

TpProxyPendingCall * tp_cli_channel_interface_sasl_authentication_call_start_mechanism_with_data
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Mechanism,
                                                         const GArray *in_Initial_Data,
                                                         tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism_with_data callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a StartMechanismWithData method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start an authentication try using <var>Mechanism</var>, and send <var>Initial_Data</var> as the &quot;initial response&quot; defined in <a href="http://tools.ietf.org/html/rfc4422section-3.3">RFC 4422 §3.3</a>.</p> <tp:rationale> <p>This method is appropriate for mechanisms where the client may send data first, such as <code>PLAIN</code>, or must send data first, such as <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> in &quot;subsequent authentication&quot; mode.</p> <p>Having two methods allows any mechanism where it makes a difference to distinguish between the absence of an initial response (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte initial response (StartMechanismWithData, with Initial_Data empty).</p> </tp:rationale> <p>If the <tp:member-ref>HasInitialData</tp:member-ref> property is false, this indicates that the underlying protocol does not make it possible to send initial data. In such protocols, this method may only be used for the <code>X-TELEPATHY-</code> pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>), and will fail if used with an ordinary SASL mechanism.</p> <tp:rationale> <p>For instance, the IRC SASL extension implemented in Charybdis and Atheme does not support initial data - the first message in the exchange only carries the mechanism. This is significant if using <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>, which cannot be used in the faster &quot;subsequent authentication&quot; mode on a protocol not supporting initial data.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Mechanism :

Used to pass an 'in' argument: The chosen mechanism.

in_Initial_Data :

Used to pass an 'in' argument: Initial data (an &quot;initial response&quot; in RFC 4422's terminology) to send with the mechanism.

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_interface_sasl_authentication_callback_for_abort_sasl ()

void                (*tp_cli_channel_interface_sasl_authentication_callback_for_abort_sasl)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AbortSASL method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_sasl_authentication_callback_for_accept_sasl ()

void                (*tp_cli_channel_interface_sasl_authentication_callback_for_accept_sasl)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AcceptSASL method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_sasl_authentication_callback_for_respond ()

void                (*tp_cli_channel_interface_sasl_authentication_callback_for_respond)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a Respond method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism ()

void                (*tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a StartMechanism method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism_with_data ()

void                (*tp_cli_channel_interface_sasl_authentication_callback_for_start_mechanism_with_data)
                                                        (TpChannel *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a StartMechanismWithData method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_channel_interface_sasl_authentication_connect_to_new_challenge ()

TpProxySignalConnection * tp_cli_channel_interface_sasl_authentication_connect_to_new_challenge
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_sasl_authentication_signal_callback_new_challenge callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal NewChallenge.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when a new challenge is received from the server, or when a message indicating successful authentication and containing additional data is received from the server.</p> <p>When the channel's handler is ready to proceed, it should respond to the challenge by calling <tp:member-ref>Respond</tp:member-ref>, or respond to the additional data by calling <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p>

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_interface_sasl_authentication_connect_to_sasl_status_changed ()

TpProxySignalConnection * tp_cli_channel_interface_sasl_authentication_connect_to_sasl_status_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_interface_sasl_authentication_signal_callback_sasl_status_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SASLStatusChanged.

Emitted when the status of the channel changes.

proxy :

A TpChannel or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.