NiceAgent

NiceAgent — ICE agent API implementation

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <agent.h>

                    NiceAgent;
enum                NiceComponentState;
enum                NiceComponentType;
enum                NiceProxyType;
enum                NiceCompatibility;
void                (*NiceAgentRecvFunc)                (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         guint len,
                                                         gchar *buf,
                                                         gpointer user_data);
#define             NICE_AGENT_MAX_REMOTE_CANDIDATES
NiceAgent *         nice_agent_new                      (GMainContext *ctx,
                                                         NiceCompatibility compat);
NiceAgent *         nice_agent_new_reliable             (GMainContext *ctx,
                                                         NiceCompatibility compat);
gboolean            nice_agent_add_local_address        (NiceAgent *agent,
                                                         NiceAddress *addr);
guint               nice_agent_add_stream               (NiceAgent *agent,
                                                         guint n_components);
void                nice_agent_remove_stream            (NiceAgent *agent,
                                                         guint stream_id);
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);
gboolean            nice_agent_gather_candidates        (NiceAgent *agent,
                                                         guint stream_id);
gboolean            nice_agent_set_remote_credentials   (NiceAgent *agent,
                                                         guint stream_id,
                                                         const gchar *ufrag,
                                                         const gchar *pwd);
gboolean            nice_agent_get_local_credentials    (NiceAgent *agent,
                                                         guint stream_id,
                                                         gchar **ufrag,
                                                         gchar **pwd);
int                 nice_agent_set_remote_candidates    (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         const GSList *candidates);
GSList *            nice_agent_get_remote_candidates    (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id);
GSList *            nice_agent_get_local_candidates     (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id);
gint                nice_agent_send                     (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         guint len,
                                                         const gchar *buf);
gboolean            nice_agent_attach_recv              (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         GMainContext *ctx,
                                                         NiceAgentRecvFunc func,
                                                         gpointer data);
gboolean            nice_agent_set_selected_pair        (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         const gchar *lfoundation,
                                                         const gchar *rfoundation);
gboolean            nice_agent_set_selected_remote_candidate
                                                        (NiceAgent *agent,
                                                         guint stream_id,
                                                         guint component_id,
                                                         NiceCandidate *candidate);
void                nice_agent_set_stream_tos           (NiceAgent *agent,
                                                         guint stream_id,
                                                         gint tos);
void                nice_agent_set_software             (NiceAgent *agent,
                                                         const gchar *software);
gboolean            nice_agent_restart                  (NiceAgent *agent);

Object Hierarchy

  GObject
   +----NiceAgent

Properties

  "compatibility"            guint                 : Read / Write / Construct Only
  "controlling-mode"         gboolean              : Read / Write
  "full-mode"                gboolean              : Read / Write / Construct Only
  "main-context"             gpointer              : Read / Write / Construct Only
  "max-connectivity-checks"  guint                 : Read / Write
  "proxy-ip"                 gchar*                : Read / Write
  "proxy-password"           gchar*                : Read / Write
  "proxy-port"               guint                 : Read / Write
  "proxy-type"               guint                 : Read / Write
  "proxy-username"           gchar*                : Read / Write
  "reliable"                 gboolean              : Read / Write / Construct Only
  "stun-pacing-timer"        guint                 : Read / Write / Construct Only
  "stun-server"              gchar*                : Read / Write
  "stun-server-port"         guint                 : Read / Write
  "upnp"                     gboolean              : Read / Write / Construct
  "upnp-timeout"             guint                 : Read / Write / Construct

Signals

  "candidate-gathering-done"                       : Run Last
  "component-state-changed"                        : Run Last
  "initial-binding-request-received"               : Run Last
  "new-candidate"                                  : Run Last
  "new-remote-candidate"                           : Run Last
  "new-selected-pair"                              : Run Last
  "reliable-transport-writable"                    : Run Last

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.

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
guint stream_id;
gchar buffer[] = "hello world!";
GSList *lcands = NULL;

