stun/usages/timer.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2008-2009 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6  * (C) 2007-2009 Nokia Corporation. All rights reserved.
   7  *  Contact: Rémi Denis-Courmont
   8  *
   9  * The contents of this file are subject to the Mozilla Public License Version
  10  * 1.1 (the "License"); you may not use this file except in compliance with
  11  * the License. You may obtain a copy of the License at
  12  * http://www.mozilla.org/MPL/
  13  *
  14  * Software distributed under the License is distributed on an "AS IS" basis,
  15  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  16  * for the specific language governing rights and limitations under the
  17  * License.
  18  *
  19  * The Original Code is the Nice GLib ICE library.
  20  *
  21  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  22  * Corporation. All Rights Reserved.
  23  *
  24  * Contributors:
  25  *   Youness Alaoui, Collabora Ltd.
  26  *   Rémi Denis-Courmont, Nokia
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of the
  29  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  30  * case the provisions of LGPL are applicable instead of those above. If you
  31  * wish to allow use of your version of this file only under the terms of the
  32  * LGPL and not to allow others to use your version of this file under the
  33  * MPL, indicate your decision by deleting the provisions above and replace
  34  * them with the notice and other provisions required by the LGPL. If you do
  35  * not delete the provisions above, a recipient may use your version of this
  36  * file under either the MPL or the LGPL.
  37  */
  38
  39 #ifndef STUN_TIMER_H
  40 # define STUN_TIMER_H 1
  41
  42 /**
  43  * SECTION:timer
  44  * @short_description: STUN timer Usage
  45  * @include: stun/usages/timer.h
  46  * @stability: Stable
  47  *
  48  * The STUN timer usage is a set of helpful utility functions that allows you
  49  * to easily track when a STUN message should be retransmitted or considered
  50  * as timed out.
  51  *
  52  *
  53  <example>
  54    <title>Simple example on how to use the timer usage</title>
  55    <programlisting>
  56    StunTimer timer;
  57    unsigned remainder;
  58    StunUsageTimerReturn ret;
  59
  60    // Build the message, etc..
  61    ...
  62
  63    // Send the message and start the timer
  64    send(socket, request, sizeof(request));
  65    stun_timer_start(&timer, STUN_TIMER_DEFAULT_TIMEOUT,
  66                     STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS);
  67
  68    // Loop until we get the response
  69    for (;;) {
  70      remainder = stun_timer_remainder(&timer);
  71
  72      // Poll the socket until data is received or the timer expires
  73      if (poll (&pollfd, 1, delay) <= 0) {
  74        // Time out and no response was received
  75        ret = stun_timer_refresh (&timer);
  76        if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
  77          // Transaction timed out
  78          break;
  79        } else if (ret == STUN_USAGE_TIMER_RETURN_RETRANSMIT) {
  80          // A retransmission is necessary
  81          send(socket, request, sizeof(request));
  82          continue;
  83        } else if (ret == STUN_USAGE_TIMER_RETURN_SUCCESS) {
  84          // The refresh succeeded and nothing has to be done, continue polling
  85          continue;
  86        }
  87      } else {
  88        // We received a response, read it
  89        recv(socket, response, sizeof(response));
  90        break;
  91      }
  92    }
  93
  94    // Check if the transaction timed out or not
  95    if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
  96      // do whatever needs to be done in that case
  97    } else {
  98      // Parse the response
  99    }
 100
 101    </programlisting>
 102  </example>
 103  */
 104
 105 #ifdef _WIN32
 106 #include <winsock2.h>
 107 #else
 108 # include <sys/types.h>
 109 # include <sys/time.h>
 110 # include <time.h>
 111 #endif
 112
 113
 114 /**
 115  * StunTimer:
 116  *
 117  * An opaque structure representing a STUN transaction retransmission timer
 118  */
 119 typedef struct stun_timer_s StunTimer;
 120
 121 struct stun_timer_s {
 122   struct timeval deadline;
 123   unsigned delay;
 124   unsigned retransmissions;
 125   unsigned max_retransmissions;
 126 };
 127
 128
 129 /**
 130  * STUN_TIMER_DEFAULT_TIMEOUT:
 131  *
 132  * The default intial timeout to use for the timer
 133  * This timeout is used for discovering server reflexive and relay
 134  * candidates, and also for keepalives, and turn refreshes.
 135  *
 136  * This value is important because it defines how much time will be
 137  * required to discover our local candidates, and this is an
 138  * uncompressible delay before the agent signals that candidates
 139  * gathering is done.
 140  *
 141  * The overall delay required for the discovery stun requests is
 142  * computed as follow, with 3 retransmissions and an initial delay
 143  * of 500ms :  500 * ( 1 + 2 + 1 ) = 2000 ms
 144  * The timeout doubles at each retransmission, except for the last one.
 145  */
 146 #define STUN_TIMER_DEFAULT_TIMEOUT 500
 147
 148 /**
 149  * STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS:
 150  *
 151  * The default maximum retransmissions before declaring that the
 152  * transaction timed out.
 153  */
 154 #define STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS 3
 155
 156 /**
 157  * STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT:
 158  *
 159  * The default intial timeout to use for a reliable timer
 160  *
 161  * The idea with this value is that stun request sent over udp or tcp
 162  * should fail at the same time, with an initial default timeout set
 163  * to 500ms.
 164  */
 165 #define STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT 2000
 166
 167 /**
 168  * StunUsageTimerReturn:
 169  * @STUN_USAGE_TIMER_RETURN_SUCCESS: The timer was refreshed successfully
 170  * and there is nothing to be done
 171  * @STUN_USAGE_TIMER_RETURN_RETRANSMIT: The timer expired and the message
 172  * should be retransmitted now.
 173  * @STUN_USAGE_TIMER_RETURN_TIMEOUT: The timer expired as well as all the
 174  * retransmissions, the transaction timed out
 175  *
 176  * Return value of stun_usage_timer_refresh() which provides you with status
 177  * information on the timer.
 178  */
 179 typedef enum {
 180   STUN_USAGE_TIMER_RETURN_SUCCESS,
 181   STUN_USAGE_TIMER_RETURN_RETRANSMIT,
 182   STUN_USAGE_TIMER_RETURN_TIMEOUT
 183 } StunUsageTimerReturn;
 184
 185 # ifdef __cplusplus
 186 extern "C" {
 187 # endif
 188
 189
 190 /**
 191  * stun_timer_start:
 192  * @timer: The #StunTimer to start
 193  * @initial_timeout: The initial timeout to use before the first retransmission
 194  * @max_retransmissions: The maximum number of transmissions before the
 195  * #StunTimer times out
 196  *
 197  * Starts a STUN transaction retransmission timer.
 198  * This should be called as soon as you send the message for the first time on
 199  * a UDP socket.
 200  * The timeout before the next retransmission is set to @initial_timeout, then
 201  * each time a packet is retransmited, that timeout will be doubled, until the
 202  * @max_retransmissions retransmissions limit is reached.
 203  * <para>
 204  * To determine the total timeout value, one can use the following equation :
 205  <programlisting>
 206  total_timeout =  initial_timeout * (2^(max_retransmissions + 1) - 1);
 207  </programlisting>
 208  * </para>
 209  *
 210  * See also: #STUN_TIMER_DEFAULT_TIMEOUT
 211  *
 212  * See also: #STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS
 213  */
 214 void stun_timer_start (StunTimer *timer, unsigned int initial_timeout,
 215       unsigned int max_retransmissions);
 216
 217 /**
 218  * stun_timer_start_reliable:
 219  * @timer: The #StunTimer to start
 220  * @initial_timeout: The initial timeout to use before the first retransmission
 221  *
 222  * Starts a STUN transaction retransmission timer for a reliable transport.
 223  * This should be called as soon as you send the message for the first time on
 224  * a TCP socket
 225  */
 226 void stun_timer_start_reliable (StunTimer *timer, unsigned int initial_timeout);
 227
 228 /**
 229  * stun_timer_refresh:
 230  * @timer: The #StunTimer to refresh
 231  *
 232  * Updates a STUN transaction retransmission timer.
 233  * Returns: A #StunUsageTimerReturn telling you what to do next
 234  */
 235 StunUsageTimerReturn stun_timer_refresh (StunTimer *timer);
 236
 237 /**
 238  * stun_timer_remainder:
 239  * @timer: The #StunTimer to query
 240  *
 241  * Query the timer on the time left before the next refresh should be done
 242  * Returns: The time remaining for the timer to expire in milliseconds
 243  */
 244 unsigned stun_timer_remainder (const StunTimer *timer);
 245
 246 # ifdef __cplusplus
 247 }
 248 # endif
 249
 250 #endif /* !STUN_TIMER_H */