## ICE ICE — STUN ICE Usage |

## Stability Level

Stable, unless otherwise indicated

## Functions

size_t | stun_usage_ice_conncheck_create ()
StunUsageIceReturn | stun_usage_ice_conncheck_process ()
StunUsageIceReturn | stun_usage_ice_conncheck_create_reply ()
uint32_t | stun_usage_ice_conncheck_priority ()
bool | stun_usage_ice_conncheck_use_candidate ()

## Types and Values

enum | StunUsageIceCompatibility
enum | StunUsageIceReturn

## Includes

    #include <stun/usages/ice.h>

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

## Functions

### 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_MSICE2, the `candidate_identifier` argument is not used.

#### Parameters

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()`

#### Parameters

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.

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

msg | The StunMessage to parse |

#### Returns

`TRUE` if the flag is set, `FALSE` if not.

## Types and Values

### enum StunUsageIceCompatibility

This enum defines which compatibility modes this ICE usage can use

`STUN_USAGE_ICE_COMPATIBILITY_DRAFT19` and `STUN_USAGE_ICE_COMPATIBILITY_WLM2009` are deprecated and should not be used in newly-written code. They are kept for compatibility reasons and represent the same compatibilities as `STUN_USAGE_ICE_COMPATIBILITY_RFC5245` and `STUN_USAGE_ICE_COMPATIBILITY_MSICE2` respectively.

#### Members

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_MSICE2 | The ICE compatibility with [MS-ICE2] specification |
STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 | The ICE compatibility with draft 19 |
STUN_USAGE_ICE_COMPATIBILITY_WLM2009 | An alias for `STUN_USAGE_ICE_COMPATIBILITY_MSICE2` |

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

#### Members

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 |