home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / fax067.zip / answ.doc < prev    next >
Text File  |  1997-04-09  |  19KB  |  480 lines
  1. Preliminary documentation for
  2.  
  3.  
  4.         ANSW.EXE and ANSW.DLL
  5.  
  6.     Created 1992 - 1997 by Dr. Harald Pollack & Bernhard Seidl
  7.  
  8.  
  9.  
  10. This application is for IBM OS/2 32 bit operation system only.
  11.  
  12.  
  13. 1) CONFIGURATION FILE
  14.  
  15.     While the name of this file can be anywhat, ANSW defaults (see at
  16.     commandline options) to ANSW.CFG
  17.  
  18.     [TASK <n>]
  19.         Starts a section within the configuration file which only effects
  20.         the selected task. To end a section you can either use another
  21.         [TASK <n>] keyword which would start another section or use the
  22.         keyword [COMMON], described below.
  23.  
  24.     [COMMON]
  25.         All keywords after this statement belong to all tasks.
  26.  
  27.     CONFIGEND
  28.         ANSW will stop working off the configuration file and everything
  29.         following this keyword will be ignored.
  30.  
  31.     LOGBINKLEYSTYLE
  32.         Using this keyword ANSW will generate BinkleyTerm like log entries.
  33.  
  34.     DEBUG
  35.         Enables a lot of stuff for debugging. Do not use, because LOG will
  36.         increase enormous.
  37.  
  38.     LOGLEVEL <n>
  39.         Writing to DEBUGLOG depends on this value (0 to 5).
  40.             0 ... do NOT write to DEBUGLOG
  41.             1 ... ERROR only
  42.             2 ... ERROR + SEND + RECEIVE only
  43.             3 ... ERROR + SEND + RECEIVE + ACTION only
  44.             4 ... ERROR + SEND + RECEIVE + ACTION + WAIT FOR only
  45.             5 ... ERROR + SEND + RECEIVE + ACTION + WAIT FOR + INFO (default)
  46.  
  47.     CLMSGOK <script or errorlevel or shellno>
  48.         If ANSW.DLL is called from CantaLoup/2, a simple mechanism will allow
  49.         further actions of the mailer if a message was recorded sucessful:
  50.             - A positiv value forces mailer to exit with this errorlevel.
  51.             - A negativ value forces mailer to 'shell' to abs(value).
  52.             - A name of a script forces the mailer to execute it.
  53.  
  54.     BAUDRATE <DTE-DCE bitrate>
  55.         Bitrate for initialisation of modem. Some older modem, especially those
  56.         which are not capable of high speed data communication, do require a
  57.         baudrate of 2400 bps.
  58.  
  59.     REDIALWAIT <seconds>
  60.         Time to wait between two dial tries.
  61.  
  62.     DIALRETRIES <count>
  63.         Number of dial tries. Default is '0'. That means after an unsuccessful
  64.         call, ANSW will terminate. If 'DIALRETRIES' is defined, ANSW will try
  65.         to establish a connection for the determined number of times until
  66.         terminating.
  67.  
  68.     PRELISTEN <seconds>
  69.         If value greater than 0 (default is 3, maximum is 10), ANSW will
  70.         'listen' on the line to detect a calling tone (from modem or fax)
  71.         before 'GreetingMessage' is played. If a calling tone is detected,
  72.         ANSW immediatly terminates, so mailer or other frontend can handle
  73.         this call.
  74.  
  75.     DIAL <dial command>
  76.         Default, 'ATD' is used. If an other dial command is required (e.g.
  77.         'ATD0W') 'DIAL' keyword can be used.
  78.  
  79.     DEBUGLOG <[+]file name>
  80.         This is the name of the log and debug log file of ANSW. Nearly all
  81.         activities are stored in this file. If a '+' precedes the path,
  82.         append mode is used: one log is chained to the next. Select NUL as
  83.         filename to disable logging.
  84.         The logfile contains a lot of informations in case of errors or
  85.         situations where help is needed. Bugreports to the author are only
  86.         sensful if this logfile is part of the report.
  87.  
  88.     PORT <serial port>
  89.         This keyword is mandatory. Even if ANSW is called using a port handle
  90.         (from frontend or mailer) this keyword must exist! The name of the
  91.         device is used to create a unique identifier for internal use!
  92.  
  93.     INITFIFO
  94.         If a hardware fifo (UART 16550) is detected by COM-device driver, the
  95.         fifo is initiallized to Rx=8 and Tx=16.
  96.  
  97.     DEBUGIDLEPRIORITY <value> or DEBUGREGULARPRIORITY <value>
  98.         These keywords, which are mutual exclusive, define the priority (0-31)
  99.         for the task (thread) which writes the data to DEBUGLOG file. Default
  100.         is IDLEPRIORITY 30. Change this setting only, if you are absolutly sure
  101.         knowing what you do! Lower priority may yield in a endless blocking
  102.         debug_thread! No data will be written to DEBUGLOG and ANSW may become
  103.         'uncloseable'. On very slow or high stressed machines, you can
  104.         try REGULARPRIORITY 0, if IDLEPRIORITY blocks writing to DEBUGLOG.
  105.  
  106.     VOICEVOLUME <value>
  107.     To be described ...
  108.  
  109.     BUSYCOUNT <cnt>
  110.         In voicemode, busy tone is signaled from DCE to DTE by supplying
  111.         <DLE>+'b'. Modem sensitivity to detect this may differ depending on
  112.         firmware version. Human voice may simulate busy to modem in playback
  113.         of a message. By default, BusyCount is 1 (one detected busy will
  114.         stop all further activities) but can be set from 1 to 5.
  115.  
  116.     RECACTSPK <val>
  117.         If modem is able to use its speaker if recording, volumelevel of it
  118.         may be selected (ATL<val> is used).
  119.  
  120.     PLAYACTSPK <val>
  121.         If modem is able to use its speaker if playback, volumelevel of it
  122.         may be selected (ATL<val> is used).
  123.  
  124.     VOICEMODE <modemtype>
  125.         Depending on modemtype (manufacturer) keywords ZYXEL or ROCKWELL may
  126.         be selected. Default is ZYXEL.
  127.  
  128.     FLOWCONTROL <type>
  129.         Normally, ANSW uses software flowcontrol (XON/XOFF), but type CTS or
  130.         HW can be set to enable hardware flowcontrol.
  131.  
  132.     VCONSENSITIVITY <val>
  133.     To be described ...
  134.  
  135.     STOPONDTMF <digit>
  136.         Normaly, telephonkey '*' acts as an immediat stop condition. By
  137.         default, digit '5' is set to act also as an unconditional stop.
  138.         Redefining to other digit is possible. Any other entry than '0' - '9'
  139.         will deactivate this feature.
  140.  
  141.     RINGCNT
  142.         Number of RING, ANSW will wait to go off-hook. Only active in
  143.         standalone mode.
  144.  
  145.  
  146.     RECTIMELIMIT <seconds>
  147.         By default, ANSW only records 30 seconds of a voice message. With this
  148.         keyword, a range of 20 - 600 seconds is selectable.
  149.  
  150.     VOICEPATH <path>
  151.         Path to where voice messages are stored (and sent from).
  152.         This entry in CFG is mandatory! There will be no default, ANSW will
  153.         not start if not defined. VOICEPATH is used to form a fully quallyfied
  154.         path to VOICELOG and VOICEIDX. If one of both keywords has OFF in CFG,
  155.         voice messages are store in <voicepath>\ANSWnnnn.ZVD, else voice
  156.         messages are stored as VCnnnnnn.ZVD (see VOICEIDX).
  157.  
  158.     VOICELOG <file name> | OFF
  159.         Filename to VOICE.LOG and only neccessary, if other than 'VOICE.LOG'.
  160.         Received voice messages from ANSW will be joined to VOICE.LOG.
  161.         Each stored voice message is flagged as 'Rcvd'. If received voice
  162.         message is too short to save, no entry is made.
  163.         In case of far inquiry or callback, the voice message file is flagged
  164.         with 'Read' (far inquiry) or 'Sent' (callback). If callback fails,
  165.         the entry is flagged with 'NoAnsw' and if dialretry count is above 0,
  166.         a new entry (with same voice file) is made and flagged with 'Spool'.
  167.         Also MakeSem is started (with DialWait) to force mailer to call ANSW
  168.         again to satisfy callback.
  169.  
  170.     VOICEIDX <file name> | OFF
  171.         Filename to VOICE.IDX and only neccessary, if other than
  172.         'VOICE.IDX'. Used to select value 'nnnnnn' for VCnnnnnn.ZVD.
  173.  
  174.     CLEANUP <modem command>
  175.         If ANSW finishes in a on-hook state (no 'quiet', no calling tone
  176.         detected), <modem command> is sent to modem. Multiple entries are
  177.         possible, recommanded is at least 'AT', but you can use any
  178.         modem command. Before CleanUp, an AT+FCLASS=0 is sent to modem and
  179.         after CleanUp a DTR-drop is performed!
  180.  
  181.     POSTINIT <modem command>
  182.         If ANSW finishes in a off-hook state ('quiet' or calling tone
  183.         detected), <modem command> is sent to modem. Multiple entries are
  184.         possible. Be carefully in selecting modem commands. Normally, the
  185.         same commands should be used as in mailers 'Answer' string, EXCEPT
  186.         ATA command, which is sent automatically after PostInit!
  187.  
  188.         Example for enabling adaptive autoanswer (fax class 2 / data)
  189.         after ANSW:
  190.  
  191.         PostInit AT+FCLASS=0
  192.         PostInit AT+FCR=1
  193.         PostInit AT+FAA=1
  194.  
  195.     PREINIT <modem command>
  196.         Just befor ANSW switches modem to voice mode, modem command is sent
  197.         to modem. Multiple entries are possible, recommended is ATE0 to
  198.         disable echo from modem. Do not use any command like ATA, ATD or ATH!
  199.  
  200.     MINMSGLENGTH <bytes>
  201.         By default, voice message less than 6000 bytes is NOT stored. You can
  202.         select any other value here.
  203.  
  204.     MENUFILE <file name>
  205.         If user selects far inquiry, this message is played. Should contain
  206.         anything like:
  207.         'Far inquiry! Hit ZERO to cancel, ONE for all new messages, TWO for
  208.         all messages and THREE to delete all messages',
  209.         or in german:
  210.         "Fernabfrage! NULL fuer Abbruch, EINS fuer alle neuen Anrufe, ZWEI
  211.         fuer alle bisherigen Anrufe, DREI zum Loeschen aller Anrufe".
  212.  
  213.     ANSW is hardcoded to this four digits (0, 1, 2, and 3)!
  214.  
  215.         This voicefile MUST BE exclusively for the used modem. No WAV or VOC or
  216.         anything else will work!
  217.  
  218.         This entry is mandatory!
  219.  
  220.     GREETINGFILE <file name>
  221.         This voice file is played when ANSW becomes activ (after PreListen).
  222.         Should contain anything like:
  223.         'Hello, there is <your name>, please speak after the beep tone',
  224.         or in german:
  225.         '<Name>, hinterlassen sie mir bitte nach dem Signalton eine
  226.         Nachricht'.
  227.  
  228.         This entry is mandatory!
  229.  
  230.     ENDRECFILE <file name>
  231.         This voice file is played after successful storage of callers message.
  232.         Should contain anything like:
  233.         'Your call is recorded',
  234.         or in german:
  235.         'Ihr Anruf wurde aufgezeichnet'.
  236.  
  237.         This entry is mandatory!
  238.  
  239.     CALLBACKFILE <file name>
  240.         If callback feature is enabled, this voicefile is played in front of
  241.         further actions. Should contain anything like:
  242.         'Announcement of incoming call, please enter password',
  243.         or in german:
  244.         "Verstaendigung ueber einen eingegangenen Anruf, bitte
  245.         Passwort eingeben".
  246.  
  247.         This entry is mandatory!
  248.  
  249.     FARINQUIRYPWD <digits>
  250.         Up to five (dialable) digits can be defined as a password for the
  251.         far inquiry feature.
  252.  
  253.     CODINGSCHEME <value>
  254.         To be described ...
  255.  
  256.     CALLBACKEVENT <day_spec.> <starttime> <endtime> <phonenumber> [<password>]
  257.         This keyword enables ANSWs callback feature. Each well received message
  258.         is sent to <phonenumber> if current day and time is in the range
  259.         specified. Multiple declarations are possible to dial to more than
  260.         one phonenumbers at different day/time.
  261.         <day_specifier> may be 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' and
  262.         'Sun'. Also possible is 'Weekday' or 'Weekend' or 'All'. Any
  263.         combinations (delimited by blank character) are allowed:
  264.  
  265.         CallbackEvent Weekend Mon 08:00 22:00 034598712 4711
  266.         CallbackEvent Weekday 07:30 17:00 789123 0815
  267.  
  268.         Overlapping of eventdefinitions for the same phonenumber should be
  269.         avoided, because ANSW will than call more times:
  270.  
  271.         CallbackEvent Week 08:30 16:30 54321
  272.         CallbackEvent Mon  15:00 21:00 54321
  273.  
  274.         will overlap on monday from 15:00 to 16:30 ! Each call at this time
  275.         will result in TWO callbacks to 54321 !!!
  276.  
  277.         Up to five (dialable) digits can be defined as a password for the
  278.         callback feature.
  279.  
  280.         Callback feature is only possible if VOICELOG and VOICEIDX ar NOT
  281.         set to OFF !
  282.  
  283.  
  284.     ACTIVITYEVENT <day_specifier> <starttime> <endtime>
  285.         If defined, activity period of ANSW can be set. Multiple declarations
  286.         are possible.
  287.         <day_specifier> may be 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' and
  288.         'Sun'. Also possible is 'Weekday' or 'Weekend' or 'All'. Any
  289.         combinations (delimited by blank character) are allowed:
  290.  
  291.         ActivityEvent Mon Tue 08:00 20:00
  292.         ActivityEvent Weekday 09:30 17:15
  293.  
  294.     INBOUND <path to inbound>
  295.         If DESTNAME and DESTADDR are also defined, a netmail (????????.PKT)
  296.         is created each time a voice message is received or transmitted.
  297.  
  298.     DESTNAME <string>
  299.         If this, INBOUND and DESTADDR is defined in ANSW.CFG, a netmail
  300.         is created and addressed to.
  301.  
  302.     DESTADDR <FidoNet style address>
  303.         Must be defined to create announcing netmail.
  304.  
  305.     SRCNAME <string>
  306.         Used to form the 'From:' part of the announcing netmail.
  307.         Default is: "ANSW".
  308.  
  309.     SRCADDR <FidoNet style address>
  310.         Normally this is the address of local system. Defaults to DESTADDR.
  311.  
  312.     SUBJECTSENDVOICE <string or %>
  313.         Used in creation of announcing netmail on transmitted voice message.
  314.         If '%' is the first (or only) character, the filename of the sent voice
  315.         message (the first only, if more than one is sent) will be placed in
  316.         subject part of netmail.
  317.         Default is: "Announcement of outgoing voice message".
  318.  
  319.     SUBJECTRECVOICE <string or %>
  320.         Used in creation of announcing netmail on received voice message.
  321.         If '%' is the first (or only) character, the filename of the stored
  322.         voice message (the first only, if more than one is sent) will be
  323.         placed in subject part of netmail.
  324.         Default is: "Announcement of incoming voice message".
  325.  
  326.     FLAGDIR <path>
  327.         Path, were an activity flag can by deposited. ANSW looks, if it finds
  328.         <path>\NOANSW.FLG and if it finds it, it will terminate immediatly.
  329.         This filename is hardcoded, but could be patched in EXE or DLL.
  330.  
  331.     EXITSEM <semaphor name>
  332.         Semaphor file to force mailer (BinkleyTerm or Cantaloup) to exit with
  333.         error level. Should be either BTEXIT (for Binkley) or CLEXIT (for
  334.         Cantaloup).
  335.         In combination with TASK and ExitErrorLevel a semaphor file is created.
  336.  
  337.     EXITERRORLEVEL <level>
  338.         Errorlevel for mailer when forced to exit by semaphor.
  339.  
  340.     ENDGREETINGTONE <duration in ms> <frequence1> [<frequence2>]
  341.         Can be used instead of fix programmed 'EndGreetingTone' (1000 880 0).
  342.         Format in CFG is:
  343.  
  344.         EndGreetingTone 1000 880 0
  345.  
  346.         Multiple entries are supported (to play 'music'), use 0 for <frequence>
  347.         to simulate silence.
  348.  
  349.         This option is preliminary and may be altered in future to
  350.  
  351.         GENTONE <purpose> <duration> <frequence1> [<frequence2>]
  352.  
  353.     FRECCFG <cfg for FREC> [<commandline parameters for FREC>]
  354.         If this is configured, ANSW calls FREC directly if it detects a
  355.         fax calling tone.
  356.  
  357. 2) COMMANDLINE OPTIONS
  358.  
  359.     -rec
  360.         ANSW is set to recording mode. You can record any voice file by
  361.         calling your modem with a telephon set. Voice file is saved as
  362.         ANSWnnnn.ZVD in VoicePath.
  363.  
  364.     -Task<n>
  365.         Where <n> specifies the task number to be used. See also [TASK <n>]
  366.         and [COMMON] keywords in configuration file. If this parameter is
  367.         not used the common task will be used.
  368.  
  369.     -c<config file>
  370.         Default ANSW assumes the configuration file is named ANSW.CFG and
  371.         located in the current directory. The '-c' command line parameter
  372.         can be used to define an other path and file name.
  373.  
  374.     -o<voice file>
  375.         Input file for playback. More that one '-o' parameter is allowed in
  376.         a single command line. Wildcards (*, ?) also are allowed. Extention
  377.         ".SQC" is reserved for testing tone sequences.
  378.  
  379.     -p<com port handle>
  380.         If this parameter is used, ANSW assumes it is called by a mailer or
  381.         other front end. Note: The port handle is not the same as
  382.         the port number (e.g. COM1)!
  383.  
  384.     -f
  385.         Internally used to force callback in a command script.
  386.  
  387.  
  388.  
  389. -------------------------------------------------------------------------------
  390.     HISTORY OF ANSW:
  391. -------------------------------------------------------------------------------
  392.  
  393.     Version 1.02:
  394.         For some features (CallBack, Far Inquiry) a VOICE.LOG and VOICE.IDX
  395.         is invented. Limited support for userdefined 'tones'. As a test, only
  396.         EndGreetingTone is implemented. To test, generate a simple ASCII file
  397.         with extention .SQC, containing in each line a single tone command:
  398.  
  399.         <duration> <frequence1> <frequence2>
  400.  
  401.         PASSWORD_BAD
  402.  
  403.         500 1000 0
  404.         200 0 0
  405.         1000 800 0
  406.  
  407.         FAR_INQUIRY_PLAYBACK_INTRO
  408.  
  409.         200 880 0
  410.         200 749 0
  411.         200 605 0
  412.  
  413.         While it is really possible, to define 'dual tones', this should be
  414.         avoid because modem (or any line exchange) could interpret it as a
  415.         DTMF command!
  416.  
  417.         New Keywords:
  418.             RINGCNT
  419.             VOICELOG
  420.             VOICEIDX
  421.             ENDGREETINGTONE
  422.             FRECCFG
  423.  
  424.         Change in Keyword:
  425.             RECORDPATH --> VOICEPATH
  426.             CALLBACKEVENT ... now place for CallbackPassword
  427.  
  428.         Keywords not longer supported:
  429.             RINGCNTMAIL
  430.             RINGCNTNOMAIL
  431.             CALLBACKPWD
  432.  
  433.     Version 1.01:
  434.         Large parts of code (esp threadhandling, memoryallocation, exception-
  435.     handling and CFG/CMD-handling) was redesigned. All parts of code, which are
  436.     also in FSEND and FREC were put to FAXPROC, which is from now on a dynamic
  437.     link library (FAXPROC.DLL). Linking of C-runtime is never more statically,
  438.     instead, C-runtime is linked dynamically (at loadtime) for ANSW, FAXPROC and
  439.     IMGPROC. So, the overall amount of codesize was reduced. Some new keywords
  440.     in CFG are available:
  441.  
  442.         INBOUND
  443.         SUBJECTRECVOICE
  444.         SUBJECTSENDVOICE
  445.         DESTADDR
  446.         DESTNAME
  447.         SRCADDR
  448.         SRCNAME
  449.         INITFIFO
  450.  
  451.     Finally, the COM port open methode is now checked in FAXPROC. Only if COM
  452.     is opend in READWRITE and SHARE_DENYREADWRITE, work is continued! I hope
  453.     some problems (when called from a mailer, which uses a patched MAXCOMM to
  454.     open COM in SHARE_DENYNONE mode) are solved now. Also SIO.SYS in
  455.     'share mode' should never more work!
  456.  
  457.     Maybe some users will disagree, but 'sharing' a communication port is NOT
  458.     usefull on a multitasking environment! Each application MUST have unique
  459.     access to its own resources.
  460.  
  461.     Version 1.00:
  462.         Only internal test version and distributed only in a very early state.
  463.  
  464.     Previous versions of ANSW and ANSWER (both by Bernhard Seidl and me)
  465.         It was decided, to split the work of both Bernhard and me. While
  466.         Bernhard distributes his work as ANSWER, me application is named from
  467.         now on ANSW. Differences between ANSWER and ANSW are therefore possible
  468.         but CFG should (mostly) match for both products. Sourcecode of both
  469.         products is exchanged, so features of one will come soon in the other.
  470.         Bernhards ANSWER is primarly a PM application (for standalone use) and
  471.         ANSW is primarly designed as Feature-DLL for Cantaloup. There also
  472.         exists an ANSW.EXE, which may work as a voice and fax frontend and is
  473.         able to 'record' and 'playback' voice files.
  474.  
  475.     Please fell free to contact the autor:
  476.         FidoNet 2:310/14.59
  477.         Internet Harald.Pollack@OMV.CO.AT
  478.  
  479.  
  480.