NiceAgent

NiceAgent — ICE agent API implementation

Stability Level

Stable, unless otherwise indicated

Functions

void (*NiceAgentRecvFunc) ()
NiceAgent * nice_agent_new ()
NiceAgent * nice_agent_new_reliable ()
NiceAgent * nice_agent_new_full ()
gboolean nice_agent_add_local_address ()
void nice_agent_set_port_range ()
guint nice_agent_add_stream ()
void nice_agent_remove_stream ()
gboolean nice_agent_set_relay_info ()
gboolean nice_agent_forget_relays ()
gboolean nice_agent_gather_candidates ()
gboolean nice_agent_set_remote_credentials ()
gboolean nice_agent_get_local_credentials ()
gboolean nice_agent_set_local_credentials ()
int nice_agent_set_remote_candidates ()
GSList * nice_agent_get_remote_candidates ()
GSList * nice_agent_get_local_candidates ()
gboolean nice_agent_get_selected_pair ()
gboolean nice_agent_peer_candidate_gathering_done ()
gint nice_agent_send ()
gint nice_agent_send_messages_nonblocking ()
gssize nice_agent_recv ()
gint nice_agent_recv_messages ()
gssize nice_agent_recv_nonblocking ()
gint nice_agent_recv_messages_nonblocking ()
gboolean nice_agent_attach_recv ()
gboolean nice_agent_set_selected_pair ()
gboolean nice_agent_set_selected_remote_candidate ()
void nice_agent_set_stream_tos ()
void nice_agent_set_software ()
gboolean nice_agent_restart ()
gboolean nice_agent_restart_stream ()
gboolean nice_agent_set_stream_name ()
const gchar * nice_agent_get_stream_name ()
NiceCandidate * nice_agent_get_default_local_candidate ()
gchar * nice_agent_generate_local_sdp ()
gchar * nice_agent_generate_local_stream_sdp ()
gchar * nice_agent_generate_local_candidate_sdp ()
int nice_agent_parse_remote_sdp ()
GSList * nice_agent_parse_remote_stream_sdp ()
NiceCandidate * nice_agent_parse_remote_candidate_sdp ()
GIOStream * nice_agent_get_io_stream ()
GSocket * nice_agent_get_selected_socket ()
GPtrArray * nice_agent_get_sockets ()
NiceComponentState nice_agent_get_component_state ()
void nice_agent_close_async ()
gboolean nice_agent_consent_lost ()
const gchar * nice_component_state_to_string ()
#define NICE_CHECK_VERSION()

Properties

gboolean bytestream-tcp Read / Write
guint compatibility Read / Write / Construct Only
gboolean consent-freshness Read / Write / Construct Only
gboolean controlling-mode Read / Write
gboolean force-relay Read / Write
gboolean full-mode Read / Write / Construct Only
gboolean ice-tcp Read / Write
gboolean ice-trickle Read / Write
gboolean ice-udp Read / Write
guint idle-timeout Read / Write / Construct
gboolean keepalive-conncheck Read / Write
gpointer main-context Read / Write / Construct Only
guint max-connectivity-checks Read / Write
NiceNominationMode nomination-mode Read / Write / Construct Only
GHashTable * proxy-extra-headers Read / Write
gchar * proxy-ip Read / Write
gchar * proxy-password Read / Write
guint proxy-port Read / Write
guint proxy-type Read / Write
gchar * proxy-username Read / Write
gboolean reliable Read / Write / Construct Only
guint stun-initial-timeout Read / Write / Construct
guint stun-max-retransmissions Read / Write / Construct
guint stun-pacing-timer Read / Write / Construct
guint stun-reliable-timeout Read / Write / Construct
gchar * stun-server Read / Write
guint stun-server-port Read / Write
gboolean support-renomination Read / Write
gboolean upnp Read / Write / Construct
guint upnp-timeout Read / Write / Construct

Signals

void candidate-gathering-done Run Last
void component-state-changed Run Last
void initial-binding-request-received Run Last
void new-candidate Run Last
void new-candidate-full Run Last
void new-remote-candidate Run Last
void new-remote-candidate-full Run Last
void new-selected-pair Run Last
void new-selected-pair-full Run Last
void reliable-transport-writable Run Last
void streams-removed Run Last

Types and Values

Object Hierarchy

    GEnum
    ├── NiceCompatibility
    ├── NiceComponentState
    ├── NiceComponentType
    ├── NiceNominationMode
    ╰── NiceProxyType
    GFlags
    ╰── NiceAgentOption
    GObject
    ╰── NiceAgent

Includes

#include <agent.h>

Description

The NiceAgent is your main object when using libnice. It is the agent that will take care of everything relating to ICE. It will take care of discovering your local candidates and do connectivity checks to create a stream of data between you and your peer.

A NiceAgent must always be used with a GMainLoop running the GMainContext passed into nice_agent_new() (or nice_agent_new_reliable()). Without the GMainContext being iterated, the agent’s timers will not fire, etc.

Streams and their components are referenced by integer IDs (with respect to a given NiceAgent). These IDs are guaranteed to be positive (i.e. non-zero) for valid streams/components.

To complete the ICE connectivity checks, the user must either register an I/O callback (with nice_agent_attach_recv()) or call nice_agent_recv_messages() in a loop on a dedicated thread. Technically, NiceAgent does not poll the streams on its own, since user data could arrive at any time; to receive STUN packets required for establishing ICE connectivity, it is backpiggying on the facility chosen by the user. NiceAgent will handle all STUN packets internally; they're never actually passed to the I/O callback or returned from nice_agent_recv_messages() and related functions.

Each stream can receive data in one of two ways: using nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived NiceInputStream and NiceIOStream classes accessible using nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: it takes a user-provided callback function and attaches the stream’s socket to the provided GMainContext, invoking the callback in that context for every packet received. nice_agent_recv_messages() instead blocks on receiving a packet, and writes it directly into a user-provided buffer. This reduces the number of callback invokations and (potentially) buffer copies required to receive packets. nice_agent_recv_messages() (or NiceInputStream) is designed to be used in a blocking loop in a separate thread.

Example 1. Simple example on how to use libnice

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
guint stream_id;
gchar buffer[] = "hello world!";
gchar *ufrag = NULL, *pwd = NULL;
gchar *remote_ufrag, *remote_pwd;
GSList *lcands = NULL;

// Create a nice agent, passing in the global default GMainContext.
NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
spawn_thread_to_run_main_loop (g_main_loop_new (NULL, FALSE));

// Connect the signals
g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
                  G_CALLBACK (cb_candidate_gathering_done), NULL);
g_signal_connect (G_OBJECT (agent), "component-state-changed",
                  G_CALLBACK (cb_component_state_changed), NULL);
g_signal_connect (G_OBJECT (agent), "new-selected-pair",
                  G_CALLBACK (cb_new_selected_pair), NULL);

// Create a new stream with one component and start gathering candidates
stream_id = nice_agent_add_stream (agent, 1);
nice_agent_gather_candidates (agent, stream_id);

// Attach I/O callback the component to ensure that:
// 1) agent gets its STUN packets (not delivered to cb_nice_recv)
// 2) you get your own data
nice_agent_attach_recv (agent, stream_id, 1, NULL,
                       cb_nice_recv, NULL);

// ... Wait until the signal candidate-gathering-done is fired ...
lcands = nice_agent_get_local_candidates(agent, stream_id, 1);

nice_agent_get_local_credentials(agent, stream_id, &ufrag, &pwd);

// ... Send local candidates and credentials to the peer

// Set the peer's remote credentials and remote candidates
nice_agent_set_remote_credentials (agent, stream_id, remote_ufrag, remote_pwd);
nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);

// ... Wait until the signal new-selected-pair is fired ...
// Send our message!
nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);

// Anything received will be received through the cb_nice_recv callback.
// You must be running a GMainLoop on the global default GMainContext in
// another thread for this to work.

// Destroy the object
g_object_unref(agent);

Refer to the examples in the examples/ subdirectory of the libnice source for more complete examples.

Functions

NiceAgentRecvFunc ()

