|
|
|
libnice Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
#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);
void nice_agent_set_port_range (NiceAgent *agent,
guint stream_id,
guint component_id,
guint min_port,
guint max_port);
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);
"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
"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
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); |
typedef struct _NiceAgent NiceAgent;
The NiceAgent is the main GObject of the libnice library and represents the ICE agent.
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"
| No activity scheduled | |
| Gathering local candidates | |
| Establishing connectivity | |
| At least one working candidate pair | |
| ICE concluded, candidate pair selection is now final | |
| Connectivity checks have been completed, but connectivity was not established | |
| Dummy state |
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.
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"
| Do not use a proxy | |
| Use a SOCKS5 proxy | |
| Use an HTTP proxy | |
| Dummy last proxy type |
Since 0.0.4
typedef enum
{
NICE_COMPATIBILITY_RFC5245 = 0,
NICE_COMPATIBILITY_GOOGLE,
NICE_COMPATIBILITY_MSN,
NICE_COMPATIBILITY_WLM2009,
NICE_COMPATIBILITY_OC2007,
NICE_COMPATIBILITY_OC2007R2,
NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_OC2007R2,
} 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
| Use compatibility with the RFC5245 ICE specs | |
| Use compatibility for Google Talk specs | |
| Use compatibility for MSN Messenger specs | |
| Use compatibility with Windows Live Messenger 2009 | |
| Use compatibility with Microsoft Office Communicator 2007 | |
| Use compatibility with Microsoft Office Communicator 2007 R2 | |
| Use compatibility for ICE Draft 19 specs | |
| Dummy last compatibility mode |
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
|
The NiceAgent Object |
|
The id of the stream |
|
The id of the component of the stream which received the data |
|
The length of the data |
|
The buffer containing the data received |
|
The user data set in nice_agent_attach_recv()
|
#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.
NiceAgent * nice_agent_new (GMainContext *ctx,NiceCompatibility compat);
Create a new NiceAgent.
The returned object must be freed with g_object_unref()
|
The Glib Mainloop Context to use for timers |
|
The compatibility mode of the agent |
Returns : |
The new agent GObject |
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"
|
The Glib Mainloop Context to use for timers |
|
The compatibility mode of the agent |
Returns : |
The new agent GObject |
Since 0.0.11
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()
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()
|
The NiceAgent Object |
|
The ID of the stream |
|
The ID of the component |
|
The minimum port to use |
|
The maximum port to use |
guint nice_agent_add_stream (NiceAgent *agent,guint n_components);
Adds a data stream to agent containing n_components components.
|
The NiceAgent Object |
|
The number of components to add to the stream |
Returns : |
The ID of the new stream, 0 on failure |
void nice_agent_remove_stream (NiceAgent *agent,guint stream_id);
Remove and free a previously created data stream from agent
|
The NiceAgent Object |
|
The ID of the stream to remove |
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.
|
The NiceAgent Object |
|
The ID of the stream |
|
The ID of the component |
|
The IP address of the TURN server |
|
The port of the TURN server |
|
The TURN username to use for the allocate |
|
The TURN password to use for the allocate |
|
The type of relay to use |
Returns : |
TRUE if the TURN settings were accepted.
FALSE if the address was invalid. |
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
See also: nice_agent_add_local_address()
See also: nice_agent_set_port_range()
|
The NiceAgent Object |
|
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.
Note
Local addresses can be previously set with
Since 0.0.5, If no local address was previously added, then the nice agent
will automatically detect the local address using
|
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
|
The NiceAgent Object |
|
The ID of the stream |
|
NULL-terminated string containing an ICE username fragment (length must be between 22 and 256 chars) |
|
NULL-terminated string containing an ICE password (length must be between 4 and 256 chars) |
Returns : |
TRUE on success, FALSE on error. |
gboolean nice_agent_get_local_credentials (NiceAgent *agent,guint stream_id,gchar **ufrag,gchar **pwd);
Gets the local credentials for stream stream_id.
|
The NiceAgent Object |
|
The ID of the stream |
|
a pointer to a NULL-terminated string containing
an ICE username fragment [OUT].
This string must be freed with g_free()
|
|
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. |
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()
|
The NiceAgent Object |
|
The ID of the stream the candidates are for |
|
The ID of the component the candidates are for |
|
a GSList 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) |
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 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.
|
The NiceAgent Object |
|
The ID of the stream |
|
The ID of the component |
Returns : |
a GSList of NiceCandidates objects representing
the remote candidates set on the agent
|
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
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.
|
The NiceAgent Object |
|
The ID of the stream |
|
The ID of the component |
Returns : |
a GSList of NiceCandidate objects representing
the local candidates of agent
|
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.
|
The NiceAgent Object |
|
The ID of the stream to send to |
|
The ID of the component to send to |
|
The length of the buffer to send |
|
The buffer of data to send |
Returns : |
The number of bytes sent, or negative error code |
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.
|
The NiceAgent Object |
|
The ID of stream |
|
The ID of the component |
|
The Glib Mainloop Context to use for listening on the component |
|
The callback function to be called when data is received on the stream's component |
|
user data associated with the callback |
Returns : |
TRUE on success, FALSE if the stream or component IDs are invalid. |
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.
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.
|
The NiceAgent Object |
|
The ID of the stream |
|
The ID of the component |
|
The NiceCandidate to select |
Returns : |
TRUE on success, FALSE on failure |
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
|
The NiceAgent Object |
|
The ID of the stream |
|
The ToS to set |
Since 0.0.9
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.
|
The NiceAgent Object |
|
The value of the SOFTWARE attribute to add. |
Since 0.0.10
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.
"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: <= 5
Default value: 0
"controlling-mode" property"controlling-mode" gboolean : Read / Write
Whether the agent is in controlling mode.
Default value: FALSE
"full-mode" property"full-mode" gboolean : Read / Write / Construct Only
Whether agent runs in ICE full mode.
Default value: TRUE
"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.
"max-connectivity-checks" property"max-connectivity-checks" guint : Read / Write
Upper limit for the total number of connectivity checks performed.
Default value: 0
"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
"proxy-password" property"proxy-password" gchar* : Read / Write
The password used to authenticate with the proxy
Default value: NULL
Since 0.0.4
"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
"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
"proxy-username" property"proxy-username" gchar* : Read / Write
The username used to authenticate with the proxy
Default value: NULL
Since 0.0.4
"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
"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
"stun-server" property"stun-server" gchar* : Read / Write
The IP address (not the hostname) of the STUN server to use.
Default value: NULL
"stun-server-port" property"stun-server-port" guint : Read / Write
Port of the STUN server used to gather server-reflexive candidates.
Allowed values: [1,65536]
Default value: 1
"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
"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
"candidate-gathering-done" signalvoid 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()
|
The NiceAgent object |
|
The ID of the stream |
|
user data set when the signal handler was connected. |
"component-state-changed" signalvoid 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
|
The NiceAgent object |
|
The ID of the stream |
|
The ID of the component |
|
The NiceComponentState of the component |
|
user data set when the signal handler was connected. |
"initial-binding-request-received" signalvoid 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.
|
The NiceAgent object |
|
The ID of the stream |
|
user data set when the signal handler was connected. |
"new-candidate" signalvoid 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"
|
The NiceAgent object |
|
The ID of the stream |
|
The ID of the component |
|
The foundation of the new candidate |
|
user data set when the signal handler was connected. |
"new-remote-candidate" signalvoid 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.
|
The NiceAgent object |
|
The ID of the stream |
|
The ID of the component |
|
The foundation of the new candidate |
|
user data set when the signal handler was connected. |
"new-selected-pair" signalvoid 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
|
The NiceAgent object |
|
The ID of the stream |
|
The ID of the component |
|
The local foundation of the selected candidate pair |
|
The remote foundation of the selected candidate pair |
|
user data set when the signal handler was connected. |
"reliable-transport-writable" signalvoid 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.
|
The NiceAgent object |
|
The ID of the stream |
|
The ID of the component |
|
user data set when the signal handler was connected. |
Since 0.0.11