#!/usr/local/bin/scripts/sh
#
#.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/A8A2BB30_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB30_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for a thin pool media
#
#     begin               : Wed Jun 7 19:47:47 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("A8A2BB30_78F0_11E6_B6F3_0000C00A45A9") = 0x0889_30
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.

# global:
  DefaultMonitoringLibrary0x0889_30='libdevmapper-event-lvm2thin.so'


disk_mediaAccess_0x0889_30_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_0x0889_30_col___                          \
    "$MediaHandlerUuid" "$SIZE" "$UUID" "$PREFIX"
}


disk_mediaAccess_0x0889_30_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_A8A2BB30_78F0_11E6_B6F3_0000C00A45A9() {
  # handles a dm-thin-pool media;
  # $1: command, in {
  #       "2ChildMedia", "2QualifiedChildDev", "CHECK", "CheckForced",
  #       "DESTROY", "DUMP", "DumpH", "REALIZE", "RealizeForced",
  #       "ReleaseMetadataSnap", "REPAIR", "RepairForced",
  #       "ReserveMetadataSnap", "RMAP", "SIZE", "VERIFY", "WAIT", "_:", "__:"
  #     },
  #     * $1 in {
  #         "2ChildMedia", "2QualifiedChildDev", "DESTROY", "REALIZE",
  #         "RealizeForced", "SIZE", "VERIFY", "WAIT"
  #       }: see "../CommonCommandsSpecification.TXT";
  #     * "CHECK", "CheckForced":
  #       'thin_check';
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $@: ...;
  #     * "DUMP":
  #       dumps the metadata;
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $@: ...;
  #     * "DumpH":
  #       dumps the metadata human readable;
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $@: ...;
  #     * "PoolSize":
  #       writes the pool-size to "stdout";
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>;
  #     * "ReleaseMetadataSnap":
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>;
  #     * "REPAIR", "RepairForced":
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $@: ...;
  #     * "ReserveMetadataSnap":
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>;
  #     * "RMAP":
  #       'thin_rmap';
  #       $2: index into the container,
  #       $3: <MediaInfo>,
  #       $4: <ParentMedia>,
  #       $5: <ParentMediaPath>,
  #       $@: ...;
  #     * "_:":
  #       ^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.

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

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

  disk_mediaAccess__RealizeForced2Forced  "$COMMAND"
  # echo  "FORCED: $FORCED"                                       >>/dev/stderr

  case "$COMMAND" in
      2ChildMedia)
        disk_mediaAccess___2ChildMedia0                                 \
                   "$MediaInfo"                                         ;;
      2QualifiedChildDev)
        disk_mediaAccess___2QualifiedChildDev                           \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"       ;;
      CHECK | CheckForced)
        shift  5
        disk_mediaAccess__0x0889_30_CHECK                               \
                   "$MediaInfo"                                   "$@"  ;;
                                                   # 'thin_check'.
      DESTROY)
        disk_mediaAccess__0x0889_30_DESTROY                             \
                   "$MediaInfo"                                         ;;
      DUMP)
        shift  5
        disk_mediaAccess__0x0889_30_DUMP                                \
                   "$MediaInfo"                                   "$@"  ;;
                                                   # dump metadata.
      DumpH)
        shift  5
        disk_mediaAccess__0x0889_30_DUMP                                \
                   "$MediaInfo"  -f human_readable                "$@"  ;;
                                                   # dump metadata human
                                                   # readable.
      MappingSummary)
        disk_mediaAccess__0x0889_30_MappingSummary                      \
                   "$MediaInfo"                                         ;;
      MonitorGetDso)
        disk_mediaAccess___MonitorGetDso                                \
                   "$MediaInfo"                                         ;;
      Monitor_isRegistered)
        disk_mediaAccess___Monitor_isRegistered                         \
                   "$MediaInfo"                                         ;;
      MonitorGetEventMask)
        disk_mediaAccess___MonitorGetEventMask                          \
                   "$MediaInfo"                                         ;;
      PoolSize)
        disk_mediaAccess__0x0889_30_PoolSize                            \
                   "$MediaInfo"                                         ;;
      REALIZE | RealizeForced)
        disk_mediaAccess__0x0889_30_REALIZE                             \
          "$FORCED"                                                     \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"       ;;
      RegisterMonitor)
        disk_mediaAccess__0x0889_30_RegisterMonitor                     \
          'REGISTER'                                                    \
                   "$MediaInfo"                                         ;;
      ReleaseMetadataSnap)
        disk_mediaAccess__0x0889_30_ReleaseMetadataSnap                 \
                   "$MediaInfo"                                         ;;
      REPAIR | RepairForced)
        shift  5
        disk_mediaAccess__0x0889_30_REPAIR                              \
          "$INDEX" "$MediaInfo" "$ParentMedia"                    "$@"  ;;
      ReserveMetadataSnap)
        disk_mediaAccess__0x0889_30_ReserveMetadataSnap                 \
                   "$MediaInfo"                                         ;;
      RMAP)
        shift  5
        disk_mediaAccess__0x0889_30_RMAP                                \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath" "$@"  ;;
                                                   # 'thin_rmap'.
      SIZE)
        disk_mediaAccess__Size1                                         ;;
      UnregisterMonitor)
        disk_mediaAccess__0x0889_30_RegisterMonitor                     \
          'UNREGISTER'                                                  \
                   "$MediaInfo"                                         ;;
      _MESSAGE)
        shift  5
        disk_mediaAccess__0x0889_30_MESSAGE                             \
                   "$MediaInfo"                                   "$@"  ;;
      _RunThinTool)
        shift  5
        disk_mediaAccess__0x0889_30_RunThinTool                         \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath" "$@"  ;;
      _:)    shift 1
             disk_mediaAccess_0x0889_30_col__                     "$@"  ;;
                                                   # ^
      __RunThinTool)
        shift  5
        disk_mediaAccess___0x0889_30_RunThinTool                        \
                   "$MediaInfo"                                   "$@"  ;;
      __:)   shift 1
             disk_mediaAccess_0x0889_30_col___                    "$@"  ;;
                                                   # ^
      *)
        disk_mediaAccess___NoContainer                                  \
          "$COMMAND" "$INDEX" "$ParentMedia"                            \
          || return                                # return on error.

        disk_mediaAccess__InvalidCommandError                           \
          "$COMMAND" "$INDEX"                                           \
          'A8A2BB30_78F0_11E6_B6F3_0000C00A45A9'                        \
          "$ParentMedia"                                           ;;
    esac                                           # return result of previous
}                                                  # command.


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

  disk_mediaAccess__A8A2BB30_78F0_11E6_B6F3_0000C00A45A9  "_:"  "$@"
}


