ICE

ICE — STUN ICE Usage

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

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