## CamelSasl

CamelSasl

## Synopsis

    struct              CamelSasl;
    CamelSasl *         camel_sasl_new                      (const gchar *service_name,
                                                             const gchar *mechanism,
                                                             CamelService *service);
    gboolean            camel_sasl_try_empty_password_sync  (CamelSasl *sasl,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_sasl_try_empty_password       (CamelSasl *sasl,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_sasl_try_empty_password_finish
                                                            (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_sasl_get_authenticated        (CamelSasl *sasl);
    void                camel_sasl_set_authenticated        (CamelSasl *sasl,
                                                             gboolean authenticated);
    const gchar *       camel_sasl_get_mechanism            (CamelSasl *sasl);
    CamelService *      camel_sasl_get_service              (CamelSasl *sasl);
    const gchar *       camel_sasl_get_service_name         (CamelSasl *sasl);
    GByteArray *        camel_sasl_challenge_sync           (CamelSasl *sasl,
                                                             GByteArray *token,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_sasl_challenge                (CamelSasl *sasl,
                                                             GByteArray *token,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GByteArray *        camel_sasl_challenge_finish         (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);
    gchar *             camel_sasl_challenge_base64_sync    (CamelSasl *sasl,
                                                             const gchar *token,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_sasl_challenge_base64         (CamelSasl *sasl,
                                                             const gchar *token,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gchar *             camel_sasl_challenge_base64_finish  (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);
    GList *             camel_sasl_authtype_list            (gboolean include_plain);
    CamelServiceAuthType * camel_sasl_authtype              (const gchar *mechanism);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelSasl
                   +----CamelSaslAnonymous
                   +----CamelSaslCramMd5
                   +----CamelSaslDigestMd5
                   +----CamelSaslGssapi
                   +----CamelSaslLogin
                   +----CamelSaslNTLM
                   +----CamelSaslPlain
                   +----CamelSaslPOPB4SMTP

## Properties

      "authenticated"            gboolean              : Read / Write
      "mechanism"                gchar*                : Read / Write / Construct Only
      "service"                  CamelService*         : Read / Write / Construct Only
      "service-name"             gchar*                : Read / Write / Construct Only

## Description

## Details

### struct CamelSasl

    struct CamelSasl;

### camel_sasl_new ()

    CamelSasl *         camel_sasl_new                      (const gchar *service_name,
                                                             const gchar *mechanism,
                                                             CamelService *service);

`service_name` : | the SASL service name
`mechanism` : | the SASL mechanism
`service` : | the CamelService that will be using this SASL
Returns : | a new CamelSasl object for the given `service_name`, `mechanism`, and `service`, or `NULL` if the mechanism is not supported.

### camel_sasl_try_empty_password_sync ()

    gboolean            camel_sasl_try_empty_password_sync  (CamelSasl *sasl,
                                                             GCancellable *cancellable,
                                                             GError **error);

`sasl` : | a CamelSasl object
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | whether or not `sasl` can attempt to authenticate without a password being provided by the caller. This will be `TRUE` for an authentication method which can attempt to use single-sign-on credentials, but which can fall back to using a provided password so it still has the `need_password` flag set in its description.

Since 3.2

### camel_sasl_try_empty_password ()

    void                camel_sasl_try_empty_password       (CamelSasl *sasl,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously determine whether `sasl` can be used for password-less authentication, for example single-sign-on using system credentials.

When the operation is finished, `callback` will be called. You can then call `camel_sasl_try_empty_password_finish()` to get the result of the operation.

`sasl` : | a CamelSasl
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.2

### camel_sasl_try_empty_password_finish ()

    gboolean            camel_sasl_try_empty_password_finish
                                                            (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_sasl_try_empty_password()`.

`sasl` : | a CamelSasl
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the SASL response. If an error occurred, `error` will also be set.

Since 3.2

### camel_sasl_get_authenticated ()

    gboolean            camel_sasl_get_authenticated        (CamelSasl *sasl);

`sasl` : | a CamelSasl
Returns : | whether or not `sasl` has successfully authenticated the user. This will be `TRUE` after it returns the last needed response. The caller must still pass that information on to the server and verify that it has accepted it.

### camel_sasl_set_authenticated ()

    void                camel_sasl_set_authenticated        (CamelSasl *sasl,
                                                             gboolean authenticated);

`sasl` : | a CamelSasl
`authenticated` : | whether we have successfully authenticated

Since 2.32

### camel_sasl_get_mechanism ()

    const gchar *       camel_sasl_get_mechanism            (CamelSasl *sasl);

`sasl` : | a CamelSasl

Since 2.32

### camel_sasl_get_service ()

    CamelService *      camel_sasl_get_service              (CamelSasl *sasl);

`sasl` : | a CamelSasl

Since 2.32

### camel_sasl_get_service_name ()

    const gchar *       camel_sasl_get_service_name         (CamelSasl *sasl);

`sasl` : | a CamelSasl

Since 2.32

### camel_sasl_challenge_sync ()

    GByteArray *        camel_sasl_challenge_sync           (CamelSasl *sasl,
                                                             GByteArray *token,
                                                             GCancellable *cancellable,
                                                             GError **error);

If `token` is `NULL`, generate the initial SASL message to send to the server. (This will be `NULL` if the client doesn't initiate the exchange.) Otherwise, `token` is a challenge from the server, and the return value is the response.

Free the returned GByteArray with `g_byte_array_free()`.

`sasl` : | a CamelSasl
`token` : | a token, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the SASL response or `NULL`. If an error occurred, `error` will also be set.

### camel_sasl_challenge ()

    void                camel_sasl_challenge                (CamelSasl *sasl,
                                                             GByteArray *token,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

If `token` is `NULL`, asynchronously generate the initial SASL message to send to the server. (This will be `NULL` if the client doesn't initiate the exchange.) Otherwise, `token` is a challenge from the server, and the asynchronous result is the response.

When the operation is finished, `callback` will be called. You can then call `camel_sasl_challenge_finish()` to get the result of the operation.

`sasl` : | a CamelSasl
`token` : | a token, or `NULL`
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.0

### camel_sasl_challenge_finish ()

    GByteArray *        camel_sasl_challenge_finish         (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_sasl_challenge()`. Free the returned GByteArray with `g_byte_array_free()`.

`sasl` : | a CamelSasl
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the SASL response or `NULL`. If an error occurred, `error` will also be set.

Since 3.0

### camel_sasl_challenge_base64_sync ()

    gchar *             camel_sasl_challenge_base64_sync    (CamelSasl *sasl,
                                                             const gchar *token,
                                                             GCancellable *cancellable,
                                                             GError **error);

As with `camel_sasl_challenge_sync()`, but the challenge `token` and the response are both base64-encoded.

`sasl` : | a CamelSasl
`token` : | a base64-encoded token
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the base64-encoded response

Since 3.0

### camel_sasl_challenge_base64 ()

    void                camel_sasl_challenge_base64         (CamelSasl *sasl,
                                                             const gchar *token,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

As with `camel_sasl_challenge()`, but the challenge `token` and the response are both base64-encoded.

When the operation is finished, `callback` will be called. You can then call `camel_store_challenge_base64_finish()` to get the result of the operation.

`sasl` : | a CamelSasl
`token` : | a base64-encoded token
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.0

### camel_sasl_challenge_base64_finish ()

    gchar *             camel_sasl_challenge_base64_finish  (CamelSasl *sasl,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_sasl_challenge_base64()`.

`sasl` : | a CamelSasl
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the base64-encoded response

Since 3.0

### camel_sasl_authtype_list ()

    GList *             camel_sasl_authtype_list            (gboolean include_plain);

`include_plain` : | whether or not to include the PLAIN mechanism
Returns : | a GList of SASL-supported authtypes. The caller must free the list, but not the contents.

### camel_sasl_authtype ()

    CamelServiceAuthType * camel_sasl_authtype              (const gchar *mechanism);

`mechanism` : | the SASL mechanism to get an authtype for
Returns : | a CamelServiceAuthType for the given mechanism, if it is supported.

## Property Details

### The `"authenticated"` property

      "authenticated"            gboolean              : Read / Write

Default value: FALSE

### The `"mechanism"` property

      "mechanism"                gchar*                : Read / Write / Construct Only

Default value: NULL

### The `"service"` property

      "service"                  CamelService*         : Read / Write / Construct Only

### The `"service-name"` property

      "service-name"             gchar*                : Read / Write / Construct Only

Default value: NULL