
INTRODUCTION

   This file describes how other programs can remote control the STiK Dialer. 
   The Dialer can be requested to either dial, or hangup, a connection. The 
   requesting program (the requester) is told about success or the error that 
   occured. During remote controled dialing or hangup no user interaction with 
   the Dialer is required, i.e. no alerts will pop up. The requester basically 
   sends a message to the Dialer that tells the Dialer about the script file 
   to be used, and the maximum number of attempts that the Dailer is allowed 
   to do. A success or an error message is returned, the error message contains 
   a code that identifies the error. Requesting a hangup works likewise, 
   however, no parameters are to be passed in that case.


SUPPORT

   Right now, STiK is not capable of supporting a lan. This means that you 
   cannot network between several computers via STiK. The current STiK version
   supports only one port, that usually will go across a modem and a telephone 
   line, connecting your host to the Internet. As a consequence, the requester 
   will always run on the same machine as the Dialer. Thus AES messages are an 
   easy to use means for the requester Dialer protocol. This is the way the 
   protocol is implemented now.

   Later versions of STiK will support lans, i.e. multiple ports at once. As a 
   consequence the requester might run on a different machine than the Dialer. 
   AES messages will not suffice anymore in that case. So later versions of 
   the Dialer will react to UDP packets carrying the protocol. This is be a 
   more general way to do the job, so the AES messages version will be obsolete 
   then. However, current STiK versions also have problems connecting processes 
   running on the same machine, via either UDP or TCP. Thus we need that kludge
   using AES messages now and for the near future. But it is important to note 
   that the AES messages interface will one day not be supported anymore, and 
   must be replaced by the UDP interface in any client that remote controls the 
   Dialer. To simplify this, the protocol will stay the same, even the length 
   of the messages, only the means for transporting the messages changes.


PROTOCOL

   Any client that wishes to remote control the Dialer first calls the STiK 
   function getvstr() to find out the value of the configuration variable 
   "DIALER". The resulting string is either the application name of the 
   Dialer (that is the name of the binary, without extension) if it does 
   not contain any full stops, or, if there are full stops, either the IP 
   address or the fully qualified domain name of the machine the Dialer is 
   running on. In case an application name is found, AES messages are to be 
   used for the protocol. Otherwise a UDP connection to the referenced 
   machine must be opened. For AES messages, appl_find() must be used now 
   to find out the AES process identification of the Dialer, to be used for 
   the appl_write() call for sending the request.

   Each message consists of 16 bytes, or 8 sixteen bit integers. Just like 
   any AES message, the first integer (array index 0) determines the meaning 
   of the message, the second integer (index 1) is the AES process identifier
   of the sender (the requester). The third entry (index 2) is always zero.
   The meaning (index 0) can be either IP_DIAL_REQUEST or IP_DIAL_HANGUP.
   For IP_DIAL_REQUEST, entries (index) 3 and 4 form a 32 bit pointer to the 
   name of the script file that is to be used. Entry (index) 5 contains the 
   maximum number of redials. If the entry 0 is IP_DIAL_HANGUP, no other 
   parameters are required, thus entries (index) 3 to 7 should be set zero.

   After sending the message the requester should anticipate messages from 
   the Dialer. These can be either IP_DIAL_DONE or IP_DIAL_ERROR. In case 
   of IP_DIAL_ERROR the fourth entry (index 3) of the response contains the 
   actual error code. The error codes can be
   
        for  IP_DIAL_REQUEST  :
               IP_IN_PROGRESS       The Dialer is already dialing.
               IP_IS_CONNECTED      The Dialer already connected this port
                                    before.
               IP_SCR_NOT_FOUND     The Dialer had problems loading the 
                                    script file.
               IP_PORT_LOCKED       Port could not be opened, probably 
                                    because another program uses it.
               IP_MAX_EXCEEDED      The specified maximum number of redials 
                                    have been carried out.
               IP_FATAL_PROBLEM     The Dialer got a fatal error response
                                    from the modem.
               IP_USER_ABORT        The user aborted the dial process.
               IP_OPEN_FAILED       STiK refuses to accept the connection.

        for  IP_DIAL_HANGUP  :
               IP_IN_PROGRESS       During the dial process hangup requests
                                    cannot be processed.
               IP_OPEN_FAILED       Due to some strange reason the port
                                    could not be reopened.

   Note that if IP_OPEN_FAILED is responded to IP_DIAL_REQUEST, your modem
   is still off hook ! Thus the telephone company will start to charge money 
   unless IP_DIAL_HANGUP is send ! For all the other error codes the modem 
   is on hook afterwards. The same holds for any response to IP_DIAL_HANGUP.


EXAMPLE

   For an example look at the Pure C sample code DIALCTRL.C. It contains 
   a simple program that just implements the above discussed protocol for 
   requesting a dialup.


AUTHOR

   Any further questions or good ideas for extensions should be directed 
   to :

   Peter Rottengatter
   Kriegerstrasse 18
   30161 Hannover
   Germany

   perot@pallas.amp.uni-hannover.de

