## ICE ICE — STUN ICE Usage |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <stun/usages/ice.h>

    enum                StunUsageIceCompatibility;
    enum                StunUsageIceReturn;
    size_t              stun_usage_ice_conncheck_create     (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buffer,
                                                             size_t buffer_len,
                                                             const uint8_t *username,
                                                             const size_t username_len,
                                                             const uint8_t *password,
                                                             const size_t password_len,
                                                             bool cand_use,
                                                             bool controlling,
                                                             uint32_t priority,
                                                             uint64_t tie,
                                                             const char *candidate_identifier,
                                                             StunUsageIceCompatibility compatibility);
    StunUsageIceReturn  stun_usage_ice_conncheck_process    (StunMessage *msg,
                                                             struct sockaddr_storage *addr,
                                                             socklen_t *addrlen,
                                                             StunUsageIceCompatibility compatibility);
    StunUsageIceReturn  stun_usage_ice_conncheck_create_reply
                                                            (StunAgent *agent,
                                                             StunMessage *req,
                                                             StunMessage *msg,
                                                             uint8_t *buf,
                                                             size_t *plen,
                                                             const struct sockaddr_storage *src,
                                                             socklen_t srclen,
                                                             bool *control,
                                                             uint64_t tie,
                                                             StunUsageIceCompatibility compatibility);
    uint32_t            stun_usage_ice_conncheck_priority   (const StunMessage *msg);
    bool                stun_usage_ice_conncheck_use_candidate
                                                            (const StunMessage *msg);

## Description

The STUN ICE usage allows for easily creating and parsing STUN Binding requests and responses used for ICE connectivity checks. The API allows you to create a connectivity check message, parse a response or create a reply to an incoming connectivity check request.

## Details

### enum StunUsageIceCompatibility

    typedef enum {
      STUN_USAGE_ICE_COMPATIBILITY_RFC5245,
      STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
      STUN_USAGE_ICE_COMPATIBILITY_MSN,
      STUN_USAGE_ICE_COMPATIBILITY_WLM2009,
      STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 = STUN_USAGE_ICE_COMPATIBILITY_RFC5245,
    } StunUsageIceCompatibility;

This enum defines which compatibility modes this ICE usage can use

### Warning

`STUN_USAGE_ICE_COMPATIBILITY_DRAFT19` is deprecated and should not be used in newly-written code. It is kept for compatibility reasons and represents the same compatibility as `STUN_USAGE_ICE_COMPATIBILITY_RFC5245`

`STUN_USAGE_ICE_COMPATIBILITY_RFC5245` | The ICE compatibility with RFC 5245
`STUN_USAGE_ICE_COMPATIBILITY_GOOGLE` | The ICE compatibility with Google's implementation of ICE
`STUN_USAGE_ICE_COMPATIBILITY_MSN` | The ICE compatibility with MSN's implementation of ICE
`STUN_USAGE_ICE_COMPATIBILITY_WLM2009` | The ICE compatibility with Windows Live Messenger and Microsoft Office Communicator 2007 R2 implementation of ICE
`STUN_USAGE_ICE_COMPATIBILITY_DRAFT19` | The ICE compatibility with draft 19

### enum StunUsageIceReturn

    typedef enum {
      STUN_USAGE_ICE_RETURN_SUCCESS,
      STUN_USAGE_ICE_RETURN_ERROR,
      STUN_USAGE_ICE_RETURN_INVALID,
      STUN_USAGE_ICE_RETURN_ROLE_CONFLICT,
      STUN_USAGE_ICE_RETURN_INVALID_REQUEST,
      STUN_USAGE_ICE_RETURN_INVALID_METHOD,
      STUN_USAGE_ICE_RETURN_MEMORY_ERROR,
      STUN_USAGE_ICE_RETURN_INVALID_ADDRESS,
      STUN_USAGE_ICE_RETURN_NO_MAPPED_ADDRESS,
    } StunUsageIceReturn;

Return value of `stun_usage_ice_conncheck_process()` and `stun_usage_ice_conncheck_create_reply()` which allows you to see what status the function call returned.

`STUN_USAGE_ICE_RETURN_SUCCESS` | The function succeeded
`STUN_USAGE_ICE_RETURN_ERROR` | There was an unspecified error
`STUN_USAGE_ICE_RETURN_INVALID` | The message is invalid for processing
`STUN_USAGE_ICE_RETURN_ROLE_CONFLICT` | A role conflict was detected
`STUN_USAGE_ICE_RETURN_INVALID_REQUEST` | The message is an not a request
`STUN_USAGE_ICE_RETURN_INVALID_METHOD` | The method of the request is invalid
`STUN_USAGE_ICE_RETURN_MEMORY_ERROR` | The buffer size is too small to hold the STUN reply
`STUN_USAGE_ICE_RETURN_INVALID_ADDRESS` | The mapped address argument has an invalid address family
`STUN_USAGE_ICE_RETURN_NO_MAPPED_ADDRESS` | The response is valid but no MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attribute was found

