README.rst

   1 ***************************************
   2 Auerswald Callnotifier for COMpact 3000
   3 ***************************************
   4
   5 Connects to the debug port of your Auerswald Compact 3000 telephony switchboard
   6 and listens for incoming calls.
   7 It will notify you whenever a call comes in.
   8
   9 It also listens for outgoing calls if you want that, and you can log
  10 incoming and/or outgoing calls into a file or a database.
  11
  12 Callnotifier is able to resolve the names of calls via LDAP and the
  13 caller location city names via OpenGeoDb.
  14
  15 .. contents::
  16
  17
  18 ============
  19 Installation
  20 ============
  21
  22 1. Clone the git repository
  23 2. Install dependencies
  24 3. Configure the tool
  25 4. Run ``./callnotifier.php``
  26
  27
  28 Dependencies
  29 ============
  30 - PEAR's Console_CommandLine package
  31 - PEAR's Net_LDAP2 package for LDAP name resolution
  32 - curl for the dreambox notifier
  33
  34
  35 =============
  36 Configuration
  37 =============
  38 Copy ``data/callnotifier.config.php.dist`` to ``data/callnotifier.config.php``
  39 (same name, just no ``.dist``), open it in a text editor and adjust it to
  40 your needs.
  41
  42 It contains examples for every plugin.
  43 Adjust them as you need and remove the ones you do not need.
  44
  45
  46
  47 Call types
  48 ==========
  49 Logging plugins allow you to specify when calls shall be logged:
  50
  51 - ``startingCall`` - when the call is coming in, and the telephone rings
  52 - ``finishedCall`` - when the call has ended
  53
  54 Furthermore you may decide which calls to log:
  55
  56 - ``i`` - Log incoming calls only
  57 - ``o`` - Log outgoing calls only
  58 - ``io`` - Log both incoming and outgoing calls
  59
  60
  61 =======
  62 Plugins
  63 =======
  64 There are two types of plugins: Detailler and Logger.
  65 Detaillers load additional details to a call - e.g. a name - and loggers
  66 can do anything, e.g. write a log file or send a XMPP message.
  67
  68 Detailler
  69 =========
  70 Plugins that fetch additional details to calls are named "detailler".
  71
  72 CallMonitor_Detailler_LDAP
  73 --------------------------
  74 The plugin determines the name for a telephone number by looking up a
  75 LDAP directory.
  76
  77 It retrieves the name of the caller for incoming calls, and the name
  78 of the telephonee for outgoing calls.
  79
  80 It searches the following LDAP attributes:
  81
  82 - ``companyPhone``
  83 - ``homePhone``
  84 - ``mobile``
  85 - ``otherPhone``
  86 - ``telephoneNumber``
  87
  88 Example configuration::
  89
  90     $callMonitor->addDetailler(
  91         new CallMonitor_Detailler_LDAP(
  92             array(
  93                 'host' => 'ldap.home.cweiske.de',
  94                 'basedn' => 'ou=adressbuch,dc=cweiske,dc=de',
  95                 'binddn' => 'cn=readonly,ou=users,dc=cweiske,dc=de',
  96                 'bindpw' => 'readonly'
  97             )
  98         )
  99     );
 100
 101
 102 CallMonitor_Detailler_OpenGeoDb
 103 -------------------------------
 104 The plugin determines the location (city) for a telephone number by
 105 checking the area code (prefix number) against a OpenGeoDB SQL database.
 106
 107 If several locations share the same area code, the one with the most inhabitants
 108 is used.
 109
 110 If you use this plugin, you need to run ``docs/opengeodb-create-my_orte.sql``
 111 on the OpenGeoDB database to create an indexed table with all relevant
 112 information needed by the plugin.
 113
 114 Example configuration::
 115
 116     $callMonitor->addDetailler(
 117         new CallMonitor_Detailler_OpenGeoDb(
 118             'mysql:host=dojo;dbname=opengeodb',
 119             'opengeodb-read',
 120             'opengeodb'
 121         )
 122     );
 123
 124
 125 ====
 126 TODO
 127 ====
 128 - multiple notification methods: XMPP, dreambox, notify-send
 129
 130
 131 ============
 132 Known issues
 133 ============
 134 Ctrl+C does not send the disconnect command.
 135 This is a problem with PHP since pcntl_signal handling and blocking sockets
 136 do not work together. The signal will not be handled.
 137
 138
 139 =======
 140 License
 141 =======
 142 Auerswald callnotifier is licensed under the terms of the GPLv3 or later.
 143
 144
 145 ======
 146 Source
 147 ======
 148 Original git website: http://git.cweiske.de/?p=auerswald-callnotifier.git
 149
 150 Mirror: https://github.com/cweiske/auerswald-callnotifier