.. include:: definitions.txt

Functions in file iminfo_xhr.php
********************************

.. contents:: Function content
  :depth: 2

.. _PrivateVariables_iminfo_xhr:

.. rst-class:: html-toggle

Private variables
=================

Private data in :php:func:`check_mediacount_iminfo_files()`
-----------------------------------------------------------

.. php:attr:: $update_iminfo

  Private data array of integers. Array length is determined by the number of locations (each location directory has an |iminfo| file). Each number represents how to update the |iminfo| in each location directory. Possible values for each array element are:

  * :phpc:`UPDATE_IMINFO_NOFILE` (0x0): the file |iminfo| needs to be generated with the available information,
  * :phpc:`UPDATE_IMINFO_EXISTS_OK` (0x1): default situation,
  * :phpc:`UPDATE_IMINFO_MEDIACOUNT` (0x2): the file |iminfo| needs to be updated because media content in public and/or private directories has been changed (removing and adding media).

    * In the normal workflow of adding new media, media is added to a location directory. Updating to public or private directories need confirmation by the owner or administrator, i.e. different type of update process compared to adding media directly public and or private directories, which is not the recommended workflow of adding new media (see next bullet)
    * New media has been added directly to public and or private directories. When this is detected the |iminfo| must be updated automatically without user or administrator credentials.

  The update will result in:

  * Adding or removing media elements (i.e. :cf:`<media> … </media>`,
  * Updating elements:

    * :cf:`<ImageInfo><PublicCount>NN</PublicCount></ImageInfo>`,
    * :cf:`<VideoInfo><PublicCount>NN</PublicCount></VideoInfo>`, and 
    * :cf:`<VideoInfo><PublicFilesCount>NN</PublicFilesCount></VideoInfo>`

  * :phpc:`UPDATE_IMINFO_VERSION` (0x4): the file |iminfo| needs to be updated (internal structure is modified and must be such that it is backwards compatible),
  * :phpc:`UPDATE_IMINFO_MAXCOUNT` (0x8),

.. php:attr:: $Iminfo_check

   Private data array (matrix): #rows= #locations, #columns=8: columns are specified with associative keys

   * Column 1 :phpc:`[‘xml_pub_im’]`: number of public images in |iminfo|,
   * Column 2 :phpc:`[‘xml_pub_vi’]`: number of public videos in |iminfo|,
   * Column 3 :phpc:`[‘xml_prv_im’]`: number of private images in |iminfo|,
   * Column 4 :phpc:`[‘xml_prv_vi’]`: number of private videos in |iminfo|,
   * Column 5 :phpc:`[‘xml_r_pub_im’]`: number of public released images in |iminfo|,
   * Column 6 :phpc:`[‘xml_r_pub_vi’]`: number of public released videos in |iminfo|,
   * Column 7 :phpc:`[‘xml_r_prv_im’]`: number of private released images in |iminfo|,
   * Column 8 :phpc:`[‘xml_r_prv_vi’]`: number of private released videos in |iminfo|,
   * Column 5 :phpc:`[‘loc_pub_im’]`: number of images in public directory,
   * Column 6 :phpc:`[‘loc_pub_vi’]`: number of videos in public directory

.. php:attr:: $update_media_dir

   Private data array with numerical keys and the length is determined by the number of locations. Each element is an array with 2 associative keys:
  
   * Column 1 :phpc:`[‘name’]`: Name of location directory
   * Column 1 :phpc:`[‘modus’]`: Update modus. Initialization value: :phpc:`UPD_NOTHING`. For other values: see :numref:`table0x0F000`.

Private data in :php:func:`Iminfo_XML_Objects_UpdateAndSave()`, :php:func:`updateIminfoFiles()`
-----------------------------------------------------------------------------------------------
  
.. php:attr:: $upd_succ

  Private datastructure: Numerical array with length of :phpc:`count($new_media_list)` where each element is an array with the following keys:
  
  * :phpc:`'status' => UPDATE_IMINFO_EXISTS_OK`,
  * :phpc:`'directory' => ''`,
  * :phpc:`'fname' => 'iminfo.xml'`,
  * :phpc:`'reason'=> ''`,
  * :phpc:`'code' => 0`,
  * :phpc:`'iminfo_version' => $iminfo_version`.

Private data in :php:func:`DetailedStatusAnalysis()`
----------------------------------------------------

.. php:attr:: $new_media

  Private datastructure: Object structure is also shown in :numref:`figure_newmedia_listobject`. Array with new media, and array length is determined by the number of locations and location directoryname is primary key. Each element has 4 sub-object identified with sub-keys:

  #. :phpc:`$NewMedia[‘location’][‘image_files’][$i][0]`: 2 index - array with numerical keys for new image filenames. Each element has 3 associated subkeys:

     i. First index (:phpc:`$i`): new image media counter.
     ii. Second index: :phpc:`0` (use of second index is to be consistent with the :phpc:`[‘video_files’]` sub-object.

     * :phpc:`[‘name’]`: (String) filename of new image,
     * :phpc:`[‘pubpriv’]`: (String) new image must be stored in :phpc:`'public'` or :phpc:`'private'` directory.
     * :phpc:`[‘tableEntry’]`: (Integer) -1, which is an initialization value. Row position in the table is not yet known (see :numref:`figure_NewMediaDetected` and :numref:`figure_RemovedMediaDetected`).
  #. :phpc:`$NewMedia[‘location’][‘video_files’][$i][$k]`: 2 index – array with numerical keys for new video filenames. Each element has 3 associated subkeys:

     i. First index (:phpc:`$i`): new video media counter.
     ii. Second index (:phpc:`$k`): number of different video formats for the current video (i.e. files with same basename but with different extensions. E.g.: :file:`video_file.mp4`, and :file:`video_file.webm` represent the same video media, but there are 2 files). The element itself has 3 associated subkeys (such as for images):

     * :phpc:`[‘name’]`: (String) filename of the new video,
     * :phpc:`[‘pubpriv’]`: (String) new video must be stored in public or private directory (the same for all the different video formats of the same video).
     * :phpc:`[‘tableEntry’]`: (Intger) -1, which is an initialization value. Row position in the table is not yet known (see :numref:`figure_NewMediaDetected` and :numref:`figure_RemovedMediaDetected`).
  #. :phpc:`$NewMedia[‘location’][‘image_count’]`: Number of new image media filenames,
  #. :phpc:`$NewMedia[‘location’][‘video_count’]`: Number of new video media filenames. Video filenames with the same basename but with different extensions will be considered as only one filename!

  Remark: if no new media is detected this output argument is NOT empty. The length of the array is determined by the number of location directories. This means the array length does not to be equal to the number new media.

.. php:attr:: $rem_media

  Private datastructure: Array with associative keys (location directory names) length determined by the number of locations. Each element is a numerical ( :phpc:`$k`) array with length determined by the number of removed media. Each element of this array is a smaller object (array) with the following associative keys:
  
  #. :phpc:`$RemMedia[‘location’][$k]['name']`: (String) filename of media selected to be removed,
  #. :phpc:`$RemMedia[‘location’][$k]['public_private']`: (String) :phpc:`'public'` or :phpc:`'private'`,
  #. :phpc:`$RemMedia[‘location’][$k]['TransferStatus']`: (Integer) See :numref:`table_Trans2SiteDir`,
  #. :phpc:`$RemMedia[‘location’][$k]['location_org_name']` (String) Original filename of media,
  #. :phpc:`$RemMedia[‘location’][$k][‘tableEntry’]`: -1, which is an initialization value. Row position in the table is not yet known (see :numref:`figure_NewMediaDetected` and :numref:`figure_RemovedMediaDetected`).

  Remark: The length of the output array is equal to the number of removed medias. If no removed media is detected the output argument is an empty array. The datastructure of :phpc:`$RemMedia` is different compared to the structure of :phpc:`$NewMedia`.
  
.. _f_check_mediacount_iminfo_files:

.. rst-class:: html-toggle

check_mediacount_iminfo_files()
================================

.. rubric:: Interface definition

.. php:function:: check_mediacount_iminfo_files(&$statDB_html, $xmlDefs, $modalClassID, $media)

   Function checks consistency of |iminfo| files in each “location” directory, and how media should be updated: image and video count stored in |iminfo| are compared with image and video count in public and private directories. When logged on the “Media processing status” tables are displayed: this function will generate table 1 (XML tab in :numref:`figure_27`).
   When updating is needed based on media count, the tab (1) in media status window is shown with a red border. |iminfo| file has different media count types ():

   #. :cf:`PublicCount`: all media (images or videos) with public tag, transferred or not transferred, i.e. the tag :cf:`Transferred2SiteDir` can have the values: :phpc:`TRANSFER_NONE, TRANSFER2PUBLIC, TRANSFER2PRIVATE, TRANSFER2PUBLIC_AGAIN, TRANSFER2PRIVATE_AGAIN,` or :phpc:`TRANSFER_FIRST_TIME_SCHEDULED` (see :numref:`sec_L4_image_media_tag` and :numref:`sec_L4_video_media_tag`). Values of these constants are given in :numref:`table_Trans2SiteDir`.
   #. :cf:`PrivateCount`: all media with private tag, transferred or not.
   #. :cf:`TransferCount = TransferCountPublic + TransferCountPrivate`,
   #. :cf:`TransferCountPublic`: all transferred media with public tag: The tag :cf:`Transferred2SiteDir = 1` ( :phpc:`TRANSFER2PUBLIC`).
   #. :cf:`TransferCountPrivate`: all transferred media with private tag: The tag :cf:`Transferred2SiteDir = 2` ( :phpc:`TRANSFER2PRIVATE`).

   Updating is needed in a location directory when count of media with tag :cf:`Transferred2SiteDir` :phpc:`= TRANSFER2PUBLIC_AGAIN`, or :cf:`Transferred2SiteDir` :phpc:`= TRANSFER2PRIVATE_AGAIN` is larger than 0.

   :param &$statDB_html: Pointer to Object of type :php:interface:`htmlStatCode_Object` (see also :numref:`table31`)
   :type &$statDB_html:
   :param $xmlDefs: `SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`phpdefinition.xml <sec_L3_phpdef>`
   :type $xmlDefs: Object
   :param $modalClassID: modal dialog ID for JQUERY
   :type $modalClassID: String
   :param $media: :ref:`Media object <sec_L3_media_object>`, is initialized in :php:func:`CheckProcessStatus_X000FF()`
   :type $media: Object
   :return:

           #. **$update_iminfo** ( *Object* ) - See object definition :php:attr:`$update_iminfo`. 
              Note: when the function is called after :php:func:`Iminfo_XML_Objects_UpdateAndSave()` the |iminfo| have been updated already and this output array will only contain 0’s.
           #. **$update_media_dir** ( *Object* ) - If |iminfo| has to be updated because of changed media count in at least one of the public or private directories, then this output variable has info about what kind of updates needs to be done in each |iminfo| file. :phpc:`$update_media_dir` is a matrix: #rows= #locations, #columns=2: columns are specified with associative keys:
		   
              * Column 1 [‘name’]: name of location directory,
              * Column 2 [‘modus’]: 4 bits number (see also :numref:`table0x0F000`): specifies what and where new media must be updated,

                 * Bit 1: :phpc:`UPD_PUB_IMAGES` (0x01000 = 4096) [●●●● 0001 ●●●● ●●●● ●●●●]
                 * Bit 2: :phpc:`UPD_PUB_VIDEOS` (0x02000 = 8192) [●●●● 0010 ●●●● ●●●● ●●●●]
                 * Bit 3: :phpc:`UPD_PRV_IMAGES` (0x04000 = 16384) [●●●● 0100 ●●●● ●●●● ●●●●]
                 * Bit 4: :phpc:`UPD_PRV_VIDEOS` (0x08000 = 32768) [●●●● 1000 ●●●● ●●●● ●●●●]
           #. **$Iminfo_check** ( *2 dimensional Array* ) - See object definition :php:attr:`$Iminfo_check`.

             The information in this output argument is used for generating the page with the overview of locations of an album (location directories, days of bicycle holiday). This information is in principle also available in |iminfo| (:cf:`<ImageInfo><PublicCount> xx </PublicCount></ImageInfo>`). Opportunity for code optimization: output argument is not needed |r_arrow| remove code which is generating this variable.

.. table:: 
   :widths: 1 1

   +--------------------------------------------------------------+-------------------------------------------------------------------+
   |                                                              |                                                                   |
   | .. figure:: Fig_DialogMsgBox_MediaProcessStatus_Admin(2).png | .. figure:: Fig_DialogMsgBox_MediaProcessStatus_NormalUser(2).png |
   |    :width: 100%                                              |    :width: 100%                                                   |
   +--------------------------------------------------------------+-------------------------------------------------------------------+
   | .. _figure_27:                                                                                                                   |
   |                                                                                                                                  |
   | .. figure:: EmptyFigure.png                                                                                                      |
   |                                                                                                                                  |
   |    Media Processing Status dialog window. Left: admin user or local host. Right: “normal” user.                                  |
   +--------------------------------------------------------------+-------------------------------------------------------------------+

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: check_mediacount_iminfo_files_Begin
   :end-before: check_mediacount_iminfo_files_End

.. _DetailedStatusAnalysis:

.. rst-class:: html-toggle

DetailedStatusAnalysis(…)
=========================

.. rubric:: Interface definition

.. php:function:: DetailedStatusAnalysis($iminfo_objs, $media, $scheme)

   Executes a detailed status analysis in each location directory: all media filenames in a location directory are compared with the filenames of media in public and private directories (info is stored in |iminfo| file in each location directory). Differences mean that either media in public and or private directories have been added and/or deleted, and are determined with the PHP function `array_diff() <https://www.php.net/manual/en/function.array-diff.php>`_, using the following code :phpc:`$df=array_diff($imlistLocation,$mListOrgFnames);`

   The function `array_diff() <https://www.php.net/manual/en/function.array-diff.php>`_ returns the values in array :phpc:`$imlistLocation` that are not present in array :phpc:`$mListOrgFnames`. This means only media in location directories with filenames which are NOT known to |iminfo| are considered as new media.
   
   Function is called by :php:func:`dirThumbs()`.
   
   :param $iminfo_objs: Array of `SimpleXMLElement objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`Iminfo.xml files <sec_L3_Iminfo_object>`
   :type $iminfo_objs: Object
   :param $media: :ref:`Media object <sec_L3_media_object>`, is initialized in :php:func:`CheckProcessStatus_X000FF()`
   :type $media: Object
   :param $scheme:
   :type $scheme: Integer
   :return:

           #. **$media** ( *Object* ) - updated :ref:`Media object <sec_L3_media_object>`. Following keys are changed:

              a. :phpc:`$media[‘NewImageCnt’]`
              b. :phpc:`$media[‘NewVideoCnt’]`
              c. :phpc:`$media[‘NewCount’]`
              d. :phpc:`$media[‘RemovedCount’]`
              e. :phpc:`$media['ImInfoNT_ImageCnt']`
              f. :phpc:`$media['ImInfoNT_VideoCnt']`
              g. :phpc:`$media['PutBackM_ImageCnt']`
              h. :phpc:`$media['PutBackM_VideoCnt']`
              i. :phpc:`$media['PutBackM_Cnt']`
           #. **$NewMedia** (*Object* ) - list with new media. Object definition: see :php:attr:`$new_media` Object structure is (also shown in :numref:`figure_newmedia_listobject`):
           #. **$RemMedia** (*Object* ) - list (array) with removed media. Object definition: see :php:attr:`$rem_media`.

.. _figure_newmedia_listobject:

.. figure:: Fig_NewMediaListObject.png
   :width: 70%
   :align: center

   New media list object.

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: DetailedStatusAnalysis_Begin
   :end-before: DetailedStatusAnalysis_End

.. _GetIminfoObjects:

.. rst-class:: html-toggle

GetIminfoObjects()
==================

.. rubric:: Interface definition

.. php:function:: GetIminfoObjects($xmlDefs)

   :param Object $xmlDefs: `SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`phpdefinition.xml <sec_L3_phpdef>`.
   :return: **$iminfo_objs**:  Array of `SimpleXMLElement objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`Iminfo.xml files <sec_L3_Iminfo_object>`.

.. _get_medianames_from_iminfo_dum:

.. rst-class:: html-toggle

get_medianames_from_iminfo(…)
=============================

.. rubric:: Interface definition

.. php:function:: get_medianames_from_iminfo($xml_iminfo)

   Get media filenames from :ref:`iminfo objects <sec_L3_Iminfo_object>`. The filenames are retrieved from the :cf:`<media>` elements in the iminfo objects (see :numref:`codeblock-xml-image-tag` and :numref:`codeblock-xml-video-tag`). A video :cf:`<media>` element may refer to multiple videofiles (same video content but with different video codecs/format, i.e. different file extensions). Videofiles with the same basename but with :cf:`n` different file extensions are considered as :cf:`n` different media files.

   :param Object $iminfo_objs: Array of `SimpleXMLElement objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`Iminfo.xml files <sec_L3_Iminfo_object>`.
   :return:

           #. **$mListOrg** ( *List object* ) - media list array with numerical keys. Each array element has the following keys:

              a) :phpc:`[‘fname’]`: original filename ( :phpc:`$media->OriginalFile->__toString()`),
              b) :phpc:`[‘TrStat’]`: transfer status (see :numref:`table_Trans2SiteDir`, :phpc:`$media->Transferred2SiteDir`),
              c) :phpc:`[‘mtype’]`: media type ( :phpc:`media->MIMETYPE->children()->getName()`).
           #. **$mListSorted** ( *List object* ) - time sorted media list array with numerical keys. Each array element has the following keys:

              a) :phpc:`[‘fname’]`: time sorted filename ( :phpc:`$media->TimeSortedFile->__toString()`),
              b) :phpc:`[‘TrStat’]`: transfer status (see :numref:`table_Trans2SiteDir`),
              c) :phpc:`[‘mtype’]`: media type ( :phpc:`media->MIMETYPE->children()->getName()`),
              d) :phpc:`[‘TimeStamp’]`: timestamp ( :phpc:`$media->TimeStamp`).
           #. **$mListSorted_Public** ( *List object* ) - time sorted public media list array with numerical keys.
           #. **$mListSorted_Private** ( *List object* ) - time sorted private media list array with numerical keys.
           #. **$count** ( *Array* ) - Array with 2 associative keys:

              a) :phpc:`['publicFiles']`: :phpc:`$xml_iminfo->ImageInfo->PublicCount+$xml_iminfo->VideoInfo->PublicFilesCount`
              b) :phpc:`['privateFiles']`: :phpc:`$xml_iminfo->ImageInfo->PrivateCount+$xml_iminfo->VideoInfo->PrivateFilesCount`
			  
.. _ImArray2IminfoXML:

.. rst-class:: html-toggle

ImArray2IminfoXML(…)
====================

.. rubric:: Interface definition

.. php:function:: ImArray2IminfoXML($imArray, $ldir, $xml_name)

   Converts :phpc:`$imArray` matrix data structure (derived from :file:`iminfo.txt`) to |iminfo| file with a given name :phpc:`$xml_name` in location directory :phpc:`$ldir`. The format of :file:`iminfo.txt` is given in :numref:`codeblock-txt-iminfo`. Function is called in function :php:func:`IminfoTXT2IminfoXML()`

   :param Matrix $imArray: Matrix data content of :file:`iminfo.txt`, and is assigned in function :php:func:`IminfoTXT2IminfoXML()`.
   :param String $ldir: location / date directory name.
   :param String $xml_name: filename of iminfo file (standard iminfo filename is |iminfo|).
   :return:
   
           #. **SaveStatus** ( *Integer* ) - 

              * 0: Failed to save $imArray to iminfo file with name $xml_name.
              * 1: :phpc:`$xml_name` is successfully saved.

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: ImArray2IminfoXML_Begin
   :end-before: ImArray2IminfoXML_End

.. _IminfoNewImageObject:

.. rst-class:: html-toggle

IminfoNewImageObject(…)
=======================

.. rubric:: Interface definition

.. php:function:: IminfoNewImageObject($exif)

   Create new image media `SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_ . (See :numref:`sec_L4_image_media_tag`). Function is called by :php:func:`Iminfo_XML_Objects_UpdateAndSave()`, and :py:mod:`php\\analyse_status_table.php`.

   :param Array $exif: Return value of `exif_read_data() <https://www.php.net/manual/en/function.exif-read-data.php>`_ . :phpc:`$exif` is metadata of the new image.
   :return: :ref:`Image media <sec_L4_image_media_tag>` object (`SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_)
   
.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: IminfoNewImageObject_Begin
   :end-before: IminfoNewImageObject_End

.. _IminfoNewVideoObject:

.. rst-class:: html-toggle

IminfoNewVideoObject(…)
=======================

.. rubric:: Interface definition

.. php:function:: IminfoNewVideoObject($exif)

   Create new video media `SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_ .(See :numref:`sec_L4_video_media_tag`). Function is called by :php:func:`Iminfo_XML_Objects_UpdateAndSave()`, and :py:mod:`php\\analyse_status_table.php`.

   :param Array $exif: Return value of `exif_read_data() <https://www.php.net/manual/en/function.exif-read-data.php>`_ . :phpc:`$exif` is metadata of the new video. Video metadata is retrieved with PHP package :ref:`getID3 <sec_L3_getID3>`.
   :return: :ref:`Video media <sec_L4_video_media_tag>` object (`SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_)
   
.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: IminfoNewVideoObject_Begin
   :end-before: IminfoNewVideoObject_End

.. _IminfoTXT2IminfoXML:

.. rst-class:: html-toggle

IminfoTXT2IminfoXML(…)
======================

.. rubric:: Interface definition

.. php:function:: IminfoTXT2IminfoXML($deb_test, $ldir, $timeStr)

  :file:`iminfo.txt` files were the first format to store media information in a description file (see also :numref:`sec_L3_iminfo_txt`).
  Converts a :file:`iminfo.txt` file to an |iminfo| file in location directory :phpc:`$ldir`. Th actual conversion is done by calling function :php:func:`ImArray2IminfoXML()`.
  In DEBUG mode the converted :file:`iminfo.txt` to :cf:`iminfo_updateIminfoXMLFile.xml` if there is already an |iminfo| file. In non DEBUG mode and if there is already an |iminfo| file it will be renamed by appending :phpc:`timeStr` to the filename. Function will become obsolete.

   :param Boolean $deb_test: Debug test purpose.
   :param String $ldir: location / date directory name
   :param String $timeStr: 
   :return:
   
           #. **Status** ( *Integer* ) - :phpc:`E_IMINFO_FS_W, E_IMINFO_TXT_1, E_IMINFO_TXT_2, E_IMINFO_UPD_OK, E_IMINFO_UPD_OK_B, E_IMINFO_CRE_OK`
           #. Name of IMINFO XML file or NULL if no XML file is generated.


.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: IminfoTXT2IminfoXML_Begin
   :end-before: IminfoTXT2IminfoXML_End

.. _Iminfo_XML_Objects_UpdateAndSave:

.. rst-class:: html-toggle

Iminfo_XML_Objects_UpdateAndSave(…)
===================================

.. rubric:: Interface definition

.. php:function:: Iminfo_XML_Objects_UpdateAndSave($doZIP, &$iminfo_objs, $new_media_list, $XFFFFF, $server_info, $send_email=FALSE)

   Function updates IMINFO object with new media entries, and is called in :php:func:`dirThumbs()`.

   :param Boolean $doZIP: If :phpc:`TRUE` |iminfo| files, which will be updated (overwritten) will be zipped first.
   :param Object $iminfo_objs: Array of `SimpleXMLElement objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`Iminfo.xml files <sec_L3_Iminfo_object>`
   :param Array $new_media_list: Array of :php:attr:`$new_media` objects
   :param Array $XFFFFF: Data :ref:`$XFFFFF <sec_L3_XFFFFF_object>` is not used for updating IMINFO objects, but as additional information in notifying e-mail.
   :param Object $server_info: Data :phpc:`$server_info` (:php:interface:`server_info_Object` object) is not used for updating IMINFO objects, but as additional information in notifying e-mail.
   :param Boolean $send_email: Optional argument (default FALSE). If :phpc:`TRUE`, email will be sent by calling :php:func:`send_email_update_iminfo()`.
   :return: Void
   
   Internal data object :php:attr:`$upd_succ`

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: Iminfo_XML_Objects_UpdateAndSave_Begin
   :end-before: Iminfo_XML_Objects_UpdateAndSave_End

.. _f_send_email_update_iminfo:

.. rst-class:: html-toggle

send_email_update_iminfo(…)
===========================

.. rubric:: Interface definition

.. php:function:: send_email_update_iminfo($nIminfoInZIP, $zipname, $wdir, $upd_success, $XFFFFF, $server_info, $caller)

   Called by :php:func:`Iminfo_XML_Objects_UpdateAndSave()`, :php:func:`updateIminfoFiles()`, and :py:mod:`php\\Imageresizeprocess.php`.

   :param Integer $nIminfoInZIP: Number of |iminfo| files in ZIP.
   :param String $zipname: Name of the ZIP file.
   :param String $wdir: Location directory name.
   :param Array $upd_success: :php:attr:`$upd_succ` Private data of :php:func:`Iminfo_XML_Objects_UpdateAndSave()` and :php:func:`updateIminfoFiles()`.
   :param Object $XFFFFF: See :ref:`object definition <sec_L3_XFFFFF_object>`.
   :param Object $server_info: See :php:interface:`server_info_Object` object.
   :param String $caller:
   :return: :phpc:`array($status, $mail->ErrorInfo)`

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: send_email_update_iminfo_Begin
   :end-before: send_email_update_iminfo_End

.. _f_updateIminfoXMLFile:

.. rst-class:: html-toggle

updateIminfoXMLFile(…)
======================

.. rubric:: Interface definition

.. php:function:: updateIminfoXMLFile($deb_test, $ldir, $timeStr, $xml_data, $preserveDateModified)

   Function is called by :php:func:`updateIminfoFiles()`

   :param Boolean $deb_test: Debug test purpose.
   :param String $ldir: location directory name
   :param String $timeStr: Time string
   :param $xml_data: :ref:`Iminfo <sec_L3_iminfo>` data object (`SimpleXMLElement object <https://www.php.net/manual/en/class.simplexmlelement.php>`_)
   :param $preserveDateModified:
   :type $preserveDateModified: Integer - Octogonal format
   :return:

           #. **$outVal** ( ** ),
           #. **$xml_name** ( *String* ) - name of iminfo filename to which the updated iminfo object is saved.

.. _f_updateIminfoFiles:

.. rst-class:: html-toggle

updateIminfoFiles(…)
====================

.. rubric:: Interface definition

.. php:function:: updateIminfoFiles($mod, $updIminfo, $iminfo_objs, $XFFFFF, $send_email=FALSE)

   Function for updating all |iminfo|'s only (no media updating) and for all users as well as for privileged user (admin, …) in the UPDATE-1 process phase. The conditions for calling UPDATE-1 process are described in :numref:`table_updateIminfoFiles`.

   Function is called by :php:func:`dirThumbs()`. Internal data object :php:attr:`$upd_succ`.
   
   :param $mod: Determines update method
   
          * 1: updating iminfo by calling :php:func:`IminfoTXT2IminfoXML()`
          * 2: updating iminfo by calling :php:func:`updateIminfoXMLFile()`
   :type $mod: Integer
   :param $updIminfo: Data object (see :ref:`PrivateVariables_iminfo_xhr` and :php:attr:`$update_iminfo`) returned by first output argument of :php:func:`check_mediacount_iminfo_files()`
   :type $updIminfo: Object
   :param Object $iminfo_objs: Array of `SimpleXMLElement objects <https://www.php.net/manual/en/class.simplexmlelement.php>`_ of :ref:`Iminfo.xml files <sec_L3_Iminfo_object>`
   :param Object $XFFFFF: See :ref:`object definition <sec_L3_XFFFFF_object>`.
   :param Boolean $send_email: optional argument, default = :phpc:`FALSE`
   :return:

           #. **$FinalUpdateStat** ( *Intger* ) - Result depends on the values in the array :phpc:`$upd_succ[$i]['status']`, where :phpc:`$i` is a counter over the number of location directories.

.. _table_updateIminfoFiles:

.. table:: Reasons for updating |iminfo|.
   :widths: 1 7 15 5
   :column-alignment: center center left center
   :header-alignment: center center left center
   :width: 80%
   
   +---+----------------------------------+-------------------------------------------------------------+------------+
   |   |  Reason                          |                                                             |Implemented |
   +===+==================================+=============================================================+============+
   | 1 || :phpc:`UPDATE_IMINFO_MEDIACOUNT`|                                                             |    NO      |
   |   || 0x2                             | * #public images in IMINFO file < location directory        |            |
   |   |                                  | * #public videos in IMINFO file < location directory        |            |
   |   |                                  | * #private images in IMINFO file < location directory       |            |
   |   |                                  | * #private videos in IMINFO file < location directory       |            |
   +---+----------------------------------+-------------------------------------------------------------+------------+
   | 2 || :phpc:`UPDATE_IMINFO_VERSION`   | IMINFO version has changed (defined by                      |   YES      |
   |   || 0x4                             | :phpc:`IMINFO_VERSION` = 20170525H2314)                     |            |
   +---+----------------------------------+-------------------------------------------------------------+------------+
   | 3 || :phpc:`UPDATE_IMINFO_MAXCOUNT`  | :phpc:`$xml->media->count()≠$xml->MediaCounterInfo->MaxCnt.`|   YES      |
   |   || 0x8                             | Normally, this should not occur.                            |            |
   +---+----------------------------------+-------------------------------------------------------------+------------+

.. rst-class:: html-toggle

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

.. literalinclude:: ..\..\..\php\iminfo_xhr.php
   :language: php
   :prepend: <?php
   :start-after: updateIminfoFiles_Begin
   :end-before: updateIminfoFiles_End