void
(*NiceAgentRecvFunc) (NiceAgent *agent,
                      guint stream_id,
                      guint component_id,
                      guint len,
                      gchar *buf,
                      gpointer user_data);

Callback function when data is received on a component

Parameters

agent

The NiceAgent Object

 

stream_id

The id of the stream

 

component_id

The id of the component of the stream which received the data

 

len

The length of the data

 

buf

The buffer containing the data received

 

user_data

The user data set in nice_agent_attach_recv()

 

nice_agent_new ()

NiceAgent *
nice_agent_new (GMainContext *ctx,
                NiceCompatibility compat);

Create a new NiceAgent. The returned object must be freed with g_object_unref()

Parameters

ctx

The Glib Mainloop Context to use for timers

 

compat

The compatibility mode of the agent

 

Returns

The new agent GObject


nice_agent_new_reliable ()

NiceAgent *
nice_agent_new_reliable (GMainContext *ctx,
                         NiceCompatibility compat);

Create a new NiceAgent in reliable mode. If the connectivity is established through ICE-UDP, then a PseudoTcpSocket will be transparently used to ensure reliability of the messages. The returned object must be freed with g_object_unref()

See also: “reliable-transport-writable”

Parameters

ctx

The Glib Mainloop Context to use for timers

 

compat

The compatibility mode of the agent

 

Returns

The new agent GObject

Since: 0.0.11


nice_agent_new_full ()

NiceAgent *
nice_agent_new_full (GMainContext *ctx,
                     NiceCompatibility compat,
                     NiceAgentOption flags);

Create a new NiceAgent with parameters that must be be defined at construction time. The returned object must be freed with g_object_unref()

See also: NiceNominationMode and NiceAgentOption

Parameters

ctx

The Glib Mainloop Context to use for timers

 

compat

The compatibility mode of the agent

 

flags

Flags to set the properties

 

Returns

The new agent GObject

Since: 0.1.15


nice_agent_add_local_address ()

gboolean
nice_agent_add_local_address (NiceAgent *agent,
                              NiceAddress *addr);

Add a local address from which to derive local host candidates for candidate gathering.

Since 0.0.5, if this method is not called, libnice will automatically discover the local addresses available

See also: nice_agent_gather_candidates()

Parameters

agent

The NiceAgent Object

 

addr

The address to listen to If the port is 0, then a random port will be chosen by the system

 

Returns

TRUE on success, FALSE on fatal (memory allocation) errors


nice_agent_set_port_range ()

void
nice_agent_set_port_range (NiceAgent *agent,
                           guint stream_id,
                           guint component_id,
                           guint min_port,
                           guint max_port);

Sets a preferred port range for allocating host candidates.

If a local host candidate cannot be created on that port range, then the nice_agent_gather_candidates() call will fail.

This MUST be called before nice_agent_gather_candidates()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

min_port

The minimum port to use

 

max_port

The maximum port to use

 

nice_agent_add_stream ()

guint
nice_agent_add_stream (NiceAgent *agent,
                       guint n_components);

Adds a data stream to agent containing n_components components. The returned stream ID is guaranteed to be positive on success.

Parameters

agent

The NiceAgent Object

 

n_components

The number of components to add to the stream

 

Returns

The ID of the new stream, 0 on failure


nice_agent_remove_stream ()

void
nice_agent_remove_stream (NiceAgent *agent,
                          guint stream_id);

Remove and free a previously created data stream from agent . If any I/O streams have been created using nice_agent_get_io_stream(), they should be closed completely using g_io_stream_close() before this is called, or they will get broken pipe errors.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream to remove

 

nice_agent_set_relay_info ()

gboolean
nice_agent_set_relay_info (NiceAgent *agent,
                           guint stream_id,
                           guint component_id,
                           const gchar *server_ip,
                           guint server_port,
                           const gchar *username,
                           const gchar *password,
                           NiceRelayType type);

Sets the settings for using a relay server during the candidate discovery. This may be called multiple times to add multiple relay servers to the discovery process; one TCP and one UDP, for example.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

server_ip

The address of the TURN server

 

server_port

The port of the TURN server

 

username

The TURN username to use for the allocate

 

password

The TURN password to use for the allocate

 

type

The type of relay to use

 

Returns

TRUE if the TURN settings were accepted. FALSE if the address was invalid.


nice_agent_forget_relays ()

gboolean
nice_agent_forget_relays (NiceAgent *agent,
                          guint stream_id,
                          guint component_id);

Forget all the relay servers previously added using nice_agent_set_relay_info(). Currently connected streams will keep using the relay as long as they have not been restarted and haven't succesfully negotiated a different path.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

FALSE if the component could not be found, TRUE otherwise

Since: 0.1.6


nice_agent_gather_candidates ()

gboolean
nice_agent_gather_candidates (NiceAgent *agent,
                              guint stream_id);

Allocate and start listening on local candidate ports and start the remote candidate gathering process. Once done, “candidate-gathering-done” is called for the stream. As soon as this function is called, “new-candidate” signals may be emitted, even before this function returns.

nice_agent_get_local_candidates() will only return non-empty results after calling this function.

See also: nice_agent_add_local_address()

See also: nice_agent_set_port_range()

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream to start

 

Returns

FALSE if the stream ID is invalid or if a host candidate couldn't be allocated on the requested interfaces/ports; TRUE otherwise

Local addresses can be previously set with nice_agent_add_local_address()

Since 0.0.5, If no local address was previously added, then the nice agent will automatically detect the local address using nice_interfaces_get_local_ips()


nice_agent_set_remote_credentials ()

gboolean
nice_agent_set_remote_credentials (NiceAgent *agent,
                                   guint stream_id,
                                   const gchar *ufrag,
                                   const gchar *pwd);

Sets the remote credentials for stream stream_id .

Stream credentials do not override per-candidate credentials if set

Due to the native of peer-reflexive candidates, any agent using a per-stream credentials (RFC5245, WLM2009, OC2007R2 and DRAFT19) instead of per-candidate credentials (GOOGLE, MSN, OC2007), must use the nice_agent_set_remote_credentials() API instead of setting the username and password on the candidates.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

ufrag

nul-terminated string containing an ICE username fragment (length must be between 22 and 256 chars)

 

pwd

nul-terminated string containing an ICE password (length must be between 4 and 256 chars)

 

Returns

TRUE on success, FALSE on error.


nice_agent_get_local_credentials ()

gboolean
nice_agent_get_local_credentials (NiceAgent *agent,
                                  guint stream_id,
                                  gchar **ufrag,
                                  gchar **pwd);

Gets the local credentials for stream stream_id . This may be called any time after creating a stream using nice_agent_add_stream().

An error will be returned if this is called for a non-existent stream, or if either of ufrag or pwd are NULL.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

ufrag

return location for a nul-terminated string containing an ICE username fragment; must be freed with g_free().

[out callee-allocates]

pwd

return location for a nul-terminated string containing an ICE password; must be freed with g_free().

[out callee-allocates]

Returns

TRUE on success, FALSE on error.


nice_agent_set_local_credentials ()

gboolean
nice_agent_set_local_credentials (NiceAgent *agent,
                                  guint stream_id,
                                  const gchar *ufrag,
                                  const gchar *pwd);

Sets the local credentials for stream stream_id .

This is only effective before ICE negotiation has started.

Since 0.1.11

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

ufrag

nul-terminated string containing an ICE username fragment (length must be between 22 and 256 chars)

 

pwd

nul-terminated string containing an ICE password (length must be between 4 and 256 chars)

 

Returns

TRUE on success, FALSE on error.


nice_agent_set_remote_candidates ()

int
nice_agent_set_remote_candidates (NiceAgent *agent,
                                  guint stream_id,
                                  guint component_id,
                                  const GSList *candidates);

Sets, adds or updates the remote candidates for a component of a stream.

NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates.

You must first call nice_agent_gather_candidates() and wait for the “candidate-gathering-done” signale before calling nice_agent_set_remote_candidates()

Since 0.1.3, there is no need to wait for the candidate-gathering-done signal. Remote candidates can be set even while gathering local candidates. Newly discovered local candidates will automatically be paired with existing remote candidates.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream the candidates are for

 

