ESoupSession: Evolution-Data-Server Reference Manual

## ESoupSession ESoupSession — A SoupSession descendant |

## Functions

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 ()
SoupRequestHTTP * | e_soup_session_new_request ()
SoupRequestHTTP * | e_soup_session_new_request_uri ()
gboolean | e_soup_session_check_result ()
GInputStream * | e_soup_session_send_request_sync ()
GByteArray * | e_soup_session_send_request_simple_sync ()
const gchar * | e_soup_session_util_status_to_string ()
gboolean | e_soup_session_util_normalize_uri_path ()

## Types and Values

struct | ESoupSession

## Object Hierarchy

        GObject
        ╰── SoupSession
            ╰── ESoupSession
                ╰── 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_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);

#### Parameters

session | an ESoupSession |

#### Returns

Associated ESource with the `session` .

[transfer none]

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 SOUP_STATUS_SSL_FAILED 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. | [out]
out_certificate_errors | return location for a GTlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error. | [out]

#### Returns

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

Since: 3.26

### e_soup_session_new_request ()

    SoupRequestHTTP *
    e_soup_session_new_request (ESoupSession *session,
                                const gchar *method,
                                const gchar *uri_string,
                                GError **error);

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

See also `e_soup_session_new_request_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 SoupRequestHTTP, or `NULL` on error.

[transfer full]

Since: 3.26

### e_soup_session_new_request_uri ()

    SoupRequestHTTP *
    e_soup_session_new_request_uri (ESoupSession *session,
                                    const gchar *method,
                                    SoupURI *uri,
                                    GError **error);

Creates a new SoupRequestHTTP, similar to `soup_session_request_http_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_request()`.

#### Parameters

session | an ESoupSession |
method | an HTTP method |
uri | a SoupURI to use for the request |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupRequestHTTP, or `NULL` on error.

[transfer full]

Since: 3.26

### e_soup_session_check_result ()

    gboolean
    e_soup_session_check_result (ESoupSession *session,
                                 SoupRequestHTTP *request,
                                 gconstpointer read_bytes,
                                 gsize bytes_length,
                                 GError **error);

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

#### Parameters

session | an ESoupSession |
request | a SoupRequestHTTP |
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_send_request_sync ()

    GInputStream *
    e_soup_session_send_request_sync (ESoupSession *session,
                                      SoupRequestHTTP *request,
                                      GCancellable *cancellable,
                                      GError **error);

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

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

Use `e_soup_session_send_request_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 `request` 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.

#### Parameters

session | an ESoupSession |
request | a SoupRequestHTTP 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 `request` . Free it with `g_object_unref()`, when no longer needed.

[transfer full]

Since: 3.26

### e_soup_session_send_request_simple_sync ()

    GByteArray *
    e_soup_session_send_request_simple_sync
                                   (ESoupSession *session,
                                    SoupRequestHTTP *request,
                                    GCancellable *cancellable,
                                    GError **error);

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

The function prints read content to stdout when `e_soup_session_get_log_level()` returns SOUP_LOGGER_LOG_BODY.

#### Parameters

session | an ESoupSession |
request | a SoupRequestHTTP 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 `request` .

[transfer full]

Since: 3.26

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

    gboolean
    e_soup_session_util_normalize_uri_path
                                   (SoupURI *suri);

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

#### Parameters

suri | a SoupURI to normalize the path for |

#### Returns

whether made any changes

Since: 3.38

## Types and Values

### struct ESoupSession

    struct ESoupSession;

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

Since: 3.26