ESoupSession: Evolution-Data-Server Reference Manual

## ESoupSession ESoupSession — A SoupSession descendant |

## Functions

GQuark | e_soup_session_error_quark ()
ESoupSession * | e_soup_session_new ()
void | e_soup_session_setup_logging ()
SoupLoggerLogLevel | e_soup_session_get_log_level ()
ESource * | e_soup_session_get_source ()
void | e_soup_session_set_credentials ()
ENamedParameters * | e_soup_session_dup_credentials ()
gboolean | e_soup_session_get_authentication_requires_credentials ()
gboolean | e_soup_session_get_ssl_error_details ()
void | e_soup_session_handle_authentication_failure ()
SoupMessage * | e_soup_session_new_message ()
SoupMessage * | e_soup_session_new_message_from_uri ()
gboolean | e_soup_session_check_result ()
gpointer | e_soup_session_prepare_message_send_sync ()
void | e_soup_session_send_message ()
GInputStream * | e_soup_session_send_message_finish ()
GInputStream * | e_soup_session_send_message_sync ()
GByteArray * | e_soup_session_send_message_simple_sync ()
GByteArray * | e_soup_session_util_get_message_bytes ()
const gchar * | e_soup_session_util_status_to_string ()
GUri * | e_soup_session_util_normalize_uri_path ()
void | e_soup_session_util_set_message_request_body ()
void | e_soup_session_util_set_message_request_body_from_data ()
GInputStream * | e_soup_session_util_ref_message_request_body ()

## Types and Values

#define | E_SOUP_SESSION_ERROR
struct | ESoupSession

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

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