+***************************************
Auerswald Callnotifier for COMpact 3000
***************************************
and listens for incoming calls.
It will notify you whenever a call comes in.
+It also listens for outgoing calls if you want that, and you can log
+incoming and/or outgoing calls into a file or a database.
+
+Callnotifier is able to resolve the names of calls via LDAP and the
+caller location city names via OpenGeoDb.
+
+.. contents::
+
+
+============
+Installation
+============
+
+1. Clone the git repository
+2. Install dependencies
+3. Configure the tool
+4. Run ``./callnotifier.php``
+
+
+Dependencies
+============
+- PEAR's Console_CommandLine package
+- PEAR's Net_LDAP2 package for LDAP name resolution
+- curl for the dreambox notifier
+
+
+Systemd service
+===============
+
+1. Copy ``scripts/systemd/auerswald-callnotifier.service`` to ``/etc/systemd/system/``
+2. Adjust user and group name and callnotifier path
+3. Enable the service::
+
+ $ systemctl daemon-reload
+ $ systemctl enable auerswald-callnotifier
+ $ systemctl start auerswald-callnotifier
+ $ systemctl status auerswald-callnotifier
+
+
+=============
+Configuration
+=============
+
+Compact 3000
+============
+Enable the debug port by activating
+
+- Configuration
+
+ - Server configuration
+
+ - D channel output via IP D channel output via IP on/off
+
+German:
+
+- Einrichtung
+
+ - Serverkonfiguration
+
+ - D-Kanal über IP ausgeben D-Kanal über IP ausgeben ein-/ausschalten
+
+
+Callnotifier
+============
+Copy ``data/callnotifier.config.php.dist`` to ``data/callnotifier.config.php``
+(same name, just no ``.dist``), open it in a text editor and adjust it to
+your needs.
+
+It contains examples for every plugin.
+Adjust them as you need and remove the ones you do not need.
+
-TODO
-====
-- multiple notification methods: XMPP, dreambox, notify-send
-- ldap name resolution
-- write a call list (who, when, how long)
-- filter/exclude by local target
+Call types
+==========
+Logging plugins allow you to specify when calls shall be logged:
-Issues
+- ``startingCall`` - when the call is coming in, and the telephone rings
+- ``finishedCall`` - when the call has ended
+
+Furthermore you may decide which calls to log:
+
+- ``i`` - Log incoming calls only
+- ``o`` - Log outgoing calls only
+- ``io`` - Log both incoming and outgoing calls
+
+
+=======
+Plugins
+=======
+There are two types of plugins: Detailler and Logger.
+Detaillers load additional details to a call - e.g. a name - and loggers
+can do anything, e.g. write a log file or send a XMPP message.
+
+Detailler
+=========
+Plugins that fetch additional details to calls are named "detailler".
+
+CallMonitor_Detailler_LDAP
+--------------------------
+The plugin determines the name for a telephone number by looking up a
+LDAP directory.
+
+It retrieves the name of the caller for incoming calls, and the name
+of the telephonee for outgoing calls.
+
+It searches the following LDAP attributes:
+
+- ``companyPhone``
+- ``homePhone``
+- ``mobile``
+- ``otherPhone``
+- ``telephoneNumber``
+
+Example configuration::
+
+ $callMonitor->addDetailler(
+ new CallMonitor_Detailler_LDAP(
+ array(
+ 'host' => 'ldap.home.cweiske.de',
+ 'basedn' => 'ou=adressbuch,dc=cweiske,dc=de',
+ 'binddn' => 'cn=readonly,ou=users,dc=cweiske,dc=de',
+ 'bindpw' => 'readonly'
+ )
+ )
+ );
+
+
+CallMonitor_Detailler_OpenGeoDb
+-------------------------------
+The plugin determines the location (city) for a telephone number by
+checking the area code (prefix number) against a OpenGeoDB SQL database.
+
+If several locations share the same area code, the one with the most inhabitants
+is used.
+
+If you use this plugin, you need to run ``docs/opengeodb-create-my_orte.sql``
+on the OpenGeoDB database to create an indexed table with all relevant
+information needed by the plugin.
+
+Example configuration::
+
+ $callMonitor->addDetailler(
+ new CallMonitor_Detailler_OpenGeoDb(
+ 'mysql:host=dojo;dbname=opengeodb',
+ 'opengeodb-read',
+ 'opengeodb'
+ )
+ );
+
+
+Logger
======
+Logger handle react on events like incoming or outgoing calls,
+if they start or finish, or on any data received from the ISDN bus.
+
+Available logger:
+
+CallDb
+ Log calls in a SQL database
+CallDreambox
+ Send messages on incoming calls to the DreamBox satellite
+ receiver
+CallEcho
+ Log to the command line. Helpful for debugging.
+CallFile
+ Log finished calls into a text file
+CallFileTop
+ Log finished calls into a text file, newest on top
+CallNotifySend
+ Use the unix ``notify-send`` command on starting and finished calls
+CallSendXmpp
+ Send an XMPP headline message for incoming calls to one or multiple
+ users.
+
+
+============
+Known issues
+============
Ctrl+C does not send the disconnect command.
This is a problem with PHP since pcntl_signal handling and blocking sockets
do not work together. The signal will not be handled.
+=======
+License
+=======
+Auerswald callnotifier is licensed under the terms of the GPLv3 or later.
+
+
+======
Source
======
-Original git website: http://git.cweiske.de/?p=auerswald-callnotifier.git
+Original git website: https://git.cweiske.de/auerswald-callnotifier.git
Mirror: https://github.com/cweiske/auerswald-callnotifier