Filter Files

The filter-files report allows for retrieving a list of files in an ownCloud user’s filesystem, based on two criteria:

Core Details

Request Path Method Content Type

remote.php/dav/files/<user>

REPORT

text/xml

The Request

An authenticated REPORT request needs to be made to retrieve a list of all files stored in a user’s ownCloud filesystem.

Example Request

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:

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 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.

<?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>

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.

Table 1. Available File Properties
Property Description Namespace

getcontentlength

The file’s content length. This is only sent for files, not for folders and collections. Refer to the size property for folders and collections.

DAV

getcontenttype

The file’s content type.

DAV

getetag

The file’s ETag

DAV

getlastmodified

The last modified date of the file

DAV

lockdiscovery

Supports the "persistent file locking" backend feature. For more information on this property, please refer to the W3C spec.

DAV

resourcetype

The resource’s type. If the resource is a folder, then the value is set to collection, otherwise, no value is returned.

DAV

comments-unread

The number of comments on the item that have yet to be read.

http://owncloud.org/ns

favorite

Indicates whether the file has been favorited or not

http://owncloud.org/ns

fileid

The id of the file

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

share-types

It is an OC-specific property which summarizes what outgoing share types are applied to the current item. The share type values are:

  • 0: user share

  • 1: group share

  • 3: link shares

http://owncloud.org/ns

size

The size of a folder or collection. This property is not returned for files. Refer to the getcontentlength property for folders and collections.

http://owncloud.org/ns

tags

A collection of tags that have been added to the file.

http://owncloud.org/ns

<?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>

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.

Tag ids can be retrieved by using the Tags API.
<?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>
The example uses xmllint to make the response more readable. Xmllint is available in the libxml2 package.

The Response

Success

Successful requests return two things:

  1. An XML payload.

  2. 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:

  1. A link to the file (href).

  2. The requested properties, along with their respective values (propstat).

  3. The file’s status (status).

Example of a successful search response
<?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>

Failure

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.

<?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>

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.

  <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>