disk_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__A8A2BB30_78F0_11E6_B6F3_0000C00A45A9  "__:" "$@"
}


disk_mediaAccess__0x0889_30_CHECK() {
  # 'thin_check';
  # $1: <MediaInfo>,
  # $@: ... .

  # global:  ThinCheck0x0EAA

  local      INDEX MediaInfo ParentMedia

  MediaInfo="$1"
  shift  1

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

  disk_mediaAccess___0x0889_30_RunThinTool  "$MediaInfo" "$ThinCheck0x0EAA" $@
}


disk_mediaAccess__0x0889_30_DESTROY() {
  # destroy media;
  # $1: <MediaInfo>.

  local  MediaInfo ParametersFile

  MediaInfo="$1"

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

  disk_mediaAccess___0x0889_30_RegisterMonitor                         \
    'UNREGISTER' "$ParametersFile"

  disk_mediaAccess___WaitForUnregisteringMonitor  "$ParametersFile"

  disk_mediaAccess___Destroy0  "$MediaInfo" ''
}


disk_mediaAccess__0x0889_30_DUMP() {
  # dump metadata;
  # $1: <MediaInfo>,
  # $@: ... .

  # global:  ThinDump0x0EAA

  local      MediaInfo MetaDataMediaPath ParametersFile

  # parameters:
    local    MetaDataMedia

  MediaInfo="$1"
  shift  1

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

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

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

  MetaDataMediaPath="$(
    disk_mediaAccess___Media2AbsolutePath  "$MetaDataMedia"
  )"  || return                                    # return on error.
  # echo  "$MetaDataMediaPath"                                    >>/dev/stderr


  disk_mediaAccess___0x0889_30_ReserveMetadataSnap  "$ParametersFile"  \
    || return                                      # return on error.

  "$ThinDump0x0EAA"  -m  "$@" "$MetaDataMediaPath"                     \
    || return                                      # return on error.

  echo  ''

  disk_mediaAccess___0x0889_30_ReleaseMetadataSnap  "$ParametersFile"
}


