[svn-commits] rmudgett: branch rmudgett/misdn_facility r180786 - in /team/rmudgett/misdn_fa...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Mon Mar 9 18:34:53 CDT 2009
Author: rmudgett
Date: Mon Mar 9 18:34:48 2009
New Revision: 180786
URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=180786
Log:
Merged revisions 180748,180762,180785 via svnmerge from
https://origsvn.digium.com/svn/asterisk/team/group/issue8824
................
r180748 | mmichelson | 2009-03-09 16:42:03 -0500 (Mon, 09 Mar 2009) | 3 lines
Resolve conflicts. Reset automerge. Feed me a steak.
................
r180762 | root | 2009-03-09 17:19:14 -0500 (Mon, 09 Mar 2009) | 11 lines
Merged revisions 180750 via svnmerge from
file:///srv/subversion/repos/asterisk/trunk
........
r180750 | russell | 2009-03-09 17:00:42 -0500 (Mon, 09 Mar 2009) | 4 lines
Add current mentors list, and first pass on a project list broken out of "PineMango"
I will work on adding projects that have been sent to be via email tomorrow.
........
................
r180785 | rmudgett | 2009-03-09 18:31:43 -0500 (Mon, 09 Mar 2009) | 1 line
Better conflict resolution plus some other comment changes
................
Modified:
team/rmudgett/misdn_facility/ (props changed)
team/rmudgett/misdn_facility/doc/google-soc2009-ideas.txt
team/rmudgett/misdn_facility/include/asterisk/app.h
team/rmudgett/misdn_facility/include/asterisk/astobj2.h
team/rmudgett/misdn_facility/include/asterisk/audiohook.h
team/rmudgett/misdn_facility/include/asterisk/callerid.h
team/rmudgett/misdn_facility/include/asterisk/channel.h
team/rmudgett/misdn_facility/include/asterisk/config.h
team/rmudgett/misdn_facility/include/asterisk/datastore.h
team/rmudgett/misdn_facility/include/asterisk/devicestate.h
team/rmudgett/misdn_facility/include/asterisk/dlinkedlists.h
team/rmudgett/misdn_facility/include/asterisk/dnsmgr.h
team/rmudgett/misdn_facility/include/asterisk/doxyref.h
team/rmudgett/misdn_facility/include/asterisk/dsp.h
team/rmudgett/misdn_facility/include/asterisk/enum.h
team/rmudgett/misdn_facility/include/asterisk/event.h
team/rmudgett/misdn_facility/include/asterisk/extconf.h
team/rmudgett/misdn_facility/include/asterisk/heap.h
team/rmudgett/misdn_facility/include/asterisk/http.h
team/rmudgett/misdn_facility/include/asterisk/linkedlists.h
team/rmudgett/misdn_facility/include/asterisk/lock.h
team/rmudgett/misdn_facility/include/asterisk/logger.h
team/rmudgett/misdn_facility/include/asterisk/manager.h
team/rmudgett/misdn_facility/include/asterisk/pbx.h
team/rmudgett/misdn_facility/include/asterisk/res_odbc.h
team/rmudgett/misdn_facility/include/asterisk/rtp.h
team/rmudgett/misdn_facility/include/asterisk/sched.h
team/rmudgett/misdn_facility/include/asterisk/taskprocessor.h
team/rmudgett/misdn_facility/include/asterisk/tcptls.h
team/rmudgett/misdn_facility/include/asterisk/timing.h
team/rmudgett/misdn_facility/include/asterisk/udptl.h
team/rmudgett/misdn_facility/include/asterisk/utils.h
team/rmudgett/misdn_facility/main/devicestate.c
team/rmudgett/misdn_facility/main/enum.c
team/rmudgett/misdn_facility/main/tcptls.c
Propchange: team/rmudgett/misdn_facility/
------------------------------------------------------------------------------
automerge = *
Propchange: team/rmudgett/misdn_facility/
------------------------------------------------------------------------------
--- misdn-facility (original)
+++ misdn-facility Mon Mar 9 18:34:48 2009
@@ -1,1 +1,1 @@
-/team/group/issue8824:1-180741
+/team/group/issue8824:1-180785
Propchange: team/rmudgett/misdn_facility/
------------------------------------------------------------------------------
--- svnmerge-integrated (original)
+++ svnmerge-integrated Mon Mar 9 18:34:48 2009
@@ -1,1 +1,1 @@
-/trunk:1-180693
+/trunk:1-180761
Modified: team/rmudgett/misdn_facility/doc/google-soc2009-ideas.txt
URL: http://svn.digium.com/svn-view/asterisk/team/rmudgett/misdn_facility/doc/google-soc2009-ideas.txt?view=diff&rev=180786&r1=180785&r2=180786
==============================================================================
--- team/rmudgett/misdn_facility/doc/google-soc2009-ideas.txt (original)
+++ team/rmudgett/misdn_facility/doc/google-soc2009-ideas.txt Mon Mar 9 18:34:48 2009
@@ -1,13 +1,116 @@
================================================================================
=== Google Summer of Code 2009 ===
-=== Project Ideas ===
=== ===
=== http://www.asterisk.org/ ===
=== ===
=== <asteriskteam at digium.com> ===
================================================================================
-...
+--------------------------------------------------------------------------------
+--- Personnel ------------------------------------------------------------------
+--------------------------------------------------------------------------------
+
+Administrator: Russell Bryant
+
+Mentors: Russell Bryant
+ Joshua Colp
+ Mark Michelson
+ Tilghman Lesher
+ Luigi Rizzo
+
+--------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
+
+--------------------------------------------------------------------------------
+--- Project Ideas --------------------------------------------------------------
+--------------------------------------------------------------------------------
+
+Project difficulty is listed on a 1 through 5 scale. A 1 would be a project
+appropriate for a college student with familiarity with C programming, but no
+experience with the Asterisk code base, or even Asterisk itself. A project with
+a difficulty of 5 would be something appropriate for a student that already has
+significant experience with the Asterisk code base.
+
+1) There are a number of projects that fall into the category of improving and
+ creating new interfaces for developers to interface with Asterisk. To get a
+ bit of an idea for the higher level vision of this effort, see the following
+ wiki page: <http://astridevcon.pbwiki.com/Codename-Pinemango/>.
+
+ Some insight regarding the motivation for this overall effort is captured
+ in this mailing list post, written by Brian Degenhardt.
+
+ - http://lists.digium.com/pipermail/asterisk-dev/2008-October/034700.html
+
+ Specific project ideas in this area are listed here:
+
+
+ a) Create a generic "data get" layer for Asterisk components to be able to
+ expose data that they maintain. Currently, modules implement specific
+ code to implement CLI commands, manager interface actions, and so forth,
+ while it would be much nicer to have this data available through a common
+ interface. For example, SNMP support has been added to Asterisk but is
+ limited in what it can expose due to the lack of this interface. This
+ project would be to create the infrastructure for this data layer and some
+ uses to prove its functionality. Then, various parts of Asterisk could
+ be converted as time permits. Note that this may end up sharing some code
+ with the "data put" interface in part b.
+
+ Difficulty - 2
+ Mentor - TBD
+
+ b) Create a generic "data put" layer for Asterisk components to allow
+ external interfaces to update configuration items, as opposed to having
+ to issue a full configuration reload to account for a single change.
+ This project would involve writing the infrastructure and some basic usage
+ to prove its functionality. Various parts of Asterisk could be converted
+ as time permits. Note that this may end up sharing some code with the
+ "data get" interface in part a.
+
+ Difficulty - 2
+ Mentor - TBD
+
+ c) Improve the performance of cache handling in the event core. The event
+ API in Asterisk provides a generic interface for subscribing to and
+ publishing asynchronous events. It also provides a caching mechanism for
+ events that represent state changes. So, to find out a state, you can
+ pull it out of the event cache. For example, the state of devices as used
+ for presence is handled using this mechanism. The data structures
+ currently used for maintaining the cache are not optimal for performance
+ when the cache gets large. This project would be to write code to
+ benchmark the performance of the caching mechanism, and then implement a
+ new storage mechanism that is more efficient.
+
+ Difficulty - 3
+ Mentor - TBD
+
+ d) Develop a method for federating Asterisk servers using distributed events
+ with a transport suitable for communication beyond a LAN. The current
+ event infrastructure includes ways to hook in and distribute events
+ between servers. There is a module which implements this, res_ais, but
+ it is only suitable for federating servers on a high speed LAN. This
+ project would be to implement a new event distribution module using a
+ protocol such as XMPP, or something else if deemed appropriate.
+
+ Difficulty - 2
+ Mentor - TBD
+
+ e) Implement a method that makes it very easy to add synchronous hooks
+ throughout the code base. Hooks are arbitrary callbacks within the
+ internals of asterisk where external components can modify asterisk's
+ behavior. While the dialplan allows applications to control much of the
+ asterisk behavior, hooks allow for business logic to be applied to
+ situations that are not associated with a call (eg: a sip registration
+ hook could allow time-goverened registration period), or for situations
+ that occur during the execution of a diaplan application (eg: codec
+ negotiation hook to apply business logic to codecs proposed in the middle
+ of a Dial command, or a transfer hook to execute business logic when a
+ SIP REINVITE is received).
+
+ Difficulty - 3
+ Mentor - TBD
+
+--------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
================================================================================
================================================================================
Modified: team/rmudgett/misdn_facility/include/asterisk/app.h
URL: http://svn.digium.com/svn-view/asterisk/team/rmudgett/misdn_facility/include/asterisk/app.h?view=diff&rev=180786&r1=180785&r2=180786
==============================================================================
--- team/rmudgett/misdn_facility/include/asterisk/app.h (original)
+++ team/rmudgett/misdn_facility/include/asterisk/app.h Mon Mar 9 18:34:48 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: team/rmudgett/misdn_facility/include/asterisk/astobj2.h
URL: http://svn.digium.com/svn-view/asterisk/team/rmudgett/misdn_facility/include/asterisk/astobj2.h?view=diff&rev=180786&r1=180785&r2=180786
==============================================================================
--- team/rmudgett/misdn_facility/include/asterisk/astobj2.h (original)
+++ team/rmudgett/misdn_facility/include/asterisk/astobj2.h Mon Mar 9 18:34:48 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: team/rmudgett/misdn_facility/include/asterisk/audiohook.h
URL: http://svn.digium.com/svn-view/asterisk/team/rmudgett/misdn_facility/include/asterisk/audiohook.h?view=diff&rev=180786&r1=180785&r2=180786
==============================================================================
--- team/rmudgett/misdn_facility/include/asterisk/audiohook.h (original)
+++ team/rmudgett/misdn_facility/include/asterisk/audiohook.h Mon Mar 9 18:34:48 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
+/*!
[... 3358 lines stripped ...]
More information about the svn-commits
mailing list