 |
 |
 |
 |
- Pseudo TCP Socket — Pseudo TCP implementation
libnice Reference Manual |
|---|
The latest version of this documentation can be found on-line at http://nice.freedesktop.org/libnice/.
- I. ICE Library
- NiceAgent — ICE agent API implementation
- NiceAddress — IP address convenience library
- NiceCandidate — ICE candidate representation
- Libnice helper functions
- Debug messages — Debug messages utility functions
- Network interfaces discovery — Utility functions to discover local network interfaces
- II. STUN Library
- StunAgent — STUN agent for building and validating STUN messages
- StunMessage — STUN messages parsing and formatting functions
- STUN Constants — STUN constants
- STUN usages
- III. Pseudo TCP Socket implementation
- Pseudo TCP Socket — Pseudo TCP implementation
- IV. Appendices
The libnice library contains the ICE library and the STUN library as well as a Pseudo TCP socket implementation.
| Top | |
|
|
|
Description
The STUN ICE usage allows for easily creating and parsing STUN Binding requests and responses used for ICE connectivity checks. The API allows you to create a connectivity check message, parse a response or create a reply to an incoming connectivity check request.
Functions
stun_usage_ice_conncheck_create ()
size_t stun_usage_ice_conncheck_create (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,const uint8_t *username,const size_t username_len,const uint8_t *password,const size_t password_len,bool cand_use,bool controlling,uint32_t priority,uint64_t tie,const char *candidate_identifier,StunUsageIceCompatibility compatibility);
Builds an ICE connectivity check STUN message.
If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_RFC5245, the
cand_use
, controlling
, priority
and tie
arguments are not used.
If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_MSICE2, the
candidate_identifier
argument is not used.
Parameters
agent |
The StunAgent to use to build the request |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use for creating the StunMessage |
 |
buffer_len |
The size of the |
 |
username |
The username to use in the request |
 |
username_len |
The length of |
 |
password |
The key to use for building the MESSAGE-INTEGRITY |
 |
password_len |
The length of |
 |
cand_use |
Set to |
 |
controlling |
Set to |
 |
priority |
The value of the PRIORITY attribute |
 |
tie |
The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute |
 |
candidate_identifier |
The foundation value to put in the CANDIDATE-IDENTIFIER attribute |
 |
compatibility |
The compatibility mode to use for building the conncheck request |
 |
stun_usage_ice_conncheck_process ()
StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg,struct sockaddr_storage *addr,socklen_t *addrlen,StunUsageIceCompatibility compatibility);
Process an ICE connectivity check STUN message and retrieve the mapped address from the message
See also stun_usage_ice_conncheck_priority() and
stun_usage_ice_conncheck_use_candidate()
Parameters
msg |
The StunMessage to process |
 |
addr |
A pointer to a sockaddr structure to fill with the mapped address that the STUN connectivity check response contains |
 |
addrlen |
The length of |
 |
compatibility |
The compatibility mode to use for processing the conncheck response |
 |
stun_usage_ice_conncheck_create_reply ()
StunUsageIceReturn stun_usage_ice_conncheck_create_reply (StunAgent *agent,StunMessage *req,StunMessage *msg,uint8_t *buf,size_t *plen,const struct sockaddr_storage *src,socklen_t srclen,bool *control,uint64_t tie,StunUsageIceCompatibility compatibility);
Tries to parse a STUN connectivity check request and builds a response accordingly.
In case of error, the msg is filled with the appropriate error response
to be sent and the value of plen is set to the size of that message.
If plen has a size of 0, then no error response should be sent.
Parameters
agent |
The StunAgent to use to build the response |
 |
req |
The original STUN request to reply to |
 |
msg |
The StunMessage to build |
 |
buf |
The buffer to use for creating the StunMessage |
 |
plen |
A pointer containing the size of the |
 |
src |
A pointer to a sockaddr structure containing the source address from which the request was received. Will be used as the mapped address in the response |
 |
srclen |
The length of |
 |
control |
Set to |
 |
tie |
The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute |
 |
compatibility |
The compatibility mode to use for building the conncheck response |
 |
stun_usage_ice_conncheck_priority ()
uint32_t
stun_usage_ice_conncheck_priority (const StunMessage *msg);
Extracts the priority from a STUN message.
stun_usage_ice_conncheck_use_candidate ()
bool
stun_usage_ice_conncheck_use_candidate
(const StunMessage *msg);
Extracts the USE-CANDIDATE attribute flag from a STUN message.
Types and Values
enum StunUsageIceCompatibility
This enum defines which compatibility modes this ICE usage can use
STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 and
STUN_USAGE_ICE_COMPATIBILITY_WLM2009 are deprecated and should not be used
in newly-written code. They are kept for compatibility reasons and represent
the same compatibilities as STUN_USAGE_ICE_COMPATIBILITY_RFC5245 and
STUN_USAGE_ICE_COMPATIBILITY_MSICE2 respectively.Members
|
The ICE compatibility with RFC 5245 |
 | |
|
The ICE compatibility with Google's implementation of ICE |
 | |
|
The ICE compatibility with MSN's implementation of ICE |
 | |
|
The ICE compatibility with [MS-ICE2] specification |
 | |
|
The ICE compatibility with draft 19 |
 | |
|
An alias
for |
 |
enum StunUsageIceReturn
Return value of stun_usage_ice_conncheck_process() and
stun_usage_ice_conncheck_create_reply() which allows you to see what
status the function call returned.
Members
|
The function succeeded |
 | |
|
There was an unspecified error |
 | |
|
The message is invalid for processing |
 | |
|
A role conflict was detected |
 | |
|
The message is an not a request |
 | |
|
The method of the request is invalid |
 | |
|
The buffer size is too small to hold the STUN reply |
 | |
|
The mapped address argument has an invalid address family |
 | |
|
The response is valid but no MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attribute was found |
 |
| Top | |
|
|
|
Functions
| NiceCandidate * | nice_candidate_new () |
| void | nice_candidate_free () |
| NiceCandidate * | nice_candidate_copy () |
| gboolean | nice_candidate_equal_target () |
Types and Values
| struct | NiceCandidate |
| enum | NiceCandidateType |
| enum | NiceCandidateTransport |
| struct | TurnServer |
| enum | NiceRelayType |
| #define | NICE_CANDIDATE_MAX_FOUNDATION |
Object Hierarchy
GBoxed ╰── NiceCandidate GEnum ├── NiceCandidateTransport ├── NiceCandidateType ╰── NiceRelayType
Description
A representation of an ICE candidate. Make sure you read the ICE drafts[1] to understand correctly the concept of ICE candidates.
[1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/
Functions
nice_candidate_new ()
NiceCandidate *
nice_candidate_new (NiceCandidateType type);
Creates a new candidate. Must be freed with nice_candidate_free()
nice_candidate_copy ()
NiceCandidate *
nice_candidate_copy (const NiceCandidate *candidate);
Makes a copy of a NiceCandidate
nice_candidate_equal_target ()
gboolean nice_candidate_equal_target (const NiceCandidate *candidate1,const NiceCandidate *candidate2);
Verifies that the candidates point to the same place, meaning they have the same transport and the same address. It ignores all other aspects.
Since: 0.1.15
Types and Values
struct NiceCandidate
struct NiceCandidate {
NiceCandidateType type;
NiceCandidateTransport transport;
NiceAddress addr;
NiceAddress base_addr;
guint32 priority;
guint stream_id;
guint component_id;
gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
gchar *username; /* pointer to a nul-terminated username string */
gchar *password; /* pointer to a nul-terminated password string */
TurnServer *turn;
gpointer sockptr;
};
A structure to represent an ICE candidate
The priority is an integer as specified in the ICE draft 19. If you are
using the MSN or the GOOGLE compatibility mode (which are based on ICE
draft 6, which uses a floating point qvalue as priority), then the priority
value will represent the qvalue multiplied by 1000.
Members
NiceCandidateType |
The type of candidate |
 |
NiceCandidateTransport |
The transport being used for the candidate |
 |
NiceAddress |
The NiceAddress of the candidate |
 |
NiceAddress |
The NiceAddress of the base address used by the candidate |
 |
guint32Â |
The priority of the candidate see note |
 |
guint |
The ID of the stream to which belongs the candidate |
 |
guint |
The ID of the component to which belongs the candidate |
 |
gchar |
The foundation of the candidate |
 |
gchar * |
The candidate-specific username to use (overrides the one set
by |
 |
gchar * |
The candidate-specific password to use (overrides the one set
by |
 |
TurnServer * |
The TurnServer settings if the candidate is
of type |
 |
gpointer |
The underlying socket |
 |
struct TurnServer
struct TurnServer {
gint ref_count;
NiceAddress server;
gchar *username;
gchar *password;
NiceRelayType type;
};
A structure to store the TURN relay settings
Members
gint |
Reference count for the structure. |
 |
NiceAddress |
The NiceAddress of the TURN server |
 |
gchar * |
The TURN username |
 |
gchar * |
The TURN password |
 |
NiceRelayType |
The NiceRelayType of the server |
 |
| Top | |
|
|
|
Functions
| size_t | stun_usage_bind_create () |
| StunUsageBindReturn | stun_usage_bind_process () |
| size_t | stun_usage_bind_keepalive () |
| StunUsageBindReturn | stun_usage_bind_run () |
Description
The STUN Binding usage allows for easily creating and parsing STUN Binding requests and responses. It offers both an asynchronous and a synchronous API that uses the STUN timer usage.
Functions
stun_usage_bind_create ()
size_t stun_usage_bind_create (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len);
Create a new STUN binding request to use with a STUN server.
Parameters
agent |
The StunAgent to use to create the binding request |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use for creating the StunMessage |
 |
buffer_len |
The size of the |
 |
stun_usage_bind_process ()
StunUsageBindReturn stun_usage_bind_process (StunMessage *msg,struct sockaddr *addr,socklen_t *addrlen,struct sockaddr *alternate_server,socklen_t *alternate_server_len);
Process a STUN binding response and extracts the mapped address from the STUN message. Also checks for the ALTERNATE-SERVER attribute.
Parameters
msg |
The StunMessage to process |
 |
addr |
A pointer to a sockaddr structure to fill with the mapped address that the STUN server gives us |
 |
addrlen |
The length of |
 |
alternate_server |
A pointer to a sockaddr structure to fill with the address of an alternate server to which we should send our new STUN binding request, in case the currently used STUN server is requesting the use of an alternate server. This argument will only be filled if the return value of the function is STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER |
 |
alternate_server_len |
The length of |
 |
Returns
A StunUsageBindReturn value. Note that STUN_USAGE_BIND_RETURN_TIMEOUT cannot be returned by this function
stun_usage_bind_keepalive ()
size_t stun_usage_bind_keepalive (StunAgent *agent,StunMessage *msg,uint8_t *buf,size_t len);
Creates a STUN binding indication that can be used for a keepalive. Since this is an indication message, no STUN response will be generated and it can only be used as a keepalive message.
Parameters
agent |
The StunAgent to use to build the message |
 |
msg |
The StunMessage to build |
 |
buf |
The buffer to use for creating the StunMessage |
 |
len |
The size of the |
 |
stun_usage_bind_run ()
StunUsageBindReturn stun_usage_bind_run (const struct sockaddr *srv,socklen_t srvlen,struct sockaddr_storage *addr,socklen_t *addrlen);
This is a convenience function that will do a synchronous Binding request to a server and wait for its answer. It will create the socket transports and use the StunTimer usage to send the request and handle the response.
Returns
A StunUsageBindReturn. Possible return values are STUN_USAGE_BIND_RETURN_SUCCESS, STUN_USAGE_BIND_RETURN_ERROR and STUN_USAGE_BIND_RETURN_TIMEOUT
Types and Values
enum StunUsageBindReturn
Return value of stun_usage_bind_process() and stun_usage_bind_run() which
allows you to see what status the function call returned.
|
|
|
 |
A
NULL is OK, both for passing and for returning.
Parameter points to an array of items.
E
Generics and defining elements of containers and arrays.
I
Parameter for input. Default is transfer none.
N
NULL may be passed as the value in, out, in-out; or as a return value.
O
Out parameter, where caller must allocate storage.
Out parameter, where caller must allocate storage.
S
Exposed in C code, not necessarily available in other languages.
The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications.
T
Free data after the code is done.
Don't free data after the code is done.
U
Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next. The Unstable interface level is a warning that these interfaces are subject to change without warning and should not be used in unbundled products. Given such caveats, customer impact need not be a factor when considering incompatible changes to an Unstable interface in a major or minor release. Nonetheless, when such changes are introduced, the changes should still be mentioned in the release notes for the affected release.
|
 |
|
|
Table of Contents
- Pseudo TCP Socket — Pseudo TCP implementation
|
|
|
|
| Top | |
|
|
|
Functions
Properties
| gboolean | bytestream-tcp | Read |
| guint | compatibility | 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 |
| 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 |
| 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
Types and Values
| Â | NiceAgent |
| enum | NiceComponentState |
| enum | NiceComponentType |
| enum | NiceProxyType |
| enum | NiceNominationMode |
| enum | NiceCompatibility |
| Â | NiceInputMessage |
| Â | NiceOutputMessage |
| #define | NICE_AGENT_MAX_REMOTE_CANDIDATES |
| enum | NiceAgentOption |
Object Hierarchy
GEnum ├── NiceCompatibility ├── NiceComponentState ├── NiceComponentType ├── NiceNominationMode ╰── NiceProxyType GFlags ╰── NiceAgentOption GObject ╰── NiceAgent
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_new ()
NiceAgent * nice_agent_new (GMainContext *ctx,NiceCompatibility compat);
Create a new NiceAgent.
The returned object must be freed with g_object_unref()
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 |
 |
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 |
 |
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 |
 |
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 |
 |
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.
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 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 |
 |
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 |
 |
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()
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) |
 |
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 |
[out callee-allocates] |
pwd |
return location for a nul-terminated string
containing an ICE password; must be freed with |
[out callee-allocates] |
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) |
 |
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] |
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 |
 |
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.
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 |
 |
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 |
 | |
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
|
[array length=n_messages] |
n_messages |
number of entries in |
 |
