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