manpagez: man pages & more
html files: libsoup
Home | html | info | man

SoupAuth

SoupAuth — HTTP client-side authentication support

Synopsis

#include <libsoup/soup.h>

                    SoupAuth;
SoupAuth *          soup_auth_new                       (GType type,
                                                         SoupMessage *msg,
                                                         const char *auth_header);
gboolean            soup_auth_update                    (SoupAuth *auth,
                                                         SoupMessage *msg,
                                                         const char *auth_header);

gboolean            soup_auth_is_for_proxy              (SoupAuth *auth);
const char *        soup_auth_get_scheme_name           (SoupAuth *auth);
const char *        soup_auth_get_host                  (SoupAuth *auth);
const char *        soup_auth_get_realm                 (SoupAuth *auth);
char *              soup_auth_get_info                  (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,
                                                         SoupURI *source_uri);
void                soup_auth_free_protection_space     (SoupAuth *auth,
                                                         GSList *space);

#define             SOUP_AUTH_SCHEME_NAME
#define             SOUP_AUTH_REALM
#define             SOUP_AUTH_HOST
#define             SOUP_AUTH_IS_FOR_PROXY
#define             SOUP_AUTH_IS_AUTHENTICATED

Object Hierarchy

  GObject
   +----SoupAuth

Properties

  "host"                     gchar*                : Read / Write / Construct Only
  "is-authenticated"         gboolean              : Read
  "is-for-proxy"             gboolean              : Read / Write / Construct Only
  "realm"                    gchar*                : Read / Write / Construct Only
  "scheme-name"              gchar*                : Read

Signals

  "save-password"                                  : Run First

Description

SoupAuth objects store the authentication data associated with a given bit of web space. They are created 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, but applications never need to be aware of the specific subclasses being used.


soup_auth_new ()

SoupAuth *          soup_auth_new                       (GType type,
                                                         SoupMessage *msg,
                                                         const char *auth_header);

Creates a new SoupAuth of type type with the information from msg and auth_header.

This is called by SoupSession; you will normally not create auths yourself.

type :

the type of auth to create (a subtype of SoupAuth)

msg :

the SoupMessage the auth is being created for

auth_header :

the WWW-Authenticate/Proxy-Authenticate header

Returns :

the new SoupAuth, or NULL if it could not be created

soup_auth_update ()

gboolean            soup_auth_update                    (SoupAuth *auth,
                                                         SoupMessage *msg,
                                                         const char *auth_header);

Updates auth with the information from msg and auth_header, possibly un-authenticating it. As with soup_auth_new(), this is normally only used by SoupSession.

auth :

a SoupAuth

msg :

the SoupMessage auth is being updated for

auth_header :

the WWW-Authenticate/Proxy-Authenticate header

Returns :

TRUE if auth is still a valid (but potentially unauthenticated) SoupAuth. FALSE if something about auth_params could not be parsed or incorporated into auth at all.

soup_auth_is_for_proxy ()

gboolean            soup_auth_is_for_proxy              (SoupAuth *auth);

Tests whether or not auth is associated with a proxy server rather than an "origin" server.

auth :

a SoupAuth

Returns :

TRUE or FALSE

soup_auth_get_scheme_name ()

const char *        soup_auth_get_scheme_name           (SoupAuth *auth);

Returns auth's scheme name. (Eg, "Basic", "Digest", or "NTLM")

auth :

a SoupAuth

Returns :

the scheme name

soup_auth_get_host ()

const char *        soup_auth_get_host                  (SoupAuth *auth);

Returns the host that auth is associated with.

auth :

a SoupAuth

Returns :

the hostname

soup_auth_get_realm ()

const char *        soup_auth_get_realm                 (SoupAuth *auth);

Returns auth's realm. This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)

auth :

a SoupAuth

Returns :

the realm name

soup_auth_get_info ()

char *              soup_auth_get_info                  (SoupAuth *auth);

Gets an opaque identifier for auth, for use as a hash key or the like. SoupAuth objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).

auth :

a SoupAuth

Returns :

the identifier

soup_auth_authenticate ()

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

Call this on an auth to authenticate it; normally this will cause the auth's message to be requeued with the new authentication info.

This does not cause the password to be saved to persistent storage; see soup_auth_save_password() for that.

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,
                                                         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 can be freed with soup_auth_free_protection_space(). [element-type utf8][transfer full utf8]

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_SCHEME_NAME

#define SOUP_AUTH_SCHEME_NAME      "scheme-name"

An alias for the "scheme" property. (The authentication scheme name.)


SOUP_AUTH_REALM

#define SOUP_AUTH_REALM            "realm"

An alias for the "realm" property. (The authentication realm.)


SOUP_AUTH_HOST

#define SOUP_AUTH_HOST             "host"

An alias for the "host" property. (The host being authenticated to.)


SOUP_AUTH_IS_FOR_PROXY

#define SOUP_AUTH_IS_FOR_PROXY     "is-for-proxy"

An alias for the "is-for-proxy" property. (Whether or not the auth is for a proxy server.)


SOUP_AUTH_IS_AUTHENTICATED

#define SOUP_AUTH_IS_AUTHENTICATED "is-authenticated"

An alias for the "is-authenticated" property. (Whether or not the auth has been authenticated.)

Property Details

The "host" property

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

Authentication host.

Default value: NULL


The "is-authenticated" property

  "is-authenticated"         gboolean              : Read

Whether or not the auth is authenticated.

Default value: FALSE


The "is-for-proxy" property

  "is-for-proxy"             gboolean              : Read / Write / Construct Only

Whether or not the auth is for a proxy server.

Default value: FALSE


The "realm" property

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

Authentication realm.

Default value: NULL


The "scheme-name" property

  "scheme-name"              gchar*                : Read

Authentication scheme name.

Default value: NULL

Signal Details

The "save-password" signal

void                user_function                      (SoupAuth *auth,
                                                        gchar    *username,
                                                        gchar    *password,
                                                        gpointer  user_data)      : Run First

Emitted to request that the username/password pair be saved. If the session supports password-saving, it will connect to this signal before emitting "authenticate", so that it record the password if requested by the caller.

auth :

the auth

username :

the username to save

password :

the password to save

user_data :

user data set when the signal handler was connected.

Since 2.28

See Also

SoupSession
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.