#!/usr/local/bin/scripts/sh
#
# ^pen: ^; ^test thoroughly for different component medias.
#
#.Y / 70 83 / / / / 105 / / / /  / /               ;A4_QUER.Y
#.YT 3 2 0 0 3 3 1 / / /
#.H!a!0:linux/<scripts>/io/disk/mediaAccess/mediaHandlers.d/A8A2BB33_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB33_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for a 'stacked' container
#
#     begin               : Mon May 24 11:48:36 CEST 2017
#
#     changes             :
#
#     copyright           : (C) 2017 by Thomas Bruecker
#
#     email               : public@thomas-r-bruecker.ch
#
#     version             : -0.0.0
#
#*******************************************************************************/

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

# MyHash("A8A2BB33_78F0_11E6_B6F3_0000C00A45A9") = 0x088C_33
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.

. "/${SCRIPTS}/memory/THIS"


Xdisk_mediaAccess_0x088C_33_col__() {
  # $1: size,
  # $2: uuid,
  # $3: prefix; most often: indent,
  # * writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  PREFIX="$3"
  PREFIX1="  $PREFIX0"
  SIZE="$1"
  UUID="$2"

  MediaHandlerUuid="$(
    echo  "${FUNCNAME[1]}"                                      \
      | string__SearchAndReplace    '^disk_mediaAccess_*' ''    \
        | string_SearchAndReplace   '_'                   '-'   \
  )"

  disk_mediaAccess_0x088C_33_col___  \
    "$MediaHandlerUuid" "$SIZE" "$UUID" "$PREFIX"
}


Xdisk_mediaAccess_0x088C_33_col___() {
  # $1: media-handler-uuid,
  # $2: size,
  # $3: uuid,
  # $4: prefix; most often: indent,
  # ^* writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  MediaHandlerUuid="$1"
  PREFIX0="$4"
  PREFIX1="  $PREFIX0"
  SIZE="$2"
  UUID="$3"

  START='8' # ^
  # ^ sort parameters.

  disk_mediaAccess_col__METHOD              "$MediaHandlerUuid" "$PREFIX0"
    disk_mediaAccess_col__CommonParameters  "$MediaHandlerUuid" "$PREFIX1"
    disk_mediaAccess_col__SIZE              "$SIZE"             "$PREFIX1"
    disk_mediaAccess_col__START             "$START"            "$PREFIX1"
    disk_mediaAccess_col__UUID              "$UUID"             "$PREFIX1"
  disk_mediaAccess_col__MethodEnd                               "$PREFIX0"
}


