.. include:: definitions.txt
   
Album datafiles and other object definitions
********************************************

.. _sec_L2_AlbumDatafiles:

Album datafiles
===============
Each album will have the following datafiles: 

.. table:: Overview of album datafiles
   :widths: 2 2 3 3 2
   :width: 80%
   :column-alignment: left center left left left
   :header-alignment: left center left left left
   
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+
   | Datafile                                       | #instances        | Existence checked by / read by PHP-function | Stored in                      | Modified by                    |
   +================================================+===================+=============================================+================================+================================+
   | :ref:`fproc.txt <sec_L3_fproc>`                | 1 per album       | :php:func:`RProc_FProc_Status_X00FF0()`     |                                | N.A.                           |
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+
   | :ref:`rproc.txt <sec_L3_rproc>`                | 1 per album       | :php:func:`RProc_FProc_Status_X00FF0()`     |                                |                                |
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+
   | :ref:`phpdefinition.xml <sec_L3_phpdef>`       | 1 per album       | :php:func:`CheckProcessStatus_X000FF()`     | :php:`SimpleXMLElement object` | Manual                         |
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+
   | :ref:`albumOverview.xml <sec_L3_albumOverview>`| 1 for all albums  | :php:func:`AlbumCatalogue()`                | :php:`SimpleXMLElement object` | Manual                         |
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+
   | :ref:`iminfo.xml <sec_L3_iminfo>`              | n per album       | :php:func:`GetIminfoObjects()`              | :php:`SimpleXMLElement object` |                                |
   +------------------------------------------------+-------------------+---------------------------------------------+--------------------------------+--------------------------------+

These album files reside at the server-side. Updating these files as a result of user action at the client side (e.g. :numref:`figure_DialogMsgBox_MediaProcessStatus`) will be implemented by AJAX calls. The content of xml files is stored in `PHP built-in XML objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ by the PHP function
`simplexml_load_file() <https://www.php.net/manual/en/function.simplexml-load-file.php>`_.

.. _sec_L3_fproc:

fproc.txt
---------
Each processed album has in its root directory file :cf:`fproc.txt`. It is an empty file, and its purpose is to lock the album content when the administrator or album owner is logged on: i.e. no new media will be processed when visiting the album. When this file is deleted, the album is unlocked so automatic updating can be executed. The file can only be deleted by administrator or album owner.

.. _sec_L3_rproc:

rproc.txt
---------
Each processed album has in its root directory file :cf:`rproc.txt`. The purpose of this file is to give a media count overview (i.e. photographs and videos) in each location directory and to have a **fast** overview of album, and how the media are divided over the public and private directories. 

#. First column: directory name,
#. Second column: total number of media,
#. Third column: total number of public media,
#. Fourth column: total number of private media.

Video media with the same basename but with different extensions (i.e. same video with different formats/codecs), are considered as different media.
The same information can be derived from all :cf:`IMINFO.XML` files, but then these files need to be processed and that requires process time (note that :cf:`IMINFO.XML` distinguishes between photographs and videos). The last row contains the sum of all media. An example of a :cf:`rproc.txt` file is given in :numref:`table_rproc_example`. The last row is the sum of media in all location directories. 

.. _table_rproc_example:

.. table:: Example of :cf:`rproc.txt file` content.
   :widths: 4 1 1 1
   :column-alignment: left center center center
   :width: 40%

   +------------------+----+----+----+
   | DeReis           | 17 | 12 | 5  |
   +------------------+----+----+----+
   | Weeshuis         | 13 | 13	| 0  |
   +------------------+----+----+----+
   | HoChiMinh        | 74 | 68 | 6  |
   +------------------+----+----+----+
   |DaguitHCM-TayNinh | 19 | 16 | 3  |
   +------------------+----+----+----+
   | DaguitHCM-Mekong | 21 | 16 | 5  |
   +------------------+----+----+----+
   | Mui Ne           | 56 | 44 | 12 |
   +------------------+----+----+----+
   | Dalat            | 57 | 50 | 7  |
   +------------------+----+----+----+
   | Nha trang        | 21 | 19 | 2  |
   +------------------+----+----+----+
   | Hoian            | 88 | 85 | 3  |
   +------------------+----+----+----+
   | Hue              |	94 | 90 | 4  |
   +------------------+----+----+----+
   | Hanoi            | 52 | 48 | 4  |
   +------------------+----+----+----+
   | Halong Bay       | 13 | 12 | 1  |
   +------------------+----+----+----+
   | \*               | 525| 473| 52 |
   +------------------+----+----+----+

.. _sec_L3_phpdef:
   
