Creates a new #EWebDAVSession associated with given source.
The #EWebDAVSession uses an #ESourceWebdav extension on certain
places when it's defined for the source.
an #ESource
If non-%NULL, the value to use for the "Accept-Language" header on #SoupMessages sent from this session.
Setting this will disable #SoupSession:accept-language-auto.
If %TRUE, #SoupSession will automatically set the string for the "Accept-Language" header on every #SoupMessage sent, based on the return value of g_get_language_names().
Setting this will override any previous value of #SoupSession:accept-language.
The #GMainContext that miscellaneous session-related asynchronous callbacks are invoked on. (Eg, setting #SoupSession:idle-timeout will add a timeout source on this context.)
For a plain #SoupSession, this property is always set to the #GMainContext that is the thread-default at the time the session was created, and cannot be overridden. For the deprecated #SoupSession subclasses, the default value is %NULL, meaning to use the global default #GMainContext.
If #SoupSession:use-thread-context is %FALSE, this context will also be used for asynchronous HTTP I/O.
The #ENamedParameters containing login credentials.
A %NULL-terminated array of URI schemes that should be
considered to be aliases for "http". Eg, if this included
In a plain #SoupSession, the default value is %NULL,
meaning that only "http" is recognized as meaning "http".
In #SoupSessionAsync and #SoupSessionSync, for backward
compatibility, the default value is an array containing the
single element
See also #SoupSession:https-aliases.
A comma-delimited list of URI schemes that should be considered to be aliases for "https". See #SoupSession:http-aliases for more information.
The default value is %NULL, meaning that no URI schemes are considered aliases for "https".
Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.
Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call soup_session_abort() after setting this if you want to ensure that all future connections will have this timeout value.
Note that the default value of 60 seconds only applies to plain #SoupSessions. If you are using #SoupSessionAsync or #SoupSessionSync, the default value is 0 (meaning idle connections will never time out).
Sets the #SoupAddress to use for the client side of the connection.
Use this property if you want for instance to bind the local socket to a specific IP address.
A #GProxyResolver to use with this session. Setting this
will clear the #SoupSession:proxy-uri property, and remove
any
By default, in a plain #SoupSession, this is set to the default #GProxyResolver, but you can set it to %NULL if you don't want to use proxies, or set it to your own #GProxyResolver if you want to control what proxies get used.
A proxy to use for all http and https requests in this
session. Setting this will clear the
#SoupSession:proxy-resolver property, and remove any
Note that #SoupSession will normally handle looking up the user's proxy settings for you; you should only use #SoupSession:proxy-uri if you need to override the user's normal proxy settings.
Also note that this proxy will be used for
The #ESource being used for this soup session.
File containing SSL CA certificates.
If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.
Normally, if #SoupSession:tls-database is set (including if it was set via #SoupSession:ssl-use-system-ca-file or #SoupSession:ssl-ca-file), then libsoup will reject any certificate that is invalid (ie, expired) or that is not signed by one of the given CA certificates, and the #SoupMessage will fail with the status %SOUP_STATUS_SSL_FAILED.
If you set #SoupSession:ssl-strict to %FALSE, then all certificates will be accepted, and you will need to call soup_message_get_https_status() to distinguish valid from invalid certificates. (This can be used, eg, if you want to accept invalid certificates after giving some sort of warning.)
For a plain #SoupSession, if the session has no CA file or TLS database, and this property is %TRUE, then all certificates will be rejected. However, beware that the deprecated #SoupSession subclasses (#SoupSessionAsync and #SoupSessionSync) have the opposite behavior: if there is no CA file or TLS database, then all certificates are always accepted, and this property has no effect.
Setting this to %TRUE is equivalent to setting #SoupSession:tls-database to the default system CA database. (and likewise, setting #SoupSession:tls-database to the default database by hand will cause this property to become %TRUE).
Setting this to %FALSE (when it was previously %TRUE) will clear the #SoupSession:tls-database field.
See #SoupSession:ssl-strict for more information on how https certificate validation is handled.
If you are using #SoupSessionAsync or #SoupSessionSync, on libsoup older than 2.74.0, the default value is %FALSE, for backward compatibility.
The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).
Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call soup_session_abort() after setting this if you want to ensure that all future connections will have this timeout value.
Note that the default value of 60 seconds only applies to plain #SoupSessions. If you are using #SoupSessionAsync or #SoupSessionSync, the default value is 0 (meaning socket I/O will not time out).
Not to be confused with #SoupSession:idle-timeout (which is the length of time that idle persistent connections will be kept open).
Sets the #GTlsDatabase to use for validating SSL/TLS certificates.
Note that setting the #SoupSession:ssl-ca-file or #SoupSession:ssl-use-system-ca-file property will cause this property to be set to a #GTlsDatabase corresponding to the indicated file or system default.
See #SoupSession:ssl-strict for more information on how https certificate validation is handled.
If you are using a plain #SoupSession then #SoupSession:ssl-use-system-ca-file will be %TRUE by default, and so this property will be a copy of the system CA database. If you are using #SoupSessionAsync or #SoupSessionSync, on libsoup older than 2.74.0, this property will be %NULL by default.
A #GTlsInteraction object that will be passed on to any #GTlsConnections created by the session. (This can be used to provide client-side certificates, for example.)
Whether or not to use NTLM authentication.
If %TRUE (which it always is on a plain #SoupSession), asynchronous HTTP requests in this session will run in whatever the thread-default #GMainContext is at the time they are started, rather than always occurring in #SoupSession:async-context.
If non-%NULL, the value to use for the "User-Agent" header on #SoupMessages sent from this session.
RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests."
The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.
If you set a #SoupSession:user_agent property that has trailing
whitespace, #SoupSession will append its own product token
(eg, "
Cancels all pending requests in session and closes all idle
persistent connections.
The message cancellation has the same semantics as with soup_session_cancel_message(); asynchronous requests on a #SoupSessionAsync will have their callback called before soup_session_abort() returns. Requests on a plain #SoupSession will not.
Issues ACL request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource.
URI to issue the request for, or %NULL to read from #ESource
the request itself, as an #EXmlDocument, the root element should be DAV:acl
optional #GCancellable object, or %NULL
Adds feature's functionality to session. You can also add a
feature to the session at construct time by using the
%SOUP_SESSION_ADD_FEATURE property.
See the main #SoupSession documentation for information on what features are present in sessions by default.
an object that implements #SoupSessionFeature
If feature_type is the type of a class that implements
#SoupSessionFeature, this creates a new feature of that type and
adds it to session as with soup_session_add_feature(). You can use
this when you don't need to customize the new feature in any way.
If feature_type is not a #SoupSessionFeature type, this gives each
existing feature on session the chance to accept feature_type as
a "subfeature". This can be used to add new #SoupAuth or
#SoupRequest types, for instance.
You can also add a feature to the session at construct time by using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property.
See the main #SoupSession documentation for information on what features are present in sessions by default.
a #GType
Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.
If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
#GBinding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A #GObject can have multiple bindings.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default
a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default
Causes session to immediately finish processing msg (regardless
of its current state) with a final status_code of status_code. You
may call this at any time after handing msg off to session; if
session has started sending the request but has not yet received
the complete response, then it will close the request's connection.
Note that with requests that have side effects (eg,
If the message is cancelled while its response body is being read,
then the response body in msg will be left partially-filled-in.
The response headers, on the other hand, will always be either
empty or complete.
Beware that with the deprecated #SoupSessionAsync, messages queued with soup_session_queue_message() will have their callbacks invoked before soup_session_cancel_message() returns. The plain #SoupSession does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.
the message to cancel
status code to set on msg (generally %SOUP_STATUS_CANCELLED)
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.
a #SoupRequestHTTP
optional bytes which had been read from the stream, or %NULL
how many bytes had been read; ignored when read_bytes is %NULL
Start a connection to uri. The operation can be monitored by providing a progress_callback
and finishes when the connection is done or an error ocurred.
Call soup_session_connect_finish() to get the #GIOStream to communicate with the server.
a #SoupURI to connect to
a #GCancellable
a #SoupSessionConnectProgressCallback which will be called for every network event that occurs during the connection.
the callback to invoke when the operation finishes
Gets the #GIOStream created for the connection to communicate with the server.
the #GAsyncResult passed to your callback
Copies a resource identified by source_uri to destination_uri on the server.
The source_uri can reference also collections, in which case the depth influences
whether only the collection itself is copied (%E_WEBDAV_DEPTH_THIS) or whether
the collection with all its children is copied (%E_WEBDAV_DEPTH_INFINITY).
URI of the resource or collection to copy
URI of the destination
requested depth, can be one of %E_WEBDAV_DEPTH_THIS or %E_WEBDAV_DEPTH_INFINITY
whether can overwrite destination_uri, when it exists
optional #GCancellable object, or %NULL
Deletes a resource identified by uri on the server. The URI can
reference a collection, in which case depth should be %E_WEBDAV_DEPTH_INFINITY.
Use depth %E_WEBDAV_DEPTH_THIS when deleting a regular resource, or %NULL,
to let the server use default Depth.
The etag argument is used to avoid clashes when overwriting existing resources.
Use %NULL etag when deleting collection resources or to force the deletion,
otherwise provide a valid ETag of a non-collection resource to verify that
the version requested to delete is the same as on the server.
Note that the actual usage of etag is also influenced by #ESourceWebdav:avoid-ifmatch
property of the associated #ESource.
URI of the resource to delete
optional requested depth, can be one of %E_WEBDAV_DEPTH_THIS or %E_WEBDAV_DEPTH_INFINITY, or %NULL
an optional ETag of the resource, or %NULL
optional #GCancellable object, or %NULL
Converts possibly path-only href into a full URI under the request_uri.
When the request_uri is %NULL, the URI defined in associated #ESource is
used instead, taken from the #ESourceWebdav extension, if defined.
Free the returned pointer with g_free(), when no longer needed.
a #SoupURI to which the href belongs, or %NULL
a possibly path-only href
This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
#GObject::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets Access Control List (ACL) restrictions for the uri, or, in case it's %NULL,
for the URI defined in associated #ESource. The out_principal_kind is valid only
if the out_restrictions contains #E_WEBDAV_ACL_RESTRICTION_REQUIRED_PRINCIPAL.
The out_principal_hrefs is valid only if the out_principal_kind is valid and when
it is #E_WEBDAV_ACE_PRINCIPAL_HREF.
Free the returned out_principal_hrefs with
g_slist_free_full (entries, g_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Gets Access Control List (ACL) for the uri, or, in case it's %NULL, for the URI
defined in associated #ESource.
This function doesn't read general #E_WEBDAV_ACE_PRINCIPAL_PROPERTY.
Free the returned out_entries with
g_slist_free_full (entries, e_webdav_access_control_entry_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Gets session's #SoupSession:async-context. This does not add a ref
to the context, so you will need to ref it yourself if you want it
to outlive its session.
For a modern #SoupSession, this will always just return the thread-default #GMainContext, and so is not especially useful.
Gets current user privileges for the uri, or, in case it's %NULL, for the URI
defined in associated #ESource.
Free the returned out_privileges with
g_slist_free_full (privileges, e_webdav_privilege_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
Reads a resource identified by uri from the server. The URI cannot
reference a collection.
The out_bytes is filled by actual data being read. If not %NULL, out_length
is populated with how many bytes had been read. The out_bytes is always
NUL-terminated, while this termination byte is not part of out_length.
Free the out_bytes with g_free(), when no longer needed.
Free returned pointer of out_href and out_etag, if not %NULL, with g_free(),
when no longer needed.
To read large data use e_webdav_session_get_sync() instead.
URI of the resource to read
optional #GCancellable object, or %NULL
Gets the first feature in session of type feature_type. For
features where there may be more than one feature of a given type,
use soup_session_get_features().
the #GType of the feature to get
Gets the first feature in session of type feature_type, provided
that it is not disabled for msg. As with
soup_session_get_feature(), this should only be used for features
where feature_type is only expected to match a single feature. In
particular, if there are two matching features, and the first is
disabled on msg, and the second is not, then this will return
%NULL, not the second feature.
Generates a list of session's features of type feature_type. (If
you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE
for feature_type.)
the #GType of the class of features to get
Returns last DAV error code as returned by the server. Each recognized code is enclosed in "[]" in the returned string, to be able to distinguish between them, in case the server returned multiple codes.
The string is valid until the next request is executed.
Gets list of principal collection href for the uri, or, in case it's %NULL,
for the URI defined in associated #ESource. The out_principal_hrefs are root
collections that contain the principals that are available on the server that
implements this resource.
Free the returned out_principal_hrefs with
g_slist_free_full (entries, g_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().
Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.
the name of the property to get
return location for the property value
This function gets back user data pointers stored via g_object_set_qdata().
A #GQuark, naming the user data pointer
Populates out_certificate_pem and out_certificate_errors with the last values
returned on #SOUP_STATUS_SSL_FAILED error.
Gets supported privileges for the uri, or, in case it's %NULL, for the URI
defined in associated #ESource.
The root node of out_privileges has always %NULL data.
Free the returned out_privileges with e_webdav_session_util_free_privileges()
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Reads a resource identified by uri from the server and writes it
to the stream. The URI cannot reference a collection.
Free returned pointer of out_href and out_etag, if not %NULL, with g_free(),
when no longer needed.
The e_webdav_session_get_data_sync() can be used to read the resource data directly to memory.
URI of the resource to read
optional #GCancellable object, or %NULL
Issues a getctag property request for a collection identified by uri, or,
in case it's %NULL, on the URI defined in associated #ESource. The ctag is
a collection tag, which changes whenever the collection changes (similar
to etag). The getctag is an extension, thus the function can fail when
the server doesn't support it.
Free the returned out_ctag with g_free(), when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Tests if session has at a feature of type feature_type (which can
be the type of either a #SoupSessionFeature, or else a subtype of
some class managed by another feature, such as #SoupAuth or
#SoupRequest).
the #GType of the class of features to check for
Checks whether object has a [floating][floating-ref] reference.
Lists content of the uri, or, in case it's %NULL, of the URI defined
in associated #ESource, which should point to a collection. The flags
influences which properties are read for the resources.
The out_resources is in no particular order.
Free the returned out_resources with
g_slist_free_full (resources, e_webdav_resource_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
requested depth, can be one of %E_WEBDAV_DEPTH_THIS, %E_WEBDAV_DEPTH_THIS_AND_CHILDREN or %E_WEBDAV_DEPTH_INFINITY
a bit-or of #EWebDAVListFlags, claiming what properties to read
optional #GCancellable object, or %NULL
Locks a resource identified by uri, or, in case it's %NULL, by the URI defined
in associated #ESource. It obtains a write lock with the given lock_scope.
The owner is used to identify the lock owner. When it's an http:// or https://,
then it's referenced as DAV:href, otherwise the value is treated as plain text.
If it's %NULL, then the user name from the associated #ESource is used.
The out_lock_token can be refreshed with e_webdav_session_refresh_lock_sync().
Release the lock with e_webdav_session_unlock_sync().
Free the returned out_lock_token with g_free(), when no longer needed.
URI to lock, or %NULL to read from #ESource
an #EWebDAVLockScope to define the scope of the lock
timeout for the lock, in seconds, on 0 to infinity
optional identificator of the owner of the lock, or %NULL
optional #GCancellable object, or %NULL
Locks a resource identified by uri, or, in case it's %NULL, on the URI
defined in associated #ESource.
The out_lock_token can be refreshed with e_webdav_session_refresh_lock_sync().
Release the lock with e_webdav_session_unlock_sync().
Free the returned out_lock_token with g_free(), when no longer needed.
If provided, free the returned out_xml_response with xmlFreeDoc(),
when no longer needed.
URI to lock, or %NULL to read from #ESource
requested depth, can be one of %E_WEBDAV_DEPTH_THIS or %E_WEBDAV_DEPTH_INFINITY
timeout for the lock, in seconds, on 0 to infinity
an XML describing the lock request, with DAV:lockinfo root element
optional #GCancellable object, or %NULL
Creates a new calendar collection identified by uri on the server.
The supports defines what component types can be stored into
the created calendar collection. Only %E_WEBDAV_RESOURCE_SUPPORTS_NONE
and values related to iCalendar content can be used here.
Using %E_WEBDAV_RESOURCE_SUPPORTS_NONE means that everything is supported.
Note that CalDAV RFC 4791 Section 4.2 forbids to create calendar resources under other calendar resources (no nested calendars are allowed).
URI of the collection to create
a human-readable display name to set, or %NULL
a human-readable description of the calendar, or %NULL
a color to set, in format "#RRGGBB", or %NULL
a bit-or of EWebDAVResourceSupports values
optional #GCancellable object, or %NULL
Creates a new address book collection identified by uri on the server.
Note that CardDAV RFC 6352 Section 5.2 forbids to create address book resources under other address book resources (no nested address books are allowed).
URI of the collection to create
a human-readable display name to set, or %NULL
a human-readable description of the address book, or %NULL
optional #GCancellable object, or %NULL
Creates a new generic collection identified by uri on the server.
To create specific collections use e_webdav_session_mkcalendar_sync()
or e_webdav_session_mkcol_addressbook_sync().
URI of the collection to create
optional #GCancellable object, or %NULL
Moves a resource identified by source_uri to destination_uri on the server.
The source_uri can reference also collections.
URI of the resource or collection to copy
URI of the destination
whether can overwrite destination_uri, when it exists
optional #GCancellable object, or %NULL
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().
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().
an HTTP method
a URI string to use for the request
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().
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than g_object_notify().
One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:
enum
{
PROP_0,
PROP_FOO,
PROP_LAST
};
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
0, 100,
50,
G_PARAM_READWRITE);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the #GParamSpec of a property installed on the class of object.
Issues OPTIONS request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource.
The out_capabilities contains a set of returned capabilities. Some known are
defined as E_WEBDAV_CAPABILITY_CLASS_1, and so on. The 'value' of the #GHashTable
doesn't have any particular meaning and the strings are compared case insensitively.
Free the hash table with g_hash_table_destroy(), when no longer needed. The returned
value can be %NULL on success, it's when the server doesn't provide the information.
The out_allows contains a set of allowed methods returned by the server. Some known
are defined as %SOUP_METHOD_OPTIONS, and so on. The 'value' of the #GHashTable
doesn't have any particular meaning and the strings are compared case insensitively.
Free the hash table with g_hash_table_destroy(), when no longer needed. The returned
value can be %NULL on success, it's when the server doesn't provide the information.
URI to issue the request for, or %NULL to read from #ESource
optional #GCancellable object, or %NULL
Issues POST request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource. The Content-Type of the data is set to
application/xml. To POST the data with a different Content-Type use
e_webdav_session_post_with_content_type_sync().
The optional out_content_type can be used to get content type of the response.
Free it with g_free(), when no longer needed.
The optional out_content can be used to get actual result content. Free it
with g_byte_array_free(), when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
data to post to the server
length of data, or -1, when data is NUL-terminated
return location for response Content-Type, or %NULL
return location for response content, or %NULL
optional #GCancellable object, or %NULL
Issues POST request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource.
The optional out_content_type can be used to get content type of the response.
Free it with g_free(), when no longer needed.
The optional out_content can be used to get actual result content. Free it
with g_byte_array_free(), when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
data to post to the server
length of data, or -1, when data is NUL-terminated
a Content-Type of the data, or %NULL, to use application/xml
return location for response Content-Type, or %NULL
return location for response content, or %NULL
optional #GCancellable object, or %NULL
Tells session that an URI from the given hostname may be requested
shortly, and so the session can try to prepare by resolving the
domain name in advance, in order to work more quickly once the URI
is actually requested.
If cancellable is non-%NULL, it can be used to cancel the
resolution. callback will still be invoked in this case, with a
status of %SOUP_STATUS_CANCELLED.
a hostname to be resolved
a #GCancellable object, or %NULL
callback to call with the result, or %NULL
Issues a DAV:principal-property-search for the uri, or, in case it's %NULL,
for the URI defined in associated #ESource. The DAV:principal-property-search
performs a search for all principals whose properties contain character data
that matches the search criteria match_value in match_property property
of namespace match_ns_uri.
By default, the function searches all members (at any depth) of the collection
identified by the uri. If apply_to_principal_collection_set is set to %TRUE,
the search is applied instead to each collection returned by
e_webdav_session_get_principal_collection_set_sync() for the uri.
The out_principals is a #GSList of #EWebDAVResource, where the kind
is set to %E_WEBDAV_RESOURCE_KIND_PRINCIPAL and only href with displayname
are filled. All other members of #EWebDAVResource are not set.
Free the returned out_principals with
g_slist_free_full (principals, e_webdav_resource_free);
when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
whether to apply to principal-collection-set
namespace URI of the property to search in, or %NULL for %E_WEBDAV_NS_DAV
name of the property to search in
a string value to search for
optional #GCancellable object, or %NULL
Issues PROPFIND request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource. On success, calls func for each returned
DAV:propstat.
The xml can be %NULL, in which case the server should behave like DAV:allprop request.
URI to issue the request for, or %NULL to read from #ESource
requested depth, can be one of %E_WEBDAV_DEPTH_THIS, %E_WEBDAV_DEPTH_THIS_AND_CHILDREN or %E_WEBDAV_DEPTH_INFINITY
the request itself, as an #EXmlDocument, the root element should be DAV:propfind, or %NULL
optional #GCancellable object, or %NULL
Issues PROPPATCH request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource, with the changes. The order of requested changes
inside xml is significant, unlike on other places.
URI to issue the request for, or %NULL to read from #ESource
an #EXmlDocument with request changes, its root element should be DAV:propertyupdate
optional #GCancellable object, or %NULL
Writes data to a resource identified by uri to the server. The URI cannot
reference a collection.
The etag argument is used to avoid clashes when overwriting existing
resources. It can contain three values:
Note that the actual usage of etag is also influenced by #ESourceWebdav:avoid-ifmatch
property of the associated #ESource.
The out_href, if provided, is filled with the resulting URI
of the written resource. It can be different from the uri when the server
redirected to a different location.
The out_etag contains ETag of the resource after it had been saved.
To write large data use e_webdav_session_put_sync() instead.
URI of the resource to write
an ETag of the resource, if it's an existing resource, or %NULL
Content-Type of the bytes to be written
actual bytes to be written
how many bytes to write, or -1, when the bytes is NUL-terminated
optional #GCancellable object, or %NULL
Writes data from stream to a resource identified by uri to the server.
The URI cannot reference a collection.
The etag argument is used to avoid clashes when overwriting existing
resources. It can contain three values:
Note that the actual behaviour is also influenced by #ESourceWebdav:avoid-ifmatch property of the associated #ESource.
The out_href, if provided, is filled with the resulting URI
of the written resource. It can be different from the uri when the server
redirected to a different location.
The out_etag contains ETag of the resource after it had been saved.
The stream should support also #GSeekable interface, because the data
send can require restart of the send due to redirect or other reasons.
This method uses Transfer-Encoding:chunked, in contrast to the e_webdav_session_put_data_sync(), which writes data stored in memory like any other request.
URI of the resource to write
an ETag of the resource, if it's an existing resource, or %NULL
Content-Type of the bytes to be written
a #GInputStream with data to be written
optional #GCancellable object, or %NULL
Queues the message msg for asynchronously sending the request and
receiving a response in the current thread-default #GMainContext.
If msg has been processed before, any resources related to the
time it was last sent are freed.
Upon message completion, the callback specified in callback will
be invoked. If after returning from this callback the message has not
been requeued, msg will be unreffed.
(The behavior above applies to a plain #SoupSession; if you are using #SoupSessionAsync or #SoupSessionSync, then the #GMainContext that is used depends on the settings of #SoupSession:async-context and #SoupSession:use-thread-context, and for #SoupSessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated #GMainContext.)
Contrast this method with soup_session_send_async(), which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
Updates msg's URI according to its status code and "Location"
header, and requeues it on session. Use this when you have set
%SOUP_MESSAGE_NO_REDIRECT on a message, but have decided to allow a
particular redirection to occur, or if you want to allow a
redirection that #SoupSession will not perform automatically (eg,
redirecting a non-safe method such as DELETE).
If msg's status code indicates that it should be retried as a GET
request, then msg will be modified accordingly.
If msg has already been redirected too many times, this will
cause it to fail with %SOUP_STATUS_TOO_MANY_REDIRECTS.
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
Refreshes existing lock lock_token for a resource identified by uri,
or, in case it's %NULL, on the URI defined in associated #ESource.
The lock_token is returned from e_webdav_session_lock_sync() and
the uri should be the same as that used with e_webdav_session_lock_sync().
URI to lock, or %NULL to read from #ESource
token of an existing lock
timeout for the lock, in seconds, on 0 to infinity
optional #GCancellable object, or %NULL
Removes feature's functionality from session.
a feature that has previously been added to session
Removes all features of type feature_type (or any subclass of
feature_type) from session. You can also remove standard features
from the session at construct time by using the
%SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.
a #GType
Tries to read detailed error information from response_data,
if not provided, then from request's response_body. If the detailed
error cannot be found, then does nothing, otherwise frees the content
of inout_error, if any, and then populates it with an error message
prefixed with prefix.
The prefix might be of form "Failed to something", because the resulting
error message will be:
"Failed to something: HTTP error code XXX (reason_phrase): detailed_error".
When prefix is %NULL, the error message will be:
"Failed with HTTP error code XXX (reason phrase): detailed_error".
As the caller might not be interested in errors, also the inout_error
can be %NULL, in which case the function does nothing.
a #SoupRequestHTTP
received response data, or %NULL
whether to ignore multistatus responses
error message prefix, used when replacing, or %NULL
Issues REPORT request on the provided uri, or, in case it's %NULL, on the URI
defined in associated #ESource. On success, calls func for each returned
DAV:propstat.
The report can result in a multistatus response, but also to raw data. In case
the func is provided and the result is a multistatus response, then it is traversed
using this func.
The optional out_content_type can be used to get content type of the response.
Free it with g_free(), when no longer needed.
The optional out_content can be used to get actual result content. Free it
with g_byte_array_free(), when no longer needed.
URI to issue the request for, or %NULL to read from #ESource
requested depth, can be %NULL, then no Depth header is sent
the request itself, as an #EXmlDocument
return location for response Content-Type, or %NULL
return location for response content, or %NULL
optional #GCancellable object, or %NULL
Creates a #SoupRequest for retrieving uri_string.
a URI, in string form
Creates a #SoupRequest for retrieving uri_string, which must be an
"http" or "https" URI (or another protocol listed in session's
#SoupSession:http-aliases or #SoupSession:https-aliases).
an HTTP method
a URI, in string form
Creates a #SoupRequest for retrieving uri, which must be an
"http" or "https" URI (or another protocol listed in session's
#SoupSession:http-aliases or #SoupSession:https-aliases).
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Synchronously sends msg and waits for the beginning of a response.
On success, a #GInputStream will be returned which you can use to
read the response body. ("Success" here means only that an HTTP
response was received and understood; it does not necessarily mean
that a 2xx class status code was received.)
If non-%NULL, cancellable can be used to cancel the request;
soup_session_send() will return a %G_IO_ERROR_CANCELLED error. Note
that with requests that have side effects (eg,
If msg is requeued due to a redirect or authentication, the
initial (3xx/401/407) response body will be suppressed, and
soup_session_send() will only return once a final response has been
received.
Contrast this method with soup_session_send_message(), which also synchronously sends a #SoupMessage, but doesn't return until the response has been completely read.
(Note that this method cannot be called on the deprecated #SoupSessionAsync subclass.)
a #SoupMessage
a #GCancellable
Asynchronously sends msg and waits for the beginning of a
response. When callback is called, then either msg has been sent,
and its response headers received, or else an error has occurred.
Call soup_session_send_finish() to get a #GInputStream for reading
the response body.
See soup_session_send() for more details on the general semantics.
Contrast this method with soup_session_queue_message(), which also asynchronously sends a #SoupMessage, but doesn't invoke its callback until the response has been completely read.
(Note that this method cannot be called on the deprecated #SoupSessionSync subclass, and can only be called on #SoupSessionAsync if you have set the #SoupSession:use-thread-context property.)
a #SoupMessage
a #GCancellable
the callback to invoke
Gets the response to a soup_session_send_async() call and (if successful), returns a #GInputStream that can be used to read the response body.
the #GAsyncResult passed to your callback
Synchronously send msg. This call will not return until the
transfer is finished successfully or there is an unrecoverable
error.
Unlike with soup_session_queue_message(), msg is not freed upon
return.
(Note that if you call this method on a #SoupSessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)
Contrast this method with soup_session_send(), which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
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.
a #SoupRequestHTTP to send
optional #GCancellable object, or %NULL
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 #ESoupSession: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.
a #SoupRequestHTTP to send
optional #GCancellable object, or %NULL
Changes Access Control List (ACL) for the uri, or, in case it's %NULL,
for the URI defined in associated #ESource.
Make sure that the entries satisfy ACL restrictions, as returned
by e_webdav_session_get_acl_restrictions_sync(). The order in the entries
is preserved. It cannot contain any %E_WEBDAV_ACE_FLAG_PROTECTED,
nor E_WEBDAV_ACE_FLAG_INHERITED, items.
Use e_webdav_session_get_acl_sync() to read currently known ACL entries, remove from the list those protected and inherited, and then modify the rest with the required changed.
Note this function doesn't support general %E_WEBDAV_ACE_PRINCIPAL_PROPERTY and returns %G_IO_ERROR_NOT_SUPPORTED error when any such is tried to be written.
In case the returned entries contain any %E_WEBDAV_ACE_PRINCIPAL_PROPERTY, or there's a need to write such Access Control Entry, then do not use e_webdav_session_get_acl_sync(), neither e_webdav_session_set_acl_sync(), and write more generic implementation.
URI to issue the request for, or %NULL to read from #ESource
entries to write
optional #GCancellable object, or %NULL
Sets credentials to use for connection. Using %NULL for credentials
unsets previous value.
an #ENamedParameters with credentials to use, or %NULL
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a #GQuark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the #GQuark storage growing unbounded.
name of the key
data to associate with that key
Sets a property on an object.
the name of the property to set
the value
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.
logging level to setup, or %NULL
"Steals" the HTTP connection associated with msg from session.
This happens immediately, regardless of the current state of the
connection, and msg's callback will not be called. You can steal
the connection from a #SoupMessage signal handler if you need to
wait for part or all of the response to be received first.
Calling this function may cause msg to be freed if you are not
holding any other reference to it.
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().
A #GQuark, naming the user data pointer
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Traverses a CALDAV:mkcalendar-response response and calls func for each returned DAV:propstat.
The message, if provided, is used to verify that the response is an XML Content-Type.
It's used to get the request URI as well.
an optional #SoupMessage corresponding to the response, or %NULL
a #GByteArray containing CALDAV:mkcalendar-response response
Traverses a DAV:mkcol-response response and calls func for each returned DAV:propstat.
The message, if provided, is used to verify that the response is an XML Content-Type.
It's used to get the request URI as well.
an optional #SoupMessage corresponding to the response, or %NULL
a #GByteArray containing DAV:mkcol-response response
Traverses a DAV:multistatus response and calls func for each returned DAV:propstat.
The message, if provided, is used to verify that the response is a multi-status
and that the Content-Type is properly set. It's used to get a request URI as well.
an optional #SoupMessage corresponding to the response, or %NULL
a #GByteArray containing DAV:multistatus response
Releases (unlocks) existing lock lock_token for a resource identified by uri,
or, in case it's %NULL, on the URI defined in associated #ESource.
The lock_token is returned from e_webdav_session_lock_sync() and
the uri should be the same as that used with e_webdav_session_lock_sync().
URI to lock, or %NULL to read from #ESource
token of an existing lock
optional #GCancellable object, or %NULL
Resumes HTTP I/O on msg. Use this to resume after calling
soup_session_pause_message().
If msg is being sent via blocking I/O, this will resume reading or
writing immediately. If msg is using non-blocking I/O, then
reading or writing won't resume until you return to the main loop.
This may only be called for asynchronous messages (those sent on a #SoupSessionAsync or using soup_session_queue_message()).
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.
Updates properties (set/remove) on the provided uri, or, in case it's %NULL,
on the URI defined in associated #ESource, with the changes. The order
of changes is significant, unlike on other places.
This function supports only flat properties, those not under other element. To support more complex property tries use e_webdav_session_proppatch_sync() directly.
URI to issue the request for, or %NULL to read from #ESource
a #GSList with request changes
optional #GCancellable object, or %NULL
Causes session to immediately finish processing msg (regardless
of its current state) with a final status_code of status_code. You
may call this at any time after handing msg off to session; if
session has started sending the request but has not yet received
the complete response, then it will close the request's connection.
Note that with requests that have side effects (eg,
If the message is cancelled while its response body is being read,
then the response body in msg will be left partially-filled-in.
The response headers, on the other hand, will always be either
empty or complete.
Beware that with the deprecated #SoupSessionAsync, messages queued with soup_session_queue_message() will have their callbacks invoked before soup_session_cancel_message() returns. The plain #SoupSession does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.
the message to cancel
status code to set on msg (generally %SOUP_STATUS_CANCELLED)
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
Queues the message msg for asynchronously sending the request and
receiving a response in the current thread-default #GMainContext.
If msg has been processed before, any resources related to the
time it was last sent are freed.
Upon message completion, the callback specified in callback will
be invoked. If after returning from this callback the message has not
been requeued, msg will be unreffed.
(The behavior above applies to a plain #SoupSession; if you are using #SoupSessionAsync or #SoupSessionSync, then the #GMainContext that is used depends on the settings of #SoupSession:async-context and #SoupSession:use-thread-context, and for #SoupSessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated #GMainContext.)
Contrast this method with soup_session_send_async(), which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
Synchronously send msg. This call will not return until the
transfer is finished successfully or there is an unrecoverable
error.
Unlike with soup_session_queue_message(), msg is not freed upon
return.
(Note that if you call this method on a #SoupSessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)
Contrast this method with soup_session_send(), which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
#GClosure to watch
Asynchronously creates a #SoupWebsocketConnection to communicate with a remote server.
All necessary WebSocket-related headers will be added to msg, and
it will then be sent and asynchronously processed normally
(including handling of redirection and HTTP authentication).
If the server returns "101 Switching Protocols", then msg's status
code and response headers will be updated, and then the WebSocket
handshake will be completed. On success,
soup_session_websocket_connect_finish() will return a new
#SoupWebsocketConnection. On failure it will return a #GError.
If the server returns a status other than "101 Switching
Protocols", then msg will contain the complete response headers
and body from the server's response, and
soup_session_websocket_connect_finish() will return
%SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET.
#SoupMessage indicating the WebSocket server to connect to
origin of the connection
a %NULL-terminated array of protocols supported
a #GCancellable
the callback to invoke
Gets the #SoupWebsocketConnection response to a soup_session_websocket_connect_async() call and (if successful), returns a #SoupWebsocketConnection that can be used to communicate with the server.
the #GAsyncResult passed to your callback
Find the #GParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
#GTypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the #GParamSpec for the new property
Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Creates a new #EWebDAVSession associated with given source.
The #EWebDAVSession uses an #ESourceWebdav extension on certain
places when it's defined for the source.
an #ESource
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.
an #ESource
Creates a #SoupSession with the default options.
Creates a new instance of a #GObject subtype and sets its properties.
Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
the type id of the #GObject subtype to instantiate
an array of #GParameter
Compares two hrefs and return whether they reference the same item on the server. The comparison is done in a relaxed way, not considering scheme part and comparing the host name case insensitively, while the path case sensitively. It also ignores the username/password information in the hostname part, if it's included. The function doesn't decode any URI-encoded characters.
the first href
the second href
Dequotes text, if it's enclosed in double-quotes. The function
changes text, it doesn't allocate new string. The function does
nothing when the text is not enclosed in double-quotes.
text to dequote
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.
an HTTP status code
preferred string to use for the message, or %NULL
Contains only private data that should be read and manipulated using the functions below.