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  */
 134 #define STUN_TIMER_DEFAULT_TIMEOUT 600
 135
 136 /**
 137  * STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS:
 138  *
 139  * The default maximum retransmissions allowed before a timer decides to timeout
 140  */
 141 #define STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS 3
 142
 143 /**
 144  * STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT:
 145  *
 146  * The default intial timeout to use for a reliable timer
 147  */
 148 #define STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT 7900
 149
 150 /**
 151  * StunUsageTimerReturn:
 152  * @STUN_USAGE_TIMER_RETURN_SUCCESS: The timer was refreshed successfully
 153  * and there is nothing to be done
 154  * @STUN_USAGE_TIMER_RETURN_RETRANSMIT: The timer expired and the message
 155  * should be retransmitted now.
 156  * @STUN_USAGE_TIMER_RETURN_TIMEOUT: The timer expired as well as all the
 157  * retransmissions, the transaction timed out
 158  *
 159  * Return value of stun_usage_timer_refresh() which provides you with status
 160  * information on the timer.
 161  */
 162 typedef enum {
 163   STUN_USAGE_TIMER_RETURN_SUCCESS,
 164   STUN_USAGE_TIMER_RETURN_RETRANSMIT,
 165   STUN_USAGE_TIMER_RETURN_TIMEOUT
 166 } StunUsageTimerReturn;
 167
 168 # ifdef __cplusplus
 169 extern "C" {
 170 # endif
 171
 172
 173 /**
 174  * stun_timer_start:
 175  * @timer: The #StunTimer to start
 176  * @initial_timeout: The initial timeout to use before the first retransmission
 177  * @max_retransmissions: The maximum number of transmissions before the
 178  * #StunTimer times out
 179  *
 180  * Starts a STUN transaction retransmission timer.
 181  * This should be called as soon as you send the message for the first time on
 182  * a UDP socket.
 183  * The timeout before the next retransmission is set to @initial_timeout, then
 184  * each time a packet is retransmited, that timeout will be doubled, until the
 185  * @max_retransmissions retransmissions limit is reached.
 186  * <para>
 187  * To determine the total timeout value, one can use the following equation :
 188  <programlisting>
 189  total_timeout =  initial_timeout * (2^(max_retransmissions + 1) - 1);
 190  </programlisting>
 191  * </para>
 192  *
 193  * See also: #STUN_TIMER_DEFAULT_TIMEOUT
 194  *
 195  * See also: #STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS
 196  */
 197 void stun_timer_start (StunTimer *timer, unsigned int initial_timeout,
 198       unsigned int max_retransmissions);
 199
 200 /**
 201  * stun_timer_start_reliable:
 202  * @timer: The #StunTimer to start
 203  *
 204  * Starts a STUN transaction retransmission timer for a reliable transport.
 205  * This should be called as soon as you send the message for the first time on
 206  * a TCP socket
 207  */
 208 void stun_timer_start_reliable (StunTimer *timer, unsigned int initial_timeout);
 209
 210 /**
 211  * stun_timer_refresh:
 212  * @timer: The #StunTimer to refresh
 213  *
 214  * Updates a STUN transaction retransmission timer.
 215  * Returns: A #StunUsageTimerReturn telling you what to do next
 216  */
 217 StunUsageTimerReturn stun_timer_refresh (StunTimer *timer);
 218
 219 /**
 220  * stun_timer_remainder:
 221  * @timer: The #StunTimer to query
 222  *
 223  * Query the timer on the time left before the next refresh should be done
 224  * Returns: The time remaining for the timer to expire in milliseconds
 225  */
 226 unsigned stun_timer_remainder (const StunTimer *timer);
 227
 228 # ifdef __cplusplus
 229 }
 230 # endif
 231
 232 #endif /* !STUN_TIMER_H */