## 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

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