disk_mediaAccess_A8A2BB33_78F0_11E6_B6F3_0000C00A45A9() {
  # handles a 'stacked' container;
  # $1: command, in {
  #       "ContainerCommand", "DESTROY", "DestroyMediaInfo",
  #       "DestroyNewComponentMedia", "GetComponentMediaInfo", "Index2Offset",
  #       "NewOffset", "numComponents", "RealizeMediaInfo",
  #       "RealizeNewComponentMedia", "SIZE", "StartOfComponentMedia", "SYNC",
  #       "VERIFY", "WAIT"
  #     },
  #     * $1 in { "DESTROY", "SIZE", "VERIFY", "WAIT" }: see
  #                                       "../CommonCommandsSpecification.TXT",
  #     * "ContainerCommand":
  #       execute a command 'for the container';
  #       $2: <INDEX>;
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $6: command, in {
  #             "DestroyMediaInfo", "DestroyNewComponentMedia",
  #             "GetComponentMediaInfo", "Index2Offset", "NewOffset",
  #             "numComponents", "RealizeMediaInfo",
  #             "RealizeNewComponentMedia", "SIZE", "StartOfComponentMedia",
  #             "SYNC", "VERIFY", "WAIT"
  #           },
  #       $7: <INDEX of component-media>;
  #     * "DestroyMediaInfo":
  #       destroy media info of component media;
  #       $1: <ParentMedia>,
  #       $2: <INDEX>;
  #     * "DestroyNewComponentMedia":
  #       destroy the new media immediately after the latest valid component
  #       media;
  #       $1: <ParentMedia>;
  #     * "GetComponentMediaInfo":
  #       get media info of a container component,
  #       $2: path to the media (device, file, rootFolder of a filsystem),
  #       $3: index into container,
  #       * writes the media info of the indexed container component to
  #         "stdout";
  #     * "Index2Offset":
  #       * index to offset;
  #       * gets the offset from the begin of <ParentMedia> of the component
  #         media that corresponds to the <INDEX> and writes it to "stdout";
  #       $1: <ParentMedia>,
  #       $2: <INDEX>;
  #     * "MaxContainerSize"
  #       writes the maximum possible size of the container, the media-info-
  #       sectors not included, to "stdout";
  #       $1: <ParentMedia>;
  #     * "MaxNewComponentMediaSize":
  #       writes the maximum possible size of a new media immediately after the
  #       latest valid component media, the media-info-sectors not included, to
  #       "stdout";
  #       $1: <ParentMedia>;
  #     * "NewOffset":
  #       gets the offset from the begin of <ParentMedia> of a possible
  #       component media immediately after the latest valid component media
  #       and writes it to "stdout";
  #       $1: <ParentMedia>;
  #     * "numComponents":
  #       * #components;
  #       * writes the number of component medias in the container to "stdout";
  #       $1: <ParentMedia>;
  #     * "RealizeMediaInfo":
  #       realize media info of component media;
  #       $1: <ParentMedia>,
  #       $2: <INDEX>;
  #     * "RealizeNewComponentMedia":
  #       * realize a new media immediately after the latest valid component
  #         media and writes it to "stdout",
  #       * the new media is realized including the media-info-sectors;
  #       $1: <ParentMedia>;
  #     * "StartOfComponentMedia":
  #       writes the start offset of the component media to "stdout";
  #       $1: <ParentMedia>,
  #       $2: <INDEX>;
  #     * "SYNC":
  #       synchronize block-device with device-mapper-tables;
  #     * "_:":  ^verify command,
  #              ^$2: path to the media (device, file, rootFolder of a filsystem),
  #              ^$3: index into container,
  #     * "__:": ^verify command,
  #              $2: media-handler-uuid,
  #              $3: size,
  #              $4: uuid,
  #              $5: prefix, most often: indent;
  #              ^* writes the size-parameter to "stdout".

  local      COMMAND INDEX MediaInfo ParentMedia ParentMediaPath

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

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

  # quick, for verifying and 'wait':
    disk_mediaAccess__VerifyNoWait  "$COMMAND"  && return 0
                                                   # if ok, return 0; no
                                                   # waiting for component
                                                   # medias at all.

  case "$COMMAND" in
      CHECK|REPAIR)  return  0                                          ;;
      ContainerCommand)
        COMMAND="$6"
        INDEX="$7"
        shift  7
        disk_mediaAccess__0x088C_33_ContainerCommand                    \
          "$COMMAND"                                                    \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" "$@"  ;;
      DESTROY)
        disk_mediaAccess__0x088C_33_DESTROY                             \
                   "$MediaInfo"                                         ;;
                                                   # destroy.
      DestroyMediaInfo)
        disk_mediaAccess__0x088C_33_DestroyMediaInfo                    \
          "$INDEX" "$MediaInfo"                                         ;;
                                                   # destroy media info of
                                                   # component media.
      DestroyNewComponentMedia)
        disk_mediaAccess__0x088C_33_DestroyNewComponentMedia            \
                   "$MediaInfo"                       ;;
      GetComponentMediaInfo)
        disk_mediaAccess__0x088C_33_GetComponentMediaInfo               \
          "$INDEX"              "$ParentMedia" "$ParentMediaPath"       ;;
      GetComponentMediaInfoOffsetPathPair)
        disk_mediaAccess__0x088C_33_GetComponentMediaInfoOffsetPathPair  \
          "$INDEX"              "$ParentMedia" "$ParentMediaPath"       ;;
      Index2Offset)
        disk_mediaAccess__0x088C_33_Index2Offset                        \
          "$INDEX"              "$ParentMedia" "$ParentMediaPath"       ;;
                                                   # index to offset.
      MaxContainerSize)
        disk_mediaAccess__0x088C_33_MaxContainerSize                    \
                                               "$ParentMediaPath"       ;;
      MaxNewComponentMediaSize)
        disk_mediaAccess__0x088C_33_MaxNewComponentMediaSize            \
                   "$MediaInfo" "$ParentMedia" "$ParentMediaPath"       ;;