disk_mediaAccess__0x0889_30_MappingSummary() {
  # writes the summary of the mappings to "stdout";
  # $1: <MediaInfo>.

  # global:  MkTemp0x0EAA Rm0x0EAA

  local      MediaInfo OutputFile Result


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

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

  disk_mediaAccess__0x0889_30_DUMP  "$MediaInfo"  -f human_readable  \
                                                                 >"$OutputFile"
  Result="$?"

  grep  -A1  'device:' "$OutputFile"

  "$Rm0x0EAA"  -f  "$OutputFile"

  echo         ''
  return       "$Result"
}


disk_mediaAccess__0x0889_30_MESSAGE() {
  # ^check or repair the media;
  # $1: <MediaInfo>,
  # $@: ... .

  local  MediaInfo ParametersFile

  MediaInfo="$1"
  shift  1

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

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

  disk_mediaAccess___0x0889_30_MESSAGE  "$ParametersFile" "$@"
}


disk_mediaAccess__0x0889_30_PoolSize() {
  # writes the pool-size to "stdout";
  # $1: <MediaInfo>.

  local  MediaInfo ParametersFile

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

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

  disk_mediaAccess___0x0889_30_PoolSize  "$ParametersFile"
}


disk_mediaAccess__0x0889_30_REALIZE() {
  # realize media or realize media forced;
  # $1: <FORCED>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMediaPath>.

  local    ChildMediaName DataMediaPath FORCED INDEX MediaInfo
  local    MetaDataMediaPath ParametersFile ParentMediaPath SIZE TABLE

  # parameters:
    local  COPYRIGHT CopyrightDetails DataBlockSize DataMedia LowWaterMark
    local  MetaDataMedia MonitoringInterval MonitoringLibrary OnlyOnHosts
    local  RealizationOptions URL UUID

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

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

  disk_mediaAccess__0x0889_30_CHECK  "$MediaInfo"  || return

  # clear global optional not ignored parameters.
    OnlyOnHosts=''
    RealizationOptions=''

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

  # echo  "$COPYRIGHT"                                            >>/dev/stderr
  # echo  "$CopyrightDetails"                                     >>/dev/stderr
  # echo  "$DataBlockSize"                                        >>/dev/stderr
  # echo  "$DataMedia"                                            >>/dev/stderr
  # echo  "$LowWaterMark"                                         >>/dev/stderr
  # echo  "$MetaDataMedia"                                        >>/dev/stderr
  # echo  "$MonitoringInterval"                                   >>/dev/stderr
  # echo  "$MonitoringLibrary"                                    >>/dev/stderr
  # echo  "$OnlyOnHosts"                                          >>/dev/stderr
  # echo  "$RealizationOptions"                                   >>/dev/stderr
  # echo  "$NOTES"                                                >>/dev/stderr
  # echo  "$URL"                                                  >>/dev/stderr
  # echo  "$UUID"                                                 >>/dev/stderr

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

  MetaDataMediaPath="$(
    disk_mediaAccess___Media2AbsolutePath  "$MetaDataMedia"
  )"  || return                                    # return on error.
  # echo  "$MetaDataMediaPath"                                    >>/dev/stderr

  SIZE="$(
    disk_mediaAccess___0x0889_30_PoolSize  "$ParametersFile"
  )"  || return                                    # return on error.
  # echo  "$SIZE"                                                 >>/dev/stderr
    # <SIZE> must be lower or equal to the the size of the data media.

  ChildMediaName="$UUID"

  disk_mediaAccess_isHandled                                              \
    "$FORCED" "$OnlyOnHosts" "$RealizationOptions"  || return 0

  TABLE="0 $SIZE  thin-pool  "
  TABLE+="$MetaDataMediaPath $DataMediaPath $DataBlockSize $LowWaterMark"
    # echo  "$TABLE"                                              >>/dev/stderr
    echo -n "$TABLE"  | disk_mediaAccess__DmCreate                        \
      "$ChildMediaName" "$RealizationOptions"  || return
                                                   # return on error.

  disk_mediaAccess___0x0889_30_RegisterMonitor                            \
    'REGISTER' "$ParametersFile"

  disk_mediaAccess__LinkAndMap                                            \
    "$ChildMediaName" "$INDEX" "$ParentMediaPath"
}