phpdefinition.xml
-----------------
The album is regular if the file :cf:`phpdefinition.xml` exists. It has sub-directories to provide structure to the album,
with names given in this file and optional descriptions. Examples of :cf:`phpdefinition.xml` files are given in :numref:`codeblock-xml-phpdef`
(without location descriptions) and :numref:`codeblock-xml-phpdef_withdescription` (with location descriptions: has tag elements :cf:`<HeeftBeschrijvingen>` and
:cf:`<verslag>)`. When the file :cf:`phpdefinition.xml` does not exist, the album has a “simple” structure: media in all sub-directories (recursively
with directory depth 1) are used for the album. As it is an album definition file it cannot be updated automatically. Any update should
be done manually by administrator or album owner. In principle any text editor will do for modifying the file :cf:`phpdefinition.xml`.

.. _codeblock-xml-phpdef:

.. code-block:: xml
   :class: dropdown
   :caption: Example content of file :cf:`phpdefinition.xml` without descriptions. The number of :cf:`<directory>` tag elements must be content consistent with file :cf:`rproc.txt`, i.e. with the number of rows - 1.

   <album>
      <directory>
        <name>DeReis</name>
        <thumb_caption>De Reis</thumb_caption>
      </directory>
      <directory>
        <name>Weeshuis</name>
        <thumb_caption>Het weeshuis</thumb_caption>
      </directory>
      <directory>
        <name>HoChiMinh</name>
        <thumb_caption>Ho Chi Minh City</thumb_caption>
      </directory>
      <directory>
        <name>DaguitHCM-TayNinh</name>
        <thumb_caption>Daguit naar TayNinh</thumb_caption>
      </directory>
      <directory>
        <name>DaguitHCM-Mekong</name>
        <thumb_caption>Daguit naar Mekong</thumb_caption>
      </directory>
      <directory>
        <name>Mui Ne</name>
        <thumb_caption>Mui Ne</thumb_caption>
      </directory>
      <directory>
        <name>Dalat</name>
        <thumb_caption>Dalat</thumb_caption>
      </directory>
      <directory>
        <name>Nha Trang</name>
        <thumb_caption>Nha Trang</thumb_caption>
      </directory>
      <directory>
        <name>Hoian</name>
        <thumb_caption>Hoian</thumb_caption>
      </directory>
      <directory>
        <name>Hue</name>
        <thumb_caption>Hue</thumb_caption>
      </directory>
      <directory>
        <name>Hanoi</name>
        <thumb_caption>Hanoi</thumb_caption>
      </directory>
      <directory>
        <name>Halong Bay</name>
        <thumb_caption>Halong Bay</thumb_caption>
      </directory>
    </album>

.. _FigCH2_DirectoryThumbs:

.. figure:: Fig18_DirectoryThumbs.png
   :width: 80%

   Directory thumbs without descriptions.

.. _codeblock-xml-phpdef_withdescription:

.. code-block:: xml
   :caption: Example content of file :cf:`phpdefinition.xml` with tag element :cf:`<verslag>`, to be used when :cf:`<HeeftBeschrijvingen> 1</HeeftBeschrijvingen>`.
   
   <?xml version="1.0" encoding="utf-8"?>
   <album>
     <HeeftBeschrijvingen>1</HeeftBeschrijvingen>
     <directory><name>12 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Zondag 12 juni</thumb_caption>
     <verslag> Zondag, Bagnères de Louchon:Port de Balès (klim vanuit noordzijde), Super Bagnères (<b>130km, 2850 
       hoogtemeters</b>). Zoals het plaatje bij de pauze laat zien is het weer prachtig. Eerste 40 km zijn relatief vlak 
       zodat we er op het eind van de dag gratis 450 hoogtemeters bij hebben gekregen vooraleer we aan de 18km lange beklimming
       begonnen van de Port de Balès. ...
     </verslag>
     </directory>
     <directory><name>13 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Maandag 13 juni</thumb_caption>
     <verslag>Maandag, Bagnères de Louchon: Portillon (klim westzijde), Mente (klim westzijde), Portet d&#39;Aspet (klim
       westzijde): <b>116km, 2380 hoogtemeters</b>. Meteen bij het uitrijden van Bagnères de Louchon begint de 11km lange klim 
       van de Portillon richting Spanje. Na de afdaling had Hans wederom een lekke band. Om er zeker van te zijn dat de band 
       ditmaal wel goed werd gemaakt, staken we met z&#39;n allen een handje toe. Sneller ging het echter niet. ...
     </verslag>
     </directory>
     <directory><name>14 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Dinsdag 14 juni</thumb_caption>
     <verslag>Dinsdag, Bagnères de Louchon: Peyresourde (eerste klim van de dag langs de oostzijde, laatste klim van de dag 
       langs de westzijde), Aspin (klim oostzijde), Hourquette (klim westzijde): <b>110km, 3150 hoogtemeters</b>. Peyresourde 
       en Aspin zijn welbekende gedienden in de Tour. De Hourquette daarentegen is pas in 2011 in het bergarsenaal van de Tour 
       opgenomen. In de Tour 2011 was de Hourquette (klim langs oostzijde) een opwarmertje voor de Tourmalet. ... 
     </verslag>
     </directory>
     <directory><name>15 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Woensdag 15 juni</thumb_caption>
     <verslag>Woensdag: Na het ontbijt werden de auto's snel ingeladen en werd er naar het volgende verblijf gereden: 
       Argelès-Gazost. Na het uitladen aldaar ging het grootste deel van de groep naar het welbekende nabijgelegen bedevaartsoord 
       Lourdes. De anderen fietsten de geplande route naar Col de Tentes (<b>99km, 1604 hoogtemeters</b>). Dit is waarschijnlijk 
       een minder bekende col die vanuit Luz-Saint-Saveur te bereiken is. ...
     </verslag>
     </directory>
     <directory><name>16 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Donderdag 16 juni</thumb_caption>
     <verslag>Donderdag, Argelès-Gazost: Aubisque (<b>115km, 1500 hoogtemeters</b>).
     </verslag>
     </directory>
     <directory><name>17 juni 2011</name><thumbIcon></thumbIcon>
     <thumb_caption>Vrijdag 17 juni</thumb_caption>
     <verslag>Vrijdag, Argelès-Gazost: Tourmalet, Hautacam (<b>135km, 3300 hoogtemeters</b>). Door een locale rittenwedstrijd 
       die toevallig ook vandaag over de Tourmalet ging op het tijdstip dat we die ook zouden doen moesten we de geplande route 
       om te draaien. Hierdoor beklommen we Tourmalet in de ochtend vanuit de westzijde (Luz-Saint-Saveur) voordat deze zou worden 
       afgesloten voor de wedstrijd in plaats vanuit Saint Marie de Campan. Bovenop de Tourmalet was het zoals gewoonlijk een 
       drukte van jewelste. De wind joeg ons de herberg in om daar een lekkernij met warme drank te nuttigen. ... 
     </verslag>
     </directory>
   </album>

