#ident "@(#)README 1.10 99/04/19 SMI"
#
#       Copyright 1997 Sun Microsystems, Inc. All Rights Reserved
#
#	README file for the new FTAM 8.0.3 API for Siemens
#

------------------
FTAM 8.0.3 New API
------------------


Type : ftiCallbackTp
--------------------

typedef int (*ftiCallbackTp) (long, long, long, int);

A) Description

The fti_CallbackTp type represents a pointer to the callback function.

The input parameters of this callback function are:
- The number of bytes transferred. 
- The number of records transferred for FTAM-1, FTAM-2 document types or the 
  number of binary blocks for FTAM-3 document type.
- The actual elapsed time that passed since the last invocation of the callback 
  function, expressed in seconds.
- The state of the connection (aborted because of a time-out or not). 
  FTITIMEOUT (=1) inactivity time-out occured, FTINTIMEOUT otherwise.

It should return :
1 to notify that the file transfer should be stopped and the connection broken, 
2 to notify that the file transfer should be stopped and the connection kept,
0 otherwise.


			- o -


Function: fti_registerCallback()
--------------------------------

int fti_registerCallback(flaip, callbkp, eltime, fesrp)
ftilaiT	*flaip;
ftiCallbackTp callbkp;
long eltime;	 
ftiesrT	*fesrp;

A) Description

The fti_registerCallback() function is used to register a user function as the 
function to be called periodically. The granularity is determined by the eltime 
parameter. 


B) Arguments

- flaip: Local Association Identifier. This input parameter identifies the FTAM association. 
  If the flaip does not correspond to an open association the function returns -1 and the error code 
  in fesrp is FTIERCNE (Connection Not Established). If null the function returns -1 and the error code 
  in fesrp is FTIERIPA (invalid parameter).

- callbkp: The pointer to the user function to be called periodically. If null, if a registered 
  callback function exists it will be deregistered.

- eltime: Elapsed time. It determines the time interval between calls to the function of type 
  ftiCallbackT. It is expressed in seconds. If eltime is equal to 0 the callback will be called only in 
  case of an inactivity time out. If eltime is less then 0 the function returns -1 and the error code 
  in fesrp is FTIERIPA (invalid parameter).

- fesrp: Pointer to an area to receive the Execution Status Report. 


C) Error codes 

The following error codes are returned in the Execution Status Report as 
appropriate:

- FTIERIPA invalid parameter

- FTIERCNA connection not established


D) Returns

The function fti_registerCallback() returns zero if successful and a non-zero 
value if unsuccessful.


			- o -


Function: fti_setInactivityTimeout()
------------------------------------

int fti_setInactivityTimeout(flaip, timeout, fesrp)
ftilaiT *flaip;
long timeout;	 
ftiesrT *fesrp;


A) Description

The fti_setInactivityTimeout() function is used to determine the maximum 
interval of inactivity during the transfer. Once the timeout expires, the FTAM 
connection should be closed. If a callback function has not been defined earlier 
the function returns -1 and the error code in fesrp is FTIERIPA (invalid parameter).


B) Arguments

- flaip: Local Association Identifier. This input parameter identifies the FTAM association.
  If the flaip does not correspond to an open	 association the function returns -1 and the error code 
  in fesrp is FTIERCNE (Connection Not Established). If null the function returns -1 and the error code 
  in fesrp is FTIERIPA (invalid parameter).

- timeout: Inactivity time-out. It is expressed in seconds. If eltime is equal to 0 FTAM conserves its 
  default time out (=10min). If eltime is less then 0 the function returns -1 and the error code 
  in fesrp is FTIERIPA (invalid parameter).

- fesrp: Pointer to an area to receive the Execution Status Report.


C) Error codes

The following error codes are returned in the Execution Status Report as 
appropriate:

FTIERIPA invalid parameter

FTIERCNA connection not established


D) Returns

The function fti_setInactivityTimeout() returns zero if successful and a non-
zero value if unsuccessful.