# ^pen:
      NestedContainerCommand)
        shift  5
        disk_mediaAccess__0x088C_33_NestedContainerCommand              \
                   "$MediaInfo" "$ParentMedia"                    "$@"  ;;
      NewOffset)
        disk_mediaAccess__0x088C_33_NewOffset                           \
                                "$ParentMedia" "$ParentMediaPath"       ;;
      numComponents)
        disk_mediaAccess__0x088C_33_numComponents                       \
                   "$MediaInfo"                                         ;;
                                                    # #components.
      RealizeMediaInfo)
        disk_mediaAccess__0x088C_33_RealizeMediaInfo                    \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"       ;;
                                                   # realize media info of
                                                   # component media.
      RealizeNewComponentMedia)
        disk_mediaAccess__0x088C_33_RealizeNewComponentMedia            \
                   "$MediaInfo" "$ParentMedia" "$ParentMediaPath"       ;;
      SIZE)
        disk_mediaAccess__Size0  '0' "$MediaInfo"                       ;;
      StartOfComponentMedia)
        disk_mediaAccess__0x088C_33_StartOfComponentMedia               \
          "$INDEX"              "$ParentMedia" "$ParentMediaPath"       ;;
      SYNC)
        disk_mediaAccess__0x088C_33_SYNC                                ;;
                                                   # synchronize block-device
                                                   # with device-mapper-tables
#     _:)
#       shift 1
#       disk_mediaAccess_0x088C_33_col__                          "$@"  ;;
#                                                  # ^
#     __:)
#       shift 1
#       disk_mediaAccess_0x088C_33_col___                         "$@"  ;;
#                                                  # ^
      *)
        disk_mediaAccess__InvalidCommandError                           \
          "$COMMAND" "$INDEX"                                           \
          'A8A2BB33_78F0_11E6_B6F3_0000C00A45A9'                        \
          "$ParentMedia"                                                ;;
    esac                                           # return result of previous
}                                                  # command.


Xdisk_mediaAccess_col__LINEAR() {                  # ': _LINEAR'
  # $1: size,
  # $2: uuid,
  # $3: prefix; most often: indent,
  # * writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB33_78F0_11E6_B6F3_0000C00A45A9  "_:"  "$@"
}


Xdisk_mediaAccess_col___LINEAR() {                  # ': __LINEAR'
  # $1: media-handler-uuid,
  # $2: size,
  # $3: uuid,
  # $4: prefix; most often: indent,
  # ^* writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB33_78F0_11E6_B6F3_0000C00A45A9  "__:" "$@"
}