disk_mediaAccess__0x0889_30_RegisterMonitor() {
  # ^destroy media;
  # $1: <COMMAND>,
  # $2: <MediaInfo>.

  local    COMMAND MediaInfo ParametersFile

  COMMAND="$1"
  MediaInfo="$2"

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

  disk_mediaAccess___0x0889_30_RegisterMonitor                         \
     "$COMMAND" "$ParametersFile"
}


disk_mediaAccess__0x0889_30_ReleaseMetadataSnap() {
  # $1: <MediaInfo>.

  local  MediaInfo ParametersFile

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

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

  disk_mediaAccess___0x0889_30_ReleaseMetadataSnap  "$ParametersFile"
}


disk_mediaAccess__0x0889_30_REPAIR() {
  # check or repair the media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $@: ... .

  local  INDEX MediaInfo ParentMedia

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

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

  disk_mediaAccess__0x0889_30_CHECK  "$MediaInfo" "$@"  && return
                                                   # checking is ok.

  echo  -e   "\nThis media may not be repaired automatically;"    >>/dev/stderr
  echo  -e   "Please contact your system-administrator."          >>/dev/stderr
                                                                  >>/dev/stderr
  disk_mediaAccess___GeneralMediaDescription                             \
    "$INDEX" 'A8A2BB30_78F0_11E6_B6F3_0000C00A45A9' "$ParentMedia" '  '

  return  "$FileSystemErrorsLeftUncorrected0x0EAA"
}


disk_mediaAccess__0x0889_30_ReserveMetadataSnap() {
  # $1: <MediaInfo>.

  local  MediaInfo ParametersFile

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

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

  disk_mediaAccess___0x0889_30_ReserveMetadataSnap  "$ParametersFile"
}


disk_mediaAccess__0x0889_30_RMAP() {
  # 'thin_rmap';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,
  # $@: ... .

  # global:  ThinRmap0x0EAA

  local      INDEX MediaInfo ParentMediaPath

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

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

  disk_mediaAccess__0x0889_30_RunThinTool                            \
    "$INDEX" "$MediaInfo" "$ParentMediaPath" "$ThinRmap0x0EAA" "$@"
}


disk_mediaAccess__0x0889_30_RunThinTool() {
  # runs a 'thin-tool' after destroying the pool; then it realizes the pool
  # again;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,
  # $4: <TOOL>,
  # $@: ... .

  local  INDEX MediaInfo ParametersFile ParentMediaPath TOOL

  INDEX="$1"
  MediaInfo="$2"
  ParentMediaPath="$3"
  TOOL="$4"
  shift  4

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

  disk_mediaAccess___Destroy0  "$MediaInfo" ''  || return
                                                   # return on error.

  disk_mediaAccess___0x0889_30_RunThinTool  "$MediaInfo" "$TOOL" "$@"
    RESULT="$?"

  disk_mediaAccess__0x0889_30_REALIZE                                  \
    '0' "$INDEX" "$MediaInfo" "$ParentMediaPath"           >/dev/null  \
    || return                                      # return on error.

  return  "$RESULT"
}


disk_mediaAccess___0x0889_30_MESSAGE() {
  # ^check or repair the media;
  # $1: path to parameters-file,
  # $@: ... .

  # global:  DeviceMapperBasePath0x0EAA

  local      ParametersFile PoolMediaName

  ParametersFile="$1"
  shift  1

  # echo  "$ParametersFile"                                       >>/dev/stderr
  # echo  "$@"                                                    >>/dev/stderr

  .  "$ParametersFile"  || return                  # return on error.

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

  PoolMediaName="$UUID"

  disk_dm__Setup  message  "${DeviceMapperBasePath0x0EAA}/$PoolMediaName"  \
    '0' "$@"
    # "'0'": seems to be a sector# 'without meaning'.
}


disk_mediaAccess___0x0889_30_PoolSize() {
  # write the pool-size to "stdout";
  # $1: path to parameters-file.

  local    DataMediaPath ParametersFile

  # parameters:
    local  DataMedia

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

  .  "$ParametersFile"  || return                  # return on error.

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

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

  disk_SIZE "$DataMediaPath" 'S'
}


