Commit 79a555bb authored by Youness Alaoui's avatar Youness Alaoui

Update the docs to include everything

parent d0cec237
......@@ -38,6 +38,16 @@
#ifndef _ADDRESS_H
#define _ADDRESS_H
/**
* SECTION:address
* @short_description: IP address convenience library
* @stability: Stable
*
* The #NiceAddress structure will allow you to easily set/get and modify an IPv4
* or IPv6 address in order to communicate with the #NiceAgent.
*/
#include <glib.h>
#ifdef G_OS_WIN32
......@@ -52,11 +62,15 @@
G_BEGIN_DECLS
#define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
typedef struct _NiceAddress NiceAddress;
/* note: clients need to know the storage size, so needs to be public */
/**
* NiceAddress:
* @addr: Generic sockaddr address
* @ip4: IPv4 sockaddr address
* @ip6: IPv6 sockaddr address
*
* The #NiceAddress structure that represents an IPv4 or IPv6 address.
*/
struct _NiceAddress
{
union
......@@ -68,45 +82,193 @@ struct _NiceAddress
};
/**
* NICE_ADDRESS_STRING_LEN:
*
* 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
*/
#define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
typedef struct _NiceAddress NiceAddress;
/**
* nice_address_init:
* @addr: The #NiceAddress to init
*
* Initialize a #NiceAddress into an undefined address
*/
void
nice_address_init (NiceAddress *addr);
/**
* nice_address_new:
*
* Create a new #NiceAddress with undefined address
* You must free it with nice_address_free()
*
* Returns: The new #NiceAddress
*/
NiceAddress *
nice_address_new (void);
/**
* nice_address_free:
* @addr: The #NiceAddress to free
*
* Frees a #NiceAddress created with nice_address_new() or nice_address_dup()
*/
void
nice_address_free (NiceAddress *addr);
/**
* nice_address_dup:
* @addr: The #NiceAddress to dup
*
* Creates a new #NiceAddress with the same address as @addr
*
* Returns: The new #NiceAddress
*/
NiceAddress *
nice_address_dup (const NiceAddress *addr);
/**
* nice_address_set_ipv4:
* @addr: The #NiceAddress to modify
* @addr_ipv4: The IPv4 address
*
* Set @addr to an IPv4 address using the data from @addr_ipv4
*
<note>
<para>
This function will reset the port to 0, so make sure you call it before
nice_address_set_port()
</para>
</note>
*/
void
nice_address_set_ipv4 (NiceAddress *addr, guint32 addr_ipv4);
/**
* nice_address_set_ipv6:
* @addr: The #NiceAddress to modify
* @addr_ipv6: The IPv6 address
*
* Set @addr to an IPv6 address using the data from @addr_ipv6
*
<note>
<para>
This function will reset the port to 0, so make sure you call it before
nice_address_set_port()
</para>
</note>
*/
void
nice_address_set_ipv6 (NiceAddress *addr, const guchar *addr_ipv6);
/**
* nice_address_set_port:
* @addr: The #NiceAddress to modify
* @port: The port to set
*
* Set the port of @addr to @port
*/
void
nice_address_set_port (NiceAddress *addr, guint port);
/**
* nice_address_get_port:
* @addr: The #NiceAddress to query
*
* Retreive the port of @addr
*
* Returns: The port of @addr
*/
guint
nice_address_get_port (const NiceAddress *addr);
/**
* nice_address_set_from_string:
* @addr: The #NiceAddress to modify
* @str: The string to set
*
* Sets an IPv4 or IPv6 address from the string @str
*
* Returns: %TRUE if success, %FALSE on error
*/
gboolean
nice_address_set_from_string (NiceAddress *addr, const gchar *str);
/**
* nice_address_set_from_sockaddr:
* @addr: The #NiceAddress to modify
* @sin: The sockaddr to set
*
* Sets an IPv4 or IPv6 address from the sockaddr structure @sin
*
*/
void
nice_address_set_from_sockaddr (NiceAddress *addr, const struct sockaddr *sin);
/**
* nice_address_copy_to_sockaddr:
* @addr: The #NiceAddress to query
* @sin: The sockaddr to fill
*
* Fills the sockaddr structure @sin with the address contained in @addr
*
*/
void
nice_address_copy_to_sockaddr (const NiceAddress *addr, struct sockaddr *sin);
/**
* nice_address_equal:
* @a: First #NiceAddress to compare
* @b: Second #NiceAddress to compare
*
* Compares two #NiceAddress structures to see if they contain the same address
*
* Returns: %TRUE if @a and @b are the same address, %FALSE if they are different
*/
gboolean
nice_address_equal (const NiceAddress *a, const NiceAddress *b);
/**
* nice_address_to_string:
* @addr: The #NiceAddress to query
* @dst: The string to fill
*
* Transforms the address @addr into a human readable string
*
*/
void
nice_address_to_string (const NiceAddress *addr, gchar *dst);
/**
* nice_address_is_private:
* @addr: The #NiceAddress to query
*
* Verifies if the address in @addr is a private address or not
*
* Returns: %TRUE if @addr is a private address, %FALSE otherwise
*/
gboolean
nice_address_is_private (const NiceAddress *addr);
/**
* nice_address_is_valid:
* @addr: The #NiceAddress to query
*
* Validate whether the #NiceAddress @addr is a valid IPv4 or IPv6 address
*
* Returns: %TRUE if @addr is valid, %FALSE otherwise
*/
G_GNUC_WARN_UNUSED_RESULT
gboolean
nice_address_is_valid (const NiceAddress *addr);
......
......@@ -193,7 +193,12 @@ nice_agent_class_init (NiceAgentClass *klass)
gobject_class->dispose = nice_agent_dispose;
/* install properties */
/**
* NiceAgent:main-context:
*
* A GLib main context is needed for all timeouts used by libnice.
* This is a property being set by the nice_agent_new() call.
*/
g_object_class_install_property (gobject_class, PROP_MAIN_CONTEXT,
g_param_spec_pointer (
"main-context",
......@@ -201,6 +206,13 @@ nice_agent_class_init (NiceAgentClass *klass)
"The GMainContext to use for timeouts",
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* NiceAgent:compatibility:
*
* The Nice agent can work in various compatibility modes depending on
* what the application/peer needs.
* <para> See also: #NiceCompatibility</para>
*/
g_object_class_install_property (gobject_class, PROP_COMPATIBILITY,
g_param_spec_uint (
"compatibility",
......@@ -264,7 +276,14 @@ nice_agent_class_init (NiceAgentClass *klass)
/* install signals */
/* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, guint state, gpointer self) */
/**
* NiceAgent::component-state-changed
* @stream_id: The ID of the stream
* @component_id: The ID of the component
* @state: The #NiceComponentState of the component
*
* This signal is fired whenever a component's state changes
*/
signals[SIGNAL_COMPONENT_STATE_CHANGED] =
g_signal_new (
"component-state-changed",
......@@ -279,7 +298,13 @@ nice_agent_class_init (NiceAgentClass *klass)
G_TYPE_UINT, G_TYPE_UINT, G_TYPE_UINT,
G_TYPE_INVALID);
/* signature: void cb(NiceAgent *agent, gpointer self) */
/**
* NiceAgent::candidate-gathering-done:
* @stream_id: The ID of the stream
*
* This signal is fired whenever a stream has finished gathering its
* candidates after a call to nice_agent_gather_candidates()
*/
signals[SIGNAL_CANDIDATE_GATHERING_DONE] =
g_signal_new (
"candidate-gathering-done",
......@@ -293,8 +318,16 @@ nice_agent_class_init (NiceAgentClass *klass)
1,
G_TYPE_UINT, G_TYPE_INVALID);
/* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id,
gchar *lfoundation, gchar* rfoundation, gpointer self) */
/**
* NiceAgent::new-selected-pair
* @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
*
* This signal is fired once a candidate pair is selected for data transfer for
* a stream's component
*/
signals[SIGNAL_NEW_SELECTED_PAIR] =
g_signal_new (
"new-selected-pair",
......@@ -309,7 +342,15 @@ nice_agent_class_init (NiceAgentClass *klass)
G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING, G_TYPE_STRING,
G_TYPE_INVALID);
/* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, gchar *foundation) */
/**
* NiceAgent::new-candidate
* @stream_id: The ID of the stream
* @component_id: The ID of the component
* @foundation: The foundation of the new candidate
*
* This signal is fired when the agent discovers a new candidate
* <para> See also: #NiceAgent::candidates-gathering-done </para>
*/
signals[SIGNAL_NEW_CANDIDATE] =
g_signal_new (
"new-candidate",
......@@ -324,7 +365,16 @@ nice_agent_class_init (NiceAgentClass *klass)
G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING,
G_TYPE_INVALID);
/* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, gchar *foundation) */
/**
* NiceAgent::new-remote-candidate
* @stream_id: The ID of the stream
* @component_id: The ID of the component
* @foundation: The foundation of the new candidate
*
* This signal is fired when the agent discovers a new remote candidate.
* This can happen with peer reflexive candidates.
* <para> See also: #NiceAgent::candidates-gathering-done </para>
*/
signals[SIGNAL_NEW_REMOTE_CANDIDATE] =
g_signal_new (
"new-remote-candidate",
......@@ -339,7 +389,13 @@ nice_agent_class_init (NiceAgentClass *klass)
G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING,
G_TYPE_INVALID);
/* signature: void cb(NiceAgent *agent, guint stream_id, gpointer self) */
/**
* NiceAgent::initial-binding-request-received
* @stream_id: The ID of the stream
*
* This signal is fired when we received our first binding request from
* the peer.
*/
signals[SIGNAL_INITIAL_BINDING_REQUEST_RECEIVED] =
g_signal_new (
"initial-binding-request-received",
......
......@@ -39,20 +39,84 @@
#ifndef _AGENT_H
#define _AGENT_H
/**
* SECTION:agent
* @short_description: ICE agent API implementation
* @see_also: #NiceCandidate
* @see_also: #NiceAddress
* @include: agent.h
* @stability: Stable
*
* The #NiceAgent is your main object when using libnice.
* It is the agent that will take care of everything relating to ICE.
* It will take care of discovering your local candidates and do
* connectivity checks to create a stream of data between you and your peer.
*
<example>
<title>Simple example on how to use libnice</title>
<programlisting>
NiceAddress base_addr;
guint stream_id;
gchar buffer[] = "hello world!";
GSList *lcands = NULL;
// 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);
g_signal_connect (G_OBJECT (lagent), "component-state-changed",
G_CALLBACK (cb_component_state_changed), NULL);
g_signal_connect (G_OBJECT (lagent), "new-selected-pair",
G_CALLBACK (cb_new_selected_pair), NULL);
// Create a new stream with one component and start gathering candidates
stream_id = nice_agent_add_stream (agent, 1);
nice_agent_gather_candidates (agent, stream_id);
// Attach to the component to receive the data
nice_agent_attach_recv (agent, stream_id, 1, NULL,
cb_nice_recv, NULL);
// ... Wait until the signal candidate-gathering-done is fired ...
lcands = nice_agent_get_local_candidates(agent, stream_id, 1);
// ... Send local candidates to the peer and set the peer's remote candidates
nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
// ... Wait until the signal new-selected-pair is fired ...
// Send our message!
nice_agent_send (lagent, ls_id, 1, sizeof(buffer), buffer);
// Anything received will be received through the cb_nice_recv callback
// Destroy the object
g_object_unref(agent);
</programlisting>
</example>
*/
#include <glib-object.h>
/**
* NiceAgent:
*
* The #NiceAgent is the main GObject of the libnice library and represents
* the ICE agent.
*/
typedef struct _NiceAgent NiceAgent;
#include "address.h"
#include "candidate.h"
#include "debug.h"
/**
* SECTION:agent
* @short_description: ICE agent API implementation
*
*
*/
G_BEGIN_DECLS
......@@ -78,7 +142,6 @@ G_BEGIN_DECLS
(G_TYPE_INSTANCE_GET_CLASS ((obj), \
NICE_TYPE_AGENT, NiceAgentClass))
typedef struct _NiceAgentClass NiceAgentClass;
struct _NiceAgentClass
......@@ -109,6 +172,7 @@ GType nice_agent_get_type (void);
* is now final
* @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
* but connectivity was not established
* @NICE_COMPONENT_STATE_LAST: Dummy state
*
* An enum representing the state of a component.
* See #NiceAgent::component-state-changed
......@@ -151,6 +215,7 @@ typedef enum
* @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
* @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
*
* An enum to specify which compatible specifications the #NiceAgent should use.
* Use with nice_agent_new()
......@@ -187,8 +252,9 @@ typedef void (*NiceAgentRecvFunc) (
* @compat: The compatibility mode of the agent
*
* Create a new #NiceAgent.
* The returned object must be freed with g_object_unref()
*
* Returns: the new agent GObject
* Returns: The new agent GObject
*/
NiceAgent *
nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
......@@ -344,7 +410,8 @@ nice_agent_get_local_credentials (
*
<note>
<para>
NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
for remote candidates
</para>
</note>
*
......@@ -372,11 +439,13 @@ nice_agent_add_remote_candidate (
*
<note>
<para>
NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
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
* Returns: The number of candidates added,
* negative on fatal (memory allocs) errors
**/
int
nice_agent_set_remote_candidates (
......@@ -419,7 +488,8 @@ nice_agent_send (
* @stream_id: The ID of the stream
* @component_id: The ID of the component
*
* Retreive from the agent the list of all local candidates for a stream's component
* Retreive from the agent the list of all local candidates
* for a stream's component
*
<note>
<para>
......@@ -450,12 +520,13 @@ nice_agent_get_local_candidates (
*
<note>
<para>
The caller owns the returned GSList but not the candidates contained within it.
The caller owns the returned GSList but not the candidates
contained within it.
</para>
<para>
The list of remote candidates can change during processing.
The client should register for the #NiceAgent::new-remote-candidate signal to
get notification of new remote candidates.
The client should register for the #NiceAgent::new-remote-candidate signal
to get notified of new remote candidates.
</para>
</note>
*
......@@ -490,11 +561,12 @@ nice_agent_restart (
* @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 component
* @func: The callback function to be called when data is received on
* the stream's component
* @data: user data associated with the callback
*
* Attaches the stream's component's sockets to the Glib Mainloop Context in order
* to be notified whenever data becomes available for a component.
* Attaches the stream's component's sockets to the Glib Mainloop Context in
* order to be notified whenever data becomes available for a component.
*
* Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
*/
......@@ -543,8 +615,8 @@ nice_agent_set_selected_pair (
* 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
* 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
......
......@@ -43,8 +43,13 @@
/**
* SECTION:candidate
* @short_description: ICE candidate representation
* @see_also: #NiceAddress
* @stability: Stable
*
*
* 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/
*/
......@@ -206,7 +211,8 @@ gfloat
nice_candidate_msn_priority (NiceCandidate *candidate);
guint32
nice_candidate_ice_priority_full (guint type_pref, guint local_pref, guint component_id);
nice_candidate_ice_priority_full (guint type_pref, guint local_pref,
guint component_id);
guint32
nice_candidate_ice_priority (const NiceCandidate *candidate);
......
......@@ -40,8 +40,19 @@
/**
* SECTION:debug
* @short_description: Debug messages utility functions
* @stability: More flags are to come and a better API to
* enable/disable each flag should be added. Unstable
*
*
* 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 flags can be "nice", "stun",
* or "all" to enable all debug messages.
*/
......
......@@ -38,7 +38,7 @@ FIXXREF_OPTIONS=
# 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=
CFILE_GLOB=$(DOC_SOURCE_DIR)/agent.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
......
......@@ -33,6 +33,7 @@ NICE_AGENT_CLASS
NICE_IS_AGENT_CLASS
NICE_AGENT_GET_CLASS
<SUBSECTION Private>
NiceAgentClass
</SECTION>
<SECTION>
......@@ -75,6 +76,7 @@ nice_candidate_pair_priority
<TITLE>NiceAddress</TITLE>
NICE_ADDRESS_STRING_LEN
NiceAddress
nice_address_init
nice_address_new
nice_address_free
nice_address_dup
......@@ -90,3 +92,53 @@ nice_address_to_string
nice_address_is_private
nice_address_is_valid
</SECTION>
<SECTION>
<FILE>component</FILE>
<SUBSECTION Private>
Component
CandidatePair
IncomingCheck
component_new
component_free
component_find_socket_by_fd
component_find_pair
component_restart
component_update_selected_pair
component_find_remote_candidate
component_set_selected_remote_candidate
</SECTION>
<SECTION>
<FILE>agent-priv</FILE>
<SUBSECTION Private>
NICE_AGENT_TIMER_TA_DEFAULT
NICE_AGENT_TIMER_TR_DEFAULT
NICE_AGENT_TIMER_TR_MIN
NICE_AGENT_MAX_CONNECTIVITY_CHECKS_DEFAULT
MAX_STUN_DATAGRAM_PAYLOAD
NiceAgent
agent_find_component
agent_find_stream
agent_gathering_done
agent_signal_gathering_done
agent_signal_new_selected_pair
agent_signal_component_state_change
agent_signal_new_candidate
agent_signal_new_remote_candidate
agent_signal_initial_binding_request_received
agent_candidate_pair_priority
agent_timeout_add_with_context
priv_attach_stream_component_socket
</SECTION>
<SECTION>
<FILE>agent-signals-marshal</FILE>
<SUBSECTION Private>
agent_marshal_VOID__UINT_UINT_UINT
agent_marshal_VOID__UINT_UINT_STRING_STRING
agent_marshal_VOID__UINT_UINT_STRING
agent_marshal_VOID__UINT
</SECTION>
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