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

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,
......
......@@ -47,6 +47,12 @@ typedef struct _NiceAgent NiceAgent;
#include "candidate.h"
#include "debug.h"
/**
* SECTION:agent
* @short_description: ICE agent API implementation
*
*
*/
G_BEGIN_DECLS
......@@ -72,26 +78,67 @@ G_BEGIN_DECLS
(G_TYPE_INSTANCE_GET_CLASS ((obj), \
NICE_TYPE_AGENT, NiceAgentClass))
/**
typedef struct _NiceAgentClass NiceAgentClass;
struct _NiceAgentClass
{
GObjectClass parent_class;
};
GType nice_agent_get_type (void);
/**
* NICE_AGENT_MAX_REMOTE_CANDIDATES:
*
* A hard limit for number for remote candidates. This
* limit is enforced to protect against malevolent remote
* limit is enforced to protect against malevolent remote
* clients.
*/
#define NICE_AGENT_MAX_REMOTE_CANDIDATES 25
/**
* NiceComponentState:
* @NICE_COMPONENT_STATE_DISCONNECTED: No activity scheduled
* @NICE_COMPONENT_STATE_GATHERING: Gathering local candidates
* @NICE_COMPONENT_STATE_CONNECTING: Establishing connectivity
* @NICE_COMPONENT_STATE_CONNECTED: At least one working candidate pair
* @NICE_COMPONENT_STATE_READY: ICE concluded, candidate pair selection
* is now final
* @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
* but connectivity was not established
*
* An enum representing the state of a component.
* See #NiceAgent::component-state-changed
*/
typedef enum
{
NICE_COMPONENT_STATE_DISCONNECTED, /* no activity scheduled */
NICE_COMPONENT_STATE_GATHERING, /* gathering local candidates */
NICE_COMPONENT_STATE_CONNECTING, /* establishing connectivity */
NICE_COMPONENT_STATE_CONNECTED, /* at least one working candidate pair */
NICE_COMPONENT_STATE_READY, /* ICE concluded, candidate pair
selection is now final */
NICE_COMPONENT_STATE_FAILED, /* connectivity checks have been completed,
but connectivity was not established */
NICE_COMPONENT_STATE_DISCONNECTED,
NICE_COMPONENT_STATE_GATHERING,
NICE_COMPONENT_STATE_CONNECTING,
NICE_COMPONENT_STATE_CONNECTED,
NICE_COMPONENT_STATE_READY,
NICE_COMPONENT_STATE_FAILED,
NICE_COMPONENT_STATE_LAST
} NiceComponentState;
/**
* NiceComponentType:
* @NICE_COMPONENT_TYPE_RTP: RTP Component type
* @NICE_COMPONENT_TYPE_RTCP: RTCP Component type
*
* Convenience enum representing the type of a component for use as the
* component_id for RTP/RTCP usages.
<example>
<title>Example of use.</title>
<programlisting>
nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);
</programlisting>
</example>
*/
typedef enum
{
NICE_COMPONENT_TYPE_RTP = 1,
......@@ -99,6 +146,15 @@ typedef enum
} NiceComponentType;
/**
* NiceCompatibility:
* @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
* @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
* @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
*
* An enum to specify which compatible specifications the #NiceAgent should use.
* Use with nice_agent_new()
*/
typedef enum
{
NICE_COMPATIBILITY_DRAFT19 = 0,
......@@ -107,39 +163,93 @@ typedef enum
NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_MSN
} NiceCompatibility;
/**
* NiceAgentRecvFunc:
* @agent: The #NiceAgent Object
* @stream_id: The id of the stream
* @component_id: The id of the component of the stream
* which received the data
* @len: The length of the data
* @buf: The buffer containing the data received
* @user_data: The user data set in nice_agent_attach_recv()
*
* Callback function when data is received on a component
*
*/
typedef void (*NiceAgentRecvFunc) (
NiceAgent *agent, guint stream_id, guint component_id, guint len,
gchar *buf, gpointer user_data);
typedef struct _NiceAgentClass NiceAgentClass;
struct _NiceAgentClass
{
GObjectClass parent_class;
};
GType nice_agent_get_type (void);
/**
* nice_agent_new:
* @ctx: The Glib Mainloop Context to use for timers
* @compat: The compatibility mode of the agent
*
* Create a new #NiceAgent.
*
* Returns: the new agent GObject
*/
NiceAgent *
nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
/**
* nice_agent_add_local_address:
* @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
*
* Add a local address from which to derive local host candidates
*
* Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
*/
gboolean
nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);
/**
* nice_agent_add_stream:
* @agent: The #NiceAgent Object
* @n_components: The number of components to add to the stream
*
* Adds a data stream to @agent containing @n_components components.
*
* Returns: The ID of the new stream, 0 on failure
**/
guint
nice_agent_add_stream (
NiceAgent *agent,
guint n_components);
/**
* nice_agent_remove_stream:
* @agent: The #NiceAgent Object
* @stream_id: The ID of the stream to remove
*
* Remove and free a previously created data stream from @agent
*
**/
void
nice_agent_remove_stream (
NiceAgent *agent,
guint stream_id);
/**
* nice_agent_set_relay_info:
* @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
*
* Sets the settings for using a relay server during the candidate discovery.
*
* Returns: %TRUE if the TURN settings were accepted.
* %FALSE if the address was invalid.
*/
gboolean nice_agent_set_relay_info(
NiceAgent *agent,
guint stream_id,
......@@ -150,23 +260,96 @@ gboolean nice_agent_set_relay_info(
const gchar *password,
NiceRelayType type);
/**
* nice_agent_gather_candidates:
* @agent: The #NiceAgent Object
* @stream_id: The id of the stream to start
*
* Start the candidate gathering process.
* Once done, #NiceAgent::candidate-gathering-done is called for the stream
*
<note>
<para>
Local addresses must be previously set with nice_agent_add_local_address()
</para>
</note>
*/
void
nice_agent_gather_candidates (
NiceAgent *agent,
guint stream_id);
/**
* nice_agent_set_remote_credentials:
* @agent: The #NiceAgent Object
* @stream_id: The ID of the stream
* @ufrag: NULL-terminated string containing an ICE username fragment
* (length must be between 22 and 256 chars)
* @pwd: NULL-terminated string containing an ICE password
* (length must be between 4 and 256 chars)
*
* Sets the remote credentials for stream @stream_id.
*
<note>
<para>
Stream credentials do not override per-candidate credentials if set
</para>
</note>
*
* Returns: %TRUE on success, %FALSE on error.
*/
gboolean
nice_agent_set_remote_credentials (
NiceAgent *agent,
guint stream_id,
const gchar *ufrag, const gchar *pwd);
/**
* nice_agent_get_local_credentials:
* @agent: The #NiceAgent Object
* @stream_id: The ID of the stream
* @ufrag: a pointer to a NULL-terminated string containing
* an ICE username fragment [OUT].
* This string must be freed with g_free()
* @pwd: a pointer to a NULL-terminated string containing an ICE
* password [OUT]
* This string must be freed with g_free()
*
* Gets the local credentials for stream @stream_id.
*
* Returns: %TRUE on success, %FALSE on error.
*/
gboolean
nice_agent_get_local_credentials (
NiceAgent *agent,
guint stream_id,
const gchar **ufrag, const gchar **pwd);
/**
* nice_agent_add_remote_candidate:
* @agent: The #NiceAgent Object
* @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
* (optional - overrides the value set in nice_agent_set_remote_credentials())
* @password: The new candidate's password
* (optional - overrides the value set in nice_agent_set_remote_credentials())
*
* Adds a new remote candidate to the agent
*
<note>
<para>
NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
</para>
</note>
*
* Returns: %TRUE on success, %FALSE on fatal (memory alloc) errors
**/
gboolean
nice_agent_add_remote_candidate (
NiceAgent *agent,
......@@ -177,6 +360,24 @@ nice_agent_add_remote_candidate (
const gchar *username,
const gchar *password);
/**
* nice_agent_set_remote_candidates:
* @agent: The #NiceAgent Object
* @stream_id: The ID of the stream the candidates are for
* @component_id: The ID of the component the candidates are for
* @candidates: a #GList of #NiceCandidate items describing each candidate to add
*
* Sets the remote candidates for a component of a stream.
* Replaces any existing remote candidates.
*
<note>
<para>
NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
</para>
</note>
*
* Returns: The number of candidates added, negative on fatal (memory allocs) errors