SoupAuth

## SoupAuth SoupAuth — HTTP Authentication support |

## Synopsis

                SoupAuth;
                SoupAuthBasic;
                SoupAuthDigest;
    SoupAuth*   soup_auth_new_from_header_list  (const GSList *vals);
    const char* soup_auth_get_scheme_name       (SoupAuth *auth);
    const char* soup_auth_get_realm             (SoupAuth *auth);
    void        soup_auth_authenticate          (SoupAuth *auth,
                                                 const char *username,
                                                 const char *password);
    gboolean    soup_auth_is_authenticated      (SoupAuth *auth);
    char*       soup_auth_get_authorization     (SoupAuth *auth,
                                                 SoupMessage *msg);
    GSList*     soup_auth_get_protection_space  (SoupAuth *auth,
                                                 const SoupUri *source_uri);
    void        soup_auth_free_protection_space (SoupAuth *auth,
                                                 GSList *space);

## Object Hierarchy

      GObject
       +----SoupAuth
             +----SoupAuthBasic
             +----SoupAuthDigest

      GObject
       +----SoupAuth
             +----SoupAuthBasic

      GObject
       +----SoupAuth
             +----SoupAuthDigest

## Description

SoupAuth objects store the authentication data associated with a given bit of webspace. They are created and maintained automatically by SoupSession.

## Details

### SoupAuth

    typedef struct _SoupAuth SoupAuth;

The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses. (NTLM authentication, which works quite differently from normal HTTP authentication, is handled by SoupConnectionNTLM.)

### SoupAuthBasic

    typedef struct _SoupAuthBasic SoupAuthBasic;

An object representing Basic HTTP authentication.

### SoupAuthDigest

    typedef struct _SoupAuthDigest SoupAuthDigest;

An object representing Digest HTTP authentication.

### soup_auth_new_from_header_list ()

    SoupAuth*   soup_auth_new_from_header_list  (const GSList *vals);

Creates a SoupAuth value based on the strongest available supported auth type in `vals`.

`vals` : | a list of WWW-Authenticate headers from a server response
Returns : | the new SoupAuth, or `NULL` if none could be created.

### soup_auth_get_scheme_name ()

    const char* soup_auth_get_scheme_name       (SoupAuth *auth);

Returns `auth`'s scheme name. (Eg, "Basic")

`auth` : | a SoupAuth
Returns : | the scheme name

### soup_auth_get_realm ()

    const char* soup_auth_get_realm             (SoupAuth *auth);

Returns `auth`'s realm, if any.

`auth` : | a SoupAuth
Returns : | the realm name

### soup_auth_authenticate ()

    void        soup_auth_authenticate          (SoupAuth *auth,
                                                 const char *username,
                                                 const char *password);

This is called by the session after requesting a username and password from the application. `auth` will take the information and do whatever scheme-specific processing is needed.

`auth` : | a SoupAuth
`username` : | the username provided by the user or client
`password` : | the password provided by the user or client

### soup_auth_is_authenticated ()

    gboolean    soup_auth_is_authenticated      (SoupAuth *auth);

Tests if `auth` has been given a username and password

`auth` : | a SoupAuth
Returns : | `TRUE` if `auth` has been given a username and password

### soup_auth_get_authorization ()

    char*       soup_auth_get_authorization     (SoupAuth *auth,
                                                 SoupMessage *msg);

Generates an appropriate "Authorization" header for `msg`. (The session will only call this if `soup_auth_is_authenticated()` returned `TRUE`.)

`auth` : | a SoupAuth
`msg` : | the SoupMessage to be authorized
Returns : | the "Authorization" header, which must be freed.

### soup_auth_get_protection_space ()

    GSList*     soup_auth_get_protection_space  (SoupAuth *auth,
                                                 const SoupUri *source_uri);

Returns a list of paths on the server which `auth` extends over. (All subdirectories of these paths are also assumed to be part of `auth`'s protection space, unless otherwise discovered not to be.)

`auth` : | a SoupAuth
`source_uri` : | the URI of the request that `auth` was generated in response to.
Returns : | the list of paths, which must be freed with `soup_auth_free_protection_space()`.

### soup_auth_free_protection_space ()

    void        soup_auth_free_protection_space (SoupAuth *auth,
                                                 GSList *space);

Frees `space`.

`auth` : | a SoupAuth
`space` : | the return value from `soup_auth_get_protection_space()`

## See Also

SoupSession, SoupConnectionNTLM