#!/usr/local/bin/scripts/sh
#
# pen: ^^^, 'ChildMediaName', 'disk_mediaAccess__isQualifiedName'

#^^^ in '24' etc. disk_mediaAccess___2ChildMediaFolderPath() {

# '2ChildDev' is only neccess. for filesytems.

# * move to 'concepts':
#   * "30nov2016 tbrue: finally:
#     * 'MediaDescriptor' --> 'MediaInfo'";
#     * keep "{" and "}" in "MediaInfo", files and folders.
#       * in script grant bash-compatibilty.
#
# * "^"
# * crypt: 'other encrypten-parameters'.
# * MediaAccess_ Realize  # whole chain / tree

#
#.Y / 70 83 / / / / 105 / / / /  / /               ;A4_QUER.Y
#.YT 3 2 0 0 3 3 1 / / /
#.H!a!0:linux/<scripts>/io/disk/mediaAccess/THIS!0.!c
#
#/***************************************************************************
#                         io disk mediaAccess THIS
#                         ++++++++++++++++++++++++
#
#     purpose             : "mediaAccess"-functions for mass-storage-medias
#
#     begin               : Sat Nov 19 20:18:34 CEST 2016
#
#     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.                                                    *
# *                                                                         *
# ***************************************************************************/

# MyHash("linux/<scripts>/io/disk/mediaAccess/THIS") = 0x0EAA
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.

# globals:
  BytesPerSector0x0EAA='512'
  CopyrightBase0x0EAA='Copyright (C) 2017 by Thomas Bruecker'
    Copyright0x0EAA="$CopyrightBase0x0EAA, <public@thomas-r-bruecker.ch>"
  DeviceMapperBasePath0x0EAA='/dev/mapper'
  DeviceQualifier0x0EAA='device:'
  DisksByUuidMountPath0x0EAA='/media/byUuid'
  LogPath0x0EAA="/var/log/mediaAccess"

  MetaDataPath0x0EAA="/dev/disk/.mediaAccess/metaData"
    # must be after "DisksByUuidMountPath0x0EAA" and before "CachesPath0x0EAA".

  CachesPath0x0EAA="${MetaDataPath0x0EAA}/caches"
    # must be after "DisksByUuidMountPath0x0EAA".

  ContainerOffsetsCachePath0x0EAA="${CachesPath0x0EAA}/containerOffsets"
    # must be after "CachesPath0x0EAA".

  FileSystemMediaInfo0x0EAA='MediaInfo.{A8A2BB26-78F0-11E6-B6F3-0000C00A45A9}.TXT'
  FilesystemQualifier0x0EAA='filesystem:'
  MediaHandlerUuidsCachePath0x0EAA="${CachesPath0x0EAA}/mediaHandlerUuids"
  MediaInfosCachePath0x0EAA="${CachesPath0x0EAA}/mediaInfos"
  MediaInfoSize0x0EAA='8'                          # in sectors.
  ParametersCachePath0x0EAA="${CachesPath0x0EAA}/parameters"
  ReverseMapPath0x0EAA="${MetaDataPath0x0EAA}/reverseMap"
  SCRIPTS='usr/local/bin'

  MediaInfoCommand0x0EAA="/${SCRIPTS}/io/disk/mediaAccess/MediaInfo"
    # must be after "SCRIPTS".

  ThisPath0x0EAA="/${SCRIPTS}/io/disk/mediaAccess/THIS"
  Title0x0EAA='io disk mediaAccess THIS -- "mediaAccess"-functions for mass-storage-medias'
  UdevRulesPath0x0EEA='/etc/udev/rules.d/100-MediaAccess.rules'
  UuidQualifier0x0EAA='uuid:'
  VerifiedMediaHandlerUuidsCachePath0x0EAA="${CachesPath0x0EAA}/verifiedMediaHandlerUuids"
  Version0x0EAA='Version 0.0.0'

  # Error Codes:
    EmptyMediaInfo0x0EAA='253'
    FileSystemErrorsLeftUncorrected0x0EAA='4'
    # 128: Invalid media;
    HasNoGetComponentMediaInfoOffsetPathPair0x0EAA='126'
    InvalidCommand0x0EAA='255'
    InvalidContainerIndex0x0EAA='127'
    MediaInfoNotComplete0x0EAA='252'
    MissingFolder0x0EAA='254'
    # others, in general method-specific.

  # DebugLog='log'

. "/${SCRIPTS}/io/con/THIS"
. "/${SCRIPTS}/io/f/THIS"
. "/${SCRIPTS}/io/disk/mediaAccess/LocalGlobals"
. "/$SCRIPTS/math/THIS"
. "/$SCRIPTS/memory/THIS"
. "/$SCRIPTS/string/THIS"


# handlers:
#{A8A2BB21-78F0-11E6-B6F3-0000C00A45A9}
#{A8A2BB22-78F0-11E6-B6F3-0000C00A45A9}
#{A8A2BB23-78F0-11E6-B6F3-0000C00A45A9}

. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/00000000_0000_0000_0000_000000000000"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB20_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB24_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB25_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB2D_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB2E,2F_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB30_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB31_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB32_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB33_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB34_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB36_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB38_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB39_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3A_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3B_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3C_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3D_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB40_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB41_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/mediaHandlers.d/A8A2BB42_78F0_11E6_B6F3_0000C00A45A9"
. "/${SCRIPTS}/io/disk/mediaAccess/Monitor"

# !!! --- EXPORT --- !!! {


con_() { : ; } #^ tty --> ...


debug_BT() {
  local  numFuntions

  echo  '{'

  numFuntions="${#FUNCNAME[*]}"
  for(( I = 0; I < numFuntions; I++))
     do
          echo  ${FUNCNAME[$I]}
       done

  echo  '}'
}


disk_SIZE() {
  # $1: path to the disk (device),
  # $2: units in { "S", ... },
  #     * "S": sectors;
  # * writes the size media to "stdout".

  # global:  BlockDev0x0EAA

  local      MEDIA UNITS

  MEDIA="$1"
  UNITS="$2"

  [ "S" != "$UNITS" ]  && return 1

  "$BlockDev0x0EAA"  --getsz  "$MEDIA"
}


disk_dm_2() {
  # global:  DmSetup0x0EAA

  local      FIELDS NAME

  FIELDS="$2"
  NAME="$1"

  "$DmSetup0x0EAA" info  "$NAME"  -c  --noheadings  -o "$FIELDS"
}


disk_dm_2BlkDevName() {
  local  NAME

  NAME="$1"

  disk_dm_2  "$NAME" 'BlkDevname'
}


disk_dm_2BlkDevPath() {
  local  BlkDevName NAME

  NAME="$1"
  BlkDevName="$(disk_dm_2BlkDevName  "$NAME")"
  echo                               "/dev/$BlkDevName"
}


disk_dm_2Major() {
  local  NAME

  NAME="$1"

  disk_dm_2  "$NAME" 'major'
}


disk_dm_2MajorMinor() {
  local  NAME

  NAME="$1"

  disk_dm_2  "$NAME" 'major,minor'
}


disk_dm_2Minor() {
  local  NAME

  NAME="$1"

  disk_dm_2  "$NAME" 'minor'
}


disk_dm_BlkDevName2Name() {
  local  BlkDevName

  BlkDevName="$1"

  disk_dm_2  "$BlkDevName" 'name'
}


disk_dm__isDevice() {
  # $1: <NAME>
  # returns true (0), if the device exists.

  # global:  DmSetup0x0EAA

  local      NAME

  NAME="$1"

  "$DmSetup0x0EAA" info  "$NAME"  >/dev/null  2>/dev/null
}


# disk_dm_2            "$1" minor
# disk_dm_2Major       "$1"
# disk_dm_2MajorMinor  "$1"
# disk_dm_2Minor       "$1"


disk_raid_Uuid2RaidUuid() {
  # $1: UUID.
  # * writes the uuid as a 'raid-uuid': "xxxxxxxx:xxxxxxxx:xxxxxxxx:xxxxxxxx"
  #   to "stdout".

  local  UUID

  UUID="$1"

  # | delete "-".
  #   | group as "xxxxxxxx:xxxxxxxx:xxxxxxxx:xxxxxxxx:".
  #     | delete trailing ":".
  string_2Lowercase                 "$(echo "$UUID")"     \
    | string_SearchAndReplace       '-'             ''    \
      | string__SearchAndReplace    '[0-9a-f]\{8\}' '&:'  \
        | string__SearchAndReplace  ':$'            ''
}


# } !!! --- EXPORT --- !!!


disk_mediaAccess_() {
  # prints information to stdout.

  # global:  Cat0x0EAA Less0x0EAA ThisPath0x0EAA

  local      Information

  # introduction:
    Information="\nTo learn more about \"$ThisPath0x0EAA\", read the"
    Information="${Information} following\ncontents of this file:\n\n"

  # + file contents:
    Information="${Information}Contents of \"$ThisPath0x0EAA\":\n\n"
    Information="${Information}$("$Cat0x0EAA"  "$ThisPath0x0EAA")"

  echo  -e  "$Information"  | "$Less0x0EAA"
}


disk_mediaAccess_dotVersion() {
  # prints version-information to stdout.

  # global:  Copyright0x0EAA Title0x0EAA Version0x0EAA

  echo  "$Title0x0EAA,"
  echo  "$Version0x0EAA"
  echo  "$Copyright0x0EAA"
}


disk_mediaAccess_col() {
  local  COMMAND

  . "/${SCRIPTS}/io/disk_/mediaAccess_/Constructors"
  COMMAND=disk_mediaAccess_col_$1;  shift 1
  $COMMAND "$@"
}


disk_mediaAccess_CheckThis() {
  # * checks the media, but does not repair it;
  # $1: <ParentMedia>,
  # $2: index into container,
  # $@: <check-options>.

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"
  shift  2

  disk_mediaAccess___MediaHandlerCommand  'CHECK' "$INDEX" "$ParentMedia"  "$@"
}


disk_mediaAccess_DestroyThis() {
  # $1: <ParentMedia>,
  # $2: index into container;
  # ^

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"

  disk_mediaAccess__MediaHandlerCommand  'DESTROY' "$ParentMedia" "$INDEX"
}


disk_mediaAccess_isHandled() {
  # $1: <forced>;
  # $2: <onlyOnHosts>;
  # $3: <RealizationOptions>;
  # * returns 0; if we handle the realize command according to the settings of
  #   the three parameters above.

  local FORCED Hostname OnlyOnHosts Options

  FORCED="$1"
  Hostname="$(hostname -f)"
  OnlyOnHosts="$2"
  RealizationOptions="$3"

  # handle if 'forced'.
    [ "1" = "$FORCED" ]                                          && return 0

  # do not handle if 'noauto'.
    string_MatchQ  "$RealizationOptions" 'noauto'                && return 1

  # handle if 'no host name is specified'.
    [ -z "$OnlyOnHosts" ]                                        && return 0

  # handle if 'a host name matches'.
    string_isMatchforWordInWordlist  "$OnlyOnHosts" "$Hostname"  && return 0

  # 'else': do not handle.
    return 1
}


disk_mediaAccess_RealizeThis() {
  # $1: <ParentMedia>,
  # $2: index into container;
  # ^

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  disk_mediaAccess__MediaHandlerCommand  'REALIZE' "$ParentMedia" "$INDEX"
}


disk_mediaAccess_RepairThis() {
  # * checks the media, and if necessary, repairs the media;
  # $1: <ParentMedia>,
  # $2: index into container,
  # $@: <check-options>.

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"
  shift  2

  disk_mediaAccess___MediaHandlerCommand  'REPAIR' "$INDEX" "$ParentMedia"  "$@"
}


disk_mediaAccess__0CacheFolders() {
  # creates the necessary folders for the caches of 'MediaAccess_'.

  # global:  CachesPath0x0EAA ContainerOffsetsCachePath0x0EAA
  #          MediaHandlerUuidsCachePath0x0EAA MediaInfosCachePath0x0EAA
  #          MkDir0x0EAA ParametersCachePath0x0EAA
  #          VerifiedMediaHandlerUuidsCachePath0x0EAA

  [ -d "$CachesPath0x0EAA" ]                                            \
    || "$MkDir0x0EAA"  -p  "$CachesPath0x0EAA"                          \
       || return                                   # return on error.
  [ -d "$ContainerOffsetsCachePath0x0EAA" ]                             \
    || "$MkDir0x0EAA"  -p  "$ContainerOffsetsCachePath0x0EAA"           \
       || return                                   # return on error.

  [ -d "$MediaHandlerUuidsCachePath0x0EAA" ]                            \
    || "$MkDir0x0EAA"  -p  "$MediaHandlerUuidsCachePath0x0EAA"          \
       || return                                   # return on error.

  [ -d "$MediaInfosCachePath0x0EAA" ]                                   \
    || "$MkDir0x0EAA"  -p  "$MediaInfosCachePath0x0EAA"                 \
       || return                                   # return on error.

  [ -d "$ParametersCachePath0x0EAA" ]                                   \
    || "$MkDir0x0EAA"  -p  "$ParametersCachePath0x0EAA"                 \
       || return                                   # return on error.

  [ -d "$VerifiedMediaHandlerUuidsCachePath0x0EAA" ]                    \
    || "$MkDir0x0EAA"  -p  "$VerifiedMediaHandlerUuidsCachePath0x0EAA"
}


