Timer

Timer — STUN timer Usage

Stability Level

Stable, unless otherwise indicated

Synopsis


#include <stun/usages/timer.h>

typedef             StunTimer;
enum                StunUsageTimerReturn;
void                stun_timer_start                    (StunTimer *timer);
void                stun_timer_start_reliable           (StunTimer *timer);
StunUsageTimerReturn stun_timer_refresh                 (StunTimer *timer);
unsigned            stun_timer_remainder                (const StunTimer *timer);

Description

The STUN timer usage is a set of helpful utility functions that allows you to easily track when a STUN message should be retransmitted or considered as timed out.

Example 3. Simple example on how to use the timer usage

   StunTimer timer;
   unsigned remainder;
   StunUsageTimerReturn ret;

   // Build the message, etc..
   ...

   // Send the message and start the timer
   send(socket, request, sizeof(request));
   stun_timer_start(&timer);

   // Loop until we get the response
   for (;;) {
     remainder = stun_timer_remainder(&timer);

     // Poll the socket until data is received or the timer expires
     if (poll (&pollfd, 1, delay) <= 0) {
       // Time out and no response was received
       ret = stun_timer_refresh (&timer);
       if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
         // Transaction timed out
         break;
       } else if (ret == STUN_USAGE_TIMER_RETURN_RETRANSMIT) {
         // A retransmission is necessary
         send(socket, request, sizeof(request));
         continue;
       } else if (ret == STUN_USAGE_TIMER_RETURN_SUCCESS) {
         // The refresh succeeded and nothing has to be done, continue polling
         continue;
       }
     } else {
       // We received a response, read it
       recv(socket, response, sizeof(response));
       break;
     }
   }

   // Check if the transaction timed out or not
   if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
     // do whatever needs to be done in that case
   } else {
     // Parse the response
   }

   


Details

StunTimer

typedef struct stun_timer_s StunTimer;

An opaque structure representing a STUN transaction retransmission timer


enum StunUsageTimerReturn

typedef enum {
  STUN_USAGE_TIMER_RETURN_SUCCESS,
  STUN_USAGE_TIMER_RETURN_RETRANSMIT,
  STUN_USAGE_TIMER_RETURN_TIMEOUT
} StunUsageTimerReturn;

Return value of stun_usage_timer_refresh() which provides you with status information on the timer.

STUN_USAGE_TIMER_RETURN_SUCCESS The timer was refreshed successfully and there is nothing to be done
STUN_USAGE_TIMER_RETURN_RETRANSMIT The timer expired and the message should be retransmitted now.
STUN_USAGE_TIMER_RETURN_TIMEOUT The timer expired as well as all the retransmissions, the transaction timed out

stun_timer_start ()

void                stun_timer_start                    (StunTimer *timer);

Starts a STUN transaction retransmission timer. This should be called as soon as you send the message for the first time on a UDP socket

timer : The StunTimer to start

stun_timer_start_reliable ()

void                stun_timer_start_reliable           (StunTimer *timer);

Starts a STUN transaction retransmission timer for a reliable transport. This should be called as soon as you send the message for the first time on a TCP socket

timer : The StunTimer to start

stun_timer_refresh ()

StunUsageTimerReturn stun_timer_refresh                 (StunTimer *timer);

Updates a STUN transaction retransmission timer.

timer : The StunTimer to refresh
Returns : A StunUsageTimerReturn telling you what to do next

stun_timer_remainder ()

unsigned            stun_timer_remainder                (const StunTimer *timer);

Query the timer on the time left before the next refresh should be done

timer : The StunTimer to query
Returns : The time remaining for the timer to expire in milliseconds