su.docs

sip协议栈

 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  Index of the wait object, or -1 upon an error.
 * </blockquote>
 * 
 * 
 * <a name="su_root_run"></a>
 * <h3>Function @c su_root_run()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * void su_root_run(su_root_t *root);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  This function waits for wait objects and the timers associated with
 *   the root object.  When any wait object is signaled or timer is
 *   expired, it invokes the callbacks, and returns waiting.
 * 
 * 
 *   This function returns when su_root_break() is called from a callback.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 * </table>
 * </blockquote>
 * 
 * 
 * <a name="su_root_break"></a>
 * <h3>Function @c su_root_break()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * void su_root_break(su_root_t *root);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  If this function is used to terminate execution of su_root_run(). It
 * 
 *   can be called from a callback function.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 * </table>
 * </blockquote>
 * 
 * 
 * <a name="su_root_step"></a>
 * <h3>Function @c su_root_step()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * su_duration_t su_root_step(su_root_t *root, su_duration_t tout);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  This function waits for wait objects and the timers associated with
 *   the @a root object.  When any wait object is signaled or timer is
 *   expired, it invokes the callbacks, and returns.
 * 
 * 
 *   This function returns when a callback has been invoked or @a tout
 *   milliseconds is elapsed.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 *   <tr><td>@c tout     <td>timeout in milliseconds
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 *   Milliseconds to the next invocation of timer, or SU_WAIT_FOREVER if
 *   there are no active timers.
 * </blockquote>
 * 
 * <a name="timer"></a>
 * <h2>Timer objects</h2>
 * 
 * Timers are used to schedule some task to be executed at given time or
 * after a default interval. The default interval is specified when the
 * timer is created. We call timer activation "setting the timer", and
 * deactivation "resetting the timer" (as in SDL). When the given time has
 * arrived or the default interval has elapsed, the timer expires and
 * it is ready for execution.
 * 
 * These functions are available for handling timers:
 * 
 * - su_timer_create()
 *   - su_timer_destroy()
 *   - su_timer_set()
 *   - su_timer_set_at()
 *   - su_timer_reset()
 *   - su_timer_run()
 * 
 * <a name="su_timer_create"></a>
 * <h3>Function @c su_timer_create()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * su_timer_t *su_timer_create(su_root_t *root, su_duration_t msec);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * 
 * <blockquote>
 * Allocate and initialize an instance of su_timer_t.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *  <tr><td>@c root   <td>the root object with which the timer will be associated
 *  <tr><td>@c msec   <td>the default duration of the timer
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  A pointer to allocated timer instance, NULL on error.
 * </blockquote>
 * 
 * 
 * <a name="su_timer_destroy"></a>
 * <h3>Function @c su_timer_destroy()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * void su_timer_destroy(su_timer_t *t);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Deinitialize and free an instance of su_timer_t.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t      <td>pointer to the timer object
 * </table>
 * </blockquote>
 * 
 * 
 * <a name="su_timer_set"></a>
 * <h3>Function @c su_timer_set()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_timer_set(su_timer_t *t,
 * 		 su_timer_f wakeup,
 * 		 su_wakeup_arg_t arg);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Sets the given timer to expire after the default duration.
 * 
 * The timer must have an default duration.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t      <td>pointer to the timer object
 *   <tr><td>@c wakeup <td>pointer to the wakeup function
 *   <tr><td>@c arg    <td>argument given to the wakeup function
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  0 if successful, -1 otherwise.
 * </blockquote>
 * 
 * 
 * <a name="su_timer_set_at"></a>
 * <h3>Function @c su_timer_set_at()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_timer_set_at(su_timer_t *t,
 * 		    su_timer_f wakeup,
 * 		    su_wakeup_arg_t arg,
 * 		    su_time_t when);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Sets the timer to expire at given time.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t      <td>pointer to the timer object
 *   <tr><td>@c wakeup <td>pointer to the wakeup function
 *   <tr><td>@c arg    <td>argument given to the wakeup function
 *   <tr><td>@c when   <td>time structure defining the wakeup time
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  0 if successful, -1 otherwise.
 * </blockquote>
 * 
 * 
 * <a name="su_timer_reset"></a>
 * <h3>Function @c su_timer_reset()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_timer_reset(su_timer_t *t);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  Resets the given timer.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t      <td>pointer to the timer object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  0 if successful, -1 otherwise.
 * </blockquote>
 * 
 * <a name="su_timer_run"></a>
 * <h3>Function @c su_timer_run()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * su_duration_t su_timer_run(su_timer_t ** const t0, su_duration_t tout);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  Expires and executes expired timers in queue.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t0     <td>pointer to the timer queue
 *   <tr><td>@c tout   <td>timeout in milliseconds
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 *  The duration in milliseconds before the next timer expires, or timeout (2**31 - 1
 *  ms), whichever is shorter.
 * </blockquote>
 * 
 * <!--
 * Root object is used for synchronizing. There must be one root object per
 * thread. There are two alternative ways for creating a root object. If you
 * are just using su_root_t, and don't want to <a
 * href="#inherit_su_root_t">inherit from it</a>, you can use
 * @c su_create().
 * -->
 * 
 * <a name="su_wait_internal.h"></a>
 * <h1>&lt;su_wait_internal.h&gt;</h1>
 * 
 * 
 * This section contains the internal functions, that is, functions used to
 * implement objects in @c &lt;su_wait.h&gt;.
 * 
 * <a name="su_root_init"></a>
 * <h3>Function @c su_root_init()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * #include &lt;su_wait_internal.h&gt;
 * 
 * int su_root_init(su_root_t *root, su_root_magic_t *magic);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * 
 * <blockquote>
 * 
 * Initialize an instance of @c su_root_t. The caller should allocate
 * the memory required for su_root_t, and set the sur_size to the size of the
 * allocated structure.
 * 
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * 
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root    <td>pointer to a uninitialized root structure
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  0 when call was successful, -1 otherwise.
 * </blockquote>
 * 
 * 
 * <h4>Note</h4>
 * <blockquote>
 * <strong>This is an internal function, and it is intended for implementing
 * the objects derived from @c su_root_t.</strong>
 * </blockquote>
 * 
 * 
 * <a name="su_root_deinit"></a>
 * <h3>Function @c su_root_deinit()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * #include &lt;su_wait_internal.h&gt;
 * 
 * void su_root_deinit(su_root_t *root);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Deinitialize an instance of su_root_t
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root    <td>pointer to a root structure
 * </table>
 * </blockquote>
 * 
 * <h4>Note</h4>
 * <blockquote>  <strong>This is an internal function, and it is intended for
 * implementing the objects derived from @c su_root_t.</strong>
 * </blockquote>
 * 
 * <a name="su_root_query"></a>
 * <h3>Function @c su_root_query()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * #include &lt;su_wait_internal.h&gt;
 * 
 * unsigned su_root_query(su_root_t *root, su_wait_t *waits, unsigned n_waits);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Copies the su_wait_t objects from the root. The number of wait objects
 * 
 *  can be found out by calling su_root_query() with n_waits as zero.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c waits    <td>pointer to array to which wait objects are copied
 *   <tr><td>@c root     <td>pointer to root object
 *   <tr><td>@c n_waits  <td>number of wait objects fitting in array waits
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  Number of wait objects, or 0 upon an error.
 * </blockquote>
 * 
 * 
 * <h4>Note</h4>
 * <blockquote><strong>This is an internal function, and it is intended for
 * implementing the objects derived from @c su_root_t.</strong>
 * </blockquote>
 * 
 * 
 * <a name="su_root_event"></a>
 * <h3>Function @c su_root_event()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * #include &lt;su_wait_internal.h&gt;
 * 
 * void su_root_event(su_root_t *root, su_wait_t *waitobj);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  Invokes the callback function associated with the wait object.
 * 
 * 
 *   If waitobj is NULL, check if a wait object associated with root is
 *   signaled, and its callback is invoked.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 *   <tr><td>@c waitobj    <td>pointer to wait object, or NULL
 * </table>
 * </blockquote>
 * 
 * <h4>Note</h4>
 * <blockquote><strong>This is an internal function, and it is intended for
 * implementing the objects derived from @c su_root_t.</strong>
 * </blockquote>
 * 
 */