Commit 35905c4e authored by Youness Alaoui's avatar Youness Alaoui

Add documentation

parent ac6ac8a7
......@@ -13,7 +13,8 @@ ALWAYS_SUBDIRS = \
socket \
random \
agent \
nice
nice \
docs
SUBDIRS = $(ALWAYS_SUBDIRS)
if WITH_GSTREAMER
......@@ -21,7 +22,7 @@ SUBDIRS += gst
endif
DIST_SUBDIRS = $(ALWAYS_SUBDIRS) gst
DISTCHECK_CONFIGURE_FLAGS = --disable-assert
DISTCHECK_CONFIGURE_FLAGS = --disable-assert -enable-gtk-doc
EXTRA_DIST = \
common.mk \
......
......@@ -36,10 +36,6 @@
* file under either the MPL or the LGPL.
*/
/**
* @file agent.c
* @brief ICE agent API implementation
*/
#ifdef HAVE_CONFIG_H
# include <config.h>
......@@ -399,13 +395,6 @@ nice_agent_init (NiceAgent *agent)
}
/**
* nice_agent_new:
*
* Create a new NiceAgent.
*
* Returns: the new agent
**/
NICEAPI_EXPORT NiceAgent *
nice_agent_new (GMainContext *ctx, NiceCompatibility compat)
{
......@@ -768,18 +757,6 @@ priv_add_new_candidate_discovery_turn (NiceAgent *agent,
return FALSE;
}
/**
* nice_agent_add_stream:
* @agent: a NiceAgent
* @n_components: number of components
*
* Add a data stream to @agent.
*
* @pre local addresses must be set with nice_agent_add_local_address()
*
* Returns: the ID of the new stream, 0 on failure
**/
NICEAPI_EXPORT guint
nice_agent_add_stream (
NiceAgent *agent,
......@@ -850,12 +827,6 @@ nice_agent_set_relay_info(NiceAgent *agent,
}
/**
* nice_agent_gather_candidates:
*
* start the candidate gathering process
*/
NICEAPI_EXPORT void
nice_agent_gather_candidates (
NiceAgent *agent,
......@@ -958,11 +929,6 @@ static void priv_remove_keepalive_timer (NiceAgent *agent)
}
}
/**
* nice_agent_remove_stream:
* @agent: a NiceAgent
* @stream_id: the ID of the stream to remove
**/
NICEAPI_EXPORT void
nice_agent_remove_stream (
NiceAgent *agent,
......@@ -1000,16 +966,6 @@ nice_agent_remove_stream (
g_static_rec_mutex_unlock (&agent->mutex);
}
/**
* nice_agent_add_local_address:
* @agent: A NiceAgent
* @addr: the address of a local IP interface
*
* Inform the agent of the presence of an address that a local
* network interface is bound to.
*
* @return FALSE on fatal (memory allocation) errors
**/
NICEAPI_EXPORT gboolean
nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr)
{
......@@ -1034,12 +990,6 @@ nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr)
return ret;
}
/**
* Adds a new, or updates an existing, remote candidate.
*
* @return TRUE if candidate was succesfully added or
* update, otherwise FALSE
*/
static gboolean priv_add_remote_candidate (
NiceAgent *agent,
guint stream_id,
......@@ -1135,21 +1085,6 @@ static gboolean priv_add_remote_candidate (
return TRUE;
}
/**
* Sets the remote credentials for stream 'stream_id'.
*
* Note: stream credentials do not override per-candidate
* credentials if set
*
* @agent: a NiceAgent
* @stream_id: identifier returnedby nice_agent_add_stream()
* @ufrag: NULL-terminated string containing an ICE username fragment
* (length must be between 22 and 256 chars)
* @pwd: NULL-terminated string containing an ICE password
* (length must be between 4 and 256 chars)
*
* @return TRUE on success
*/
NICEAPI_EXPORT gboolean
nice_agent_set_remote_credentials (
NiceAgent *agent,
......@@ -1177,18 +1112,7 @@ nice_agent_set_remote_credentials (
return ret;
}
/**
* Gets the local credentials for stream 'stream_id'.
*
* @agent: a NiceAgent
* @stream_id: identifier returnedby nice_agent_add_stream()
* @ufrag: a pointer to a NULL-terminated string containing
* an ICE username fragment [OUT]
* @pwd: a pointer to a NULL-terminated string containing an ICE
* password [OUT]
*
* @return TRUE on success
*/
NICEAPI_EXPORT gboolean
nice_agent_get_local_credentials (
NiceAgent *agent,
......@@ -1219,22 +1143,7 @@ nice_agent_get_local_credentials (
return ret;
}
/**
* nice_agent_add_remote_candidate
* @agent: a NiceAgent
* @stream_id: the ID of the stream the candidate is for
* @component_id: the ID of the component the candidate is for
* @type: the type of the new candidate
* @addr: the new candidate's IP address
* @username: the new candidate's username (XXX: candidates don't have usernames)
* @password: the new candidate's password (XXX: candidates don't have usernames)
*
* Add a candidate our peer has informed us about to the agent's list.
*
* Note: NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute
* maximum limit for remote candidates
* @return FALSE on fatal (memory alloc) errors
**/
NICEAPI_EXPORT gboolean
nice_agent_add_remote_candidate (
NiceAgent *agent,
......@@ -1246,14 +1155,8 @@ nice_agent_add_remote_candidate (
const gchar *password)
{
/* XXX: to be deprecated */
g_static_rec_mutex_lock (&agent->mutex);
/* XXX: should we allow use of this method without an
* initial call to nice_agent_set_remote_candidates()
* with an empty set? */
gboolean ret =
priv_add_remote_candidate (agent,
stream_id,
......@@ -1275,22 +1178,7 @@ nice_agent_add_remote_candidate (
return ret;
}
/**
* nice_agent_set_remote_candidates
* @agent: a NiceAgent
* @stream_id: the ID of the stream the candidate is for
* @component_id: the ID of the component the candidate is for
* @candidates: a list of NiceCandidate items describing the candidates
*
* Sets the remote candidates for a component of a stream. Replaces
* any existing remote candidates.
*
* Note: NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute
* maximum limit for remote candidates
*
* @return number of candidates added, negative on fatal (memory
* allocs) errors
**/
NICEAPI_EXPORT int
nice_agent_set_remote_candidates (NiceAgent *agent, guint stream_id, guint component_id, const GSList *candidates)
{
......@@ -1336,12 +1224,6 @@ nice_agent_set_remote_candidates (NiceAgent *agent, guint stream_id, guint compo
}
/**
* Reads data from a ready, nonblocking socket attached to an ICE
* stream component.
*
* @return number of octets received, or negative on error
*/
static gint
_nice_agent_recv (
NiceAgent *agent,
......@@ -1411,15 +1293,7 @@ _nice_agent_recv (
return len;
}
/**
* Sends a data payload over a stream component.
*
* @pre 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
*
* @return number of bytes sent, or negative error code
*/
NICEAPI_EXPORT gint
nice_agent_send (
NiceAgent *agent,
......@@ -1467,16 +1341,6 @@ nice_agent_send (
}
/**
* nice_agent_get_local_candidates:
* @agent: A NiceAgent
*
* The caller owns the returned GSList as well as the candidates contained
* within it. To get full results, the client should wait for the
* 'candidates-gathering-done' signal.
*
* Returns: a GSList of local candidates (NiceCandidate) belonging to @agent
**/
NICEAPI_EXPORT GSList *
nice_agent_get_local_candidates (
NiceAgent *agent,
......@@ -1502,19 +1366,6 @@ nice_agent_get_local_candidates (
}
/**
* nice_agent_get_remote_candidates:
* @agent: A NiceAgent
*
* The caller owns the returned GSList but not the candidates contained within
* it.
*
* Note: the list of remote candidates can change during processing.
* The client should register for the "new-remote-candidate" signal to
* get notification of new remote candidates.
*
* Returns: a GSList of remote candidates (NiceCandidate) belonging to @agent
**/
NICEAPI_EXPORT GSList *
nice_agent_get_remote_candidates (
NiceAgent *agent,
......@@ -1538,17 +1389,7 @@ nice_agent_get_remote_candidates (
return ret;
}
/**
* nice_agent_restart
* @agent: A NiceAgent
*
* Restarts the session as defined in ICE spec (ID-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.
*
* Returns: FALSE on error
**/
gboolean
nice_agent_restart (
NiceAgent *agent)
......@@ -1813,13 +1654,6 @@ nice_agent_attach_recv (
return ret;
}
/**
* Sets the selected candidate pair for media transmission
* for given stream component. Calling this function will
* disable all further ICE processing (connection check,
* state machine updates, etc). Note that keepalives will
* continue to be sent.
*/
NICEAPI_EXPORT gboolean
nice_agent_set_selected_pair (
NiceAgent *agent,
......@@ -1879,21 +1713,6 @@ GSource* agent_timeout_add_with_context (NiceAgent *agent, guint interval,
}
/**
* nice_agent_set_selected_remote_candidate:
* @agent: a #NiceAgent
* @stream_id: the stream id
* @component_id: the component id
* @candidate: the #NiceCandidate to force
*
* Sets the selected remote candidate for media transmission
* for given stream component. Calling this function will
* disable all further ICE processing (connection check,
* state machine updates, etc). Note that keepalives will
* continue to be sent.
*
* Returns: %TRUE on success, %FALSE on failure
*/
NICEAPI_EXPORT gboolean
nice_agent_set_selected_remote_candidate (
NiceAgent *agent,
......
This diff is collapsed.
......@@ -39,18 +39,43 @@
#ifndef _CANDIDATE_H
#define _CANDIDATE_H
#include "socket.h"
/**
* SECTION:candidate
* @short_description: ICE candidate representation
*
*
*/
G_BEGIN_DECLS
#include "socket.h"
#define NICE_CANDIDATE_TYPE_PREF_HOST 120
#define NICE_CANDIDATE_TYPE_PREF_PEER_REFLEXIVE 110
#define NICE_CANDIDATE_TYPE_PREF_SERVER_REFLEXIVE 100
#define NICE_CANDIDATE_TYPE_PREF_RELAYED 60
/* Max foundation size '1*32ice-char' plus terminating NULL, ICE ID-19 */
#define NICE_CANDIDATE_MAX_FOUNDATION 32+1
/**
* NICE_CANDIDATE_MAX_FOUNDATION:
*
* The maximum size a candidate foundation can have.
*/
#define NICE_CANDIDATE_MAX_FOUNDATION 32+1
/**
* NiceCandidateType:
* @NICE_CANDIDATE_TYPE_HOST: A host candidate
* @NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE: A server reflexive candidate
* @NICE_CANDIDATE_TYPE_PEER_REFLEXIVE: A peer reflexive candidate
* @NICE_CANDIDATE_TYPE_RELAYED: A relay candidate
*
* An enum represneting the type of a candidate
*/
typedef enum
{
NICE_CANDIDATE_TYPE_HOST,
......@@ -59,11 +84,25 @@ typedef enum
NICE_CANDIDATE_TYPE_RELAYED,
} NiceCandidateType;
/**
* NiceCandidateTransport:
* @NICE_CANDIDATE_TRANSPORT_UDP: UDP transport
*
* An enum representing the type of transport to use
*/
typedef enum
{
NICE_CANDIDATE_TRANSPORT_UDP,
} NiceCandidateTransport;
/**
* NiceRelayType:
* @NICE_RELAY_TYPE_TURN_UDP: A TURN relay using UDP
* @NICE_RELAY_TYPE_TURN_TCP: A TURN relay using TCP
* @NICE_RELAY_TYPE_TURN_TLS: A TURN relay using TLS over TCP
*
* An enum representing the type of relay to use
*/
typedef enum {
NICE_RELAY_TYPE_TURN_UDP,
NICE_RELAY_TYPE_TURN_TCP,
......@@ -75,6 +114,15 @@ typedef struct _NiceCandidate NiceCandidate;
typedef struct _TurnServer TurnServer;
/**
* TurnServer:
* @server: The #NiceAddress of the TURN server
* @username: The TURN username
* @password: The TURN password
* @type: The #NiceRelayType of the server
*
* A structure to store the TURN relay settings
*/
struct _TurnServer
{
NiceAddress server; /**< TURN server address */
......@@ -83,6 +131,26 @@ struct _TurnServer
NiceRelayType type; /**< TURN type */
};
/**
* NiceCandidate:
* @type: The type of candidate
* @transport: The transport being used for the candidate
* @addr: The #NiceAddress of the candidate
* @base_addr: The #NiceAddress of the base address used by the candidate
* @priority: The priority of the candidate
* @stream_id: The ID of the stream to which belongs the candidate
* @component_id: The ID of the component to which belongs the candidate
* @foundation: The foundation of the candidate
* @username: The candidate-specific username to use (overrides the one set
* by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
* @password: The candidate-specific password to use (overrides the one set
* by nice_agent_set_local_credentials() or nice_agent_set_remote_credentials())
* @turn: The #TurnServer settings if the candidate is
* of type %NICE_CANDIDATE_TYPE_RELAYED
* @sockptr: The underlying socket
*
* A structure to represent an ICE candidate
*/
struct _NiceCandidate
{
NiceCandidateType type;
......@@ -93,19 +161,44 @@ struct _NiceCandidate
guint stream_id;
guint component_id;
gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
NiceSocket *sockptr;
gchar *username; /* pointer to a NULL-terminated username string */
gchar *password; /* pointer to a NULL-terminated password string */
TurnServer *turn;
NiceSocket *sockptr;
};
/**
* nice_candidate_new:
* @type: The #NiceCandidateType of the candidate to create
*
* Creates a new candidate. Must be freed with nice_candidate_free()
*
* Returns: A new #NiceCandidate
*/
NiceCandidate *
nice_candidate_new (NiceCandidateType type);
/**
* nice_candidate_free:
* @candidate: The candidate to free
*
* Frees a #NiceCandidate
*/
void
nice_candidate_free (NiceCandidate *candidate);
/**
* nice_candidate_copy:
* @candidate: The candidate to copy
*
* Makes a copy of a #NiceCandidate
*
* Returns: A new #NiceCandidate, a copy of @candidate
*/
NiceCandidate *
nice_candidate_copy (const NiceCandidate *candidate);
gfloat
nice_candidate_jingle_priority (NiceCandidate *candidate);
......@@ -121,8 +214,6 @@ nice_candidate_ice_priority (const NiceCandidate *candidate);
guint64
nice_candidate_pair_priority (guint32 o_prio, guint32 a_prio);
NiceCandidate *
nice_candidate_copy (const NiceCandidate *candidate);
G_END_DECLS
......
......@@ -36,11 +36,41 @@
#ifndef _DEBUG_H
#define _DEBUG_H
/**
* SECTION:debug
* @short_description: Debug messages utility functions
*
*
*/
#include <glib.h>
/**
* nice_debug_init:
*
* Initialize the debugging system. Uses the NICE_DEBUG environment variable
* to set the appropriate debugging flags
*/
void nice_debug_init (void);
/**
* nice_debug_enable:
* @with_stun: Also enable stun debugging messages
*
* Enables libnice debug output to the terminal
*/
void nice_debug_enable (gboolean with_stun);
/**
* nice_debug_disable:
* @with_stun: Also disable stun debugging messages
*
* Disables libnice debug output to the terminal
*/
void nice_debug_disable (gboolean with_stun);
void nice_debug (const char *fmt, ...);
#endif /* _DEBUG_H */
......
#!/bin/sh
set -e
gtkdocize || exit 1
autoreconf -i
run_configure=true
......
......@@ -15,6 +15,10 @@ AC_CONFIG_FILES([
nice/nice.pc
random/Makefile
gst/Makefile
docs/Makefile
docs/reference/Makefile
docs/reference/libnice/Makefile
docs/reference/libstun/Makefile
])
# Set the libtool C/A/R version info
......@@ -96,6 +100,9 @@ AS_IF([test "${enable_coverage}" != "no"], [
])
AC_SUBST(CCACHE_DISABLE)
# check for gtk-doc
GTK_DOC_CHECK(1.9)
AC_CONFIG_MACRO_DIR(m4)
AC_OUTPUT
SUBDIRS = reference
EXTRA_DIST = design.txt
SUBDIRS = libnice libstun
## Process this file with automake to produce Makefile.in
# We require automake 1.6 at least.
AUTOMAKE_OPTIONS = 1.6
# The name of the module, e.g. 'glib'.
DOC_MODULE=libnice
# The top-level SGML file. You can change this if you want to.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code. Relative to $(srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=$(top_srcdir)/agent
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS=--rebuild-types
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(DOC_SOURCE_DIR)/agent.h $(DOC_SOURCE_DIR)/address.h $(DOC_SOURCE_DIR)/debug.h $(DOC_SOURCE_DIR)/candidate.h
CFILE_GLOB=
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= conncheck.h discovery.h stream.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files=
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
AM_CFLAGS = $(ERROR_CFLAGS) \
$(GLIB_CFLAGS) \
-I $(top_srcdir) \
-I $(top_srcdir)/random \
-I $(top_srcdir)/socket \
-I $(top_srcdir)/stun
GTKDOC_LIBS= $(top_builddir)/agent/libagent.la $(GLIB_LIBS)
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST +=
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
#DISTCLEANFILES +=
# Comment this out if you want your docs-status tested during 'make check'
TESTS = $(GTKDOC_CHECK)
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>libnice Reference Manual</title>
<releaseinfo>
for libnice 0.0.1
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://nice.freedesktop.org/libnice/index.html">http://nice.freedesktop.org/libnice/</ulink>.
</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"/>
</chapter>
</book>
<SECTION>
<FILE>agent</FILE>
NICE_AGENT_MAX_REMOTE_CANDIDATES
NiceComponentState
NiceComponentType
NiceCompatibility
NiceAgentRecvFunc
<TITLE>NiceAgent</TITLE>
NiceAgent
nice_agent_new
nice_agent_add_local_address
nice_agent_add_stream
nice_agent_remove_stream
nice_agent_set_relay_info
nice_agent_gather_candidates
nice_agent_set_remote_credentials
nice_agent_get_local_credentials
nice_agent_add_remote_candidate
nice_agent_set_remote_candidates
nice_agent_send
nice_agent_get_local_candidates
nice_agent_get_remote_candidates
nice_agent_restart
nice_agent_attach_recv
nice_agent_set_selected_pair
nice_agent_set_selected_remote_candidate
<SUBSECTION Standard>
NICE_AGENT
NICE_IS_AGENT
NICE_TYPE_AGENT
nice_agent_get_type
NICE_AGENT_CLASS
NICE_IS_AGENT_CLASS
NICE_AGENT_GET_CLASS
<SUBSECTION Private>
</SECTION>
<SECTION>
<FILE>debug</FILE>
<TITLE>Debug messages</TITLE>
nice_debug_enable
nice_debug_disable
<SUBSECTION Private>
nice_debug_init
nice_debug
</SECTION>
<SECTION>
<FILE>candidate</FILE>
<TITLE>NiceCandidate</TITLE>
NICE_CANDIDATE_MAX_FOUNDATION
NiceCandidateType
NiceCandidateTransport
NiceRelayType
NiceCandidate
TurnServer
nice_candidate_new
nice_candidate_free
nice_candidate_copy
<SUBSECTION Private>
NICE_CANDIDATE_TYPE_PREF_HOST
NICE_CANDIDATE_TYPE_PREF_PEER_REFLEXIVE
NICE_CANDIDATE_TYPE_PREF_SERVER_REFLEXIVE
NICE_CANDIDATE_TYPE_PREF_RELAYED
nice_candidate_jingle_priority
nice_candidate_msn_priority
nice_candidate_ice_priority_full
nice_candidate_ice_priority
nice_candidate_pair_priority
</SECTION>
<SECTION>
<FILE>address</FILE>
<TITLE>NiceAddress</TITLE>
NICE_ADDRESS_STRING_LEN
NiceAddress
nice_address_new
nice_address_free
nice_address_dup
nice_address_set_ipv4
nice_address_set_ipv6
nice_address_set_port
nice_address_get_port
nice_address_set_from_string
nice_address_set_from_sockaddr
nice_address_copy_to_sockaddr
nice_address_equal