FHEM Application Programming Interface for Modules.

Description of the fhem.pl functions offered to modules, and used Modules
interfaces. 
NOTE: if there is a difference between this description and fhem.pl, then this
document is to be fixed, and not fhem.pl.


Global Variables
================

------
$addTimerStacktrace
  if set to one, InternalTimer calls will add a stacktrace to the internal hash
  holding all the Timers. Used by fhemdebug

$auth_refresh
  if set one, refresh the authorization caches. Used by the allowed module.

$cmdFromAnalyze
  holds the command which will be executed by eval. Used by the __WARN__
  handler or stacktrace to report better error messages.

$devcount
  global devicecounter, used to give a unique sequential number (NR) to each
  created device. Devices are saved in NR order.

$featurelevel
  supported FHEM feature level. Its default value is the current FHEM version,
  (6.1, etc), and can be set by the user to a lower level by the attribute
  featurelevel to have more backward compatibility, if the module supports it.

$fhemForked
  set to 1 if we are in a forked process. Set only, if the fhemFork() routine
  is used for forking.

$fhemTestFile
  file to include if -t is specified. Uset for Unit tests, see the t
  subdirectory for details.

$fhem_started
  set to the current UNIX time upon FHEM startup.

$haveInet6
  set to true if the IO::Socker::INET6 module is available and the global
  variable useInet6 is set.

$init_done
  set to one, if the fhem.cfg and fhem.state are processed.
  The global INITIALIZED trigger is sent after this value is set to one,
  InternalTimers are processed next.

$internal_data
  global variable, to avoid data copying between modules. E.g. FileLog_get will
  set this variable when the outfile parameter is specified as "-".

$lastDefChange
  this variable is increased each time a definition or attribute changes. Used
  by modules to invalidate their private caches.

$lastWarningMsg
  set to the last __WARN__ message.

$nextat
  set to the time of the next InternalTimer call.

$numCPUs
  number of CPUs, if running on a Linux system.

$reread_active
  set to one while the rereadcfg operation is active.

$selectTimestamp
  set to the time before the last select was started. Can be used to identify
  busy loops, where a select was not called betweeen function calls.

$winService
  the Windows Service object.

------
%attr
  hash of Attributes. The Attributes are reerences by Devicename.

%cmds
  hash of available FHEM Commands. The command Name is specified by the hash
  key. 
  Mandatory entries:
  - Fn
    String, holding the name of the function to be called. The function will be
    called with the Client-Hash (Source-Channel of the command) and the
    command-line parameters as one string, without the command name.
  - Hlp
    One-line help, displayed by the help command
  Optional entries:
  - ReplacedBy
    Name of the new entry
  - Modulename
    Name of the module to load when this command is entered (autoloading the
    command)
  - ClientFilter
    Name of a module, this command is only valid if it is entered through this
    channel (e.g. quit is only valid for telnet connections)

%data
  Global variable, can be used by modules or enduser to store arbitrary data.

%defs
  hash of FHEM definitions.
  Mandatory entries:
  - NAME: name od the FHEM definition
  - FUUID: unique id, remains the same even after renaming
  - TYPE: name of the corresponding module or global
  - NR: number of this definition, used when saving
  - STATE: the "general" state of the device
           Note: this entry ist set by the framework from the developer
           supplied state Reading, if the user does not override it by the
           stateFormat attribute.
  - DEF: additional parameters at definition

  Optional entries
  - CFGFN: name of the configuration file the definition is coming from, used
    to save it again to this file
  - CL: input channel from where the definition was entered (telnet, FHEMWEB,
    etc). Set temporarily for DefFn/SetFn/GetFn/DeleteFn/ModifyFn/etc calls
  - EXCEPT_FD: the Filedescriptor to be monitored by select. Note: in order to
    be used, selectlist must be filled.
  - FD: the Filedescriptor to be monitored by select. Note: in order to be
    used, selectlist must be filled.
  - TEMPORARY: if set, do not save this definition, nor trigger the
    structure-change flag
  - VOLATILE: if set, save this definition to the state file, and do not
    trigger the structure-change flag
  - .AttrList
    List of device specific attributes. If absent, the module specific ones
    will be used by getAllAttr()
  - NTFY_ORDER
    The order in which the NotifyFn functions of the different devices are
    called. If not specified, is set to 50-name, or
    $module{NotifyOrderPrefix}-name
    
%inform
  telnet connections to be notified for generated events.
  
%intAt
  hash of InternalTimer entries. Maintained in parallel to the intAtA array.
  Mandatory filed for each entry:
  - TRIGGERTIME: UNIX timestamp
  - FN: function name or reference to be called
  - ARG: parameter to call the function with when the timer triggers
  - atNr: key in the hash, for cross-referencing to the array.  Optional field:
  - STACKTRACE: set if $addTimerStacktrace is specified, holding the current
    (as of the time of calling InternalTimer) stack trace.