component_id

The ID of the component the candidates are for

 

candidates

a GSList of NiceCandidate items describing each candidate to add.

[element-type NiceCandidate][transfer none]

Returns

The number of candidates added, negative on errors (memory allocation error or invalid component)


nice_agent_get_remote_candidates ()

GSList *
nice_agent_get_remote_candidates (NiceAgent *agent,
                                  guint stream_id,
                                  guint component_id);

Get a list of the remote candidates set on a stream's component

The caller owns the returned GSList as well as the candidates contained within it.

The list of remote candidates can change during processing. The client should register for the “new-remote-candidate” signal to get notified of new remote candidates.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

a GSList of NiceCandidates objects representing the remote candidates set on the agent .

[element-type NiceCandidate][transfer full]


nice_agent_get_local_candidates ()

GSList *
nice_agent_get_local_candidates (NiceAgent *agent,
                                 guint stream_id,
                                 guint component_id);

Retrieve from the agent the list of all local candidates for a stream's component

The caller owns the returned GSList as well as the candidates contained within it. To get full results, the client should wait for the “candidate-gathering-done” signal.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

a GSList of NiceCandidate objects representing the local candidates of agent .

[element-type NiceCandidate][transfer full]


nice_agent_get_selected_pair ()

gboolean
nice_agent_get_selected_pair (NiceAgent *agent,
                              guint stream_id,
                              guint component_id,
                              NiceCandidate **local,
                              NiceCandidate **remote);

Retreive the selected candidate pair for media transmission for a given stream's component.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

local

The local selected candidate

 

remote

The remote selected candidate

 

Returns

TRUE on success, FALSE if there is no selected candidate pair


nice_agent_peer_candidate_gathering_done ()

gboolean
nice_agent_peer_candidate_gathering_done
                               (NiceAgent *agent,
                                guint stream_id);

Notifies the agent that the remote peer has concluded candidate gathering and thus no more remote candidates are expected to arrive for stream_id .

This will allow the stream components without a successful connectivity check to stop waiting for more candidates to come and finally transit into NICE_COMPONENT_STATE_FAILED.

Calling the function has an effect only when “trickle-ice” is TRUE.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

Returns

FALSE if the stream could not be found, TRUE otherwise

Since: 0.1.16


nice_agent_send ()

gint
nice_agent_send (NiceAgent *agent,
                 guint stream_id,
                 guint component_id,
                 guint len,
                 const gchar *buf);

Sends a data payload over a stream's component.

Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case, in any state if component was in READY state before and was then restarted

In reliable mode, the -1 error value means either that you are not yet connected or that the send buffer is full (equivalent to EWOULDBLOCK). In both cases, you simply need to wait for the “reliable-transport-writable” signal to be fired before resending the data.

In non-reliable mode, it will virtually never happen with UDP sockets, but it might happen if the active candidate is a TURN-TCP connection that got disconnected.

In both reliable and non-reliable mode, a -1 error code could also mean that the stream_id and/or component_id are invalid.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream to send to

 

component_id

The ID of the component to send to

 

len

The length of the buffer to send

 

buf

The buffer of data to send

 

Returns

The number of bytes sent, or negative error code


nice_agent_send_messages_nonblocking ()

gint
nice_agent_send_messages_nonblocking (NiceAgent *agent,
                                      guint stream_id,
                                      guint component_id,
                                      const NiceOutputMessage *messages,
                                      guint n_messages,
                                      GCancellable *cancellable,
                                      GError **error);

Sends multiple messages on the socket identified by the given stream/component pair. Transmission is non-blocking, so a G_IO_ERROR_WOULD_BLOCK error may be returned if the send buffer is full.

As with nice_agent_send(), the given component must be in NICE_COMPONENT_STATE_READY or, as a special case, in any state if it was previously ready and was then restarted.

On success, the number of messages written to the socket will be returned, which may be less than n_messages if transmission would have blocked part-way through. Zero will be returned if n_messages is zero, or if transmission would have blocked on the first message.

In reliable mode, it is instead recommended to use nice_agent_send(). The return value can be less than n_messages or 0 even if it is still possible to send a partial message. In this case, "nice-agent-writable" will never be triggered, so the application would have to use nice_agent_sent() to fill the buffer or have to retry sending at a later point.

On failure, -1 will be returned and error will be set. If the NiceAgent is reliable and the socket is not yet connected, G_IO_ERROR_BROKEN_PIPE will be returned; if the write buffer is full, G_IO_ERROR_WOULD_BLOCK will be returned. In both cases, wait for the “reliable-transport-writable” signal before trying again. If the given stream_id or component_id are invalid or not yet connected, G_IO_ERROR_BROKEN_PIPE will be returned. G_IO_ERROR_FAILED will be returned for other errors.

Parameters

agent

a NiceAgent

 

stream_id

the ID of the stream to send to

 

component_id

the ID of the component to send to

 

messages

array of messages to send, of at least n_messages entries in length.

[array length=n_messages]

n_messages

number of entries in messages

 

cancellable

a GCancellable to cancel the operation from another thread, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

the number of messages sent (may be zero), or -1 on error

Since: 0.1.5


nice_agent_recv ()

gssize
nice_agent_recv (NiceAgent *agent,
                 guint stream_id,
                 guint component_id,
                 guint8 *buf,
                 gsize buf_len,
                 GCancellable *cancellable,
                 GError **error);

A single-message version of nice_agent_recv_messages().

Parameters

agent

a NiceAgent

 

stream_id

the ID of the stream to receive on

 

component_id

the ID of the component to receive on

 

buf

caller-allocated buffer to write the received data into, of length at least buf_len .

[array length=buf_len][out caller-allocates]

buf_len

length of buf .

[in]

cancellable

a GCancellable to allow the operation to be cancelled from another thread, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

the number of bytes written to buf on success (guaranteed to be greater than 0 unless buf_len is 0), 0 if in reliable mode and the remote peer closed the stream, or -1 on error

Since: 0.1.5


nice_agent_recv_messages ()

gint
nice_agent_recv_messages (NiceAgent *agent,
                          guint stream_id,
                          guint component_id,
                          NiceInputMessage *messages,
                          guint n_messages,
                          GCancellable *cancellable,
                          GError **error);

Block on receiving data from the given stream/component combination on agent , returning only once exactly n_messages messages have been received and written into messages , the stream is closed by the other end or by calling nice_agent_remove_stream(), or cancellable is cancelled.

Any STUN packets received will not be added to messages ; instead, they'll be passed for processing to NiceAgent itself. Since NiceAgent does not poll for messages on its own, it's therefore essential to keep calling this function for ICE connection establishment to work.

In the non-error case, in reliable mode, this will block until all buffers in all n_messages have been filled with received data (i.e. messages is treated as a large, flat array of buffers). In non-reliable mode, it will block until n_messages messages have been received, each of which does not have to fill all the buffers in its NiceInputMessage. In the non-reliable case, each NiceInputMessage must have enough buffers to contain an entire message (65536 bytes), or any excess data may be silently dropped.

For each received message, “length” will be set to the number of valid bytes stored in the message’s buffers. The bytes are stored sequentially in the buffers; there are no gaps apart from at the end of the buffer array (in non-reliable mode). If non-NULL on input, “from” will have the address of the sending peer stored in it. The base addresses, sizes, and number of buffers in each message will not be modified in any case.

This must not be used in combination with nice_agent_attach_recv() on the same stream/component pair.

If the stream/component pair doesn’t exist, or if a suitable candidate socket hasn’t yet been selected for it, a G_IO_ERROR_BROKEN_PIPE error will be returned. A G_IO_ERROR_CANCELLED error will be returned if the operation was cancelled. G_IO_ERROR_FAILED will be returned for other errors.

Parameters

agent

a NiceAgent

 

stream_id

the ID of the stream to receive on

 

component_id

the ID of the component to receive on

 

messages

caller-allocated array of NiceInputMessages to write the received messages into, of length at least n_messages .

[array length=n_messages][out caller-allocates]

n_messages

number of entries in messages

 

cancellable

a GCancellable to allow the operation to be cancelled from another thread, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

