typedef struct al_command { 
   int    command; 
   char * str_arg; 
   word   num_arg; 
} al_command; 

int xn_scriptlogin(int          iface_no, 
                   al_command * script, 
                   int          num_commands, 
                   char       * term_str);

Parameters

iface_no

Interface number returned by xn_attach.

script

Pointer to script to execute. See below for details.

num_commands

Number of script commands in *script.

term_str

Line termination string for sending modem commands (usually "\r").

return value

Returns 0 if successful, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Section Error Codes further describes each error.

Possible values for this function are:

Value	Meaning
EBADIFACE	Invalid interface number (RTIP-32 specific).
EMODEMBADRESP	Unexpected response from modem (RTIP-32 specific).
EMODEMSENDFAILED	Sending character to modem failed (RTIP-32 specific).
ENOTINITIALIZED	RTIP-32 has not been initialized (xn_rtip_init has not been called).

This function automates login to a remote server over a Hayes compatible modem. The login procedure will be determined by the commands given in the table pointed to by script. The scripting language used to automate logins consists of a table with an arbitrary number of entries, each of which represents a command. The table is of data type struct al_command. In each entry, there are three fields: integer command which determines what command is to be used, string str_arg which acts as an argument to the command and integer num_arg which acts as another argument to the command. Some commands require both the string and the numeric arguments, some require one or the other, and some require neither. If the string argument is not needed, it can be set to NULL, and if the integer argument is not needed, it should just be set to zero.

Commands

AL_SEND

Sends the string pointed to by str_arg to the modem.

AL_SLEEP

Waits for num_arg seconds.

AL_NOOP

No Operation.

AL_WAITLIST

AL_WAITLIST is the same as AL_WAIT except several strings may be tested simultaneously. To use AL_WAITLIST, put several contiguous AL_WAITLIST entries in the table terminated by an AL_BRKERR. Each AL_WAITLIST in the list can be optionally followed by an AL_BRKFND. If any of the strings are received, the script continues to the next command that is not AL_WAITLIST, AL_BRKERR or AL_BRKFND. If none of the strings are received and if the next command is a AL_BRKERR, execution continues at the AL_LABEL entry with the name specified by str_arg. The timeout value for the AL_WAITLIST command must be placed in the first entry. If you need to implement two separate but contiguous AL_WAITLIST procedures, place an AL_NOOP command between them. The AL_NOOP command does nothing. It is provided as a way to separate AL_WAITLIST procedures.

For example, the following script would wait up to 60 seconds for the strings "CONNECT," "BUSY" or "NO DIAL." If none of the 3 strings comes in, the script would perform a goto to the AL_LABEL with "error4:"

{AL_WAITLIST, "CONNECT", 60}, 
{AL_WAITLIST, "BUSY", 0}, 
{AL_WAITLIST, "NO DIAL", 0}, 
{AL_BRKERR,   "error4", 0}, 
... 
{AL_LABEL,    "error4", 0}, 
{AL_PRINT,    "AL: Not connecting", 0},

In the example below, the script is modified such that if "BUSY" is received, the script will go to the "error5" label. If "NO DIAL" is received, the script will go to the "error6" label. If none of the 3 are received, the script will go to the "error4" label. If "CONNECT" is received, the script will go to the command after the AL_BRKERR command:

{AL_WAITLIST, "CONNECT", 60}, 
{AL_WAITLIST, "BUSY", 0}, 
{AL_BRKFND,   "error5", 0}, 
{AL_WAITLIST, "NO DIAL", 0}, 
{AL_BRKFND,   "error6", 0}, 
{AL_BRKERR,   "error4", 0}, 
... 
{AL_LABEL,    "error4", 0}, 
{AL_PRINT,    "AL: Not connecting", 0},

AL_WAIT

Waits num_args seconds for a string str_arg to come in from the modem.

AL_BRKERR

Acts as a conditional goto statement. Upon error, it will transfer control to the instruction following the label specified in str_arg. Whether or not AL_BRKERR will cause a jump is determined by the result of the previous AL_WAIT or AL_WAITLIST commands. If the string that AL_WAIT, or one of the strings that AL_WAITLIST was waiting for, did not come in, this is considered an error, and AL_BRKERR will cause a jump.

AL_BRKFND

Acts as a conditional goto statement. Upon finding the string in the previous AL_WAIT or AL_WAITLIST command, will jump to the instruction following the label specified in str_arg. Whether or not AL_BRKFND will cause a jump is determined by the result of the previous AL_WAIT command or AL_WAITLIST command. If the string that AL_WAIT or AL_WAITLIST was waiting for came in, then AL_BRKFND will cause a jump.

AL_LABEL

Sets up a label for use by AL_BRKERR. The label is specified in str_arg.

AL_PRINT

Prints out str_arg using callback cb_wr_screen_string_fnc.

AL_END

Terminates execution of the script and returns success.

AL_ENDERR

Terminates execution of the script and returns failure.

Demo program PPPDemo contains two small scripts to login to Windows 2000/XP by Direct Cable Connection.

Here is a more elaborate example script:

al_command MyScript[] = 
{ 
   {AL_PRINT,    "AL: Logging in...", 0}, 
   {AL_SEND,     "ATM1L1", 0}, 
   {AL_WAIT,     "OK", 5}, 
   {AL_BRKERR,   "error1", 0}, 
   {AL_SEND,     "ATDT9526100", 0}, 
   {AL_WAITLIST, "CONNECT", 60}, 
   {AL_WAITLIST, "BUSY", 0}, 
   {AL_BRKFND,   "error5", 0}, 
   {AL_WAITLIST, "NO DIAL", 0}, 
   {AL_BRKFND,   "error6", 0}, 
   {AL_BRKERR,   "error4", 0}, 
   {AL_WAITLIST, "ogin:", 40}, 
   {AL_WAITLIST, "sername:", 0}, 
   {AL_BRKERR,   "error2", 0}, 
   {AL_SEND,     "my name", 0},      // username goes here 
   {AL_WAIT,     "ssword", 10}, 
   {AL_BRKERR,   "error3", 0}, 
   {AL_SEND,     "my password", 0},  // password goes here 
   {AL_END,      "", 0}, 
   {AL_LABEL,    "error1", 0}, 
   {AL_PRINT,    "AL: Modem not responding", 0}, 
   {AL_ENDERR,   "", 0}, 
   {AL_LABEL,    "error2", 0}, 
   {AL_PRINT,    "AL: Login failed.", 0}, 
   {AL_ENDERR,   "", 0}, 
   {AL_LABEL,    "error3", 0}, 
   {AL_PRINT,    "AL: No password prompt", 0}, 
   {AL_ENDERR,   "", 0}, 
   {AL_LABEL,    "error4", 0}, 
   {AL_PRINT,    "AL: Not connecting", 0}, 
   {AL_ENDERR,   "", 0}, 
   {AL_LABEL,    "error5", 0}, 
   {AL_PRINT,    "AL: Busy", 0}, 
   {AL_ENDERR,   "", 0}, 
   {AL_LABEL,    "error6", 0}, 
   {AL_PRINT,    "AL: No dial tone", 0}, 
   {AL_ENDERR,   "", 0} 
};  

Result = xn_scriptlogin(iface_no, 
                        Myscript, 
                        sizeof(MyScript) / sizeof(MyScript[0]), 
                        "\r");

The script prints out "AL: Logging in..." as soon as it starts. Then it sends the initialization string "ATM1L1\r" to the modem. The "\r" represents a line feed, term_str parameter and must be present. Then it waits 5 seconds for the string "OK" to come in from the modem. If the string fails to appear within 5 seconds, the program jumps to the instruction following "error1," which causes the string "AL: Modem not responding" to be printed on the screen. If "OK" does come in within 5 seconds, the program sends "ATDT9526100\r" to the modem, which causes the modem to dial the number for a local internet access provider. The program then waits 45 seconds for the string "ogin:" to come in over the modem. If the string fails to come in, the program jumps to "error2," which causes it to print out "AL: Login failed." Otherwise, the program sends the specified username out over the modem. The program then waits 10 seconds for the string "ssword:" to come in, and jumps to "error3" if it does not. Otherwise, the program sends the password to the remote side and terminates via AL_END.

Left Extended RTIP-32 API

Function xn_hangup

Down Function xn_autoip