Changes between Initial Version and Version 1 of KeepAlive


Ignore:
Timestamp:
03/12/10 12:44:51 (7 years ago)
Author:
alamaison
Comment:

Added keepalive API usage (originally by Simon Josefsson on the mailing list)

Legend:

Unmodified
Added
Removed
Modified
  • KeepAlive

    v1 v1  
     1= Sending keepalive requests = 
     2 
     3Sending keepalive's is off by default.  
     4 
     5The two APIs are: 
     6 
     7{{{ 
     8#!c 
     9/* 
     10 * libssh2_keepalive_config() 
     11 * 
     12 * Set how often keepalive messages should be sent.  WANT_REPLY 
     13 * indicates whether the keepalive messages should request a response 
     14 * from the server.  INTERVAL is number of seconds that can pass 
     15 * without any I/O, use 0 (the default) to disable keepalives.  To 
     16 * avoid some busy-loop corner-cases, if you specify an interval of 1 
     17 * it will be treated as 2. 
     18 * 
     19 * Note that non-blocking applications are responsible for sending the 
     20 * keepalive messages using libssh2_keepalive_send(). 
     21 */ 
     22LIBSSH2_API void libssh2_keepalive_config (LIBSSH2_SESSION *session, 
     23                                          int want_reply, 
     24                                          unsigned interval); 
     25 
     26/* 
     27 * libssh2_keepalive_send() 
     28 * 
     29 * Send a keepalive message if needed.  SECONDS_TO_NEXT indicates how 
     30 * many seconds you can sleep after this call before you need to call 
     31 * it again.  Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on 
     32 * I/O errors. 
     33 */ 
     34LIBSSH2_API int libssh2_keepalive_send (LIBSSH2_SESSION *session, 
     35                                       int *seconds_to_next); 
     36}}} 
     37If your application is blocking, to enable sending of keepalive 
     38requests, you just add a call like this: 
     39{{{ 
     40#!c 
     41 libssh2_keepalive_config (session, 1, 5); 
     42}}} 
     43This will send keepalive messages every 5 seconds, and the message that 
     44will be sent requests the server to respond to the message (because 
     45`want_reply=1`).  That's it! 
     46 
     47If your application is non-blocking, you need to first call 
     48`libssh2_keepalive_config` as above, but you also need to make sure you 
     49call `libssh2_keepalive_send` in your select loop and use its output as 
     50the maximum time to sleep in your select call.  For example: 
     51{{{ 
     52#!c 
     53 while (1) { 
     54     struct timeval tmout; 
     55     int err = libssh2_keepalive_send(sess, &tmout.tv_sec); 
     56     if (err) { 
     57         // ... 
     58     } 
     59     tmout.tv_usec = 0; 
     60     // set up fd_sets 
     61     ev = select(..., &tmout); 
     62     // handle events 
     63 } 
     64}}}