ESoupSession

ESoupSession — A SoupSession descendant

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── SoupSession
        ╰── ESoupSession
            ├── EGDataSession
            ╰── EWebDAVSession

Includes

#include <libedataserver/libedataserver.h>

Description

The ESoupSession is a SoupSession descendant, which hides common tasks related to the way evolution-data-server works.

Functions

e_soup_session_error_quark ()

GQuark
e_soup_session_error_quark (void);

e_soup_session_new ()

ESoupSession *
e_soup_session_new (ESource *source);

Creates a new ESoupSession associated with given source . The source can be used to store and read SSL trust settings, but only if it already contains an ESourceWebdav extension. Otherwise the SSL trust settings are ignored.

Parameters

source

an ESource

 

Returns

a new ESoupSession; free it with g_object_unref(), when no longer needed.

[transfer full]

Since: 3.26


e_soup_session_setup_logging ()

void
e_soup_session_setup_logging (ESoupSession *session,
                              const gchar *logging_level);

Setups logging for the session . The logging_level can be one of: "all" - log whole raw communication; "body" - the same as "all"; "headers" - log the headers only; "min" - minimal logging; "1" - the same as "all". Any other value, including NULL, disables logging.

Use e_soup_session_get_log_level() to get current log level.

Parameters

session

an ESoupSession

 

logging_level

logging level to setup, or NULL.

[nullable]

Since: 3.26


e_soup_session_get_log_level ()

SoupLoggerLogLevel
e_soup_session_get_log_level (ESoupSession *session);

Parameters

session

an ESoupSession

 

Returns

Current log level, as SoupLoggerLogLevel

Since: 3.26


e_soup_session_get_source ()

ESource *
e_soup_session_get_source (ESoupSession *session);

Returns an ESource associated with the session , if such was set in the creation time.

Parameters

session

an ESoupSession

 

Returns

Associated ESource with the session , or NULL.

[transfer none][nullable]

Since: 3.26


e_soup_session_set_credentials ()

void
e_soup_session_set_credentials (ESoupSession *session,
                                const ENamedParameters *credentials);

Sets credentials to use for connection. Using NULL for credentials unsets previous value.

Parameters

session

an ESoupSession

 

credentials

an ENamedParameters with credentials to use, or NULL.

[nullable]

Since: 3.26


e_soup_session_dup_credentials ()

ENamedParameters *
e_soup_session_dup_credentials (ESoupSession *session);

Parameters

session

an ESoupSession

 

Returns

A copy of the credentials being previously set with e_soup_session_set_credentials(), or NULL when none are set. Free the returned pointer with e_named_parameters_free(), when no longer needed.

[nullable][transfer full]

Since: 3.26


e_soup_session_set_force_http1 ()

void
e_soup_session_set_force_http1 (ESoupSession *session,
                                gboolean force_http1);

Sets whether the messages created through the session using e_soup_session_new_message() or e_soup_session_new_message_from_uri() should force use of the HTTP/1, instead of trying HTTP/2 and fallback to HTTP/1, when the newer version cannot be used.

The property has no effect when e_soup_session_util_get_force_http1_supported() returns FALSE.

Parameters

session

an ESoupSession

 

force_http1

the value to set

 

Since: 3.48


e_soup_session_get_force_http1 ()

gboolean
e_soup_session_get_force_http1 (ESoupSession *session);

Returns whether it's forced to use HTTP/1 for the messages created by the session . See e_soup_session_set_force_http1() for more information about the limitations.

Parameters

session

an ESoupSession

 

Returns

whether it's forced to use HTTP/1

Since: 3.48


e_soup_session_set_handle_backoff_responses ()

void
e_soup_session_set_handle_backoff_responses
                               (ESoupSession *session,
                                gboolean handle_backoff_responses);

Sets whether to automatically handle backoff responses from the server, that is, when the server requests the client to retry later.

Note: This handles only the synchronous functions to send the messages. Clients using the asynchronous API need to handle the backoff responses on their own.

Parameters

session

an ESoupSession

 

handle_backoff_responses

the value to set

 

Since: 3.54


e_soup_session_get_handle_backoff_responses ()

