Top | ![]() |
![]() |
![]() |
![]() |
The ESoupSession is a SoupSession descendant, which hides common tasks related to the way evolution-data-server works.
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.
Since: 3.26
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.
Since: 3.26
SoupLoggerLogLevel
e_soup_session_get_log_level (ESoupSession *session
);
Since: 3.26
ESource *
e_soup_session_get_source (ESoupSession *session
);
Returns an ESource associated with the session
, if such was set in the creation time.
Since: 3.26
void e_soup_session_set_credentials (ESoupSession *session
,const ENamedParameters *credentials
);
Sets credentials to use for connection. Using NULL
for credentials
unsets previous value.
session |
an ESoupSession |
|
credentials |
an ENamedParameters with credentials to use, or |
[nullable] |
Since: 3.26
ENamedParameters *
e_soup_session_dup_credentials (ESoupSession *session
);
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
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
.
Since: 3.48
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.
Since: 3.48
gboolean
e_soup_session_get_authentication_requires_credentials
(ESoupSession *session
);
Whether the last connection attempt required any credentials. Authentications like OAuth2 do not want extra credentials to work.
Since: 3.28
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.
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 |
[out][optional] |
out_certificate_errors |
return location for a GTlsCertificateFlags,
with certificate error flags when the operation failed with a TLS/SSL error, or |
[out][optional] |
Since: 3.26
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
.
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 |
[out][optional] |
out_certificate_errors |
return location for a GTlsCertificateFlags,
with certificate error flags when the operation failed with a TLS/SSL error, or |
[out][optional] |
error |
return location for a GError, or |
Since: 3.46
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()
.
session |
an ESoupSession |
|
method |
an HTTP method |
|
uri_string |
a URI string to use for the request |
|
error |
return location for a GError, or |
Since: 3.26
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()
.
session |
an ESoupSession |
|
method |
an HTTP method |
|
uri |
a GUri to use for the request |
|
error |
return location for a GError, or |
Since: 3.46
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.
session |
an ESoupSession |
|
message |
a SoupMessage |
|
read_bytes |
optional bytes which had been read from the stream, or |
[nullable] |
bytes_length |
how many bytes had been read; ignored when |
|
error |
return location for a GError, or |
Since: 3.26
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.
session |
an ESoupSession |
|
message |
a SoupMessage to prepare for asynchronous send |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.46
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.
session |
an ESoupSession |
|
message |
a SoupMessage to send |
|
io_priority |
the I/O priority of the request, like |
|
prepare_data |
data returned from |
[transfer full] |
cancellable |
optional GCancellable object, or |
|
callback |
the callback to invoke once the request is finished. |
[scope async] |
user_data |
user data for |
Since: 3.46
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.
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 |
Since: 3.46
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.
session |
an ESoupSession |
|
message |
a SoupMessage to send |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
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
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.
session |
an ESoupSession |
|
message |
a SoupMessage to send |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
A newly allocated GByteArray,
which contains whole content from the URI pointed to by message
.
[transfer full]
Since: 3.26
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.
read message data on failed request, or NULL
, when none had been read.
[transfer none][nullable]
Since: 3.46
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.
status_code |
an HTTP status code |
|
reason_phrase |
preferred string to use for the message, or |
[nullable] |
Error text based on given arguments. The returned
value is valid as long as reason_phrase
is not freed.
[transfer none]
Since: 3.26
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
.
a new GUri with modified path, or NULL
, when
no change was required.
[transfer full][nullable]
Since: 3.46
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.
message |
a SoupMessage |
|
content_type |
optional Content-Type of the |
[nullable] |
input_stream (transfer none) |
the request body data as a GInputStream |
|
length |
length of the |
Since: 3.46
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
.
message |
a SoupMessage |
|
create_copy |
whether to create copy of the |
|
content_type |
optional Content-Type of the |
[nullable] |
data |
the request body data |
|
length |
length of the |
|
free_func |
a free function for the |
[nullable] |
Since: 3.46
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.
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
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.
Since: 3.48
struct ESoupSession;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26