kbass@kenbass.com - 9/13/03

Caller ID Broadcaster - this program operates in one of two modes.

NOTE: Your modem must be caller ID capable (support the AT #CID=1) command and
you must subscribe to the caller ID service from your telephone company.

I have tested this with 2 modems - 1) USR Sportster modem on /dev/ttyS0 
and 2) a 'PCTel' 'winmodem' on /dev/ttyS15

1) [DEFAULT] It continuously monitors a caller ID capable modem. The
calling info is extracted, wrapped in an XML structure, and UDP
broadcast.

./cidbcast --file cidbcast.xml

  By default, /dev/ttyS0 is used, the UDP port is 6947, and the broadcast
address is 255.255.255.255. The default modem init string is
"AT S7=45 S0=0 L0 V1 X4 &c1 E0 Q0 #CID=1 S41=1". All these can be overridden
with command line options - invoke with '--help' for syntax.

  NOTE: S41=1 is used to turn on distinctive ringing detection.

- OR - 

2) [USING '--once' option] It relies on an external program to
invoke it; a single UDP packet is sent based on the command line
arguments, and the program exits. This mode would be used if you
want to integrate into something like mgetty or for testing.

Example:
./cidbcast --once --file cidbcast.xml ttyS0 "3015551212" "JOE SCHMOE" 1
                                      ^^port ^^number    ^^name      ^^line

Rather then hardcode the XML structure, an xml 'template' must be
provided. This program will replace keywords in the template with
caller ID info. A default cidbcast.xml is provided.

Assumptions: 

a) You are behind a firewall. You understand that the name/phone
number of everyone calling you will be broadcast from your computer
onto your LAN. Be sure your broadcast data is not be forwarded outside
your local network.

b) You don't use your modem for other things (I use broadband - this
   modem is dedicated to this caller id task). However, if you
   integrate this with mgetty, this might not be a concern.

The following keywords will be replaced in the XML file before being
sent via UDP.

%cid_port% - whatever tty port (ie; ttyS0, ttyS15, etc)
%cid_ring_type% - distinctive ring indicator (1 = Line 1, 2 = Line2,
                  3 = Line 3, 4 = Line 4)
%cid_name% - name of caller
%cid_number% - number of caller
%cid_date% - date from caller id (MMDD) [sent from phone company]
%cid_time% - time from caller id (HHMM) [sent from phone company]

The following fields are derived from the system this program is running
on and not from the phone company. See 'localtime' manpage.

%cid_time_stamp% - number of seconds since Jan 1, 1970
%cid_time_zone% - timezone string (eg; EDT)
%cid_daylight_saving% - flag indicating if daylight savings is in effect
                        (positive value indicates daylight saving in effect,
                         zero indicates not in effect, negative value
                         indicates unknown)
%cid_time_hour%        - hour portion of time (0 to 23)
%cid_time_minute%      - minute portion of time (0 to 59)
%cid_time_second%      - second portion of time (0 to 59)
%cid_time_day%         - day of the month (1 to 31)
%cid_time_month%       - month (1 to 12)
%cid_time_year%        - year (actual year)
%cid_time_string%      - string representation (see ctime())
                       - example: Wed Sep 17 22:48:21 2003


gnassas@mac.com 6/25/2005

The phonebook argument allows cidbcast to supply names when the
telco doesn't transmit one which is very handy in my area where
few/no mobile numbers have names associated with them. Substitutions
are made just before expanding the keywords in the xml file. The
phonebook parsing routine is very simplistic - it expects a number,
a colon and then a name with no whitespace before or after. The
program has a hard limit of 19 characters for names.
