GI.Soup.Objects.Auth

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.

Auth objects store the authentication data associated with a given bit of web space. They are created automatically by [classsession].

Exported types

newtype Auth

Memory-managed wrapper type.

Constructors

Auth (ManagedPtr Auth)

Instances

Eq Auth

Defined in GI.Soup.Objects.Auth

Methods

(==) :: Auth -> Auth -> Bool

(/=) :: Auth -> Auth -> Bool

GObject Auth

Defined in GI.Soup.Objects.Auth

ManagedPtrNewtype Auth

Defined in GI.Soup.Objects.Auth

Methods

toManagedPtr :: Auth -> ManagedPtr Auth

TypedObject Auth

Defined in GI.Soup.Objects.Auth

Methods

glibType :: IO GType

HasParentTypes Auth

Defined in GI.Soup.Objects.Auth

IsGValue (Maybe Auth)

Convert Auth to and from GValue. See toGValue and fromGValue.

Defined in GI.Soup.Objects.Auth

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Auth -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Auth)

type ParentTypes Auth

Defined in GI.Soup.Objects.Auth

type ParentTypes Auth = '[Object]

class (GObject o, IsDescendantOf Auth o) => IsAuth o

Type class for types which can be safely cast to Auth, for instance with toAuth.

Instances

(GObject o, IsDescendantOf Auth o) => IsAuth o

Defined in GI.Soup.Objects.Auth

toAuth :: (MonadIO m, IsAuth o) => o -> m Auth

Cast to Auth, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

authenticate, bindProperty, bindPropertyFull, canAuthenticate, cancel, forceFloating, freezeNotify, getv, isAuthenticated, isCancelled, isFloating, isForProxy, isReady, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, update, watchClosure.

Getters

getAuthority, getAuthorization, getData, getInfo, getProperty, getProtectionSpace, getQdata, getRealm, getSchemeName.

Setters

setData, setDataFull, setProperty.

authenticate

authAuthenticate

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> Text

username: the username provided by the user or client

-> Text

password: the password provided by the user or client

-> m ()

Call this on an auth to authenticate it.

Normally this will cause the auth's message to be requeued with the new authentication info.

canAuthenticate

authCanAuthenticate

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Bool

Returns: True if auth is able to accept credentials.

Tests if auth is able to authenticate by providing credentials to the [methodauth.authenticate].

cancel

authCancel

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m ()

Call this on an auth to cancel it.

You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided ([methodauth.authenticate] is not called). The Auth will be cancelled on dispose if it hans't been authenticated.

getAuthority

authGetAuthority

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Text

Returns: the authority

Returns the authority (host:port) that auth is associated with.

getAuthorization

authGetAuthorization

Arguments

:: (HasCallStack, MonadIO m, IsAuth a, IsMessage b)

=> a

auth: a Auth

-> b

msg: the Message to be authorized

-> m Text

Returns: the "Authorization" header, which must be freed.

Generates an appropriate "Authorization" header for msg.

(The session will only call this if [methodauth.is_authenticated] returned True.)

getInfo

authGetInfo

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Text

Returns: the identifier

Gets an opaque identifier for auth.

The identifier can be used as a hash key or the like. Auth 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).

getProtectionSpace

authGetProtectionSpace

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> Uri

sourceUri: the URI of the request that auth was generated in response to.

-> m [Text]

Returns: the list of paths, which can be freed with [methodauth.free_protection_space].

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.)

getRealm

authGetRealm

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Text

Returns: the realm name

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.)

getSchemeName

authGetSchemeName

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Text

Returns: the scheme name

soup_auth_get_scheme_name: (attributes org.gtk.Method.get_property=scheme-name) Returns auth's scheme name. (Eg, "Basic", "Digest", or "NTLM")

isAuthenticated

authIsAuthenticated

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Bool

Returns: True if auth has been given a username and password

Tests if auth has been given a username and password.

isCancelled

authIsCancelled

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Bool

Returns: True if auth has been cancelled

Tests if auth has been cancelled

isForProxy

authIsForProxy

Arguments

:: (HasCallStack, MonadIO m, IsAuth a)

=> a

auth: a Auth

