[svn-commits] jpeeler: trunk r180719 - in /trunk: include/asterisk/ main/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Mon Mar 9 15:58:21 CDT 2009
Author: jpeeler
Date: Mon Mar 9 15:58:17 2009
New Revision: 180719
URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=180719
Log:
Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
Copied from my review board description:
This is a continuation of the API changes documentation started for describing
changes between releases. Most of the API changes were pretty simple needing
only to be brought to attention via the new "Asterisk API Changes" list.
However, if you see anything that needs further explanation feel free to
supplement what is there. The current method of documenting is to add (in the
header file): \version <ver number> <description of changes> and then to add
the function to the change list in doxyref.h on the AstAPIChanges page. I also
made sure all the functions that were newly added were tagged with \since
1.6.1. I think this is a good habit to start both for the historical aspect as
well as for the future ability to easily add a "New Asterisk API" page.
Review: http://reviewboard.digium.com/r/190/
Modified:
trunk/include/asterisk/app.h
trunk/include/asterisk/astobj2.h
trunk/include/asterisk/audiohook.h
trunk/include/asterisk/callerid.h
trunk/include/asterisk/channel.h
trunk/include/asterisk/config.h
trunk/include/asterisk/datastore.h
trunk/include/asterisk/devicestate.h
trunk/include/asterisk/dlinkedlists.h
trunk/include/asterisk/dnsmgr.h
trunk/include/asterisk/doxyref.h
trunk/include/asterisk/dsp.h
trunk/include/asterisk/enum.h
trunk/include/asterisk/event.h
trunk/include/asterisk/extconf.h
trunk/include/asterisk/heap.h
trunk/include/asterisk/http.h
trunk/include/asterisk/linkedlists.h
trunk/include/asterisk/lock.h
trunk/include/asterisk/logger.h
trunk/include/asterisk/manager.h
trunk/include/asterisk/pbx.h
trunk/include/asterisk/res_odbc.h
trunk/include/asterisk/rtp.h
trunk/include/asterisk/sched.h
trunk/include/asterisk/taskprocessor.h
trunk/include/asterisk/tcptls.h
trunk/include/asterisk/timing.h
trunk/include/asterisk/udptl.h
trunk/include/asterisk/utils.h
trunk/main/devicestate.c
trunk/main/enum.c
trunk/main/tcptls.c
Modified: trunk/include/asterisk/app.h
URL: http://svn.digium.com/svn-view/asterisk/trunk/include/asterisk/app.h?view=diff&rev=180719&r1=180718&r2=180719
==============================================================================
--- trunk/include/asterisk/app.h (original)
+++ trunk/include/asterisk/app.h Mon Mar 9 15:58:17 2009
@@ -37,7 +37,7 @@
/* IVR stuff */
/*! \brief Callback function for IVR
- \return returns 0 on completion, -1 on hangup or digit if interrupted
+ \return returns 0 on completion, -1 on hangup or digit if interrupted
*/
typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
@@ -57,8 +57,8 @@
AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */
} ast_ivr_action;
-/*!
- Special "options" are:
+/*!
+ Special "options" are:
\arg "s" - "start here (one time greeting)"
\arg "g" - "greeting/instructions"
\arg "t" - "timeout"
@@ -69,7 +69,7 @@
struct ast_ivr_option {
char *option;
ast_ivr_action action;
- void *adata;
+ void *adata;
};
struct ast_ivr_menu {
@@ -83,13 +83,13 @@
#define AST_IVR_DECLARE_MENU(holder, title, flags, foo...) \
static struct ast_ivr_option __options_##holder[] = foo;\
static struct ast_ivr_menu holder = { title, flags, __options_##holder }
-
-
-/*! \brief Runs an IVR menu
+
+
+/*! \brief Runs an IVR menu
\return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
-/*! \brief Plays a stream and gets DTMF data from a channel
+/*! \brief Plays a stream and gets DTMF data from a channel
* \param c Which channel one is interacting with
* \param prompt File to pass to ast_streamfile (the one that you wish to play).
* It is also valid for this to be multiple files concatenated by "&".
@@ -98,8 +98,8 @@
* \param maxlen Max Length of the data
* \param timeout Timeout length waiting for data(in milliseconds). Set to 0 for standard timeout(six seconds), or -1 for no time out.
*
- * This function was designed for application programmers for situations where they need
- * to play a message and then get some DTMF data in response to the message. If a digit
+ * This function was designed for application programmers for situations where they need
+ * to play a message and then get some DTMF data in response to the message. If a digit
* is pressed during playback, it will immediately break out of the message and continue
* execution of your code.
*/
@@ -108,6 +108,14 @@
/*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
+/*!
+ * \brief Set voicemail function callbacks
+ * \param[in] inboxcount2_func set function pointer
+ * \param[in] sayname_func set function pointer
+ * \param[in] inboxcount_func set function pointer
+ * \param[in] messagecount_func set function pointer
+ * \version 1.6.1 Added inboxcount2_func, sayname_func
+ */
void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder),
int (*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs),
int (*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs),
@@ -122,16 +130,31 @@
/*! \brief Determine number of new/old messages in a mailbox */
int ast_app_inboxcount(const char *mailbox, int *newmsgs, int *oldmsgs);
-/*! \brief Determine number of urgent/new/old messages in a mailbox */
+/*!
+ * \brief Determine number of urgent/new/old messages in a mailbox
+ * \param[in] mailbox the mailbox context to use
+ * \param[out] urgentmsgs the urgent message count
+ * \param[out] newmsgs the new message count
+ * \param[out] oldmsgs the old message count
+ * \return Returns 0 for success, negative upon error
+ * \since 1.6.1
+ */
int ast_app_inboxcount2(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs);
-/*! Given a mailbox and context, play that mailbox owner's name to the channel specified */
+/*!
+ * \brief Given a mailbox and context, play that mailbox owner's name to the channel specified
+ * \param[in] chan channel to announce name to
+ * \param[in] mailbox mailbox to retrieve name for
+ * \param[in] context context to retrieve name for
+ * \return Returns 0 for success, negative upon error
+ * \since 1.6.1
+ */
int ast_app_sayname(struct ast_channel *chan, const char *mailbox, const char *context);
/*! \brief Determine number of messages in a given mailbox and folder */
int ast_app_messagecount(const char *context, const char *mailbox, const char *folder);
-/*! \brief Safely spawn an external program while closing file descriptors
+/*! \brief Safely spawn an external program while closing file descriptors
\note This replaces the \b system call in all Asterisk modules
*/
int ast_safe_system(const char *s);
@@ -179,13 +202,13 @@
/*! \brief Stream a filename (or file descriptor) as a generator. */
int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
-/*!
- * \brief Stream a file with fast forward, pause, reverse, restart.
- * \param chan
+/*!
+ * \brief Stream a file with fast forward, pause, reverse, restart.
+ * \param chan
* \param file filename
- * \param fwd, rev, stop, pause, restart, skipms, offsetms
- *
- * Before calling this function, set this to be the number
+ * \param fwd, rev, stop, pause, restart, skipms, offsetms
+ *
+ * Before calling this function, set this to be the number
* of ms to start from the beginning of the file. When the function
* returns, it will be the number of ms from the beginning where the
* playback stopped. Pass NULL if you don't care.
@@ -197,15 +220,15 @@
int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf);
-/*! \brief Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum
+/*! \brief Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum
\n
- permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
+ permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
calls ast_unlock_path() on 'path' if passed */
int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
-/*! \brief Record a message and prepend the message to the given record file after
- playing the optional playfile (or a beep), storing the duration in
- 'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under
+/*! \brief Record a message and prepend the message to the given record file after
+ playing the optional playfile (or a beep), storing the duration in
+ 'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under
'silencethreshold' or use '-1' for either or both parameters for defaults. */
int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
@@ -338,7 +361,7 @@
*/
#define AST_STANDARD_APP_ARGS(args, parse) \
args.argc = ast_app_separate_args(parse, ',', args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
-
+
/*!
\brief Performs the 'nonstandard' argument separation process for an application.
\param args An argument structure defined using AST_DECLARE_APP_ARGS
@@ -351,7 +374,7 @@
*/
#define AST_NONSTANDARD_APP_ARGS(args, parse, sep) \
args.argc = ast_app_separate_args(parse, sep, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
-
+
/*!
\brief Separate a string into arguments in an array
\param buf The string to be parsed (this must be a writable copy, as it will be modified)
@@ -511,13 +534,24 @@
/*! \brief Decode a stream of encoded control or extended ASCII characters */
int ast_str_get_encoded_str(struct ast_str **str, int maxlen, const char *stream);
-/*! \brief Common routine for child processes, to close all fds prior to exec(2) */
+/*!
+ * \brief Common routine for child processes, to close all fds prior to exec(2)
+ * \param[in] n starting file descriptor number for closing all higher file descriptors
+ * \since 1.6.1
+ */
void ast_close_fds_above_n(int n);
-/*! \brief Common routine to safely fork without a chance of a signal handler firing badly in the child */
+/*!
+ * \brief Common routine to safely fork without a chance of a signal handler firing badly in the child
+ * \param[in] stop_reaper flag to determine if sigchld handler is replaced or not
+ * \since 1.6.1
+ */
int ast_safe_fork(int stop_reaper);
-/*! \brief Common routine to cleanup after fork'ed process is complete (if reaping was stopped) */
+/*!
+ * \brief Common routine to cleanup after fork'ed process is complete (if reaping was stopped)
+ * \since 1.6.1
+ */
void ast_safe_fork_cleanup(void);
#if defined(__cplusplus) || defined(c_plusplus)
Modified: trunk/include/asterisk/astobj2.h
URL: http://svn.digium.com/svn-view/asterisk/trunk/include/asterisk/astobj2.h?view=diff&rev=180719&r1=180718&r2=180719
==============================================================================
--- trunk/include/asterisk/astobj2.h (original)
+++ trunk/include/asterisk/astobj2.h Mon Mar 9 15:58:17 2009
@@ -19,7 +19,7 @@
#include "asterisk/compat.h"
-/*! \file
+/*! \file
* \ref AstObj2
*
* \page AstObj2 Object Model implementing objects and containers.
@@ -46,9 +46,9 @@
Creating an object requires the size of the object and
and a pointer to the destructor function:
-
+
struct foo *o;
-
+
o = ao2_alloc(sizeof(struct foo), my_destructor_fn);
The value returned points to the user-visible portion of the objects
@@ -66,7 +66,7 @@
ao2_ref(o, -1)
causing the destructor to be called (and then memory freed) when
- the refcount goes to 0.
+ the refcount goes to 0.
- ao2_ref(o, +1) can be used to modify the refcount on the
object in case we want to pass it around.
@@ -138,9 +138,9 @@
/*
\note DEBUGGING REF COUNTS BIBLE:
-An interface to help debug refcounting is provided
+An interface to help debug refcounting is provided
in this package. It is dependent on the REF_DEBUG macro being
-defined in a source file, before the #include of astobj2.h,
+defined in a source file, before the #include of astobj2.h,
and in using variants of the normal ao2_xxxx functions
that are named ao2_t_xxxx instead, with an extra argument, a string,
that will be printed out into /tmp/refs when the refcount for an
@@ -153,14 +153,14 @@
ao2_t_container_alloc(arg1,arg2,arg3,arg4)
ao2_t_link(arg1, arg2, arg3)
ao2_t_unlink(arg1, arg2, arg3)
-ao2_t_callback(arg1,arg2,arg3,arg4,arg5)
+ao2_t_callback(arg1,arg2,arg3,arg4,arg5)
ao2_t_find(arg1,arg2,arg3,arg4)
ao2_t_iterator_next(arg1, arg2)
If you study each argument list, you will see that these functions all have
one extra argument that their ao2_xxx counterpart. The last argument in
each case is supposed to be a string pointer, a "tag", that should contain
-enough of an explanation, that you can pair operations that increment the
+enough of an explanation, that you can pair operations that increment the
ref count, with operations that are meant to decrement the refcount.
Each of these calls will generate at least one line of output in /tmp/refs.
@@ -186,9 +186,9 @@
0x8cc07e8 -1 chan_sip.c:2370:unref_peer (unref_peer, from sip_devicestate, release ref from find_peer) [@3]
...
-The first column is the object address.
-The second column reflects how the operation affected the ref count
- for that object. Creation sets the ref count to 1 (=1).
+The first column is the object address.
+The second column reflects how the operation affected the ref count
+ for that object. Creation sets the ref count to 1 (=1).
increment or decrement and amount are specified (-1/+1).
The remainder of the line specifies where in the file the call was made,
and the function name, and the tag supplied in the function call.
@@ -240,13 +240,13 @@
#endif
In the above code, note that the "normal" helper funcs call ao2_ref() as
-normal, and the "helper" functions call ao2_ref_debug directly with the
+normal, and the "helper" functions call ao2_ref_debug directly with the
file, function, and line number info provided. You might find this
well worth the effort to help track these function calls in the code.
-To find out why objects are not destroyed (a common bug), you can
-edit the source file to use the ao2_t_* variants, add the #define REF_DEBUG 1
-before the #include "asterisk/astobj2.h" line, and add a descriptive
+To find out why objects are not destroyed (a common bug), you can
+edit the source file to use the ao2_t_* variants, add the #define REF_DEBUG 1
+before the #include "asterisk/astobj2.h" line, and add a descriptive
tag to each call. Recompile, and run Asterisk, exit asterisk with
"stop gracefully", which should result in every object being destroyed.
Then, you can "sort -k 1 /tmp/refs > x1" to get a sorted list of
@@ -254,16 +254,16 @@
for you and output any problems it finds.
The above may seem astronomically more work than it is worth to debug
-reference counts, which may be true in "simple" situations, but for
+reference counts, which may be true in "simple" situations, but for
more complex situations, it is easily worth 100 times this effort to
help find problems.
-To debug, pair all calls so that each call that increments the
+To debug, pair all calls so that each call that increments the
refcount is paired with a corresponding call that decrements the
-count for the same reason. Hopefully, you will be left with one
+count for the same reason. Hopefully, you will be left with one
or more unpaired calls. This is where you start your search!
-For instance, here is an example of this for a dialog object in
+For instance, here is an example of this for a dialog object in
chan_sip, that was not getting destroyed, after I moved the lines around
to pair operations:
@@ -300,11 +300,11 @@
(by Steve Murphy)
SOME TIPS for complicated code, and ref counting:
-1. Theoretically, passing a refcounted object pointer into a function
+1. Theoretically, passing a refcounted object pointer into a function
call is an act of copying the reference, and could be refcounted.
But, upon examination, this sort of refcounting will explode the amount
of code you have to enter, and for no tangible benefit, beyond
-creating more possible failure points/bugs. It will even
+creating more possible failure points/bugs. It will even
complicate your code and make debugging harder, slow down your program
doing useless increments and decrements of the ref counts.
@@ -312,14 +312,14 @@
is copied into a structure or stored. Make sure to decrement the refcount
of any previous pointer that might have been there, if setting
this field might erase a previous pointer. ao2_find and iterate_next
-internally increment the ref count when they return a pointer, so
+internally increment the ref count when they return a pointer, so
you need to decrement the count before the pointer goes out of scope.
3. Any time you decrement a ref count, it may be possible that the
object will be destroyed (freed) immediately by that call. If you
-are destroying a series of fields in a refcounted object, and
+are destroying a series of fields in a refcounted object, and
any of the unref calls might possibly result in immediate destruction,
-you can first increment the count to prevent such behavior, then
+you can first increment the count to prevent such behavior, then
after the last test, decrement the pointer to allow the object
to be destroyed, if the refcount would be zero.
@@ -345,7 +345,7 @@
}
...
dialog_unref(dialog, "Let's unbump the count in the unlink so the poor pvt can disappear if it is time");
-
+
In the above code, the ao2_t_unlink could end up destroying the dialog
object; if this happens, then the subsequent usages of the dialog
pointer could result in a core dump. So, we 'bump' the
@@ -385,10 +385,10 @@
/*! \brief
* Allocate and initialize an object.
- *
+ *
* \param data_size The sizeof() of the user-defined structure.
* \param destructor_fn The destructor function (can be NULL)
- * \return A pointer to user-data.
+ * \return A pointer to user-data.
*
* Allocates a struct astobj2 with sufficient space for the
* user-defined structure.
@@ -448,7 +448,7 @@
/*! \brief
* Lock an object.
- *
+ *
* \param a A pointer to the object we want to lock.
* \return 0 on success, other values on error.
*/
@@ -461,7 +461,7 @@
/*! \brief
* Unlock an object.
- *
+ *
* \param a A pointer to the object we want unlock.
* \return 0 on success, other values on error.
*/
@@ -485,20 +485,22 @@
int _ao2_trylock(void *a, const char *file, const char *func, int line, const char *var);
#endif
-/*! \brief
- * Return the lock address of an object
- *
- * \param a A pointer to the object we want.
+/*!
+ * \brief Return the lock address of an object
+ *
+ * \param[in] obj A pointer to the object we want.
* \return the address of the lock, else NULL.
- *
- * This function comes in handy mainly for debugging locking
- * situations, where the locking trace code reports the
+ *
+ * This function comes in handy mainly for debugging locking
+ * situations, where the locking trace code reports the
* lock address, this allows you to correlate against
* object address, to match objects to reported locks.
+ *
+ * \since 1.6.1
*/
void *ao2_object_get_lockaddr(void *obj);
-/*!
+/*!
\page AstObj2_Containers AstObj2 Containers
Containers are data structures meant to store several objects,
@@ -522,7 +524,7 @@
- \b ao2_find(c, arg, flags)
returns zero or more element matching a given criteria
- (specified as arg). 'c' is the container pointer. Flags
+ (specified as arg). 'c' is the container pointer. Flags
can be:
OBJ_UNLINK - to remove the object, once found, from the container.
OBJ_NODATA - don't return the object if found (no ref count change)
@@ -535,14 +537,14 @@
Similar to find. fn() can tell when to stop, and
do anything with the object including unlinking it.
- c is the container;
- - flags can be
+ - flags can be
OBJ_UNLINK - to remove the object, once found, from the container.
OBJ_NODATA - don't return the object if found (no ref count change)
OBJ_MULTIPLE - don't stop at first match (not fully implemented)
OBJ_POINTER - if set, 'arg' is an object pointer, and a hashtable
search will be done. If not, a traversal is done through
all the hashtable 'buckets'..
- - fn is a func that returns int, and takes 3 args:
+ - fn is a func that returns int, and takes 3 args:
(void *obj, void *arg, int flags);
obj is an object
arg is the same as arg passed into ao2_callback
@@ -560,7 +562,7 @@
The mechanism is very flexible because the callback function fn()
can do basically anything e.g. counting, deleting records, etc.
possibly using arg to store the results.
-
+
- \b iterate on a container
this is done with the following sequence
@@ -571,7 +573,7 @@
void *o;
i = ao2_iterator_init(c, flags);
-
+
while ( (o = ao2_iterator_next(&i)) ) {
... do something on o ...
ao2_ref(o, -1);
@@ -583,7 +585,7 @@
- \b ao2_ref(c, -1)
dropping a reference to a container destroys it, very simple!
-
+
Containers are ao2 objects themselves, and this is why their
implementation is simple too.
@@ -661,22 +663,22 @@
*/
typedef int (ao2_hash_fn)(const void *obj, const int flags);
-/*! \name Object Containers
+/*! \name Object Containers
* Here start declarations of containers.
*/
/*@{ */
struct ao2_container;
/*! \brief
- * Allocate and initialize a container
+ * Allocate and initialize a container
* with the desired number of buckets.
- *
+ *
* We allocate space for a struct astobj_container, struct container
* and the buckets[] array.
*
* \param n_buckets Number of buckets for hash
* \param hash_fn Pointer to a function computing a hash value.
- * \param cmp_fn Pointer to a function comparating key-value
+ * \param cmp_fn Pointer to a function comparating key-value
* with a string. (can be NULL)
* \return A pointer to a struct container.
*
@@ -693,7 +695,7 @@
struct ao2_container *_ao2_container_alloc(const unsigned int n_buckets,
ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn);
struct ao2_container *_ao2_container_alloc_debug(const unsigned int n_buckets,
- ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn,
+ ao2_hash_fn *hash_fn, ao2_callback_fn *cmp_fn,
char *tag, char *file, int line, const char *funcname);
/*! \brief
@@ -705,7 +707,7 @@
/*! \name Object Management
* Here we have functions to manage objects.
*
- * We can use the functions below on any kind of
+ * We can use the functions below on any kind of
* object defined by the user.
*/
/*@{ */
@@ -750,7 +752,7 @@
* be called.
*
* \note If the object gets unlinked from the container, the container's
- * reference to the object will be automatically released. (The
+ * reference to the object will be automatically released. (The
* refcount will be decremented).
*/
#ifdef REF_DEBUG
@@ -774,7 +776,7 @@
/*! \brief
* ao2_callback() is a generic function that applies cb_fn() to all objects
* in a container, as described below.
- *
+ *
* \param c A pointer to the container to operate on.
* \param flags A set of flags specifying the operation to perform,
partially used by the container code, but also passed to
@@ -790,8 +792,8 @@
* \param cb_fn A function pointer, that will be called on all
objects, to see if they match. This function returns CMP_MATCH
if the object is matches the criteria; CMP_STOP if the traversal
- should immediately stop, or both (via bitwise ORing), if you find a
- match and want to end the traversal, and 0 if the object is not a match,
+ should immediately stop, or both (via bitwise ORing), if you find a
+ match and want to end the traversal, and 0 if the object is not a match,
but the traversal should continue. This is the function that is applied
to each object traversed. It's arguments are:
(void *obj, void *arg, int flags), where:
@@ -800,7 +802,7 @@
flags is the same as flags passed into ao2_callback (flags are
also used by ao2_callback).
* \param arg passed to the callback.
- * \return A pointer to the object found/marked,
+ * \return A pointer to the object found/marked,
* a pointer to a list of objects matching comparison function,
* NULL if not found.
*
@@ -822,13 +824,13 @@
* This function searches through a container and performs operations
* on objects according on flags passed.
* XXX describe better
- * The comparison is done calling the compare function set implicitly.
- * The p pointer can be a pointer to an object or to a key,
+ * The comparison is done calling the compare function set implicitly.
+ * The p pointer can be a pointer to an object or to a key,
* we can say this looking at flags value.
* If p points to an object we will search for the object pointed
* by this value, otherwise we serch for a key value.
* If the key is not uniq we only find the first matching valued.
- * If we use the OBJ_MARK flags, we mark all the objects matching
+ * If we use the OBJ_MARK flags, we mark all the objects matching
* the condition.
*
* The use of flags argument is the follow:
@@ -842,7 +844,7 @@
* to a key (not yet supported)
* OBJ_POINTER the pointer is an object pointer
*
- * In case we return a list, the callee must take care to destroy
+ * In case we return a list, the callee must take care to destroy
* that list when no longer used.
*
* \note When the returned object is no longer in use, ao2_ref() should
@@ -856,7 +858,7 @@
#define ao2_callback(arg1,arg2,arg3,arg4) _ao2_callback((arg1), (arg2), (arg3), (arg4))
#endif
void *_ao2_callback_debug(struct ao2_container *c, enum search_flags flags,
- ao2_callback_fn *cb_fn, void *arg, char *tag,
+ ao2_callback_fn *cb_fn, void *arg, char *tag,
char *file, int line, const char *funcname);
void *_ao2_callback(struct ao2_container *c,
enum search_flags flags,
@@ -885,7 +887,7 @@
#define ao2_callback_data(arg1,arg2,arg3,arg4,arg5) _ao2_callback_data((arg1), (arg2), (arg3), (arg4), (arg5))
#endif
void *_ao2_callback_data_debug(struct ao2_container *c, enum search_flags flags,
- ao2_callback_data_fn *cb_fn, void *arg, void *data, char *tag,
+ ao2_callback_data_fn *cb_fn, void *arg, void *data, char *tag,
char *file, int line, const char *funcname);
void *_ao2_callback_data(struct ao2_container *c,
enum search_flags flags,
@@ -909,7 +911,7 @@
*
* When we need to walk through a container, we use
* ao2_iterator to keep track of the current position.
- *
+ *
* Because the navigation is typically done without holding the
* lock on the container across the loop,
* objects can be inserted or deleted or moved
@@ -924,7 +926,7 @@
* not see this object, because it would still be waiting on the container
* lock so that it can be added.
* - It would be extremely rare to see an object twice. The only way this can
- * happen is if an object got unlinked from the container and added again
+ * happen is if an object got unlinked from the container and added again
* during the same iteration. Furthermore, when the object gets added back,
* it has to be in the current or later bucket for it to be seen again.
*
@@ -953,7 +955,7 @@
*
*/
-/*! \brief
+/*! \brief
* The Astobj2 iterator
*
* \note You are not supposed to know the internals of an iterator!
@@ -995,7 +997,7 @@
unsigned int version;
};
-/* the flags field can contain F_AO2I_DONTLOCK, which will prevent
+/* the flags field can contain F_AO2I_DONTLOCK, which will prevent
ao2_iterator_next calls from locking the container while it
searches for the next pointer */
Modified: trunk/include/asterisk/audiohook.h
URL: http://svn.digium.com/svn-view/asterisk/trunk/include/asterisk/audiohook.h?view=diff&rev=180719&r1=180718&r2=180719
==============================================================================
--- trunk/include/asterisk/audiohook.h (original)
+++ trunk/include/asterisk/audiohook.h Mon Mar 9 15:58:17 2009
@@ -165,7 +165,7 @@
*/
void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
-/*!
+/*!
* \brief Detach specified source audiohook from channel
*
* \param chan Channel to detach from
@@ -205,9 +205,9 @@
/*!
\brief Find out how many audiohooks from a certain source exist on a given channel, regardless of status.
- \param chan The channel on which to find the spies
+ \param chan The channel on which to find the spies
\param source The audiohook's source
- \param type The type of audiohook
+ \param type The type of audiohook
\return Return the number of audiohooks which are from the source specified
Note: Function performs nlocking.
@@ -235,26 +235,32 @@
*/
#define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
-/*! \brief Adjust the volume on frames read from or written to a channel
+/*!
+ * \brief Adjust the volume on frames read from or written to a channel
* \param chan Channel to muck with
* \param direction Direction to set on
* \param volume Value to adjust the volume by
* \return Returns 0 on success, -1 on failure
+ * \since 1.6.1
*/
int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
-/*! \brief Retrieve the volume adjustment value on frames read from or written to a channel
+/*!
+ * \brief Retrieve the volume adjustment value on frames read from or written to a channel
* \param chan Channel to retrieve volume adjustment from
* \param direction Direction to retrieve
* \return Returns adjustment value
+ * \since 1.6.1
*/
int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
-/*! \brief Adjust the volume on frames read from or written to a channel
+/*!
+ * \brief Adjust the volume on frames read from or written to a channel
* \param chan Channel to muck with
* \param direction Direction to increase
* \param volume Value to adjust the adjustment by
* \return Returns 0 on success, -1 on failure
+ * \since 1.6.1
*/
int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
Modified: trunk/include/asterisk/callerid.h
URL: http://svn.digium.com/svn-view/asterisk/trunk/include/asterisk/callerid.h?view=diff&rev=180719&r1=180718&r2=180719
==============================================================================
--- trunk/include/asterisk/callerid.h (original)
+++ trunk/include/asterisk/callerid.h Mon Mar 9 15:58:17 2009
@@ -66,9 +66,9 @@
/* defines dealing with message waiting indication generation */
/*! MWI SDMF format */
-#define CID_MWI_TYPE_SDMF 0x00
+#define CID_MWI_TYPE_SDMF 0x00
/*! MWI MDMF format -- generate only MWI field */
-#define CID_MWI_TYPE_MDMF 0x01
+#define CID_MWI_TYPE_MDMF 0x01
/*! MWI MDMF format -- generate name, callerid, date and MWI fields */
#define CID_MWI_TYPE_MDMF_FULL 0x02
@@ -169,11 +169,12 @@
*/
int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, int codec);
-/*! \brief Generate message waiting indicator
- * \param active The message indicator state
+/*! \brief Generate message waiting indicator
+ * \param active The message indicator state
* -- either 0 no messages in mailbox or 1 messages in mailbox
- * \param type Format of message (any of CID_MWI_TYPE_*)
- * \see callerid_generate() for more info as it use the same encoding
+ * \param type Format of message (any of CID_MWI_TYPE_*)
+ * \see callerid_generate() for more info as it use the same encoding
+ * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
*/
int vmwi_generate(unsigned char *buf, int active, int type, int codec, const char *name,
const char *number, int flags);
Modified: trunk/include/asterisk/channel.h
URL: http://svn.digium.com/svn-view/asterisk/trunk/include/asterisk/channel.h?view=diff&rev=180719&r1=180718&r2=180719
==============================================================================
--- trunk/include/asterisk/channel.h (original)
+++ trunk/include/asterisk/channel.h Mon Mar 9 15:58:17 2009
@@ -28,7 +28,7 @@
A phone call through Asterisk consists of an incoming
connection and an outbound connection. Each call comes
in through a channel driver that supports one technology,
- like SIP, DAHDI, IAX2 etc.
+ like SIP, DAHDI, IAX2 etc.
\par
Each channel driver, technology, has it's own private
channel or dialog structure, that is technology-dependent.
@@ -38,13 +38,13 @@
\par Call scenario
This happens when an incoming call arrives to Asterisk
-# Call arrives on a channel driver interface
- -# Channel driver creates a PBX channel and starts a
+ -# Channel driver creates a PBX channel and starts a
pbx thread on the channel
-# The dial plan is executed
-# At this point at least two things can happen:
- -# The call is answered by Asterisk and
+ -# The call is answered by Asterisk and
Asterisk plays a media stream or reads media
- -# The dial plan forces Asterisk to create an outbound
+ -# The dial plan forces Asterisk to create an outbound
call somewhere with the dial (see \ref app_dial.c)
application
.
@@ -67,14 +67,14 @@
Asterisk in order to be able to provide a proper CDR record
for the call.
-
+
\par Masquerading channels
In some cases, a channel can masquerade itself into another
- channel. This happens frequently in call transfers, where
+ channel. This happens frequently in call transfers, where
a new channel takes over a channel that is already involved
in a call. The new channel sneaks in and takes over the bridge
and the old channel, now a zombie, is hung up.
-
+
\par Reference
\arg channel.c - generic functions
\arg channel.h - declarations of functions, flags and structures
@@ -86,11 +86,11 @@
*/
/*! \page Def_Bridge Asterisk Channel Bridges
- In Asterisk, there's several media bridges.
+ In Asterisk, there's several media bridges.
The Core bridge handles two channels (a "phone call") and bridge
them together.
-
+
The conference bridge (meetme) handles several channels simultaneously
with the support of an external timer (DAHDI timer). This is used
not only by the Conference application (meetme) but also by the
@@ -111,11 +111,11 @@
\li \see ast_channel_bridge()
\li \see app_meetme.c
\li \ref AstRTPbridge
- \li \see ast_rtp_bridge()
+ \li \see ast_rtp_bridge()
\li \ref Def_Channel
*/
-/*! \page AstFileDesc File descriptors
+/*! \page AstFileDesc File descriptors
Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
in the \ref ast_channel structure.
*/
@@ -173,7 +173,7 @@
typedef unsigned long long ast_group_t;
-/*! \todo Add an explanation of an Asterisk generator
+/*! \todo Add an explanation of an Asterisk generator
*/
struct ast_generator {
void *(*alloc)(struct ast_channel *chan, void *params);
@@ -191,7 +191,7 @@
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* Also, NULL and "" must be considered equivalent.
- *
+ *
* SIP and IAX2 has utf8 encoded Unicode caller ID names.
* In some cases, we also have an alternative (RPID) E.164 number that can be used
* as caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to pstn gateway).
@@ -214,8 +214,8 @@
int cid_tns; /*!< Callerid Transit Network Select */
};
-/*! \brief
- Structure to describe a channel "technology", ie a channel driver
+/*! \brief
+ Structure to describe a channel "technology", ie a channel driver
See for examples:
\arg chan_iax2.c - The Inter-Asterisk exchange protocol
\arg chan_sip.c - The SIP channel driver
@@ -223,7 +223,7 @@
If you develop your own channel driver, this is where you
tell the PBX at registration of your driver what properties
- this driver supports and where different callbacks are
+ this driver supports and where different callbacks are
implemented.
*/
struct ast_channel_tech {
@@ -239,17 +239,17 @@
int (* const devicestate)(void *data); /*!< Devicestate call back */
- /*!
- * \brief Start sending a literal DTMF digit
+ /*!
+ * \brief Start sending a literal DTMF digit
*
- * \note The channel is not locked when this function gets called.
+ * \note The channel is not locked when this function gets called.
*/
int (* const send_digit_begin)(struct ast_channel *chan, char digit);
- /*!
- * \brief Stop sending a literal DTMF digit
+ /*!
+ * \brief Stop sending a literal DTMF digit
*
- * \note The channel is not locked when this function gets called.
+ * \note The channel is not locked when this function gets called.
*/
int (* const send_digit_end)(struct ast_channel *chan, char digit, unsigned int duration);
@@ -320,7 +320,7 @@
/*! \brief Retrieve base channel (agent and local) */
struct ast_channel* (* get_base_channel)(struct ast_channel *chan);
-
+
/*! \brief Set base channel (agent and local) */
int (* set_base_channel)(struct ast_channel *chan, struct ast_channel *base);
@@ -353,7 +353,7 @@
AST_ADSI_OFFHOOKONLY,
};
-/*!
+/*!
* \brief ast_channel states
*
* \note Bits 0-15 of state are reserved for the state (up/down) of the line
@@ -385,7 +385,7 @@
T38_STATE_NEGOTIATED, /*!< T38 established */
};
-/*! \brief Main Channel structure associated with a channel.
+/*! \brief Main Channel structure associated with a channel.
* This is the side of it mostly used by the pbx and call management.
*
* \note XXX It is important to remember to increment .cleancount each time
@@ -441,7 +441,7 @@
AST_STRING_FIELD(parkinglot); /*! Default parking lot, if empty, default parking lot */
AST_STRING_FIELD(dialcontext); /*!< Dial: Extension context that we were called from */
);
-
+
struct timeval whentohangup; /*!< Non-zero, set to actual time when channel is to be hung up */
pthread_t blocker; /*!< If anyone is blocking, this is them */
[... 3234 lines stripped ...]
More information about the svn-commits
mailing list