
This program is intended to be used in the Asterisk extensions.conf file
to announce (over your system's speakers) the calling party. 

In order to be useful, it depends on the following files being present:

1. in /var/lib/asterisk/sounds/CID-PLACES, a series of gsm files, one for
   each area code in the NA dialplan. There are around 400 of these. For 
   example, /var/lib/asterisk/sounds/CID-PLACES/307.gsm will say "Wyoming".

	NOTE: you can generate these files using the included file
	      areacodescript, in this way:
              festival < areacodescript

	Depending on the voice, this will take about 2 meg.

2. in /var/lib/asterisk/sounds/CID-PLACES/country-codes, a series of gsm files,
   one for each country code. Hmmm. Around 200 or 300 of these. For example,
   the file /var/lib/asterisk/sounds/CID-PLACES/country-codes/43.gsm will
   say "Austria".

	NOTE: you can generate these files using the included file
	      areacodescript, in this way:
              festival < countrycodes-script

	Depending on the voice, this will take about 4 meg.

        PS. If you want these files, but don't have festival,
        you might consider this: It will take you longer to record
        these files yourself, than to find and download festival,
        build it, install it, and run the scripts mentioned above!
        This may even include the time you might want to spend
        experimenting with the many voices supplied. My favorite
        voices are:

	(from the festival  lib/siteinit.scm file:) 

	(set! voice_default 'voice_ked_diphone)  ;; in the 1.4.3 release

	(set! voice_default 'voice_cstr_us_awb_arctic_multisyn) ;; in the 1.95beta

	 the ked_diphone voice is pretty legible. The cstr_us_awb is much more natural, 
         has kind of a scottish accent. For use on natural text, I'd personally
	 use the cstr voice, BUT, FOR the weird names used in City names, etc. in 
	 the area codes, I'd suggest the ked_diphone.

3. /var/lib/asterisk/sounds/CID-PLACES/international.gsm  "international"

4. /var/lib/asterisk/sounds/priv-unlisted.gsm      "unlisted"

5. /var/lib/asterisk/sounds/unknowncallerfrom.gsm  "unknown caller FROM:"

6. /var/lib/asterisk/sounds/somewhereinstate.gsm  "somewhere in-state"

7. /var/lib/asterisk/sounds/somewhereoutstate.gsm "somewhere outside the state"

8. For your local area code, a directory within /var/lib/asterisk/sounds/CID-PLACES,
   that contains all the area-code's prefixes, if you are energetic enough to supply these.
   for instance, the number 307-754-1111 will have "Powell, Wyoming" recorded in
   /var/lib/asterisk/sounds/CID-PLACES/307/754.gsm  
   (I gathered mine from a listing in the phone book-- one phone book was even so kind
    as to list all the cell phone prefixes by city. Wyoming is the easiest area code
    in the nation to supply these kinds of files for...!).

9. And the most challenging: in the directory /var/lib/asterisk/sounds/priv-callerintros/,
   a set of gsm files, whose names correspond to a callerid that might call you frequently,
   and whose contents are the "introduction" identifying the caller from that callerid. So,
   for example, you might have /var/lib/asterisk/sounds/priv-callerintros/3079998888.gsm, and
   it will contain the sound: "The illustrious Steve Murphy", or somesuch.

   If it makes you feel any more motivated, I've built up 426 such introductions in my
   /var/lib/asterisk/sounds/priv-callerintros dir.


The area code scripts were derived from http://www.bennetyee.org/ucsd-pages/area.html
I took liberal license in hacking the descriptions so they'd be fairly concise.

The country code scripts were derived from somewhere on the internet, a list of country codes, 
somewhere, I forget, sorry.

Prerequisites:

1. Make sure that /usr/bin/play exists. It is used to play a gsm file over the speakers.

2. Make sure you have a sound card, speakers, etc.!!!

3. Make sure you are on the asterisk system!

4. Edit who-is-it.c, and set the macro  LOCAL_AREACODE  to your own
   local area code. I'd be fairly amazed if anyone else ever actually used the default "307".

5. Edit the Makefile, and perhaps you need to change the asterisk libdir,
   which is defaulted to "/var/lib/asterisk", or the location to install 
   who-is-it, or the ... oh, just check it over, please.

6. Edit the countrycode and area code festival scripts,
   because they contain hard-wired paths /var/lib/asterisk,
   and globally change these to what's correct for your system.

To install:

1. Compile the program. Type:   make   
   and then, do "make install" to put most things in place.

2. Enter this somewhere near the beginning of the incoming context for calls:

exten => s,7,System(/usr/local/bin/who-is-it ${CALLERIDNUM} "${CALLERIDNAME}"&)

The above line assumes, of course, that who-is-it is in /usr/local/bin. 
the program who-is-it will always return a 0, or success result code, but
it in turn calls /usr/bin/play, which doesn't, and sometimes strange things happen.
I have added a little feature to my copy of the System app in asterisk, where I 
add "|0" to the end of the command string, and the app then is forced to return
a 0, success, code no matter what. This works much better for this app. 
See asterisk bug site, 

http://bugs.digium.com/bug_view_page.php?bug_id=0000768

for the patch, use the diffu file last entered. IF you have problems, 
apply the patch, rebuild and install asterisk, and use this instead:

exten => s,7,System(/usr/local/bin/who-is-it ${CALLERIDNUM} "${CALLERIDNAME}"&|0)

THE ALGORITHM:

1. The program is called with the first arg set to the CID (10 digit phone number in the US), 
followed optionally by the name string that ofttimes is passed along with the number.
If the name string isn't there, it is set to a null string in the program.

2. if the number starts with a '1', it is erased. The program is written from a us-canada 
   point of view. You'll have to mod the program for your region if you aren't in the us/canada area.

3. If the number starts with '011', it plays "international" over the speaker.

4. If the name string is "Privacy Manager", then it plays "unlisted" over the speaker.
   If you are using the Privacy Manager application in your extensions.conf, then incoming
   callers with no CID will be required to enter a number, or be hung up on. If they
   enter a number, it will be the CID number, and "Privacy Manager" will the name string.
   In my home line context, I have this:

	[homeline]
	exten => s,1,Answer
	exten => s,2,Zapateller,nocallerid
	exten => s,3,PrivacyManager
	...


5. If the intro file is present, it plays it from /var/lib/asterisk/sounds/priv-callerintros

6. If it is not:

	a. if the number is "international", it tries to find the best, longest match in the 
           /var/lib/asterisk/sounds/CID-PLACES/country-codes/ dir, of the digits after the
           "011". And then plays it.
        b. if the number is not international, it extracts the area code (first 3 digits), and
           plays the "unknown caller from" message.
        c. If the area code is your local area code:
              AND if the prefix file is present in /var/lib/asterisk/sounds/CID-PLACES/<areacode>
              it will play it.
              if the prefix file cannot be located, it plays "somewhere in - state".
	d. if not, the area code is not local, and if you have a prefix file for it in
           ar/lib/asterisk/sounds/CID-PLACES/<areacode>/, it will play it.
           Otherwise, it will just play the area code file in /var/lib/asterisk/sounds/CID-PLACES/,
           if it is there, and if all else fails, it will play the "somewhere out of state" message.
7. If a CID name string was supplied:
   it opens a file, /tmp/CID.<pid>.festival.txt, and writes the name string in there, and then
   calls /usr/bin/festival --tts <tmpfile>, and "speaks" the name string over the speakers.

=====================================================================================================
                         AGI script Version
=====================================================================================================

I've coded an AGI interface version of the who-is-it script. With it, you can use
auto-answering softphones running on PC's, or even hardware Voip phones that have
an auto-answering capability.

For instance, the softphone "DIAX" by Dante has an auto-answer mode. The simplest way
to use it is in the unfiltered autoanswer mode. Steve Sokol's IAXphone has an auto-answer
mode you can switch on, that will autoanswer any call from a certain extension number you
can set, the default is 7777, if you set the option for it. 

Here are some credits for the various pieces of this capability:

###
### Many thanks to Peter Svensson psvasterisk at psv.nu, for his
### timely advise and references. This is part of cross between
### a hotel-style wakeup call application, and a voice announce
### application using MeetMe facilities, both of which can be found
### on the Asterisk Wiki.
###
### Rob Fugina Wakeup call implementation:
###       http://www.voip-info.org/tiki-index.php?page=Asterisk%20tips%20wake-up
### John Todd's announce feature via autoanswer phones & MeetMe app:
###       http://www.voip-info.org/tiki-index.php?page=Cisco%207940-7960%20auto-answer%20config



INSTALL:

First, get and install the hotel Wakeup code. You will need at least the MyAsterisk perl 
file. See http://www.geekthing.com/~robf/asterisk/   -- It contains a write_call_file
function that is used. 

Also, the callall script from John Todd's entry is used, along with some of the contexts
he suggested in the above-mentioned write-up...

In your extensions.conf, insert the following:

[add-to-conference]
exten => start,1,MeetMe(5555,dmqp)
exten => h,1,Hangup

[announce-all]
exten => s,1,MeetMe(5555,dtqp)
exten => s,2,MeetMeAdmin(5555,K)
exten => s,3,Hangup
exten => h,1,MeetMeAdmin(5555,K)
exten => h,2,Hangup

The callall will dial all the auto-answer extensions, and use the add-to-conference context
to enter them into MeetMe.

The announce-all is used by the submit-announce.agi script to enter the announcer into the
Meetme, and play the who-is-it-agi script to the listeners.

Invoking the Announcement:

Usually in the start extension of the context for an incoming call, you insert the following
instructions in you extensions.conf file:

exten => s,5,SetVar,CONFCIDNA=${CALLERIDNAME}
exten => s,6,SetVar,CONFCIDNU=${CALLERIDNUM}
exten => s,7,AGI(callall)
exten => s,8,AGI(submit-announce.agi)

[NOTE: the exten/priority numbers should be modified, of course, to fit in the proper
spot in your environment!!! ]

The CONFCID vars are for the submit-announce.agi script. They are probably not critical...
I haven't tried to use the plain agi_callerid vars, to see if they will be sufficient.

The callall agi script will dial up all the autoanswer phones you have provided files
for. The submit-announce introduces the "master" conference member that plays sounds to
the rest. They both toss files into the "outgoing" spool directory to do these tasks.
The submit-announce script dials the Local/ channel to enable a sort of 3-way call,
with the MeetMe app hooked up to the who-is-it-agi script.

The call files for the callall script look this inside:

Channel: IAX2/murfiaxphone
Context: add-to-conference
Extension: start
Priority: 1
CallerID:  7777


NOTES:

The priv-callerintros dir in /var/lib/asterisk/sounds is going to be used by the privacy/screen
options in the Dial app, after 1.0. So, intros will tend to accumulate there if you desire.

See:  http://bugs.digium.com/bug_view_page.php?bug_id=0000752