gboolean
e_soup_session_get_handle_backoff_responses
                               (ESoupSession *session);

Returns whether the session can handle backoff responses from the server. See e_soup_session_set_handle_backoff_responses() for more information about the limitations.

Parameters

session

an ESoupSession

 

Returns

whether the session handles backoff responses

Since: 3.54


e_soup_session_get_authentication_requires_credentials ()

gboolean
e_soup_session_get_authentication_requires_credentials
                               (ESoupSession *session);

Parameters

session

an ESoupSession

 

Returns

Whether the last connection attempt required any credentials. Authentications like OAuth2 do not want extra credentials to work.

Since: 3.28


e_soup_session_get_ssl_error_details ()

gboolean
e_soup_session_get_ssl_error_details (ESoupSession *session,
                                      gchar **out_certificate_pem,
                                      GTlsCertificateFlags *out_certificate_errors);

Populates out_certificate_pem and out_certificate_errors with the last values returned on G_TLS_ERROR_BAD_CERTIFICATE error.

Parameters

session

an ESoupSession

 

out_certificate_pem

return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error, or NULL.

[out][optional]

out_certificate_errors

return location for a GTlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error, or NULL.

[out][optional]

Returns

Whether the information was available and set to the out parameters.

Since: 3.26


e_soup_session_handle_authentication_failure ()

void
e_soup_session_handle_authentication_failure
                               (ESoupSession *session,
                                const ENamedParameters *credentials,
                                const GError *op_error,
                                ESourceAuthenticationResult *out_auth_result,
                                gchar **out_certificate_pem,
                                GTlsCertificateFlags *out_certificate_errors,
                                GError **error);

Handles authentication failure and sets appropriate value to the out_auth_result for the provided op_error and used credentials . Converts the op_error into an appropriate error returned in the error .

Also updates connection status on the associated ESource with the session .

Parameters

session

an ESoupSession

 

credentials

credentials used for the authentication.

[nullable]

op_error

a GError of the authentication operation

 

out_auth_result

an ESourceAuthenticationResult with an authentication result.

[out]

out_certificate_pem

return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error, or NULL.

[out][optional]

out_certificate_errors

return location for a GTlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error, or NULL.

[out][optional]

error

return location for a GError, or NULL

 

Since: 3.46


e_soup_session_new_message ()

SoupMessage *
e_soup_session_new_message (ESoupSession *session,
                            const gchar *method,
                            const gchar *uri_string,
                            GError **error);

Creates a new SoupMessage, similar to soup_message_new(), but also presets request headers with "User-Agent" to be "Evolution/version" and with "Connection" to be "close".

See also e_soup_session_new_message_from_uri().

Parameters

session

an ESoupSession

 

method

an HTTP method

 

uri_string

a URI string to use for the request

 

error

return location for a GError, or NULL

 

Returns

a new SoupMessage, or NULL on error.

[transfer full]

Since: 3.26


e_soup_session_new_message_from_uri ()

SoupMessage *
e_soup_session_new_message_from_uri (ESoupSession *session,
                                     const gchar *method,
                                     GUri *uri,
                                     GError **error);

Creates a new SoupMessage, similar to soup_message_new_from_uri(), but also presets request headers with "User-Agent" to be "Evolution/version" and with "Connection" to be "close".

See also e_soup_session_new_message().

Parameters

session

an ESoupSession

 

method

an HTTP method

 

uri

a GUri to use for the request

 

error

return location for a GError, or NULL

 

Returns

a new SoupMessage, or NULL on error.

[transfer full]

Since: 3.46


e_soup_session_check_result ()

gboolean
e_soup_session_check_result (ESoupSession *session,
                             SoupMessage *message,
                             gconstpointer read_bytes,
                             gsize bytes_length,
                             GError **error);

Checks result of the message and sets the error if it failed. When it failed and the read_bytes is provided, then these are set to message 's response body, thus it can be used later.

Parameters

session

an ESoupSession

 

message

a SoupMessage

 

read_bytes

optional bytes which had been read from the stream, or NULL.

[nullable]

bytes_length

how many bytes had been read; ignored when read_bytes is NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded, aka TRUE, when no error recognized and FALSE otherwise.