disk_mediaAccess__0x088C_33_ContainerCommand() {
  # execute a command 'for the container';
  # $1: command, in {
  #       "DestroyMediaInfo", "DestroyNewComponentMedia",
  #       "GetComponentMediaInfo", "Index2Offset", "NewOffset",
  #       "numComponents", "RealizeMediaInfo", "RealizeNewComponentMedia", "SIZE",
  #       "StartOfComponentMedia", "SYNC", "VERIFY", "WAIT"
  #     },
  # $2: <INDEX of component-media>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>,
  # $@: ... .


  local  COMMAND INDEX 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

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


disk_mediaAccess__0x088C_33_DESTROY() {
  # destroy, destroy especially the media-info-medias.
  # $1: <MediaInfo>.

  local    I MediaInfo _numComponents
                               # do not interfere with "numComponents".
  # parameters:
    local  numComponents

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

  _numComponents="$(
    disk_mediaAccess__0x088C_33_numComponents              "$MediaInfo"
  )"  || return                                    # return on error.

  let _numComponents++                             # 'container' has index 0.
  # echo  $_numComponents                                         >>/dev/stderr

  for((I = 0; I < _numComponents; I++))
    do
        disk_mediaAccess__0x088C_33_DestroyMediaInfo  "$I" "$MediaInfo"       \
                                                                    2>/dev/null
      done
  return  0
}


disk_mediaAccess__0x088C_33_DestroyMediaInfo() {
  # destroy media info of component media;
  # $1: <INDEX of component-media>,
  # $2: <MediaInfo>.

  local  ComponentMediaInfoName MediaInfo UUID

  INDEX="$1"
  MediaInfo="$2"

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

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

  ComponentMediaInfoName="${UUID}.MediaInfo.${INDEX}"

  disk_mediaAccess___Destroy1  "$ComponentMediaInfoName"
}


disk_mediaAccess__0x088C_33_DestroyNewComponentMedia() {
  # destroys the new media immediately after the latest valid component media;
  # $1: <MediaInfo>.

  local  MediaInfo NewComponentMediaName UUID

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

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

  NewComponentMediaName="${UUID}.NewComponent"

  disk_mediaAccess___Destroy1  "$NewComponentMediaName"
}


disk_mediaAccess__0x088C_33_GetComponentMediaInfo() {
  # * gets the raw 4096 bytes media-info at the begin of the component media
  #   that corresponds to the <INDEX> and writes it to "stdout",
  # * returns "0" (true) if the media info is available;
  # $1: <INDEX of component-media>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  DD0x0EAA MediaInfoSize0x0EAA

  local      INDEX OFFSET ParentMedia ParentMediaPath

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

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

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

  "$DD0x0EAA"                                     \
    bs='512'                                      \
    count="$MediaInfoSize0x0EAA"                  \
    if="$ParentMediaPath"                         \
    skip="$OFFSET"                                \
    2>/dev/null
}


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

  local      INDEX OFFSET ParentMedia ParentMediaPath

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

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

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

  echo  "'$OFFSET' '$ParentMediaPath'"
}


disk_mediaAccess__0x088C_33_Index2Offset() {
  # gets the offset from the begin of <ParentMedia> of the component media that
  # corresponds to the <INDEX> and writes it to "stdout";
  # $1: <INDEX of component-media>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  Cat0x0EAA ContainerOffsetsCachePath0x0EAA

  local      CachedFilePath INDEX ContainerComponentSize numComponents OFFSET
  local      ParentMedia ParentMediaPath

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

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

  numComponents="$(
    disk_mediaAccess__0x088C_33_numComponents "$MediaInfo"
  )"  || return                                    # return on error.
  # echo  $numComponents                                          >>/dev/stderr
    [ "$numComponents" -lt "$INDEX" ]  && {
      disk_mediaAccess__InvalidIndexError  "$INDEX" "$ParentMedia"  || return
    }                                              # return on error.

  echo  -n  '.'                                                   >>/dev/stderr

  # it is not worth, to cache these two.
    [ 0 -eq "$INDEX" ]  && { echo  '0';                     return; }
    [ 1 -eq "$INDEX" ]  && { echo  "$MediaInfoSize0x0EAA";  return; }

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

  [ -f "$CachedFilePath" ]  && { "$Cat0x0EAA"  "$CachedFilePath";  return; }
                                                  # already cached.
  # echo  -n  't'                                                 >>/dev/stderr

  let "INDEX -= 1"

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

  # echo  getting ContainerComponentSize $INDEX                   >>/dev/stderr

  ContainerComponentSize="$(
    disk_mediaAccess___MediaHandlerCommand  'SIZE' "$INDEX" "$ParentMedia" ''
  )"  || return                                    # return on error.
  # echo  $ContainerComponentSize                                 >>/dev/stderr

  let "OFFSET += ContainerComponentSize"

  echo  "$OFFSET"  | tee  "$CachedFilePath"
}


