owncloud · settermjd · Nov 19, 2018 · Nov 13, 2018 · Nov 13, 2018 · Nov 14, 2018
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <oc:filter-rules>
+        <oc:favorite>1</oc:favorite>
+    </oc:filter-rules>
+</oc:filter-files>
+
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <a:prop>
+        <oc:fileid/>
+        <oc:permissions/>
+        <oc:size/>
+        <oc:owner-id/>
+        <oc:owner-display-name/>
+        <a:getlastmodified/>
+        <a:getetag/>
+        <a:getcontenttype/>
+    </a:prop>
+    <oc:filter-rules>
+        <oc:favorite>1</oc:favorite>
+        <oc:systemtag>1</oc:systemtag>
+    </oc:filter-rules>
+</oc:filter-files>
+
+
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:filter-files xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <a:prop>
+        <oc:fileid/>
+        <oc:permissions/>
+        <oc:size/>
+        <oc:owner-id/>
+        <oc:owner-display-name/>
+        <a:getlastmodified/>
+        <a:getetag/>
+        <a:getcontenttype/>
+    </a:prop>
+    <oc:filter-rules>
+        <oc:favorite>1</oc:favorite>
+    </oc:filter-rules>
+</oc:filter-files>
+
+
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:search-files 
+    xmlns:a="DAV:" 
+    xmlns:oc="http://owncloud.org/ns">
+    <oc:search>
+        <oc:pattern>web</oc:pattern>
+        <oc:limit>5</oc:limit>
+    </oc:search>
+</oc:search-files>
+
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:search-files 
+    xmlns:a="DAV:" 
+    xmlns:oc="http://owncloud.org/ns">
+    <oc:search>
+        <oc:pattern>web</oc:pattern>
+    </oc:search>
+</oc:search-files>
+
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<oc:search-files 
+    xmlns:a="DAV:" 
+    xmlns:oc="http://owncloud.org/ns">
+    <a:prop>
+        <oc:id/>
+        <oc:downloadURL/>
+        <oc:fileid/>
+        <oc:permissions/>
+        <oc:size/>
+        <oc:owner-id/>
+        <oc:owner-display-name/>
+        <a:getlastmodified/>
+        <a:getetag/>
+        <a:getcontenttype/>
+    </a:prop>
+    <oc:search>
+        <oc:pattern>site</oc:pattern>
+    </oc:search>
+</oc:search-files>
+
+
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<d:error 
+    xmlns:d="DAV:" 
+    xmlns:s="http://sabredav.org/ns">
+  <s:exception>Sabre\Xml\ParseException</s:exception>
+  <s:message>This should never happen (famous last words)</s:message>
+</d:error>
+
@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<d:multistatus xmlns:d="DAV:" 
+    xmlns:s="http://sabredav.org/ns" 
+    xmlns:oc="http://owncloud.org/ns">
+  <d:response>
+    <d:href>/remote.php/dav/files/admin/Test/Sub-test/Website%20Plan.md</d:href>
+    <d:propstat>
+      <d:prop>
+        <oc:id>00000065oc21s4c9iej2</oc:id>
+        <oc:fileid>65</oc:fileid>
+        <oc:permissions>RDNVW</oc:permissions>
+        <oc:size>423</oc:size>
+        <oc:owner-id>admin</oc:owner-id>
+        <oc:owner-display-name>admin</oc:owner-display-name>
+        <d:getlastmodified>Fri, 28 Jul 2017 05:51:07 GMT</d:getlastmodified>
+        <d:getetag>"0286fcdabf5b4f5ef84788d86c37e245"</d:getetag>
+        <d:getcontenttype>text/markdown</d:getcontenttype>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+    <d:propstat>
+      <d:prop>
+        <oc:downloadUR/>
+      </d:prop>
+      <d:status>HTTP/1.1 404 Not Found</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
+
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<d:multistatus 
+    xmlns:d="DAV:" 
+    xmlns:s="http://sabredav.org/ns" 
+    xmlns:oc="http://owncloud.org/ns">
+  <d:response>
+    <d:href>/remote.php/dav/files/admin/welcome.txt</d:href>
+    <d:propstat>
+      <d:prop>
+        <oc:fileid>28</oc:fileid>
+        <oc:permissions>RDNVW</oc:permissions>
+        <oc:size>163</oc:size>
+        <oc:owner-id>admin</oc:owner-id>
+        <oc:owner-display-name>admin</oc:owner-display-name>
+        <d:getlastmodified>Mon, 05 Nov 2018 10:52:58 GMT</d:getlastmodified>
+        <d:getetag>"91b08390250f5294390c4fc92b6b0138"</d:getetag>
+        <d:getcontenttype>text/plain</d:getcontenttype>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<d:multistatus 
+    xmlns:d="DAV:" 
+    xmlns:s="http://sabredav.org/ns" 
+    xmlns:oc="http://owncloud.org/ns">
+  <d:response>
+    <d:href>/remote.php/dav/files/admin/Test/Sub-test/Site-Plan.md</d:href>
+    <d:propstat>
+      <d:prop>
+        <oc:id>00000065oc21s4c9iej2</oc:id>
+        <oc:downloadURL/>
+        <oc:fileid>65</oc:fileid>
+        <oc:permissions>RDNVW</oc:permissions>
+        <oc:size>423</oc:size>
+        <oc:owner-id>admin</oc:owner-id>
+        <oc:owner-display-name>admin</oc:owner-display-name>
+        <d:getlastmodified>Fri, 28 Jul 2017 05:51:07 GMT</d:getlastmodified>
+        <d:getetag>"0286fcdabf5b4f5ef84788d86c37e245"</d:getetag>
+        <d:getcontenttype>text/markdown</d:getcontenttype>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
+
@@ -68,6 +68,7 @@
 ***** xref:webdav_api/comments.adoc[The Comments API]
 ***** xref:webdav_api/files_versions.adoc[The Files Versions API]
 ***** xref:webdav_api/tags.adoc[The Tags API]
