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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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