disk_mediaAccess__0Folders() {
  # creates the necessary folders for 'MediaAccess_'.

  # global:  LogPath0x0EAA MkDir0x0EAA ReverseMapPath0x0EAA

  disk_mediaAccess__0CacheFolders            || return
                                                   # return on error.
  [ -d "$LogPath0x0EAA" ]                               \
    || "$MkDir0x0EAA"  -p  "$LogPath0x0EAA"  || return
                                                   # return on error.
  [ -d "$ReverseMapPath0x0EAA" ]                        \
    || "$MkDir0x0EAA"  -p  "$ReverseMapPath0x0EAA"
}


disk_mediaAccess__0MediaAccess() {
  # initializes 'MediaAccess'.

  disk_mediaAccess__0Folders
  disk_mediaAccess__0UdevRules
}


disk_mediaAccess__0MediaInfo() {
  # * initializes the 4096 bytes media info at the begin of the media, with
  #   zeros;
  # * clears the corresponding cache-entry;
  # $1: <ParentMedia>,
  # $2: index into container.

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"


  disk_mediaAccess__WriteMediaInfo  '/dev/zero' "$ParentMedia" "$INDEX"
}


disk_mediaAccess__0UdevRules() {
  # create the udev-rules-file.

  # global:  Cat0x0EAA UdevRulesPath0x0EEA

  [ -f "$UdevRulesPath0x0EEA" ]  && return  0

  "$Cat0x0EAA"  >"$UdevRulesPath0x0EEA" <<UdevRulesText0x0EEA
#/***************************************************************************
#                         udev-rules for "MediaAccess"
#                         ++++++++++++++++++++++++++++
#
#     purpose             : start "mediaAccess" automatically
#
#     begin               : Fri May 11 23:50:28 CEST 2018
#
#     changes             :
#
#     copyright           : (C) 2018 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.                                                    *
# *                                                                         *
# ***************************************************************************/

# test:
#   ACTION=="add", ENV{ID_FS_UUID}=="83710736-0ddf-4bd3-9b75-ff52e2a0059e",  RUN+="/bin/bash -c '/bin/echo $env{ID_FS_UUID} > /dev/tty9'"
#   ACTION=="add", ENV{ID_VENDOR}=XXX, RUN+="/bin/bash -c '/bin/echo $env{ID_VENDOR} > /dev/tty9'"
#   SUBSYSTEM=="scsi_disk", ACTION=="add", RUN+="/bin/bash -c '/bin/echo $env{ID_FS_UUID} > /udevXXX.log'"

#   does not produce output: SUBSYSTEM=="scsi_disk", ACTION=="add", RUN+="/bin/echo xxx1 > /dev/tty2"

SUBSYSTEM=="block", ACTION=="add", PROGRAM="/usr/local/bin/MediaAccess_ _UdevHook  %P %k %n"
UdevRulesText0x0EEA
}


disk_mediaAccess__2ChildDev() {
  # converts the  "qualified parent-media" at the "index into the container" to
  # the qualified block-device-path of its child-media and writes the path to
  # "stdout";
  # $1: <ParentMedia>,
  # $2: index into container.

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  disk_mediaAccess___MediaHandlerCommand  "2ChildDev" "$INDEX" "$ParentMedia"
}


disk_mediaAccess__2ChildMedia() {
  # converts the "qualified parent-media" at the "index into the container" to
  # its child-media and writes the qualified child-media-name to "stdout";
  # $1: <ParentMedia>,
  # $2: index into container.

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"

  disk_mediaAccess___MediaHandlerCommand  "2ChildMedia" "$INDEX" "$ParentMedia"
}


disk_mediaAccess__CheckIndex() {
  # returns "0" (true) if the index is valid;
  # $1: index into container.

  local  INDEX

  INDEX="$1"

  string__MatchQ  "$INDEX" '^[0-9]*$'
}


