Commit a35bc947 authored by Philip Withnall's avatar Philip Withnall Committed by Olivier Crête

agent: Fix badly formatted gtk-doc comments

parent 0388646b
...@@ -43,8 +43,7 @@ ...@@ -43,8 +43,7 @@
/** /**
* SECTION:agent * SECTION:agent
* @short_description: ICE agent API implementation * @short_description: ICE agent API implementation
* @see_also: #NiceCandidate * @see_also: #NiceCandidate, #NiceAddress
* @see_also: #NiceAddress
* @include: agent.h * @include: agent.h
* @stability: Stable * @stability: Stable
* *
...@@ -69,49 +68,49 @@ ...@@ -69,49 +68,49 @@
* receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed
* to be used in a blocking loop in a separate thread. * to be used in a blocking loop in a separate thread.
* *
<example> * <example>
<title>Simple example on how to use libnice</title> * <title>Simple example on how to use libnice</title>
<programlisting> * <programlisting>
guint stream_id; * guint stream_id;
gchar buffer[] = "hello world!"; * gchar buffer[] = "hello world!";
GSList *lcands = NULL; * GSList *lcands = NULL;
*
// Create a nice agent * // Create a nice agent
NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245); * NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
*
// Connect the signals * // Connect the signals
g_signal_connect (G_OBJECT (agent), "candidate-gathering-done", * g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
G_CALLBACK (cb_candidate_gathering_done), NULL); * G_CALLBACK (cb_candidate_gathering_done), NULL);
g_signal_connect (G_OBJECT (agent), "component-state-changed", * g_signal_connect (G_OBJECT (agent), "component-state-changed",
G_CALLBACK (cb_component_state_changed), NULL); * G_CALLBACK (cb_component_state_changed), NULL);
g_signal_connect (G_OBJECT (agent), "new-selected-pair", * g_signal_connect (G_OBJECT (agent), "new-selected-pair",
G_CALLBACK (cb_new_selected_pair), NULL); * G_CALLBACK (cb_new_selected_pair), NULL);
*
// Create a new stream with one component and start gathering candidates * // Create a new stream with one component and start gathering candidates
stream_id = nice_agent_add_stream (agent, 1); * stream_id = nice_agent_add_stream (agent, 1);
nice_agent_gather_candidates (agent, stream_id); * nice_agent_gather_candidates (agent, stream_id);
*
// Attach to the component to receive the data * // Attach to the component to receive the data
nice_agent_attach_recv (agent, stream_id, 1, NULL, * nice_agent_attach_recv (agent, stream_id, 1, NULL,
cb_nice_recv, NULL); * cb_nice_recv, NULL);
*
// ... Wait until the signal candidate-gathering-done is fired ... * // ... Wait until the signal candidate-gathering-done is fired ...
lcands = nice_agent_get_local_candidates(agent, stream_id, 1); * lcands = nice_agent_get_local_candidates(agent, stream_id, 1);
*
// ... Send local candidates to the peer and set the peer's remote candidates * // ... Send local candidates to the peer and set the peer's remote candidates
nice_agent_set_remote_candidates (agent, stream_id, 1, rcands); * nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
*
// ... Wait until the signal new-selected-pair is fired ... * // ... Wait until the signal new-selected-pair is fired ...
// Send our message! * // Send our message!
nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer); * nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);
*
// Anything received will be received through the cb_nice_recv callback * // Anything received will be received through the cb_nice_recv callback
*
// Destroy the object * // Destroy the object
g_object_unref(agent); * g_object_unref(agent);
*
</programlisting> * </programlisting>
</example> * </example>
* *
* Refer to the examples in the examples/ subdirectory of the libnice source for * Refer to the examples in the examples/ subdirectory of the libnice source for
* more complete examples. * more complete examples.
......
...@@ -145,10 +145,10 @@ struct _TurnServer ...@@ -145,10 +145,10 @@ struct _TurnServer
{ {
gint ref_count; gint ref_count;
NiceAddress server; /**< TURN server address */ NiceAddress server;
gchar *username; /**< TURN username */ gchar *username;
gchar *password; /**< TURN password */ gchar *password;
NiceRelayType type; /**< TURN type */ NiceRelayType type;
}; };
/** /**
......
...@@ -82,7 +82,7 @@ struct _CandidatePair ...@@ -82,7 +82,7 @@ struct _CandidatePair
{ {
NiceCandidate *local; NiceCandidate *local;
NiceCandidate *remote; NiceCandidate *remote;
guint64 priority; /**< candidate pair priority */ guint64 priority; /* candidate pair priority */
CandidatePairKeepalive keepalive; CandidatePairKeepalive keepalive;
}; };
...@@ -138,48 +138,48 @@ io_callback_data_free (IOCallbackData *data); ...@@ -138,48 +138,48 @@ io_callback_data_free (IOCallbackData *data);
struct _Component struct _Component
{ {
NiceComponentType type; NiceComponentType type;
guint id; /**< component id */ guint id; /* component id */
NiceComponentState state; NiceComponentState state;
GSList *local_candidates; /**< list of Candidate objs */ GSList *local_candidates; /* list of Candidate objs */
GSList *remote_candidates; /**< list of Candidate objs */ GSList *remote_candidates; /* list of Candidate objs */
GSList *socket_sources; /**< list of SocketSource objs; must only grow monotonically */ GSList *socket_sources; /* list of SocketSource objs; must only grow monotonically */
guint socket_sources_age; /**< incremented when socket_sources changes */ guint socket_sources_age; /* incremented when socket_sources changes */
GSList *incoming_checks; /**< list of IncomingCheck objs */ GSList *incoming_checks; /* list of IncomingCheck objs */
GList *turn_servers; /**< List of TURN servers */ GList *turn_servers; /* List of TURN servers */
CandidatePair selected_pair; /**< independent from checklists, CandidatePair selected_pair; /* independent from checklists,
see ICE 11.1. "Sending Media" (ID-19) */ see ICE 11.1. "Sending Media" (ID-19) */
NiceCandidate *restart_candidate; /**< for storing active remote candidate during a restart */ NiceCandidate *restart_candidate; /* for storing active remote candidate during a restart */
NiceCandidate *turn_candidate; /**< for storing active turn candidate if turn servers have been cleared */ NiceCandidate *turn_candidate; /* for storing active turn candidate if turn servers have been cleared */
/* I/O handling. The main context must always be non-NULL, and is used for all /* I/O handling. The main context must always be non-NULL, and is used for all
* socket recv() operations. All io_callback emissions are invoked in this * socket recv() operations. All io_callback emissions are invoked in this
* context too. * context too.
* *
* recv_messages and io_callback are mutually exclusive, but it is allowed for * recv_messages and io_callback are mutually exclusive, but it is allowed for
* both to be NULL if the Component is not currently ready to receive data. */ * both to be NULL if the Component is not currently ready to receive data. */
GMutex io_mutex; /**< protects io_callback, io_user_data, GMutex io_mutex; /* protects io_callback, io_user_data,
pending_io_messages and io_callback_id. pending_io_messages and io_callback_id.
immutable: can be accessed without immutable: can be accessed without
holding the agent lock; if the agent holding the agent lock; if the agent
lock is to be taken, it must always be lock is to be taken, it must always be
taken before this one */ taken before this one */
NiceAgentRecvFunc io_callback; /**< function called on io cb */ NiceAgentRecvFunc io_callback; /* function called on io cb */
gpointer io_user_data; /**< data passed to the io function */ gpointer io_user_data; /* data passed to the io function */
GQueue pending_io_messages; /**< queue of messages which have been GQueue pending_io_messages; /* queue of messages which have been
received but not passed to the client received but not passed to the client
in an I/O callback or recv() call yet. in an I/O callback or recv() call yet.
each element is an owned each element is an owned
IOCallbackData */ IOCallbackData */
guint io_callback_id; /* GSource ID of the I/O callback */ guint io_callback_id; /* GSource ID of the I/O callback */
GMainContext *own_ctx; /**< own context for GSources for this GMainContext *own_ctx; /* own context for GSources for this
component */ component */
GMainContext *ctx; /**< context for GSources for this GMainContext *ctx; /* context for GSources for this
component (possibly set from the app) */ component (possibly set from the app) */
NiceInputMessage *recv_messages; /**< unowned messages for receiving into */ NiceInputMessage *recv_messages; /* unowned messages for receiving into */
guint n_recv_messages; /**< length of recv_messages */ guint n_recv_messages; /* length of recv_messages */
NiceInputMessageIter recv_messages_iter; /**< current write position in NiceInputMessageIter recv_messages_iter; /* current write position in
recv_messages */ recv_messages */
GError **recv_buf_error; /**< error information about failed reads */ GError **recv_buf_error; /* error information about failed reads */
NiceAgent *agent; /* unowned, immutable: can be accessed without holding the NiceAgent *agent; /* unowned, immutable: can be accessed without holding the
* agent lock */ * agent lock */
......
...@@ -49,15 +49,27 @@ ...@@ -49,15 +49,27 @@
#define NICE_CANDIDATE_PAIR_MAX_FOUNDATION NICE_CANDIDATE_MAX_FOUNDATION*2 #define NICE_CANDIDATE_PAIR_MAX_FOUNDATION NICE_CANDIDATE_MAX_FOUNDATION*2
/**
* NiceCheckState:
* @NICE_CHECK_WAITING: Waiting to be scheduled.
* @NICE_CHECK_IN_PROGRESS: Connection checks started.
* @NICE_CHECK_SUCCEEDED: Connection successfully checked.
* @NICE_CHECK_FAILED: No connectivity; retransmissions ceased.
* @NICE_CHECK_FROZEN: Waiting to be scheduled to %NICE_CHECK_WAITING.
* @NICE_CHECK_CANCELLED: Check cancelled.
* @NICE_CHECK_DISCOVERED: A valid candidate pair not on the check list.
*
* States for checking a candidate pair.
*/
typedef enum typedef enum
{ {
NICE_CHECK_WAITING = 1, /**< waiting to be scheduled */ NICE_CHECK_WAITING = 1,
NICE_CHECK_IN_PROGRESS, /**< conn. checks started */ NICE_CHECK_IN_PROGRESS,
NICE_CHECK_SUCCEEDED, /**< conn. succesfully checked */ NICE_CHECK_SUCCEEDED,
NICE_CHECK_FAILED, /**< no connectivity, retransmissions ceased */ NICE_CHECK_FAILED,
NICE_CHECK_FROZEN, /**< waiting to be scheduled to WAITING */ NICE_CHECK_FROZEN,
NICE_CHECK_CANCELLED, /**< check cancelled */ NICE_CHECK_CANCELLED,
NICE_CHECK_DISCOVERED /**< a valid candidate pair not on check list */ NICE_CHECK_DISCOVERED,
} NiceCheckState; } NiceCheckState;
typedef struct _CandidateCheckPair CandidateCheckPair; typedef struct _CandidateCheckPair CandidateCheckPair;
......
...@@ -46,13 +46,13 @@ ...@@ -46,13 +46,13 @@
typedef struct typedef struct
{ {
NiceAgent *agent; /**< back pointer to owner */ NiceAgent *agent; /* back pointer to owner */
NiceCandidateType type; /**< candidate type STUN or TURN */ NiceCandidateType type; /* candidate type STUN or TURN */
NiceSocket *nicesock; /**< XXX: should be taken from local cand: existing socket to use */ NiceSocket *nicesock; /* XXX: should be taken from local cand: existing socket to use */
NiceAddress server; /**< STUN/TURN server address */ NiceAddress server; /* STUN/TURN server address */
GTimeVal next_tick; /**< next tick timestamp */ GTimeVal next_tick; /* next tick timestamp */
gboolean pending; /**< is discovery in progress? */ gboolean pending; /* is discovery in progress? */
gboolean done; /**< is discovery complete? */ gboolean done; /* is discovery complete? */
Stream *stream; Stream *stream;
Component *component; Component *component;
TurnServer *turn; TurnServer *turn;
...@@ -66,10 +66,10 @@ typedef struct ...@@ -66,10 +66,10 @@ typedef struct
typedef struct typedef struct
{ {
NiceAgent *agent; /**< back pointer to owner */ NiceAgent *agent; /* back pointer to owner */
NiceSocket *nicesock; /**< existing socket to use */ NiceSocket *nicesock; /* existing socket to use */
NiceAddress server; /**< STUN/TURN server address */ NiceAddress server; /* STUN/TURN server address */
NiceCandidate *candidate; /**< candidate to refresh */ NiceCandidate *candidate; /* candidate to refresh */
Stream *stream; Stream *stream;
Component *component; Component *component;
StunAgent stun_agent; StunAgent stun_agent;
......
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