NiceCandidate

NiceCandidate — ICE candidate representation

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── NiceCandidate
    GEnum
    ├── NiceCandidateTransport
    ├── NiceCandidateType
    ╰── NiceRelayType

Description

A representation of an ICE candidate. Make sure you read the ICE drafts[1] to understand correctly the concept of ICE candidates.

[1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/

Functions

nice_candidate_new ()

NiceCandidate *
nice_candidate_new (NiceCandidateType type);

Creates a new candidate. Must be freed with nice_candidate_free()

Parameters

type

The NiceCandidateType of the candidate to create

 

Returns

A new NiceCandidate


nice_candidate_free ()

void
nice_candidate_free (NiceCandidate *candidate);

Frees a NiceCandidate

Parameters

candidate

The candidate to free

 

nice_candidate_copy ()

NiceCandidate *
nice_candidate_copy (const NiceCandidate *candidate);

Makes a copy of a NiceCandidate

Parameters

candidate

The candidate to copy

 

Returns

A new NiceCandidate, a copy of candidate


nice_candidate_equal_target ()

gboolean
nice_candidate_equal_target (const NiceCandidate *candidate1,
                             const NiceCandidate *candidate2);

Verifies that the candidates point to the same place, meaning they have the same transport and the same address. It ignores all other aspects.

Parameters

candidate1

A candidate

 

candidate2

A candidate

 

Returns

TRUE if the candidates point to the same place

Since: 0.1.15


nice_candidate_transport_to_string ()

const gchar *
nice_candidate_transport_to_string (NiceCandidateTransport transport);

Useful for debugging functions, just returns a static string with the candidate transport.

Parameters

transport

a NiceCandidateTransport

 

Returns

a static string with the candidate transport

Since: 0.1.19


nice_candidate_type_to_string ()

const gchar *
nice_candidate_type_to_string (NiceCandidateType type);

Useful for debugging functions, just returns a static string with the candidate type.

Parameters

type

a NiceCandidateType

 

Returns

a static string with the candidate type

Since: 0.1.19


nice_candidate_relay_address ()

void
nice_candidate_relay_address (const NiceCandidate *candidate,
                              NiceAddress *addr);

In case the given candidate is relayed through a TURN server, use this utility function to get its address.

Parameters

candidate

A relay candidate

 

addr

The NiceAddress to fill

 

Since: 0.1.19


nice_candidate_stun_server_address ()

gboolean
nice_candidate_stun_server_address (const NiceCandidate *candidate,
                                    NiceAddress *addr);

In case the given candidate server-reflexive, use this utility function to get its address. The address will be filled only if the candidate was generated using an STUN server.

Parameters

candidate

A server-reflexive candidate

 

addr

The NiceAddress to fill

 

Returns

TRUE if it's a STUN created ICE candidate, or FALSE if the reflexed's server was not STUN.

Since: 0.1.20

Types and Values

struct NiceCandidate

struct NiceCandidate {
  NiceCandidateType type;
  NiceCandidateTransport transport;
  NiceAddress addr;
  NiceAddress base_addr;
  guint32 priority;
  guint stream_id;
  guint component_id;
  gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
  gchar *username;        /* pointer to a nul-terminated username string */
  gchar *password;        /* pointer to a nul-terminated password string */
};

A structure to represent an ICE candidate

The priority is an integer as specified in the ICE draft 19. If you are using the MSN or the GOOGLE compatibility mode (which are based on ICE draft 6, which uses a floating point qvalue as priority), then the priority value will represent the qvalue multiplied by 1000.

Members

NiceCandidateType type;

The type of candidate

 

NiceCandidateTransport transport;

The transport being used for the candidate

 

NiceAddress addr;

The NiceAddress of the candidate

 

NiceAddress base_addr;

The NiceAddress of the base address used by the candidate

 

guint32 priority;

The priority of the candidate see note

 

guint stream_id;

The ID of the stream to which belongs the candidate

 

guint component_id;

The ID of the component to which belongs the candidate

 

gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];

The foundation of the candidate

 

gchar *username;

The candidate-specific username to use (overrides the one set by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())

 

gchar *password;

The candidate-specific password to use (overrides the one set by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())

 

enum NiceCandidateType

An enum representing the type of a candidate

Members

NICE_CANDIDATE_TYPE_HOST

A host candidate

 

NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE

A server reflexive candidate (or a NAT-assisted candidate)

 

NICE_CANDIDATE_TYPE_PEER_REFLEXIVE

A peer reflexive candidate

 

NICE_CANDIDATE_TYPE_RELAYED

A relay candidate

 

enum NiceCandidateTransport

An enum representing the type of transport to use

Members

NICE_CANDIDATE_TRANSPORT_UDP

UDP transport

 

NICE_CANDIDATE_TRANSPORT_TCP_ACTIVE

TCP Active transport

 

NICE_CANDIDATE_TRANSPORT_TCP_PASSIVE

TCP Passive transport

 

NICE_CANDIDATE_TRANSPORT_TCP_SO

TCP Simultaneous-Open transport

 

enum NiceRelayType

An enum representing the type of relay to use

Members

NICE_RELAY_TYPE_TURN_UDP

A TURN relay using UDP

 

NICE_RELAY_TYPE_TURN_TCP

A TURN relay using TCP

 

NICE_RELAY_TYPE_TURN_TLS

A TURN relay using TLS over TCP

 

NICE_CANDIDATE_MAX_FOUNDATION

#define NICE_CANDIDATE_MAX_FOUNDATION                (32+1)

The maximum size a candidate foundation can have.


NICE_CANDIDATE_MAX_TURN_SERVERS

#define NICE_CANDIDATE_MAX_TURN_SERVERS              8

The maximum number of turns servers.


NICE_CANDIDATE_MAX_LOCAL_ADDRESSES

#define NICE_CANDIDATE_MAX_LOCAL_ADDRESSES           64

The maximum number of local addresses. The constraint is that the maximum number of local addresses and number of turn servers must fit on 9 bits, to ensure candidate priority uniqueness. See also NICE_CANDIDATE_MAX_TURN_SERVERS . We choose 6 bits for the number of local addresses, and 3 bits for the number of turn servers.

See Also

NiceAddress