.. index:: single: http_client_digest_session(HTTPTransport) .. _http_client_digest_session/1:

.. rst-class:: right

object

http_client_digest_session(HTTPTransport)

Stateful HTTP Digest client sessions that add cookie persistence and one-round-trip Digest challenge retry on top of the normalized HTTP client and socket libraries.

| Availability: | logtalk_load(http_digest(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-07-09

| Compilation flags: | static, context_switching_calls

| Imports: | public :ref:`options <options/0>` | public :ref:`http_text_helpers <http_text_helpers/0>` | Uses: | :ref:`http_cookie_jar <http_cookie_jar/0>` | :ref:`http_cookies(Representation) <http_cookies/1>` | :ref:`http_core <http_core/0>` | :ref:`http_digest <http_digest/0>` | :ref:`http_multipart <http_multipart/0>` | :ref:`list <list/0>` | :ref:`url(Representation) <url/1>` | :ref:`user <user/0>` | :ref:`uuid(Representation) <uuid/1>`

| Remarks:

• Option precedence: When the same session default, Digest default, or per-request option is given multiple times, the first occurrence is used.
• Reactive authentication: Requests are sent once without credentials and retried automatically only when the response carries a 401 Digest challenge accepted by the core http_digest object.

| Inherited public predicates: |  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents:: :local: :backlinks: top

Public predicates

.. index:: open/3 .. _http_client_digest_session/1::open/3:

open/3 ^^^^^^^^^^

Opens a new Digest client session with the given username and password and a freshly created owned cookie jar.

| Compilation flags: | static

| Template: | open(Session,Username,Password) | Mode and number of proofs: | open(-compound,++text,++text) - one_or_error

| Exceptions:

---

.. index:: open/4 .. _http_client_digest_session/1::open/4:

open/4 ^^^^^^^^^^

Opens a new Digest client session using the given credentials plus cookie-jar, request-default, and default Digest authorization options.

| Compilation flags: | static

| Template: | open(Session,Username,Password,Options) | Mode and number of proofs: | open(-compound,++text,++text,+list(compound)) - one_or_error

| Exceptions: | Username or Password is neither a variable nor text: | type_error(text,Text) | Options is a variable or a partial list: | instantiation_error | Options is neither a variable nor a list: | type_error(list,Options) | An element Option of the list Options is neither a variable nor a compound term: | type_error(compound,Option) | An element Option of the list Options is a compound term but not a valid option: | domain_error(option,Option) | Options contains an invalid Digest client session option: | domain_error(http_client_digest_session_option,Option) | Options contains an invalid Digest client session option combination: | domain_error(http_client_digest_session_options,Options) | Options contains invalid persisted cookie data: | domain_error(http_cookie_jar_persisted_cookies,PersistedCookies)

---

.. index:: close/1 .. _http_client_digest_session/1::close/1:

close/1 ^^^^^^^^^^^

Closes a Digest client session and, when applicable, the owned cookie jar created for it.

| Compilation flags: | static

| Template: | close(Session) | Mode and number of proofs: | close(+compound) - one_or_error

| Exceptions: | Session is a variable: | instantiation_error | Session is neither a variable nor an open Digest client session handle: | domain_error(http_client_digest_session,Session) | Session refers to a closed Digest client session handle: | existence_error(http_client_digest_session,http_client_digest_session(SessionId))

---

.. index:: cookie_jar/2 .. _http_client_digest_session/1::cookie_jar/2:

cookie_jar/2 ^^^^^^^^^^^^^^^^

Returns the configured cookie jar handle or the atom none when the session does not persist cookies.

| Compilation flags: | static

| Template: | cookie_jar(Session,Jar) | Mode and number of proofs: | cookie_jar(+compound,-term) - one_or_error

| Exceptions: | Session is a variable: | instantiation_error | Session is neither a variable nor an open Digest client session handle: | domain_error(http_client_digest_session,Session) | Session refers to a closed Digest client session handle: | existence_error(http_client_digest_session,http_client_digest_session(SessionId))

---

.. index:: request/5 .. _http_client_digest_session/1::request/5:

request/5 ^^^^^^^^^^^^^

Performs one HTTP request using session defaults, cookie replay/storage, and automatic retry when the server replies with a Digest challenge.

| Compilation flags: | static

| Template: | request(Session,Method,URL,Response,Options) | Mode and number of proofs: | request(+compound,+atom,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is a variable: | instantiation_error | Session is neither a variable nor an open Digest client session handle: | domain_error(http_client_digest_session,Session) | Session refers to a closed Digest client session handle: | existence_error(http_client_digest_session,http_client_digest_session(SessionId)) | URL is a variable: | instantiation_error | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | URL uses an unsupported HTTP scheme: | domain_error(http_client_scheme,Scheme) | Options is a variable or a partial list: | instantiation_error | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options) | Options contains an invalid Digest client session request option: | domain_error(http_client_digest_session_request_option,Option) | Options contains invalid form-data headers: | domain_error(http_client_form_data_headers,Headers) | Options contains invalid form-data properties: | domain_error(http_client_form_data_properties,Properties) | The Digest challenge contains an unsupported algorithm: | domain_error(http_digest_algorithm,Algorithm) | The Digest challenge contains an unsupported qop value: | domain_error(http_digest_qop,Qop)

---

.. index:: get/4 .. _http_client_digest_session/1::get/4:

get/4 ^^^^^^^^^

Convenience wrapper over request/5 using the get method.

| Compilation flags: | static

| Template: | get(Session,URL,Response,Options) | Mode and number of proofs: | get(+compound,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

.. index:: head/4 .. _http_client_digest_session/1::head/4:

head/4 ^^^^^^^^^^

Convenience wrapper over request/5 using the head method.

| Compilation flags: | static

| Template: | head(Session,URL,Response,Options) | Mode and number of proofs: | head(+compound,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

.. index:: delete/4 .. _http_client_digest_session/1::delete/4:

delete/4 ^^^^^^^^^^^^

Convenience wrapper over request/5 using the delete method.

| Compilation flags: | static

| Template: | delete(Session,URL,Response,Options) | Mode and number of proofs: | delete(+compound,+atom,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

.. index:: post/5 .. _http_client_digest_session/1::post/5:

post/5 ^^^^^^^^^^

Convenience wrapper over request/5 using the post method and the given body.

| Compilation flags: | static

| Template: | post(Session,URL,Body,Response,Options) | Mode and number of proofs: | post(+compound,+atom,+compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Body is invalid for the generated normalized HTTP request: | domain_error(http_body,Body) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

.. index:: put/5 .. _http_client_digest_session/1::put/5:

put/5 ^^^^^^^^^

Convenience wrapper over request/5 using the put method and the given body.

| Compilation flags: | static

| Template: | put(Session,URL,Body,Response,Options) | Mode and number of proofs: | put(+compound,+atom,+compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Body is invalid for the generated normalized HTTP request: | domain_error(http_body,Body) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

.. index:: patch/5 .. _http_client_digest_session/1::patch/5:

patch/5 ^^^^^^^^^^^

Convenience wrapper over request/5 using the patch method and the given body.

| Compilation flags: | static

| Template: | patch(Session,URL,Body,Response,Options) | Mode and number of proofs: | patch(+compound,+atom,+compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Session is not an open Digest client session handle: | domain_error(http_client_digest_session,Session) | URL is not a supported absolute HTTP URL: | domain_error(http_client_url,URL) | Body is invalid for the generated normalized HTTP request: | domain_error(http_body,Body) | Options contains invalid Digest client session request options: | domain_error(http_client_digest_session_request_options,Options)

---

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

.. index:: session_seed_/1 .. _http_client_digest_session/1::session_seed_/1:

session_seed_/1 ^^^^^^^^^^^^^^^^^^^

Last allocated Digest client session identifier.

| Compilation flags: | dynamic

| Template: | session_seed_(SessionId) | Mode and number of proofs: | session_seed_(?positive_integer) - zero_or_one

---

.. index:: session_state_/2 .. _http_client_digest_session/1::session_state_/2:

session_state_/2 ^^^^^^^^^^^^^^^^^^^^

Per-session stored cookie jar ownership, credentials, default request state, and default Digest authorization options.

| Compilation flags: | dynamic

| Template: | session_state_(SessionId,State) | Mode and number of proofs: | session_state_(?positive_integer,?compound) - zero_or_more

---

Operators

(none)