|
|
|
libnice Reference Manual | |
|---|---|---|---|---|
#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);
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.
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
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.
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. |
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 |
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.
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 |
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. |
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.
|