.. Netfiles API documentation master file, created by
   sphinx-quickstart on Fri Mar  6 11:42:21 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Get Changed Files
=================

The ``showChangedFiles`` call allows you to retrieve information about the changed files & folders within a dataroom.
You can specify the ``scope`` as well as the *since*-date. ``scope`` defines what type of objects you are looking for (see below).

The *since*-date (``period``) is given in Hyperwave Date Format (``yyyy/MM/dd HH:mm:ss +0000``).

Request
-------

Request method is ``showChangedFiles``:

::

  GET https://app.netfiles.de/<dataroom-name>;internal&action=json&apikey=<YourApiKey>&deviceID=<currentDeviceID>&method=showChangedFiles&period=<date_time_since>&scope=<scope>
  Authorization: Basic BASE64(UTF8Bytes(<username>:<password>))
  Accept: application/json
  User-Agent: iPad
  netfiles: <value of the netfiles cookie>
  sk1: <value of the sk1 cookie>
  HW_User: <value of the HW_User cookie>
  HyperwaveSession: <value of the HyperwaveSession cookie>
  sk_s_web_S: <value of the sk_s_web_S cookie>
  sk_p_web_S: <value of the sk_p_web_S cookie>


Response
--------

The response is a json object (``application/json``) representing a list of HW_Objects:

E.g.:

.. code:: json

    {
      "count": 2,
      "response": [
        {
          "type": "document",
          "id": "ID-29855.6432902402691-2",
          "path": "/tombusinessplus/projectfiles/anders.txt",
          "icon": "text",
          "documentClass": "",
          "version": "V 02",
          "downloadProhibited": false,
          "title": "anders.txt",
          "name": "anders.txt",
          "creationDate": "2019/10/09 10:00:32 +0000",
          "modificationDate": "2019/10/09 10:05:23 +0000",
          "author": "   ",
          "writeAccess": false,
          "documentType": "text/plain",
          "md5Checksum": "55b56a1400ea438c8cc912351b8187fa",
          "documentSize": 7
        },
        {
          "type": "collection",
          "id": "ID-29855.6480642866411-1",
          "path": "/tombusinessplus/projectfiles/Über den Berğen, beı den Şieben Zwergen",
          "documentClass": "",
          "version": "",
          "downloadProhibited": false,
          "title": "Über den Berğen, beı den Şieben Zwergen",
          "name": "Über den Berğen, beı den Şieben Zwergen",
          "creationDate": "2020/03/10 13:09:33 +0000",
          "modificationDate": "2020/03/10 13:09:33 +0000",
          "author": "   ",
          "writeAccess": true,
          "subDocs": "0"
        }
      ]
    }

In the example above, we have provided you with filenames including Turkish characters. We will keep this dataroom as example
for the future (``tombusinessplus``)

Returned Headers and Set Cookies are the same as with the :doc:`Check Identity <checkidentity>` call.

Discussion - Scope
------------------

The ``scope`` is extremely important. Depending on what you exactly want from the server, there are five (5!) scopes.

``scope=projectfiles``
    Applies only to *normal* datarooms (i.e. it does **not** apply for Boardrooms). Returns the list of changed **files** and
    **folders** in that dataroom.

``scope=files``
    Applies only to *normal* datarooms (i.e. it does **not** apply to Boardrooms). Returns the list of changed **files**.

``scope=folders``
    Applies only to *normal* datarooms (i.e. it does **not** apply to Boardrooms). Returns the list of changed **folders**.

``scope=meetings``
    Applies only to *Boardrooms*, i.e. it does **not** work on normal datarooms (returns 0 entries on normal datarooms).
    Returns the list of all :doc:`Meetings <../meetings/meeting>`, :doc:`Meeting Collections <../meetings/meetingcollection>`,
    :doc:`Meeting Topics <../meetings/meetingtopic>`, and :doc:`Meeting Topic Minutes <../meetings/meetingtopicminutes>`
    that have changed since date given. It does **not** return the list of files.

``scope=meetingfiles``
    Applies only to *Boardrooms*, i.e., it *should* not work on normal datarooms. It returns the list of changed files & folders
    since date given.

Discussion - Offline Use
------------------------

You can use this call to identify which files & folders have changed. But when a file or folder is moved from one parent to a new parent, both parents are changed. Additionally, the file itself is also changed since its parent is now different.

So, the change in question can be manyfold. Especially with regards to the files, changes can be many:

- Move from parent *a* to parent *b*
- Change in the content of the file
- Change in other attributes of the file (name, ...)
- ...

In order to actually (e.g.) synchronize all changes, you would need to re-load the file in question, re-load the children of parent *a* (in order to remove the object from there) and re-load the children of parent *b* (in order to be synchronized).

Keep this in mind when writing offline apps.

    **IMPORTANT**: *Changed* means that the file had to exist prior to the period you have given as ``period`` parameter. If a file was
    added to the dataroom *after* ``period``, it will not be returned as a *changed*. In order to get the list of files/folders that were
    added after ``period`` (and maybe even changed thereafter) you *must* make a :doc:`Get New Files <shownewfiles>` call.

    Otherwise your syncronization won't be complete...