Since: 3.26


e_soup_session_prepare_message_send_sync ()

gpointer
e_soup_session_prepare_message_send_sync
                               (ESoupSession *session,
                                SoupMessage *message,
                                GCancellable *cancellable,
                                GError **error);

Prepares the message to be a sent asynchronously with e_soup_session_send_message(). The returned pointer is passed to the e_soup_session_send_message() as the prepare_data parameter.

Parameters

session

an ESoupSession

 

message

a SoupMessage to prepare for asynchronous send

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

prepare data for e_soup_session_send_message(), or NULL on error.

[nullable][transfer full]

Since: 3.46


e_soup_session_send_message ()

void
e_soup_session_send_message (ESoupSession *session,
                             SoupMessage *message,
                             gint io_priority,
                             gpointer prepare_data,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Asynchronously sends the message . Finish the call with e_soup_session_send_message_finish().

The prepare_data is a result of the e_soup_session_prepare_message_send_sync() and this function assumes ownership of it. The prepare_data cannot be used again after this call.

Parameters

session

an ESoupSession

 

message

a SoupMessage to send

 

io_priority

the I/O priority of the request, like G_PRIORITY_DEFAULT

 

prepare_data

data returned from e_soup_session_prepare_message_send_sync().

[transfer full]

cancellable

optional GCancellable object, or NULL

 

callback

the callback to invoke once the request is finished.

[scope async]

user_data

user data for callback

 

Since: 3.46


e_soup_session_send_message_finish ()

GInputStream *
e_soup_session_send_message_finish (ESoupSession *session,
                                    GAsyncResult *result,
                                    gchar **out_certificate_pem,
                                    GTlsCertificateFlags *out_certificate_errors,
                                    GError **error);

Finishes the call of e_soup_session_send_message(). This is supposed to be called from the callback passed to the e_soup_session_send_message().

The optional out_certificate_pem and out_certificate_errors are set, when provided, only if the operation failed with a TLS/SSL error.

Make sure the GInputStream is read and freed from the same thread, and with the same thread default main context, which this function was called from, otherwise it can break libsoup3.

Parameters

session

an ESoupSession

 

result

a GAsyncResult object

 

out_certificate_pem

return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error.

[out][optional][nullable]

out_certificate_errors

return location for a GTlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error.

[out][optional]

error

return location for a GError, or NULL

 

Returns

a GInputStream for reading the response body, or NULL on error.

[transfer full][nullable]

Since: 3.46


e_soup_session_send_message_sync ()

GInputStream *
e_soup_session_send_message_sync (ESoupSession *session,
                                  SoupMessage *message,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously sends prepared message and returns GInputStream that can be used to read its contents.

This calls soup_session_send() internally, but it also setups the message according to “source” authentication settings. It also extracts information about used certificate, in case of G_TLS_ERROR_BAD_CERTIFICATE error and keeps it for later use by e_soup_session_get_ssl_error_details().

Use e_soup_session_send_message_simple_sync() to read whole content into a GByteArray.

Note that SoupSession doesn't log content read from GInputStream, thus the caller may print the read content on its own when needed.

Note the message is fully filled only after there is anything read from the resulting GInputStream, thus use e_soup_session_check_result() to verify that the receive had been finished properly.

Make sure the GInputStream is read and freed from the same thread, and with the same thread default main context, which this function was called from, otherwise it can break libsoup3.

Parameters

session

an ESoupSession

 

message

a SoupMessage to send

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

A newly allocated GInputStream, that can be used to read from the URI pointed to by message . Free it with g_object_unref(), when no longer needed.

[transfer full]

Since: 3.26


e_soup_session_send_message_simple_sync ()

GByteArray *
e_soup_session_send_message_simple_sync
                               (ESoupSession *session,
                                SoupMessage *message,
                                GCancellable *cancellable,
                                GError **error);

Similar to e_soup_session_send_message_sync(), except it reads whole response content into memory and returns it as a GByteArray. Use e_soup_session_send_message_sync() when you want to have more control on the content read.

Parameters

session

an ESoupSession

 

message

a SoupMessage to send

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

A newly allocated GByteArray, which contains whole content from the URI pointed to by message .

[transfer full]

Since: 3.26


e_soup_session_util_get_message_bytes ()

GByteArray *
e_soup_session_util_get_message_bytes (SoupMessage *message);

Returns bytes read from the message response, when the message send failed. This can be used to examine detailed error returned by the server in the response body.

Parameters

message

a SoupMessage

 

Returns

read message data on failed request, or NULL, when none had been read.

[transfer none][nullable]

Since: 3.46


e_soup_session_util_status_to_string ()

const gchar *
e_soup_session_util_status_to_string (guint status_code,
                                      const gchar *reason_phrase);

Returns the reason_phrase , if it's non-NULL and non-empty, a static string corresponding to status_code . In case neither that can be found a localized "Unknown error" message is returned.

Parameters

status_code

an HTTP status code

 

reason_phrase

preferred string to use for the message, or NULL.

[nullable]

Returns

Error text based on given arguments. The returned value is valid as long as reason_phrase is not freed.

[transfer none]

Since: 3.26


e_soup_session_util_normalize_uri_path ()

GUri *
e_soup_session_util_normalize_uri_path
                               (GUri *uri);

Normalizes the path of the uri , aka encodes characters, which should be encoded, if needed. Returns, modified URI when any change had been made to the path. It doesn't touch other parts of the uri .

Parameters

uri

a GUri to normalize the path for

 

Returns

a new GUri with modified path, or NULL, when no change was required.

[transfer full][nullable]

Since: 3.46


e_soup_session_util_set_message_request_body ()

void
e_soup_session_util_set_message_request_body
                               (SoupMessage *message,
                                const gchar *content_type,
                                GInputStream *input_stream,
                                gssize length);

Sets the request body of the message from the input_stream of the length , with optional content_type . The function makes sure the message request body is set again when the message is restarted.

The input_stream should implement the GSeekable interface.

Parameters

message

a SoupMessage

 

content_type

optional Content-Type of the data , or NULL.

[nullable]

input_stream (transfer none)

the request body data as a GInputStream

 

length

length of the data

 

Since: 3.46


e_soup_session_util_set_message_request_body_from_data ()

void
e_soup_session_util_set_message_request_body_from_data
                               (SoupMessage *message,
                                gboolean create_copy,
                                const gchar *content_type,
                                gconstpointer data,
                                gssize length,
                                GDestroyNotify free_func);

Sets the request body of the message from the data of the length , with optional content_type . The function makes sure the message request body is set again when the message is restarted.

When the create_copy is TRUE, the free_func should be NULL.

Parameters

message

a SoupMessage

 

create_copy

whether to create copy of the data

 

content_type

optional Content-Type of the data , or NULL.

[nullable]

data

the request body data

 

length

length of the data

 

free_func

a free function for the data , or NULL.

[nullable]

Since: 3.46


e_soup_session_util_ref_message_request_body ()

GInputStream *
e_soup_session_util_ref_message_request_body
                               (SoupMessage *message,
                                gssize *out_length);

Returns referenced request data for the message , as being previously set by the e_soup_session_util_set_message_request_body() or e_soup_session_util_set_message_request_body_from_data().

Do not call this function while the message is queued in a SoupSession, nor modify the input stream position until the message lefts the SoupSession.

Parameters

message

a SoupMessage

 

out_length

length of the input stream.

[out][optional]

Returns

a new GInputStream with the request body being previously set, or NULL. The out_length is set to the length of the returned input stream.

[nullable][transfer full]

Since: 3.46


e_soup_session_util_get_force_http1_supported ()

gboolean
e_soup_session_util_get_force_http1_supported
                               (void);

Checks whether e_soup_session_set_force_http1() can be used to force HTTP/1 usage. This depends on the libsoup version the data server had been compiled with.

Returns

TRUE, when the force of HTTP/1 is supported, FALSE otherwise

Since: 3.48

Types and Values

E_SOUP_SESSION_ERROR

#define E_SOUP_SESSION_ERROR (e_soup_session_error_quark())

struct ESoupSession

struct ESoupSession;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.26