+***** xref:webdav_api/search.adoc[The Search API]
 ** General Contributor Guidelines
 *** xref:general/code-of-conduct.adoc[Community Code of Conduct]
 *** xref:general/codingguidelines.adoc[Coding Style & General Guidelines]

@@ -0,0 +1,13 @@
+= Core Details
+
+[cols=",,",options="header",]
+|=====================================================
+|Request Path 
+|Method 
+|Content Type
+
+|`{request_path}` 
+|{method} 
+|{content_type}
+|=====================================================
+
@@ -0,0 +1,18 @@
+==== If The Payload File Cannot Be Read Or Is Invalid XML
+
+If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an `HTTP/1.1 500 Internal Server Error` status code.
+
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml[indent=0]
+....
+
+==== If a Non-Existent Property Is Requested 
+
+If a non-existent property is requested, then an additional `propstat` element is returned, as in the example below, which contains a list of the properties which were not available.
+
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/response/common/failure/request_non_existent_property.xml[indent=0,lines=19..25]
+....
+
@@ -0,0 +1,44 @@
+// Page attributes
+:page-partial:
+
+.Available File Properties
+[cols="1,3,2",options="header",]
+|===
+|Property
+|Description
+|Namespace
+
+|id
+|The id of the file
+|`http://owncloud.org/ns`
+
+|permissions
+|The permissions set on the file
+|`http://owncloud.org/ns`
+
+|size
+|The file's size
+|`http://owncloud.org/ns`
+
+|owner-id
+|The id of the file owner
+|`http://owncloud.org/ns`
+
+|owner-display-name
+|The display name of the file owner
+|`http://owncloud.org/ns`
+
+|getlastmodified
+|The last modified date of the file
+|`DAV`
+
+|getetag
+|The file's ETag
+|`DAV`
+
+|getcontenttype
+|The file's content type.
+|`DAV`
+
+|===
+
@@ -0,0 +1,11 @@
+= Search API
+
+If you need to search for files, then you can use the WebDAV search API.
+The search API exposes two endpoints for finding files in a user’s filesystem; these are:
+
+- xref:search-files[Search Files]
+- xref:filter-files[Filter Files]
+
+include::search/search_files.adoc[leveloffset=+1]
+
+include::search/filter_files.adoc[leveloffset=+1]
@@ -0,0 +1,118 @@
+[[filter-files]]
+= Filter Files
+// Page attributes
+:page-partial:
+// Attributes for the core details include
+:request_path: remote.php/dav/files/<user> 
+:method: REPORT
+:content_type: text/xml
+
+The `filter-files` report allows for retrieving a list of files in an ownCloud user's filesystem, based on two criteria:
+
+include::{partialsdir}/webdav_api/core_request_details.adoc[leveloffset=+1]
+
+== The Request
+
+An authenticated https://tools.ietf.org/html/rfc3253#section-3.6[REPORT request] needs to be made to retrieve a list of all files stored in a user's ownCloud filesystem.
+
+=== Example Request
+
+[source,console]
+....
+curl --silent \
+  -X REPORT \
+  --data "@filter-files-criteria.xml" \
+  -u admin:admin \
+  'http://localhost/remote.php/dav/files/admin' | xmllint --format -
+....
+
+The request must include a request body that includes the rules to filter by.
+There are two filter rules which can be supplied; these are:
+
+[cols="1,2,1,1,1",options="header",]
+|===
+|Rule
+|Description
+|Type
+|Accepted Values
+|Mandatory
+
+|`favorite`
+|Whether they’ve been marked as a favorite or not (mandatory)
+|integer
+|`0`,`1`
+|Yes
+
+|`systemtag`
+|The tags that have been assigned to them
+|integer
+|Any valid system tag. 
+ These can be retrieved by using xref:webdav_api/tags.adoc#list-tags[the Tags API].
+|No
+|===
+
+=== Example Request Bodies
+
+Below, are several examples of the XML response bodies that can be sent with the request.
+
+==== Minimal Request Body
+
+In the `search` element, it specifies the search pattern to filter down the list of files to return in a successful resultset.
+
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml[indent=0]
+....
+
+==== Limiting Returned File Properties
+
+If only a specific list of properties is required for each file, then a `prop` element needs to be included in the response body, such as in the example below.
+
+include::{partialsdir}/webdav_api/search/file_properties.adoc[]
+
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml[indent=0]
+....
+
+==== Filtering By Tag
+
+Files can be filtered by those assigned specific tags.
+If this is required, then the `systemtag` element needs to be supplied, which contains a space-separated list of tag _ids_ to filter by.
+
+TIP: Tag ids can be retrieved by using xref:webdav_api/tags.adoc#list-tags[the Tags API].
+
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml[indent=0]
+....
+
+NOTE: The example uses http://xmlsoft.org/xmllint.html[xmllint] to make the response more readable.
+Xmllint is available in the http://www.xmlsoft.org/[libxml2 package].
+
+== The Response
+
+=== Success
+
+Successful requests return two things:
+
+. An XML payload.
+. A status of `HTTP/1.1 207 Multi-Status`.
+
+You can see an example of the XML payload below.
+The XML payload contains a `response` element for each file.
+And each `response` element contains three items:
+
+. A link to the file (`href`).
+. The requested properties, along with their respective values (`propstat`).
+. The file's status (`status`).
+
+.Example of a successful search response
+[source,xml]
+....
+include::{examplesdir}/core/webdav_api/search/response/filter_files/success.xml[indent=0]
+....
+
+=== Failure
+
+include::{partialsdir}/webdav_api/search/common_error_responses.adoc[]