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 @@
/**
* SECTION:agent
* @short_description: ICE agent API implementation
* @see_also: #NiceCandidate
* @see_also: #NiceAddress
* @see_also: #NiceCandidate, #NiceAddress
* @include: agent.h
* @stability: Stable
*
......@@ -69,49 +68,49 @@
* receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed
* to be used in a blocking loop in a separate thread.
*
<example>
<title>Simple example on how to use libnice</title>
<programlisting>
guint stream_id;
gchar buffer[] = "hello world!";
GSList *lcands = NULL;
// Create a nice agent
NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
// Connect the signals
g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
G_CALLBACK (cb_candidate_gathering_done), NULL);
g_signal_connect (G_OBJECT (agent), "component-state-changed",
G_CALLBACK (cb_component_state_changed), NULL);
g_signal_connect (G_OBJECT (agent), "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 (agent, stream_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>
* <example>
* <title>Simple example on how to use libnice</title>
* <programlisting>
* guint stream_id;
* gchar buffer[] = "hello world!";
* GSList *lcands = NULL;
*
* // Create a nice agent
* NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
*
* // Connect the signals
* g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
* G_CALLBACK (cb_candidate_gathering_done), NULL);
* g_signal_connect (G_OBJECT (agent), "component-state-changed",
* G_CALLBACK (cb_component_state_changed), NULL);
* g_signal_connect (G_OBJECT (agent), "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 (agent, stream_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>
*
* Refer to the examples in the examples/ subdirectory of the libnice source for
* more complete examples.
......
......@@ -145,10 +145,10 @@ struct _TurnServer
{
gint ref_count;
NiceAddress server; /**< TURN server address */
gchar *username; /**< TURN username */
gchar *password; /**< TURN password */
NiceRelayType type; /**< TURN type */
NiceAddress server;
gchar *username;
gchar *password;
NiceRelayType type;
};
/**
......
......@@ -82,7 +82,7 @@ struct _CandidatePair
{
NiceCandidate *local;
NiceCandidate *remote;
guint64 priority; /**< candidate pair priority */
guint64 priority; /* candidate pair priority */
CandidatePairKeepalive keepalive;
};
......@@ -138,48 +138,48 @@ io_callback_data_free (IOCallbackData *data);
struct _Component
{
NiceComponentType type;
guint id; /**< component id */
guint id; /* component id */
NiceComponentState state;
GSList *local_candidates; /**< list of Candidate objs */
GSList *remote_candidates; /**< list of Candidate objs */
GSList *socket_sources; /**< list of SocketSource objs; must only grow monotonically */
guint socket_sources_age; /**< incremented when socket_sources changes */
GSList *incoming_checks; /**< list of IncomingCheck objs */
GList *turn_servers; /**< List of TURN servers */
CandidatePair selected_pair; /**< independent from checklists,
GSList *local_candidates; /* list of Candidate objs */
GSList *remote_candidates; /* list of Candidate objs */
GSList *socket_sources; /* list of SocketSource objs; must only grow monotonically */
guint socket_sources_age; /* incremented when socket_sources changes */
GSList *incoming_checks; /* list of IncomingCheck objs */
GList *turn_servers; /* List of TURN servers */
CandidatePair selected_pair; /* independent from checklists,
see ICE 11.1. "Sending Media" (ID-19) */
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 *restart_candidate; /* for storing active remote candidate during a restart */
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
* socket recv() operations. All io_callback emissions are invoked in this
* context too.
*
* 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. */
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.
immutable: can be accessed without
holding the agent lock; if the agent
lock is to be taken, it must always be
taken before this one */
NiceAgentRecvFunc io_callback; /**< function called on io cb */
gpointer io_user_data; /**< data passed to the io function */
GQueue pending_io_messages; /**< queue of messages which have been
NiceAgentRecvFunc io_callback; /* function called on io cb */
gpointer io_user_data; /* data passed to the io function */
GQueue pending_io_messages; /* queue of messages which have been
received but not passed to the client
in an I/O callback or recv() call yet.
each element is an owned
IOCallbackData */
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 */
GMainContext *ctx; /**< context for GSources for this
GMainContext *ctx; /* context for GSources for this
component (possibly set from the app) */
NiceInputMessage *recv_messages; /**< unowned messages for receiving into */
guint n_recv_messages; /**< length of recv_messages */
NiceInputMessageIter recv_messages_iter; /**< current write position in
NiceInputMessage *recv_messages; /* unowned messages for receiving into */
guint n_recv_messages; /* length of recv_messages */
NiceInputMessageIter recv_messages_iter; /* current write position in
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
* agent lock */
......
......@@ -49,15 +49,27 @@
#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
{
NICE_CHECK_WAITING = 1, /**< waiting to be scheduled */
NICE_CHECK_IN_PROGRESS, /**< conn. checks started */
NICE_CHECK_SUCCEEDED, /**< conn. succesfully checked */
NICE_CHECK_FAILED, /**< no connectivity, retransmissions ceased */
NICE_CHECK_FROZEN, /**< waiting to be scheduled to WAITING */
NICE_CHECK_CANCELLED, /**< check cancelled */
NICE_CHECK_DISCOVERED /**< a valid candidate pair not on check list */
NICE_CHECK_WAITING = 1,
NICE_CHECK_IN_PROGRESS,
NICE_CHECK_SUCCEEDED,
NICE_CHECK_FAILED,
NICE_CHECK_FROZEN,
NICE_CHECK_CANCELLED,
NICE_CHECK_DISCOVERED,
} NiceCheckState;
typedef struct _CandidateCheckPair CandidateCheckPair;
......
......@@ -46,13 +46,13 @@
typedef struct
{
NiceAgent *agent; /**< back pointer to owner */
NiceCandidateType type; /**< candidate type STUN or TURN */
NiceSocket *nicesock; /**< XXX: should be taken from local cand: existing socket to use */
NiceAddress server; /**< STUN/TURN server address */
GTimeVal next_tick; /**< next tick timestamp */
gboolean pending; /**< is discovery in progress? */
gboolean done; /**< is discovery complete? */
NiceAgent *agent; /* back pointer to owner */
NiceCandidateType type; /* candidate type STUN or TURN */
NiceSocket *nicesock; /* XXX: should be taken from local cand: existing socket to use */
NiceAddress server; /* STUN/TURN server address */
GTimeVal next_tick; /* next tick timestamp */
gboolean pending; /* is discovery in progress? */
gboolean done; /* is discovery complete? */
Stream *stream;
Component *component;
TurnServer *turn;
......@@ -66,10 +66,10 @@ typedef struct
typedef struct
{
NiceAgent *agent; /**< back pointer to owner */
NiceSocket *nicesock; /**< existing socket to use */
NiceAddress server; /**< STUN/TURN server address */
NiceCandidate *candidate; /**< candidate to refresh */
NiceAgent *agent; /* back pointer to owner */
NiceSocket *nicesock; /* existing socket to use */
NiceAddress server; /* STUN/TURN server address */
NiceCandidate *candidate; /* candidate to refresh */
Stream *stream;
Component *component;
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