// Create a nice agent
NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);

// 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 to the component to receive the 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);

// ... Send local candidates to the peer and set the peer's remote candidates
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

// Destroy the object
g_object_unref(agent);


Details

NiceAgent

typedef struct _NiceAgent NiceAgent;

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


enum NiceComponentState

typedef enum
{
  NICE_COMPONENT_STATE_DISCONNECTED,
  NICE_COMPONENT_STATE_GATHERING,
  NICE_COMPONENT_STATE_CONNECTING,
  NICE_COMPONENT_STATE_CONNECTED,
  NICE_COMPONENT_STATE_READY,
  NICE_COMPONENT_STATE_FAILED,
  NICE_COMPONENT_STATE_LAST
} NiceComponentState;

An enum representing the state of a component.

See also: "component-state-changed"

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

typedef enum
{
  NICE_COMPONENT_TYPE_RTP = 1,
  NICE_COMPONENT_TYPE_RTCP = 2
} 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);


NICE_COMPONENT_TYPE_RTP

RTP Component type

NICE_COMPONENT_TYPE_RTCP

RTCP Component type

enum NiceProxyType

typedef enum
{
  NICE_PROXY_TYPE_NONE = 0,
  NICE_PROXY_TYPE_SOCKS5,
  NICE_PROXY_TYPE_HTTP,
  NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
} 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"

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 NiceCompatibility

typedef enum
{
  NICE_COMPATIBILITY_RFC5245 = 0,
  NICE_COMPATIBILITY_GOOGLE,
  NICE_COMPATIBILITY_MSN,
  NICE_COMPATIBILITY_WLM2009,
  NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
  NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_WLM2009,
} NiceCompatibility;

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

Warning

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

NICE_COMPATIBILITY_RFC5245

Use compatibility with the RFC5245 ICE 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_DRAFT19

Use compatibility for ICE Draft 19 specs

NICE_COMPATIBILITY_LAST

Dummy last compatibility mode

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

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_MAX_REMOTE_CANDIDATES

#define NICE_AGENT_MAX_REMOTE_CANDIDATES    25

A hard limit for the number of remote candidates. This limit is enforced to protect against malevolent remote clients.


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()

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, which uses PseudoTcpSocket to assure reliability of the messages. The returned object must be freed with g_object_unref()

See also: "reliable-transport-writable"

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_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()

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_add_stream ()

guint               nice_agent_add_stream               (NiceAgent *agent,
                                                         guint n_components);

Adds a data stream to agent containing n_components components.

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

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.

agent :

The NiceAgent Object

stream_id :

The ID of the stream

component_id :

The ID of the component

server_ip :

The IP 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_gather_candidates ()

gboolean            nice_agent_gather_candidates        (NiceAgent *agent,
                                                         guint stream_id);

Start the candidate gathering process. Once done, "candidate-gathering-done" is called for the stream

agent :

The NiceAgent Object

stream_id :

The id of the stream to start

Returns :

FALSE if there were no local addresses and they couldn't be discovered. In this case, call nice_agent_add_local_address() first. See also: nice_agent_add_local_address()

Note

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.

Note

Stream credentials do not override per-candidate credentials if set

agent :

The NiceAgent Object

stream_id :

The ID of the stream

ufrag :

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

pwd :

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

agent :

The NiceAgent Object

stream_id :

The ID of the stream

ufrag :

a pointer to a NULL-terminated string containing an ICE username fragment [OUT]. This string must be freed with g_free()

pwd :

a pointer to a NULL-terminated string containing an ICE password [OUT] This string must be freed with g_free()

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.

Note

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()

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 GList of NiceCandidate items describing each candidate to add

Returns :

The number of candidates added, negative on errors (memory allocation or if the local candidates are not done gathering yet)

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

Note

The caller owns the returned GSList but not 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.

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

