interface.sgml

Intercom 是一个 Unix系统上灵活的语音传输软件。支持标准音频压缩比如GSM, G.711, and G.72x和其他音频编码。Intercom专为高速网络设计来传输高品质的语音

<!-- $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 for
which it was not necessarily designed.  In order to get the most from this
chapter, you will want some experience with a programming or scripting
language such as bash, PERL, or C.  Any language should do as Intercom's
callouts are general.</para>

<para>Intercom provides a way by which a shell command can decide what
Intercom should do on a certain event.  This allows the user to do things as
simple as playing a sound when an Incoming call comes in or as complex as
implementing time restrictions and blacklists.  This chapter describes these
methods 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 shell
programmer to understand; however, I am a programmer and not a technical
writer.  If something is unclear, do not hesitate to contact
me.</para></note>

<section id="interface-hooks">
<title>Introduction to Hooks</title>

<para>Intercom can execute a given command when a certain event occurs.  By
command, I refer to an Intercom command and not a Unix shell command.  Hooks
are administered through the <command>hook</command> command and are
automatically saved with the <command>save</command> command.</para>

<para>To add a command-hook, you pass the event type and the command to
execute to the <command>hook add</command> command.  The command you specify
will be executed whenever that particular event is triggered.  The currently
defined event types are as follows.</para>

<itemizedlist>
<listitem><para>call_incoming - Triggered on an Incoming call.  At the point
of the trigger, Intercom is ready to either accept or reject the call unless
a 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 succeeded
but before the call is actually answered or rejected by the called
party.</para></listitem>
<listitem><para>call_connect - Triggered just as a call is connected.  This
event is triggered both when we are the caller or the call
recipient.</para></listitem>
<listitem><para>hangup_lc - Event which is triggered when our end terminated
an established call.</para></listitem>
<listitem><para>hangup_rmt - Triggered when the remote party has
disconnected a call.</para></listitem>
</itemizedlist>

<note><para>You can have more than one hook for an event type.  Hooks are
executed in the order in which they were added.</para></note>

<para>As a simple example of a hook, we can automatically answer incoming
calls 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 following
command.</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 interfacing
is the <command>exec</command> command.  It takes a single argument and
passes it directly to the shell.  For example, if you wanted to clear the
screen, you could enter <command>exec clear</command>.  Or better yet, to
define 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 of
a shell command.  This is done with the <command>if</command> command.  It
borrows much of its syntax from shell though it is much more limited.  The
syntax 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 be
omitted.</para></note></para>

<para>If can further be extended to check for a specific exit-code using
operators such as =, &lt;, and &gt;.  These will test the exit-code against
the 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 the
exit-code of testprog.sh was greater than 1, you would enter the
following.</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 little
functionality with the possible exception of exec.  However, combined, they
allow the user to perform simple to complex Intercom tasks.  A hook command
for example, could call a shell script.  It could even execute a command
based on the exit-code of that script.  In the following section, you will
find some practical examples which demonstrate using these commands
together.  You may be able to use some of them as-is and some will need
modifications.</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 incoming
call is received.  Hooks make this very easy to implement.  For this
example, you will need a wave player such as bplay and a wave to play.  Any
wave will do but don't make it too long or you will have to wait before
answering the call.  The below example assumes that ring.wav resides in the
sounds directory off of the home directory of the user running
Intercom.</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 and
is 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 will
probably want Intercom to switch the OSS recording source to the mic input. 
The following simple example should do just this.  <note><para>You will
most likely need to adjust the cmix command below for the particular mixer
you 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 a
possible implementation of hooks and conditionals.  Let's say you wanted to
automatically reject calls before 08:00 and after 18:00.  To accomplish
this, you would use a hook command which looks something like the
following.</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 for
other date implementations.</para>

</section>

</section>

</section>

</chapter>