the number of valid messages written to messages on success (guaranteed to be greater than 0 unless n_messages is 0), 0 if the remote peer closed the stream, or -1 on error

Since: 0.1.5


nice_agent_recv_nonblocking ()

gssize
nice_agent_recv_nonblocking (NiceAgent *agent,
                             guint stream_id,
                             guint component_id,
                             guint8 *buf,
                             gsize buf_len,
                             GCancellable *cancellable,
                             GError **error);

A single-message version of nice_agent_recv_messages_nonblocking().

Parameters

agent

a NiceAgent

 

stream_id

the ID of the stream to receive on

 

component_id

the ID of the component to receive on

 

buf

caller-allocated buffer to write the received data into, of length at least buf_len .

[array length=buf_len][out caller-allocates]

buf_len

length of buf .

[in]

cancellable

a GCancellable to allow the operation to be cancelled from another thread, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

the number of bytes received into buf on success (guaranteed to be greater than 0 unless buf_len is 0), 0 if in reliable mode and the remote peer closed the stream, or -1 on error

Since: 0.1.5


nice_agent_recv_messages_nonblocking ()

gint
nice_agent_recv_messages_nonblocking (NiceAgent *agent,
                                      guint stream_id,
                                      guint component_id,
                                      NiceInputMessage *messages,
                                      guint n_messages,
                                      GCancellable *cancellable,
                                      GError **error);

Try to receive data from the given stream/component combination on agent , without blocking. If receiving data would block, -1 is returned and G_IO_ERROR_WOULD_BLOCK is set in error . If any other error occurs, -1 is returned and error is set accordingly. Otherwise, 0 is returned if (and only if) n_messages is 0. In all other cases, the number of valid messages stored in messages is returned, and will be greater than 0.

This function behaves similarly to nice_agent_recv_messages(), except that it will not block on filling (in reliable mode) or receiving (in non-reliable mode) exactly n_messages messages. In reliable mode, it will receive bytes into messages until it would block; in non-reliable mode, it will receive messages until it would block.

Any STUN packets received will not be added to messages ; instead, they'll be passed for processing to NiceAgent itself. Since NiceAgent does not poll for messages on its own, it's therefore essential to keep calling this function for ICE connection establishment to work.

As this function is non-blocking, cancellable is included only for parity with nice_agent_recv_messages(). If cancellable is cancelled before this function is called, a G_IO_ERROR_CANCELLED error will be returned immediately.

This must not be used in combination with nice_agent_attach_recv() on the same stream/component pair.

Parameters

agent

a NiceAgent

 

stream_id

the ID of the stream to receive on

 

component_id

the ID of the component to receive on

 

messages

caller-allocated array of NiceInputMessages to write the received messages into, of length at least n_messages .

[array length=n_messages][out caller-allocates]

n_messages

number of entries in messages

 

cancellable

a GCancellable to allow the operation to be cancelled from another thread, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

the number of valid messages written to messages on success (guaranteed to be greater than 0 unless n_messages is 0), 0 if in reliable mode and the remote peer closed the stream, or -1 on error

Since: 0.1.5


nice_agent_attach_recv ()

gboolean
nice_agent_attach_recv (NiceAgent *agent,
                        guint stream_id,
                        guint component_id,
                        GMainContext *ctx,
                        NiceAgentRecvFunc func,
                        gpointer data);

Attaches the stream's component's sockets to the Glib Mainloop Context in order to be notified whenever data becomes available for a component, and to enable NiceAgent to receive STUN messages (during the establishment of ICE connectivity).

This must not be used in combination with nice_agent_recv_messages() (or NiceIOStream or NiceInputStream) on the same stream/component pair.

Calling nice_agent_attach_recv() with a NULL func will detach any existing callback and cause reception to be paused for the given stream/component pair. You must iterate the previously specified GMainContext sufficiently to ensure all pending I/O callbacks have been received before calling this function to unset func , otherwise data loss of received packets may occur.

[skip]

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of stream

 

component_id

The ID of the component

 

ctx

The Glib Mainloop Context to use for listening on the component

 

func

The callback function to be called when data is received on the stream's component (will not be called for STUN messages that should be handled by NiceAgent itself)

 

data

user data associated with the callback

 

Returns

TRUE on success, FALSE if the stream or component IDs are invalid.


nice_agent_set_selected_pair ()

gboolean
nice_agent_set_selected_pair (NiceAgent *agent,
                              guint stream_id,
                              guint component_id,
                              const gchar *lfoundation,
                              const gchar *rfoundation);

Sets the selected candidate pair for media transmission for a given stream's component. Calling this function will disable all further ICE processing (connection check, state machine updates, etc). Note that keepalives will continue to be sent.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

lfoundation

The local foundation of the candidate to use

 

rfoundation

The remote foundation of the candidate to use

 

Returns

TRUE on success, FALSE if the candidate pair cannot be found


nice_agent_set_selected_remote_candidate ()

gboolean
nice_agent_set_selected_remote_candidate
                               (NiceAgent *agent,
                                guint stream_id,
                                guint component_id,
                                NiceCandidate *candidate);

Sets the selected remote candidate for media transmission for a given stream's component. This is used to force the selection of a specific remote candidate even when connectivity checks are failing (e.g. non-ICE compatible candidates). Calling this function will disable all further ICE processing (connection check, state machine updates, etc). Note that keepalives will continue to be sent.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

candidate

The NiceCandidate to select

 

Returns

TRUE on success, FALSE on failure


nice_agent_set_stream_tos ()

void
nice_agent_set_stream_tos (NiceAgent *agent,
                           guint stream_id,
                           gint tos);

Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

tos

The ToS to set

 

Since: 0.0.9


nice_agent_set_software ()

void
nice_agent_set_software (NiceAgent *agent,
                         const gchar *software);

This function will set the value of the SOFTWARE attribute to be added to STUN requests, responses and error responses sent during connectivity checks.

The SOFTWARE attribute will only be added in the NICE_COMPATIBILITY_RFC5245 and NICE_COMPATIBILITY_WLM2009 compatibility modes.

The software argument will be appended with the libnice version before being sent.

The software argument must be in UTF-8 encoding and only the first 128 characters will be sent.

Parameters

agent

The NiceAgent Object

 

software

The value of the SOFTWARE attribute to add.

 

Since: 0.0.10


nice_agent_restart ()

gboolean
nice_agent_restart (NiceAgent *agent);

Restarts the session as defined in ICE draft 19. This function needs to be called both when initiating (ICE spec section 9.1.1.1. "ICE Restarts"), as well as when reacting (spec section 9.2.1.1. "Detecting ICE Restart") to a restart.

If consent-freshness has been enabled on agent , as specified in RFC7675 then restarting streams will restore the local consent.

Parameters

agent

The NiceAgent Object

 

Returns

TRUE on success FALSE on error


nice_agent_restart_stream ()

gboolean
nice_agent_restart_stream (NiceAgent *agent,
                           guint stream_id);

Restarts a single stream as defined in RFC 5245. This function needs to be called both when initiating (ICE spec section 9.1.1.1. "ICE Restarts"), as well as when reacting (spec section 9.2.1.1. "Detecting ICE Restart") to a restart.

Unlike nice_agent_restart(), this applies to a single stream. It also does not generate a new tie breaker.

If consent-freshness has been enabled on agent , as specified in RFC7675 then restart stream_id will restore the local consent for that stream.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

Returns

TRUE on success FALSE on error

Since: 0.1.6


nice_agent_set_stream_name ()

gboolean
nice_agent_set_stream_name (NiceAgent *agent,
                            guint stream_id,
                            const gchar *name);

This function will assign a media type to a stream. The only values that can be used to produce a valid SDP are: "audio", "video", "text", "application", "image" and "message".

This is only useful when parsing and generating an SDP of the candidates.

See also: nice_agent_generate_local_sdp()

See also: nice_agent_parse_remote_sdp()

See also: nice_agent_get_stream_name()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream to change

 

name

The new name of the stream or NULL

 

Returns

TRUE if the name has been set. FALSE in case of error (invalid stream or duplicate name).

Since: 0.1.4


nice_agent_get_stream_name ()

const gchar *
nice_agent_get_stream_name (NiceAgent *agent,
                            guint stream_id);

This function will return the name assigned to a stream.

See also: nice_agent_set_stream_name()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream to change

 

Returns

The name of the stream. The name is only valid while the stream exists or until it changes through a call to nice_agent_set_stream_name().

Since: 0.1.4


nice_agent_get_default_local_candidate ()

NiceCandidate *
nice_agent_get_default_local_candidate
                               (NiceAgent *agent,
                                guint stream_id,
                                guint component_id);

This helper function will return the recommended default candidate to be used for non-ICE compatible clients. This will usually be the candidate with the lowest priority, since it will be the longest path but the one with the most chances of success.

This function is only useful in order to manually generate the local SDP

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

The candidate to be used as the default candidate, or NULL in case of error. Must be freed with nice_candidate_free() once done.


nice_agent_generate_local_sdp ()

gchar *
nice_agent_generate_local_sdp (NiceAgent *agent);

Generate an SDP string containing the local candidates and credentials for all streams and components in the agent.

The SDP will not contain any codec lines and the 'm' line will not list any payload types.

It is highly recommended to set names on the streams prior to calling this function. Unnamed streams will show up as '-' in the 'm' line, but the SDP will not be parseable with nice_agent_parse_remote_sdp() if a stream is unnamed.

The default candidate in the SDP will be selected based on the lowest priority candidate for the first component.

See also: nice_agent_set_stream_name()

See also: nice_agent_parse_remote_sdp()

See also: nice_agent_generate_local_stream_sdp()

See also: nice_agent_generate_local_candidate_sdp()

See also: nice_agent_get_default_local_candidate()

Parameters

agent

The NiceAgent Object

 

Returns

A string representing the local SDP. Must be freed with g_free() once done.

Since: 0.1.4


nice_agent_generate_local_stream_sdp ()

gchar *
nice_agent_generate_local_stream_sdp (NiceAgent *agent,
                                      guint stream_id,
                                      gboolean include_non_ice);

Generate an SDP string containing the local candidates and credentials for a stream.

The SDP will not contain any codec lines and the 'm' line will not list any payload types.

It is highly recommended to set the name of the stream prior to calling this function. Unnamed streams will show up as '-' in the 'm' line.

The default candidate in the SDP will be selected based on the lowest priority candidate.

See also: nice_agent_set_stream_name()

See also: nice_agent_parse_remote_stream_sdp()

See also: nice_agent_generate_local_sdp()

See also: nice_agent_generate_local_candidate_sdp()

See also: nice_agent_get_default_local_candidate()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

include_non_ice

Whether or not to include non ICE specific lines (m=, c= and a=rtcp: lines)

 

Returns

A string representing the local SDP for the stream. Must be freed with g_free() once done.

Since: 0.1.4


nice_agent_generate_local_candidate_sdp ()

gchar *
nice_agent_generate_local_candidate_sdp
                               (NiceAgent *agent,
                                NiceCandidate *candidate);

Generate an SDP string representing a local candidate.

See also: nice_agent_parse_remote_candidate_sdp()

See also: nice_agent_generate_local_sdp()

See also: nice_agent_generate_local_stream_sdp()

Parameters

agent

The NiceAgent Object

 

candidate

The candidate to generate

 

Returns

A string representing the SDP for the candidate. Must be freed with g_free() once done.

Since: 0.1.4


nice_agent_parse_remote_sdp ()

int
nice_agent_parse_remote_sdp (NiceAgent *agent,
                             const gchar *sdp);

Parse an SDP string and extracts candidates and credentials from it and sets them on the agent.

See also: nice_agent_set_stream_name()

See also: nice_agent_generate_local_sdp()

See also: nice_agent_parse_remote_stream_sdp()

See also: nice_agent_parse_remote_candidate_sdp()

Parameters

agent

The NiceAgent Object

 

sdp

The remote SDP to parse

 

Returns

The number of candidates added, negative on errors

Since: 0.1.4


nice_agent_parse_remote_stream_sdp ()

GSList *
nice_agent_parse_remote_stream_sdp (NiceAgent *agent,
                                    guint stream_id,
                                    const gchar *sdp,
                                    gchar **ufrag,
                                    gchar **pwd);

Parse an SDP string representing a single stream and extracts candidates and credentials from it.

See also: nice_agent_generate_local_stream_sdp()

See also: nice_agent_parse_remote_sdp()

See also: nice_agent_parse_remote_candidate_sdp()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream to parse

 

sdp

The remote SDP to parse

 

ufrag

Pointer to store the ice ufrag if non NULL. Must be freed with g_free() after use

 

pwd

Pointer to store the ice password if non NULL. Must be freed with g_free() after use

 

Returns

A GSList of candidates parsed from the SDP, or NULL in case of errors.

[element-type NiceCandidate][transfer full]

Since: 0.1.4


nice_agent_parse_remote_candidate_sdp ()

NiceCandidate *
nice_agent_parse_remote_candidate_sdp (NiceAgent *agent,
                                       guint stream_id,
                                       const gchar *sdp);

Parse an SDP string and extracts the candidate from it.

See also: nice_agent_generate_local_candidate_sdp()

See also: nice_agent_parse_remote_sdp()

See also: nice_agent_parse_remote_stream_sdp()

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream the candidate belongs to

 

sdp

The remote SDP to parse

 

Returns

The parsed candidate or NULL if there was an error.

Since: 0.1.4


nice_agent_get_io_stream ()

GIOStream *
nice_agent_get_io_stream (NiceAgent *agent,
                          guint stream_id,
                          guint component_id);

Gets a GIOStream wrapper around the given stream and component in agent . The I/O stream will be valid for as long as stream_id is valid. The GInputStream and GOutputStream implement GPollableInputStream and GPollableOutputStream.

This function may only be called on reliable NiceAgents. It is a programming error to try and create an I/O stream wrapper for an unreliable stream.

Parameters

agent

A NiceAgent

 

stream_id

The ID of the stream to wrap

 

component_id

The ID of the component to wrap

 

Returns

A GIOStream.

[transfer full]

Since: 0.1.5


nice_agent_get_selected_socket ()

GSocket *
nice_agent_get_selected_socket (NiceAgent *agent,
                                guint stream_id,
                                guint component_id);

Retreive the local socket associated with the selected candidate pair for media transmission for a given stream's component.

This is useful for adding ICE support to legacy applications that already have a protocol that maintains a connection. If the socket is duplicated before unrefing the agent, the application can take over and continue to use it. New applications are encouraged to use the built in libnice stream handling instead and let libnice handle the connection maintenance.

Users of this method are encouraged to not use a TURN relay or any kind of proxy, as in this case, the socket will not be available to the application because the packets are encapsulated.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

pointer to the GSocket, or NULL if there is no selected candidate or if the selected candidate is a relayed candidate.

[transfer full][nullable]

Since: 0.1.5


nice_agent_get_sockets ()

GPtrArray *
nice_agent_get_sockets (NiceAgent *agent,
                        guint stream_id,
                        guint component_id);

Each component can have multiple sockets, this is an API to retrieve them all to be able to set properties. Most of the sockets for a component are created when calling nice_agent_gather_candidates(), so this API should be called right after to able to set properties on the sockets before they are used.

These sockets can be a mix of UDP & TCP sockets depending on the compatibility mode and options that have been set.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

An array containing all of the sockets for this component. Free with g_ptr_array_unref() when done.

[element-type GSocket][transfer full]

Since: 0.1.17


nice_agent_get_component_state ()

NiceComponentState
nice_agent_get_component_state (NiceAgent *agent,
                                guint stream_id,
                                guint component_id);

Retrieves the current state of a component.

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

the NiceComponentState of the component and NICE_COMPONENT_STATE_FAILED if the component was invalid.

Since: 0.1.8


nice_agent_close_async ()

void
nice_agent_close_async (NiceAgent *agent,
                        GAsyncReadyCallback callback,
                        gpointer callback_data);

Asynchronously closes resources the agent has allocated on remote servers.

The agent will call the callback in the current GMainContext in which this function is called. The GAsyncResult in the callback can be ignored as this operation never fails.

Calling this function before freeing the agent makes sure the allocated relay ports aren't left behind on TURN server but properly removed.

Parameters

agent

The NiceAgent object

 

callback

A callback that will be called when the closing is complete.

[nullable]

callback_data

A pointer that will be passed to the callback.

[nullable]

Since: 0.1.16


nice_agent_consent_lost ()

gboolean
nice_agent_consent_lost (NiceAgent *agent,
                         guint stream_id,
                         guint component_id);

Notifies the agent that consent to receive has been revoked. This will cause the component to fail with 403 'Forbidden' all incoming STUN binding requests as specified in RFC 7675.

A stream with a component in the consent-lost state can be reused by performing an ice restart with nice_agent_restart() or nice_agent_restart_stream().

Calling the function only has an effect when agent has been created with NICE_AGENT_OPTION_CONSENT_FRESHNESS .

Parameters

agent

The NiceAgent Object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

Returns

FALSE if the stream or component could not be found or consent freshness is not enabled, TRUE otherwise

Since: 0.1.19


nice_component_state_to_string ()

const gchar *
nice_component_state_to_string (NiceComponentState state);

Returns a string representation of the state, generally to use in debug messages.

Parameters

state

a NiceComponentState

 

Returns

a string representation of state .

[transfer none]

Since: 0.1.6


NICE_CHECK_VERSION()

#define             NICE_CHECK_VERSION(major, minor, micro)

Macro that returns TRUE if the version if libnice that you are compiling against is greater or equal to the argument

Parameters

major

The major numbe of the version

 

minor

The major numbe of the version

 

micro

The major numbe of the version

 

Since: 0.1.20

Types and Values

NiceAgent

typedef struct _NiceAgent NiceAgent;

The NiceAgent is the main GObject of the libnice library and represents the ICE agent.


enum NiceComponentState

An enum representing the state of a component.

See also: “component-state-changed”

Members

NICE_COMPONENT_STATE_DISCONNECTED

No activity scheduled

 

NICE_COMPONENT_STATE_GATHERING

Gathering local candidates

 

NICE_COMPONENT_STATE_CONNECTING

Establishing connectivity

 

NICE_COMPONENT_STATE_CONNECTED

At least one working candidate pair

 

NICE_COMPONENT_STATE_READY

ICE concluded, candidate pair selection is now final

 

NICE_COMPONENT_STATE_FAILED

Connectivity checks have been completed, but connectivity was not established

 

NICE_COMPONENT_STATE_LAST

Dummy state

 

enum NiceComponentType

Convenience enum representing the type of a component for use as the component_id for RTP/RTCP usages.

Example 2. Example of use.

1
nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);

Members

NICE_COMPONENT_TYPE_RTP

RTP Component type

 

NICE_COMPONENT_TYPE_RTCP

RTCP Component type

 

enum NiceProxyType

An enum to specify which proxy type to use for relaying. Note that the proxies will only be used with TCP TURN relaying.

See also: “proxy-type”

Members

NICE_PROXY_TYPE_NONE

Do not use a proxy

 

NICE_PROXY_TYPE_SOCKS5

Use a SOCKS5 proxy

 

NICE_PROXY_TYPE_HTTP

Use an HTTP proxy

 

NICE_PROXY_TYPE_LAST

Dummy last proxy type

 

Since: 0.0.4


enum NiceNominationMode

An enum to specity the kind of nomination mode to use by the agent, as described in RFC 5245. Two modes exists, regular and aggressive. They differ by the way the controlling agent chooses to put the USE-CANDIDATE attribute in its STUN messages. The aggressive mode is supposed to nominate a pair faster, than the regular mode, potentially causing the nominated pair to change until the connection check completes.

Members

NICE_NOMINATION_MODE_REGULAR

Regular nomination mode

 

NICE_NOMINATION_MODE_AGGRESSIVE

Aggressive nomination mode

 

Since: 0.1.15


enum NiceCompatibility

An enum to specify which compatible specifications the NiceAgent should use. Use with nice_agent_new()

NICE_COMPATIBILITY_DRAFT19 is deprecated and should not be used in newly-written code. It is kept for compatibility reasons and represents the same compatibility as NICE_COMPATIBILITY_RFC5245

If NICE_COMPATIBILITY_RFC5245 compatibility mode is used for a non-reliable agent, then ICE-UDP will be used with higher priority and ICE-TCP will also be used when the UDP connectivity fails. If it is used with a reliable agent, then ICE-UDP will be used with the TCP-Over-UDP (PseudoTcpSocket) if ICE-TCP fails and ICE-UDP succeeds.

Members

NICE_COMPATIBILITY_RFC5245

Use compatibility with the RFC5245 ICE-UDP specs and RFC6544 ICE-TCP specs

 

NICE_COMPATIBILITY_DRAFT19

Use compatibility for ICE Draft 19 specs

 

NICE_COMPATIBILITY_GOOGLE

Use compatibility for Google Talk specs

 

NICE_COMPATIBILITY_MSN

Use compatibility for MSN Messenger specs

 

NICE_COMPATIBILITY_WLM2009

Use compatibility with Windows Live Messenger 2009

 

NICE_COMPATIBILITY_OC2007

Use compatibility with Microsoft Office Communicator 2007

 

NICE_COMPATIBILITY_OC2007R2

Use compatibility with Microsoft Office Communicator 2007 R2

 

NICE_COMPATIBILITY_LAST

Dummy last compatibility mode

 

NiceInputMessage

typedef struct {
  GInputVector *buffers;
  gint n_buffers;  /* may be -1 to indicate @buffers is NULL-terminated */
  NiceAddress *from;  /* return location for address of message sender */
  gsize length;  /* sum of the lengths of @buffers */
} NiceInputMessage;

Represents a single message received off the network. For reliable connections, this is essentially just an array of buffers (specifically, from can be ignored). for non-reliable connections, it represents a single packet as received from the OS.

n_buffers may be -1 to indicate that buffers is terminated by a GInputVector with a NULL buffer pointer.

By providing arrays of NiceInputMessages to functions like nice_agent_recv_messages(), multiple messages may be received with a single call, which is more efficient than making multiple calls in a loop. In this manner, nice_agent_recv_messages() is analogous to recvmmsg(); and NiceInputMessage to struct mmsghdr.

Members

GInputVector *buffers;

unowned array of GInputVector buffers to store data in for this message.

[array length=n_buffers]

gint n_buffers;

number of GInputVectors in buffers , or -1 to indicate buffers is NULL-terminated

 

NiceAddress *from;

return location to store the address of the peer who transmitted the message, or NULL.

[allow-none]

gsize length;

total number of valid bytes contiguously stored in buffers

 

Since: 0.1.5


NiceOutputMessage

typedef struct {
  GOutputVector *buffers;
  gint n_buffers;
} NiceOutputMessage;

Represents a single message to transmit on the network. For reliable connections, this is essentially just an array of buffer. for non-reliable connections, it represents a single packet to send to the OS.

n_buffers may be -1 to indicate that buffers is terminated by a GOutputVector with a NULL buffer pointer.

By providing arrays of NiceOutputMessages to functions like nice_agent_send_messages_nonblocking(), multiple messages may be transmitted with a single call, which is more efficient than making multiple calls in a loop. In this manner, nice_agent_send_messages_nonblocking() is analogous to sendmmsg(); and NiceOutputMessage to struct mmsghdr.

Members

GOutputVector *buffers;

unowned array of GOutputVector buffers which contain data to transmit for this message.

[array length=n_buffers]

gint n_buffers;

number of GOutputVectors in buffers , or -1 to indicate buffers is NULL-terminated

 

Since: 0.1.5


NICE_AGENT_MAX_REMOTE_CANDIDATES

#define NICE_AGENT_MAX_REMOTE_CANDIDATES    25

NICE_AGENT_MAX_REMOTE_CANDIDATES has been deprecated since version 0.1.20 and should not be used in newly-written code.

Replace with dynamic value based on the “max-connectivity-checks” property

Was a limit on the number of remote candidates one can set, but is no longer used by libnice itself.


enum NiceAgentOption

These are options that can be passed to nice_agent_new_full(). They set various properties on the agent. Not including them sets the property to the other value.

Members

NICE_AGENT_OPTION_NONE

No enabled options (Since: 0.1.19)

 

NICE_AGENT_OPTION_REGULAR_NOMINATION

Enables regular nomination, default is aggrssive mode (see NiceNominationMode).

 

NICE_AGENT_OPTION_RELIABLE

Enables reliable mode, possibly using PseudoTCP, * see nice_agent_new_reliable().

 

NICE_AGENT_OPTION_LITE_MODE

Enable lite mode

 

NICE_AGENT_OPTION_ICE_TRICKLE

Enable ICE trickle mode

 

NICE_AGENT_OPTION_SUPPORT_RENOMINATION

Enable renomination triggered by NOMINATION STUN attribute proposed here: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00

 

NICE_AGENT_OPTION_CONSENT_FRESHNESS

Enable RFC 7675 consent freshness support. (Since: 0.1.19)

 

NICE_AGENT_OPTION_BYTESTREAM_TCP

Use bytestream mode for reliable TCP connections. (Since: 0.1.20)

 

Since: 0.1.15

Property Details

The “bytestream-tcp” property

  “bytestream-tcp”           gboolean

This property defines whether receive/send operations over a TCP socket, in reliable mode, are considered as packetized or as bytestream. In unreliable mode, every send/recv is considered as packetized, and this property is ignored and cannot be set.

In reliable mode, this property will always return TRUE in the NICE_COMPATIBILITY_GOOGLE compatibility mode.

If the property is TRUE, the stream is considered in bytestream mode and data can be read with any receive size. If the property is FALSE, then the stream is considered packetized and each receive will return one packet of the same size as what was sent from the peer. If in packetized mode, then doing a receive with a size smaller than the packet, will cause the remaining bytes in the packet to be dropped, breaking the reliability of the stream.

Flags: Read / Write

Default value: FALSE

Since: 0.1.8


The “compatibility” property

  “compatibility”            guint

The Nice agent can work in various compatibility modes depending on what the application/peer needs.

See also: NiceCompatibility

Flags: Read / Write / Construct Only

Allowed values: <= 5

Default value: 0


The “consent-freshness” property

  “consent-freshness”        gboolean

Whether to perform periodic consent freshness checks as specified in RFC 7675. When TRUE, the agent will periodically send binding requests to the peer to maintain the consent to send with the peer. On receipt of any authenticated error response, a component will immediately move to the failed state.

Setting this property to TRUE implies that 'keepalive-conncheck' should be TRUE as well.

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 0.1.19


The “controlling-mode” property

  “controlling-mode”         gboolean

Whether the agent has the controlling role. This property should be modified before gathering candidates, any modification occuring later will be hold until ICE is restarted.

Flags: Read / Write

Default value: FALSE


The “force-relay” property

  “force-relay”              gboolean

Force all traffic to go through a relay for added privacy, this allows hiding the local IP address. When this is enabled, so local candidates are available before relay servers have been set with nice_agent_set_relay_info().

Flags: Read / Write

Default value: FALSE

Since: 0.1.14


The “full-mode” property

  “full-mode”                gboolean

Whether agent runs in ICE full mode.

Flags: Read / Write / Construct Only

Default value: TRUE


The “ice-tcp” property

  “ice-tcp”                  gboolean

Whether the agent should use ICE-TCP when gathering candidates. If the option is disabled, no TCP candidates will be generated. If the agent is in reliable mode, then pseudotcp will need to be used over UDP candidates.

This option should be set before gathering candidates and should not be modified afterwards.

The “ice-tcp” property can be set at the same time as the “ice-udp” property, but both cannot be unset at the same time. If “ice-udp” is set to FALSE, then this property cannot be set to FALSE as well.

ICE-TCP is only supported for NICE_COMPATIBILITY_RFC5245, NICE_COMPATIBILITY_OC2007 and NICE_COMPATIBILITY_OC2007R2 compatibility modes.

Flags: Read / Write

Default value: TRUE

Since: 0.1.8


The “ice-trickle” property

  “ice-trickle”              gboolean

Whether to perform Trickle ICE as per draft-ietf-ice-trickle-ice-21. When TRUE, the agent will postpone changing a component state to NICE_COMPONENT_STATE_FAILED until nice_agent_peer_candidate_gathering_done() has been called with the ID of the component's stream.

Flags: Read / Write

Default value: FALSE

Since: 0.1.16


The “ice-udp” property

  “ice-udp”                  gboolean

Whether the agent should use ICE-UDP when gathering candidates. If the option is disabled, no UDP candidates will be generated. If the agent is in reliable mode, then pseudotcp will not be used since pseudotcp works on top of UDP candidates.

This option should be set before gathering candidates and should not be modified afterwards.

The “ice-udp” property can be set at the same time as the “ice-tcp” property, but both cannot be unset at the same time. If “ice-tcp” is set to FALSE, then this property cannot be set to FALSE as well.

Flags: Read / Write

Default value: TRUE

Since: 0.1.8


The “idle-timeout” property

  “idle-timeout”             guint

A final timeout in msec, launched when the agent becomes idle, before stopping its activity.

This timer will delay the decision to set a component as failed. This delay is added to reduce the chance to see the agent receiving new stun activity just after the conncheck list has been declared failed (some valid pairs, no nominated pair, and no in-progress pairs), reactiviting conncheck activity, and causing a (valid) state transitions like that: connecting -> failed -> connecting -> connected -> ready. Such transitions are not buggy per-se, but may break the test-suite, that counts precisely the number of time each state has been set, and doesnt expect these transcient failed states.

This timer is also useful when the agent is in controlled mode and the other controlling peer takes some time to elect its nominated pair (this may be the case for SfB peers).

This timer is *NOT* part if the RFC5245, as this situation is not covered in sect 8.1.2 "Updating States", but deals with a real use-case, where a controlled agent can not wait forever for the other peer to make a nomination decision.

Also note that the value of this timeout will not delay the emission of 'connected' and 'ready' agent signals, and will not slow down the behaviour of the agent when the peer agent works in a timely manner.

Flags: Read / Write / Construct

Allowed values: [50,60000]

Default value: 5000

Since: 0.1.17


The “keepalive-conncheck” property

  “keepalive-conncheck”      gboolean

Use binding requests as keepalives instead of binding indications. This means that the keepalives may time out which will change the component state to NICE_COMPONENT_STATE_FAILED.

Enabing this is a slight violation of RFC 5245 section 10 which recommends using Binding Indications for keepalives.

This is always enabled if the compatibility mode is NICE_COMPATIBILITY_GOOGLE.

This is always enabled if the 'consent-freshness' property is TRUE

Flags: Read / Write

Default value: FALSE

Since: 0.1.8


The “main-context” property

  “main-context”             gpointer

A GLib main context is needed for all timeouts used by libnice. This is a property being set by the nice_agent_new() call.

Flags: Read / Write / Construct Only


The “max-connectivity-checks” property

  “max-connectivity-checks”  guint

Upper limit for the total number of connectivity checks performed.

Flags: Read / Write

Default value: 0


The “nomination-mode” property

  “nomination-mode”          NiceNominationMode

The nomination mode used in the ICE specification for describing the selection of valid pairs to be used upstream.

See also: NiceNominationMode

Flags: Read / Write / Construct Only

Default value: NICE_NOMINATION_MODE_AGGRESSIVE

Since: 0.1.15


The “proxy-extra-headers” property

  “proxy-extra-headers”      GHashTable *

Optional extra headers to append to the HTTP proxy CONNECT request. Provided as key/value-pairs in hash table corresponding to header-name/header-value.

[type GLib.HashTable(utf8,utf8)]

Flags: Read / Write

Since: 0.1.20


The “proxy-ip” property

  “proxy-ip”                 gchar *

The proxy server IP used to bypass a proxy firewall

Flags: Read / Write

Default value: NULL

Since: 0.0.4


The “proxy-password” property

  “proxy-password”           gchar *

