su.docs

sip协议栈

 * @c su_home_t. It checks that the @a suh_size field is valid.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * The function @c su_home_init() returns @c 0 when
 * successful, or @c -1 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_home_t.</strong>
 * </blockquote>
 * 
 * <a name="su_home_deinit"></a>
 * <h3>Function @c su_home_deinit() - free memory blocks from home </h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void su_home_deinit(su_home_t *h);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function @c su_home_deinit() frees the memory blocks
 * associated with the home object.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 * </table>
 * </blockquote>
 * 
 * <h4>Note</h4>
 * <blockquote><strong>This is an internal function, and it is intended for
 * implementing the objects derived from @c su_home_t.</strong>
 * </blockquote>
 * 
 * 
 * <a name="su_wait.h"></a>
 * <h1>&lt;su_wait.h&gt;</h1>
 * 
 * This section describes synchronization functionality.
 * The @c su_wait library provides portable synchronization
 * primitives needed for running communication software.
 * 
 * Synchronization means that the program can stop waiting for events,
 * set callback functions for events, schedule timers, and set callback
 * functions for timers. In other words, it is an OS-independent
 * @c poll()/@c select()/@c WaitForMultipleObjects()
 * interface, spiced up with timer interface.
 * 
 * The library provides three kinds of objects: root
 * objects (@c su_root_t), wait objects
 * (@c su_wait_t), and timer objects
 * (@c su_timer_t).
 * 
 * <a name="wait"></a>
 * <h2>Wait Objects</h2>
 * 
 * 
 *   Wait objects are used to signal I/O events to the process.
 *   The events are as follows:
 * 
 * <dl>
 *   <dt>SU_WAIT_IN
 *   <dd>incoming data is available
 * 
 *   <dt>SU_WAIT_OUT
 *   <dd>data can be output
 * 
 *   <dt>SU_WAIT_ERR
 *   <dd>an error occurred
 * 
 *   <dt>SU_WAIT_HUP
 *   <dd>the socket connection was closed
 * 
 *   <dt>SU_WAIT_ACCEPT
 *   <dd>a listening socket accepted a new connection attempt
 * </dl>
 * 
 * 
 *   It is possible to combine several events with |, binary or operator.
 * 
 * 
 *   Public API contains functions as follows:
 * <ul>
 *   - su_wait_create()
 *   - su_wait_destroy()
 *   - su_wait()
 *   - su_wait_events()
 * </ul>
 * 
 * 
 *   In Unix, the wait object is @c struct poll. The structure contains a file
 *   handle, a mask describing expected events, and a mask containing the
 *   occurred events after calling @c poll(), ie. @c su_wait().
 * 
 * 
 *   In Windows, the wait object is a @c HANDLE (a descriptor of a Windows
 *   kernel entity).
 * 
 * 
 * <a name="su_wait_create"></a>
 * <h3>Function @c su_wait_create()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_wait_create(su_wait_t *newwait, su_socket_t socket, int events)</pre></blockquote>
 * 
 * <h4>Description</h4>
 * 
 * <blockquote>
 * @c Su_wait_create() creates a new wait object for a
 * @a socket with given @a events.  The new wait object is
 * assigned to the @a newwait parameter.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * 
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c newwait<td>the newly created wait object
 *   <tr><td>@c socket <td>socket descriptor
 *   <tr><td>@c events <td>mask for events that can signal this wait object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * 
 * <blockquote>
 * 0 if the call was successful, -1 otherwise.
 * </blockquote>
 * 
 * <a name="su_wait_destroy"></a>
 * <h3>Function @c su_wait_destroy()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre> #include &lt;su_wait.h&gt;
 * 
 * int su_wait_destroy(su_wait_t *waitobj);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>Destroy a wait object.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * 
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c waitobj <td>pointer to wait object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * 
 * <blockquote>
 * 0 when successful, -1 upon an error.
 * </blockquote>
 * 
 * <a name="su_wait"></a>
 * <h3>Function @c su_wait()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_wait(su_wait_t waits[], unsigned n, long timeout);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  Block until a event specified by wait objects or a timeout occurs.
 * 
 * 
 *   In Unix, this is poll.
 * 
 * 
 *   In Windows, this is WSAWaitForMultipleEvents
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c waits   <td>array of wait objects
 *   <tr><td>@c n       <td>number of wait objects in array waits
 *   <tr><td>@c timeout <td>timeout in milliseocnds
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 *   Index of the signaled wait object, if any, SU_WAIT_TIMEOUT if timeout
 *   occurred, and -1 upon an error.
 * </blockquote>
 * 
 * <a name="su_wait_events"></a>
 * <h3>Function @c su_wait_events()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_wait_events(su_wait_t *waitobj, su_socket_t s);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>  Return an mask describing events occurred.
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c waitobj  <td>pointer to wait object
 *   <tr><td>@c s        <td>socket
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  Binary mask describing the events.
 * </blockquote>
 * 
 * <a name="su_wait_mask"></a>
 * <h3>Function @c su_wait_mask()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_wait_mask(su_wait_t *waitobj, su_socket_t s, int events);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 *   Sets the mask describing events that can signal the wait object.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c waitobj  <td>pointer to wait object
 *   <tr><td>@c s        <td>socket
 *   <tr><td>@c events   <td>new event mask
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 *   0 when successful, -1 upon an error.
 * </blockquote>
 * 
 * <a name="root"></a>
 * <h2>Root objects</h2>
 * 
 * 
 *    Root object is a structure containing a list of wait objects,
 *    associated callback functions, and arguments to these functions.
 *    It can also contain a list of timers, and a magic cookie (a pointer
 *    defined by root object user.)
 * 
 * 
 *    The public API contains following functions:
 * <ul>
 *   - su_root_create()
 *   - su_root_destroy()
 *   - su_root_magic()
 *   - su_root_register()
 *   - su_root_unregister()
 *   - su_root_run()
 *   - su_root_break()
 *   - su_root_step()
 * </ul>
 * 
 * These functions are intended for implementing su_root API:
 * <ul>
 *   - su_root_init()
 *   - su_root_deinit()
 *   - su_root_query()
 *   - su_root_event()
 * </ul>
 * 
 * <a name="su_root_create"></a>
 * <h3>Function @c su_root_create()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * su_root_t *su_root_create(su_root_magic_t *magic);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Allocate and initialize an instance of su_root_t
 * </blockquote>
 * 
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c magic    <td>pointer to user data
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  A pointer to allocated su_root_t instance, NULL on error.
 * </blockquote>
 * 
 * 
 * <a name="su_root_destroy"></a>
 * <h3>Function @c su_root_destroy()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * void su_root_destroy(su_root_t *root);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Deinitialize and free 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>
 * 
 * 
 * <a name="su_root_magic"></a>
 * <h3>Function @c su_root_magic()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * su_root_magic_t *su_root_magic(su_root_t *root);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Return the user data pointer that was given input to su_root_create() or
 * 
 *  su_root_init().
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to a root object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  A pointer to user data
 * </blockquote>
 * 
 * 
 * <a name="su_root_register"></a>
 * <h3>Function @c su_root_register()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_root_register(su_root_t *root,
 * 		     su_wait_t *waits,
 * 		     su_wakeup_f callback,
 * 		     su_wakeup_arg_t arg,
 * 		     int priority);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> Register a su_wait_t object. The wait object, a callback function and
 * 
 *  a argument is stored to the root object. The callback function is called,
 *  when the wait object is signaled.
 * 
 *  Please note if identical wait objects are inserted, only first one is
 *  ever signalled.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 *   <tr><td>@c waits    <td>pointer to wait object
 *   <tr><td>@c callback <td>callback function pointer
 *   <tr><td>@c arg      <td>argument given to callback function when it is invoked
 *   <tr><td>@c priority <td>relative priority of the wait object
 *              (0 is normal, 1 important, 2 realtime)
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>  Index of the wait object, or -1 upon an error.
 * </blockquote>
 * 
 * 
 * <a name="su_root_unregister"></a>
 * <h3>Function @c su_root_unregister()</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_wait.h&gt;
 * 
 * int su_root_unregister(su_root_t *root,
 * 		       su_wait_t *wait,
 * 		       su_wakeup_f callback,
 * 		       su_wakeup_arg_t arg);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote> UnRegisters a su_wait_t object. The wait object, a callback function and
 * 
 *  a argument are removed from the root object. The callback function is called,
 *  when the wait object is signaled.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c root     <td>pointer to root object
 *   <tr><td>@c waits    <td>pointer to wait object
 *   <tr><td>@c callback <td>callback function pointer (may be NULL)
 *   <tr><td>@c arg      <td>argument given to callback function when it
 *                                 is invoked (may be NULL)