It is also possible to query metadata of archived messages containing details of a transferred files. This metadata may be retrieved/queried by:
allow-admin-querying-users-data is set to true)As returned result set may be quite large, mechanism supports XEP-0059: Result Set Management for pagination.
All timestamps sent to the server or returned by the server using this extension are compatible with DataTime profile defined in XMPP Data and Time Profiles (XEP-0082)
Returned result set may be filtered with use of the following fields.
| Name | Field type | Expected value | Description | Access |
|---|---|---|---|---|
domain | list-single | Domain for which request sender is an admin | Return only files sent to/from a domain | Admin |
owner | jid-single | User from a domain for which request sender is an admin | Return only files sent to/from a user | Admin |
after | text-single | Timestamp | Returns only files sent after this timestamp | User / Admin |
before | text-single | Timestamp | Returns only files sent before this timestamp | User / Admin |
contains | text-single | Text | Returns only files for which name, description or url contain this text | User / Admin |
media-type | text-single | Text | Returns only files for which media type contain this text | User / Admin |
smaller-than | text-single | Number | Returns only files for which size is smaller than | User / Admin |
bigger-than | text-single | Number | Returns only files for which size is bigger than | User / Admin |
If field will not be set, then its value will not be used to filter results.
If owner field is set, then domain field may be left empty.
If admin of a domain will not pass domain or owner it will receive results only from his own archive (files sent to or by him).
To know which fields you may specify to query archived files metadata, send following query:
Example request to retrieve form fields.
<iq type="get" id="queryForm1">
<query xmlns="urn:xmpp:tigase:file:metadata"/>
</iq>
The server replies with all the form fields it support in queries:
Example response on form fields retrieval.
<iq type="result" id="queryForm1">
<query xmlns="urn:xmpp:tigase:file:metadata">
<x xmlns="jabber:x:data" type="form">
<field var="FORM_TYPE" type="hidden">
<value>urn:xmpp:tigase:file:metadata</value>
</field>
<field var="domain" type="list-single" label="Domain">
<option>example.com</option>
</field>
<field var="owner" type="jid-single" label="Owner"/>
<field var="after" type="text-single" label="After timestamp"/>
<field var="before" type="text-single" label="Before timestamp"/>
<field var="contains" type="text-single" label="Text to search for in name, description or url"/>
<field var="media-type" type="text-single" label="Part of media type (MimeType)"/>
<field var="smaller-than" type="text-single" label="Maximal size of a file"/>
<field var="bigger-then" type="text-single" label="Minimal size of a file"/>
</x>
</query>
</iq>
Fields domain and owner will available only when query would be executed by a user which is a domain administrator of any vhost at the installation.
To do that we send <iq/> of type set with <query/> element qualified with by namespace urn:xmpp:tigase:file:metadata which must contain data form with FORM_TYPE field set to urn:xmpp:tigase:file:metadata.
The form may contains additional fields, but we may skip those fields for which we do not wish to provide values.
Optionally, to paginate or limit number of results, we may add <set/> qualified by namespace http://jabber.org/protocol/rsm as specified in XEP-0059: Result Set Management.
Example request to retrieve first page of results.
<iq type="set" id="query1">
<query xmlns="urn:xmpp:tigase:file:metadata">
<x xmlns="jabber:x:data" type="submit">
<field var="FORM_TYPE" type="hidden">
<value>urn:xmpp:tigase:file:metadata</value>
</field>
</x>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
In the response server will return a <list/> element qualified by namespace urn:xmpp:tigase:file:metadata. In this element there will be a <set/> element qualified by http://jabber.org/protocol/rsm (see XEP-0059: Result Set Management) containing pagination details and a list of <item/> elements.
Each <item/> element will contain following attributes:
- id - ID of the message containing metadata
- with - bare jid of a sender/recipient of a file
- stamp - timestamp of a message
- url - link to download the file
Additionally, domain admin will receive owner attribute which will contain bare jid of the owner of the archive in which result was found.
Each <item/> element will contain file element qualified by namespace urn:xmpp:jingle:apps:file-transfer:5 which may contain following elements:
media-typenamedescsizeThe <file/> element format is described in XEP-0234: Jingle File Transfer - 5. Application Format.
<file/> element will contains <name/>, <desc/>, <size/> and <media-type/> elements only if file transfer was initiated with XMPP <message/> containing description of a transferred file specified in XEP-0385: SIMS
Example response with first page of results.
<iq type="set" id="query1">
<list xmlns="urn:xmpp:tigase:file:metadata">
<item id="dcbb06cb-1d41-41bf-a4f3-396af26d0509"
with="buddy-1@example.com"
stamp="2021-04-28T08:15:04.063Z"
url="https://example.com/uploaded/b2718a48-ed88-4afe-99c2-ee99219d896f/first.jpg">
<file xmlns="urn:xmpp:jingle:apps:file-transfer:5">
<media-type>image/jpeg</media-type>
<name>first.jpg</name>
<desc>First shared image</desc>
<size>1334232</size>
</file>
</item>
<item id="a8c131e8-5ed5-46dd-aef7-871fd88531ab"
with="buddy-2@example.com"
stamp="2021-04-28T09:25:04.563Z"
url="https://example.com/uploaded/c5d0bc87-b3ef-4846-aee9-2855e067f03a/second.jpg">
<file xmlns="urn:xmpp:jingle:apps:file-transfer:5"/>
</item>
...
<item id="f4805382-da50-46e5-a683-70dbd214a0cb"
with="buddy-1@example.com"
stamp="2021-04-28T12:53:14.862Z"
url="https://example.com/uploaded/19d07312-6c10-40c0-b185-735fed7d452e/flower.jpg">
<file xmlns="urn:xmpp:jingle:apps:file-transfer:5">
<media-type>image/jpeg</media-type>
<name>flower.jpg</name>
<desc>Image of a flowers</desc>
<size>1274422</size>
</file>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index="0">dcbb06cb-1d41-41bf-a4f3-396af26d0509</first>
<last>f4805382-da50-46e5-a683-70dbd214a0cb</last>
<count>123</count>
</set>
</query>
</iq>
To retrieve next page of the results, send request with the same query but add <after/> or <before/> elements with proper values to the set element of the request.