Commit cf920a85 authored by Youness Alaoui's avatar Youness Alaoui

Update docs, finish formatting the gtk-doc and add the STUN API to the exported symbols list

parent e6b909de
......@@ -63,10 +63,6 @@
// Create a nice agent
NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_DRAFT19);
// Specify which local interface to use
nice_address_set_from_string (&base_addr, "127.0.0.1");
nice_agent_add_local_address (agent, &base_addr);
// Connect the signals
g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
G_CALLBACK (cb_candidate_gathering_done), NULL);
......@@ -359,7 +355,11 @@ gboolean nice_agent_set_relay_info(
*
<note>
<para>
Local addresses must be previously set with nice_agent_add_local_address()
Local addresses can be previously set with nice_agent_add_local_address()
</para>
<para>
If no local address was previously added, then the nice agent will
automatically detect the local address using nice_interfaces_get_local_ips()
</para>
</note>
*/
......
......@@ -1684,7 +1684,7 @@ static CandidateCheckPair *priv_process_response_check_for_peer_reflexive(NiceAg
remote_candidate);
p->state = NICE_CHECK_FAILED;
nice_debug ("Agent %p : pair %p state FAILED", agent, p);
/* step: add a new discovered pair (see ICE 7.1.2.2.2
"Constructing a Valid Pair" (ID-19)) */
new_pair = priv_add_peer_reflexive_pair (agent, stream->id, component->id, cand, p);
......@@ -1698,7 +1698,7 @@ static CandidateCheckPair *priv_process_response_check_for_peer_reflexive(NiceAg
* Tries to match STUN reply in 'buf' to an existing STUN connectivity
* check transaction. If found, the reply is processed. Implements
* section 7.1.2 "Processing the Response" of ICE spec (ID-19).
*
*
* @return TRUE if a matching transaction is found
*/
static gboolean priv_map_reply_to_conn_check_request (NiceAgent *agent, Stream *stream, Component *component, NiceSocket *sockptr, const NiceAddress *from, NiceCandidate *local_candidate, NiceCandidate *remote_candidate, StunMessage *resp)
......@@ -1816,7 +1816,7 @@ static gboolean priv_map_reply_to_conn_check_request (NiceAgent *agent, Stream *
/*
* Tries to match STUN reply in 'buf' to an existing STUN discovery
* transaction. If found, a reply is sent.
*
*
* @return TRUE if a matching transaction is found
*/
static gboolean priv_map_reply_to_discovery_request (NiceAgent *agent, StunMessage *resp)
......
......@@ -10,18 +10,37 @@
</releaseinfo>
</bookinfo>
<chapter>
<title>libnice's public API</title>
<xi:include href="xml/agent.xml"/>
<xi:include href="xml/address.xml"/>
<xi:include href="xml/debug.xml"/>
<xi:include href="xml/candidate.xml"/>
<xi:include href="xml/interfaces.xml"/>
<xi:include href="xml/stunagent.xml"/>
<xi:include href="xml/stunmessage.xml"/>
<xi:include href="xml/turn.xml"/>
<xi:include href="xml/bind.xml"/>
<xi:include href="xml/ice.xml"/>
<xi:include href="xml/timer.xml"/>
</chapter>
<part>
<title>ICE Library</title>
<chapter>
<xi:include href="xml/agent.xml"/>
<xi:include href="xml/address.xml"/>
<xi:include href="xml/candidate.xml"/>
</chapter>
<chapter>
<title>Libnice helper functions </title>
<xi:include href="xml/debug.xml"/>
<xi:include href="xml/interfaces.xml"/>
</chapter>
</part>
<part>
<title>STUN Library</title>
<chapter>
<xi:include href="xml/stunagent.xml"/>
<xi:include href="xml/stunmessage.xml"/>
</chapter>
<chapter>
<title>STUN usages</title>
<xi:include href="xml/bind.xml"/>
<xi:include href="xml/ice.xml"/>
<xi:include href="xml/turn.xml"/>
<xi:include href="xml/timer.xml"/>
</chapter>
</part>
<para>The libnice library contains both the ICE library and the
STUN library.
</para>
</book>
......@@ -37,3 +37,60 @@ nice_debug_enable
nice_interfaces_get_ip_for_interface
nice_interfaces_get_local_interfaces
nice_interfaces_get_local_ips
stun_agent_build_unknown_attributes_error
stun_agent_default_validater
stun_agent_finish_message
stun_agent_init
stun_agent_init_error
stun_agent_init_indication
stun_agent_init_request
stun_agent_init_response
stun_agent_validate
stun_debug_disable
stun_debug_enable
stun_message_append
stun_message_append32
stun_message_append64
stun_message_append_addr
stun_message_append_bytes
stun_message_append_error
stun_message_append_flag
stun_message_append_string
stun_message_append_xor_addr
stun_message_append_xor_addr_full
stun_message_find
stun_message_find32
stun_message_find64
stun_message_find_addr
stun_message_find_error
stun_message_find_flag
stun_message_find_string
stun_message_find_xor_addr
stun_message_find_xor_addr_full
stun_message_get_class
stun_message_get_method
stun_message_has_attribute
stun_message_has_cookie
stun_message_id
stun_message_init
stun_message_length
stun_message_validate_buffer_length
stun_optional
stun_strerror
stun_timer_refresh
stun_timer_remainder
stun_timer_start
stun_timer_start_reliable
stun_usage_bind_create
stun_usage_bind_keepalive
stun_usage_bind_process
stun_usage_bind_run
stun_usage_ice_conncheck_create
stun_usage_ice_conncheck_create_reply
stun_usage_ice_conncheck_priority
stun_usage_ice_conncheck_process
stun_usage_ice_conncheck_use_candidate
stun_usage_turn_create
stun_usage_turn_create_refresh
stun_usage_turn_process
stun_usage_turn_refresh_process
......@@ -36,9 +36,15 @@
#ifndef STUN_BIND_H
# define STUN_BIND_H 1
/*
* @file bind.h
* @brief STUN binding discovery
/**
* SECTION:bind
* @short_description: STUN Binding Usage
* @include: stun/usages/bind.h
* @stability: Stable
*
* 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.
*/
......
......@@ -36,9 +36,16 @@
#ifndef STUN_CONNCHECK_H
# define STUN_CONNCHECK_H 1
/*
* @file ice.h
* @brief STUN/ICE connectivity checks
/**
* SECTION:ice
* @short_description: STUN ICE Usage
* @include: stun/usages/ice.h
* @stability: Stable
*
* 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.
*/
# include "stun/stunagent.h"
......
......@@ -36,9 +36,66 @@
#ifndef STUN_TIMER_H
# define STUN_TIMER_H 1
/*
* @file timer.h
* @brief STUN retransmission timer
/**
* SECTION:timer
* @short_description: STUN timer Usage
* @include: stun/usages/timer.h
* @stability: Stable
*
* 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>
<title>Simple example on how to use the timer usage</title>
<programlisting>
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);
// 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
}
</programlisting>
</example>
*/
#ifdef _WIN32
......
......@@ -36,10 +36,19 @@
#ifndef STUN_TURN_H
# define STUN_TURN_H 1
/*
* @file bind.h
* @brief STUN binding discovery
/**
* SECTION:turn
* @short_description: TURN Allocation Usage
* @include: stun/usages/turn.h
* @stability: Stable
*
* 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.
*/
#ifdef _WIN32
#include "win32_common.h"
#else
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment