#/***************************************************************************
#                         io disk_ mediaAccess_ Common Commands Specification
#                         +++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : specifies the common commands for media handler
#                           functions for "mediaAccess"
#
#     begin               : Fri May 19 19:09:28 CEST 2017
#
#     changes             :
#
#     copyright           : (C) 2017 by Thomas Bruecker
#
#     email               : public@thomas-r-bruecker.ch
#
#     version             : -0.0.0
#
#***************************************************************************/

#/***************************************************************************
# *                                                                         *
# *   This program is free software; you can redistribute it and/or modify  *
# *   it under the terms of the GNU General Public License as published by  *
# *   the Free Software Foundation; either version 2 of the License, or     *
# *   (at your option) any later version.                                   *
# *                                                                         *
# *   This program is distributed in the hope that it will be useful, but   *
# *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU      *
# *   General Public License for more details.                              *
# *                                                                         *
# *   You should have received a copy of the GNU General Public License     *
# *   along with this program; if not, write to the Free Software           *
# *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,            *
# *   MA 02110-1301 USA.                                                    *
# *                                                                         *
# ***************************************************************************/

* function parameters "$1", "$2", "$3":
  * $1: command, in {
      "2ChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
      "SIZE", "VERIFY", "WAIT"
    }:
    * "2ChildDev":     maps the media (converts the media), denoted by the
                       <ParentMedia> and the <index into the container>
                       to the qualified block-device-path and writes it to
                       "stdout";
                       $2: <ParentMedia>,
                       $3: index into the container;
    * "2ChildMedia":   maps the media (converts the media), denoted by the
                       <ParentMedia> and the <index into the container> to the
                       qualified child-media-name and writes it to "stdout";
                       $2: <ParentMedia>,
                       $3: index into the container;
    * "DESTROY":       destroys the media, no output;
                       $2: <ParentMedia>,
                       $3: index into the container;
    * "REALIZE":       realizes the media, and writes the qualified name of
                       the realized media (the qualified child-media-name) to
                       "stdout";
                       $2: <ParentMedia>,
                       $3: index into the container;
    * "RealizeForced": realizes the media forced, and writes the qualified
                       name of the realized media (the qualified child-media-
                       name) to "stdout";
                       $2: <ParentMedia>,
                       $3: index into the container;
    * "SIZE":          writes the size of the child-media, the size of media-
                       info included, to "stdout";
                       $2: <ParentMedia>,
                       $3: index into the container;

    * "VERIFY":        * verifies if the media handler for the supplied media-
                         handler-uuid is valid,
                       * returns "0" (true), if the media handler for the
                         supplied media-handler-uuid is valid;
    * "WAIT":          wait-for-components-command;
                       $2: <ParentMedia>,
                       $3: index into the container,
                       $4: sub-command, in { "0", "1" }
                         * "0": ask, if the handler is able to wait for
                            component medias,
                           * no output,
                           * returns "1" (false), if it is able to wait;
                         * "1": wait for component medias,
                           * outputs an error message to "stderr", if the
                             component medias are not ready before 'timeout',
                           * returns "0" (true), if the component medias are
                             ready,
                           * returns "1" (false), on 'timeout'.