disk_mediaAccess__DeleteCaches() {
  # deletes the caches of 'MediaAccess_'.

  # global:  ContainerOffsetsCachePath0x0EAA MediaHandlerUuidsCachePath0x0EAA
  #          MediaInfosCachePath0x0EAA ParametersCachePath Rm0x0EAA
  #          VerifiedMediaHandlerUuidsCachePath0x0EAA


  "$Rm0x0EAA"  -f  ${ContainerOffsetsCachePath0x0EAA}/*             2>/dev/null
  "$Rm0x0EAA"  -f  ${MediaHandlerUuidsCachePath0x0EAA}/*            2>/dev/null
  "$Rm0x0EAA"  -f  ${MediaInfosCachePath0x0EAA}/*                   2>/dev/null
  "$Rm0x0EAA"  -f  $ParametersCachePath0x0EAA/*                     2>/dev/null
  "$Rm0x0EAA"  -f  ${VerifiedMediaHandlerUuidsCachePath0x0EAA}/*    2>/dev/null

  return  0                                        # no error!
}


disk_mediaAccess__DeleteDmRealizationOptions() {
  # deletes the options from the <RealizationOptions> and writes the changed
  # <RealizationOptions> to "stdout",
  # $1: <RealizationOptions>,

  local  RealizationOptions

  RealizationOptions="$1"

  echo "$RealizationOptions"                                  \
    | disk_mediaAccess__DeleteRealizationOption  'noauto'     \
    | disk_mediaAccess__DeleteRealizationOption  'readahead'  \
    | disk_mediaAccess__DeleteRealizationOption  'ro'         \
    | string__SearchAndReplace  ' *'              ''
}


disk_mediaAccess__DeleteRealizationOption() {
  # reads the realization-options from "stdin", deletes the option from it and
  # writes the changed result to "stdout",
  # $1: option-name.

  # global:  Cat0x0EAA

  local  OPTION OptionName RealizationOptions ToDelete

  OptionName="$1"
  RealizationOptions="$("$Cat0x0EAA"  '/dev/stdin')"

  # echo  "$OptionName"                                           >>/dev/stderr

  while   disk_mediaAccess__isRealizationOption         \
      "$RealizationOptions" "$OptionName"
    do
        # echo  "isOption: $OptionName"                           >>/dev/stderr

        OPTION="$(
          disk_mediaAccess__GetRealizationOption        \
            "$RealizationOptions" "$OptionName"
        )"
        if [ -z "$OPTION" ]; then
            # no option-value.
              ToDelete="$OptionName"
          else
            ToDelete="${OptionName}=$OPTION"
          fi

        # echo "$OPTION"                                          >>/dev/stderr
        # echo "$ToDelete"                                        >>/dev/stderr

        RealizationOptions="$(
          echo "$RealizationOptions"                    \
            | string_SearchAndReplace   "$ToDelete" ''  \
            | string__SearchAndReplace  ' *'        ''
        )"
      done
  echo "$RealizationOptions"
}


disk_mediaAccess__Dev2Uuid() {
  # converts the qualified block-device-name to the qualified media-name and
  # writes the name to "stdout";
  # $1: qualified block-device-name .

  local  DevicePath INDEX IndexMediaPair QualifiedMedia UUID

  QualifiedMedia="$1"

  DevicePath="$(disk_mediaAccess__DeviceName2Path  "$QualifiedMedia")"

  if  disk_dm__isDevice                     "$DevicePath"; then
      UUID="$(disk_dm_BlkDevName2Name       "$DevicePath")"
      disk_mediaAccess__WriteQualifiedUuid  "$UUID"
    else
      INDEX="$(
        disk_mediaAccess___2ParentIndex     "$QualifiedMedia"
      )"  || return                                # return on error.
      QualifiedMedia="$(
        disk_mediaAccess___2ParentMedia     "$QualifiedMedia"
      )"  || return                                # return on error.
      disk_mediaAccess__2ChildMedia         "$QualifiedMedia" "$INDEX"
    fi
}


disk_mediaAccess__DeviceName2Path() {
  # converts the qualified media-name of a device to the path to the device and
  # writes it to "stdout";
  # $1: qualified media-name .

  # global:  DeviceQualifier0x0EAA

  local      QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__StripQualifier                  \
    "$QualifiedMedia" "$DeviceQualifier0x0EAA"
}


disk_mediaAccess__deviceName2Path() {
  # * converts the qualified media-name of a device to the path to the device and
  #   writes it to "stdout";
  # * you may not use an alias here because the called function-name is built
  #   at runtime;
  # $1: qualified media-name .

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__DeviceName2Path  "$QualifiedMedia"
}


disk_mediaAccess__DmCreate() {
  # $1: name;
  # $2: realization options;
  # * creates device-mapper-device with <name> and table provided on "stdin".

  # global:  DmSetup0x0EAA

  local      NAME ReadAhead ReadOnly RealizationOptions

  NAME="$1"
  RealizationOptions="$2"

  if  string_MatchQ  "$RealizationOptions" 'readahead'; then
      #   | clean till "readahead".
      #     | clean after "readahead<...>".
      #       | remove "=".
      ReadAhead="$(
        echo  "$RealizationOptions"                                     \
          | string__SearchAndReplace     '^.*readahead' 'readahead'     \
            | string__SearchAndReplace   ' .*'          ''              \
              | string_SearchAndReplace  '='            ' '
      )"

      ReadAhead="--$(echo  "$ReadAhead")"
    else
      ReadAhead="--readahead none"
    fi

  # echo  $RealizationOptions                                     >>/dev/stderr

  RealizationOptions="$(
    echo  "$RealizationOptions"                                         \
      | disk_mediaAccess__DeleteRealizationOption  'parent'
  )"
  # echo  $RealizationOptions                                     >>/dev/stderr

  if string_isMatchforWordInWordlist  "$RealizationOptions" 'ro'; then
      ReadOnly='-r'
    fi

  # echo  $ReadAhead                                              >>/dev/stderr
  # echo  ReadOnly = $ReadOnly                                    >>/dev/stderr

  "$DmSetup0x0EAA" create  -u "_$NAME"  "$NAME" $ReadAhead $ReadOnly
    # "$ReadAhead" and "$ReadOnly" surrounded with "" does not work.
}


disk_mediaAccess__FilesystemName2Path() {
  # converts the qualified media-name of a filesystem to the path to the file-
  # system and writes it to "stdout";
  # $1: qualified media-name .

  # global:  FilesystemQualifier0x0EAA

  local      QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__StripQualifier                      \
    "$QualifiedMedia" "$FilesystemQualifier0x0EAA"
}


disk_mediaAccess__filesystemName2Path() {
  # * converts the qualified media-name of a filesystem to the path to the
  #   filesystem and writes it to "stdout";
  # * you may not use an alias here because the called function-name is built
  #   at runtime;
  # $1: qualified media-name .

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__FilesystemName2Path  "$QualifiedMedia"
}


disk_mediaAccess__GetMediaHandlerUuid() {
  # * gets the media handler uuid and writes it to "stdout",
  # * returns "0" (true) if the media handler uuid is availabl;
  # $1: <ParentMedia>,
  # $2: index into container.

  local  INDEX ParentMedia ParentMediaPath

  INDEX="$2"
  ParentMedia="$1"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___GetMediaHandlerUuid                                      \
    "$INDEX" "$ParentMedia" "$ParentMediaPath" ''
}


disk_mediaAccess__GetMediaInfo() {
  # * gets the raw 4096 bytes media info at the begin of the media, and writes
  #   it to "stdout";
  # * returns "0" (true) if the media info is available;
  # $1: <ParentMedia>,
  # $2: index into container;
  #     (here we 'keep' <ParentMedia>, <INDEX> .)

  # global:  Cat0x0EAA MkTemp0x0EAA Rm0x0EAA

  local      INDEX OutputFile ParentMedia RESULT

  INDEX="$2"
  ParentMedia="$1"

  OutputFile="$("$MkTemp0x0EAA"  '/tmp/Output.XXXXXXXX')"

  disk_mediaAccess___GetMediaInfo  "$INDEX" "$ParentMedia"  >"$OutputFile"
  RESULT="$?"

  echo  ''                                                        >>/dev/stderr
  "$Cat0x0EAA"     "$OutputFile"
  "$Rm0x0EAA"  -f  "$OutputFile"
  return           "$RESULT"
}


disk_mediaAccess__GetRealizationOption() {
  # * writes the option to "stdout",
  # * returns true (0), if the option exists;
  # $1: <RealizationOptions>,
  # $2: option-name.

  local OptionName RealizationOptions RESULT

  OptionName="$2"
  RealizationOptions="$1"

  if  disk_mediaAccess__isRealizationOption                                \
        "$RealizationOptions" "$OptionName";  then

      RESULT='0'

      # | clean till "<OptionName>";
      #   | clean after "<OptionNane><...>";
      #     | remove "=";
      #       | remove <OptionName>.
      echo  "$RealizationOptions"                                          \
        | string__SearchAndReplace       "^.*${OptionName}" "$OptionName"  \
          | string__SearchAndReplace     ' .*'              ''             \
            | string_SearchAndReplace    '='                ''             \
              | string_SearchAndReplace  "$OptionName"      ''
    else
      RESULT='1'
    fi

  return "$RESULT"
}


disk_mediaAccess__InvalidCommandError() {
  # prints the error message to "stdout";
  # $1: command,
  # $2: index into container,
  # $3: <MediaHandlerUuid>,
  # $4: <ParentMedia>.

  # global:  InvalidCommand0x0EAA

  local      COMMAND INDEX MediaHandlerUuid ParentMedia

  COMMAND="$1"
  INDEX="$2"
  MediaHandlerUuid="$3"
  ParentMedia="$4"

  disk_mediaAccess___GeneralError "Invalid Command \"$COMMAND\""  \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia"

  return  "$InvalidCommand0x0EAA"
}


disk_mediaAccess__InvalidIndexError() {
  # prints the error message to "stdout";
  # $1: index into container,
  # $2: <ParentMedia>.

  # global:  InvalidContainerIndex0x0EAA

  local      INDEX ParentMedia

  INDEX="$1"
  ParentMedia="$2"

  echo  -en  "\nError: Invalid Index \"$INDEX\" for Media "       >>/dev/stderr
  echo  -e   "\"$ParentMedia\".\n"                                >>/dev/stderr

  return "$InvalidContainerIndex0x0EAA"
}


disk_mediaAccess__InvalidMediaInfoError() {
  # prints the error message to "stdout";
  # $1: index into container,
  # $2: <ParentMedia>.
  # $3: <RESULT>

  local  INDEX ParentMedia RESULT

  INDEX="$1"
  ParentMedia="$2"
  RESULT="$3"

  echo  -en  "\nError: \"$ParentMedia\" "                        >>/dev/stderr
  echo  -e   "has Invalid Media Info at Index \"$INDEX\".\n"      >>/dev/stderr

  return  "$RESULT"
}


disk_mediaAccess__isContainer() {
  # ^* returns "0" (true) if the media handler uuid may be handled.
  # $1: index into container,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  local  INDEX ParentMedia ParentMediaPath

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___isGeneralContainer                    \
    "$INDEX" "$ParentMedia" "$ParentMediaPath"  && return

  disk_mediaAccess___isStackedContainer                    \
    "$INDEX" "$ParentMedia" "$ParentMediaPath"
                                                   # return result of last
}                                                  # command.


disk_mediaAccess__isEndOfChain() {
  # * ^returns "0" (true) if the provided media is the last media in its chain.
  #    * 128 on invalid media info;
  # $1: index into container,
  # $2: <ParentMedia>.

  # global:  FileSystemMediaInfo0x0EAA

  local      INDEX ParentMedia

  INDEX="$1"
  ParentMedia="$2"

  disk_mediaAccess__VerifyMediaHandlerUuid  "$ParentMedia" "$INDEX"  \
                                          2>/dev/null  || return 0
    # invalid media: end of chain; 'silent' error.

  string__MatchQ  "$ParentMedia" '^/dev/.*$'           && return 1
    # media is a device; may contain other medias: not end of chain.

  string__MatchQ  "$ParentMedia" '^/media/byUuid/.*$'  && return 1
    # media is ^in /media/... a device; may contain other medias: not end of chain.

  string__MatchQ  "$ParentMedia" '^/mnt/.*$'           || return 128
    # neither 'dev' nor 'mnt': ivalid media.
#^^^
  [ -f "$ParentMedia/$FileSystemMediaInfo0x0EAA" ]     || return 0
    # no media info in folder: end of chain.

  # we get here because there is a 'FileSystemMediaInfo'-File in the folder:
  # not end of chain.
  echo  "$ParentMedia/$FileSystemMediaInfo0x0EAA"
                                                             return 1
}


disk_mediaAccess__isMedia() {
  # returns "0" (true) if the media exists;
  # $1: qualified media-name.

  local  Path QualifiedMedia

  QualifiedMedia="$1"

  # echo  $QualifiedMedia                                         >>/dev/stderr

  Path="$(disk_mediaAccess__QualifiedName2Path  "$QualifiedMedia")"
  [ -e "$Path" ]                                   # return result of last
}                                                  # command.


disk_mediaAccess__isMediaHandlerUuid() {
  # returns "0" (true) if the uuid to be tested is equal to the media-handler-
  # uuid of the 'parent-media';
  # $1: index into container,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>,
  # $4: uuid to be tested.

  local  INDEX ParentMedia ParentMediaPath TestUuid

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"
  TestUuid="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $TestUuid                                               >>/dev/stderr

  MediaHandlerUuid="$(
    disk_mediaAccess___GetMediaHandlerUuid                             \
      "$INDEX" "$ParentMedia" "$ParentMediaPath" ''
  )"  || return                                    # return on error.
  # echo  $MediaHandlerUuid                                       >>/dev/stderr

  disk_mediaAccess___VerifyMediaHandlerUuid                            \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia" "$ParentMediaPath" ''  \
     || return                                     # return on error.

  [ "$TestUuid" == "$MediaHandlerUuid" ]           # return result of last
}                                                  # command.


disk_mediaAccess__isQualifiedDevice() {
  # ^converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: qualified media-name .

  # global:  DeviceQualifier0x0EAA

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__isQualifiedName             \
    "$QualifiedMedia" "$DeviceQualifier0x0EAA"
}


disk_mediaAccess__isQualifiedFilesystem() {
  # ^converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: qualified media-name .

  # global:  FilesystemQualifier0x0EAA

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__isQualifiedName                 \
    "$QualifiedMedia" "$FilesystemQualifier0x0EAA"
}


disk_mediaAccess__isQualifiedName() {
  # ^converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: qualified media-name .
  # $2: <QUALIFIER>.

  local  QualifiedMedia QUALIFIER

  QUALIFIER="$2"
  QualifiedMedia="$1"

  string__MatchQ  "$QualifiedMedia" "^$QUALIFIER"
}


disk_mediaAccess__isQualifiedUuid() {
  # ^converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: qualified media-name .

  # global:  UuidQualifier0x0EAA

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess__isQualifiedName           \
    "$QualifiedMedia" "$UuidQualifier0x0EAA"
}


disk_mediaAccess__isRealizationOption() {
  # returns true (0), if the option exists;
  # $1: <RealizationOptions>,
  # $2: option-name.

  local OptionName RealizationOptions

  OptionName="$2"
  RealizationOptions="$1"

  string__MatchQ  "$RealizationOptions" "^$OptionName "    ||
                                                   # at begin of line.

  string_MatchQ   "$RealizationOptions" " $OptionName "    ||
                                                   # between other options.

  string__MatchQ  "$RealizationOptions" " ${OptionName}$"  ||
                                                   # at end of line.

  string__MatchQ  "$RealizationOptions" "^${OptionName}$"  ||
                                                   # entire line.

  string_MatchQ   "$RealizationOptions" "$OptionName="
                                                   # option with value.
                                                   # return result of last
}                                                  # command.


disk_mediaAccess__LinkAndMap() {
  # creates
  # * the link from "/media/byUuid/<ChildMediaName>" to the device-mapper-
  #   target '<ChildMediaName>' and writes the child-media
  #   ("uuid:<ChildMediaName>") to "stdout",
  # * the entry "/media/byUuid/.reverseMap/<AbsoluteChildMediaPath>" with the
  #   reverse-mapping information;
  # $1: <ChildMediaName>,
  # $2: index into container,
  # $3: <ParentMediaPath>.

  local  ChildMediaName INDEX ParentMediaPath TargetPath

  ChildMediaName="$1"
  INDEX="$2"
  ParentMediaPath="$3"

  TargetPath="$(disk_mediaAccess___Uuid2AbsolutePath1  "$ChildMediaName")"  \
    || return                                      # return on error.

  # echo  $ChildMedia                                             >>/dev/stderr
  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $TargetPath                                             >>/dev/stderr

  disk_mediaAccess___LinkAndMap                                             \
    "$ChildMediaName" "$INDEX" "$ParentMediaPath" "$TargetPath"
}


disk_mediaAccess__MakeURL() {
  # $1: media handler uuid;
  # * writes the url to "stdout".

  # global:  MediaAccessHomeURL0x0EAA
  local  MediaHandlerUuid

  MediaHandlerUuid="$1"
  echo  -e  "${MediaAccessHomeURL0x0EAA}/${MediaHandlerUuid}"
}


disk_mediaAccess__Media2ReverseMapDevice() {
  # ^converts the media-name (UUID) to the qualified media of the device and
  # writes it to "stdout";
  # $1: qualified media-name .

  local  QualifiedMedia

  QualifiedMedia="$1"
  # echo  $QualifiedMedia                                         >>/dev/stderr


  if  disk_mediaAccess__isQualifiedUuid  "$QualifiedMedia"; then
      disk_mediaAccess__Uuid2Dev         "$QualifiedMedia"
    else
      echo                               "$QualifiedMedia"
    fi
}


disk_mediaAccess__MediaHandlerCommand() {
  # $1:      command,
  # $2:      <ParentMedia>,
  # $3:      index into container,
  # $4 ... : arguments for command.

  # global:  Cat0x0EAA MkTemp0x0EAA Rm0x0EAA

  local      COMMAND INDEX MediaInfo OutputFile ParentMedia RESULT

  COMMAND="$1"
  INDEX="$3"
  ParentMedia="$2"
  shift  3

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  OutputFile="$("$MkTemp0x0EAA"  '/tmp/Output.XXXXXXXX')"

  disk_mediaAccess___MediaHandlerCommand                     \
    "$COMMAND" "$INDEX" "$ParentMedia" "$@"  >"$OutputFile"
  RESULT="$?"

  echo  ''                                                        >>/dev/stderr
  "$Cat0x0EAA"     "$OutputFile"
  "$Rm0x0EAA"  -f  "$OutputFile"
  return           "$RESULT"
}


disk_mediaAccess__Parameters2File() {
  # * writes the parameters to a file and prints its name to "stdout".
  # * !!! the file must not be deleted after use !!!
  # $1: <MediaInfo>.

  # global:  ColRm0x0EAA MediaInfoCommand0x0EAA ParametersCachePath0x0EAA
  #          Sha512Sum0x0EAA

  local      INDEX MediaInfo MediaInfoHash ParametersFile

  MediaInfo="$1"
  MediaInfoHash="$(echo  "$MediaInfo"  | "$Sha512Sum0x0EAA"              \
                     | "$ColRm0x0EAA"  128)"
  # echo  "$MediaInfoHash"                              >>__Parameters2File.LOG

  ParametersFile="${ParametersCachePath0x0EAA}/$MediaInfoHash"

  if [ ! -f "$ParametersFile"  ]; then             # not cached.
      # echo  "$MediaInfoHash"                     >>__Parameters2FileTaken.LOG

      echo  -n  "$MediaInfo"  | "$MediaInfoCommand0x0EAA"  'PARAMETERS'  \
        >"$ParametersFile"                                               \
        || return                                  # return on error.
    fi

  echo  "$ParametersFile"
}


disk_mediaAccess__QualifiedName2Path() {
  # converts the qualified media-name to the path to the media and writes it to
  # "stdout";
  # $1: qualified media-name .

  local  MEDIA QUALIFIER

  MEDIA="$1"

  # echo  $QualifiedMedia                                         >>/dev/stderr

  QUALIFIER="$(
    disk_mediaAccess___QualifiedName2Qualifier  "$MEDIA"
  )"
  # echo  $QUALIFIER                                              >>/dev/stderr

  [ -z "$QUALIFIER" ]  && {                        # if not qualified, do not
                                                   # convert.
    echo  ""                                                      >>/dev/stderr
    echo  -e  "Error: Invalid Media \"$MEDIA\"; missing qualifier."  \
                                                                  >>/dev/stderr
    return
  }

  disk_mediaAccess__${QUALIFIER}Name2Path       "$MEDIA"
}


disk_mediaAccess__RealizeForced2Forced() {
  # sets "<FORCED>" on 'RealizeForced';
  # $1: <COMMAND>;
  # 'nameref', "local  -n" is not possible in "bash-4.1.2-48" (CentOS-6.x).

  local  COMMAND

  COMMAND="$1"

  if [ "RealizeForced" == "$COMMAND" ]; then
      # realize forced.
        FORCED='1'
    else
      FORCED='0'
    fi
}


disk_mediaAccess__Size0() {
  #  write size of media; size of media info included, to "stdout";
  # $1: <AdditionalSize>,
  # $1: <MediaInfo>.

  # global:  MediaInfoSize0x0EAA

  local      AdditionalSize INDEX MediaInfo TotalSize

  # parameters:
    local    SIZE

  AdditionalSize="$1"
  MediaInfo="$2"

  # echo  $AdditionalSize                                         >>/dev/stderr
  # echo  $MediaInfo                                              >>/dev/stderr

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"  \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo $SIZE                                                    >>/dev/stderr

  let "TotalSize = SIZE + AdditionalSize + MediaInfoSize0x0EAA"
  echo  "$TotalSize"
}


disk_mediaAccess__Size1() {
  # * size of a media, that consists only of the media info.
  # * write size of media; size of media info included, to "stdout".

  echo  "$MediaInfoSize0x0EAA"
}


disk_mediaAccess__StripQualifier() {
  # $1: qualified media-name,
  # $2: <QUALIFIER>.

  local  QualifiedMedia QUALIFIER

  QUALIFIER="$2"
  QualifiedMedia="$1"

  # echo  $QUALIFIER                                              >>/dev/stderr
  # echo  $QualifiedMedia                                         >>/dev/stderr

  echo  "$QualifiedMedia"  | string__SearchAndReplace  "^$QUALIFIER" ''
}


disk_mediaAccess__StripUuidQualifier() {
  # strips the uuid-qualifier from the qualified media-name and writes it to
  # "stdout";
  # $1: qualified media-name.

  # global:  UuidQualifier0x0EAA

  local      QualifiedMedia

  QualifiedMedia="$1"

  # echo  $QualifiedMedia                                         >>/dev/stderr

  disk_mediaAccess__StripQualifier  "$QualifiedMedia" "$UuidQualifier0x0EAA"
}


disk_mediaAccess__UdevHook() {
  # * does initializations for 'udev'.
  # $1: 'disk'-name of partition,
  # $2: partition-name,
  # $3: partition #.

  local  DISK PARTITION  PartNo

  DISK="$1"
  PARTITION="$2"
  PartNo="$3"

  # echo  -e  "\"disk_mediaAccess__UdevHook()\""                    >/dev/tty11
  # echo  $DISK                                                     >/dev/tty11
  # echo  $PARTITION                                                >/dev/tty11
  # echo  $PartNo                                                   >/dev/tty11

  disk_mediaAccess___UdevHook  "$DISK" "$PARTITION" "$PartNo"  \
                                                     >/dev/null  2>/dev/null  &
  return 0
}


disk_mediaAccess__Uuid2Dev() {
  # converts ( by using "disk_mediaAccess__2ChildDev()" ) the "qualified media"
  # at the "index into the container" to its qualified block-device-path and
  # writes the path to "stdout";
  # $1: qualified media-name.

  local  INDEX QualifiedMedia

  QualifiedMedia="$1"

  # echo  wah0                                         >>/dev/stderr

  INDEX="$(
    disk_mediaAccess___2ParentIndex  "$QualifiedMedia"
  )"  || return                                # return on error.
  QualifiedMedia="$(
    disk_mediaAccess___2ParentMedia  "$QualifiedMedia"
  )"  || return                                # return on error.

  disk_mediaAccess__2ChildDev       "$QualifiedMedia" "$INDEX"
  # echo  wah1                                         >>/dev/stderr

}


disk_mediaAccess__uuidName2Path() {
  # * converts the qualified media-name of a media specified by an uuid to the
  #   path to the media and writes it to "stdout";
  # * you may not use an alias here because the called function-name is built
  #   at runtime;
  # $1: qualified media-name .

  local  QualifiedMedia

  QualifiedMedia="$1"

  disk_mediaAccess___QualifiedUuid2ByUuidPath  "$QualifiedMedia"
}


disk_mediaAccess__VerifyMayWait() {
  # * returns
  #   * true (0),  if "VERIFY" == "<COMMAND>",
  #   * false (1), if "WAIT" == "<COMMAND>" and "0" == "$SubCommand",
  #   * true (0),  if "WAIT" == "<COMMAND>" and "1" == "$SubCommand";
  # * prints to "stdout":
  #   * "0" (the return-value may be directly returned by the caller), if
  #     * "VERIFY" == "<COMMAND>",
  #     * "WAIT" == "<COMMAND>" and "0" == "$SubCommand",
  #   * "1", if "WAIT" == "<COMMAND>" and "1" == "$SubCommand";
  #   * "255"  else^
  # $1: <COMMAND>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>,
  # $6: <SubCommand>.

  # global:  InvalidCommand0x0EAA

  local      COMMAND INDEX MediaHandlerUuid MediaInfo ParentMedia
  local      ParentMediaPath SubCommand

  COMMAND="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"
  SubCommand="$6"

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $SubCommand                                             >>/dev/stderr

  [ "VERIFY" == "$COMMAND" ]         && { echo '0';  return 0; }
                                                   # verify is ok.
  if [ "WAIT" == "$COMMAND" ]; then
      [ "0" == "$SubCommand" ]  && { echo '0';  return 1; }
                                                   # may wait for component
                                                   # medias.
      [ "1" == "$SubCommand" ]  && { echo '1';  return 0; }

    # else, invalid <SubCommand>:
      MediaHandlerUuid="$(
        disk_mediaAccess____GetMediaHandlerUuid                         \
          "$INDEX" "$MediaInfo" "$ParentMediaPath" ''
      )"

      disk_mediaAccess___GeneralError                                   \
        "Invalid Sub Command \"$SubCommand\" for Command \"$COMMAND\""  \
        "$INDEX" "$MediaHandlerUuid" "$ParentMedia"

      echo '0';  return  "$InvalidCommand0x0EAA"
    fi
    # else
      echo '1';  return 0
}


disk_mediaAccess__VerifyNoWait() {
  # $1: <COMMAND>,
  # * returns
  #   * true (0),  if "VERIFY" == "<COMMAND>" or "W" == "<COMMAND>",
  #   * false, else.

  local  COMMAND

  COMMAND="$1"

  if [ "VERIFY" = "$COMMAND" -o "WAIT" = "$COMMAND" ]; then
      return  0                                    # ok., and no waiting for
    fi                                             # component medias at all.
    # else
  return  1
}


disk_mediaAccess__VerifyMediaHandlerUuid() {
  # returns "0" (true) if the media handler uuid may be handled;
  # $1: <ParentMedia>,
  # $2: index into container.

  local  INDEX MediaHandlerUuid ParentMedia ParentMediaPath

  INDEX="$2"
  ParentMedia="$1"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  MediaHandlerUuid="$(
    disk_mediaAccess___GetMediaHandlerUuid                                    \
      "$INDEX" "$ParentMedia" "$ParentMediaPath" ''
  )"  || return                                   # return on error.

  disk_mediaAccess___VerifyMediaHandlerUuid                                   \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia" "$ParentMediaPath" ''
}


disk_mediaAccess__WaitError() {
  # prints the error message to "stdout";
  # $1: <ParentMedia>.

  # from caller:  ComponentMedias MissingMedias

  local           ComponentMedia I numComponents PrevMissingMedia ParentMedia

  ParentMedia="$1"

  numComponents="${#ComponentMedias[@]}"

  # echo  ${MissingMedias[@]}                                     >>/dev/stderr
  # echo  ${ComponentMedias[@]}                                   >>/dev/stderr
  # echo  $numComponents                                          >>/dev/stderr

  echo  -en  "Error: After waiting for the component medias for " >>/dev/stderr
  echo  -e   "\"$ParentMedia\""                                   >>/dev/stderr
  echo      "       -- The following component medias are not ready:"  \
                                                                  >>/dev/stderr

  PrevMissingMedia=''
  for ((I = 0; I < numComponents; I++))
    do
        if [ "1" == "${MissingMedias[$I]}" ]; then
            # do only for components that are not ready:
              ComponentMedia="${ComponentMedias[$I]}"
              # echo  $ComponentMedia                             >>/dev/stderr
              if [ "THIS" == "$ComponentMedia" ]; then
                  ComponentMedia="$ParentMedia"
                fi

              [ -n "$PrevMissingMedia" ]                               \
                && echo  -e "       * \"$PrevMissingMedia\","     >>/dev/stderr

              PrevMissingMedia="$ComponentMedia"
          fi
      done

  # "disk_mediaAccess__WaitError()" is only called if at least one media is
  # missing; so you have to show at least one media at all:
    echo  -e                "       * \"$ComponentMedia\"."       >>/dev/stderr
}


disk_mediaAccess__WaitForComponentMedias() {
  # wait for component medias;
  # $1: <INDEX>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>,
  # $4: <TIMEOUT>.

  # from caller:  ComponentMedias

  # global:       Sleep0x0EAA

  local           ComponentMediaPath haveMissingMedias INDEX I
  local  -a       MissingMedias
  local           numComponents ParentMedia ParentMediaPath TIMEOUT

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"
  TIMEOUT="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $TIMEOUT                                                >>/dev/stderr

  numComponents="${#ComponentMedias[@]}"
  # echo  ${ComponentMedias[@]}                                   >>/dev/stderr
  # echo  $numComponents                                          >>/dev/stderr

  for ((I = 0; I < numComponents; I++))
    do  MissingMedias[$I]=1;  done                 # 'not ready'.
  # echo  MissingMedias ${MissingMedias[@]}                       >>/dev/stderr

  until [ "0" == "$TIMEOUT" ]
    do
        haveMissingMedias=0
        for ((I = 0; I < numComponents; I++))
          do
              if [ "1" == "${MissingMedias[$I]}" ]; then
                  # do only for components that are not ready:
                    ComponentMediaPath="${ComponentMedias[$I]}"
                    if [ "THIS" == "$ComponentMediaPath" ]; then
                        ComponentMediaPath="$ParentMediaPath"
                      else
                        ComponentMediaPath="$(
                          disk_mediaAccess___Media2AbsolutePath      \
                            "${ComponentMedias[$I]}"
                        )"                          # ignore errors here!
                      fi
                    # echo  $ComponentMediaPath                   >>/dev/stderr

                    if f_isBlockDevice  "$ComponentMediaPath"; then
                        MissingMedias[$I]=0
                      else
                        let "haveMissingMedias++"
                      fi
                fi
          done  # for

        [ "0" == "$haveMissingMedias" ]  && return  0
        "$Sleep0x0EAA"  1;  let "TIMEOUT--";  # echo $TIMEOUT     >>/dev/stderr
      done  # until
   # echo  MissingMedias ${MissingMedias[@]}                      >>/dev/stderr

  disk_mediaAccess__WaitError  "$ParentMedia"
  return  1
}


disk_mediaAccess__WriteIndexMediaPair() {
  # writes a media-index-pair to "stdout";
  # $1: index into container,
  # $2: qualified media.

  local  INDEX QualifiedMedia

  INDEX="$1"
  QualifiedMedia="$2"

  echo  "'$INDEX' '$QualifiedMedia'"
}


disk_mediaAccess__WriteMediaInfo() {
  # * writes the <InputFile> to the 4096 bytes media info at the begin of the
  #   media,
  # * clears the corresponding cache-entry;
  # $1: <InputFile>,
  # $2: <ParentMedia>,
  # $3: index into container.

  local  Answer INDEX InputFile ParentMedia ParentMediaPath

  INDEX="$3"
  InputFile="$1"
  ParentMedia="$2"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $InputFile                                              >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  echo  -en   "\n\nWrite \"Yes! Yes!\" if you really want to "    >>/dev/stderr
  echo  -e    "write to the media\n"                              >>/dev/stderr
  Answer="$(
    con_READ  "  \"$ParentMedia\" at index \"$INDEX\". >"
  )"  # "con_READ()" writes by default to "/dev/stderr".
  # echo  $Answer                                                 >>/dev/stderr

  if [ 'Yes! Yes!' = "$Answer" ]; then
      disk_mediaAccess___WriteMediaInfo                                       \
        "$INDEX" "$InputFile" "$ParentMedia" "$ParentMediaPath"
    else
      echo  -en  "Aborting writing to the media "                 >>/dev/stderr
      echo  -e   "\"$ParentMedia\" at index \"$INDEX\".\n\n"      >>/dev/stderr
    fi
}


disk_mediaAccess__WriteQualifiedDevice() {
  # writes the qualified name of a media, that is a device, to "stdout";
  # $1: absolute path to media as device.

  # global:  DeviceQualifier0x0EAA

  local      PathLoc

  PathLoc="$1"
  disk_mediaAccess___WriteQualifiedName  "$PathLoc" "$DeviceQualifier0x0EAA"
}


disk_mediaAccess__WriteQualifiedFilesystem() {
  # writes the qualified name of a media, that is a filesystem, to "stdout";
  # $1: absolute path to media as device.

  # global:  FilesystemQualifier0x0EAA

  local      PathLoc

  PathLoc="$1"
  disk_mediaAccess___WriteQualifiedName  "$PathLoc" "$FilesystemQualifier0x0EAA"
}


disk_mediaAccess__WriteQualifiedUuid() {
  # writes the qualified name of a media specified by an uuid to "stdout";
  # $1: uuid.

  # global:  UuidQualifier0x0EAA

  local      PathLoc

  PathLoc="$1"
  disk_mediaAccess___WriteQualifiedName  "$PathLoc" "$UuidQualifier0x0EAA"
}


disk_mediaAccess___2CacheFilePath() {
  # creates the cache-file-name from the "<index into container>", the
  # "<ParentMedia>" and an optional "<MethodPath>" and writes it to "stdout";
  # $1: <BasePath>,
  # $2: index into container,
  # $3: <MethodPath>,
  # $4: <ParentMediaPath>.

  local  BasePath INDEX MethodPath ParentMediaPath

  BasePath="$1"
  INDEX="$2"
  MethodPath="$3"
  ParentMediaPath="$4"

  # echo  $BasePath                                               >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $MethodPath                                             >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  ParentMediaPath="$(f_EscapePath0x05BF  "$ParentMediaPath")"

  if [ -z  "$MethodPath"  ]; then                  # empty "<MethodPath>".
      echo  "${BasePath}/${INDEX}_${ParentMediaPath}"
    else
      echo  "${BasePath}/${INDEX}_${ParentMediaPath}_$MethodPath"  \
        | string__SearchAndReplace  ' ' '%'
   fi
}


disk_mediaAccess___2ChildDev() {
  # maps a media (converts the media), denoted by the <path to the media> and
  # the <index into container> to the block-device-name and writes it to
  # "stdout";
  # $1: index into container,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ChildMedia MediaInfo INDEX ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  ChildMedia="$(
    disk_mediaAccess___2ChildMedia1                           \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  disk_mediaAccess___QualifiedUuid2Dev  "$ChildMedia"
}


disk_mediaAccess___2ChildMedia0() {
  # ^converts, for parent-medias, whose child-media corresponds directly to the
  # <UUID>, the "parent-media" at the "index into the container" to its child-
  # media and writes the qualified child-media-name to "stdout";
  # $1: <MediaInfo>.

  local  MediaInfo UUID

  MediaInfo="$1"
  # echo  $MediaInfo                                              >>/dev/stderr

  UUID="$(disk_mediaAccess___2ChildUuid  "$MediaInfo")"  || return
                                                   # return on error.
  disk_mediaAccess__WriteQualifiedUuid  "$UUID"
}


disk_mediaAccess___2ChildMedia1() {
  # converts the "qualified parent-media" at the "index into the container" to
  # its child-media and writes the qualified child-media-name to "stdout";
  # $1: index into container.
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess____MediaHandlerCommand                                  \
    '2ChildMedia' "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___2ChildMediaFolderPath() {
  # writes the path of the child-media-folder to "stdout";
  # $1: <ChildMediaName>.

  # global:  DisksByUuidMountPath0x0EAA

  local      ChildMediaFolderPath
  local  -l  ChildMediaFolderPathLC                # converts to lower case.
  local      ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  ChildMediaFolderPathLC="${ChildMediaName}.D"
  ChildMediaFolderPath="$DisksByUuidMountPath0x0EAA/$ChildMediaFolderPathLC"

  echo "$ChildMediaFolderPath"
}


disk_mediaAccess___2ChildUuid() {
  # ^converts, for parent-medias, whose child-media corresponds directly to the
  # <UUID>, the "parent-media" at the "index into the container" to its child-
  # media and writes the qualified child-media-name to "stdout";
  # $1: <MediaInfo>.

  local    MediaInfo ParametersFile

  # parameters:
  local    UUID

  MediaInfo="$1"
  # echo  $MediaInfo                                              >>/dev/stderr

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"  \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  echo  "$UUID"
}


disk_mediaAccess___2ParentIndex() {
  # converts the "<ChildMedia>" to its parent-index and writes it to "stdout";
  # $1: <ChildMedia>.

  local  ChildMedia IndexMediaPair

  ChildMedia="$1"

  IndexMediaPair="$(
    disk_mediaAccess___2ParentIndexMediaPair  "$ChildMedia"
  )"  || return                                     # return on error.

  disk_mediaAccess___IndexMediaPair2Index     "$IndexMediaPair"
}


disk_mediaAccess___2ParentIndexMediaPair() {
  # converts the "<ChildMedia>" to its parent-index-media-pair and writes it to
  # "stdout";
  # $1: <ChildMedia>.

  # global:  Cat0x0EAA ReverseMapPath0x0EAA

  local      ChildDevPath ChildMedia

  ChildMedia="$1"
  # echo  $ChildMedia                                             >>/dev/stderr

  ChildDevPath="$(disk_mediaAccess___Media2AbsolutePath  "$ChildMedia")"   \
    || return                                      # return on error.
  ChildDevPath="$(f_EscapePath0x05BF                    "$ChildDevPath")"  \
    || return                                      # return on error.
  # echo  $ChildDevPath                                           >>/dev/stderr

  [ -z "$ChildDevPath" ]  && return  1             # if no media-name, do not
                                                   # convert.
  "$Cat0x0EAA"  "${ReverseMapPath0x0EAA}/$ChildDevPath"
}


disk_mediaAccess___2ParentMedia() {
  # converts the "<ChildMedia>" to its parent-media and writes it to "stdout";
  # $1: <ChildMedia>.

  local  ChildMedia IndexMediaPair

  ChildMedia="$1"

  IndexMediaPair="$(
    disk_mediaAccess___2ParentIndexMediaPair  "$ChildMedia"
  )"  || return                                    # return on error.

  disk_mediaAccess___IndexMediaPair2Media     "$IndexMediaPair"
}


disk_mediaAccess___CheckMediaInfo() {
  # * reads the <MediaInfo> from "stdin" and checks it;
  # * returns
  #   * "0" (true)                    if the <MediaInfo> is parsable,
  #   * "<EmptyMediaInfo0x0EAA>"      if the <MediaInfo> is empty,
  #   * "<MediaInfoNotComplete0x0EAA> if the <MediaInfo> has not been read
  #                                   compeletely,
  #   * 'else'                        on any other parse-error.

  # global:  EmptyMediaInfo0x0EAA MediaInfoCommand0x0EAA
  # global:  MediaInfoNotComplete0x0EAA


  local      ErrorMessage MediaInfo Result

  MediaInfo="$1"

  ErrorMessage="$("$MediaInfoCommand0x0EAA"  'MediaInfo'     2>&1  >/dev/null)"
  Result="$?"

  if [ '1' == "$Result" ]; then
      # echo $Result                                              >>/dev/stderr
      # echo $ErrorMessage                                        >>/dev/stderr

    string_MatchQ  "$ErrorMessage" 'unexpected $end'                 \
      &&  return  "$MediaInfoNotComplete0x0EAA"
        # else
    fi
  # else
    return  "$Result"
}


disk_mediaAccess___DeleteCacheEntries() {
  # deletes the entries for the 'ChildMedia' in the caches of 'MediaAccess_';
  # $1: <MediaName>.

  # global:  MediaHandlerUuidsCachePath0x0EAA MediaInfosCachePath0x0EAA
  #          Rm0x0EAA VerifiedMediaHandlerUuidsCachePath0x0EAA

  local      MediaName

  MediaName="$1"

  MediaName="$(f_EscapePath0x05BF  "$MediaName")"                              \
    || return                                      # return on error.
  # echo  $MediaName                                              >>/dev/stderr

  "$Rm0x0EAA"  -f  ${ContainerOffsetsCachePath0x0EAA}/*${MediaName}*           \
    2>/dev/null
  "$Rm0x0EAA"  -f  ${MediaHandlerUuidsCachePath0x0EAA}/*${MediaName}*          \
    2>/dev/null
  "$Rm0x0EAA"  -f  ${MediaInfosCachePath0x0EAA}/*${MediaName}*                 \
    2>/dev/null
  "$Rm0x0EAA"  -f  ${VerifiedMediaHandlerUuidsCachePath0x0EAA}/*${MediaName}*  \
    2>/dev/null

  return  0                                        # no error!
}


disk_mediaAccess___Destroy0() {
  # removes the media;
  # $1: <MediaInfo>,
  # $2: <SUFFIX>.

  local  ChildMediaName MediaInfo SUFFIX UUID

  MediaInfo="$1"
  SUFFIX="$2"

  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $SUFFIX                                                 >>/dev/stderr

  UUID="$(disk_mediaAccess___2ChildUuid  "$MediaInfo")"  || return
                                                   # return on error.
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="${UUID}${SUFFIX}"

  [ -z  "$ChildMediaName"  ]  && return  1         # return on empty name.

  disk_mediaAccess____Destroy  "$ChildMediaName"
}


disk_mediaAccess___Destroy1() {
  # destroys a media, that does not have a reverse-map-entry;
  # $1: <ChildMediaName>.

  # global:  DmSetup0x0EAA Rm0x0EAA

  local      ChildDevPath ChildMediaByUuidPath ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  [ -z  "$ChildMediaName"  ]  && return  1         # return on empty name.

  ChildDevPath="$(
    disk_mediaAccess___Uuid2AbsolutePath0  "$ChildMediaName"
  )"  || return                                    # return on error.
  # echo  $ChildDevPath                                           >>/dev/stderr

  ChildMediaByUuidPath="$(
    disk_mediaAccess___Uuid2ByUuidPath     "$ChildMediaName"
  )"
  # echo  $ChildByUuidMediaPath                                   >>/dev/stderr

  "$DmSetup0x0EAA" remove                  "$ChildMediaName"  || return
                                                   # return on error; do not
                                                   # unlink when the device-
                                                   # mapper-device still
                                                   # exists.

  "$Rm0x0EAA"  -f                          "$ChildMediaByUuidPath"
  disk_mediaAccess___DeleteCacheEntries    "$ChildDevPath"
}


disk_mediaAccess___GeneralError() {
  # prints the error message to "stdout";
  # $1: <ErrorMessage>,
  # $2: index into container,
  # $3: <MediaHandlerUuid>,
  # $4: <ParentMedia>.

  local  INDEX MediaHandlerUuid ParentMedia

  ErrorMessage="$1"
  INDEX="$2"
  MediaHandlerUuid="$3"
  ParentMedia="$4"

  echo  ""                                                        >>/dev/stderr
  echo  -e   "Error: $ErrorMessage;"                              >>/dev/stderr
  disk_mediaAccess___GeneralMediaDescription               \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia" '       '
}


disk_mediaAccess___GeneralMediaDescription() {
  # prints a general media-description to "stdout";
  # $1: index into container,
  # $2: <MediaHandlerUuid>,
  # $3: <ParentMedia>,
  # $4: <PREFIX>.

  local  INDEX MediaHandlerUuid ParentMedia PREFIX

  INDEX="$1"
  MediaHandlerUuid="$2"
  ParentMedia="$3"
  PREFIX="$4"

  echo  -e   "${PREFIX}Method: \"${MediaHandlerUuid}()\","        >>/dev/stderr
  echo  -en  "${PREFIX}Media:  \"$ParentMedia\" at "              >>/dev/stderr
  echo  -en  "Index \"$INDEX\".\n"                                >>/dev/stderr
}


disk_mediaAccess___GetMayBeXlatedMediaInfo() {
  # ^
  # $1: index into container,
  # $2: <ParentMedia>.

  local  INDEX ParentMedia

  INDEX="$1"
  ParentMedia="$2"

  disk_mediaAccess___MediaHandlerCommand           \
    '_GetXlatedMediaInfo' "$INDEX" "$ParentMedia"
}


disk_mediaAccess___GetMediaHandlerUuid() {
  # * gets the media-handler-uuid and writes it to "stdout",
  # * caches the media-handler-uuid,
  # * returns "0" (true) if the media handler uuid is available;
  # $1: index into container,
  # $2: <ParentMedia>,
  # $2: <ParentMediaPath>,
  # $@: 'path to method' for 'MediaInfoCommand0x0EAA' (as args).

  local  INDEX MediaInfo MethodPath ParentMedia ParentMediaPath

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"
  shift 3
  MethodPath=$@

  MediaInfo="$(
    disk_mediaAccess____GetMediaInfo                        \
    "$INDEX" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  disk_mediaAccess____GetMediaHandlerUuid                   \
    "$INDEX" "$MediaInfo" "$ParentMediaPath" "$MethodPath"
}


disk_mediaAccess___GetMediaInfo() {
  # * gets the raw 4096 bytes media info at the begin of the media, and writes
  #   it to "stdout";
  # * returns "0" (true) if the media info is available;
  # * for recursion;
  # $1: index into container,
  # $2: <ParentMedia>.

  local  INDEX ParentMedia ParentMediaPath

  INDEX="$1"
  ParentMedia="$2"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess____GetMediaInfo                                            \
    "$INDEX" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___IndexMediaPair2Index() {
  # converts a media-index-pair, e.g. as returned by
  # "disk_mediaAccess___2ParentIndexMediaPair()" to the "index into the
  # container" of the media and writes the index to "stdout";
  # $1: media-index-pair.

  local  IndexMediaPair

  IndexMediaPair="$1"

  disk_mediaAccess___Pair2FirstComponent  "$IndexMediaPair"
}


disk_mediaAccess___IndexMediaPair2Media() {
  # converts a media-index-pair, e.g. as returned by
  # "disk_mediaAccess___2ParentIndexMediaPair()" to the media and writes it
  # to "stdout";
  # $1: media-index-pair.

  local  IndexMediaPair

  IndexMediaPair="$1"

  disk_mediaAccess___Pair2SecondComponent  "$IndexMediaPair"
}


disk_mediaAccess___LinearTable() {
  # creates a linear table for a child-media;
  # $1: <ChildMediaName>,
  # $2: <ParentMedia>,
  # $3: <RealizationOptions>,
  # $4: <SIZE>,
  # $5: <START>.

  local  ChildMediaName ParentMedia ParentMediaPath RealizationOptions SIZE
  local  START TABLE

  ChildMediaName="$1"
  ParentMedia="$2"
  RealizationOptions="$3"
  SIZE="$4"
  START="$5"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  $SIZE                                                   >>/dev/stderr
  # echo  $START                                                  >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess____LinearTable                                             \
    "$ChildMediaName"                                                         \
    "$ParentMediaPath" "$RealizationOptions" "$SIZE" "$START"
}


disk_mediaAccess___Link() {
  # provided, the "ChildMediaName" belongs to a device-mapper-device (it is not
  # necessary, that the corresponding link exists in "/media/byUuid");
  # * converts the "ChildMediaName" to its "block-device-path",
  # * creates the link from "/media/byUuid/<ChildMediaName>" to this
  # "block-device-path" and writes the qualified child-media to "stdout";
  # $1: <ChildMediaName>,

  local  ChildDevPath ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  ChildDevPath="$(
    disk_mediaAccess___Uuid2AbsolutePath1  "$ChildMediaName"
  )"  || return                                    # return on error.
  # echo  $ChildDevPath                                           >>/dev/stderr

  disk_mediaAccess____Link                 "$ChildMediaName" "$ChildDevPath"
}


disk_mediaAccess___LinkAndMap() {
  # creates
  # * the link from the <TargetPath> to "/media/byUuid/<ChildMediaName>" and
  #   writes the new media ("uuid:<ChildMediaName>") to "stdout",
  # * the entry "/media/byUuid/.reverseMap/<TargetPath>" with the reverse-
  #   mapping information;
  # $1: <ChildMediaName>,
  # $2: index into container,
  # $3: <ParentMediaPath>,
  # $4: <TargetPath>.

  local  ChildMedia ChildMediaName INDEX ParentMediaPath TargetPath

  ChildMediaName="$1"
  INDEX="$2"
  ParentMediaPath="$3"
  TargetPath="$4"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $TargetPath                                             >>/dev/stderr

  ChildMedia="$(disk_mediaAccess____Link  "$ChildMediaName" "$TargetPath")"

  disk_mediaAccess___WriteReverseMapEntry                                    \
    "$TargetPath" "$INDEX" "$ParentMediaPath"

  echo  "$ChildMedia"
}


disk_mediaAccess___Media2AbsolutePath() {
  # converts the qualified media-name to the absolute path to the media and
  # writes it to "stdout";
  # $1: qualified media-name .

  local  MEDIA MediaPath

  MEDIA="$1"

  MediaPath="$(disk_mediaAccess__QualifiedName2Path  "$MEDIA")"  || return
                                                   # return on error.
  # echo  $MediaPath                                              >>/dev/stderr

  f_ToAbsolutePath  "$MediaPath"
}


disk_mediaAccess___MediaHandlerCommand() {
  # for recursion;
  # $1:      <COMMAND>,
  # $2:      index into container,
  # $3:      <ParentMedia>,
  # $4 ... : arguments for command.

  local  COMMAND INDEX MediaInfo ParentMedia ParentMediaPath

  COMMAND="$1"
  INDEX="$2"
  ParentMedia="$3"
  shift  3

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ParentMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$ParentMedia")"  \
    || return                                      # return on error.
  # echo  $ParentMediaPath                                        >>/dev/stderr

  MediaInfo="$(
    disk_mediaAccess____GetMediaInfo                                          \
      "$INDEX" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  "$MediaInfo"                                            >>/dev/stderr

  disk_mediaAccess____MediaHandlerCommand                                     \
    "$COMMAND" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" "$@"
}


disk_mediaAccess___MediaInfoOffsetPathPair2Offset() {
  # converts a media-info-offset-path-pair, e.g. as returned by
  # "disk_mediaAccess____GetMediaInfoOffsetPathPair()" to the "offset into the
  # the media and writes it to "stdout";
  # $1: media-info-offset-path-pair.

  disk_mediaAccess___Pair2FirstComponent  "$1"
}


disk_mediaAccess___MediaInfoOffsetPathPair2Path() {
  # converts a media-info-offset-path-pair, e.g. as returned by
  # "disk_mediaAccess____GetMediaInfoOffsetPathPair()" to the "path to the
  # media" and writes it to "stdout";
  # $1: media-info-offset-path-pair.

  disk_mediaAccess___Pair2SecondComponent  "$1"
}


disk_mediaAccess___NoContainer() {
  # prints the error message to "stdout";
  # $1: command,
  # $2: index into container,
  # $3: <ParentMedia>.

  local  COMMAND INDEX ParentMedia

  COMMAND="$1"
  INDEX="$2"
  ParentMedia="$3"

  [ '0' = "$INDEX" ]                                           &&  return 0
  [ 'GetComponentMediaInfo'               != "$COMMAND"  -a                  \
    'GetComponentMediaInfoOffsetPathPair' != "$COMMAND"     ]  &&  return 0

  disk_mediaAccess__InvalidIndexError  "$INDEX" "$ParentMedia"
  return                                           # return result of previous
}                                                  # command.


disk_mediaAccess___Pair2FirstComponent() {
  # ^converts a media-index-pair, e.g. as returned by
  # "disk_mediaAccess___2ParentIndexMediaPair()" to the "index into the
  # container" of the media and writes the index to "stdout";
  # $1: <Pair>.

  local  Pair

  Pair="$1"

  echo  "$Pair"  | string__SearchAndReplace  "^'\(.*\)' \+'.*$"  '\1'
}


disk_mediaAccess___Pair2SecondComponent() {
  # ^converts a media-index-pair, e.g. as returned by
  # "disk_mediaAccess___2ParentIndexMediaPair()" to the media and writes it
  # to "stdout";
  # $1: <Pair>.

  local  Pair

  Pair="$1"

  echo  "$Pair"  | string__SearchAndReplace  "^.*' \+'\(.*\)'$"  '\1'
}


disk_mediaAccess___QualifiedName2Qualifier() {
  # extracts the the qualifier from qualified media-name writes it to "stdout";
  # $1: qualified media-name.

  local  QualifiedMedia QUALIFIER

  QUALIFIER="$2"
  QualifiedMedia="$1"

  # echo  $QUALIFIER                                              >>/dev/stderr

  string__MatchQ  "$QualifiedMedia" '^.*:'  || return
                                                   # if not qualified, do not
                                                   # convert.

  echo            "$QualifiedMedia"  | string__SearchAndReplace  ':.*$' ''
}


disk_mediaAccess___QualifiedUuid2ByUuidPath() {
  # converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: qualified media-name .

  local  QualifiedMedia UUID

  QualifiedMedia="$1"

  UUID="$(disk_mediaAccess__StripUuidQualifier  "$QualifiedMedia")"
  disk_mediaAccess___Uuid2ByUuidPath            "$UUID"
}


disk_mediaAccess___QualifiedUuid2Dev() {
  # provided, the "qualified uuid" belongs to a block-device; converts the
  # "qualified uuid" to its qualified block-device-path and writes the path to
  # "stdout";
  # $1: "qualified uuid".

  local  DevPath QualifiedUuid

  QualifiedUuid="$1"
  # echo  $QualifiedUuid                                          >>/dev/stderr

  DevPath="$(disk_mediaAccess___Media2AbsolutePath  "$QualifiedUuid")"   \
    || return                                             # return on error.

  disk_mediaAccess__WriteQualifiedDevice            "$DevPath"
}


disk_mediaAccess___UdevHook() {
  # * does initializations for 'udev'.
  # $1: 'disk' of partition,
  # $2: partition name,
  # $3: partition #.

  # global:  LogPath0x0EAA

  local  DEVICE DevicePath DISK LogPath PARTITION PartNo

  DISK="$1"
  LogPath="$LogPath0x0EAA/Udev.LOG"
  PARTITION="$2"
  PartNo="$3"

  # echo  -e  "\"disk_mediaAccess___UdevHook()\""                   >/dev/tty11
  # echo  $DISK                                                     >/dev/tty11
  # echo  $PARTITION                                                >/dev/tty11
  # echo  $PartNo                                                   >/dev/tty11

  # 'standard' media-infos are either on partition #1 or #4.
    [ '1' == "$PartNo"  -o  '4' == "$PartNo" ]  || return  0

      DevicePath="/dev/$PARTITION"
      DEVICE="$(disk_mediaAccess__WriteQualifiedDevice  "$DevicePath")"
      echo      $DEVICE                                             >/dev/tty11
      echo      $DevicePath                                         >/dev/tty11
      echo      $PartNo                                             >/dev/tty11

      disk_mediaAccess___DeleteCacheEntries  "$DevicePath"

      disk_mediaAccess__VerifyMediaHandlerUuid  "$DEVICE" '0'  2>/dev/tty11  \
        || return

      disk_mediaAccess___DeleteCacheEntries "/dev/$DISK"

      echo  -e  "\"disk_mediaAccess___UdevHook()\"; RES: $?"        >/dev/tty11

      echo  -e  "\"disk_mediaAccess___UdevHook()\"; $@"            >>"$LogPath"

      echo  -e  "\"disk_mediaAccess___UdevHook()\"; /dev/$1"        >/dev/tty11
      echo  -e  "\"disk_mediaAccess___UdevHook()\"; /dev/$1"       >>"$LogPath"

      echo  -e  "\"disk_mediaAccess___UdevHook()\"; /dev/$2"        >/dev/tty11
      echo  -e  "\"disk_mediaAccess___UdevHook()\"; /dev/$2"       >>"$LogPath"

      # set                                                         >/dev/tty11
      # set                                                        >>"$LogPath"

      echo '----------------------------------------------------'  >>"$LogPath"
}


disk_mediaAccess___UnLink() {
  # destroys
  # * the link to "/media/byUuid/<ChildMediaName>",
  # $1: <ChildMediaName>.

  # global:  Rm0x0EAA

  local      ChildMediaByUuidPath ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  [ -z  "$ChildMediaName"  ]  && return  1         # return on empty name.

  ChildMediaByUuidPath="$(
    disk_mediaAccess___Uuid2ByUuidPath  "$ChildMediaName"
  )"
  # echo  "$ChildMediaByUuidPath"                                 >>/dev/stderr

  "$Rm0x0EAA"  -f                       "$ChildMediaByUuidPath"
}


disk_mediaAccess___UnLinkAndUnMap() {
  # * deletes the cache-entries for '<ChildMediaName>',
  # * destroys
  #   * the link to "/media/byUuid/<ChildMediaName>",
  #   * the entry "/media/byUuid/.metaData/.reverseMap/<ChildMediaName>";
  # $1: <ChildMediaName>.

  # global:  ReverseMapPath0x0EAA Rm0x0EAA

  local      ChildDevPath0 ChildDevPath1 ChildMediaByUuidPath ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  [ -z  "$ChildMediaName"  ]  && return  1         # return on empty name.

  ChildDevPath0="$(
    disk_mediaAccess___Uuid2AbsolutePath0  "$ChildMediaName"
  )"  || return                                    # return on error.
  # echo  $ChildDevPath0                                          >>/dev/stderr

  ChildDevPath1="$(
    f_EscapePath0x05BF                     "$ChildDevPath0"
  )"  || return                                    # return on error.
  # echo  $ChildDevPath1                                          >>/dev/stderr

  ChildMediaByUuidPath="$(
    disk_mediaAccess___Uuid2ByUuidPath     "$ChildMediaName"
  )"
  # echo  "$ChildMediaByUuidPath"                                 >>/dev/stderr

  "$Rm0x0EAA"  -f                          "$ChildMediaByUuidPath"
  "$Rm0x0EAA"  -f  "${ReverseMapPath0x0EAA}/$ChildDevPath1"

  disk_mediaAccess___DeleteCacheEntries   "$ChildDevPath0"
}


disk_mediaAccess___UnMap() {
  # destroys the entry "/media/byUuid/.reverseMap/<ChildDevicePath>";
  # $1: <ChildMediaName>.

  # global:  ReverseMapPath0x0EAA Rm0x0EAA

  local      ChildDevicePath0 ChildDevicePath1 ChildMediaName

  ChildMediaName="$1"

  # echo  $ChildMediaName                                         >>/dev/stderr

  [ -z  "$ChildMediaName"  ]  && return  1         # return on empty name.

  ChildDevPath0="$(disk_mediaAccess___Uuid2AbsolutePath0  "$ChildMediaName")"  \
    || return                                      # return on error.
  # echo  $ChildDevPath0                                          >>/dev/stderr

  ChildDevPath1="$(f_EscapePath0x05BF  "$ChildDevPath0")"                     \
    || return                                      # return on error.
  # echo  $ChildDevPath1                                          >>/dev/stderr

  "$Rm0x0EAA"  -f  "${ReverseMapPath0x0EAA}/$ChildDevPath1"

  disk_mediaAccess___DeleteCacheEntries  "$ChildDevPath0"
}


disk_mediaAccess___Uuid2AbsolutePath0() {
  # provided, the "uuid" belongs to a block-device, and a corresponding link
  # exists in "/media/byUuid"; converts the "uuid" to its "block-device-path"
  # and writes the path to "stdout";
  # $1: "uuid".

  local  QualifiedUuid UUID

  UUID="$1"
  # echo  $UUID                                                   >>/dev/stderr

  QualifiedUuid="$(disk_mediaAccess__WriteQualifiedUuid  "$UUID")"
  # echo  $QualifiedUuid                                          >>/dev/stderr

  disk_mediaAccess___Media2AbsolutePath                  "$QualifiedUuid"
}


disk_mediaAccess___Uuid2AbsolutePath1() {
  # provided, the "uuid" belongs to a device-mapper-device (it is not
  # necessary, that the corresponding link exists in "/media/byUuid"); converts
  # the "uuid" to its "block-device-path" and writes the path to "stdout";
  # $1: "uuid".

  local UUID

  UUID="$1"

  disk_dm_2BlkDevPath  "$UUID"
}


disk_mediaAccess___Uuid2ByUuidPath() {
  # converts the qualified media-name of a media specified by an uuid to the
  # path to the media and writes it to "stdout";
  # $1: media-name as "uuid".

  # global:  DisksByUuidMountPath0x0EAA

  local      UUID

  UUID="$1"

  echo  "${DisksByUuidMountPath0x0EAA}/$UUID"
}


disk_mediaAccess___VerifyMediaHandlerUuid() {
  # * returns "0" (true) if the media handler uuid may be handled;
  # $1: <INDEX>,
  # $2: <MediaHandlerUuid>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>,
  # $@: 'path to method' for 'MediaInfoCommand0x0EAA' (as args).

  # global:  VerifiedMediaHandlerUuidsCachePath0x0EAA

  local      CachedFilePath INDEX MediaHandlerUuid MethodPath ParentMedia
  local      ParentMediaPath

  INDEX="$1"
  MediaHandlerUuid="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"
  shift  4
  MethodPath="$@"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $MediaHandlerUuid                                       >>/dev/stderr
  # echo  $MethodPath                                             >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  CachedFilePath="$(
    disk_mediaAccess___2CacheFilePath                  \
      "$VerifiedMediaHandlerUuidsCachePath0x0EAA"      \
      "$INDEX" "$MethodPath" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $CachedFilePath                                         >>/dev/stderr
  # echo  $CachedFilePath                       >>___VerifyMediaHandlerUuid.LOG

  [ -f "$CachedFilePath" ]  && return  0           # already cached.
  # echo  $CachedFilePath                   >>__VerifyMediaHandlerUuidTaken.LOG

  disk_mediaAccess____VerifyMediaHandlerUuid           \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia"  && {
      touch   "$CachedFilePath"
      return  '0'
  } # else
}


disk_mediaAccess___WriteMediaInfo() {
  # * writes the <InputFile> to the 4096 bytes media info at the begin of the
  #   media,
  # * clears the corresponding cache-entry;
  # $1: index into container,
  # $2: <InputFile>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  # global:  BytesPerSector0x0EAA DD0x0EAA MediaInfosCachePath0x0EAA Rm0x0EAA

  local      CachedFilePath INDEX InputFile Offset OffsetPathPair ParentMedia
  local      ParentMediaPath

  INDEX="$1"
  InputFile="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $InputFile                                              >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  CachedFilePath="$(
    disk_mediaAccess___2CacheFilePath                                     \
      "$MediaInfosCachePath0x0EAA" "$INDEX" '' "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $CachedFilePath                                 >>___GetMediaInfo.LOG
  # echo  $CachedFilePath                                         >>/dev/stderr

  "$Rm0x0EAA"  -f "$CachedFilePath"

  OffsetPathPair="$(
    disk_mediaAccess____GetMediaInfoOffsetPathPair                        \
      "$INDEX" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  Offset="$(
    disk_mediaAccess___MediaInfoOffsetPathPair2Offset  "$OffsetPathPair"
  )"
  ParentMediaPath="$(
    disk_mediaAccess___MediaInfoOffsetPathPair2Path    "$OffsetPathPair"  \
  )"
  # echo  "$OffsetPathPair"                                       >>/dev/stderr
  # echo  "$Offset"                                               >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  echo  ''                                                        >>/dev/stderr
  "$DD0x0EAA"                                                             \
    bs="$BytesPerSector0x0EAA"                                            \
    count="$MediaInfoSize0x0EAA"                                          \
    if="$InputFile"                                                       \
    of="$ParentMediaPath"                                                 \
    seek="$Offset"
}


disk_mediaAccess___WriteQualifiedName() {
  # writes the qualified name for the media to "stdout";
  # $1: unqualified media-name,
  # $2: <QUALIFIER>.

  local MEDIA QUALIFIER

  MEDIA="$1"
  QUALIFIER="$2"

  echo  "${QUALIFIER}$MEDIA"
}


disk_mediaAccess___WriteReverseMapEntry() {
  # creates
  # * the entry
  #   * "/media/byUuid/.reverseMap/<ChildDevicePath>",
  #   with the reverse-mapping information;
  # $1: <ChildDevicePath>,
  # $2: <index into container>,
  # $3: <ParentMediaPath>.

  # global:  ReverseMapPath0x0EAA

  local      ChildDevPath INDEX ParentMedia ParentMediaPath

  ChildDevPath="$1"
  INDEX="$2"
  ParentMediaPath="$3"

  # echo  $ChildDevPath                                           >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  ChildDevPath="$(f_EscapePath0x05BF                     "$ChildDevPath")"     \
    || return                                      # return on error.

  ParentMedia="$(disk_mediaAccess__WriteQualifiedDevice  "$ParentMediaPath")"
  # echo  $ParentMedia                                            >>/dev/stderr

  disk_mediaAccess__WriteIndexMediaPair                                        \
    "$INDEX" "$ParentMedia"  >"${ReverseMapPath0x0EAA}/$ChildDevPath"
}


disk_mediaAccess____Destroy() {
  # removes the media;
  # $1: <ChildMediaName>.

  # global:  DmSetup0x0EAA

  local      ChildMediaName

  ChildMediaName="$1"
  # echo  $ChildMediaName                                         >>/dev/stderr

  "$DmSetup0x0EAA" remove               "$ChildMediaName"  || return
                                                   # return on error; do not
                                                   # unlink and unmap when
                                                   # the device-mapper-device
                                                   # still exists.

  disk_mediaAccess___UnLinkAndUnMap     "$ChildMediaName"
                                                   # refers to the still
                                                   # existing link; even if
                                                   # the device-mapper-device
}                                                  # is already removed!


disk_mediaAccess____GetMediaHandlerUuid() {
  # * gets the media-handler-uuid and writes it to "stdout",
  # * caches the media-handler-uuid,
  # * returns "0" (true) if the media handler uuid is available;
  # $1: index into container,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,
  # $@: 'path to method' for 'MediaInfoCommand0x0EAA' (as args).

  # global:  Cat0x0EAA MediaHandlerUuidsCachePath0x0EAA

  local      CachedFilePath INDEX MediaHandlerUuid MediaInfo MethodPath
  local      ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMediaPath="$3"
  shift 3
  MethodPath=$@

  CachedFilePath="$(
    disk_mediaAccess___2CacheFilePath            \
      "$MediaHandlerUuidsCachePath0x0EAA"        \
      "$INDEX" "$MethodPath" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $CachedFilePath                                         >>/dev/stderr
  # echo  $CachedFilePath                         >>___GeteMediaHandlerUuid.LOG
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $MethodPath                                             >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  [ -f "$CachedFilePath" ]  && { "$Cat0x0EAA"  "$CachedFilePath";  return; }
                                                   # already cached.
  MediaHandlerUuid="$(
    disk_mediaAccess_____GetMediaHandlerUuid  "$MediaInfo" $MethodPath
  )"  || return                                    # return on error.
    # "$@" must be without quotes to handle correctly
    # "disk_mediaAccess__GetMediaHandlerUuid <ParentMedia> <INDEX> '' ".

  echo  "$MediaHandlerUuid"
  echo  "$MediaHandlerUuid"  >"$CachedFilePath"
}


disk_mediaAccess____GetMediaInfo() {
  # * gets the raw 4096 bytes media info at the begin of the media, and writes
  #   it to "stdout";
  # * returns "0" (true) if the media info is available;
  # * for recursion;
  # $1: index into container,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  BytesPerSector0x0EAA Cat0x0EAA
  # global:  HasNoGetComponentMediaInfoOffsetPathPair0x0EAA
  # global:  MediaInfosCachePath0x0EAA

  local      CachedFilePath INDEX Offset OffsetPathPair ParentMedia
  local      ParentMediaPath

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"

  # echo  "$INDEX"                                                >>/dev/stderr
  # echo  "$ParentMedia"                                          >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  CachedFilePath="$(
    disk_mediaAccess___2CacheFilePath                                     \
      "$MediaInfosCachePath0x0EAA" "$INDEX" '' "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  "$CachedFilePath"                               >>___GetMediaInfo.LOG
  # echo  "$CachedFilePath"                                       >>/dev/stderr

  [ -f "$CachedFilePath" ]  && { "$Cat0x0EAA"  "$CachedFilePath";  return; }
                                                   # already cached.

  OffsetPathPair="$(
    disk_mediaAccess____GetMediaInfoOffsetPathPair                        \
      "$INDEX" "$ParentMedia" "$ParentMediaPath"
  )"
  Result="$?"
  # echo  "$OffsetPathPair"                                       >>/dev/stderr
  # echo  "$Result"                                               >>/dev/stderr

  case "$Result" in
      0)
        disk_mediaAccess____OffsetPathPair2MediaInfo                      \
          "$CachedFilePath" "$OffsetPathPair"                           ;;
                                                   # return result of previous
                                                   # command.
      "$HasNoGetComponentMediaInfoOffsetPathPair0x0EAA")
        disk_mediaAccess____GetMediaInfoByGetComponentMediaInfo           \
          "$CachedFilePath" "$INDEX" "$ParentMedia" "$ParentMediaPath"  ;;
                                                   # return result of previous
                                                   # command.
      *)  return  "$Result"
    esac
}


disk_mediaAccess____GetMediaInfoByGetComponentMediaInfo() {
  # *  gets the raw 4096 bytes media info by the command
  #                          "GetComponentMediaInfo" and writes it to "stdout";
  # * returns "0" (true) if the media info is available;
  # $1: <CachedFilePath>;
  # $2: index into container,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local      CachedFilePath INDEX MediaInfo MediaHandlerUuid ParentMedia
  local      ParentMediaPath

  CachedFilePath="$1"
  INDEX="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $CachedFilePath                                         >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  # here: <INDEX> > 0; so we must try to open the container
    MediaHandlerUuid="$(
      disk_mediaAccess___GetMediaHandlerUuid                           \
        '0' "$ParentMedia" "$ParentMediaPath" ''
    )"  || return                                  # return on error.
    # echo  $MediaHandlerUuid                                     >>/dev/stderr

    disk_mediaAccess___VerifyMediaHandlerUuid                          \
      '0' "$MediaHandlerUuid" "$ParentMedia" "$ParentMediaPath" ''     \
      || return                                    # return on error.
    # echo  "'VerifyMediaHandlerUuid': OK."                       >>/dev/stderr

    # here we have a 'valid' media that might be a 'valid' container.
      MediaInfo="$(disk_mediaAccess____GetMediaInfo                    \
        '0' "$ParentMedia" "$ParentMediaPath"
      )"  || return                                # return on error.

      MediaInfo="$(
        disk_mediaAccess_${MediaHandlerUuid}  'GetComponentMediaInfo'  \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
      )"  || return                                # return on error.

    echo  "$MediaInfo"  | tee "$CachedFilePath"
}


disk_mediaAccess____GetMediaInfoOffsetPathPair() {
  # * gets the offset and the path to the raw 4096 bytes media info at the
  #   begin of the media, and writes them to "stdout";
  # * returns "0" (true) if the media info is available;
  # $1: index into container,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  local  INDEX MediaInfo MediaHandlerUuid ParentMedia ParentMediaPath

  INDEX="$1"
  ParentMedia="$2"
  ParentMediaPath="$3"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  [ '' = "$INDEX" ]  && {
    echo  -e  "\nError: No Index for Media \"$ParentMedia\".\n"     \
                                                                  >>/dev/stderr
    return 127
  }

  disk_mediaAccess__CheckIndex  "$INDEX"                            \
    || disk_mediaAccess__InvalidIndexError                          \
      "$INDEX" "$ParentMedia"  || return           # return on error.

  [ '0' = "$INDEX" ]  && {
    echo  "'0' '$ParentMediaPath'"
    return
  }                                                # if container; get info
                                                   # about container.
  # here: <INDEX> > 0; so we must try to open the container
    MediaHandlerUuid="$(
      disk_mediaAccess___GetMediaHandlerUuid                        \
        '0' "$ParentMedia" "$ParentMediaPath" ''
    )"  || return                                  # return on error.
    # echo  $MediaHandlerUuid                                     >>/dev/stderr

    disk_mediaAccess___VerifyMediaHandlerUuid                       \
      '0' "$MediaHandlerUuid" "$ParentMedia" "$ParentMediaPath" ''  \
      || return                                    # return on error.
    # echo  "'VerifyMediaHandlerUuid': OK."                       >>/dev/stderr

    # here we have a 'valid' media that might be a 'valid' container.
      MediaInfo="$(disk_mediaAccess____GetMediaInfo                 \
        '0' "$ParentMedia" "$ParentMediaPath"
      )"  || return                                # return on error.

      disk_mediaAccess_${MediaHandlerUuid}                          \
        'GetComponentMediaInfoOffsetPathPair'                       \
        "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess____LinearTable() {
  # creates a linear table for a child-media;
  # $1: <ChildMediaName>,
  # $2: <ParentMediaPath>,
  # $3: <RealizationOptions>,
  # $4: <SIZE>,
  # $5: <START>.

  local  ChildMediaName ParentMediaPath RealizationOptions SIZE START TABLE

  ChildMediaName="$1"
  ParentMediaPath="$2"
  RealizationOptions="$3"
  SIZE="$4"
  START="$5"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  $SIZE                                                   >>/dev/stderr
  # echo  $START                                                  >>/dev/stderr

  TABLE="0 $SIZE  linear  $ParentMediaPath  $START"
    # echo  "$TABLE"                                              >>/dev/stderr
    echo  -n  "$TABLE"  | disk_mediaAccess__DmCreate      \
      "$ChildMediaName" "$RealizationOptions"  || return
                                                   # return on error.
}


disk_mediaAccess____Link() {
  # creates the link from the <TargetPath> to "/media/byUuid/<ChildMediaName>"
  # and writes the new media-path ("/media/byUuid/<ChildMediaName>") to
  # "stdout";
  # $1: <ChildMediaName>,
  # $2: <TargetPath>.

  local  ChildMediaByUuidPath ChildMediaName TargetPath

  ChildMediaName="$1"
  TargetPath="$2"
  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $TargetPath                                             >>/dev/stderr

  ChildMediaByUuidPath="$(
    disk_mediaAccess___Uuid2ByUuidPath  "$ChildMediaName"
  )"
  ln  -s  "$TargetPath"                 "$ChildMediaByUuidPath"

  disk_mediaAccess__WriteQualifiedUuid  "$ChildMediaName"
}


disk_mediaAccess____MediaHandlerCommand() {
  # $1:      <COMMAND>,
  # $2:      index into container,
  # $3:      <MediaInfo>,
  # $4:      <ParentMedia>,
  # $5:      <ParentMediaPath>,
  # $6 ... : arguments for command.

  local  COMMAND INDEX MediaHandlerUuid MediaInfo ParentMedia ParentMediaPath

  COMMAND="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"
  shift  5

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  MediaHandlerUuid="$(
    disk_mediaAccess____GetMediaHandlerUuid                                  \
      "$INDEX" "$MediaInfo" "$ParentMediaPath" ''
  )"  || return                                    # return on error.
  # echo  $MediaHandlerUuid                                       >>/dev/stderr

  disk_mediaAccess___VerifyMediaHandlerUuid                                  \
    "$INDEX" "$MediaHandlerUuid" "$ParentMedia" "$ParentMediaPath" ''        \
    || return                                      # return on error.

  disk_mediaAccess_${MediaHandlerUuid}                                       \
    "$COMMAND" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" "$@"
}


disk_mediaAccess____OffsetPathPair2MediaInfo() {
  # * specified by a media-info-offset-path-pair, e.g. as returned by
  #   "disk_mediaAccess____GetMediaInfoOffsetPathPair()", it gets the raw
  #   4096 bytes media info at the begin of the media, and writes it to
  #   "stdout";
  # * returns "0" (true) if the media info is available;
  # $1: <CachedFilePath>;
  # $2: media-info-offset-path-pair.

  # global:  BytesPerSector0x0EAA Cat0x0EAA DD0x0EAA MediaInfoNotComplete0x0EAA
  #          Rm0x0EAA

  local      CachedFilePath Count isInfoWritten Limit Offset OffsetPathPair
  local      ParentMediaPath Result

  CachedFilePath="$1"
  OffsetPathPair="$2"

  # echo  "$CachedFilePath"                                       >>/dev/stderr
  # echo  "$OffsetPathPair"                                       >>/dev/stderr

  Offset="$(
    disk_mediaAccess___MediaInfoOffsetPathPair2Offset  "$OffsetPathPair"
  )"
  ParentMediaPath="$(
    disk_mediaAccess___MediaInfoOffsetPathPair2Path    "$OffsetPathPair"      \
  )"
  # echo  "$OffsetPathPair"                                       >>/dev/stderr
  # echo  "$Offset"                                               >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  Count='0'
  let "Limit = 1024 * MediaInfoSize0x0EAA"

  isInfoWritten='0'
  while
        :
    do
        let "Count += MediaInfoSize0x0EAA"
        # echo  "$Count"                                          >>/dev/stderr

        "$DD0x0EAA"                                                           \
          bs="$BytesPerSector0x0EAA"                                          \
          count="$Count"                                                      \
          if="$ParentMediaPath"                                               \
          of="$CachedFilePath.tmp"                                            \
          skip="$Offset"                                                      \
            2>/dev/null                                                       \
            || return                                # return on error.
            # 'of' is not written on error.

        "$Cat0x0EAA"  "$CachedFilePath.tmp"                       >/dev/null  \
          || return           # check, if may be read; return on error.
        "$Cat0x0EAA"  "$CachedFilePath.tmp"                                   \
                                          | string_dashNUL  >"$CachedFilePath"
        "$Rm0x0EAA"   "$CachedFilePath.tmp"

        "$Cat0x0EAA"  "$CachedFilePath"  | disk_mediaAccess___CheckMediaInfo
        Result="$?"
        # echo  "$Result"                                         >>/dev/stderr

        case "$Result" in
            0)
              "$Cat0x0EAA"  "$CachedFilePath"
              return  "$Result"                           ;;

            "$MediaInfoNotComplete0x0EAA")
              [ '0' == "$isInfoWritten" ]  && {
                echo  -e  "\nreading media-info:"                 >>/dev/stderr
                isInfoWritten='1'
              }
              echo  -n '.'                                        >>/dev/stderr

              [ "$Limit" -le "$Count" ]  && {
              echo    ''                                          >>/dev/stderr
              "$Cat0x0EAA"       "$CachedFilePath"                            \
                | "$MediaInfoCommand0x0EAA"  'MediaInfo'             >/dev/null
                  Result="$?"
                "$Rm0x0EAA"  -f  "$CachedFilePath"
                return  "$Result"
              }                                           ;;

            *)                                     # it is an error.
              echo             ''                                 >>/dev/stderr
              "$Cat0x0EAA"     "$CachedFilePath"                              \
                | "$MediaInfoCommand0x0EAA"  'MediaInfo'             >/dev/null
                  Result="$?"
              "$Rm0x0EAA"  -f  "$CachedFilePath"
              return  "$Result"                           ;;
          esac
    done
}


disk_mediaAccess____VerifyMediaHandlerUuid() {
  # * returns "0" (true) if the media handler uuid may be handled;
  # $1: <INDEX>,
  # $2: <MediaHandlerUuid>,
  # $3: <ParentMedia>.

  local      CachedFileName CachedFilePath INDEX MediaHandlerUuid ParentMedia
  local      RESULT

  INDEX="$1"
  MediaHandlerUuid="$2"
  ParentMedia="$3"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $MediaHandlerUuid                                       >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  [ -z "$MediaHandlerUuid" ]  && {                 # empty media handler uuid.
    disk_mediaAccess__InvalidMediaInfoError  "$INDEX" "$ParentMedia" '127'
    return
  }

  disk_mediaAccess_____VerifyMediaHandlerUuid  "$MediaHandlerUuid"            \
    && return  '0'
  # else
    RESULT=$?

    disk_mediaAccess__InvalidMediaInfoError  "$INDEX" "$ParentMedia" "$RESULT"
}


disk_mediaAccess_____GetMediaHandlerUuid() {
  # * gets the media handler uuid and writes it to "stdout".
  # * returns "0" (true) if the media handler uuid is available.
  # $1: <MediaInfo>,
  # $@: 'path to method' for 'MediaInfoCommand0x0EAA' (as args);

  # global:  MediaInfoCommand0x0EAA

  local      MediaInfo ParentMedia

  MediaInfo="$1"
  shift  1

  RESULT="$(
    echo  -n  "$MediaInfo"  | "$MediaInfoCommand0x0EAA"  'MediaHandlerUuid'  $@
  )" || return                                     # return on error.
    # "$@" must be without quotes to handle correctly
    # "disk_mediaAccess__GetMediaHandlerUuid <ParentMedia> <INDEX> '' ".

  # replace "-" by "_":
    echo "$RESULT"  | string_SearchAndReplace  '-' '_'
}


disk_mediaAccess_____VerifyMediaHandlerUuid() {
  # returns "0" (true) if the media handler uuid may be handled;
  # $1: <MediaHandlerUuid>,

  local  MediaHandlerUuid

  MediaHandlerUuid="$1"
  # echo  $MediaHandlerUuid                                       >>/dev/stderr

  [ -z "$MediaHandlerUuid" ]  && return  127       # empty media handler uuid.

  disk_mediaAccess_${MediaHandlerUuid}  'VERIFY' '' '' '' ''        2>/dev/null
}


#^^^ in alphabetical order.
disk_mediaAccess_c2() {
  # $1: <ParentMedia>,
  # $2: index into container;

  local  INDEX ParentMedia

  INDEX="$2"
  ParentMedia="$1"

  until
      disk_mediaAccess__isEndOfChain  "$INDEX" "$ParentMedia"
    do
      if [ "128" = "$?" ]; then
          echo invalid #^
          return 128
        fi

        # echo M: $ParentMedia
        ParentMedia="$(
          disk_mediaAccess_RealizeThis  "$ParentMedia" $INDEX
        )"  || return                              # return on error.
    done
}


disk_mediaAccess_c3() {
  # ^ recursive; does not work;
  # $1: <ParentMedia>.

  local  ParentMedia

  ParentMedia="$1"

    disk_mediaAccess__isEndOfChain  "$INDEX" "$ParentMedia"  && return
    if [ "128" = "$?" ]; then
        echo invalid #^
        return 128
      fi

    disk_mediaAccess_RealizeThis  "$ParentMedia" $INDEX  || return
    disk_mediaAccess_c3           "$ParentMedia"
}


disk_mediaAccess_t1() {

  disk_dm_BlkDevName2Name  "$1"

#  disk_raid_Uuid2RaidUuid $1
#   MediaInfo="$(disk_mediaAccess__GetMediaInfo  "$@")"
 # echo $MediaInfo
# echo xxx1
#  disk_mediaAccess__isEndOfChain "$@"
#  disk_mediaAccess__VerifyMediaHandlerUuid   "$@"  || return
# echo xxx2

#  MID="$(disk_mediaAccess__GetMediaHandlerUuid "$(disk_mediaAccess__GetMediaInfo $@)")"
}


disk_mediaAccess__0MediaAccess