%logInform
  hash of functions to be called for each Log call. Used e.g by FHEMWEB to show
  the FHEM-Log or notify, when the readLog attribute is set.

%modules
  hash of the modules. Modules are loaded only on request, e.g. when define is
  specified.

  Mandatory Entries:
  - ORDER: used for notifying devices for dispatched raw messages

  Optional Entries:
  - AttrFn: name of the function to be called when an attribute is set or
    deleted.  Function parameters: set or del, and an array of parameters.
  - AttrList: list of supported attributes. Used if the device hash (%defs) has
    no .AttrList entry.
  - AuthenticateFn: name of the function called to check if a connection is
    authenticated. Called with the hash of the authentication-instance, the
    connection hash, and the authentication arguments. Returns 0 if the
    authentication is not needed, 1 if authenticated and 2 if the
    authentication failed.
  - AuthorizeFn: name of the function called to check if an operation is
    authorized. Called with the hash of the authorization-instance, the
    connection hash, the type of the check (cmd or  devicename), the
    authorization arguments, and a $silent parameter. Returns 1 if authorized
    and 0 else.
  - CanAuthenticate: set by the module to 1 if it requires authentication. Used
    for Security-Checks.
  - Clients: list of potential modules which will be notified by Dispatch.
  - DefFn: the function called upon definition of a device. Called with the
    prefilled §defs hash and the command-line parameters as one string.
  - DelayedShutdownFn: called before FHEM shutdown, this function can delay the
    shutdown if returns 1. Called with the instance of the device.
  - DeleteFn: the function called upon deleting a definition, called with the
    hash of the device to be deleted.
  - defptr: hash of module-specific data, will be restored after a reload
    operation.
  - ExceptFn: function called when the select exception-Field reported an
    action. Called with the hash of the device, selectlist mus be filled, and
    EXCEP_FD must be set in the device hash.
  - FingerPrintFn: name of a function to prepare data for duplicate detection.
  - GetFn: name of the function to be called when the get command is called.
    Parameters: hash of the device, and an array of parameters
  - ldata: hash of module-specific data, will be restored after a reload
    operation.
  - LOADED: set to 1 if the module is loaded
  - Match: Regexp used in Dispatch, to identify if a message is relevant for a
    module. Set in the logical module.
  - MatchList: Hash of Modulename=>regexps, in order to search the right module
    in Dispatch. Set in the physical module, used after no defined instance is
    found to process the data, to trigger a module load.
  - NotifyFn: name of the function to be called when an event is triggered.
    Parameters: hash of the notify device, hash of the device producing the
    events. The events themselves are available by calling the deviceEvents
    function.
  - NotifyOrderPrefix: used to crate the NTFY_ORDER, if it is not set
    explicitely by the module.
  - ParseFn: Name of a function called by Dispatch to interpret data received
    by the physical (aka IO) module. Called with the IO-Instance and the raw
    data.
  - parseParams: if set, the SetFn/GetFn/DefFn parameters are called with the
    results of the parseParams function and not an array, which consists of the
    space separated command line.
  - ReadFn: name of the function to be called if dta is available. Called with
    the hash of the instance. In order to be called, %selectlist must contain a
    hash of the entry, and FD must contain the Filedescriptor to be monitored.
  - ReadyFn: called for all definitions in the %readyfnlist. On unix/osx/linux
    this is used to check if a device becomes available again, on Windows it is
    used to check if it has data, as serial devices on windows do not support
    the select call.
  - RenameFn: called when a device is renamed, with the new and the old name as
    parameters.
  - SetFn: name of the function to be called when the set command is called.
    Parameters: hash of the device, and an array of parameters.
  - ShutdownFn: called before FHEM-shutdown, to enable a cleanup.
  - StateFn: called from the setstate command, to align internal values to the
    state. Called with the device name, timestamp, readingname and value as
    parameters.
  - WriteFn: name of the function used to Write data to the device (called by
    IOWrite). Parameters: hash of the IO Device, and an array of data.
  - UndefFn: called from rereadcfg and delete to clean up (close
    filedescriptors, etc). Called with the hash of the device instance.

%ntfyHash
  hash of devices to be notified. If cleared, it will be recomputed before
  any device can be notified. Note: this computation is CPU intensive.

%prioQueues
  List of (low-)priority queues, added by PrioQueue_add

%readyfnlist
  List of devices scheduled for calling their ReadyFn

%selectlist
  List of devices scheduled for calling their ReadFn/WriteFn or ExceptFn, if
  the select of the corresponding FD/EXCEPT_FD returns activity.

%value
  hash used for featurelist <= 5.6, holding the value of each device.
  Replaced by the Value() function for featurelist > 5.6

@intAtA
  array of InternalTimer entries, see the %intAt hash for details.

@structChangeHist
  array of structural changes not saved.