.. _FigCH2_DirectoryThumbs+Description:

.. figure:: Fig18_DirectoryThumbs+Description.png
   :width: 80%

   Directory thumbs with descriptions.

.. _sec_L3_albumOverview:
   
albumOverview.xml
-----------------
File :file:`albumOverview.xml` contains an overview of all albums. Each album is represented as an element with the following child nodes:

* :cf:`<Name>`: Name of the album.
* :cf:`<Directory>`: Directory relative to the document root.
* :cf:`<Owner>`: Owner of the album. Possible values are given by the Group enumeration values (see :ref:`Table members <sec_L4_members_DB>` of the users database in MySQL, and :numref:`members_table_example`). The value is used to determine which users have the permission view the private version of an album, and the permission to edit the album. For example if :cf:`<Owner>famile</Owner>` then only registered users belonging to the :cf:`familie` Group can edit and view the album.
* :cf:`<Description>`: Short description of the album.
* :cf:`<CreationDate>`: Creation date of the album.
* :cf:`<ID>`: Unique identification number.

.. rst-class:: html-toggle

Source code
-----------

.. literalinclude:: ..\..\..\albumOverview.xml
   :language: xml
   :caption: Current content of :file:`albumOverview.xml`.

.. _sec_L3_iminfo_txt:

iminfo.txt
----------
First file format to store info of media (comma separated format). It is text file where each line represents a media file. A typical example is given in :numref:`codeblock-txt-iminfo`. Each line has a fixed number of data entries:

* Column 1: media filename after processing (in general down sizing),
* Column 2: original filename (in location directory),
* Column 3: timestamp (date and time format),
* Column 4: UNIX timestamp format: more convenient for ordening,
* Column 5: R (public) or Private,
* Column 6: Horizontal pixel number in original media file
* Column 7: Vertical pixel number in original media file
* Column 8: Horizontal resolution
* Column 9: Vertical resolution

.. _codeblock-txt-iminfo:

.. code-block:: text
   :caption: Structure of an :cf:`iminfo.txt` file.
   
   0000-IMAG2917-small.jpg,IMAG2917.JPG,2008:07:21 01:40:34,1216597234,R,2560,1920,72/1,72/1,
   0001-IMAG2918-small.jpg,IMAG2918.JPG,2008:07:21 01:52:36,1216597956,R,1920,2560,72/1,72/1,
   0002-IMAG2929-small.jpg,IMAG2929.JPG,2008:07:21 04:40:58,1216608058,Private,1920,2560,72/1,72/1,

A switch was made to another format (see :numref:`sec_L3_iminfo`), which was more flexible with respect to future extensions, and which has possibilities for internal structure.

.. _sec_L3_iminfo:

iminfo.xml - iminfo object
--------------------------
If the album file :cf:`phpdefinition.xml` exists, each location directory must have a file called :cf:`iminfo.xml`, containing information of each media in the location directory. The xml file global structure is given in :numref:`codeblock-xml-iminfo`. As mentioned in :numref:`sec_L2_AlbumDatafiles`, the content of an  :cf:`iminfo.xml` is stored in an object of class `SimpleXMLElement <https://www.php.net/manual/en/class.simplexmlelement.php>` by the PHP function `simplexml_load_file() <https://www.php.net/manual/en/function.simplexml-load-file.php>`_.
When new media is added and or media is removed from an album in a location directory, the iminfo.xml file in that location directory can be updated automatically by administrator or album owner (see paragraph :numref:`sec_L3_album_admin`).

.. _codeblock-xml-iminfo:

.. code-block:: xml
   :caption: Structure of an :cf:`iminfo.xml` file.
   
   <?xml version="1.0" encoding="utf-8"?>
   <directory>
     <media>…</media>
     <media>…</media>
     <media>…</media>
     …
     <media>…</media>
     <ImageInfo> … </ImageInfo>
     <VideoInfo> … </VideoInfo>
     <MediaCounterInfo> … </MediaCounterInfo>
     <Version> … </Version>
   </directory>

There are 2 types of media: image and video. The image and video media tags only differ in their :cf:`<MIMETYPE>` tag element (see sections 
:numref:`sec_L4_image_media_tag` and :numref:`sec_L4_video_media_tag`). The tag elements :cf:`<ImageInfo>` and :cf:`<VideoInfo>` contain information about the numbers of images and videos, 
respectively. Description of the tag elements :cf:`<ImageInfo>` and :cf:`<VideoInfo>` are given in :numref:`sec_L4_image_info_tag`, and :numref:`sec_L4_video_info_tag`, respectively.

.. _sec_L4_image_media_tag:

.. rst-class:: html-toggle

Example Image media tag
^^^^^^^^^^^^^^^^^^^^^^^
.. _codeblock-xml-image-tag:

.. code-block:: xml
   :caption: Code of media element for image type.
   
   <media>
      <Selected>1</Selected>
      <TimeSortedFile> 0021-P6130094-small.jpg</TimeSortedFile>
      <OriginalFile> P6130094.JPG</OriginalFile>
      <TimeString> 2011:06:13 15:10:03</TimeString>
      <TimeStamp> 1307970603</TimeStamp>
      <PublicPrivate> R</PublicPrivate>
      <Transferred2SiteDir> 1</Transferred2SiteDir>
      <Width>4288</Width>
      <Height>3216</Height>
      <XResolution>72/1</XResolution>
      <YResolution>72/1</YResolution>
      <GPSLongitude>0.66046715003498</GPSLongitude>
      <GPSLatitude>42.977415539993</GPSLatitude>
      <MIMETYPE>
         <IMAGE>
            <BASENAME>P6130094</BASENAME>
            <TYPE ext="JPEG">1</TYPE>
         </IMAGE>
      </MIMETYPE>
      <Count>1</Count>
    </media>

An explanation of tag element :cf:`<Transferred2SiteDir>` and possible values are given in section :numref:`sec_L3_Transferred2SiteDir`.

.. _sec_L4_video_media_tag:

.. rst-class:: html-toggle

Example Video media tag
^^^^^^^^^^^^^^^^^^^^^^^
.. _codeblock-xml-video-tag:

.. code-block:: xml
   :caption: Code of media element for video type.
   
   <media>
      <Selected>1</Selected>
      <TimeSortedFile>12-Juni-pause1.mp4</TimeSortedFile>
      <OriginalFile>12-Juni-pause1.mp4</OriginalFile>
      <TimeString> </TimeString>
      <TimeStamp>1485863183</TimeStamp>
      <PublicPrivate> R</PublicPrivate>
      <Transferred2SiteDir>-1</Transferred2SiteDir>
      <Width>640</Width>
      <Height>360</Height>
      <XResolution>0</XResolution>
      <YResolution>0</YResolution>
      <GPSLongitude>NO-LNG</GPSLongitude>
      <GPSLatitude>NO-LAT</GPSLatitude>
      <MIMETYPE>
         <VIDEO>
            <BASENAME>12-Juni-pause1</BASENAME>
            <TYPE ext="WEBM">1</TYPE>
            <TYPE ext="MP4">1</TYPE>
         </VIDEO>
      </MIMETYPE>
      <Count>2</Count>
    </media>

.. _sec_L4_media_info_tag:

.. rst-class:: html-toggle

Example General media info tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Images and video have the following general info tags:

.. _table_general_media_tags:
   
.. table:: General info tags for images and video.
   :widths: 2 1 3
   :width: 85%
   :column-alignment: left center left
   :header-alignment: left center left
   :class: lasttable
   
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | Info tag                         | Video / image  | Purpose of tag / description                                        |
   +==================================+================+=====================================================================+
   | :cf:`<HasImage>`                 | Image + video  | Boolean                                                             |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<ReleasedCount>`            | Image + video  | Total number of released public and private images or videos.       |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Rel_PublicCount>`          | Image + video  | Number of released public images or videos.                         |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Rel_PrivateCount>`         | Image + video  | Number of released private images or videos.                        |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Rel_PublicFilesCount>`     | Video          | number of released public video files.                              |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Rel_PrivateFilesCount>`    | Video          | number of released private video files.                             |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Trf_PublicCount>`          | Image + video  | Number of images or videos to be transferred to public directory.   |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<Trf_PrivateCount>`         | Image + video  | Number of images or videos to be transferred to private directory.  |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<PublicCount>`              | Image + video  | Total number of public images or videos.                            |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<PublicFilesCount>`         | Video          | Total number of public video files.                                 |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<PrivateCount>`             | Image + video  | Number of private iamges or videos.                                 |
   +----------------------------------+----------------+---------------------------------------------------------------------+
   | :cf:`<PrivateFilesCount>`        | Video          | Total number of private video files.                                |
   +----------------------------------+----------------+---------------------------------------------------------------------+

.. _sec_L4_image_info_tag:

.. rst-class:: html-toggle

Example General image info tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
   :caption: Code of ImageInfo element.
   
   <ImageInfo>
      <HasImage>1</HasImage>
      <TransferCount>22</TransferCount>
      <TransferCountPublic>22</TransferCountPublic>
      <TransferCountPrivate>0</TransferCountPrivate>
      <PublicCount>22</PublicCount>
      <PrivateCount>0</PrivateCount>
   </ImageInfo>

.. _sec_L4_video_info_tag:

.. rst-class:: html-toggle

Example General video info tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
   :caption: Code of VideoInfo element.
   
   <VideoInfo>
      <HasVideo>1</HasVideo>
      <TransferCount>1</TransferCount>
      <TransferCountPublic>1</TransferCountPublic>
      <TransferCountPrivate>0</TransferCountPrivate>
      <TransferFilesCountPublic>2</TransferFilesCountPublic>
      <TransferFilesCountPrivate>0</TransferFilesCountPrivate>
      <PublicCount>2</PublicCount>
      <PublicFilesCount>4</PublicFilesCount>
      <PrivateCount>0</PrivateCount>
      <PrivateFilesCount>0</PrivateFilesCount>
      <VideoWidth>640</VideoWidth>
      <VideoHeight>360</VideoHeight>
   </VideoInfo>

.. _sec_L2_adua:

Album datafiles update approach
===============================
Normal user
-----------
.. _table_albumdatafile_updmeth_normal:
   
.. table:: Update methods for album datafiles: normal user. Under normal conditions no album files will be updated, except when |rproc| is accidentally deleted. 
   :widths: 3 2 2 12
   :width: 85%
   :column-alignment: left center center left
   :header-alignment: left center center left
   :class: t-albdataf_updmeth, lasttable
   
   +---------------+---------------+-----------+--------------------------------------------------------------------------+
   | File          | #files        | Update    | Update info                                                              |
   |               |               | method    |                                                                          |
   +===============+===============+===========+==========================================================================+
   | |fproc|       | 1 per album   | NONE      | As “normal” user the file |fproc| cannot be                              |
   |               |               |           | deleted, meaning that the album is locked.                               |
   +---------------+---------------+-----------+--------------------------------------------------------------------------+
   | |rproc|       | 1 per album   | Automatic | Automatic regeneration by function                                       |
   |               |               |           | :php:func:`RProc_FProc_Status_X00FF0()`: see also                        |
   |               |               |           | :numref:`table_UpdAct_Rproc_Fproc_Status_X00FF0`                         |
   |               |               |           |                                                                          |
   |               |               |           | * File |rproc| exists: no update takes place.                            |
   |               |               |           | * File |rproc| does not exist: Under normal this should not occur. If by |
   |               |               |           |   accident this file is deleted |rproc| is created with the info from all|
   |               |               |           |   |iminfo| files.                                                        |
   +---------------+---------------+-----------+--------------------------------------------------------------------------+
   | |phpdef|      | 1 per album   | NONE      | No update will take place.                                               |
   +---------------+---------------+-----------+--------------------------------------------------------------------------+
   | |iminfo|      | 1 per location| NONE      | No update will take place.                                               |
   +---------------+---------------+-----------+--------------------------------------------------------------------------+

.. _table_UpdAct_Rproc_Fproc_Status_X00FF0:

.. table:: Update actions as normal user on files :cf:`fproc.txt` and :cf:`rproc.txt` implemented in function :php:func:`RProc_FProc_Status_X00FF0()`.
   :widths: 4 2 2 3 3 5
   :column-alignment: left center center center center left
   :header-alignment: left center center center center left
   :width: 85%
   :class: lasttable

   +------------------------------------------+--------+--------+-----------+--------------+-------------------------------+
   | :php:func:`RProc_FProc_Status_X00FF0()`  | fproc  | rproc  | fproc     | rproc        |Remark                         |
   |                                          | exists | exists | action    | action       |                               |
   +==========================================+========+========+===========+==============+===============================+
   | :phpc:`NO_PROCESSED_FILES` (0x0000)      | 1      | 1/0    | Do nothing|              |                               |
   +------------------------------------------+--------+--------+-----------+--------------+-------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_KEPT`   | 1      | 0      | Do nothing| Regenerate   | When rproc.txt is accidentally|
   |  (0x0001)                                |        |        |           |              | removed by a file manager     |
   |                                          +--------+--------+-----------+--------------+-------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                               |
   +------------------------------------------+--------+--------+-----------+--------------+-------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_ADD_REM`| 1      | 0      | Do nothing| Regenerate   | When rproc.txt is accidentally|
   |  (0x0002)                                |        |        |           |              | removed by a file manager     |
   |                                          +--------+--------+-----------+--------------+-------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                               |
   +------------------------------------------+--------+--------+-----------+--------------+-------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_REMOVED`| 1      | 0      | Do nothing| Regenerate   | When rproc.txt is accidentally|
   |  (0x0003)                                |        |        |           |              | removed by a file manager     |
   |                                          +--------+--------+-----------+--------------+-------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                               |
   +------------------------------------------+--------+--------+-----------+--------------+-------------------------------+

.. _figure_DialogMsgBox_MediaProcessStatus_nuser:

.. figure:: Fig_DialogMsgBox_MediaProcessStatus_NormalUser.png
   :width: 100%
   
   Media Processing Status dialog window for “normal” user. When an album change is detected, which would require an album update a dialog box will pop up. When “STATUS WINDOW” is selected the normal user can see what changes have been detected. When selecting “LOGIN” the normal user change switch to album owner or “admin” in order to proceed with the album update process. For more details see also :numref:`sec_L4_normal_user_update_needed`.

.. _sec_L3_album_admin:
   
Album owner / administrator
---------------------------
.. _table_albumdatafile_updmeth_admin:
   
.. list-table:: Update methods for album datafiles: administrator.
   :widths: 4 2 2 15
   :width: 90%
   :header-rows: 1
   :class: t-albdataf-updmethrows, lasttable
   
   * - File
     - #files
     - | Update
       | method
     - Update info
   * - :cf:`fproc.txt`
     - 1 per album
     - NONE
     - When deleted the update process is started. The file :cf:`fproc.txt` is deleted when pressing the “OK” button in the media processing status dialog box (see :numref:`figure_DialogMsgBox_MediaProcessStatus_admin`). The file itself cannot be updated since it is an empty file.
       When the update process is completed the file :cf:`fproc.txt` is created again (by :php:func:`RProc_FProc_Status_X00FF0()`) so that the album is locked.
   * - :cf:`rproc.txt`
     - 1 per album
     - Automatic
     - | In the current implementation approach :cf:`rproc.txt` is updated in 2 phases.
       | Phase 1: :php:func:`RProc_FProc_Status_X00FF0()`, which is the same as for “normal” user (see also See :numref:`table_UpdAct_Rproc_Fproc_Status_X00FF0_admin`).
       | Phase 2:

       * 0x00F00: see also :numref:`table0x00F00` for a description what type of modification has taken place. This is communicated in the media process status dialog box (see :numref:`figure_DialogMsgBox_MediaProcessStatus`).
       * In the actual updating process (initiated when :cf:`fproc.txt` is deleted), when all iminfo.xml files have been updated, :cf:`rproc.txt` will be updated using the updated :cf:`iminfo.xml` files by an AJAX call (:js:func:`AnalyseDeletedAndNewMedia()` implemented in :js:`js\\myjs\\public_private.js`) to :py:mod:`php\\analyse_status_table.php`.
       * The info in \|F\|F\|●●●1\|F\|F\| itself is not used for updating :cf:`rproc.txt` file.
       * Only administrator can update this file.
   * - :cf:`phpdefinition.xml`
     - 1 per album
     - NONE
     - Must be modified by using text editor (i.e. not automatic update). A user interface can be developed to edit :cf:`phpdefinition.xml`.
   * - :cf:`iminfo.xml`
     - 1 per location
     - NONE
     - Only administrator/album owner can initiate the update process of :cf:`iminfo.xml` files, by deleting the file :cf:`fproc.txt`.

.. _table_UpdAct_Rproc_Fproc_Status_X00FF0_admin:

.. table:: Actions on files :cf:`fproc.txt` and :cf:`rproc.txt` implemented in function :php:func:`RProc_FProc_Status_X00FF0()`.
   :widths: 5 1 1 2 3 5
   :column-alignment: left center center center left left
   :header-alignment: left center center center center left
   :width: 85%
   :class: lasttable

   +------------------------------------------+--------+--------+-----------+--------------+----------------------------------+
   |Rproc_Fproc_Status_X00FF0()               | fproc  | rproc  | fproc     | rproc        |Remark                            |
   |                                          | exists | exists | action    | action       |                                  |
   +==========================================+========+========+===========+==============+==================================+
   | :phpc:`NO_PROCESSED_FILES(0x0000)`       | 1      | 1/0    | Delete    |              |                                  |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 0      | 1/0    | Create    | Regenerate   |                                  |
   +------------------------------------------+--------+--------+-----------+--------------+----------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_KEPT`   | 0      | 0      | Create    | Regenerate   |                                  |
   | (0x0001)                                 +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 0      | 1      | Create    |Read |rproc|  |                                  |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 0      | Do nothing| Regenerate   | |rproc| is removed by filemanger |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                                  |
   +------------------------------------------+--------+--------+-----------+--------------+----------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_ADD_REM`| 0      | 0      | Create    | Regenerate   |                                  |
   | (0x0002)                                 +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 0      | 1      | Create    |Read |rproc|  |                                  |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 0      | Do nothing| Regenerate   | |rproc| is removed by filemanger |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                                  |
   +------------------------------------------+--------+--------+-----------+--------------+----------------------------------+
   | :phpc:`PROCESSED_FILES_ORIGINALS_REMOVED`| 0      | 0      | Create    | Regenerate   |                                  |
   | (0x0003)                                 +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 0      | 1      | Create    |Read |rproc|  |                                  |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 0      | Do nothing| Regenerate   | |rproc| is removed by filemanger |
   |                                          +--------+--------+-----------+--------------+----------------------------------+
   |                                          | 1      | 1      | Do nothing|Read |rproc|  |                                  |
   +------------------------------------------+--------+--------+-----------+--------------+----------------------------------+

.. _figure_DialogMsgBox_MediaProcessStatus_admin:

.. figure:: Fig_DialogMsgBox_MediaProcessStatus_Admin.png
   :width: 50%
   :align: center

   Media Processing Status dialog window for administrator. Note that there is an additional tab ("New/Removed media"). For more details see also :numref:`sec_L4_admin_user_update_needed`.

.. Section 3.3

Album main object definitions
=============================

.. _sec_L3_media_object:

Media object
------------
Object created and initialized by :php:func:`InitMediaObject()`, which is called at the beginning of :php:func:`dirThumbs()`. The initialization values are given in the second column of :numref:`table_Description_MediaObject`. Media object is updated by :php:func:`CheckProcessStatus_X000FF()`.

.. _sec_L4_media_object_definition:

Definition
^^^^^^^^^^

.. _table_Description_MediaObject:

.. table:: Description of Media object and its initialization values.
   :widths: 3 3 8
   :width: 85%
   :column-alignment: left center left

   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   |Object key                | Init value          | Comment                                                                                        |
   +==========================+=====================+================================================================================================+
   | :phpc:`CountList`        | Empty array         | See :numref:`table_mediaList`                                                                  |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`NoMedia`          | FALSE               |                                                                                                |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`UpdateAction`     | NO_MEDIA_PROCESSING | 3\ :sup:`rd` output argument of function :php:func:`RProc_FProc_Status_X00FF0()`. See also     |
   |                          |                     | :numref:`sec_L4_media_object_values`.                                                          |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`NewCount`         | 0                   | :php:`=NewImageCnt + NewVideoCnt`                                                              |
   |                          |                     |                                                                                                |
   |                          |                     | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`NewImageCnt`      | 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`NewVideoCnt`      | 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+ 
   | :phpc:`RemovedCount`     | 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+ 
   | :phpc:`ImInfoNT_ImageCnt`| 0                   | (NT = not transferred)                                                                         |
   |                          |                     |                                                                                                |
   |                          |                     | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+ 
   | :phpc:`ImInfoNT_VideoCnt`| 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+ 
   | :phpc:`PutBackM_ImageCnt`| 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`PutBackM_VideoCnt`| 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+
   | :phpc:`PutBackM_Cnt`     | 0                   | Value assigned in :php:func:`DetailedStatusAnalysis()`                                         |
   +--------------------------+---------------------+------------------------------------------------------------------------------------------------+

.. _sec_L4_media_object_values:
   
Values for UpdateAction
^^^^^^^^^^^^^^^^^^^^^^^
See also third output argument of function :php:func:`RProc_FProc_Status_X00FF0()`.

.. table:: Values for key :cf:`UpdateAction` of the :cf:`Media` object.
   :widths: 1 2
   :width: 85%
   :column-alignment: left left

   +----------------------------------------------+-------------------------------------------------------------------------------------------------+
   | :phpc:`NO_MEDIA_PROCESSING` (=0x00)          |                                                                                                 |
   |                                              | * Default value: Value returned by :php:func:`RProc_FProc_Status_X00FF0()` when both |fproc|    |
   |                                              |   and |rproc| exist.                                                                            |
   |                                              | * Value is assigned when :php:`$session['caller']==='child'`.                                   |
   +----------------------------------------------+-------------------------------------------------------------------------------------------------+
   | :phpc:`UPD_MEDIA_PROCESSING` (=0x02)         | Value returned by :php:func:`RProc_FProc_Status_X00FF0()` when |fproc| does not exist. This will|
   |                                              | result in the assignment :php:`$albumDirThumbStatHtml['status']['updateProgressDialogBox'] =    |
   |                                              | true` (see also :numref:`table32`) in the main script of |prepareDirOverviewGalleryAjax.php|,   | 
   |                                              | and will initiate the actual update process in JavaScript function                              |
   |                                              | :js:func:`prepareDirOverviewGallery`. See also :numref:`figure_AdminProcessFlow-2`.             |
   +----------------------------------------------+-------------------------------------------------------------------------------------------------+
   | :phpc:`ALL_MEDIA_PROCESSING` (=0x01)         | Value returned by :php:func:`RProc_FProc_Status_X00FF0()` when neither |fproc| nor |rproc| exist|
   | If \|F\|F\|F\|F\|●●XX\|==                    | (in case when the value of :php:`X0000F` is equal to :php:`PROCESSED_FILES_ORIGINALS_ADD_REM`   |
   | :phpc:`NO_PROCESSED_FILES`                   | or :php:`NO_PROCESSED_FILES`. See also :numref:`table0x0000F`.                                  |
   +----------------------------------------------+-------------------------------------------------------------------------------------------------+

Use and scope
^^^^^^^^^^^^^
The object is used as data member in the AJAX interface API object :php:interface:`albumDirThumbStatHtml_Object` (see :numref:`sec_L2_PHP_API_AJAX_Object`, and :numref:`table28`).

.. _sec_L3_XFFFFF_object:

:phpc:`XFFFFF` object
---------------------
Instance of the object is initialized in, and returned by :php:func:`CheckProcessStatus_X000FF()`. The values of the keys withe IP info about server side ad client side, are initialized to empty strings.

.. _sec_L4_XFFFFF_GlobStat:

Definition
^^^^^^^^^^

* :phpc:`['GlobStat']`: Hexadecimal number consisting of 5 digits: see :numref:`sec_L2_DefinedConstants` and :numref:`table26`.
* :phpc:`['FillStat']`: Hexadecimal mask (5 digits). The object :phpc:`$XFFFFF` is passed as an argument in various functions. This key holds a value which indicates which digit(s) of :phpc:`['GlobStat']` are changed by the calling function. For example: in the function :php:func:`CheckProcessStatus_X000FF()` the return value of :phpc:`$XFFFFF['FillStat']` is :phpc:`0x0000F` indicating that the fifth digit has been set to a value.
* :phpc:`['permissionDeleteProcFile']`: Boolean. True when user is allowed to delete file |fproc|. This is determined by the macro :phpc:`ALBUM_UPDATE_PERMISSION_LEVEL`, which is defined in |loginFunctions.php|. False otherwise.
* :phpc:`['server_ip']`: IP address of webserver.
* :phpc:`['client_ip']`: IP address of client server. On local host IP of webserver and client server are equal (127.0.0.1).

.. _sec_L4_XFFFFF_Global:

:phpc:`XFFFFF[GlobStat]` masks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _table_Mask-XFFFFF_def:

.. list-table:: Mask definition for :phpc:`XFFFFF[‘GlobStat’]`.
   :widths: 6 3 2 15
   :width: 90%
   :header-rows: 1
   
   * - Mask name
     - Mask value
     - Position
     - Note
   * - :phpc:`RESIZE_STAT_MASK`
     - 0x0000F (1111)
     - 1
     - All bits of position 1
   * - :phpc:`RESIZE_STAT_MASK_2`
     - 0x00003 (0011)
     - 1
     -
   * - :phpc:`RESIZE_STAT_MASK_TIMECHANGE`
     - 0x0000C (1100)
     - 1
     - Mask for determining the date/time related bits
   * - :phpc:`FPROC_STAT_MASK`
     - 0x000F0
     - 2
     - All bits of position 2
   * - :phpc:`RPROC_STAT_MASK`
     - 0x00F00
     - 3
     - All bits of position 3
   * - :phpc:`UPD_STAT_MASK`
     - 0x0F000
     - 4
     - All bits of position 4
   * - :phpc:`RPROC_UPD_MEDIA_MASK`
     - 0xF0000
     - 5
     - All bits of position 5
   * - :phpc:`ADMIN_LOGIN_MASK`
     - | 0xF0E0C
       | F = 1111
       | E = 1110
       | C = 1100
     -
     - | If the result of masking :phpc:`XFFFFF[GlobStat]` with :phpc:`ADMIN_LOGIN_MASK` is not zero, then updating is needed which can only be done by someone with administrator rights. As a result, a message box will pop-up giving the end-user the option for logging in as administrator directly.
       | If the result of the masking is zero, then no message box will pop up. Reason for administrator log in could be:

       * Position 1 (C-mask): :phpc:`LOCATION_DIR_HAS_CHANGED`, :phpc:`PUBLIC_DIR_HAS_CHANGED`,
       * Position 3 (E-mask): The first bit of position 3 indicates if the file :cf:`rproc.txt` exists or not. As :cf:`rproc.txt` normally exists this bit is ignored when determining whether to propose administrator log on or not. The other 3 bits, however, indicate how to update the file :cf:`rproc.txt` file and this can only be done with administrator rights.
       * Position 5 (F-mask):

Use and scope
^^^^^^^^^^^^^

.. _sec_L3_XFFFFF_Arr_object:

:phpc:`XFFFFF_Arr` object
-------------------------
Instance of the object is initialized in, and returned by :php:func:`CheckProcessStatus_X000FF()`.

Definition
^^^^^^^^^^
Media status array for each location directory, where the array index is a numerical key. Each array element of :phpc:`XFFFFF_Arr` has the following keys (see also :numref:`table_example_xfffff_arr`):

* :phpc:`['locDirname']`: directory name,
* :phpc:`['XFFFFF']`:

  * XFFFF\ :it-blue:`F` (1): set in function :php:func:`CheckProcessStatus_X000FF()`. Not all bits are checked.
  * XFFF\ :it-blue:`F`\ F (2): IS STILL MISSING!! IS IT NEEDED??
  * X\ :it-blue:`F`\ F\ :it-blue:`F`\ FF (3, 5): set in function |CompareMediaCntRprocLocDir_XF0F00|.
  * XF\ :it-blue:`F`\ FFF (4): set in function :php:func:`Mediacount_IMINFO_X0F000`.
* :phpc:`['dirAccessTime']`: timestamp of directory at the beginning of calling :php:func:`dirThumbs()`.
* :phpc:`['iminfoAccessTime']`: timestamp of |iminfo| file at the beginning of calling :php:func:`dirThumbs()`.
* :phpc:`['resizedAccessTime']`: timestamp of public/private directory at the beginning of calling :php:func:`dirThumbs()`.

Timestamps are rounded - off of the time returned by the PHP function `filemtime() <https://www.php.net/filemtime>`_, which returns a UNIX format timestamp (i.e. number of seconds since January 1st, 1970: rounded - off to minutes, and converted back to seconds.

