## SoupAuth

SoupAuth — HTTP Authentication support

## Synopsis

    struct      SoupAuth;
    SoupAuth*   soup_auth_new_from_header_list  (const GSList *header);
    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

## Description

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

SoupAuth itself is an abstract class. Specific HTTP Authentication mechanisms are implemented by its subclasses. (NTLM authentication, which works quite differently from normal HTTP authentication, is handled by SoupConnectionNTLM.)

## Details

### struct SoupAuth

    struct SoupAuth;

### soup_auth_new_from_header_list ()

    SoupAuth*   soup_auth_new_from_header_list  (const GSList *header);

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

`header` : |
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` should 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`. (This will only be called if `soup_auth_is_authenticated()` returns `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

SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM