This file is part of Palantir documentation.
Copyright (c) 1998 Dim Zegebart, Russia, Moscow
zager@post.comstar.ru

APPS covered :
1. Wait string helper.
2. Wait delimiters helper.
3. AutoDialer helper.

                          Applications description.

                            1. Wait String Helper
This helper 'listen' input stream from a given comm port and sends msg
to client application then recieved data matches string defined by a client.

Helper API:

#define wstring_(_str_) ({(waiting_string*)(_str_);}) - just usefull wrapper.

int waiting_strings_init(void); - call this function before any related to
this helper ones.
Return value : 1 - OK, 0 - Failed.

waiting_string *comm_port_waitstring_add(device *port,dz_app *app,char *s);
Add string 's' to list of processed strings.
Parameters -
device *port - port on which helper waits string.
dz_app *app - Palantir application to which helper sends msg
E_COMM_STRING then string recieved.
char *s - string to wait
Return value : pointer to waiting_string structure (see below), NULL - failed
Example : comm_port_waitstring_add(com2,modem_app,"BUSY");

void comm_port_waitstring_remove(device *port,dz_app *app,char *s);
Remove string from list previously added by comm_port_waitstring_add();
Parameters -
device *port - port on which string was installed.
dz_app *app - Palantir application.
char *s - string to remove.
Example : comm_port_waitstring_remove(com2,modem_app,"BUSY");

Message from this helper :
E_COMM_STRING - generated by 'Wait string application'
int p1 - (waiting_string*)pointer to the data structure 'waiting_string' :
typedef struct
{ dz_app *app;//application which waits for string
  device *dev;//port
  int status;//0 - active string; 1 - passive string (not processed)
  char *string;//waited string
  char *string_buf;//runtime buffer
  int string_len;
  int string_buf_len;
} waiting_string;
int p2 - just shortcat pointer to the p1->dev field. Comm port on which
string was recieved.

Note : then string recieved the field 'status' becomes 1, so string is
inactive. If you want string to be active just set this field to 0.

See also : src/dzadial.c for exaple of using this helper

                          2. Wait Delemiters Helper

This helper 'listen' input stream from a given comm port and sends msg
to client application then recieved data enclosed by pair of delimiter
strings defined by a client.

Helper API :

#define wdelimiter_(_str_) ({(waiting_delimiter*)(_str_);}) - just usefull
wrapper.

int waiting_delimiter_init(void); - call this function before any related to
this helper ones.
Return value : 1 - OK, 0 - Failed.

waiting_delimiter
*comm_port_waitdelimiters_add(device *dev,dz_app *app,char *s1,char *s2);
Parameters -
device *port - port on which helper waits data.
dz_app *app - Palantir application to which helper sends msg
E_COMM_DELIMITERS then pair of delimiter strings recieved.
char *s1 - open delimiter string
char *s2 - close delimiter string
Return value : pointer to waiting_delimiter structure (see below),
NULL - failed
Example : comm_port_waitdelimiter_add(com2,modem_app,"START","STOP");

void
comm_port_waitdelimiter_remove(device *port,dz_app *app,char *s1,char *s2);
Remove delimiters from list previously added by comm_port_waitstring_add();
Parameters -
device *port - port on which string was installed.
dz_app *app - Palantir application.
char *s1,char *s2 - delimiters to remove
Example : comm_port_waitdelimiters_remove(com2,modem_app,"START","STOP");

Message from this helper :
E_COMM_DELIMITERS- generated by 'Wait delimiters application'
int p1 - (waiting_delimiter*) pointer to the data structure
         'waiting_delimiter' :
typedef struct
{ dz_app *app;//application wich wait for delimiter
  device *dev;//port
  int status;//0 - active string; 1 - passive string (not processed)
  char *delimiter1;//waited delimiter1
  char *delimiter1_buf;//runtime buffer
  int delimiter1_len;
  int delimiter1_buf_len;
  char *delimiter2;//waited delimiter2
  char *delimiter2_buf;//runtime buffer
  int delimiter2_len;
  int delimiter2_buf_len;
  buf_status_type buffer_status;
  int buffer_len;
  int buffer_max_len;
  char *buffer; //run-time buffer for delimited text
  char *rcv_buffer; //actual data recieved
} waiting_delimiter;
int p2 - just shortcat pointer to the p1->dev field. Comm port on which
data was recieved.
Note : then data recieved the field 'status' becomes 1, so this structure is
inactive. If you want structure to be active just set this field to 0.
You had to free(rcv_buffer) after using.

See also : src/dzadial.c for exaple of using this helper

                             3. AutoDialer Helper

This helper trys to dial numbers stored in list and sends msg E_COMM_CONNECT
then connection established.
Helper API :

int autodialer_init(void); - call this function before any related to
this helper ones.
Return value : 1 - OK, 0 - Failed.

dialing_string *comm_port_dialstring_add(device *port,dz_app *app,char *s);
Add dialing number to the dialed list.
Parameters -
device *port - port on which helper will dial.
dz_app *app - Palantir application to which dialer'll send msg
E_DIALER_CONNECT.
char *s - call command.
Example :
comm_port_dialstring_add(com2,modem_app,"atdt6009097");
Return value : pointer to structure dialing_string, NULL - failed
typedef struct
{ dz_app *app;//application
  device *dev;//port
  int status;// 0 - active number, 1 - inactive number
  char call_command[25];
} dialing_string;

Message from/to this helper :
E_DIALER_START - start dialing. Send this msg to adial_app then you
want to dial list
p1 - 0 (unused)
p2 - device *com. Pointer to comm port on which to dial.
Example :
 comm_port_dialstring_add(com2,app,CMD1);
 comm_port_dialstring_add(com2,app,CMD2);
 comm_port_dialstring_add(com2,app,CMD3);
 app_msg_put(adial_app,E_DIALER_START,0,(int)com2);

E_DIALER_CONNECT - adial_app sends this msg then connection established
p1 - dialing_string *cmd. Pointer to number on which connection established
p2 - char *s, connection string.
Example :
case E_DIALER_CONNECT :
 printf("%s : Connected %s\n",dstring_(p2)->call_command,(char*)p1);
 break;
"atdt96009797 : Connected 2400/V42BIS/LAPM"

E_DIALER_FINISH - adial_app sends this msg then all numbers in list were
proccessed and all connections were established
p1 - 0 (unused)
p2 - device *com, comm port on which dialing finished
Example :
case E_DIALER_FINISHED :
 printf("\nFinished.\n");
 break;

E_DIALER_CONTINUE- send this msg to adial_app to proccess next number in list
p1 - dz_app *app, current app
p2 -device *com, comm port
Example :
case E_DIALER_CONNECT :
 printf("%s : Connected %s\n",dstring_(p2)->call_command,(char*)p1);
 //you can do now communication on com2
 //we just dial next number.
 //dial next number
 app_msg_put(adial_app,E_DIALER_CONTINUE,(int)app,(int)com2);

void comm_port_dialstring_remove(device *port,dz_app *app,char *s); -
Remove calling command from dialing list.
Parameters -
device *port - port.
dz_app *app - Palantir application.
char *s - call command.
Example :
comm_port_dialstring_remove(com2,modem_app,"atdt6009797");

See also : /palantir/pdemo/dialer.c