ESoupSession

ESoupSession — A SoupSession descendant

Functions

Types and Values

struct ESoupSession

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

Types and Values

struct ESoupSession

struct ESoupSession {
};

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

Since: 3.26