The password used to authenticate with the proxy

Flags: Read / Write

Default value: NULL

Since: 0.0.4


The “proxy-port” property

  “proxy-port”               guint

The proxy server port used to bypass a proxy firewall

Flags: Read / Write

Allowed values: [1,65536]

Default value: 1

Since: 0.0.4


The “proxy-type” property

  “proxy-type”               guint

The type of proxy set in the proxy-ip property

Flags: Read / Write

Allowed values: <= 2

Default value: 0

Since: 0.0.4


The “proxy-username” property

  “proxy-username”           gchar *

The username used to authenticate with the proxy

Flags: Read / Write

Default value: NULL

Since: 0.0.4


The “reliable” property

  “reliable”                 gboolean

Whether the agent is providing a reliable transport of messages (through ICE-TCP or PseudoTCP over ICE-UDP)

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 0.0.11


The “stun-initial-timeout” property

  “stun-initial-timeout”     guint

The initial timeout (msecs) of the STUN binding requests used in the gathering stage, to find our local candidates. This property is described as 'RTO' in the RFC 5389 and RFC 5245. This timeout is doubled for each retransmission, until “stun-max-retransmissions” have been done, with an exception for the last restransmission, where the timeout is divided by two instead (RFC 5389 indicates that a customisable multiplier 'Rm' to 'RTO' should be used).

Flags: Read / Write / Construct

Allowed values: [20,9999]

Default value: 500

Since: 0.1.15


The “stun-max-retransmissions” property

  “stun-max-retransmissions” guint

The maximum number of retransmissions of the STUN binding requests used in the gathering stage, to find our local candidates, and used in the connection check stage, to test the validity of each constructed pair. This property is described as 'Rc' in the RFC 5389, with a default value of 7. The timeout of each STUN request is doubled for each retransmission, so the choice of this value has a direct impact on the time needed to move from the CONNECTED state to the READY state, and on the time needed to complete the GATHERING state.

Flags: Read / Write / Construct

Allowed values: [1,99]

Default value: 3

Since: 0.1.15


The “stun-pacing-timer” property

  “stun-pacing-timer”        guint

Timer 'Ta' (msecs) used in the IETF ICE specification for pacing candidate gathering and sending of connectivity checks.

Flags: Read / Write / Construct

Allowed values: >= 1

Default value: 20


The “stun-reliable-timeout” property

  “stun-reliable-timeout”    guint

The initial timeout of the STUN binding requests used for a reliable timer.

Flags: Read / Write / Construct

Allowed values: [20,99999]

Default value: 2000

Since: 0.1.15


The “stun-server” property

  “stun-server”              gchar *

The IP address (or hostname) of the STUN server to use.

Flags: Read / Write

Default value: NULL


The “stun-server-port” property

  “stun-server-port”         guint

Port of the STUN server used to gather server-reflexive candidates.

Flags: Read / Write

Allowed values: [1,65536]

Default value: 1


The “support-renomination” property

  “support-renomination”     gboolean

Support RENOMINATION STUN attribute proposed here: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00 As soon as RENOMINATION attribute is received from remote candidate's address, corresponding candidates pair gets selected. This is specific to Google Chrome/libWebRTC.

Flags: Read / Write

Default value: FALSE


The “upnp” property

  “upnp”                     gboolean

Whether the agent should use UPnP to open a port in the router and get the external IP

Flags: Read / Write / Construct

Default value: TRUE

Since: 0.0.7


The “upnp-timeout” property

  “upnp-timeout”             guint

The maximum amount of time (in milliseconds) to wait for UPnP discovery to finish before signaling the “candidate-gathering-done” signal

Flags: Read / Write / Construct

Allowed values: [100,60000]

Default value: 200

Since: 0.0.7

Signal Details

The “candidate-gathering-done” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               gpointer   user_data)

This signal is fired whenever a stream has finished gathering its candidates after a call to nice_agent_gather_candidates()

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “component-state-changed” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               guint      component_id,
               guint      state,
               gpointer   user_data)

This signal is fired whenever a component’s state changes. There are many valid state transitions.

State transition diagram

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

state

The new NiceComponentState of the component

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “initial-binding-request-received” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               gpointer   user_data)

This signal is fired when we received our first binding request from the peer.

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “new-candidate” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               guint      component_id,
               gchar     *foundation,
               gpointer   user_data)

This signal is fired when the agent discovers a new local candidate. When this signal is emitted, a matching “new-candidate-full” is also emitted with the candidate.

See also: “candidate-gathering-done”, “new-candidate-full”

NiceAgent::new-candidate has been deprecated since version 0.1.8 and should not be used in newly-written code.

Use “new-candidate-full”

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

foundation

The foundation of the new candidate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “new-candidate-full” signal

void
user_function (NiceAgent     *agent,
               NiceCandidate *candidate,
               gpointer       user_data)

This signal is fired when the agent discovers a new local candidate. When this signal is emitted, a matching “new-candidate” is also emitted with the candidate's foundation.

See also: “candidate-gathering-done”, “new-candidate”

Parameters

agent

The NiceAgent object

 

candidate

The new NiceCandidate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.1.8


The “new-remote-candidate” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               guint      component_id,
               gchar     *foundation,
               gpointer   user_data)

This signal is fired when the agent discovers a new remote candidate. This can happen with peer reflexive candidates. When this signal is emitted, a matching “new-remote-candidate-full” is also emitted with the candidate.

See also: “new-remote-candidate-full”

NiceAgent::new-remote-candidate has been deprecated since version 0.1.8 and should not be used in newly-written code.

Use “new-remote-candidate-full”

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

foundation

The foundation of the new candidate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “new-remote-candidate-full” signal

void
user_function (NiceAgent     *agent,
               NiceCandidate *candidate,
               gpointer       user_data)

This signal is fired when the agent discovers a new remote candidate. This can happen with peer reflexive candidates. When this signal is emitted, a matching “new-remote-candidate” is also emitted with the candidate's foundation.

See also: “new-remote-candidate”

Parameters

agent

The NiceAgent object

 

candidate

The new NiceCandidate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.1.8


The “new-selected-pair” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               guint      component_id,
               gchar     *lfoundation,
               gchar     *rfoundation,
               gpointer   user_data)

This signal is fired once a candidate pair is selected for data transfer for a stream's component This is emitted along with “new-selected-pair-full” which has the whole candidate, the Foundation of a Candidate is not a unique identifier.

See also: “new-selected-pair-full”

NiceAgent::new-selected-pair has been deprecated since version 0.1.8 and should not be used in newly-written code.

Use “new-selected-pair-full”

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

lfoundation

The local foundation of the selected candidate pair

 

rfoundation

The remote foundation of the selected candidate pair

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “new-selected-pair-full” signal

void
user_function (NiceAgent     *agent,
               guint          stream_id,
               guint          component_id,
               NiceCandidate *lcandidate,
               NiceCandidate *rcandidate,
               gpointer       user_data)

This signal is fired once a candidate pair is selected for data transfer for a stream's component. This is emitted along with “new-selected-pair”.

See also: “new-selected-pair”

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

lcandidate

The local NiceCandidate of the selected candidate pair

 

rcandidate

The remote NiceCandidate of the selected candidate pair

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.1.8


The “reliable-transport-writable” signal

void
user_function (NiceAgent *agent,
               guint      stream_id,
               guint      component_id,
               gpointer   user_data)

This signal is fired on the reliable NiceAgent when the underlying reliable transport becomes writable. This signal is only emitted when the nice_agent_send() function returns less bytes than requested to send (or -1) and once when the connection is established.

Parameters

agent

The NiceAgent object

 

stream_id

The ID of the stream

 

component_id

The ID of the component

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.0.11


The “streams-removed” signal

void
user_function (NiceAgent           *agent,
               _NiceAgentStreamIds *stream_ids,
               gpointer             user_data)

This signal is fired whenever one or more streams are removed from the agent .

Parameters

agent

The NiceAgent object

 

stream_ids

An array of unsigned integer stream IDs, ending with a 0 ID.

[array zero-terminated=1][element-type uint]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.1.5

See Also

NiceCandidate, NiceAddress