disk_mediaAccess__0x088C_33_MaxContainerSize() {
  # writes the maximum possible size of the container, the media-info-sectors
  # not included, to "stdout";
  # $1: <ParentMediaPath>.

  # global:  MediaInfoSize0x0EAA

  local      DiskSize MaxContainerSize ParentMediaPath

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

  DiskSize="$(disk_SIZE  "$ParentMediaPath" 'S')"
  # echo  $DiskSize                                               >>/dev/stderr

  let    "MaxContainerSize = DiskSize - MediaInfoSize0x0EAA"
  echo  "$MaxContainerSize"
}


disk_mediaAccess__0x088C_33_MaxNewComponentMediaSize() {
  # writes the maximum possible size of a new media immediately after the
  # latest valid component media, the media-info-sectors not included, to
  # "stdout";
  # $1: <MediaInfo>.
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  MediaInfoSize0x0EAA

  local      MaxContainerSize MaxNewComponentMediaSize MaxSize MediaInfo OFFSET
  local      ParentMedia ParentMediaPath

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

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

  MaxContainerSize="$(
    disk_mediaAccess__0x088C_33_MaxContainerSize  "$ParentMediaPath"
  )"

  MaxSize="$(disk_mediaAccess__Size0  '0' "$MediaInfo")"
                                                   # '0': the container !
  let "MaxSize -= MediaInfoSize0x0EAA"             # the size of media-info is
                                                   # included in 'MaxSize'.
  # echo  $MaxContainerSize                                       >>/dev/stderr
  # echo  $MaxSize                                                >>/dev/stderr

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

  MaxNewComponentMediaSize="$(math_Min  "$MaxContainerSize" "$MaxSize")"
  # echo  $MaxNewComponentMediaSize                               >>/dev/stderr

  let "MaxNewComponentMediaSize -= OFFSET" # + MediaInfoSize0x0EAA)"
                                                   # 'OFFSET' 'is before' the
                                                   # media-info of the new
                                                   # component-media.

  # echo  $MaxNewComponentMediaSize                               >>/dev/stderr

  MaxNewComponentMediaSize="$(math_Max  "$MaxNewComponentMediaSize" '0')"

  echo  "$MaxNewComponentMediaSize"
}


disk_mediaAccess__0x088C_33_NewOffset() {
  # * gets the offset from the begin of <ParentMedia> of a possible component
  #   media immediately after the latest valid component media and writes it to
  #   "stdout";
  # $1: <ParentMedia>,
  # $2: <ParentMediaPath>.
  # ^ problem with index = numComponents + 1 !!!

  # global:  EmptyMediaInfo0x0EAA

  local      I OFFSET ParentMedia ParentMediaPath RESULT TmpOffset

  ParentMedia="$1"
  ParentMediaPath="$2"

  OFFSET=0
  for((I = 0; ; I++))
    do
        TmpOffset="$(
          disk_mediaAccess__0x088C_33_Index2Offset  \
            "$I" "$ParentMedia" "$ParentMediaPath"
        )"
        RESULT="$?"
        [ "$EmptyMediaInfo0x0EAA" == "$RESULT" ]    \
          && break
        [ '0'                     != "$RESULT" ]    \
          && return "$RESULT"                      # return on error.

        OFFSET="$TmpOffset"
      done
  echo  $OFFSET
}


disk_mediaAccess__0x088C_33_numComponents() {
  # writes the number of component medias in the container to "stdout";
  # $1: <MediaInfo>.

  local    MediaInfo ParametersFile

  # parameters:
    local  numComponents

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

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

  echo  $numComponents
}


