SDK.TXT
20SEP94

This document is for NLM developers only; no user information is contained herein.

TCPIP.NLM version M have a new option in the BSD Socket and TLI API.  
(TCP188.EXE contains version M)

KeepAlive Option using the BSD Socket API
-----------------------------------------
Applications using the BSD Socket application programming interface can
toggle the use of the TCP KeepAlive timer and set the timer value using the
setsockopt function.

By default, TCPIP.NLM does not send KeepAlives on connections using the BSD
Socket API.

setsockopt
  The setsockopt function establishes the parameters for socket operation.

Syntax
   #include <sys/types.h>
   #include <sys/socket.h>

   setsockopt( int s, int level, int optname, char *optval, int optlen);

      s     (Input) Identifies the socket file handle of a socket for  
            which parameters are to be established.

      level    (Input) SOL_SOCKET

      optname  (Input) SO_KEEPALIVE

      optval   (Input) Points to an option value. The SO_KEEPALIVE option  

               value is an integer indicating the time-out value in        

               minutes.  If the value is zero, the KeepAlive timer is      

               disabled. If the value is between 1 and 4, inclusive, the   

               timeout value is set to two hours.

               Formerly this value was used only to toggle KeepAlive on    

               (value != 0) or off (optval == 0).

KeepAlive Option using the TLI API
----------------------------------
Applications using the TLI application programming interface can toggle the
use of the TCP KeepAlive timer and set the timer value using the t_optmgmt
function.

By default, TCPIP.NLM sends KeepAlives at 2 hour intervals on connections
using the TLI API.  Previous versions of TCP for NetWare did not support
the t_optmgmt function.

Syntax
   #include <tiuser.h>
   int t_optmgmt ( int fh, struct t_optmgmt *req, struct t_optmgmt *ret )

       fh   (Input)  Identifies a bound transport endpoint.

       req  (Input)  Points to a structure containing protocol options.

       ret  (Output) Receives the options and flag values.

Remarks
The req and ret arguments point to a t_optmgmt structure containing the
following members:

   struct netbuf opt;
   long flags;

The opt field identifies protocol options and the flags field specifies the
action to take with those options.
The T_NEGOTIATE flag must be set to change the KeepAlive timer. The T_CHECK
and T_DEFAULT flags are not supported.

  The netbuf structure contains the following members:
      unsigned int maxlen;
      unsigned int len;
      char *buf;

      maxlen   (Input)  Has no meaning for the req argument.

               (Output) Specifies the maximum size of the options buffer.

      len      (Input)  Specifies the number of bytes in the options

               (Output) Specifies the number of bytes returned.

      buf      (Input)  Points to the options buffer.  See t_opthdr
               defined below.

               (Output) Points to the buffer where the options are to be    
               placed.  See t_opthdr defined below.


The following structures must be defined by the application.

The t_opthdr structure defines the option to be negotiated and should be   
equivalent to the structure shown:

        struct t_opthdr
        {
                unsigned long len;
                unsigned long level;
                unsigned long name;
                unsigned long status;
                struct t_kpalive kp_val;
        };

        len      length of t_opthdr

        level    INET_TCP

                 The following define is required:
                 #define INET_TCP  0x06

        name     TCP_KEEPALIVE

                 The following define is required:
                 #define TCP_KEEPALIVE 0x08

        status   T_SUCCESS or T_FAILURE indicates the status of
                 the negotiation.

        kp_val   The t_kpalive structure defines the state of the
                 KeepAlive timer, and the timer interval.
                 It should be equivalent to the structure shown:


        struct   t_kpalive {
                             long kp_onoff;
                             long kp_timeout;
                           }
        kp_onoff     0 - disable KeepAlives
                     1 - enable KeepAlives

        kp_timeout   The timer value in minutes. If the
                     value is less than 5, the timeout value
                     is set to two hours.

TCP/IP's Behavior
-----------------
Once the KeepAlive timer expires, TCP/IP will send a KeepAlive packet to
the TCP peer.  If the TCP peer responds, the timer will be reset.  If
the TCP peer does not respond within the current estimate of the
connection's round trip time, TCP/IP will retransmit the KeepAlive packet.
TCP/IP will retry according to its standard retry algorithm.  An
exponential backoff algorithm is used to calculate an increasing round trip
time estimate for each retry.  This means that after the KeepAlive timer
has expired, the connection will not be closed, until TCP/IP has exhausted
its normal retries.