-> m Bool

Returns: True or False

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

isReady

authIsReady

Arguments

:: (HasCallStack, MonadIO m, IsAuth a, IsMessage b)

=> a

auth: a Auth

-> b

msg: a Message

-> m Bool

Returns: True if auth is ready to make a request with.

Tests if auth is ready to make a request for msg with.

For most auths, this is equivalent to [methodauth.is_authenticated], but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

new

authNew

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)

=> GType

type: the type of auth to create (a subtype of Auth)

-> a

msg: the Message the auth is being created for

-> Text

authHeader: the WWW-Authenticate/Proxy-Authenticate header

-> m (Maybe Auth)

Returns: the new Auth, or Nothing if it could not be created

Creates a new Auth of type type with the information from msg and authHeader.

This is called by [classsession]; you will normally not create auths yourself.

update

authUpdate

Arguments

:: (HasCallStack, MonadIO m, IsAuth a, IsMessage b)

=> a

auth: a Auth

-> b

msg: the Message auth is being updated for

-> Text

authHeader: the WWW-Authenticate/Proxy-Authenticate header

-> m Bool

Returns: True if auth is still a valid (but potentially unauthenticated) Auth. False if something about authParams could not be parsed or incorporated into auth at all.

Updates auth with the information from msg and authHeader, possibly un-authenticating it.

As with [ctorauth.new], this is normally only used by [classsession].

Properties

authority

The authority (host:port) being authenticated to.

clearAuthAuthority :: (MonadIO m, IsAuth o) => o -> m ()

Set the value of the “authority” property to Nothing. When overloading is enabled, this is equivalent to

clear #authority

constructAuthAuthority :: (IsAuth o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “authority” property. This is rarely needed directly, but it is used by new.

getAuthAuthority :: (MonadIO m, IsAuth o) => o -> m Text

Get the value of the “authority” property. When overloading is enabled, this is equivalent to

get auth #authority

setAuthAuthority :: (MonadIO m, IsAuth o) => o -> Text -> m ()

Set the value of the “authority” property. When overloading is enabled, this is equivalent to

set auth [ #authority := value ]

isAuthenticated

Whether or not the auth has been authenticated.

getAuthIsAuthenticated :: (MonadIO m, IsAuth o) => o -> m Bool

Get the value of the “is-authenticated” property. When overloading is enabled, this is equivalent to

get auth #isAuthenticated

isCancelled

Whether or not the auth has been cancelled.

getAuthIsCancelled :: (MonadIO m, IsAuth o) => o -> m Bool

Get the value of the “is-cancelled” property. When overloading is enabled, this is equivalent to

get auth #isCancelled

isForProxy

Whether or not the auth is for a proxy server.

constructAuthIsForProxy :: (IsAuth o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “is-for-proxy” property. This is rarely needed directly, but it is used by new.

getAuthIsForProxy :: (MonadIO m, IsAuth o) => o -> m Bool

Get the value of the “is-for-proxy” property. When overloading is enabled, this is equivalent to

get auth #isForProxy

setAuthIsForProxy :: (MonadIO m, IsAuth o) => o -> Bool -> m ()

Set the value of the “is-for-proxy” property. When overloading is enabled, this is equivalent to

set auth [ #isForProxy := value ]

realm

The authentication realm.

clearAuthRealm :: (MonadIO m, IsAuth o) => o -> m ()

Set the value of the “realm” property to Nothing. When overloading is enabled, this is equivalent to

clear #realm

constructAuthRealm :: (IsAuth o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “realm” property. This is rarely needed directly, but it is used by new.

getAuthRealm :: (MonadIO m, IsAuth o) => o -> m Text

Get the value of the “realm” property. When overloading is enabled, this is equivalent to

get auth #realm

setAuthRealm :: (MonadIO m, IsAuth o) => o -> Text -> m ()

Set the value of the “realm” property. When overloading is enabled, this is equivalent to

set auth [ #realm := value ]

schemeName

The authentication scheme name.

getAuthSchemeName :: (MonadIO m, IsAuth o) => o -> m Text

Get the value of the “scheme-name” property. When overloading is enabled, this is equivalent to

get auth #schemeName