home *** CD-ROM | disk | FTP | other *** search
/ Network Support Encyclopedia 96-1 / novell-nsepro-1996-1-cd2.iso / download / netware / tcp188.exe / SDK.TXT < prev    next >
Text File  |  1994-09-20  |  5KB  |  155 lines
  1. SDK.TXT
  2. 20SEP94
  3.  
  4. This document is for NLM developers only; no user information is contained herein.
  5.  
  6. TCPIP.NLM version M have a new option in the BSD Socket and TLI API.  
  7. (TCP188.EXE contains version M)
  8.  
  9. KeepAlive Option using the BSD Socket API
  10. -----------------------------------------
  11. Applications using the BSD Socket application programming interface can
  12. toggle the use of the TCP KeepAlive timer and set the timer value using the
  13. setsockopt function.
  14.  
  15. By default, TCPIP.NLM does not send KeepAlives on connections using the BSD
  16. Socket API.
  17.  
  18. setsockopt
  19.   The setsockopt function establishes the parameters for socket operation.
  20.  
  21. Syntax
  22.    #include <sys/types.h>
  23.    #include <sys/socket.h>
  24.  
  25.    setsockopt( int s, int level, int optname, char *optval, int optlen);
  26.  
  27.       s     (Input) Identifies the socket file handle of a socket for  
  28.             which parameters are to be established.
  29.  
  30.       level    (Input) SOL_SOCKET
  31.  
  32.       optname  (Input) SO_KEEPALIVE
  33.  
  34.       optval   (Input) Points to an option value. The SO_KEEPALIVE option  
  35.  
  36.                value is an integer indicating the time-out value in        
  37.  
  38.                minutes.  If the value is zero, the KeepAlive timer is      
  39.  
  40.                disabled. If the value is between 1 and 4, inclusive, the   
  41.  
  42.                timeout value is set to two hours.
  43.  
  44.                Formerly this value was used only to toggle KeepAlive on    
  45.  
  46.                (value != 0) or off (optval == 0).
  47.  
  48. KeepAlive Option using the TLI API
  49. ----------------------------------
  50. Applications using the TLI application programming interface can toggle the
  51. use of the TCP KeepAlive timer and set the timer value using the t_optmgmt
  52. function.
  53.  
  54. By default, TCPIP.NLM sends KeepAlives at 2 hour intervals on connections
  55. using the TLI API.  Previous versions of TCP for NetWare did not support
  56. the t_optmgmt function.
  57.  
  58. Syntax
  59.    #include <tiuser.h>
  60.    int t_optmgmt ( int fh, struct t_optmgmt *req, struct t_optmgmt *ret )
  61.  
  62.        fh   (Input)  Identifies a bound transport endpoint.
  63.  
  64.        req  (Input)  Points to a structure containing protocol options.
  65.  
  66.        ret  (Output) Receives the options and flag values.
  67.  
  68. Remarks
  69. The req and ret arguments point to a t_optmgmt structure containing the
  70. following members:
  71.  
  72.    struct netbuf opt;
  73.    long flags;
  74.  
  75. The opt field identifies protocol options and the flags field specifies the
  76. action to take with those options.
  77. The T_NEGOTIATE flag must be set to change the KeepAlive timer. The T_CHECK
  78. and T_DEFAULT flags are not supported.
  79.  
  80.   The netbuf structure contains the following members:
  81.       unsigned int maxlen;
  82.       unsigned int len;
  83.       char *buf;
  84.  
  85.       maxlen   (Input)  Has no meaning for the req argument.
  86.  
  87.                (Output) Specifies the maximum size of the options buffer.
  88.  
  89.       len      (Input)  Specifies the number of bytes in the options
  90.  
  91.                (Output) Specifies the number of bytes returned.
  92.  
  93.       buf      (Input)  Points to the options buffer.  See t_opthdr
  94.                defined below.
  95.  
  96.                (Output) Points to the buffer where the options are to be    
  97.                placed.  See t_opthdr defined below.
  98.  
  99.  
  100. The following structures must be defined by the application.
  101.  
  102. The t_opthdr structure defines the option to be negotiated and should be   
  103. equivalent to the structure shown:
  104.  
  105.         struct t_opthdr
  106.         {
  107.                 unsigned long len;
  108.                 unsigned long level;
  109.                 unsigned long name;
  110.                 unsigned long status;
  111.                 struct t_kpalive kp_val;
  112.         };
  113.  
  114.         len      length of t_opthdr
  115.  
  116.         level    INET_TCP
  117.  
  118.                  The following define is required:
  119.                  #define INET_TCP  0x06
  120.  
  121.         name     TCP_KEEPALIVE
  122.  
  123.                  The following define is required:
  124.                  #define TCP_KEEPALIVE 0x08
  125.  
  126.         status   T_SUCCESS or T_FAILURE indicates the status of
  127.                  the negotiation.
  128.  
  129.         kp_val   The t_kpalive structure defines the state of the
  130.                  KeepAlive timer, and the timer interval.
  131.                  It should be equivalent to the structure shown:
  132.  
  133.  
  134.         struct   t_kpalive {
  135.                              long kp_onoff;
  136.                              long kp_timeout;
  137.                            }
  138.         kp_onoff     0 - disable KeepAlives
  139.                      1 - enable KeepAlives
  140.  
  141.         kp_timeout   The timer value in minutes. If the
  142.                      value is less than 5, the timeout value
  143.                      is set to two hours.
  144.  
  145. TCP/IP's Behavior
  146. -----------------
  147. Once the KeepAlive timer expires, TCP/IP will send a KeepAlive packet to
  148. the TCP peer.  If the TCP peer responds, the timer will be reset.  If
  149. the TCP peer does not respond within the current estimate of the
  150. connection's round trip time, TCP/IP will retransmit the KeepAlive packet.
  151. TCP/IP will retry according to its standard retry algorithm.  An
  152. exponential backoff algorithm is used to calculate an increasing round trip
  153. time estimate for each retry.  This means that after the KeepAlive timer
  154. has expired, the connection will not be closed, until TCP/IP has exhausted
  155. its normal retries.