#!/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/Monitor!0.!c
#
#/***************************************************************************
#                         io disk mediaAccess Monitor
#                         +++++++++++++++++++++++++++
#
#     purpose             : "mediaAccess" monitor-functions for mass-storage-
#                           medias
#
#     begin               : Sat Sep  1 12:11:36 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.                                                    *
# *                                                                         *
# ***************************************************************************/

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

# globals:
  CopyrightBase0x105A='Copyright (C) 2018 by Thomas Bruecker'
    Copyright0x105A="$CopyrightBase0x105A, <public@thomas-r-bruecker.ch>"
  MonitorCommand0x105A="/${SCRIPTS}/io/disk/dm/monitor/Monitor"
  MonitorPath0x105A="/${SCRIPTS}/io/disk/mediaAccess/Monitor"
  Title0x105A='io disk mediaAccess Monitor -- "mediaAccess" monitor-'
  Title0x105A+='functions for mass-storage-medias'
  Version0x105A='Version 0.0.0'

  # DebugLog='log'


disk_mediaAccess_monitor() {
  # prints information to stdout.

  # global:  Cat0x0EAA Less0x0EAA ThisPath0x105A

  local Information

  # introduction:
    Information="\nTo learn more about \"$MonitorPath0x105A\", read the"
    Information="${Information}\nfollowing contents of this file:\n\n"

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

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


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

  # global:  Copyright0x105A Title0x105A Version0x105A

  echo  "$Title0x105A,"
  echo  "$Version0x105A"
  echo  "$Copyright0x105A"
}


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

  local  VolumeName Reason DeviceName

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

  case "$Reason" in
      ThinPoolDataFull|ThinPoolError|ThinPoolMetadataFull)
          disk_mediaAccess___0x0889_30_DmEventDStrategyCommand  \
            "$Reason" "$DeviceName" "$@"                        ;;
      *)
          echo  "Invalid Reason"                                   >/dev/stderr
          return  127                                           ;;
    esac
}


disk_mediaAccess___MonitorGetDso() {
  # ^ 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: <MediaInfo>.

  local  MediaInfo

  MediaInfo="$1"

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

  disk_mediaAccess___QueryMonitor  'GetDso' "$MediaInfo"
}


disk_mediaAccess___MonitorGetEventMask() {
  # ^ 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: <MediaInfo>.

  local  MediaInfo

  MediaInfo="$1"

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

  disk_mediaAccess___QueryMonitor  'GetEventMask' "$MediaInfo"
}


disk_mediaAccess___Monitor_isRegistered() {
  # ^ 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: <MediaInfo>.

  local  MediaInfo

  MediaInfo="$1"

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

  disk_mediaAccess___QueryMonitor  'isRegistered' "$MediaInfo"
}


disk_mediaAccess___QueryMonitor() {
  # ^ 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: <COMMAND>,
  # $2: <MediaInfo>.

  # global:  DmEventD0xEAA MonitorCommand0x105A

  local      ChildMediaName COMMAND MediaInfo ParametersFile

  # parameters:
    local    UUID

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

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

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

  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"

  "$MonitorCommand0x105A"  "$COMMAND" "$ChildMediaName" "$DmEventD0xEAA"
}


disk_mediaAccess___RegisterMonitor() {
  # ^ 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: <ChildMediaName>,
  # $2: <COMMAND>,
  # $3: <DefaultMonitoringLibrary>,
  # $4: <MonitoringInterval>,
  # $5: <MonitoringLibrary>.

  # global:  DmEventD0xEAA MonitorCommand0x105A

  local      ChildMediaName COMMAND DefaultMonitoringLibrary MonitoringInterval
  local      MonitoringLibrary

  ChildMediaName="$1"
  COMMAND="$2"
  DefaultMonitoringLibrary="$3"
  MonitoringInterval="$4"
  MonitoringLibrary="$5"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $DefaultMonitoringLibrary                               >>/dev/stderr
  # echo  $MonitoringInterval                                     >>/dev/stderr
  # echo  $MonitoringLibrary                                      >>/dev/stderr

  [ 'REGISTER' = "$COMMAND" ]                                             \
    && disk_mediaAccess____Monitor_isRegistered  "$ChildMediaName"        \
    && return                                      # do not register twice.

  if [ 'UNREGISTER' = "$COMMAND" ]; then
      if ! disk_mediaAccess____Monitor_isRegistered  "$ChildMediaName";   \
        then
          return  0                                # do not unregister twice.
        fi
    fi

  [ '' = "$MonitoringLibrary" ]  &&                                       \
    MonitoringLibrary="$DefaultMonitoringLibrary"
  # echo  $MonitoringLibrary                                      >>/dev/stderr

  [ '' != "$MonitoringInterval"  -a  '0' != "$MonitoringInterval" ] &&    \
    "$MonitorCommand0x105A"                                               \
      "$COMMAND" "$ChildMediaName" "$DmEventD0xEAA" "$MonitoringLibrary"  \
      "$MonitoringInterval"
}


disk_mediaAccess___MonitorSendMail() {
  # ^
  # $1: <Subject>.

  local Subject ToAddr

  Subject="$1"
  ToAddr='root'

  mail  -s "$Subject"  "$ToAddr"
}


disk_mediaAccess___WaitForUnregisteringMonitor() {
  # ^ 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: <ParametersFile>.

  local    ChildMediaName ParametersFile

  # parameters:
    local  UUID

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

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

  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"

  while  disk_mediaAccess____Monitor_isRegistered  "$ChildMediaName"
    do  :;  done
}


disk_mediaAccess____Monitor_isRegistered() {
  # ^ 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: <ChildMediaName>.

  local  ChildMediaName

  ChildMediaName="$1"

  # echo  $ChildMediaName                                         >>/dev/stderr

  disk_mediaAccess____QueryMonitor  "$ChildMediaName" 'isRegistered'
}


disk_mediaAccess____QueryMonitor() {
  # ^ 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: <ChildMediaName>,
  # $2: <COMMAND>.

  # global:  DmEventD0xEAA MonitorCommand0x105A

  local      ChildMediaName COMMAND

  ChildMediaName="$1"
  COMMAND="$2"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $COMMAND                                                >>/dev/stderr

  "$MonitorCommand0x105A"  "$COMMAND" "$ChildMediaName" "$DmEventD0xEAA"
}