Top | ![]() |
![]() |
![]() |
![]() |
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 () |
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
);
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
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 SOUP_STATUS_SSL_FAILED 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. |
[out] |
out_certificate_errors |
return location for a GTlsCertificateFlags, with certificate error flags when the the operation failed with a TLS/SSL error. |
[out] |
Since: 3.26
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()
.
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
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()
.
session |
an ESoupSession |
|
method |
an HTTP method |
|
uri |
a SoupURI to use for the request |
|
error |
return location for a GError, or |
Since: 3.26
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.
session |
an ESoupSession |
|
request |
||
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
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.
session |
an ESoupSession |
|
request |
a SoupRequestHTTP 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 request
.
Free it with g_object_unref()
, when no longer needed.
[transfer full]
Since: 3.26
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.
session |
an ESoupSession |
|
request |
a SoupRequestHTTP 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 request
.
[transfer full]
Since: 3.26
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
struct ESoupSession;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26