nice_agent_get_local_candidates ()

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

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

Note

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.

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

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.

Note

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

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

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

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.

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.

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

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.

Note

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.

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.

agent :

The NiceAgent Object

Returns :

TRUE on success FALSE on error

Property Details

The "compatibility" property

  "compatibility"            guint                 : Read / Write / Construct Only

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

See also: NiceCompatibility

Allowed values: <= 3

Default value: 0


The "controlling-mode" property

  "controlling-mode"         gboolean              : Read / Write

Whether the agent is in controlling mode.

Default value: FALSE


The "full-mode" property

  "full-mode"                gboolean              : Read / Write / Construct Only

Whether agent runs in ICE full mode.

Default value: TRUE


The "main-context" property

  "main-context"             gpointer              : Read / Write / Construct Only

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


The "max-connectivity-checks" property

  "max-connectivity-checks"  guint                 : Read / Write

Upper limit for the total number of connectivity checks performed.

Default value: 0


The "proxy-ip" property

  "proxy-ip"                 gchar*                : Read / Write

The proxy server IP used to bypass a proxy firewall

Default value: NULL

Since 0.0.4


The "proxy-password" property

  "proxy-password"           gchar*                : Read / Write

The password used to authenticate with the proxy

Default value: NULL

Since 0.0.4


The "proxy-port" property

  "proxy-port"               guint                 : Read / Write

The proxy server port used to bypass a proxy firewall

Allowed values: [1,65536]

Default value: 1

Since 0.0.4


The "proxy-type" property

  "proxy-type"               guint                 : Read / Write

The type of proxy set in the proxy-ip property

Allowed values: <= 2

Default value: 0

Since 0.0.4


The "proxy-username" property

  "proxy-username"           gchar*                : Read / Write

The username used to authenticate with the proxy

Default value: NULL

Since 0.0.4


The "reliable" property

  "reliable"                 gboolean              : Read / Write / Construct Only

Whether the agent should use PseudoTcp to ensure a reliable transport of messages

Default value: FALSE

Since 0.0.11


The "stun-pacing-timer" property

  "stun-pacing-timer"        guint                 : Read / Write / Construct Only

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

Allowed values: >= 1

Default value: 20


The "stun-server" property

  "stun-server"              gchar*                : Read / Write

The STUN server used to obtain server-reflexive candidates.

Default value: NULL


The "stun-server-port" property

  "stun-server-port"         guint                 : Read / Write

The STUN server used to obtain server-reflexive candidates.

Allowed values: [1,65536]

Default value: 1


The "upnp" property

  "upnp"                     gboolean              : Read / Write / Construct

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

Default value: TRUE

Since 0.0.7


The "upnp-timeout" property

  "upnp-timeout"             guint                 : Read / Write / Construct

The maximum amount of time to wait for UPnP discovery to finish before signaling the "candidate-gathering-done" signal

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)      : Run Last

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

agent :

The NiceAgent object

stream_id :

The ID of the stream

user_data :

user data set when the signal handler was connected.

The "component-state-changed" signal

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

This signal is fired whenever a component's state changes

agent :

The NiceAgent object

stream_id :

The ID of the stream

component_id :

The ID of the component

state :

The NiceComponentState of the component

user_data :

user data set when the signal handler was connected.

The "initial-binding-request-received" signal

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

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

agent :

The NiceAgent object

stream_id :

The ID of the stream

user_data :

user data set when the signal handler was connected.

The "new-candidate" signal

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

This signal is fired when the agent discovers a new candidate

See also: "candidate-gathering-done"

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.

The "new-remote-candidate" signal

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

This signal is fired when the agent discovers a new remote candidate. This can happen with peer reflexive candidates.

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.

The "new-selected-pair" signal

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

This signal is fired once a candidate pair is selected for data transfer for a stream's component

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.

The "reliable-transport-writable" signal

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

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.

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.

Since 0.0.11

See Also

NiceAddress