<!-- $Id: interface.sgml,v 1.1 2002/03/10 10:17:07 shane Exp $ --><chapter id="interface"><title>Interfacing With Intercom</title><para>This chapter is for those who wish to extend Intercom in ways forwhich it was not necessarily designed.  In order to get the most from thischapter, you will want some experience with a programming or scriptinglanguage such as bash, PERL, or C.  Any language should do as Intercom'scallouts are general.</para><para>Intercom provides a way by which a shell command can decide whatIntercom should do on a certain event.  This allows the user to do things assimple as playing a sound when an Incoming call comes in or as complex asimplementing time restrictions and blacklists.  This chapter describes thesemethods and includes examples whenever possible.</para><!-- TODO: drop this when I know it's correct --><note><para>The implementation should be fairly easy for any shellprogrammer to understand; however, I am a programmer and not a technicalwriter.  If something is unclear, do not hesitate to contactme.</para></note><section id="interface-hooks"><title>Introduction to Hooks</title><para>Intercom can execute a given command when a certain event occurs.  Bycommand, I refer to an Intercom command and not a Unix shell command.  Hooksare administered through the <command>hook</command> command and areautomatically saved with the <command>save</command> command.</para><para>To add a command-hook, you pass the event type and the command toexecute to the <command>hook add</command> command.  The command you specifywill be executed whenever that particular event is triggered.  The currentlydefined event types are as follows.</para><itemizedlist><listitem><para>call_incoming - Triggered on an Incoming call.  At the pointof the trigger, Intercom is ready to either accept or reject the call unlessa previous hook of this type has changed the state</para></listitem><listitem><para>call_outgoing - Triggered when an outgoing call is placed. The event is triggered after a connection to the remote host has succeededbut before the call is actually answered or rejected by the calledparty.</para></listitem><listitem><para>call_connect - Triggered just as a call is connected.  Thisevent is triggered both when we are the caller or the callrecipient.</para></listitem><listitem><para>hangup_lc - Event which is triggered when our end terminatedan established call.</para></listitem><listitem><para>hangup_rmt - Triggered when the remote party hasdisconnected a call.</para></listitem></itemizedlist><note><para>You can have more than one hook for an event type.  Hooks areexecuted in the order in which they were added.</para></note><para>As a simple example of a hook, we can automatically answer incomingcalls unconditionally with the following command.</para><para><prompt>intercom: </prompt><command>hook add call_incoming answer</command></para><para>Or, to reject all incoming calls, execute the followingcommand.</para><para><prompt>intercom: </prompt><command>hook add call_incoming hangup</command></para></section><section id="interface-exec"><title>Executing external programs</title><para>One of the simplest yet most powerful commands in terms of interfacingis the <command>exec</command> command.  It takes a single argument andpasses it directly to the shell.  For example, if you wanted to clear thescreen, you could enter <command>exec clear</command>.  Or better yet, todefine a clear alias to do the same thing, enter<command>alias <replaceable>clear</replaceable> 'exec clear'</command>.Exec takes only one argument so for more complicated commands,mind your quoting.</para></section><section id="interface-if"><title>Conditionals</title><para>Intercom can execute commands conditionally based on the exit-code ofa shell command.  This is done with the <command>if</command> command.  Itborrows much of its syntax from shell though it is much more limited.  Thesyntax of <command>if</command> is as follows.</para><para>if &lt;<replaceable>shell-command</replaceable>&gt;&lt;<replaceable>intercom-command</replaceable>&gt;[else &lt;<replaceable>else-command</replaceable>&gt;]</para><para>The <command>if</command> command will execute<replaceable>&lt;intercom-command&gt;</replaceable>if the exit status of <replaceable>&lt;shell-command&gt;</replaceable> is 0;otherwise, <replaceable>&lt;else-command&gt;</replaceable> is executed. <note><para>The else clause in an if command can beomitted.</para></note></para><para>If can further be extended to check for a specific exit-code usingoperators such as =, &lt;, and &gt;.  These will test the exit-code againstthe value specified.  The valid operators are = (equal to), != (not equal),&lt; (less than), &gt; (greater than), &lt;= (less than or equal to), and &gt;=(greater or equal to).  For example, to execute the hangup command if theexit-code of testprog.sh was greater than 1, you would enter thefollowing.</para><para><prompt>intercom: </prompt><command>If testprog.sh '>' 1 hangup</command></para></section><section id="interface-final"><title>Putting it all Together</title><para>The hook, exec, and if commands on their own offer very littlefunctionality with the possible exception of exec.  However, combined, theyallow the user to perform simple to complex Intercom tasks.  A hook commandfor example, could call a shell script.  It could even execute a commandbased on the exit-code of that script.  In the following section, you willfind some practical examples which demonstrate using these commandstogether.  You may be able to use some of them as-is and some will needmodifications.</para><section id="interface-final-examples"><title>Practical Examples</title><section id="interface-final-examples-sound"><title>Incoming Audio Alert</title><para>Most people will probably want some sort of audio alert when an incomingcall is received.  Hooks make this very easy to implement.  For thisexample, you will need a wave player such as bplay and a wave to play.  Anywave will do but don't make it too long or you will have to wait beforeanswering the call.  The below example assumes that ring.wav resides in thesounds directory off of the home directory of the user runningIntercom.</para><para><prompt>intercom: </prompt><command>hook add call_incoming'exec "bplay $HOME/sounds/ring.wav 1>/dev/null 2>&1 "'</command></para><para>Adding an audio alert when a call is terminated is fairly trivial andis left as an excersize for the reader.</para></section><section id="interface-final-examples-mixer"><title>Setting the Mixer</title><para>If you often record from your Line input or another source, you willprobably want Intercom to switch the OSS recording source to the mic input. The following simple example should do just this.  <note><para>You willmost likely need to adjust the cmix command below for the particular mixeryou use.</para></note><para><prompt>intercom: </prompt><command>hook add call_connect 'exec "cmix rcs mic on"'</command></para></section><section id="interface-final-examples-time"><title>Call Time Restrictions</title><para>The following is a more complicated example which demonstrates apossible implementation of hooks and conditionals.  Let's say you wanted toautomatically reject calls before 08:00 and after 18:00.  To accomplishthis, you would use a hook command which looks something like thefollowing.</para><para><prompt>intercom: </prompt><command>hook add call_incoming"if \"test `date +%H` -lt 8 -o `date +%H` -gt 18\" hangup"</command></para><para>The date calls are expanded by Intercom to the values of the hour. This assumes you are using GNU date though and may have to be adjusted forother date implementations.</para></section></section></section></chapter>