### stun_usage_ice_conncheck_create ()

    size_t              stun_usage_ice_conncheck_create     (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buffer,
                                                             size_t buffer_len,
                                                             const uint8_t *username,
                                                             const size_t username_len,
                                                             const uint8_t *password,
                                                             const size_t password_len,
                                                             bool cand_use,
                                                             bool controlling,
                                                             uint32_t priority,
                                                             uint64_t tie,
                                                             const char *candidate_identifier,
                                                             StunUsageIceCompatibility compatibility);

Builds an ICE connectivity check STUN message. If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_RFC5245, the `cand_use`, `controlling`, `priority` and `tie` arguments are not used. If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_WLM2009, the `candidate_identifier` argument is not used.

`agent` : | The StunAgent to use to build the request
`msg` : | The StunMessage to build
`buffer` : | The buffer to use for creating the StunMessage
`buffer_len` : | The size of the `buffer`
`username` : | The username to use in the request
`username_len` : | The length of `username`
`password` : | The key to use for building the MESSAGE-INTEGRITY
`password_len` : | The length of `password`
`cand_use` : | Set to `TRUE` to append the USE-CANDIDATE flag to the request
`controlling` : | Set to `TRUE` if you are the controlling agent or set to `FALSE` if you are the controlled agent.
`priority` : | The value of the PRIORITY attribute
`tie` : | The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute
`candidate_identifier` : | The foundation value to put in the CANDIDATE-IDENTIFIER attribute
`compatibility` : | The compatibility mode to use for building the conncheck request
Returns : | The length of the message built.

### stun_usage_ice_conncheck_process ()

    StunUsageIceReturn  stun_usage_ice_conncheck_process    (StunMessage *msg,
                                                             struct sockaddr_storage *addr,
                                                             socklen_t *addrlen,
                                                             StunUsageIceCompatibility compatibility);

Process an ICE connectivity check STUN message and retreive the mapped address from the message

See also `stun_usage_ice_conncheck_priority()` and `stun_usage_ice_conncheck_use_candidate()`

`msg` : | The StunMessage to process
`addr` : | A pointer to a sockaddr structure to fill with the mapped address that the STUN connectivity check response contains
`addrlen` : | The length of `addr`
`compatibility` : | The compatibility mode to use for processing the conncheck response
Returns : | A StunUsageIceReturn value

### stun_usage_ice_conncheck_create_reply ()

    StunUsageIceReturn  stun_usage_ice_conncheck_create_reply
                                                            (StunAgent *agent,
                                                             StunMessage *req,
                                                             StunMessage *msg,
                                                             uint8_t *buf,
                                                             size_t *plen,
                                                             const struct sockaddr_storage *src,
                                                             socklen_t srclen,
                                                             bool *control,
                                                             uint64_t tie,
                                                             StunUsageIceCompatibility compatibility);

Tries to parse a STUN connectivity check request and builds a response accordingly.

### Note

In case of error, the `msg` is filled with the appropriate error response to be sent and the value of `plen` is set to the size of that message. If `plen` has a size of 0, then no error response should be sent.

`agent` : | The StunAgent to use to build the response
`req` : | The original STUN request to reply to
`msg` : | The StunMessage to build
`buf` : | The buffer to use for creating the StunMessage
`plen` : | A pointer containing the size of the `buffer` on input. Will contain the length of the message built on output.
`src` : | A pointer to a sockaddr structure containing the source address from which the request was received. Will be used as the mapped address in the response
`srclen` : | The length of `addr`
`control` : | Set to `TRUE` if you are the controlling agent or set to `FALSE` if you are the controlled agent.
`tie` : | The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute
`compatibility` : | The compatibility mode to use for building the conncheck response
Returns : | A StunUsageIceReturn value

### stun_usage_ice_conncheck_priority ()

    uint32_t            stun_usage_ice_conncheck_priority   (const StunMessage *msg);

Extracts the priority from a STUN message.

`msg` : | The StunMessage to parse
Returns : | host byte order priority, or 0 if not specified.

### stun_usage_ice_conncheck_use_candidate ()

    bool                stun_usage_ice_conncheck_use_candidate
                                                            (const StunMessage *msg);

Extracts the USE-CANDIDATE attribute flag from a STUN message.

`msg` : | The StunMessage to parse
Returns : | `TRUE` if the flag is set, `FALSE` if not.