SoupAuth 3 LIBSOUP Library
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;

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_new_from_header_list

### 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_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_get_realm

### 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_authenticate

### 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_is_authenticated

### 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_authorization

### 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_get_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()`

soup_auth_free_protection_space

## See Also

SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM