modem_script()

Run a script on a device

Synopsis:

#include <sys/modem.h>

int modem_script( int fd,
                  struct modem_script* table,
                  speed_t* baud,
                  void (*io)( 
                        char* progress,
                        char* in,
                        char* out ),
                  int (*cancel)(void) );

Library:

libc

Description:

The modem_script() function runs the script table on the device associated with the file descriptor fd. The script implements a simple state machine which emits strings and waits for responses.

Each string emitted and received is passed to the function io() as follows:

This allows an application to setup a callback which can display the scripts interaction in a status window.

If a cancel function is provided, it's called once each newquiet 1/10 of a second while waiting for input. If this function returns a nonzero value, the read returns immediately with -1 and errno is set to ETIMEDOUT. The cancel function can be used as a callback in a graphical dialer which needs to support a cancel button to stop a script.

The table is passed as an array of structures containing the following members:

The following example clarifies the operation of the script:

/*
 curstate curflags newstate newflags newtimeout 
 newquiet retvalue pattern response
*/

struct modem_script table[] ={
  {1, 0,            1, 0,              2,  5, 0,
   NULL,              "ATZ\\r\\P0a"},
  {1, 0,            2, 0,              30, 5, 0,
   "*ok*",            "ATDT5910934"},
  {2, MODEM_BAUD,   3, MODEM_LASTLINE, 10, 5, 0,
   "*connect*",       NULL},
  {3, 0,            4, 0,              8,  5, 0,
   "*login:*",        "guest"},
  {4, MODEM_NOECHO, 5, 0,              15, 5, 0,
   "*password:*",     "xxxx"},
  {5, 0,            0, 0,              0,  0, 0,
   "*$ *",            NULL},
  {0, 0,            0, 0,              0,  0, 1,
   "*no carrier*",    NULL},
  {0, 0,            0, 0,              0,  0, 2,
   "*no answer*",     NULL},
  {0, 0,            0, 0,              0,  0, 3,
   "*no dialtone*",   NULL},
  {0, 0,            0, 0,              0,  0, 4,
   "*busy*",          NULL},
  { NULL }
};

When this script is passed to modem_script(), the current state is set to 1 and the output will be ATZ (the response in the first array element).

While in any state, modem_script() waits for input matching it against the current state or the wildcard state of 0.

State 1

State 2

State 3

State 4

State 5

If the flag MODEM_BAUD is set for a state then any number embedded in a matching response is extracted and assigned as a number to the baud parameter.

If the flag MODEM_NOECHO isn't set for a state then all emitted strings are also set to the passed io function as (*io)(0, 0, response).

Returns:

The retvalue member of a script entry which terminates the script. This will always be a positive number. If modem_script fails, -1 is returned (errno is set).

Errors:

EAGAIN

The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed in the write operation.

EBADF

The file descriptor, fildes, isn't a valid file descriptor open for writing.

EINTR

The write operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file does not report partial transfers.

EIO

A physical I/O error occurred. The precise meaning is device-dependent.

EPIPE

An attempt was made to write to a pipe (or FIFO) that isn't open for reading by any process. A SIGPIPE signal is also sent to the process.

Classification:

QNX 6

Caveats:

Depending on what you do in your cancel function, modem_read() may or not be signal handler or thread-safe.

See also:

modem_open(), modem_read(), modem_write()