disk_mediaAccess__0x088C_33_RealizeMediaInfo() {
  # realize media info of component media;
  # $1: <INDEX of component-media>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  # global:  MediaInfoSize0x0EAA

  local      ComponentMediaInfoName INDEX OFFSET ParentMedia ParentMediaPath
  local      UUID

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

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

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

  ComponentMediaInfoName="${UUID}.MediaInfo.${INDEX}"
  # echo  $ComponentMediaInfoName                                 >>/dev/stderr

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

  disk_mediaAccess____LinearTable  "$ComponentMediaInfoName"         \
    "$ParentMediaPath" '' "$MediaInfoSize0x0EAA" "$OFFSET"           \
    || return                                      # return on error.

  disk_mediaAccess___Link  "$ComponentMediaInfoName"
}


disk_mediaAccess__0x088C_33_RealizeNewComponentMedia() {
  # * realizes a new media immediately after the latest valid component media
  #   and writes it to "stdout",
  # * the new media is realized including the media-info-sectors;
  # $1: <MediaInfo>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  MediaInfoSize0x0EAA

  local      MaxNewComponentMediaSize MediaHandlerUuid MediaInfo
  local      NewComponentMediaName OFFSET ParentMedia ParentMediaPath SIZE UUID

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

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

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

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

  NewComponentMediaName="${UUID}.NewComponent"

  MaxNewComponentMediaSize="$(
    disk_mediaAccess__0x088C_33_MaxNewComponentMediaSize                      \
      "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"
  # echo  $MaxNewComponentMediaSize                               >>/dev/stderr

  MediaHandlerUuid="$(
    disk_mediaAccess____GetMediaHandlerUuid                                   \
      '0' "$MediaInfo" "$ParentMediaPath" ''
  )"                                               # '0': the container !

  if [ "0" -ge "$MaxNewComponentMediaSize" ]; then
      echo      ""                                                >>/dev/stderr
      echo  -n  "Error: No Space Left on "                        >>/dev/stderr
      echo      "Media: \"$ParentMedia\","                        >>/dev/stderr
      echo      "       Method: \"$MediaHandlerUuid()\"."         >>/dev/stderr
      echo      ""                                                >>/dev/stderr
      return 1
    fi
    # else

  let "SIZE = MaxNewComponentMediaSize + MediaInfoSize0x0EAA"
                                                   # include media-info-size.
  # echo  $SIZE                                                   >>/dev/stderr

  disk_mediaAccess___LinearTable  "$NewComponentMediaName"                    \
    "$ParentMedia" '' "$SIZE" "$OFFSET"                                       \
    || return                                      # return on error.


  disk_mediaAccess___Link  "$NewComponentMediaName"
}


disk_mediaAccess__0x088C_33_StartOfComponentMedia() {
  # writes the start offset of the component media to "stdout";
  # $1: <INDEX of component-media>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>.

  # global:  MediaInfoSize0x0EAA

  local  INDEX OFFSET ParentMedia ParentMediaPath START

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

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

  OFFSET="$(
    disk_mediaAccess__0x088C_33_Index2Offset      \
      "$INDEX" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  let "START = OFFSET + MediaInfoSize0x0EAA"
  echo  $START
}


disk_mediaAccess__0x088C_33_SYNC() {
  # synchronize block-device with device-mapper-tables.

  disk_mediaAccess__DeleteCaches
  memory_FreeCache  Page
}


disk_mediaAccess___isStackedContainer() {
  # ^ * returns "0" (true) if the media handler uuid may be handled.
  # $1: <INDEX>,
  # $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__isMediaHandlerUuid          \
    "$INDEX" "$ParentMedia" "$ParentMediaPath"  \
    'A8A2BB33_78F0_11E6_B6F3_0000C00A45A9'
                                                   # return result of last
}                                                  # command.