Top | ![]() |
![]() |
![]() |
![]() |
The EWebDAVSession is a class to work with WebDAV (RFC 4918), CalDAV (RFC 4791) or CardDAV (RFC 6352) servers, providing API for common requests/responses, on top of an ESoupSession. It supports also Access Control Protocol (RFC 3744).
EWebDAVResource * e_webdav_resource_new (EWebDAVResourceKind kind
,guint32 supports
,const gchar *href
,const gchar *etag
,const gchar *display_name
,const gchar *content_type
,gsize content_length
,glong creation_date
,glong last_modified
,const gchar *description
,const gchar *color
);
Some values of the resource are not always valid, depending on the kind
,
but also whether server stores such values and whether it had been asked
for them to be fetched.
The etag
for E_WEBDAV_RESOURCE_KIND_COLLECTION
can be a change tag instead.
kind |
an EWebDAVResourceKind of the resource |
|
supports |
bit-or of EWebDAVResourceSupports values |
|
href |
href of the resource |
|
etag |
optional ETag of the resource, or |
[nullable] |
display_name |
optional display name of the resource, or |
[nullable] |
content_type |
optional Content-Type of the resource, or |
[nullable] |
content_length |
optional Content-Length of the resource, or 0 |
|
creation_date |
optional date of creation of the resource, or 0 |
|
last_modified |
optional last modified time of the resource, or 0 |
|
description |
optional description of the resource, or |
[nullable] |
color |
optional color of the resource, or |
[nullable] |
A newly created EWebDAVResource, prefilled with
given values. Free it with e_webdav_resource_free()
, when no longer needed.
[transfer full]
Since: 3.26
EWebDAVResource *
e_webdav_resource_copy (const EWebDAVResource *src
);
A new EWebDAVResource prefilled with
the same values as src
, or NULL
, when src
is NULL
.
Free it with e_webdav_resource_free()
, when no longer needed.
[transfer full]
Since: 3.26
void
e_webdav_resource_free (gpointer ptr
);
Frees an EWebDAVResource previously created with e_webdav_resource_new()
or e_webdav_resource_copy()
. The function does nothing, if ptr
is NULL
.
Since: 3.26
gboolean (*EWebDAVPropstatTraverseFunc) (EWebDAVSession *webdav
,xmlXPathContext *xpath_ctx
,const gchar *xpath_prop_prefix
,const SoupURI *request_uri
,const gchar *href
,guint status_code
,gpointer user_data
);
A callback function for e_webdav_session_propfind_sync()
,
e_webdav_session_report_sync()
and other XML response with DAV:propstat
elements traversal functions.
The xpath_prop_prefix
can be NULL
only once, for the first time,
which is meant to let the caller setup the xpath_ctx
, like to register
its own namespaces to it with e_xml_xpath_context_register_namespaces()
.
All other invocations of the function will have xpath_prop_prefix
non-NULL
.
webdav |
||
xpath_ctx |
an xmlXPathContextPtr |
|
xpath_prop_prefix |
an XPath prefix for the current prop element, without trailing forward slash. |
[nullable] |
request_uri |
a SoupURI, containing the request URI, maybe redirected by the server |
|
href |
a full URI to which the property belongs, or |
[nullable] |
status_code |
an HTTP status code for this property |
|
user_data |
user data, as passed to |
Since: 3.26
EWebDAVPropertyChange * e_webdav_property_change_new_set (const gchar *ns_uri
,const gchar *name
,const gchar *value
);
Creates a new EWebDAVPropertyChange of kind E_WEBDAV_PROPERTY_SET
,
which is used to modify or set the property value. The value
is a string
representation of the value to store. It can be NULL
, but it means
an empty value, not to remove it. To remove property use
e_webdav_property_change_new_remove()
instead.
ns_uri |
namespace URI of the property |
|
name |
name of the property |
|
value |
value of the property, or |
[nullable] |
A new EWebDAVPropertyChange. Free it with
e_webdav_property_change_free()
, when no longer needed.
[transfer full]
Since: 3.26
EWebDAVPropertyChange * e_webdav_property_change_new_remove (const gchar *ns_uri
,const gchar *name
);
Creates a new EWebDAVPropertyChange of kind E_WEBDAV_PROPERTY_REMOVE
,
which is used to remove the given property. To change property value
use e_webdav_property_change_new_set()
instead.
A new EWebDAVPropertyChange. Free it with
e_webdav_property_change_free()
, when no longer needed.
[transfer full]
Since: 3.26
EWebDAVPropertyChange *
e_webdav_property_change_copy (const EWebDAVPropertyChange *src
);
A new EWebDAVPropertyChange prefilled with
the same values as src
, or NULL
, when src
is NULL
.
Free it with e_webdav_property_change_free()
, when no longer needed.
[transfer full]
Since: 3.26
void
e_webdav_property_change_free (gpointer ptr
);
Frees an EWebDAVPropertyChange previously created with e_webdav_property_change_new_set()
,
e_webdav_property_change_new_remove()
or or e_webdav_property_change_copy()
.
The function does nothing, if ptr
is NULL
.
Since: 3.26
EWebDAVPrivilege * e_webdav_privilege_new (const gchar *ns_uri
,const gchar *name
,const gchar *description
,EWebDAVPrivilegeKind kind
,EWebDAVPrivilegeHint hint
);
Describes one privilege entry. The hint
can be E_WEBDAV_PRIVILEGE_HINT_UNKNOWN
for privileges which are not known to the EWebDAVSession. It's possible, because
the servers can define their own privileges. The hint is also tried to pair with
known hnts when it's E_WEBDAV_PRIVILEGE_HINT_UNKNOWN
.
The ns_uri
and name
can be NULL
only if the hint
is one of the known
privileges. Otherwise it's an error to pass either of the two as NULL
.
ns_uri |
a namespace URI. |
[nullable] |
name |
element name. |
[nullable] |
description |
human read-able description, or |
[nullable] |
kind |
||
hint |
A newly created EWebDAVPrivilege, prefilled with
given values. Free it with e_webdav_privilege_free()
, when no longer needed.
[transfer full]
Since: 3.26
EWebDAVPrivilege *
e_webdav_privilege_copy (const EWebDAVPrivilege *src
);
A new EWebDAVPrivilege prefilled with
the same values as src
, or NULL
, when src
is NULL
.
Free it with e_webdav_privilege_free()
, when no longer needed.
[transfer full]
Since: 3.26
void
e_webdav_privilege_free (gpointer ptr
);
Frees an EWebDAVPrivilege previously created with e_webdav_privilege_new()
or e_webdav_privilege_copy()
. The function does nothing, if ptr
is NULL
.
Since: 3.26
EWebDAVAccessControlEntry * e_webdav_access_control_entry_new (EWebDAVACEPrincipalKind principal_kind
,const gchar *principal_href
,guint32 flags
,const gchar *inherited_href
);
Describes one Access Control Entry (ACE).
The flags
should always contain either E_WEBDAV_ACE_FLAG_GRANT
or
E_WEBDAV_ACE_FLAG_DENY
value.
Use e_webdav_access_control_entry_append_privilege()
to add respective
privileges to the entry.
principal_kind |
||
principal_href |
principal href; should be set only if |
[nullable] |
flags |
bit-or of EWebDAVACEFlag values |
|
inherited_href |
href of the resource from which inherits; should be set only if |
[nullable] |
A newly created EWebDAVAccessControlEntry, prefilled with
given values. Free it with e_webdav_access_control_entry_free()
, when no longer needed.
[transfer full]
Since: 3.26
EWebDAVAccessControlEntry *
e_webdav_access_control_entry_copy (const EWebDAVAccessControlEntry *src
);
A new EWebDAVAccessControlEntry prefilled with
the same values as src
, or NULL
, when src
is NULL
.
Free it with e_webdav_access_control_entry_free()
, when no longer needed.
[transfer full]
Since: 3.26
void
e_webdav_access_control_entry_free (gpointer ptr
);
Frees an EWebDAVAccessControlEntry previously created with e_webdav_access_control_entry_new()
or e_webdav_access_control_entry_copy()
. The function does nothing, if ptr
is NULL
.
Since: 3.26
void e_webdav_access_control_entry_append_privilege (EWebDAVAccessControlEntry *ace
,EWebDAVPrivilege *privilege
);
Appends a new privilege
to the list of privileges for the ace
.
The function assumes ownership of the privilege
, which is freed
together with the ace
.
Since: 3.26
GSList *
e_webdav_access_control_entry_get_privileges
(EWebDAVAccessControlEntry *ace
);
A GSList of EWebDAVPrivilege
with the list of privileges for the ace
. The reurned GSList, together with its data
is owned by the ace
.
[element-type EWebDAVPrivilege][transfer none]
Since: 3.26
EWebDAVSession *
e_webdav_session_new (ESource *source
);
Creates a new EWebDAVSession associated with given source
.
The EWebDAVSession uses an ESourceWebdav extension on certain
places when it's defined for the source
.
Since: 3.26
SoupRequestHTTP * e_webdav_session_new_request (EWebDAVSession *webdav
,const gchar *method
,const gchar *uri
,GError **error
);
webdav |
||
method |
an HTTP method |
|
uri |
URI to create the request for, or |
[nullable] |
error |
return location for a GError, or |
A new SoupRequestHTTP for the given uri
, or, when NULL
,
for the URI stored in the associated ESource. Free the returned structure
with g_object_unref()
, when no longer needed.
[transfer full]
Since: 3.26
gboolean e_webdav_session_replace_with_detailed_error (EWebDAVSession *webdav
,SoupRequestHTTP *request
,const GByteArray *response_data
,gboolean ignore_multistatus
,const gchar *prefix
,GError **inout_error
);
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.
webdav |
||
request |
||
response_data |
received response data, or |
[nullable] |
ignore_multistatus |
whether to ignore multistatus responses |
|
prefix |
error message prefix, used when replacing, or |
[nullable] |
inout_error |
a GError variable to replace content to, or |
[inout][nullable][transfer full] |
Since: 3.26
gchar * e_webdav_session_ensure_full_uri (EWebDAVSession *webdav
,const SoupURI *request_uri
,const gchar *href
);
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.
webdav |
||
request_uri |
a SoupURI to which the |
[nullable] |
href |
a possibly path-only href |
Since: 3.24
gboolean e_webdav_session_options_sync (EWebDAVSession *webdav
,const gchar *uri
,GHashTable **out_capabilities
,GHashTable **out_allows
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_capabilities |
return location for DAV capabilities. |
[out][transfer full] |
out_allows |
return location for allowed operations. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_post_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *data
,gsize data_length
,gchar **out_content_type
,GByteArray **out_content
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
data |
data to post to the server |
|
data_length |
length of |
|
out_content_type |
return location for response Content-Type, or |
[nullable][transfer full] |
out_content |
return location for response content, or |
[nullable][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_propfind_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *depth
,const EXmlDocument *xml
,EWebDAVPropstatTraverseFunc func
,gpointer func_user_data
,GCancellable *cancellable
,GError **error
);
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 provided XPath context has registered E_WEBDAV_NS_DAV
namespace
with prefix "D". It doesn't have any other namespace registered.
The func
is called always at least once, with NULL
xpath_prop_prefix, which
is meant to let the caller setup the xpath_ctx, like to register its own namespaces
to it with e_xml_xpath_context_register_namespaces()
. All other invocations of func
will have xpath_prop_prefix non-NULL
.
The xml
can be NULL
, in which case the server should behave like DAV:allprop request.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
depth |
requested depth, can be one of |
|
xml |
the request itself, as an EXmlDocument, the root element should be DAV:propfind, or |
[nullable] |
func |
an EWebDAVPropstatTraverseFunc function to call for each DAV:propstat in the multistatus response. |
[scope call] |
func_user_data |
user data passed to |
[closure func] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_proppatch_sync (EWebDAVSession *webdav
,const gchar *uri
,const EXmlDocument *xml
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
xml |
an EXmlDocument with request changes, its root element should be DAV:propertyupdate |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_report_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *depth
,const EXmlDocument *xml
,EWebDAVPropstatTraverseFunc func
,gpointer func_user_data
,gchar **out_content_type
,GByteArray **out_content
,GCancellable *cancellable
,GError **error
);
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 provided XPath context has registered E_WEBDAV_NS_DAV
namespace
with prefix "D". It doesn't have any other namespace registered.
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 func
is called always at least once, with NULL
xpath_prop_prefix,
which is meant to let the caller setup the xpath_ctx, like to register its own namespaces
to it with e_xml_xpath_context_register_namespaces()
. All other invocations of func
will have xpath_prop_prefix non-NULL
.
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
depth |
requested depth, can be |
[nullable] |
xml |
the request itself, as an EXmlDocument |
|
func |
an EWebDAVPropstatTraverseFunc function to call for each DAV:propstat in the multistatus response, or |
[nullable][scope call] |
func_user_data |
user data passed to |
[closure func] |
out_content_type |
return location for response Content-Type, or |
[nullable][transfer full] |
out_content |
return location for response content, or |
[nullable][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_mkcol_sync (EWebDAVSession *webdav
,const gchar *uri
,GCancellable *cancellable
,GError **error
);
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()
.
webdav |
||
uri |
URI of the collection to create |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_mkcol_addressbook_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *display_name
,const gchar *description
,GCancellable *cancellable
,GError **error
);
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).
webdav |
||
uri |
URI of the collection to create |
|
display_name |
a human-readable display name to set, or |
[nullable] |
description |
a human-readable description of the address book, or |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_mkcalendar_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *display_name
,const gchar *description
,const gchar *color
,guint32 supports
,GCancellable *cancellable
,GError **error
);
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).
webdav |
||
uri |
URI of the collection to create |
|
display_name |
a human-readable display name to set, or |
[nullable] |
description |
a human-readable description of the calendar, or |
[nullable] |
color |
a color to set, in format "#RRGGBB", or |
[nullable] |
supports |
a bit-or of EWebDAVResourceSupports values |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_sync (EWebDAVSession *webdav
,const gchar *uri
,gchar **out_href
,gchar **out_etag
,GOutputStream *out_stream
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI of the resource to read |
|
out_href |
optional return location for href of the resource, or |
[out][nullable][transfer full] |
out_etag |
optional return location for etag of the resource, or |
[out][nullable][transfer full] |
out_stream |
a GOutputStream to write data to. |
[out caller-allocates] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_data_sync (EWebDAVSession *webdav
,const gchar *uri
,gchar **out_href
,gchar **out_etag
,gchar **out_bytes
,gsize *out_length
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI of the resource to read |
|
out_href |
optional return location for href of the resource, or |
[out][nullable][transfer full] |
out_etag |
optional return location for etag of the resource, or |
[out][nullable][transfer full] |
out_bytes |
return location for bytes being read. |
[out][transfer full] |
out_length |
option return location for length of bytes being read, or |
[out][nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_put_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *etag
,const gchar *content_type
,GInputStream *stream
,gchar **out_href
,gchar **out_etag
,GCancellable *cancellable
,GError **error
);
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:
NULL
- to write completely new resource
empty string - write new resource or overwrite any existing, regardless changes on the server
valid ETag - overwrite existing resource only if it wasn't changed on the server.
Note that the actual behaviour is also influenced by “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.
webdav |
||
uri |
URI of the resource to write |
|
etag |
an ETag of the resource, if it's an existing resource, or |
[nullable] |
content_type |
Content-Type of the |
|
stream |
a GInputStream with data to be written |
|
out_href |
optional return location for href of the resource, or |
[out][nullable][transfer full] |
out_etag |
optional return location for etag of the resource, or |
[out][nullable][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_put_data_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *etag
,const gchar *content_type
,const gchar *bytes
,gsize length
,gchar **out_href
,gchar **out_etag
,GCancellable *cancellable
,GError **error
);
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:
NULL
- to write completely new resource
empty string - write new resource or overwrite any existing, regardless changes on the server
valid ETag - overwrite existing resource only if it wasn't changed on the server.
Note that the actual usage of etag
is also influenced by “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.
webdav |
||
uri |
URI of the resource to write |
|
etag |
an ETag of the resource, if it's an existing resource, or |
[nullable] |
content_type |
Content-Type of the |
|
bytes |
actual bytes to be written |
|
length |
how many bytes to write, or -1, when the |
|
out_href |
optional return location for href of the resource, or |
[out][nullable][transfer full] |
out_etag |
optional return location for etag of the resource, or |
[out][nullable][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_delete_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *depth
,const gchar *etag
,GCancellable *cancellable
,GError **error
);
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 “avoid-ifmatch”
property of the associated ESource.
webdav |
||
uri |
URI of the resource to delete |
|
depth |
optional requested depth, can be one of |
[nullable] |
etag |
an optional ETag of the resource, or |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_copy_sync (EWebDAVSession *webdav
,const gchar *source_uri
,const gchar *destination_uri
,const gchar *depth
,gboolean can_overwrite
,GCancellable *cancellable
,GError **error
);
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
).
webdav |
||
source_uri |
URI of the resource or collection to copy |
|
destination_uri |
URI of the destination |
|
depth |
requested depth, can be one of |
|
can_overwrite |
whether can overwrite |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_move_sync (EWebDAVSession *webdav
,const gchar *source_uri
,const gchar *destination_uri
,gboolean can_overwrite
,GCancellable *cancellable
,GError **error
);
Moves a resource identified by source_uri
to destination_uri
on the server.
The source_uri
can reference also collections.
webdav |
||
source_uri |
URI of the resource or collection to copy |
|
destination_uri |
URI of the destination |
|
can_overwrite |
whether can overwrite |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_lock_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *depth
,gint32 lock_timeout
,const EXmlDocument *xml
,gchar **out_lock_token
,xmlDoc **out_xml_response
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to lock, or |
[nullable] |
depth |
requested depth, can be one of |
|
lock_timeout |
timeout for the lock, in seconds, on 0 to infinity |
|
xml |
an XML describing the lock request, with DAV:lockinfo root element |
|
out_lock_token |
return location of the obtained or refreshed lock token. |
[out][transfer full] |
out_xml_response |
optional return location for the server response as xmlDocPtr. |
[out][nullable][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_refresh_lock_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *lock_token
,gint32 lock_timeout
,GCancellable *cancellable
,GError **error
);
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()
.
webdav |
||
uri |
URI to lock, or |
[nullable] |
lock_token |
token of an existing lock |
|
lock_timeout |
timeout for the lock, in seconds, on 0 to infinity |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_unlock_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *lock_token
,GCancellable *cancellable
,GError **error
);
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()
.
webdav |
||
uri |
URI to lock, or |
[nullable] |
lock_token |
token of an existing lock |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_traverse_multistatus_response (EWebDAVSession *webdav
,const SoupMessage *message
,const GByteArray *xml_data
,EWebDAVPropstatTraverseFunc func
,gpointer func_user_data
,GError **error
);
Traverses a DAV:multistatus response and calls func
for each returned DAV:propstat.
The provided XPath context has registered E_WEBDAV_NS_DAV
namespace with prefix "D".
It doesn't have any other namespace registered.
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.
The func
is called always at least once, with NULL
xpath_prop_prefix, which
is meant to let the caller setup the xpath_ctx, like to register its own namespaces
to it with e_xml_xpath_context_register_namespaces()
. All other invocations of func
will have xpath_prop_prefix non-NULL
.
webdav |
||
message |
an optional SoupMessage corresponding to the response, or |
[nullable] |
xml_data |
a GByteArray containing DAV:multistatus response |
|
func |
an EWebDAVPropstatTraverseFunc function to call for each DAV:propstat in the multistatus response. |
[scope call] |
func_user_data |
user data passed to |
[closure func] |
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_traverse_mkcol_response (EWebDAVSession *webdav
,const SoupMessage *message
,const GByteArray *xml_data
,EWebDAVPropstatTraverseFunc func
,gpointer func_user_data
,GError **error
);
Traverses a DAV:mkcol-response response and calls func
for each returned DAV:propstat.
The provided XPath context has registered E_WEBDAV_NS_DAV
namespace with prefix "D".
It doesn't have any other namespace registered.
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.
The func
is called always at least once, with NULL
xpath_prop_prefix, which
is meant to let the caller setup the xpath_ctx, like to register its own namespaces
to it with e_xml_xpath_context_register_namespaces()
. All other invocations of func
will have xpath_prop_prefix non-NULL
.
webdav |
||
message |
an optional SoupMessage corresponding to the response, or |
[nullable] |
xml_data |
a GByteArray containing DAV:mkcol-response response |
|
func |
an EWebDAVPropstatTraverseFunc function to call for each DAV:propstat in the response. |
[scope call] |
func_user_data |
user data passed to |
[closure func] |
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_traverse_mkcalendar_response (EWebDAVSession *webdav
,const SoupMessage *message
,const GByteArray *xml_data
,EWebDAVPropstatTraverseFunc func
,gpointer func_user_data
,GError **error
);
Traverses a CALDAV:mkcalendar-response response and calls func
for each returned DAV:propstat.
The provided XPath context has registered E_WEBDAV_NS_DAV
namespace with prefix "D" and
E_WEBDAV_NS_CALDAV
namespace with prefix "C". It doesn't have any other namespace registered.
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.
The func
is called always at least once, with NULL
xpath_prop_prefix, which
is meant to let the caller setup the xpath_ctx, like to register its own namespaces
to it with e_xml_xpath_context_register_namespaces()
. All other invocations of func
will have xpath_prop_prefix non-NULL
.
webdav |
||
message |
an optional SoupMessage corresponding to the response, or |
[nullable] |
xml_data |
a GByteArray containing CALDAV:mkcalendar-response response |
|
func |
an EWebDAVPropstatTraverseFunc function to call for each DAV:propstat in the response. |
[scope call] |
func_user_data |
user data passed to |
[closure func] |
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_getctag_sync (EWebDAVSession *webdav
,const gchar *uri
,gchar **out_ctag
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_ctag |
return location for the ctag. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_list_sync (EWebDAVSession *webdav
,const gchar *uri
,const gchar *depth
,guint32 flags
,GSList **out_resources
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
depth |
requested depth, can be one of |
|
flags |
a bit-or of EWebDAVListFlags, claiming what properties to read |
|
out_resources |
return location for the resources. |
[out][transfer full][element-type EWebDAVResource] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_update_properties_sync (EWebDAVSession *webdav
,const gchar *uri
,const GSList *changes
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
changes |
a GSList with request changes. |
[element-type EWebDAVResource] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_lock_resource_sync (EWebDAVSession *webdav
,const gchar *uri
,EWebDAVLockScope lock_scope
,gint32 lock_timeout
,const gchar *owner
,gchar **out_lock_token
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to lock, or |
[nullable] |
lock_scope |
an EWebDAVLockScope to define the scope of the lock |
|
lock_timeout |
timeout for the lock, in seconds, on 0 to infinity |
|
owner |
optional identificator of the owner of the lock, or |
[nullable] |
out_lock_token |
return location of the obtained or refreshed lock token. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_acl_sync (EWebDAVSession *webdav
,const gchar *uri
,const EXmlDocument *xml
,GCancellable *cancellable
,GError **error
);
Issues ACL request on the provided uri
, or, in case it's NULL
, on the URI
defined in associated ESource.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
xml |
the request itself, as an EXmlDocument, the root element should be DAV:acl |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_supported_privilege_set_sync (EWebDAVSession *webdav
,const gchar *uri
,GNode **out_privileges
,GCancellable *cancellable
,GError **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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_privileges |
return location for the tree of supported privileges. |
[out][transfer full][element-type EWebDAVPrivilege] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_current_user_privilege_set_sync (EWebDAVSession *webdav
,const gchar *uri
,GSList **out_privileges
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_privileges |
return location for a |
[out][transfer full][element-type EWebDAVPrivilege] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_acl_sync (EWebDAVSession *webdav
,const gchar *uri
,GSList **out_entries
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_entries |
return location for a GSList of EWebDAVAccessControlEntry. |
[out][transfer full][element-type EWebDAVAccessControlEntry] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_acl_restrictions_sync (EWebDAVSession *webdav
,const gchar *uri
,guint32 *out_restrictions
,EWebDAVACEPrincipalKind *out_principal_kind
,GSList **out_principal_hrefs
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_restrictions |
return location for bit-or of EWebDAVACLRestrictions. |
[out] |
out_principal_kind |
return location for principal kind. |
[out] |
out_principal_hrefs |
return location for a GSList of principal href-s. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_get_principal_collection_set_sync (EWebDAVSession *webdav
,const gchar *uri
,GSList **out_principal_hrefs
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
out_principal_hrefs |
return location for a GSList of principal href-s. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_set_acl_sync (EWebDAVSession *webdav
,const gchar *uri
,const GSList *entries
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
entries |
entries to write. |
[element-type EWebDAVAccessControlEntry] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_webdav_session_principal_property_search_sync (EWebDAVSession *webdav
,const gchar *uri
,gboolean apply_to_principal_collection_set
,const gchar *match_ns_uri
,const gchar *match_property
,const gchar *match_value
,GSList **out_principals
,GCancellable *cancellable
,GError **error
);
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.
webdav |
||
uri |
URI to issue the request for, or |
[nullable] |
apply_to_principal_collection_set |
whether to apply to principal-collection-set |
|
match_ns_uri |
namespace URI of the property to search in, or |
[nullable] |
match_property |
name of the property to search in |
|
match_value |
a string value to search for |
|
out_principals |
return location for matching principals. |
[out][transfer full][element-type EWebDAVResource] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Whether succeeded. Note it can report success also when no matching principal had been found.
Since: 3.26
gchar *
e_webdav_session_util_maybe_dequote (gchar *text
);
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.
Since: 3.26
void
e_webdav_session_util_free_privileges (GNode *privileges
);
Frees privileges
returned by e_webdav_session_get_supported_privilege_set_sync()
.
The function does nothing, if privileges
is NULL
.
Since: 3.26
#define E_WEBDAV_CAPABILITY_CALENDAR_SCHEDULE "calendar-schedule"
#define E_WEBDAV_CAPABILITY_CALENDAR_AUTO_SCHEDULE "calendar-auto-schedule"
#define E_WEBDAV_CONTENT_TYPE_CALENDAR "text/calendar; charset=\"utf-8\""
#define E_WEBDAV_COLLATION_ASCII_NUMERIC_SUFFIX "ascii-numeric"
#define E_WEBDAV_COLLATION_ASCII_NUMERIC "i;" E_WEBDAV_COLLATION_ASCII_NUMERIC_SUFFIX
#define E_WEBDAV_COLLATION_ASCII_CASEMAP_SUFFIX "ascii-casemap"
#define E_WEBDAV_COLLATION_ASCII_CASEMAP "i;" E_WEBDAV_COLLATION_ASCII_CASEMAP_SUFFIX
#define E_WEBDAV_COLLATION_UNICODE_CASEMAP_SUFFIX "unicode-casemap"
#define E_WEBDAV_COLLATION_UNICODE_CASEMAP "i;" E_WEBDAV_COLLATION_UNICODE_CASEMAP_SUFFIX
struct EWebDAVSession { };
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26