cancellable |
a GCancellable to cancel the operation from
another thread, or |
[allow-none] |
error |
[allow-none] |
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 |
 | |
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 |
[array length=buf_len][out caller-allocates] |
buf_len |
length of |
 |
cancellable |
a GCancellable to allow the operation to be
cancelled from another thread, or |
[allow-none] |
error |
[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 |
 | |
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 |
[array length=n_messages][out caller-allocates] |
n_messages |
number of entries in |
 |
cancellable |
a GCancellable to allow the operation to be
cancelled from another thread, or |
[allow-none] |
error |
[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 |
 | |
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 |
[array length=buf_len][out caller-allocates] |
buf_len |
length of |
 |
cancellable |
a GCancellable to allow the operation to be
cancelled from another thread, or |
[allow-none] |
error |
[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 |
 | |
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 |
[array length=n_messages][out caller-allocates] |
n_messages |
number of entries in |
 |
cancellable |
a GCancellable to allow the operation to be
cancelled from another thread, or |
[allow-none] |
error |
[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 |
 |
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 |
 |
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 |
 |
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
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.
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.
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.
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()
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()
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()
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) |
 |
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()
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()
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()
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 |
 |
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 |
 | |
stream_id |
The ID of the stream to wrap |
 |
component_id |
The ID of the component to wrap |
 |
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_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_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.
Since: 0.1.6
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â€
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); |
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â€
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.
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
|
Use compatibility with the RFC5245 ICE-UDP specs and RFC6544 ICE-TCP specs |
 | |
|
Use compatibility for ICE Draft 19 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 |
 | |
|
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 * |
unowned array of GInputVector buffers to store data in for this message. |
[array length=n_buffers] |
gint |
number of GInputVectors in |
 |
NiceAddress * |
return location to store the address of the peer who
transmitted the message, or |
[allow-none] |
gsize |
total number of valid bytes contiguously stored in |
 |
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 * |
unowned array of GOutputVector buffers which contain data to transmit for this message. |
[array length=n_buffers] |
gint |
number of GOutputVectors in |
 |
Since: 0.1.5
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.
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
|
Enables regular nomination, default is aggrssive mode (see NiceNominationMode). |
 | |
|
Enables reliable mode, possibly using PseudoTCP, * see |
 | |
|
Enable lite mode |
 | |
|
Enable ICE trickle mode |
 | |
|
Enable renomination triggered by NOMINATION STUN attribute proposed here: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00 |
 |
Since: 0.1.15
Property Details
The “bytestream-tcp†property
“bytestream-tcp†gboolean
This property defines whether receive/send over a TCP or pseudo-TCP, 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 considred 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.
This property is currently read-only, and will become read/write once bytestream mode will be supported.
Flags: Read
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 “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 “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.
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-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: 200
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: 7
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: 7900
Since: 0.1.15
The “stun-server†property
“stun-server†gchar *
The IP address (not the 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.
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.
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.
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.
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
| Top | |
|
|
|
Functions
Types and Values
| struct | StunMessage |
| enum | StunClass |
| enum | StunMethod |
| enum | StunAttribute |
| typedef | StunTransactionId |
| enum | StunError |
| enum | StunMessageReturn |
| #define | STUN_MESSAGE_BUFFER_INCOMPLETE |
| #define | STUN_MESSAGE_BUFFER_INVALID |
| Â | StunInputVector |
Description
The STUN Messages API allows you to create STUN messages easily as well as to parse existing messages.
Functions
stun_message_init ()
bool stun_message_init (StunMessage *msg,StunClass c,StunMethod m,const StunTransactionId id);
Initializes a STUN message buffer, with no attributes.
Parameters
msg |
The StunMessage to initialize |
 |
c |
STUN message class (host byte order) |
 |
m |
STUN message method (host byte order) |
 |
id |
16-bytes transaction ID |
 |
stun_message_length ()
uint16_t
stun_message_length (const StunMessage *msg);
Get the length of the message (including the header)
stun_message_find ()
const void * stun_message_find (const StunMessage *msg,StunAttribute type,uint16_t *palen);
Finds an attribute in a STUN message and fetches its content
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
palen |
A pointer to store the length of the attribute |
 |
stun_message_find_flag ()
StunMessageReturn stun_message_find_flag (const StunMessage *msg,StunAttribute type);
Looks for a flag attribute within a valid STUN message.
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not zero.
stun_message_find32Â ()
StunMessageReturn stun_message_find32 (const StunMessage *msg,StunAttribute type,uint32_t *pval);
Extracts a 32-bits attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
pval |
A pointer where to store the value (host byte order) |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
4 bytes.
stun_message_find64Â ()
StunMessageReturn stun_message_find64 (const StunMessage *msg,StunAttribute type,uint64_t *pval);
Extracts a 64-bits attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
pval |
A pointer where to store the value (host byte order) |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute's size is not
8 bytes.
stun_message_find_string ()
StunMessageReturn stun_message_find_string (const StunMessage *msg,StunAttribute type,char *buf,size_t buflen);
Extracts an UTF-8 string from a valid STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
buf |
A pointer where to store the data |
 |
buflen |
The length of the buffer |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute is improperly
encoded
STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE is return if the buffer size is too
small to hold the string
The string will be nul-terminated.
stun_message_find_addr ()
StunMessageReturn stun_message_find_addr (const StunMessage *msg,StunAttribute type,struct sockaddr_storage *addr,socklen_t *addrlen);
Extracts a network address attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
addr |
The sockaddr to be filled |
 |
addrlen |
The size of the |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
wrong or if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_find_xor_addr ()
StunMessageReturn stun_message_find_xor_addr (const StunMessage *msg,StunAttribute type,struct sockaddr_storage *addr,socklen_t *addrlen);
Extracts an obfuscated network address attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
addr |
The sockaddr to be filled |
 |
addrlen |
The size of the |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
wrong or if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_find_xor_addr_full ()
StunMessageReturn stun_message_find_xor_addr_full (const StunMessage *msg,StunAttribute type,struct sockaddr_storage *addr,socklen_t *addrlen,uint32_t magic_cookie);
Extracts an obfuscated network address attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to find |
 |
addr |
The sockaddr to be filled |
 |
addrlen |
The size of the |
 |
magic_cookie |
The magic cookie to use to XOR the address. |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the attribute payload size is
wrong or if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_find_error ()
StunMessageReturn stun_message_find_error (const StunMessage *msg,int *code);
Extract the error response code from a STUN message
stun_message_append ()
void * stun_message_append (StunMessage *msg,StunAttribute type,size_t length);
Reserves room for appending an attribute to an unfinished STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
length |
The length of the attribute |
 |
stun_message_append_bytes ()
StunMessageReturn stun_message_append_bytes (StunMessage *msg,StunAttribute type,const void *data,size_t len);
Appends a binary value to a STUN message
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
data |
The data to append |
 |
len |
The length of the attribute |
 |
stun_message_append_flag ()
StunMessageReturn stun_message_append_flag (StunMessage *msg,StunAttribute type);
Appends an empty flag attribute to a STUN message
stun_message_append32Â ()
StunMessageReturn stun_message_append32 (StunMessage *msg,StunAttribute type,uint32_t value);
Appends a 32-bits value attribute to a STUN message
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
value |
The value to append (host byte order) |
 |
stun_message_append64Â ()
StunMessageReturn stun_message_append64 (StunMessage *msg,StunAttribute type,uint64_t value);
Appends a 64-bits value attribute to a STUN message
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
value |
The value to append (host byte order) |
 |
stun_message_append_string ()
StunMessageReturn stun_message_append_string (StunMessage *msg,StunAttribute type,const char *str);
Adds an attribute from a nul-terminated string to a STUN message
stun_message_append_addr ()
StunMessageReturn stun_message_append_addr (StunMessage *msg,StunAttribute type,const struct sockaddr *addr,socklen_t addrlen);
Append a network address attribute to a STUN message
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
addr |
The sockaddr to be append |
 |
addrlen |
The size of the |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_append_xor_addr ()
StunMessageReturn stun_message_append_xor_addr (StunMessage *msg,StunAttribute type,const struct sockaddr_storage *addr,socklen_t addrlen);
Append an obfuscated network address attribute to a STUN message
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
addr |
The sockaddr to be append |
 |
addrlen |
The size of the |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_append_xor_addr_full ()
StunMessageReturn stun_message_append_xor_addr_full (StunMessage *msg,StunAttribute type,const struct sockaddr_storage *addr,socklen_t addrlen,uint32_t magic_cookie);
Append an obfuscated network address attribute from a STUN message.
Parameters
msg |
The StunMessage |
 |
type |
The StunAttribute to append |
 |
addr |
The sockaddr to be append |
 |
addrlen |
The size of the |
 |
magic_cookie |
The magic cookie to use to XOR the address. |
 |
Returns
A StunMessageReturn value.
STUN_MESSAGE_RETURN_INVALID is returned if the addrlen
is too small
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS if the address family is unknown.
stun_message_append_error ()
StunMessageReturn stun_message_append_error (StunMessage *msg,StunError code);
Appends the ERROR-CODE attribute to the STUN message and fills it according to code
stun_message_validate_buffer_length ()
int stun_message_validate_buffer_length (const uint8_t *msg,size_t length,bool has_padding);
This function will take a data buffer and will try to validate whether it is a STUN message or if it's not or if it's an incomplete STUN message and will provide us with the length of the STUN message.
Parameters
msg |
The buffer to validate |
 |
length |
The length of the buffer |
 |
has_padding |
Set TRUE if attributes should be padded to multiple of 4 bytes |
 |
Returns
The length of the valid STUN message in the buffer.
See also: STUN_MESSAGE_BUFFER_INCOMPLETE
See also: STUN_MESSAGE_BUFFER_INVALID
stun_message_validate_buffer_length_fast ()
ssize_t stun_message_validate_buffer_length_fast (StunInputVector *buffers,int n_buffers,size_t total_length,bool has_padding);
Quickly validate whether the message in the given buffers
is potentially a
valid STUN message, an incomplete STUN message, or if it’s definitely not one
at all.
This is designed as a first-pass validation only, and does not check the
message’s attributes for validity. If this function returns success, the
buffers can be compacted and a more thorough validation can be performed
using stun_message_validate_buffer_length(). If it fails, the buffers
definitely do not contain a complete, valid STUN message.
Parameters
buffers |
array of contiguous StunInputVectors containing already-received message data. |
[array length=n_buffers][in caller-allocated] |
n_buffers |
number of entries in |
 |
total_length |
total number of valid bytes stored consecutively in |
 |
has_padding |
|
 |
Returns
The length of the valid STUN message in the buffer, or zero or -1 on failure
See also: STUN_MESSAGE_BUFFER_INCOMPLETE
See also: STUN_MESSAGE_BUFFER_INVALID
Since: 0.1.5
stun_message_id ()
void stun_message_id (const StunMessage *msg,StunTransactionId id);
Retreive the STUN transaction id from a STUN message
stun_message_get_class ()
StunClass
stun_message_get_class (const StunMessage *msg);
Retreive the STUN class from a STUN message
stun_message_get_method ()
StunMethod
stun_message_get_method (const StunMessage *msg);
Retreive the STUN method from a STUN message
stun_message_has_attribute ()
bool stun_message_has_attribute (const StunMessage *msg,StunAttribute type);
Checks if an attribute is present within a STUN message.
stun_message_has_cookie ()
bool
stun_message_has_cookie (const StunMessage *msg);
Checks if the STUN message has a RFC5389 compatible cookie
stun_optional ()
bool
stun_optional (uint16_t t);
Helper function that checks whether a STUN attribute is a mandatory or an optional attribute
stun_strerror ()
const char *
stun_strerror (StunError code);
Transforms a STUN error-code into a human readable string
Types and Values
struct StunMessage
struct StunMessage {
StunAgent *agent;
uint8_t *buffer;
size_t buffer_len;
uint8_t *key;
size_t key_len;
uint8_t long_term_key[16];
bool long_term_valid;
};
This structure represents a STUN message
Members
StunAgent * |
The agent that created or validated this message |
 |
The buffer containing the STUN message |
 | |
The length of the buffer (not the size of the message) |
 | |
The short term credentials key to use for authentication validation or that was used to finalize this message |
 | |
The length of the associated key |
 | |
The long term credential key to use for authentication validation or that was used to finalize this message |
 | |
Whether or not the long_term_key variable contains valid data |
 |
enum StunMethod
This enum is used to represent the method of a STUN message, as defined by various RFCs
Members
|
The Binding method as defined by the RFC5389 |
 | |
|
The Shared-Secret method as defined by the RFC3489 |
 | |
|
The Allocate method as defined by the TURN draft 12 |
 | |
|
The Set-Active-Destination method as defined by the TURN draft 4 |
 | |
|
The Refresh method as defined by the TURN draft 12 |
 | |
|
The Send method as defined by the TURN draft 00 |
 | |
|
The Connect method as defined by the TURN draft 4 |
 | |
|
The older Set-Active-Destination method as defined by the TURN draft 0 |
 | |
|
The Send method used in indication messages as defined by the TURN draft 12 |
 | |
|
The Data method used in indication messages as defined by the TURN draft 12 |
 | |
|
The Connect-Status method used in indication messages as defined by the TURN draft 4 |
 | |
|
The CreatePermission method as defined by the TURN draft 12 |
 | |
|
The ChannelBind method as defined by the TURN draft 12 |
 |
enum StunAttribute
Known STUN attribute types as defined by various RFCs and drafts
Members
|
The MAPPED-ADDRESS attribute as defined by RFC5389 |
 | |
|
The RESPONSE-ADDRESS attribute as defined by RFC3489 |
 | |
|
The CHANGE-REQUEST attribute as defined by RFC3489 |
 | |
|
The SOURCE-ADDRESS attribute as defined by RFC3489 |
 | |
|
The CHANGED-ADDRESS attribute as defined by RFC3489 |
 | |
|
The USERNAME attribute as defined by RFC5389 |
 | |
|
The PASSWORD attribute as defined by RFC3489 |
 | |
|
The MESSAGE-INTEGRITY attribute as defined by RFC5389 |
 | |
|
The ERROR-CODE attribute as defined by RFC5389 |
 | |
|
The UNKNOWN-ATTRIBUTES attribute as defined by RFC5389 |
 | |
|
The REFLECTED-FROM attribute as defined by RFC3489 |
 | |
|
The CHANNEL-NUMBER attribute as defined by TURN draft 09 and 12 |
 | |
|
The LIFETIME attribute as defined by TURN draft 04, 09 and 12 |
 | |
|
The ALTERNATE-SERVER attribute as defined by [MS-TURN] |
 | |
|
The MAGIC-COOKIE attribute as defined by the rosenberg-midcom TURN draft 08 |
 | |
|
The BANDWIDTH attribute as defined by TURN draft 04 |
 | |
|
The DESTINATION-ADDRESS attribute as defined by the rosenberg-midcom TURN draft 08 |
 | |
|
The REMOTE-ADDRESS attribute as defined by TURN draft 04 |
 | |
|
The PEER-ADDRESS attribute as defined by TURN draft 09 |
 | |
|
The XOR-PEER-ADDRESS attribute as defined by TURN draft 12 |
 | |
|
The DATA attribute as defined by TURN draft 04, 09 and 12 |
 | |
|
The REALM attribute as defined by RFC5389 |
 | |
|
The NONCE attribute as defined by RFC5389 |
 | |
|
The RELAY-ADDRESS attribute as defined by TURN draft 04 |
 | |
|
The RELAYED-ADDRESS attribute as defined by TURN draft 09 |
 | |
|
The XOR-RELAYED-ADDRESS attribute as defined by TURN draft 12 |
 | |
|
The REQUESTED-ADDRESS-TYPE attribute as defined by TURN-IPV6 draft 05 |
 | |
|
The REQUESTED-PORT-PROPS attribute as defined by TURN draft 04 |
 | |
|
The REQUESTED-PROPS attribute as defined by TURN draft 09 |
 | |
|
The EVEN-PORT attribute as defined by TURN draft 12 |
 | |
|
The REQUESTED-TRANSPORT attribute as defined by TURN draft 12 |
 | |
|
The DONT-FRAGMENT attribute as defined by TURN draft 12 |
 | |
|
The XOR-MAPPED-ADDRESS attribute as defined by RFC5389 |
 | |
|
The TIMER-VAL attribute as defined by TURN draft 04 |
 | |
|
The REQUESTED-IP attribute as defined by TURN draft 04 |
 | |
|
The RESERVATION-TOKEN attribute as defined by TURN draft 09 and 12 |
 | |
|
The CONNECT-STAT attribute as defined by TURN draft 04 |
 | |
|
The PRIORITY attribute as defined by ICE draft 19 |
 | |
|
The USE-CANDIDATE attribute as defined by ICE draft 19 |
 | |
|
The OPTIONS optional attribute as defined by libjingle |
 | |
|
The MS-VERSION optional attribute as defined by [MS-TURN] |
 | |
|
The XOR-MAPPED-ADDRESS optional attribute as defined by [MS-TURN] |
 | |
|
The SOFTWARE optional attribute as defined by RFC5389 |
 | |
|
The ALTERNATE-SERVER optional attribute as defined by RFC5389 |
 | |
|
The FINGERPRINT optional attribute as defined by RFC5389 |
 | |
|
The ICE-CONTROLLED optional attribute as defined by ICE draft 19 |
 | |
|
The ICE-CONTROLLING optional attribute as defined by ICE draft 19 |
 | |
|
The MS-SEQUENCE NUMBER optional attribute as defined by [MS-TURN] |
 | |
|
The CANDIDATE-IDENTIFIER optional attribute as defined by [MS-ICE2] |
 | |
|
The IMPLEMENTATION-VERSION optional attribute as defined by [MS-ICE2] |
 | |
|
The NOMINATION attribute as defined by draft-thatcher-ice-renomination-00 and deployed in Google Chrome |
 |
StunTransactionId
typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
A type that holds a STUN transaction id.
enum StunError
STUN error codes as defined by various RFCs and drafts
Members
|
The ERROR-CODE value for the "Try Alternate" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Bad Request" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Unauthorized" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Unknown Attribute" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Allocation Mismatch" error as defined in TURN draft 12. Equivalent to the "No Binding" error defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Stale Nonce" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Active Destination Already Set" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Address Family not Supported" error as defined in TURN IPV6 Draft 05. |
 | |
|
The ERROR-CODE value for the "Wrong Credentials" error as defined in TURN Draft 12. |
 | |
|
he ERROR-CODE value for the "Unsupported Transport Protocol" error as defined in TURN Draft 12. |
 | |
|
The ERROR-CODE value for the "Invalid IP Address" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Invalid Port" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Operation for TCP Only" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Connection Already Exists" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Allocation Quota Reached" error as defined in TURN draft 12. |
 | |
|
The ERROR-CODE value for the "Role Conflict" error as defined in ICE draft 19. |
 | |
|
The ERROR-CODE value for the "Server Error" error as defined in RFC5389 |
 | |
|
The ERROR-CODE value for the "Insufficient Capacity" error as defined in TURN draft 04. |
 | |
|
The ERROR-CODE value for the "Insufficient Capacity" error as defined in TURN draft 12. |
 | |
|
The maximum possible ERROR-CODE value as defined by RFC 5389. |
 |
enum StunMessageReturn
The return value of most stun_message_* functions. This enum will report on whether an operation was successful or not and what error occured if any.
Members
|
The operation was successful |
 | |
|
The attribute was not found |
 | |
|
The argument or data is invalid |
 | |
|
There is not enough space in the message to append data to it, or not enough in an argument to fill it with the data requested. |
 | |
|
The address in the arguments or in the STUN message is not supported. |
 |
STUN_MESSAGE_BUFFER_INCOMPLETE
#define STUN_MESSAGE_BUFFER_INCOMPLETE 0
Convenience macro for stun_message_validate_buffer_length() meaning that the
data to validate does not hold a complete STUN message
STUN_MESSAGE_BUFFER_INVALID
#define STUN_MESSAGE_BUFFER_INVALID -1
Convenience macro for stun_message_validate_buffer_length() meaning that the
data to validate is not a valid STUN message
StunInputVector
typedef struct {
const uint8_t *buffer;
size_t size;
} StunInputVector;
Container for a single buffer which also stores its length. This is designed for vectored I/O: typically an array of StunInputVectors is passed to functions, providing multiple buffers which store logically contiguous received data.
This is guaranteed to be layed out identically in memory to GInputVector.
Since: 0.1.5
| Top | |
|
|
|
Functions
| void | stun_timer_start () |
| void | stun_timer_start_reliable () |
| StunUsageTimerReturn | stun_timer_refresh () |
| unsigned | stun_timer_remainder () |
Types and Values
| typedef | StunTimer |
| enum | StunUsageTimerReturn |
| #define | STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS |
| #define | STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT |
| #define | STUN_TIMER_DEFAULT_TIMEOUT |
Description
The STUN timer usage is a set of helpful utility functions that allows you to easily track when a STUN message should be retransmitted or considered as timed out.
Example 3. Simple example on how to use the timer usage
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 |
StunTimer timer; unsigned remainder; StunUsageTimerReturn ret; // Build the message, etc.. ... // Send the message and start the timer send(socket, request, sizeof(request)); stun_timer_start(&timer, STUN_TIMER_DEFAULT_TIMEOUT, STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS); // Loop until we get the response for (;;) { remainder = stun_timer_remainder(&timer); // Poll the socket until data is received or the timer expires if (poll (&pollfd, 1, delay) <= 0) { // Time out and no response was received ret = stun_timer_refresh (&timer); if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) { // Transaction timed out break; } else if (ret == STUN_USAGE_TIMER_RETURN_RETRANSMIT) { // A retransmission is necessary send(socket, request, sizeof(request)); continue; } else if (ret == STUN_USAGE_TIMER_RETURN_SUCCESS) { // The refresh succeeded and nothing has to be done, continue polling continue; } } else { // We received a response, read it recv(socket, response, sizeof(response)); break; } } // Check if the transaction timed out or not if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) { // do whatever needs to be done in that case } else { // Parse the response } |
Functions
stun_timer_start ()
void stun_timer_start (StunTimer *timer,unsigned int initial_timeout,unsigned int max_retransmissions);
Starts a STUN transaction retransmission timer.
This should be called as soon as you send the message for the first time on
a UDP socket.
The timeout before the next retransmission is set to initial_timeout
, then
each time a packet is retransmited, that timeout will be doubled, until the
max_retransmissions
retransmissions limit is reached.
To determine the total timeout value, one can use the following equation :
total_timeout = initial_timeout * (2^(max_retransmissions + 1) - 1);
See also: STUN_TIMER_DEFAULT_TIMEOUT
See also: STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS
stun_timer_start_reliable ()
void stun_timer_start_reliable (StunTimer *timer,unsigned int initial_timeout);
Starts a STUN transaction retransmission timer for a reliable transport. This should be called as soon as you send the message for the first time on a TCP socket
Parameters
timer |
The StunTimer to start |
 |
initial_timeout |
The initial timeout to use before the first retransmission |
 |
stun_timer_refresh ()
StunUsageTimerReturn
stun_timer_refresh (StunTimer *timer);
Updates a STUN transaction retransmission timer.
Types and Values
StunTimer
typedef struct stun_timer_s StunTimer;
An opaque structure representing a STUN transaction retransmission timer
enum StunUsageTimerReturn
Return value of stun_usage_timer_refresh() which provides you with status
information on the timer.
STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS
#define STUN_TIMER_DEFAULT_MAX_RETRANSMISSIONS 7
The default maximum retransmissions allowed before a timer decides to timeout
STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT
#define STUN_TIMER_DEFAULT_RELIABLE_TIMEOUT 7900
The default intial timeout to use for a reliable timer
STUN_TIMER_DEFAULT_TIMEOUT
#define STUN_TIMER_DEFAULT_TIMEOUT 200
The default intial timeout to use for the timer RFC recommendds 500, but it's ridiculous, 50ms is known to work in most cases as it is also what is used by SIP style VoIP when sending A-Law and mu-Law audio, so 200ms should be hyper safe. With an initial timeout of 200ms, a default of 7 transmissions, the last timeout will be 16 * 200ms, and we expect to receive a response from the stun server before (1 + 2 + 4 + 8 + 16 + 32 + 16) * 200ms = 15200 ms after the initial stun request has been sent.
|
|
|
|
- NiceAgent — ICE agent API implementation
- NiceAddress — IP address convenience library
- NiceCandidate — ICE candidate representation
| Top | |
|
|
|
Types and Values
| #define | STUN_AGENT_MAX_SAVED_IDS |
| #define | STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES |
| #define | STUN_ATTRIBUTE_HEADER_LENGTH |
| #define | STUN_ATTRIBUTE_LENGTH_LEN |
| #define | STUN_ATTRIBUTE_LENGTH_POS |
| #define | STUN_ATTRIBUTE_TYPE_LEN |
| #define | STUN_ATTRIBUTE_TYPE_POS |
| #define | STUN_ATTRIBUTE_VALUE_POS |
| #define | STUN_ID_LEN |
| #define | STUN_MAGIC_COOKIE |
| #define | STUN_MAX_MESSAGE_SIZE |
| #define | STUN_MAX_MESSAGE_SIZE_IPV4 |
| #define | STUN_MAX_MESSAGE_SIZE_IPV6 |
| #define | STUN_MESSAGE_ATTRIBUTES_POS |
| #define | STUN_MESSAGE_HEADER_LENGTH |
| #define | STUN_MESSAGE_LENGTH_LEN |
| #define | STUN_MESSAGE_LENGTH_POS |
| #define | STUN_MESSAGE_TRANS_ID_LEN |
| #define | STUN_MESSAGE_TRANS_ID_POS |
| #define | STUN_MESSAGE_TYPE_LEN |
| #define | STUN_MESSAGE_TYPE_POS |
| #define | TURN_MAGIC_COOKIE |
Description
Various constants defining parts of the STUN and TURN protocols and on-the-wire packet formats.
Types and Values
STUN_AGENT_MAX_SAVED_IDS
#define STUN_AGENT_MAX_SAVED_IDS 200
Maximum number of simultaneously ongoing STUN transactions.
STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES
#define STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES 256
Maximum number of unknown attribute which can be handled in a single STUN message.
STUN_ATTRIBUTE_HEADER_LENGTH
#define STUN_ATTRIBUTE_HEADER_LENGTH STUN_ATTRIBUTE_VALUE_POS
Length of a single STUN attribute header (in bytes).
STUN_ATTRIBUTE_LENGTH_LEN
#define STUN_ATTRIBUTE_LENGTH_LEN 2
Length of the length field of a STUN attribute (in bytes).
STUN_ATTRIBUTE_LENGTH_POS
#define STUN_ATTRIBUTE_LENGTH_POS
Offset of the length field of a STUN attribute (in bytes).
STUN_ATTRIBUTE_TYPE_LEN
#define STUN_ATTRIBUTE_TYPE_LEN 2
Length of the type field of a STUN attribute (in bytes).
STUN_ATTRIBUTE_TYPE_POS
#define STUN_ATTRIBUTE_TYPE_POS 0
Offset of the type field of a STUN attribute (in bytes).
STUN_ATTRIBUTE_VALUE_POS
#define STUN_ATTRIBUTE_VALUE_POS
Offset of the value field of a STUN attribute (in bytes).
STUN_MAGIC_COOKIE
#define STUN_MAGIC_COOKIE 0x2112A442
Magic cookie value used to identify STUN messages.
STUN_MAX_MESSAGE_SIZE_IPV4
#define STUN_MAX_MESSAGE_SIZE_IPV4 576
Maximum size of a STUN message sent over IPv4 (in bytes).
STUN_MAX_MESSAGE_SIZE_IPV6
#define STUN_MAX_MESSAGE_SIZE_IPV6 1280
Maximum size of a STUN message sent over IPv6 (in bytes).
STUN_MESSAGE_ATTRIBUTES_POS
#define STUN_MESSAGE_ATTRIBUTES_POS
Offset of the attributes of a STUN message (in bytes).
STUN_MESSAGE_HEADER_LENGTH
#define STUN_MESSAGE_HEADER_LENGTH STUN_MESSAGE_ATTRIBUTES_POS
Total length of a STUN message header (in bytes).
STUN_MESSAGE_LENGTH_LEN
#define STUN_MESSAGE_LENGTH_LEN 2
Length of the length field of a STUN message (in bytes).
STUN_MESSAGE_LENGTH_POS
#define STUN_MESSAGE_LENGTH_POS
Offset of the length field of a STUN message (in bytes).
STUN_MESSAGE_TRANS_ID_LEN
#define STUN_MESSAGE_TRANS_ID_LEN 16
Length of the transaction ID field of a STUN message (in bytes).
STUN_MESSAGE_TRANS_ID_POS
#define STUN_MESSAGE_TRANS_ID_POS
Offset of the transaction ID field of a STUN message (in bytes).
STUN_MESSAGE_TYPE_LEN
#define STUN_MESSAGE_TYPE_LEN 2
Length of the type field of a STUN message (in bytes).
STUN_MESSAGE_TYPE_POS
#define STUN_MESSAGE_TYPE_POS 0
Offset of the type field of a STUN message (in bytes).
|
|
|
|
Table of Contents
|
|
|
|
- Debug messages — Debug messages utility functions
- Network interfaces discovery — Utility functions to discover local network interfaces
| Top | |
|
|
|
Description
Libnice can output a lot of information when debug messages are enabled. This can significantly help track down problems and/or understand what it's doing.
You can enable/disable the debug messages by calling nice_debug_enable()
or nice_debug_disable() and choosing whether you want only ICE debug messages
or also stun debug messages.
By default, the debug messages are disabled, unless the environment variable NICE_DEBUG is set, in which case, it must contain a comma separated list of flags specifying which debug to enable.
The currently available flags are "nice", "stun", "pseudotcp", "pseudotcp-verbose" or "all" to enable all debug messages.
If the 'pseudotcp' flag is enabled, then 'pseudotcp-verbose' gets automatically disabled. This is to allow the use of the 'all' flag without having verbose messages from pseudotcp. You can enable verbose debug messages from the pseudotcp layer by specifying 'pseudotcp-verbose' without the 'pseudotcp' flag.
This API is unstable and is subject to change at any time... More flags are to come and a better API to enable/disable each flag should be added.
Functions
nice_debug_enable ()
void
nice_debug_enable (gboolean with_stun);
Enables libnice debug output to the terminal. Note that the
G_MESSAGES_DEBUG and NICE_DEBUG environment variables must be set to the
set of logging domains to print, in order for any output to be printed. Set
them to all to print all debugging messages, or any of the following
domains:
libnice-stunlibnice-testslibnice-socketlibnicelibnice-pseudotcplibnice-pseudotcp-verbose
nice_debug_disable ()
void
nice_debug_disable (gboolean with_stun);
Disables libnice debug output to the terminal
| Top | |
|
|
|
Functions
Types and Values
| Â | PseudoTcpSocket |
| enum | PseudoTcpState |
| enum | PseudoTcpWriteResult |
| Â | PseudoTcpCallbacks |
| enum | PseudoTcpDebugLevel |
| enum | PseudoTcpShutdown |
Object Hierarchy
GEnum ├── PseudoTcpDebugLevel ├── PseudoTcpShutdown ├── PseudoTcpState ╰── PseudoTcpWriteResult GObject ╰── PseudoTcpSocket
Description
The PseudoTcpSocket is an object implementing a Pseudo Tcp Socket for use over UDP. The socket will implement a subset of the TCP stack to allow for a reliable transport over non-reliable sockets (such as UDP).
See the file tests/test-pseudotcp.c in the source package for an example of how to use the object.
Functions
pseudo_tcp_socket_new ()
PseudoTcpSocket * pseudo_tcp_socket_new (guint32 conversation,PseudoTcpCallbacks *callbacks);
Creates a new PseudoTcpSocket for the specified conversation
The callbacks must be non-NULL, in order to get notified of packets the
socket needs to send.
If the callbacks structure was dynamicly allocated, it can be freed
after the call pseudo_tcp_socket_new
Parameters
conversation |
The conversation id for the socket. |
 |
callbacks |
A pointer to the PseudoTcpCallbacks structure for getting notified of the PseudoTcpSocket events. |
 |
Since: 0.0.11
pseudo_tcp_socket_connect ()
gboolean
pseudo_tcp_socket_connect (PseudoTcpSocket *self);
Connects the PseudoTcpSocket to the peer with the same conversation id.
The connection will only be successful after the
PseudoTcpCallbacks:PseudoTcpOpened callback is called
Returns
TRUE on success, FALSE on failure (not in TCP_LISTEN state)
See also: pseudo_tcp_socket_get_error()
Since: 0.0.11
pseudo_tcp_socket_recv ()
gint pseudo_tcp_socket_recv (PseudoTcpSocket *self,char *buffer,size_t len);
Receive data from the socket.
Only call this on the PseudoTcpCallbacks:PseudoTcpReadable callback.
This function should be called in a loop. If this function does not
return -1 with EWOULDBLOCK as the error, the
PseudoTcpCallbacks:PseudoTcpReadable callback will not be called again.
Parameters
self |
The PseudoTcpSocket object. |
 |
buffer |
The buffer to fill with received data |
 |
len |
The length of |
 |
Since: 0.0.11
pseudo_tcp_socket_send ()
gint pseudo_tcp_socket_send (PseudoTcpSocket *self,const char *buffer,guint32 len);
Send data on the socket.
If this function return -1 with EWOULDBLOCK as the error, or if the return
value is lower than len, then the PseudoTcpCallbacks:PseudoTcpWritable
callback will be called when the socket will become writable.
Parameters
self |
The PseudoTcpSocket object. |
 |
buffer |
The buffer with data to send |
 |
len |
The length of |
 |
Since: 0.0.11
pseudo_tcp_socket_close ()
void pseudo_tcp_socket_close (PseudoTcpSocket *self,gboolean force);
Close the socket for sending. If force
is set to FALSE, the socket will
finish sending pending data before closing. If it is set to TRUE, the socket
will discard pending data and close the connection immediately (sending a TCP
RST segment).
The socket will be closed in both directions – sending and receiving – and
any pending received data must be read before calling this function, by
calling pseudo_tcp_socket_recv() until it blocks. If any pending data is in
the receive buffer when pseudo_tcp_socket_close() is called, a TCP RST
segment will be sent to the peer to notify it of the data loss.
The PseudoTcpCallbacks:PseudoTcpClosed callback will not be called once
the socket gets closed. It is only used for aborted connection.
Instead, the socket gets closed when the pseudo_tcp_socket_get_next_clock()
function returns FALSE.
See also: pseudo_tcp_socket_get_next_clock()
Parameters
self |
The PseudoTcpSocket object. |
 |
force |
|
 |
Since: 0.0.11
pseudo_tcp_socket_shutdown ()
void pseudo_tcp_socket_shutdown (PseudoTcpSocket *self,PseudoTcpShutdown how);
Shut down sending, receiving, or both on the socket, depending on the value
of how
. The behaviour of pseudo_tcp_socket_send() and
pseudo_tcp_socket_recv() will immediately change after this function returns
(depending on the value of how
), though the socket may continue to process
network traffic in the background even if sending or receiving data is
forbidden.
This is equivalent to the POSIX shutdown() function. Setting how
to
PSEUDO_TCP_SHUTDOWN_RDWR is equivalent to calling pseudo_tcp_socket_close().
Since: 0.1.8
pseudo_tcp_socket_is_closed ()
gboolean
pseudo_tcp_socket_is_closed (PseudoTcpSocket *self);
Gets whether the socket is closed, with the shutdown handshake completed, and both peers no longer able to read or write data to the connection.
Since: 0.1.8
pseudo_tcp_socket_is_closed_remotely ()
gboolean
pseudo_tcp_socket_is_closed_remotely (PseudoTcpSocket *self);
Gets whether the socket has been closed on the remote peer’s side of the
connection (i.e. whether pseudo_tcp_socket_close() has been called there).
This is guaranteed to return TRUE if pseudo_tcp_socket_is_closed() returns
TRUE. It will not return TRUE after pseudo_tcp_socket_close() is called
until a FIN segment is received from the remote peer.
Since: 0.1.8
pseudo_tcp_socket_get_error ()
int
pseudo_tcp_socket_get_error (PseudoTcpSocket *self);
Return the last encountered error.
The return value can be :
EINVAL (for pseudo_tcp_socket_connect()).
EWOULDBLOCK or ENOTCONN (for pseudo_tcp_socket_recv() and
pseudo_tcp_socket_send()).
Returns
The error code
See also: pseudo_tcp_socket_connect()
See also: pseudo_tcp_socket_recv()
See also: pseudo_tcp_socket_send()
Since: 0.0.11
pseudo_tcp_socket_get_next_clock ()
gboolean pseudo_tcp_socket_get_next_clock (PseudoTcpSocket *self,guint64 *timeout);
Call this to determine the timeout needed before the next time call
to pseudo_tcp_socket_notify_clock() should be made.
Parameters
self |
The PseudoTcpSocket object. |
 |
timeout |
A pointer to be filled with the new timeout. |
 |
Returns
TRUE if timeout
was filled, FALSE if the socket is closed and
ready to be destroyed.
See also: pseudo_tcp_socket_notify_clock()
Since: 0.0.11
pseudo_tcp_socket_notify_clock ()
void
pseudo_tcp_socket_notify_clock (PseudoTcpSocket *self);
Start the processing of receiving data, pending data or syn/acks.
Call this based on timeout value returned by
pseudo_tcp_socket_get_next_clock().
It's ok to call this too frequently.
See also: pseudo_tcp_socket_get_next_clock()
Since: 0.0.11
pseudo_tcp_socket_notify_mtu ()
void pseudo_tcp_socket_notify_mtu (PseudoTcpSocket *self,guint16 mtu);
Set the MTU of the socket
Since: 0.0.11
pseudo_tcp_socket_notify_packet ()
gboolean pseudo_tcp_socket_notify_packet (PseudoTcpSocket *self,const gchar *buffer,guint32 len);
Notify the PseudoTcpSocket when a new packet arrives
Parameters
self |
The PseudoTcpSocket object. |
 |
buffer |
The buffer containing the received data |
 |
len |
The length of |
 |
Since: 0.0.11
pseudo_tcp_set_debug_level ()
void
pseudo_tcp_set_debug_level (PseudoTcpDebugLevel level);
Sets the debug level to enable/disable normal/verbose debug messages.
Since: 0.0.11
pseudo_tcp_socket_get_available_bytes ()
gint
pseudo_tcp_socket_get_available_bytes (PseudoTcpSocket *self);
Gets the number of bytes of data in the buffer that can be read without receiving more packets from the network.
Since: 0.1.5
pseudo_tcp_socket_can_send ()
gboolean
pseudo_tcp_socket_can_send (PseudoTcpSocket *self);
Returns if there is space in the send buffer to send any data.
Since: 0.1.5
pseudo_tcp_socket_get_available_send_space ()
gsize
pseudo_tcp_socket_get_available_send_space
(PseudoTcpSocket *self);
Gets the number of bytes of space available in the transmission buffer.
Since: 0.1.5
pseudo_tcp_socket_notify_message ()
gboolean pseudo_tcp_socket_notify_message (PseudoTcpSocket *self,NiceInputMessage *message);
Notify the PseudoTcpSocket that a new message has arrived, and enqueue the data in its buffers to the PseudoTcpSocket’s receive buffer.
Parameters
self |
The PseudoTcpSocket object. |
 |
message |
A NiceInputMessage containing the received data. |
 |
Since: 0.1.5
pseudo_tcp_socket_set_time ()
void pseudo_tcp_socket_set_time (PseudoTcpSocket *self,guint32 current_time);
Sets the current monotonic time to be used by the TCP socket when calculating
timeouts and expiry times. If this function is not called, or is called with
current_time
as zero, g_get_monotonic_time() will be used. Otherwise, the
specified current_time
will be used until it is updated by calling this
function again.
This function is intended for testing only, and should not be used in production code.
Parameters
self |
The PseudoTcpSocket object. |
 |
current_time |
Current monotonic time, in milliseconds; or zero to use the system monotonic clock. |
 |
Since: 0.1.8
Types and Values
PseudoTcpSocket
typedef struct _PseudoTcpSocket PseudoTcpSocket;
The PseudoTcpSocket is the GObject implementing the Pseudo TCP Socket
Since: 0.0.11
enum PseudoTcpState
An enum representing the state of the PseudoTcpSocket. These states correspond to the TCP states in RFC 793.
See also: “stateâ€
Members
|
The socket's initial state. The socket isn't connected and is listening for an incoming connection |
 | |
|
The socket has sent a connection request (SYN) packet and is waiting for an answer |
 | |
|
The socket has received a connection request (SYN) packet. |
 | |
|
The socket is connected |
 | |
|
The socket has been closed |
 | |
|
The socket has been closed locally but not remotely (Since: 0.1.8) |
 | |
|
The socket has been closed locally but not remotely (Since: 0.1.8) |
 | |
|
The socket has been closed locally and remotely (Since: 0.1.8) |
 | |
|
The socket has been closed locally and remotely (Since: 0.1.8) |
 | |
|
The socket has been closed remotely but not locally (Since: 0.1.8) |
 | |
|
The socket has been closed locally and remotely (Since: 0.1.8) |
 |
Since: 0.0.11
enum PseudoTcpWriteResult
An enum representing the result value of the write operation requested by the PseudoTcpSocket.
See also: PseudoTcpCallbacks:WritePacket
Since: 0.0.11
PseudoTcpCallbacks
typedef struct {
gpointer user_data;
void (*PseudoTcpOpened) (PseudoTcpSocket *tcp, gpointer data);
void (*PseudoTcpReadable) (PseudoTcpSocket *tcp, gpointer data);
void (*PseudoTcpWritable) (PseudoTcpSocket *tcp, gpointer data);
void (*PseudoTcpClosed) (PseudoTcpSocket *tcp, guint32 error, gpointer data);
PseudoTcpWriteResult (*WritePacket) (PseudoTcpSocket *tcp,
const gchar * buffer, guint32 len, gpointer data);
} PseudoTcpCallbacks;
A structure containing callbacks functions that will be called by the PseudoTcpSocket when some events happen.
See also: PseudoTcpWriteResult
Members
gpointer |
A user defined pointer to be passed to the callbacks |
 |
The PseudoTcpSocket is now connected |
 | |
The socket is readable |
 | |
The socket is writable |
 | |
The socket was closed (both sides) |
 | |
This callback is called when the socket needs to send data. |
 |
Since: 0.0.11
enum PseudoTcpShutdown
Options for which parts of a connection to shut down when calling
pseudo_tcp_socket_shutdown(). These correspond to the values passed to POSIX
shutdown().
Since: 0.1.8
Property Details
The “ack-delay†property
“ack-delay†guint
Delayed ACK timeout (in milliseconds).
Flags: Read / Write
Default value: 100
The “callbacks†property
“callbacks†gpointer
Structure with the callbacks to call when PseudoTcp events happen.
Flags: Read / Write
The “conversation†property
“conversation†guint
The TCP Conversation ID.
Flags: Read / Write / Construct Only
Default value: 0
The “no-delay†property
“no-delay†gboolean
Disable the Nagle algorithm (like the TCP_NODELAY option).
Flags: Read / Write
Default value: FALSE
The “rcv-buf†property
“rcv-buf†guint
Receive Buffer size.
Flags: Read / Write
Allowed values: >= 1
Default value: 61440
The “snd-buf†property
“snd-buf†guint
Send Buffer size.
Flags: Read / Write
Allowed values: >= 1
Default value: 92160
The “state†property
“state†guint
The current state (enum PseudoTcpState) of the PseudoTcp socket.
Flags: Read
Allowed values: <= 4
Default value: 0
The “support-fin-ack†property
“support-fin-ack†gboolean
Whether to support the FIN–ACK extension to the pseudo-TCP protocol for this socket. The extension is only compatible with other libnice pseudo-TCP stacks, and not with Jingle pseudo-TCP stacks. If enabled, support is negotiatied on connection setup, so it is safe for a PseudoTcpSocket with support enabled to be used with one with it disabled, or with a Jingle pseudo-TCP socket which doesn’t support it at all.
Support is enabled by default.
Flags: Read / Write / Construct Only
Default value: TRUE
Since: 0.1.8
|
|
|
|
- StunAgent — STUN agent for building and validating STUN messages
- StunMessage — STUN messages parsing and formatting functions
- STUN Constants — STUN constants
| Top | |
|
|
|
Network interfaces discoveryNetwork interfaces discovery — Utility functions to discover local network interfaces |
Description
These utility functions allow the discovery of local network interfaces in a portable manner, they also allow finding the local ip addresses or the address allocated to a network interface.
Functions
nice_interfaces_get_ip_for_interface ()
gchar *
nice_interfaces_get_ip_for_interface (gchar *interface_name);
Retrieves the IP address of an interface by its name. If this fails, NULL
is returned.
nice_interfaces_get_local_interfaces ()
GList *
nice_interfaces_get_local_interfaces (void);
Get the list of local interfaces
Returns
a newly-allocated GList of strings. The caller must free it.
[element-type utf8][transfer full]
| Top | |
|
|
|
Functions
| bool | (*StunMessageIntegrityValidate)Â () |
| void | (*StunDebugHandler)Â () |
| void | stun_agent_init () |
| StunValidationStatus | stun_agent_validate () |
| bool | stun_agent_default_validater () |
| bool | stun_agent_init_request () |
| bool | stun_agent_init_indication () |
| bool | stun_agent_init_response () |
| bool | stun_agent_init_error () |
| size_t | stun_agent_build_unknown_attributes_error () |
| size_t | stun_agent_finish_message () |
| bool | stun_agent_forget_transaction () |
| void | stun_agent_set_software () |
| void | stun_debug_enable () |
| void | stun_debug_disable () |
| void | stun_set_debug_handler () |
Types and Values
| typedef | StunAgent |
| enum | StunCompatibility |
| enum | StunAgentUsageFlags |
| enum | StunValidationStatus |
| Â | StunDefaultValidaterData |
Description
The STUN Agent allows you to create and validate STUN messages easily. It's main purpose is to make sure the building and validation methods used are compatible with the RFC you create it with. It also tracks the transaction ids of the requests you send, so you can validate if a STUN response you received should be processed by that agent or not.
Functions
StunMessageIntegrityValidate ()
bool (*StunMessageIntegrityValidate) (StunAgent *agent,StunMessage *message,uint8_t *username,uint16_t username_len,uint8_t **password,size_t *password_len,void *user_data);
This is the prototype for the validater
argument of the stun_agent_validate()
function.
See also: stun_agent_validate()
Parameters
agent |
The StunAgent |
 |
message |
The StunMessage being validated |
 |
username |
The username found in the |
 |
username_len |
The length of |
 |
password |
The password associated with that username. This argument is a pointer to a byte array that must be set by the validater function. |
 |
password_len |
The length of |
 |
user_data |
Data to give the function |
 |
StunDebugHandler ()
void (*StunDebugHandler) (const char *format,va_list ap);
Callback for a debug message from the STUN code.
stun_agent_init ()
void stun_agent_init (StunAgent *agent,const uint16_t *known_attributes,StunCompatibility compatibility,StunAgentUsageFlags usage_flags);
This function must be called to initialize an agent before it is being used.
The known_attributes data must exist in memory as long as the agent is used
If the STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS and STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS usage flags are not set, then the agent will default in using the short term credentials mechanism
The STUN_AGENT_USAGE_USE_FINGERPRINT and STUN_AGENT_USAGE_ADD_SOFTWARE
usage flags are only valid if the STUN_COMPATIBILITY_RFC5389 or
STUN_COMPATIBILITY_MSICE2 compatibility is used
Parameters
agent |
The StunAgent to initialize |
 |
known_attributes |
An array of uint16_t specifying which attributes should
be known by the agent. Any STUN message received that contains a mandatory
attribute that is not in this array will yield a
STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE or a
STUN_VALIDATION_UNKNOWN_ATTRIBUTE error when calling |
 |
compatibility |
The StunCompatibility to use for this agent. This will affect how the agent builds and validates the STUN messages |
 |
usage_flags |
A bitflag using StunAgentUsageFlags values to define which STUN usages the agent should use. |
 |
stun_agent_validate ()
StunValidationStatus stun_agent_validate (StunAgent *agent,StunMessage *msg,const uint8_t *buffer,size_t buffer_len,StunMessageIntegrityValidate validater,void *validater_data);
This function is used to validate an inbound STUN message and transform its data buffer into a StunMessage. It will take care of various validation algorithms to make sure that the STUN message is valid and correctly authenticated.
See also: stun_agent_default_validater()
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The data buffer of the STUN message |
 |
buffer_len |
The length of |
 |
validater |
A StunMessageIntegrityValidate function callback that will be called if the agent needs to validate a MESSAGE-INTEGRITY attribute. It will only be called if the agent finds a message that needs authentication and a USERNAME is present in the STUN message, but no password is known. The validater will not be called if the STUN_AGENT_USAGE_IGNORE_CREDENTIALS usage flag is set on the agent, and it will always be called if the STUN_AGENT_USAGE_FORCE_VALIDATER usage flag is set on the agent. |
 |
validater_data |
A user data to give to the |
 |
Returns
if the return value is different from STUN_VALIDATION_NOT_STUN or
STUN_VALIDATION_INCOMPLETE_STUN, then the msg argument will contain a valid
STUN message that can be used.
This means that you can use the msg variable as the request argument to
functions like stun_agent_init_error() or
stun_agent_build_unknown_attributes_error().
If the return value is STUN_VALIDATION_BAD_REQUEST,
STUN_VALIDATION_UNAUTHORIZED or STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST
then the key in the StunMessage will not be set, so that error responses
will not have a MESSAGE-INTEGRITY attribute.
stun_agent_default_validater ()
bool stun_agent_default_validater (StunAgent *agent,StunMessage *message,uint8_t *username,uint16_t username_len,uint8_t **password,size_t *password_len,void *user_data);
This is a helper function to be used with stun_agent_validate(). If no
complicated processing of the username needs to be done, this function can
be used with stun_agent_validate() to quickly and easily match the username
of a STUN message with its password. Its user_data
argument must be an array
of StunDefaultValidaterData which will allow us to map a username to a
password
See also: stun_agent_validate()
Parameters
agent |
The StunAgent |
 |
message |
The StunMessage being validated |
 |
username |
The username found in the |
 |
username_len |
The length of |
 |
password |
The password associated with that username. This argument is a pointer to a byte array that must be set by the validater function. |
 |
password_len |
The length of |
 |
user_data |
This must be an array of StunDefaultValidaterData structures. The last element in the array must have a username set to NULL |
 |
stun_agent_init_request ()
bool stun_agent_init_request (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,StunMethod m);
Creates a new STUN message of class STUN_REQUEST and with the method m
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use in the StunMessage |
 |
buffer_len |
The length of the buffer |
 |
m |
The StunMethod of the request |
 |
stun_agent_init_indication ()
bool stun_agent_init_indication (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,StunMethod m);
Creates a new STUN message of class STUN_INDICATION and with the method m
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use in the StunMessage |
 |
buffer_len |
The length of the buffer |
 |
m |
The StunMethod of the indication |
 |
stun_agent_init_response ()
bool stun_agent_init_response (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,const StunMessage *request);
Creates a new STUN message of class STUN_RESPONSE and with the same method
and transaction ID as the message request
. This will also copy the pointer
to the key that was used to authenticate the request, so you won't need to
specify the key with stun_agent_finish_message()
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use in the StunMessage |
 |
buffer_len |
The length of the buffer |
 |
request |
The StunMessage of class STUN_REQUEST that this response is for |
 |
stun_agent_init_error ()
bool stun_agent_init_error (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,const StunMessage *request,StunError err);
Creates a new STUN message of class STUN_ERROR and with the same method
and transaction ID as the message request
. This will also copy the pointer
to the key that was used to authenticate the request (if authenticated),
so you won't need to specify the key with stun_agent_finish_message().
It will then add the ERROR-CODE attribute with code err
and the associated
string.
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use in the StunMessage |
 |
buffer_len |
The length of the buffer |
 |
request |
The StunMessage of class STUN_REQUEST that this error response is for |
 |
err |
The StunError to put in the ERROR-CODE attribute of the error response |
 |
stun_agent_build_unknown_attributes_error ()
size_t stun_agent_build_unknown_attributes_error (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,const StunMessage *request);
Creates a new STUN message of class STUN_ERROR and with the same method
and transaction ID as the message request
. It will then add the ERROR-CODE
attribute with code STUN_ERROR_UNKNOWN_ATTRIBUTE and add all the unknown
mandatory attributes from the request
STUN message in the
STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES attribute, it will then finish the message
by calling stun_agent_finish_message()
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use in the StunMessage |
 |
buffer_len |
The length of the buffer |
 |
request |
The StunMessage of class STUN_REQUEST that this response is for |
 |
stun_agent_finish_message ()
size_t stun_agent_finish_message (StunAgent *agent,StunMessage *msg,const uint8_t *key,size_t key_len);
This function will 'finish' a message and make it ready to be sent. It will add the MESSAGE-INTEGRITY and FINGERPRINT attributes if necessary. If the STUN message has a STUN_REQUEST class, it will save the transaction id of the message in the agent for future matching of the response.
See also: stun_agent_forget_transaction()
Parameters
agent |
The StunAgent |
 |
msg |
The StunMessage to finish |
 |
key |
The key to use for the MESSAGE-INTEGRITY attribute |
 |
key_len |
The length of the |
 |
Returns
The final size of the message built or 0 if an error occured
The return value must always be checked. a value of 0 means the either the buffer's size is too small to contain the finishing attributes (MESSAGE-INTEGRITY, FINGERPRINT), or that there is no more free slots for saving the sent id in the agent's state.
Everytime stun_agent_finish_message() is called for a STUN_REQUEST
message, you must make sure to call stun_agent_forget_transaction() in
case the response times out and is never received. This is to avoid
filling up the StunAgent's sent ids state preventing any further
use of the stun_agent_finish_message()
stun_agent_forget_transaction ()
bool stun_agent_forget_transaction (StunAgent *agent,StunTransactionId id);
This function is used to make the StunAgent forget about a previously created transaction.
This function should be called when a STUN request was previously
created with stun_agent_finish_message() and for which no response was ever
received (timed out). The StunAgent keeps a list of the sent transactions
in order to validate the responses received. If the response is never received
this will allow the StunAgent to forget about the timed out transaction and
free its slot for future transactions.
Since: 0.0.6
stun_agent_set_software ()
void stun_agent_set_software (StunAgent *agent,const char *software);
This function will set the value of the SOFTWARE attribute to be added to STUN requests, responses and error responses.
Calling this function will automatically enable the addition of the SOFTWARE attribute for RFC5389 and MSICE2 compatibility modes.
The software argument must be in UTF-8 encoding and only the first
128 characters will be sent.
The value of the software argument must stay valid throughout the life of
the StunAgent's life. Do not free its content.
Since: 0.0.10
stun_set_debug_handler ()
void
stun_set_debug_handler (StunDebugHandler handler);
Set a callback function to be invoked for each debug message from the STUN
code. The callback will only be invoked if STUN debugging is enabled using
stun_debug_enable().
The default callback prints the formatted debug message to stderr.
Types and Values
enum StunCompatibility
Enum that specifies the STUN compatibility mode of the StunAgent
STUN_COMPATIBILITY_WLM2009 is deprecated and should not be used
in newly-written code. It is kept for compatibility reasons and represents
the same compatibility as STUN_COMPATIBILITY_MSICE2.Members
|
Use the STUN specifications compatible with RFC 3489 |
 | |
|
Use the STUN specifications compatible with RFC 5389 |
 | |
|
Use the STUN specifications compatible with [MS-ICE2] (a mix between RFC3489 and RFC5389) |
 | |
|
Use the STUN specifications compatible with Microsoft Office Communicator 2007 (basically RFC3489 with swapped REALM and NONCE attribute hex IDs, attributes are not aligned) |
 | |
|
An alias for |
 | |
|
Dummy last compatibility mode |
 |
enum StunAgentUsageFlags
This enum defines a bitflag usages for a StunAgent and they will define how the agent should behave, independently of the compatibility mode it uses.
See also: stun_agent_init()
See also: stun_agent_validate()
Members
|
The agent should be using the short term credentials mechanism for authenticating STUN messages |
 | |
|
The agent should be using the long term credentials mechanism for authenticating STUN messages |
 | |
|
The agent should add the FINGERPRINT attribute to the STUN messages it creates. |
 | |
|
The agent should add the SOFTWARE attribute
to the STUN messages it creates. Calling |
 | |
|
The agent should ignore any credentials
in the STUN messages it receives (the MESSAGE-INTEGRITY attribute
will never be validated by |
 | |
|
The agent should ignore credentials in the STUN messages it receives if the StunClass of the message is STUN_INDICATION (some implementation require STUN_INDICATION messages to be authenticated, while others never add a MESSAGE-INTEGRITY attribute to a STUN_INDICATION message) |
 | |
|
The agent should always try to validate the password of a STUN message, even if it already knows what the password should be (a response to a previously created request). This means that the StunMessageIntegrityValidate callback will always be called when there is a MESSAGE-INTEGRITY attribute. |
 | |
|
The agent should not assume STUN attributes are aligned on 32-bit boundaries when parsing messages and also do not add padding when creating messages. |
 |
enum StunValidationStatus
This enum is used as the return value of stun_agent_validate() and represents
the status result of the validation of a STUN message.
Members
|
The message is validated |
 | |
|
This is not a valid STUN message |
 | |
|
The message seems to be valid but incomplete |
 | |
|
The message does not have the cookie or the fingerprint while the agent needs it with its usage |
 | |
|
The message is valid but unauthorized with no username and message-integrity attributes. A BAD_REQUEST error must be generated |
 | |
|
The message is valid but unauthorized as the username/password do not match. An UNAUTHORIZED error must be generated |
 | |
|
The message is valid but this is a response/error that doesn't match a previously sent request |
 | |
|
The message is valid but
contains one or more unknown comprehension attributes.
|
 | |
|
The message is valid but contains one or more unknown comprehension attributes. This is a response, or error, or indication message and no error response should be sent |
 |
StunDefaultValidaterData
typedef struct {
uint8_t *username;
size_t username_len;
uint8_t *password;
size_t password_len;
} StunDefaultValidaterData;
This structure is used as an element of the user_data to the
stun_agent_default_validater() function for authenticating a STUN
message during validationg.
See also: stun_agent_default_validater()
|
|
|
|
A
C
D
I
N
O
P
R
S
T
|
|
|
|
Table of Contents
- StunAgent — STUN agent for building and validating STUN messages
- StunMessage — STUN messages parsing and formatting functions
- STUN Constants — STUN constants
- STUN usages
| Top | |
|
|
|
Functions
| void | nice_address_init () |
| NiceAddress * | nice_address_new () |
| void | nice_address_free () |
| NiceAddress * | nice_address_dup () |
| void | nice_address_set_ipv4Â () |
| void | nice_address_set_ipv6Â () |
| void | nice_address_set_port () |
| guint | nice_address_get_port () |
| gboolean | nice_address_set_from_string () |
| void | nice_address_set_from_sockaddr () |
| void | nice_address_copy_to_sockaddr () |
| gboolean | nice_address_equal () |
| gboolean | nice_address_equal_no_port () |
| void | nice_address_to_string () |
| gboolean | nice_address_is_private () |
| gboolean | nice_address_is_valid () |
| int | nice_address_ip_version () |
Description
The NiceAddress structure will allow you to easily set/get and modify an IPv4 or IPv6 address in order to communicate with the NiceAgent.
Functions
nice_address_init ()
void
nice_address_init (NiceAddress *addr);
Initialize a NiceAddress into an undefined address
nice_address_new ()
NiceAddress *
nice_address_new (void);
Create a new NiceAddress with undefined address
You must free it with nice_address_free()
nice_address_free ()
void
nice_address_free (NiceAddress *addr);
Frees a NiceAddress created with nice_address_new() or nice_address_dup()
nice_address_dup ()
NiceAddress *
nice_address_dup (const NiceAddress *addr);
Creates a new NiceAddress with the same address as addr
nice_address_set_ipv4Â ()
void nice_address_set_ipv4 (NiceAddress *addr,guint32 addr_ipv4);
Set addr
to an IPv4 address using the data from addr_ipv4
This function will reset the port to 0, so make sure you call it before
nice_address_set_port()
nice_address_set_ipv6Â ()
void nice_address_set_ipv6 (NiceAddress *addr,const guchar *addr_ipv6);
Set addr
to an IPv6 address using the data from addr_ipv6
This function will reset the port to 0, so make sure you call it before
nice_address_set_port()
nice_address_set_port ()
void nice_address_set_port (NiceAddress *addr,guint port);
Set the port of addr
to port
nice_address_get_port ()
guint
nice_address_get_port (const NiceAddress *addr);
Retreive the port of addr
nice_address_set_from_string ()
gboolean nice_address_set_from_string (NiceAddress *addr,const gchar *str);
Sets an IPv4 or IPv6 address from the string str
nice_address_set_from_sockaddr ()
void nice_address_set_from_sockaddr (NiceAddress *addr,const struct sockaddr *sin);
Sets an IPv4 or IPv6 address from the sockaddr structure sin
nice_address_copy_to_sockaddr ()
void nice_address_copy_to_sockaddr (const NiceAddress *addr,struct sockaddr *sin);
Fills the sockaddr structure sin
with the address contained in addr
nice_address_equal ()
gboolean nice_address_equal (const NiceAddress *a,const NiceAddress *b);
Compares two NiceAddress structures to see if they contain the same address and the same port.
nice_address_equal_no_port ()
gboolean nice_address_equal_no_port (const NiceAddress *a,const NiceAddress *b);
Compares two NiceAddress structures to see if they contain the same address, ignoring the port.
Since: 0.1.8
nice_address_to_string ()
void nice_address_to_string (const NiceAddress *addr,gchar *dst);
Transforms the address addr
into a human readable string
nice_address_is_private ()
gboolean
nice_address_is_private (const NiceAddress *addr);
Verifies if the address in addr
is a private address or not
nice_address_is_valid ()
gboolean
nice_address_is_valid (const NiceAddress *addr);
Validate whether the NiceAddress addr
is a valid IPv4 or IPv6 address
nice_address_ip_version ()
int
nice_address_ip_version (const NiceAddress *addr);
Returns the IP version of the address
Types and Values
NiceAddress
typedef struct {
union
{
struct sockaddr addr;
struct sockaddr_in ip4;
struct sockaddr_in6 ip6;
} s;
} NiceAddress;
The NiceAddress structure that represents an IPv4 or IPv6 address.
NICE_ADDRESS_STRING_LEN
#define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
The maximum string length representation of an address.
When using nice_address_to_string() make sure the string has a size of
at least NICE_ADDRESS_STRING_LEN
| Top | |
|
|
|
Functions
| size_t | stun_usage_turn_create () |
| size_t | stun_usage_turn_create_refresh () |
| StunUsageTurnReturn | stun_usage_turn_process () |
| StunUsageTurnReturn | stun_usage_turn_refresh_process () |
| size_t | stun_usage_turn_create_permission () |
Description
The STUN TURN usage allows for easily creating and parsing STUN Allocate requests and responses used for TURN. The API allows you to create a new allocation or refresh an existing one as well as to parse a response to an allocate or refresh request.
Functions
stun_usage_turn_create ()
size_t stun_usage_turn_create (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,StunMessage *previous_response,StunUsageTurnRequestPorts request_ports,int32_t bandwidth,int32_t lifetime,uint8_t *username,size_t username_len,uint8_t *password,size_t password_len,StunUsageTurnCompatibility compatibility);
Create a new TURN Allocation request
Parameters
agent |
The StunAgent to use to build the request |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use for creating the StunMessage |
 |
buffer_len |
The size of the |
 |
previous_response |
If this is the first request you are sending, set this argument to NULL, if it's a subsequent request you are building, then set this argument to the response you have received. This argument is used for building long term credentials (using the REALM and NONCE attributes) as well as for getting the RESERVATION-TOKEN attribute when you previously requested an allocation which reserved two ports |
 |
request_ports |
Specify how you want to request the allocated port(s). This is only used if the compatibility is set to STUN_USAGE_TURN_COMPATIBILITY_DRAFT9 |
 |
bandwidth |
The bandwidth to request from the server for the allocation. If this value is negative, then no BANDWIDTH attribute is added to the request. This is only used if the compatibility is set to STUN_USAGE_TURN_COMPATIBILITY_DRAFT9 |
 |
lifetime |
The lifetime of the allocation to request from the server. If this value is negative, then no LIFETIME attribute is added to the request. This is only used if the compatibility is set to STUN_USAGE_TURN_COMPATIBILITY_DRAFT9 |
 |
username |
The username to use in the request |
 |
username_len |
The length of |
 |
password |
The key to use for building the MESSAGE-INTEGRITY |
 |
password_len |
The length of |
 |
compatibility |
The compatibility mode to use for building the Allocation request |
 |
stun_usage_turn_create_refresh ()
size_t stun_usage_turn_create_refresh (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,StunMessage *previous_response,int32_t lifetime,uint8_t *username,size_t username_len,uint8_t *password,size_t password_len,StunUsageTurnCompatibility compatibility);
Create a new TURN Refresh request
Parameters
agent |
The StunAgent to use to build the request |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use for creating the StunMessage |
 |
buffer_len |
The size of the |
 |
previous_response |
If this is the first request you are sending, set this argument to NULL, if it's a subsequent request you are building, then set this argument to the response you have received. This argument is used for building long term credentials (using the REALM and NONCE attributes) |
 |
lifetime |
The lifetime of the allocation to request from the server. If this value is negative, then no LIFETIME attribute is added to the request. This is only used if the compatibility is set to STUN_USAGE_TURN_COMPATIBILITY_DRAFT9 |
 |
username |
The username to use in the request |
 |
username_len |
The length of |
 |
password |
The key to use for building the MESSAGE-INTEGRITY |
 |
password_len |
The length of |
 |
compatibility |
The compatibility mode to use for building the Allocation request |
 |
stun_usage_turn_process ()
StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,struct sockaddr_storage *relay_addr,socklen_t *relay_addrlen,struct sockaddr_storage *addr,socklen_t *addrlen,struct sockaddr_storage *alternate_server,socklen_t *alternate_server_len,uint32_t *bandwidth,uint32_t *lifetime,StunUsageTurnCompatibility compatibility);
Process a TURN Allocate response and extract the necessary information from the message
Parameters
msg |
The message containing the response |
 |
relay_addr |
A pointer to a sockaddr structure to fill with the relay address that the TURN server allocated for us |
 |
relay_addrlen |
The length of |
 |
addr |
A pointer to a sockaddr structure to fill with the mapped address that the STUN response contains. This argument will only be filled if the return value of the function is STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS |
 |
addrlen |
The length of |
 |
alternate_server |
A pointer to a sockaddr structure to fill with the
address of an alternate server to which we should send our new STUN
Allocate request, in case the currently used TURN server is requesting the use
of an alternate server. This argument will only be filled if the return value
of the function is STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER
In the case of |
 |
alternate_server_len |
The length of |
 |
bandwidth |
A pointer to fill with the bandwidth the TURN server allocated us |
 |
lifetime |
A pointer to fill with the lifetime of the allocation |
 |
compatibility |
The compatibility mode to use for processing the Allocation response |
 |
stun_usage_turn_refresh_process ()
StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg,uint32_t *lifetime,StunUsageTurnCompatibility compatibility);
Process a TURN Refresh response and extract the necessary information from the message
Parameters
msg |
The message containing the response |
 |
lifetime |
A pointer to fill with the lifetime of the allocation |
 |
compatibility |
The compatibility mode to use for processing the Refresh response |
 |
Returns
A StunUsageTurnReturn value. A STUN_USAGE_TURN_RETURN_RELAY_SUCCESS means the Refresh was successful, but no relay address is given (kept the same as for the original allocation)
stun_usage_turn_create_permission ()
size_t stun_usage_turn_create_permission (StunAgent *agent,StunMessage *msg,uint8_t *buffer,size_t buffer_len,uint8_t *username,size_t username_len,uint8_t *password,size_t password_len,uint8_t *realm,size_t realm_len,uint8_t *nonce,size_t nonce_len,struct sockaddr_storage *peer,StunUsageTurnCompatibility compatibility);
Create a new TURN CreatePermission request
Parameters
agent |
The StunAgent to use to build the request |
 |
msg |
The StunMessage to build |
 |
buffer |
The buffer to use for creating the StunMessage |
 |
buffer_len |
The size of the |
 |
username |
The username to use in the request |
 |
username_len |
The length of |
 |
password |
The key to use for building the MESSAGE-INTEGRITY |
 |
password_len |
The length of |
 |
realm |
The realm identifier to use in the request |
 |
realm_len |
The length of |
 |
nonce |
Unique and securely random nonce to use in the request |
 |
nonce_len |
The length of |
 |
peer |
Server-reflexive host address to request permission for |
 |
compatibility |
The compatibility mode to use for building the CreatePermission request |
 |
Types and Values
enum StunUsageTurnCompatibility
Specifies which TURN specification compatibility to use
Members
|
Use the specification compatible with TURN Draft 09 |
 | |
|
Use the specification compatible with Google Talk's relay server |
 | |
|
Use the specification compatible with MSN TURN servers |
 | |
|
Use the specification compatible with Microsoft Office Communicator 2007 |
 | |
|
Use the specification compatible with RFC 5766 (the final, canonical TURN standard) |
 |
enum StunUsageTurnRequestPorts
This enum is used to specify which port configuration you want when creating a new Allocation
enum StunUsageTurnReturn
Return value of stun_usage_turn_process() and
stun_usage_turn_refresh_process() which allows you to see what status the
function call returned.
Members
|
The response was successful and a relay address is provided |
 | |
|
The response was successful and a relay address as well as a mapped address are provided |
 | |
|
The response resulted in an error |
 | |
|
The response is not a valid response |
 | |
|
The server requests the message to be sent to an alternate server |
 |
|
|
|
|
A
|
|
|
|
Table of Contents
- NiceAgent — ICE agent API implementation
- NiceAddress — IP address convenience library
- NiceCandidate — ICE candidate representation
- Libnice helper functions
- Debug messages — Debug messages utility functions
- Network interfaces discovery — Utility functions to discover local network interfaces