disk_mediaAccess___0x0889_30_RegisterMonitor() {
  # ^destroy media;
  # $1: <COMMAND>,
  # $2: <ParametersFile>.

  # global:  DefaultMonitoringLibrary0x0889_30

  local    ChildMediaName COMMAND ParametersFile

  # parameters:
    local  MonitoringInterval MonitoringLibrary UUID

  COMMAND="$1"
  ParametersFile="$2"

  # clear global optional not ignored parameters.
    MonitoringInterval=''
    MonitoringLibrary=''

  .  "$ParametersFile"  || return                  # return on error.

  # echo  "$MonitoringInterval"                                   >>/dev/stderr
  # echo  "$MonitoringLibrary"                                    >>/dev/stderr
  # echo  "$UUID"                                                 >>/dev/stderr

  ChildMediaName="$UUID"

  disk_mediaAccess___RegisterMonitor                                   \
    "$ChildMediaName" "$COMMAND" "$DefaultMonitoringLibrary0x0889_30"  \
    "$MonitoringInterval" "$MonitoringLibrary"
}


disk_mediaAccess___0x0889_30_ReleaseMetadataSnap() {
  # $1: path to parameters-file.

  local  ParametersFile

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

  disk_mediaAccess___0x0889_30_MESSAGE         \
    "$ParametersFile" 'release_metadata_snap'
}


disk_mediaAccess__0x0889_30_REPAIR() {
  # check or repair the media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $@: ... .

  local  INDEX MediaInfo ParentMedia

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

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

  disk_mediaAccess__0x0889_30_CHECK  "$MediaInfo" "$@"  && return
                                                   # checking is ok.

  echo  -e   "\nThis media may not be repaired automatically;"    >>/dev/stderr
  echo  -e   "Please contact your system-administrator."          >>/dev/stderr
                                                                  >>/dev/stderr
  disk_mediaAccess___GeneralMediaDescription                             \
    "$INDEX" 'A8A2BB30_78F0_11E6_B6F3_0000C00A45A9' "$ParentMedia" '  '

  return  "$FileSystemErrorsLeftUncorrected0x0EAA"
}


disk_mediaAccess___0x0889_30_ReserveMetadataSnap() {
  # $1: path to parameters-file.

  local  ParametersFile

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

  disk_mediaAccess___0x0889_30_MESSAGE         \
    "$ParametersFile" 'reserve_metadata_snap'
}


disk_mediaAccess___0x0889_30_RunThinTool() {
  # runs a 'thin-tool'; the pool must be 'destroyed';
  # $1: <MediaInfo>,
  # $2: <TOOL>,
  # $@: ... .

  local    MediaInfo MetaDataMediaPath ParametersFile TOOL

  # parameters:
    local  MetaDataMedia

  MediaInfo="$1"
  TOOL="$2"
  shift  2

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

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

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

  MetaDataMediaPath="$(
    disk_mediaAccess___Media2AbsolutePath  "$MetaDataMedia"
  )"  || return                                    # return on error.
  # echo  "$MetaDataMediaPath"                                    >>/dev/stderr

  "$TOOL"  "$MetaDataMediaPath" "$@"
}


disk_mediaAccess___0x0889_30_DmEventDStrategyCommand() {
  # ^
  # $1: <Reason>,
  # $2: <DeviceName>,
  # $4 ... .

  local  FillEventSubject HostName Reason DeviceName

  Reason="$1"
  DeviceName="$2"
  shift  2

  HostName="$(hostname -f)"
  FillEventSubject="'Fill-Event' on Thin pool \"$DeviceName:$HostName\""

  case "$Reason" in
      ThinPoolDataFull)
          echo  "WARNING: Thin pool \"$DeviceName\" data is now $1% full."  \
            | disk_mediaAccess___MonitorSendMail  "$FillEventSubject"       \
              || {
                echo  "Failed to send mail"                        >/dev/stderr
                return  124
                #^ %s from %s: %s.");
              }
        ;;
      ThinPoolError)
          echo  "ERROR: Thin pool \"$DeviceName\" has error."               \
            | disk_mediaAccess___MonitorSendMail                            \
              "'Error-Event' on Thin pool \"$DeviceName:$HostName\""        \
              || {
                echo  "Failed to send mail"                        >/dev/stderr
                return  124
              }
        ;;
      ThinPoolMetadataFull)
          echo                                                              \
            "WARNING: Thin pool \"$DeviceName\" metadata is now $1% full."  \
            | disk_mediaAccess___MonitorSendMail  "$FillEventSubject"       \
              || {
                echo  "Failed to send mail"                        >/dev/stderr
                return  124
              }
        ;;
    esac

  echo  "INFO: Sending mail."
}