Use and scope
^^^^^^^^^^^^^

#. The main instance of the object :phpc:`XFFFFF_Arr` is initialized in the function :php:func:`CheckProcessStatus_X000FF()` and is only used in in function :php:func:`dirThumbs()` and functions called inside :php:func:`dirThumbs()`.
#. The variable is transferred by means of a JSON object to the update function, initiated by a user with proper permissions, :php:func:`update_media_directories()`, implemented in file |media-update-progress.php|.

.. _sec_L4_example_XFFFFF_Arr_object:

Example as return value of :php:func:`CheckProcessStatus_X000FF()` when |phpdef| exists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _table_example_xfffff_arr:

.. table:: Initialization in :php:func:`CheckProcessStatus_X000FF()` when |phpdef| exists.
   :widths: 3 5 5 5 5 5
   :width: 75%
   :column-alignment: center left left left left left
   :header-alignment: center center center center center center

   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | Array  | Assoc.key:        | Assoc.key:    | Assoc.key:    | Assoc.key:       | Assoc.key:        |
   | index  | locDirname        | XFFFFF status | dirAccessTime | iminfoAccessTime | resizedAccessTime |
   +========+===================+===============+===============+==================+===================+
   | 0	    | DeReis            |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 1      | Weeshuis          |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 2      | HoChiMinh         |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 3      | DaguitHCM-TayNinh |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 4      | DaguitHCM-Mekong  |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 5      | Mui Ne            |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 6      | Dalat             |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 7      | Nha Trang         |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 8      | Hoian             |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 9      | Hue               |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 10     | Hanoi             |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+
   | 11	    | Halong Bay        |               |               |                  |                   |
   +--------+-------------------+---------------+---------------+------------------+-------------------+

.. _sec_L3_Iminfo_object:

:phpc:`iminfo` object
---------------------
Definition
^^^^^^^^^^
Content of each :cf:`iminfo.xml` file is stored in PHP `SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_. See also :numref:`sec_L3_iminfo`.

:phpc:`update_iminfo` object
----------------------------
Definition
^^^^^^^^^^
Array with length determined by the number of locations (each location directory has an |iminfo| file). Each element of the object is 2 bits hexadecimal number, which represents how to update the iminfo.xml in
each location directory. Object is initialized in function :php:func:`check_mediacount_iminfo_files()`.