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,
                                                         StunUsageIceCompatibility compatibility);
StunUsageIceReturn  stun_usage_ice_conncheck_process    (StunMessage *msg,
                                                         struct sockaddr *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 *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_DRAFT19,
  STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
  STUN_USAGE_ICE_COMPATIBILITY_MSN,
} StunUsageIceCompatibility;

This enum defines which compatibility modes this ICE usage can use

STUN_USAGE_ICE_COMPATIBILITY_DRAFT19

The ICE compatibility with draft 19

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

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,
                                                         StunUsageIceCompatibility compatibility);

Builds an ICE connectivity check STUN message. If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_DRAFT19, the cand_use, controlling, priority and tie arguments are 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

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