aboutsummaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorjpeeler <jpeeler@f38db490-d61c-443f-a65b-d21fe96a405b>2009-03-09 21:22:42 +0000
committerjpeeler <jpeeler@f38db490-d61c-443f-a65b-d21fe96a405b>2009-03-09 21:22:42 +0000
commit3bdae19e24bf719ce75e2e4096ed9fe740c43335 (patch)
tree0719180d62267806e4f017648b09f46f0defcb4d /include
parentd815e15aad47d9fb7c053b59babcbdd4bd2d2d5e (diff)
Merged revisions 180719 via svnmerge from
https://origsvn.digium.com/svn/asterisk/trunk ........ r180719 | jpeeler | 2009-03-09 15:58:17 -0500 (Mon, 09 Mar 2009) | 16 lines 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/ ........ git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.6.1@180740 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'include')
-rw-r--r--include/asterisk/app.h88
-rw-r--r--include/asterisk/astobj2.h128
-rw-r--r--include/asterisk/audiohook.h18
-rw-r--r--include/asterisk/callerid.h13
-rw-r--r--include/asterisk/channel.h289
-rw-r--r--include/asterisk/config.h69
-rw-r--r--include/asterisk/datastore.h7
-rw-r--r--include/asterisk/devicestate.h79
-rw-r--r--include/asterisk/dlinkedlists.h61
-rw-r--r--include/asterisk/dnsmgr.h4
-rw-r--r--include/asterisk/doxyref.h28
-rw-r--r--include/asterisk/dsp.h36
-rw-r--r--include/asterisk/enum.h27
-rw-r--r--include/asterisk/event.h91
-rw-r--r--include/asterisk/extconf.h26
-rw-r--r--include/asterisk/heap.h19
-rw-r--r--include/asterisk/http.h15
-rw-r--r--include/asterisk/linkedlists.h11
-rw-r--r--include/asterisk/lock.h61
-rw-r--r--include/asterisk/logger.h20
-rw-r--r--include/asterisk/manager.h3
-rw-r--r--include/asterisk/pbx.h4
-rw-r--r--include/asterisk/res_odbc.h3
-rw-r--r--include/asterisk/rtp.h17
-rw-r--r--include/asterisk/sched.h25
-rw-r--r--include/asterisk/taskprocessor.h16
-rw-r--r--include/asterisk/tcptls.h17
-rw-r--r--include/asterisk/timing.h10
-rw-r--r--include/asterisk/udptl.h3
-rw-r--r--include/asterisk/utils.h4
30 files changed, 774 insertions, 418 deletions
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 4951169ec..a34a8eec5 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -32,7 +32,7 @@ extern "C" {
/* 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);
@@ -52,8 +52,8 @@ typedef enum {
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"
@@ -64,7 +64,7 @@ typedef enum {
struct ast_ivr_option {
char *option;
ast_ivr_action action;
- void *adata;
+ void *adata;
};
struct ast_ivr_menu {
@@ -78,13 +78,13 @@ struct ast_ivr_menu {
#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 "&".
@@ -93,8 +93,8 @@ int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbd
* \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.
*/
@@ -103,6 +103,14 @@ int ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxl
/*! \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),
@@ -117,16 +125,31 @@ int ast_app_has_voicemail(const char *mailbox, const char *folder);
/*! \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);
@@ -174,13 +197,13 @@ int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const ch
/*! \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
+ * \param fwd, rev, stop, pause, restart, skipms, offsetms
*
- * Before calling this function, set this to be the number
+ * 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.
@@ -192,15 +215,15 @@ int ast_play_and_wait(struct ast_channel *chan, const char *fn);
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);
@@ -333,7 +356,7 @@ int ast_app_group_list_unlock(void);
*/
#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
@@ -346,7 +369,7 @@ int ast_app_group_list_unlock(void);
*/
#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)
@@ -504,13 +527,24 @@ int ast_get_encoded_str(const char *stream, char *result, size_t result_size);
/*! \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)
diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index 1311b3fe8..82ced0d5a 100644
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -19,7 +19,7 @@
#include "asterisk/compat.h"
-/*! \file
+/*! \file
* \ref AstObj2
*
* \page AstObj2 Object Model implementing objects and containers.
@@ -46,9 +46,9 @@ locks.
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 @@ On return from ao2_alloc():
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 @@ list. However there is no ordering among elements.
/*
\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_ref(arg1,arg2,arg3)
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 @@ These lines look like this:
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 @@ static struct sip_pvt *dialog_unref(struct sip_pvt *p, char *tag)
#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 @@ all the objects, or you can use "util/refcounter" to scan the file
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 @@ THE ART OF REFERENCE COUNTING
(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 @@ doing useless increments and decrements of the ref counts.
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 @@ Example:
}
...
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 @@ typedef void (*ao2_destructor_fn)(void *);
/*! \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 @@ int _ao2_ref(void *o, int delta);
/*! \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 @@ int _ao2_lock(void *a, const char *file, const char *func, int line, const char
/*! \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);
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
+/*!
+ * \brief Return the lock address of an object
*
- * \param a A pointer to the object we want.
+ * \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 @@ Operations on container include:
- \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 @@ Operations on container include:
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 @@ Operations on container include:
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 @@ Operations on container include:
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 @@ Operations on container include:
- \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.
@@ -649,22 +651,22 @@ enum search_flags {
*/
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.
*
@@ -681,7 +683,7 @@ struct ao2_container;
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
@@ -693,7 +695,7 @@ int ao2_container_count(struct ao2_container *c);
/*! \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.
*/
/*@{ */
@@ -738,7 +740,7 @@ void *_ao2_link(struct ao2_container *c, void *newobj);
* 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
@@ -762,7 +764,7 @@ struct ao2_list {
/*! \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
@@ -778,8 +780,8 @@ struct ao2_list {
* \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:
@@ -788,7 +790,7 @@ struct ao2_list {
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.
*
@@ -810,13 +812,13 @@ struct ao2_list {
* 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:
@@ -830,7 +832,7 @@ struct ao2_list {
* 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
@@ -844,8 +846,8 @@ struct ao2_list {
#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,
- char *file, int line, const char *funcname);
+ 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,
ao2_callback_fn *cb_fn, void *arg);
@@ -868,7 +870,7 @@ void *_ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
*
* 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
@@ -883,7 +885,7 @@ void *_ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
* 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.
*
@@ -912,7 +914,7 @@ void *_ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
*
*/
-/*! \brief
+/*! \brief
* The Astobj2 iterator
*
* \note You are not supposed to know the internals of an iterator!
@@ -954,7 +956,7 @@ struct ao2_iterator {
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 */
diff --git a/include/asterisk/audiohook.h b/include/asterisk/audiohook.h
index acda0a652..1012822b4 100644
--- a/include/asterisk/audiohook.h
+++ b/include/asterisk/audiohook.h
@@ -165,7 +165,7 @@ int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
*/
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 @@ void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
/*!
\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 @@ int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, cons
*/
#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);
diff --git a/include/asterisk/callerid.h b/include/asterisk/callerid.h
index 45272e01a..6177546d9 100644
--- a/include/asterisk/callerid.h
+++ b/include/asterisk/callerid.h
@@ -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 @@ void callerid_free(struct callerid_state *cid);
*/
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);
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 9540776e5..99264bfec 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -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 @@ References:
\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 @@ enum ast_bridge_result {
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 @@ struct ast_generator {
* \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 @@ struct ast_callerid {
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 @@ struct ast_callerid {
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 @@ struct ast_channel_tech {
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 @@ struct ast_channel_tech {
/*! \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 @@ enum ast_channel_adsicpe {
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 @@ enum ast_t38_state {
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 @@ struct ast_channel {
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 */
ast_mutex_t lock_dont_use; /*!< Lock a channel for some operations. See ast_channel_lock() */
@@ -506,10 +506,10 @@ struct ast_channel {
/*! \brief ast_channel_tech Properties */
enum {
- /*! \brief Channels have this property if they can accept input with jitter;
+ /*! \brief Channels have this property if they can accept input with jitter;
* i.e. most VoIP channels */
AST_CHAN_TP_WANTSJITTER = (1 << 0),
- /*! \brief Channels have this property if they can create jitter;
+ /*! \brief Channels have this property if they can create jitter;
* i.e. most VoIP channels */
AST_CHAN_TP_CREATESJITTER = (1 << 1),
};
@@ -540,7 +540,7 @@ enum {
AST_FLAG_OUTGOING = (1 << 10),
/*! A DTMF_BEGIN frame has been read from this channel, but not yet an END */
AST_FLAG_IN_DTMF = (1 << 12),
- /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
+ /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
* currently being emulated */
AST_FLAG_EMULATE_DTMF = (1 << 13),
/*! This is set to tell the channel not to generate DTMF begin frames, and
@@ -556,7 +556,7 @@ enum {
* a message aimed at preventing a subsequent hangup exten being run at the pbx_run
* level */
AST_FLAG_BRIDGE_HANGUP_RUN = (1 << 17),
- /*! This flag indicates that the hangup exten should NOT be run when the
+ /*! This flag indicates that the hangup exten should NOT be run when the
* bridge terminates, this will allow the hangup in the pbx loop to be run instead.
* */
AST_FLAG_BRIDGE_HANGUP_DONT = (1 << 18),
@@ -639,15 +639,16 @@ enum channelreloadreason {
CHANNEL_MANAGER_RELOAD,
};
-/*!
+/*!
* \note None of the datastore API calls lock the ast_channel they are using.
* So, the channel should be locked before calling the functions that
* take a channel argument.
*/
-/*!
+/*!
* \brief Create a channel data store object
* \deprecated You should use the ast_datastore_alloc() generic function instead.
+ * \version 1.6.1 deprecated
*/
struct ast_datastore *ast_channel_datastore_alloc(const struct ast_datastore_info *info, const char *uid)
__attribute__((deprecated));
@@ -655,6 +656,7 @@ struct ast_datastore *ast_channel_datastore_alloc(const struct ast_datastore_inf
/*!
* \brief Free a channel data store object
* \deprecated You should use the ast_datastore_free() generic function instead.
+ * \version 1.6.1 deprecated
*/
int ast_channel_datastore_free(struct ast_datastore *datastore)
__attribute__((deprecated));
@@ -662,8 +664,8 @@ int ast_channel_datastore_free(struct ast_datastore *datastore)
/*! \brief Inherit datastores from a parent to a child. */
int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *to);
-/*!
- * \brief Add a datastore to a channel
+/*!
+ * \brief Add a datastore to a channel
*
* \note The channel should be locked before calling this function.
*
@@ -673,8 +675,8 @@ int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *
int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore);
-/*!
- * \brief Remove a datastore from a channel
+/*!
+ * \brief Remove a datastore from a channel
*
* \note The channel should be locked before calling this function.
*
@@ -683,8 +685,8 @@ int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *da
*/
int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore);
-/*!
- * \brief Find a datastore on a channel
+/*!
+ * \brief Find a datastore on a channel
*
* \note The channel should be locked before calling this function.
*
@@ -699,8 +701,8 @@ struct ast_datastore *ast_channel_datastore_find(struct ast_channel *chan, const
/*! \brief Change the state of a channel */
int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
-/*!
- * \brief Create a channel structure
+/*!
+ * \brief Create a channel structure
*
* \retval NULL failure
* \retval non-NULL successfully allocated channel
@@ -710,8 +712,8 @@ int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
*/
struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...) __attribute__((format(printf, 9, 10)));
-/*!
- * \brief Queue an outgoing frame
+/*!
+ * \brief Queue an outgoing frame
*
* \note The channel does not need to be locked before calling this function.
*/
@@ -731,19 +733,21 @@ int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
*/
int ast_queue_frame_head(struct ast_channel *chan, struct ast_frame *f);
-/*!
- * \brief Queue a hangup frame
+/*!
+ * \brief Queue a hangup frame
*
* \note The channel does not need to be locked before calling this function.
*/
int ast_queue_hangup(struct ast_channel *chan);
-/*!
+/*!
* \brief Queue a hangup frame with hangupcause set
*
* \note The channel does not need to be locked before calling this function.
- * \param chan channel to queue frame onto
- * \param cause the hangup cause
+ * \param[in] chan channel to queue frame onto
+ * \param[in] cause the hangup cause
+ * \return 0 on success, -1 on error
+ * \since 1.6.1
*/
int ast_queue_hangup_with_cause(struct ast_channel *chan, int cause);
@@ -787,8 +791,8 @@ int ast_queue_control(struct ast_channel *chan, enum ast_control_frame_type cont
int ast_queue_control_data(struct ast_channel *chan, enum ast_control_frame_type control,
const void *data, size_t datalen);
-/*!
- * \brief Change channel name
+/*!
+ * \brief Change channel name
*
* \note The channel must be locked before calling this function.
*/
@@ -797,15 +801,15 @@ void ast_change_name(struct ast_channel *chan, char *newname);
/*! \brief Free a channel structure */
void ast_channel_free(struct ast_channel *);
-/*!
- * \brief Requests a channel
+/*!
+ * \brief Requests a channel
*
* \param type type of channel to request
* \param format requested channel format (codec)
* \param data data to pass to the channel requester
* \param status status
*
- * Request a channel of a given type, with data as optional information used
+ * Request a channel of a given type, with data as optional information used
* by the low level module
*
* \retval NULL failure
@@ -814,7 +818,7 @@ void ast_channel_free(struct ast_channel *);
struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
/*!
- * \brief Request a channel of a given type, with data as optional information used
+ * \brief Request a channel of a given type, with data as optional information used
* by the low level module and attempt to place a call on it
*
* \param type type of channel to request
@@ -832,7 +836,7 @@ struct ast_channel *ast_request_and_dial(const char *type, int format, void *dat
int timeout, int *reason, const char *cid_num, const char *cid_name);
/*!
- * \brief Request a channel of a given type, with data as optional information used
+ * \brief Request a channel of a given type, with data as optional information used
* by the low level module and attempt to place a call on it
* \param type type of channel to request
* \param format requested channel format
@@ -855,7 +859,7 @@ struct ast_channel *__ast_request_and_dial(const char *type, int format, void *d
*/
int ast_channel_register(const struct ast_channel_tech *tech);
-/*! \brief Unregister a channel technology
+/*! \brief Unregister a channel technology
* \param tech Structure defining channel technology or "type" that was previously registered
* \return No return value.
*/
@@ -895,7 +899,7 @@ int ast_channel_trace_is_enabled(struct ast_channel *chan);
int ast_channel_trace_serialize(struct ast_channel *chan, struct ast_str **out);
#endif
-/*! \brief Hang up a channel
+/*! \brief Hang up a channel
* \note This function performs a hard hangup on a channel. Unlike the soft-hangup, this function
* performs all stream stopping, etc, on the channel that needs to end.
* chan is no longer valid after this call.
@@ -904,13 +908,13 @@ int ast_channel_trace_serialize(struct ast_channel *chan, struct ast_str **out);
*/
int ast_hangup(struct ast_channel *chan);
-/*!
- * \brief Softly hangup up a channel
+/*!
+ * \brief Softly hangup up a channel
*
* \param chan channel to be soft-hung-up
* \param cause Ast hangupcause for hangup
*
- * Call the protocol layer, but don't destroy the channel structure
+ * Call the protocol layer, but don't destroy the channel structure
* (use this if you are trying to
* safely hangup a channel managed by another thread.
*
@@ -920,34 +924,49 @@ int ast_hangup(struct ast_channel *chan);
*/
int ast_softhangup(struct ast_channel *chan, int cause);
-/*! \brief Softly hangup up a channel (no channel lock)
+/*! \brief Softly hangup up a channel (no channel lock)
* \param chan channel to be soft-hung-up
* \param cause Ast hangupcause for hangup (see cause.h) */
int ast_softhangup_nolock(struct ast_channel *chan, int cause);
-/*! \brief Check to see if a channel is needing hang up
+/*! \brief Check to see if a channel is needing hang up
* \param chan channel on which to check for hang up
* This function determines if the channel is being requested to be hung up.
* \return Returns 0 if not, or 1 if hang up is requested (including time-out).
*/
int ast_check_hangup(struct ast_channel *chan);
-/*! \brief Compare a offset with the settings of when to hang a channel up
+/*!
+ * \brief Compare a offset with the settings of when to hang a channel up
* \param chan channel on which to check for hang up
- * \param offset offset in seconds and useconds from current time
+ * \param offset offset in seconds from current time
* \return 1, 0, or -1
- * This function compares a offset from current time with the absolute time
+ * This function compares a offset from current time with the absolute time
* out on a channel (when to hang up). If the absolute time out on a channel
* is earlier than current time plus the offset, it returns 1, if the two
* time values are equal, it return 0, otherwise, it return -1.
+ * \sa ast_channel_cmpwhentohangup_tv()
+ * \version 1.6.1 deprecated function (only had seconds precision)
*/
int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset) __attribute__((deprecated));
+
+/*!
+ * \brief Compare a offset with the settings of when to hang a channel up
+ * \param chan channel on which to check for hangup
+ * \param offset offset in seconds and microseconds from current time
+ * \return 1, 0, or -1
+ * This function compares a offset from current time with the absolute time
+ * out on a channel (when to hang up). If the absolute time out on a channel
+ * is earlier than current time plus the offset, it returns 1, if the two
+ * time values are equal, it return 0, otherwise, it return -1.
+ * \since 1.6.1
+ */
int ast_channel_cmpwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
-/*! \brief Set when to hang a channel up
+/*! \brief Set when to hang a channel up
*
* \param chan channel on which to check for hang up
- * \param offset offset in seconds and useconds relative to the current time of when to hang up
+ * \param offset offset in seconds relative to the current time of when to hang up
*
* This function sets the absolute time out on a channel (when to hang up).
*
@@ -955,13 +974,29 @@ int ast_channel_cmpwhentohangup_tv(struct ast_channel *chan, struct timeval offs
* calling it.
*
* \return Nothing
+ * \sa ast_channel_setwhentohangup_tv()
+ * \version 1.6.1 deprecated function (only had seconds precision)
*/
void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset) __attribute__((deprecated));
+
+/*! \brief Set when to hang a channel up
+ *
+ * \param chan channel on which to check for hang up
+ * \param offset offset in seconds and useconds relative to the current time of when to hang up
+ *
+ * This function sets the absolute time out on a channel (when to hang up).
+ *
+ * \note This function does not require that the channel is locked before
+ * calling it.
+ *
+ * \return Nothing
+ * \since 1.6.1
+ */
void ast_channel_setwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
-/*!
+/*!
* \brief Answer a channel
- *
+ *
* \param chan channel to answer
*
* This function answers a channel and handles all necessary call
@@ -975,18 +1010,18 @@ void ast_channel_setwhentohangup_tv(struct ast_channel *chan, struct timeval off
int ast_answer(struct ast_channel *chan);
int __ast_answer(struct ast_channel *chan, unsigned int delay, int cdr_answer);
-/*! \brief Make a call
+/*! \brief Make a call
* \param chan which channel to make the call on
* \param addr destination of the call
* \param timeout time to wait on for connect
- * Place a call, take no longer than timeout ms.
- \return Returns -1 on failure, 0 on not enough time
- (does not automatically stop ringing), and
+ * Place a call, take no longer than timeout ms.
+ \return Returns -1 on failure, 0 on not enough time
+ (does not automatically stop ringing), and
the number of seconds the connect took otherwise.
*/
int ast_call(struct ast_channel *chan, char *addr, int timeout);
-/*! \brief Indicates condition of channel
+/*! \brief Indicates condition of channel
* \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
* \param chan channel to change the indication
* \param condition which condition to indicate on the channel
@@ -1006,14 +1041,14 @@ int ast_indicate_data(struct ast_channel *chan, int condition, const void *data,
/* Misc stuff ------------------------------------------------ */
-/*! \brief Wait for input on a channel
+/*! \brief Wait for input on a channel
* \param chan channel to wait on
* \param ms length of time to wait on the channel
- * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
+ * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
\return Returns < 0 on failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
int ast_waitfor(struct ast_channel *chan, int ms);
-/*! \brief Wait for a specified amount of time, looking for hangups
+/*! \brief Wait for a specified amount of time, looking for hangups
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
* Waits for a specified amount of time, servicing the channel as required.
@@ -1021,7 +1056,7 @@ int ast_waitfor(struct ast_channel *chan, int ms);
*/
int ast_safe_sleep(struct ast_channel *chan, int ms);
-/*! \brief Wait for a specified amount of time, looking for hangups and a condition argument
+/*! \brief Wait for a specified amount of time, looking for hangups and a condition argument
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
* \param cond a function pointer for testing continue condition
@@ -1032,7 +1067,7 @@ int ast_safe_sleep(struct ast_channel *chan, int ms);
*/
int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
-/*! \brief Waits for activity on a group of channels
+/*! \brief Waits for activity on a group of channels
* \param chan an array of pointers to channels
* \param n number of channels that are to be waited upon
* \param fds an array of fds to wait upon
@@ -1049,8 +1084,8 @@ struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n,
int *fds, int nfds, int *exception, int *outfd, int *ms);
/*! \brief Waits for input on a group of channels
- Wait for input on an array of channels for a given # of milliseconds.
- \return Return channel with activity, or NULL if none has activity.
+ Wait for input on an array of channels for a given # of milliseconds.
+ \return Return channel with activity, or NULL if none has activity.
\param chan an array of pointers to channels
\param n number of channels that are to be waited upon
\param ms time "ms" is modified in-place, if applicable */
@@ -1068,16 +1103,16 @@ int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
disconnected. */
struct ast_frame *ast_read(struct ast_channel *chan);
-/*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
+/*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
\param chan channel to read a frame from
\return Returns a frame, or NULL on error. If it returns NULL, you
best just stop reading frames and assume the channel has been
- disconnected.
- \note Audio is replaced with AST_FRAME_NULL to avoid
+ disconnected.
+ \note Audio is replaced with AST_FRAME_NULL to avoid
transcode when the resulting audio is not necessary. */
struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
-/*! \brief Write a frame to a channel
+/*! \brief Write a frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1085,7 +1120,7 @@ struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
*/
int ast_write(struct ast_channel *chan, struct ast_frame *frame);
-/*! \brief Write video frame to a channel
+/*! \brief Write video frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1093,7 +1128,7 @@ int ast_write(struct ast_channel *chan, struct ast_frame *frame);
*/
int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
-/*! \brief Write text frame to a channel
+/*! \brief Write text frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1105,7 +1140,7 @@ int ast_write_text(struct ast_channel *chan, struct ast_frame *frame);
int ast_prod(struct ast_channel *chan);
/*! \brief Sets read format on channel chan
- * Set read format for channel to whichever component of "format" is best.
+ * Set read format for channel to whichever component of "format" is best.
* \param chan channel to change
* \param format format to change to
* \return Returns 0 on success, -1 on failure
@@ -1113,15 +1148,15 @@ int ast_prod(struct ast_channel *chan);
int ast_set_read_format(struct ast_channel *chan, int format);
/*! \brief Sets write format on channel chan
- * Set write format for channel to whichever component of "format" is best.
+ * Set write format for channel to whichever component of "format" is best.
* \param chan channel to change
* \param format new format for writing
* \return Returns 0 on success, -1 on failure
*/
int ast_set_write_format(struct ast_channel *chan, int format);
-/*!
- * \brief Sends text to a channel
+/*!
+ * \brief Sends text to a channel
*
* \param chan channel to act upon
* \param text string of text to send on the channel
@@ -1130,7 +1165,7 @@ int ast_set_write_format(struct ast_channel *chan, int format);
*
* \note The channel does not need to be locked before calling this function.
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*/
int ast_sendtext(struct ast_channel *chan, const char *text);
@@ -1179,7 +1214,7 @@ int ast_senddigit_end(struct ast_channel *chan, char digit, unsigned int duratio
char *ast_recvtext(struct ast_channel *chan, int timeout);
/*! \brief Browse channels in use
- * Browse the channels currently in use
+ * Browse the channels currently in use
* \param prev where you want to start in the channel list
* \return Returns the next channel in the list, NULL on end.
* If it returns a channel, that channel *has been locked*!
@@ -1209,7 +1244,7 @@ struct ast_channel *ast_walk_channel_by_exten_locked(const struct ast_channel *c
int ast_waitfordigit(struct ast_channel *c, int ms);
/*! \brief Wait for a digit
- Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
+ Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
* \param c channel to wait for a digit on
* \param ms how many milliseconds to wait
* \param audiofd audio file descriptor to write to if audio frames are received
@@ -1217,37 +1252,37 @@ int ast_waitfordigit(struct ast_channel *c, int ms);
* \return Returns 1 if ctrlfd becomes available */
int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
-/*! Reads multiple digits
+/*! Reads multiple digits
* \param c channel to read from
* \param s string to read in to. Must be at least the size of your length
* \param len how many digits to read (maximum)
* \param timeout how long to timeout between digits
* \param rtimeout timeout to wait on the first digit
* \param enders digits to end the string
- * Read in a digit string "s", max length "len", maximum timeout between
+ * Read in a digit string "s", max length "len", maximum timeout between
digits "timeout" (-1 for none), terminated by anything in "enders". Give them rtimeout
for the first digit. Returns 0 on normal return, or 1 on a timeout. In the case of
- a timeout, any digits that were read before the timeout will still be available in s.
+ a timeout, any digits that were read before the timeout will still be available in s.
RETURNS 2 in full version when ctrlfd is available, NOT 1*/
int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
/*! \brief Report DTMF on channel 0 */
-#define AST_BRIDGE_DTMF_CHANNEL_0 (1 << 0)
+#define AST_BRIDGE_DTMF_CHANNEL_0 (1 << 0)
/*! \brief Report DTMF on channel 1 */
-#define AST_BRIDGE_DTMF_CHANNEL_1 (1 << 1)
+#define AST_BRIDGE_DTMF_CHANNEL_1 (1 << 1)
/*! \brief Return all voice frames on channel 0 */
-#define AST_BRIDGE_REC_CHANNEL_0 (1 << 2)
+#define AST_BRIDGE_REC_CHANNEL_0 (1 << 2)
/*! \brief Return all voice frames on channel 1 */
-#define AST_BRIDGE_REC_CHANNEL_1 (1 << 3)
+#define AST_BRIDGE_REC_CHANNEL_1 (1 << 3)
/*! \brief Ignore all signal frames except NULL */
-#define AST_BRIDGE_IGNORE_SIGS (1 << 4)
+#define AST_BRIDGE_IGNORE_SIGS (1 << 4)
-/*! \brief Makes two channel formats compatible
+/*! \brief Makes two channel formats compatible
* \param c0 first channel to make compatible
* \param c1 other channel to make compatible
- * Set two channels to compatible formats -- call before ast_channel_bridge in general .
+ * Set two channels to compatible formats -- call before ast_channel_bridge in general .
* \return Returns 0 on success and -1 if it could not be done */
int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
@@ -1258,7 +1293,7 @@ int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
* \return Returns 0 on success and -1 if it could not be done */
int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
-/*! Bridge two channels together
+/*! Bridge two channels together
* \param c0 first channel to bridge
* \param c1 second channel to bridge
* \param config config for the channels
@@ -1270,7 +1305,7 @@ int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,
struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
-/*!
+/*!
* \brief Weird function made for call transfers
*
* \param original channel to make a copy of
@@ -1281,14 +1316,14 @@ int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,
* the guts out of "clone" and puts them into the "original" channel, then alerts the
* channel driver of the change, asking it to fixup any private information (like the
* p->owner pointer) that is affected by the change. The physical layer of the original
- * channel is hung up.
+ * channel is hung up.
*
* \note Neither channel passed here needs to be locked before calling this function.
*/
int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
/*! Gives the string form of a given cause code */
-/*!
+/*!
* \param state cause to get the description of
* Give a name to a cause code
* Returns the text form of the binary cause code given
@@ -1296,16 +1331,16 @@ int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clo
const char *ast_cause2str(int state) attribute_pure;
/*! Convert the string form of a cause code to a number */
-/*!
+/*!
* \param name string form of the cause
* Returns the cause code
*/
int ast_str2cause(const char *name) attribute_pure;
/*! Gives the string form of a given channel state */
-/*!
+/*!
* \param ast_channel_state state to get the name of
- * Give a name to a state
+ * Give a name to a state
* Returns the text form of the binary state given
*/
const char *ast_state2str(enum ast_channel_state);
@@ -1325,13 +1360,13 @@ char *ast_transfercapability2str(int transfercapability) attribute_const;
asterisk application to be portable. They're mainly useful for tweaking performance */
/*! Sets an option on a channel */
-/*!
+/*!
* \param channel channel to set options on
* \param option option to change
* \param data data specific to option
* \param datalen length of the data
* \param block blocking or not
- * Set an option on a channel (see frame.h), optionally blocking awaiting the reply
+ * Set an option on a channel (see frame.h), optionally blocking awaiting the reply
* Returns 0 on success and -1 on failure
*/
int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
@@ -1342,7 +1377,7 @@ int ast_best_codec(int fmts);
/*! Checks the value of an option */
-/*!
+/*!
* Query the value of an option
* Works similarly to setoption except only reads the options.
*/
@@ -1413,15 +1448,15 @@ void ast_tonepair_stop(struct ast_channel *chan);
int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
/*!
- * \brief Automatically service a channel for us...
+ * \brief Automatically service a channel for us...
*
* \retval 0 success
* \retval -1 failure, or the channel is already being autoserviced
*/
int ast_autoservice_start(struct ast_channel *chan);
-/*!
- * \brief Stop servicing a channel for us...
+/*!
+ * \brief Stop servicing a channel for us...
*
* \note if chan is locked prior to calling ast_autoservice_stop, it
* is likely that there will be a deadlock between the thread that calls
@@ -1429,24 +1464,26 @@ int ast_autoservice_start(struct ast_channel *chan);
* that chan is not locked prior to this call
*
* \retval 0 success
- * \retval -1 error, or the channel has been hungup
+ * \retval -1 error, or the channel has been hungup
*/
int ast_autoservice_stop(struct ast_channel *chan);
/*!
* \brief Enable or disable timer ticks for a channel
*
- * \arg rate number of timer ticks per second
+ * \param rate number of timer ticks per second
*
* If timers are supported, force a scheduled expiration on the
- * timer fd, at which point we call the callback function / data
+ * timer fd, at which point we call the callback function / data
*
* Call this function with a rate of 0 to turn off the timer ticks
+ *
+ * \version 1.6.1 changed samples parameter to rate, accomodates new timing methods
*/
int ast_settimeout(struct ast_channel *c, unsigned int rate, int (*func)(const void *data), void *data);
/*! \brief Transfer a channel (if supported). Returns -1 on error, 0 if not supported
- and 1 if supported and requested
+ and 1 if supported and requested
\param chan current channel
\param dest destination extension for transfer
*/
@@ -1461,7 +1498,7 @@ int ast_transfer(struct ast_channel *chan, char *dest);
*/
int ast_do_masquerade(struct ast_channel *chan);
-/*! \brief Find bridged channel
+/*! \brief Find bridged channel
\param chan Current channel
*/
struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
@@ -1577,7 +1614,7 @@ static inline void timersub(struct timeval *tvend, struct timeval *tvstart, stru
}
#endif
-/*! \brief Waits for activity on a group of channels
+/*! \brief Waits for activity on a group of channels
* \param nfds the maximum number of file descriptors in the sets
* \param rfds file descriptors to check for read availability
* \param wfds file descriptors to check for write availability
@@ -1657,10 +1694,10 @@ const char *ast_channel_reason2str(int reason);
/*! \brief channel group info
*/
struct ast_group_info {
- struct ast_channel *chan;
- char *category;
- char *group;
- AST_LIST_ENTRY(ast_group_info) list;
+ struct ast_channel *chan;
+ char *category;
+ char *group;
+ AST_LIST_ENTRY(ast_group_info) list;
};
diff --git a/include/asterisk/config.h b/include/asterisk/config.h
index af74ae3cc..48ab206eb 100644
--- a/include/asterisk/config.h
+++ b/include/asterisk/config.h
@@ -67,7 +67,7 @@ typedef enum {
RQ_DATETIME,
} require_type;
-/*! \brief Structure for variables, used for configurations and for channel variables
+/*! \brief Structure for variables, used for configurations and for channel variables
*/
struct ast_variable {
const char *name;
@@ -91,7 +91,17 @@ typedef struct ast_config *realtime_multi_get(const char *database, const char *
typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
typedef int realtime_store(const char *database, const char *table, va_list ap);
typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
+
+/*!
+ * \brief Function pointer called to ensure database schema is properly configured for realtime use
+ * \since 1.6.1
+ */
typedef int realtime_require(const char *database, const char *table, va_list ap);
+
+/*!
+ * \brief Function pointer called to clear the database cache and free resources used for such
+ * \since 1.6.1
+ */
typedef int realtime_unload(const char *database, const char *table);
/*! \brief Configuration engine structure, used to define realtime drivers */
@@ -108,7 +118,7 @@ struct ast_config_engine {
struct ast_config_engine *next;
};
-/*! \brief Load a config file
+/*! \brief Load a config file
* \param filename path of file to open. If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
* Create a config structure from a given configuration file.
* \param who_asked The module which is making this request.
@@ -124,7 +134,7 @@ struct ast_config *ast_config_load2(const char *filename, const char *who_asked,
#define ast_config_load(filename, flags) ast_config_load2(filename, AST_MODULE, flags)
-/*! \brief Destroys a config
+/*! \brief Destroys a config
* \param config pointer to config data structure
* Free memory associated with a given config
*
@@ -139,7 +149,7 @@ void ast_config_destroy(struct ast_config *config);
*/
struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
-/*! \brief Goes through categories
+/*! \brief Goes through categories
* \param config Which config structure you wish to "browse"
* \param prev A pointer to a previous category.
* This function is kind of non-intuitive in it's use. To begin, one passes NULL as the second argument. It will return a pointer to the string of the first category in the file. From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
@@ -149,7 +159,7 @@ struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
*/
char *ast_category_browse(struct ast_config *config, const char *prev);
-/*!
+/*!
* \brief Goes through variables
* Somewhat similar in intent as the ast_category_browse.
* List variables of config file category
@@ -166,19 +176,19 @@ struct ast_variable *ast_variable_browse(const struct ast_config *config, const
*/
struct ast_variable *ast_category_first(struct ast_category *cat);
-/*!
- * \brief Gets a variable
+/*!
+ * \brief Gets a variable
* \param config which (opened) config to use
* \param category category under which the variable lies
* \param variable which variable you wish to get the data for
* Goes through a given config file in the given category and searches for the given variable
*
- * \retval The variable value on success
+ * \retval The variable value on success
* \retval NULL if unable to find it.
*/
const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
-/*!
+/*!
* \brief Retrieve a category if it exists
* \param config which config to use
* \param category_name name of the category you're looking for
@@ -189,8 +199,8 @@ const char *ast_variable_retrieve(const struct ast_config *config, const char *c
*/
struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
-/*!
- * \brief Check for category duplicates
+/*!
+ * \brief Check for category duplicates
* \param config which config to use
* \param category_name name of the category you're looking for
* This will search through the categories within a given config file for a match.
@@ -199,10 +209,10 @@ struct ast_category *ast_category_get(const struct ast_config *config, const cha
*/
int ast_category_exist(const struct ast_config *config, const char *category_name);
-/*!
- * \brief Retrieve realtime configuration
+/*!
+ * \brief Retrieve realtime configuration
* \param family which family/config to lookup
- * This will use builtin configuration backends to look up a particular
+ * This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Note
* that unlike the variables in ast_config, the resulting list of variables
* MUST be freed with ast_variables_destroy() as there is no container.
@@ -223,6 +233,7 @@ struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_se
* facility; on reload, a front end resource may request to purge that cache.
* \retval 0 If any cache was purged
* \retval -1 If no cache was found
+ * \since 1.6.1
*/
int ast_unload_realtime(const char *family);
@@ -255,22 +266,24 @@ int ast_unload_realtime(const char *family);
*
* Note that you should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
+ *
+ * \since 1.6.1
*/
int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
-/*!
- * \brief Retrieve realtime configuration
+/*!
+ * \brief Retrieve realtime configuration
* \param family which family/config to lookup
- * This will use builtin configuration backends to look up a particular
+ * This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Unlike
* the ast_load_realtime, this function can return more than one entry and
- * is thus stored inside a taditional ast_config structure rather than
+ * is thus stored inside a traditional ast_config structure rather than
* just returning a linked list of variables.
*/
struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
-/*!
- * \brief Update realtime configuration
+/*!
+ * \brief Update realtime configuration
* \param family which family/config to be updated
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@@ -292,8 +305,8 @@ int ast_update_realtime(const char *family, const char *keyfield, const char *lo
*/
int ast_store_realtime(const char *family, ...) attribute_sentinel;
-/*!
- * \brief Destroy realtime configuration
+/*!
+ * \brief Destroy realtime configuration
* \param family which family/config to be destroyed
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@@ -304,8 +317,8 @@ int ast_store_realtime(const char *family, ...) attribute_sentinel;
*/
int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
-/*!
- * \brief Check if realtime engine is configured for family
+/*!
+ * \brief Check if realtime engine is configured for family
* \param family which family/config to be checked
* \return 1 if family is configured in realtime and engine exists
*/
@@ -314,7 +327,7 @@ int ast_check_realtime(const char *family);
/*! \brief Check if there's any realtime engines loaded */
int ast_realtime_enabled(void);
-/*! \brief Free variable list
+/*! \brief Free variable list
* \param var the linked list of variables to free
* This function frees a list of variables.
*/
@@ -367,7 +380,7 @@ const char *ast_config_option(struct ast_config *cfg, const char *cat, const cha
struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
void ast_category_append(struct ast_config *config, struct ast_category *cat);
-/*!
+/*!
* \brief Inserts new category
* \param config which config to use
* \param cat newly created category to insert
@@ -408,7 +421,7 @@ int ast_variable_delete(struct ast_category *category, const char *variable, con
* \param object Boolean of whether to make the new variable an object
* \return 0 on success or -1 on failure.
*/
-int ast_variable_update(struct ast_category *category, const char *variable,
+int ast_variable_update(struct ast_category *category, const char *variable,
const char *value, const char *match, unsigned int object);
int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
@@ -487,7 +500,7 @@ enum ast_parse_flags {
*
* Examples of use:
* ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
- * &a, -1000, 1000);
+ * &a, -1000, 1000);
* returns 0, a = 223
* ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
* &a, 9999, 10, 100);
diff --git a/include/asterisk/datastore.h b/include/asterisk/datastore.h
index 6eb4cf2a5..6da1bd0bb 100644
--- a/include/asterisk/datastore.h
+++ b/include/asterisk/datastore.h
@@ -59,13 +59,18 @@ struct ast_datastore {
AST_LIST_ENTRY(ast_datastore) entry; /*!< Used for easy linking */
};
-/*!
+/*!
* \brief Create a data store object
+ * \param[in] info information describing the data store object
+ * \param[in] uid unique identifer
+ * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc
*/
struct ast_datastore *ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid);
/*!
* \brief Free a data store object
+ * \param[in] datastore datastore to free
+ * \version 1.6.1 moved here and renamed from ast_channel_datastore_free
*/
int ast_datastore_free(struct ast_datastore *datastore);
diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index ab37fe1ed..b0bf5bfcf 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -23,7 +23,7 @@
* method. For an example, see apps/app_queue.c.
*
* \todo Currently, when the state of a device changes, the device state provider
- * calls one of the functions defined here to queue an object to say that the
+ * calls one of the functions defined here to queue an object to say that the
* state of a device has changed. However, this does not include the new state.
* Another thread processes these device state change objects and calls the
* device state provider's callback to figure out what the new state is. It
@@ -41,7 +41,7 @@
extern "C" {
#endif
-/*! \brief Device States
+/*! \brief Device States
* \note The order of these states may not change because they are included
* in Asterisk events which may be transmitted across the network to
* other servers.
@@ -65,24 +65,25 @@ typedef enum ast_device_state (*ast_devstate_prov_cb_type)(const char *data);
* \brief Convert channel state to devicestate
*
* \param chanstate Current channel state
+ * \since 1.6.1
*/
enum ast_device_state ast_state_chan2dev(enum ast_channel_state chanstate);
-/*!
- * \brief Convert device state to text string for output
+/*!
+ * \brief Convert device state to text string for output
*
- * \param devstate Current device state
+ * \param devstate Current device state
*/
const char *devstate2str(enum ast_device_state devstate);
-/*!
- * \brief Convert device state to text string that is easier to parse
+/*!
+ * \brief Convert device state to text string that is easier to parse
*
- * \param devstate Current device state
+ * \param devstate Current device state
*/
const char *ast_devstate_str(enum ast_device_state devstate);
-/*!
+/*!
* \brief Convert device state from text to integer value
*
* \param val The text representing the device state. Valid values are anything
@@ -92,12 +93,12 @@ const char *ast_devstate_str(enum ast_device_state devstate);
*/
enum ast_device_state ast_devstate_val(const char *val);
-/*!
+/*!
* \brief Search the Channels by Name
*
* \param device like a dial string
*
- * Search the Device in active channels by compare the channel name against
+ * Search the Device in active channels by compare the channel name against
* the device name. Compared are only the first chars to the first '-' char.
*
* \retval AST_DEVICE_UNKNOWN if no channel found
@@ -105,7 +106,7 @@ enum ast_device_state ast_devstate_val(const char *val);
*/
enum ast_device_state ast_parse_device_state(const char *device);
-/*!
+/*!
* \brief Asks a channel for device state
*
* \param device like a dial string
@@ -115,12 +116,12 @@ enum ast_device_state ast_parse_device_state(const char *device);
* Tries the channel device state callback if not supported search in the
* active channels list for the device.
*
- * \retval an AST_DEVICE_??? state
+ * \retval an AST_DEVICE_??? state
* \retval -1 on failure
*/
enum ast_device_state ast_device_state(const char *device);
-/*!
+/*!
* \brief Tells Asterisk the State for Device is changed
*
* \param state the new state of the device
@@ -130,13 +131,13 @@ enum ast_device_state ast_device_state(const char *device);
* of device states. It will also be stored in the internal event
* cache.
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*/
int ast_devstate_changed(enum ast_device_state state, const char *fmt, ...)
__attribute__((format(printf, 2, 3)));
-/*!
+/*!
* \brief Tells Asterisk the State for Device is changed
*
* \param state the new state of the device
@@ -146,62 +147,65 @@ int ast_devstate_changed(enum ast_device_state state, const char *fmt, ...)
* of device states. It will also be stored in the internal event
* cache.
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*/
int ast_devstate_changed_literal(enum ast_device_state state, const char *device);
-/*!
- * \brief Tells Asterisk the State for Device is changed
+/*!
+ * \brief Tells Asterisk the State for Device is changed.
+ * (Accept change notification, add it to change queue.)
*
* \param fmt device name like a dial string with format parameters
*
* Asterisk polls the new extension states and calls the registered
* callbacks for the changed extensions
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*
* \note This is deprecated in favor of ast_devstate_changed()
+ * \version 1.6.1 deprecated
*/
int ast_device_state_changed(const char *fmt, ...)
__attribute__((deprecated,format(printf, 1, 2)));
-/*!
- * \brief Tells Asterisk the State for Device is changed
+/*!
+ * \brief Tells Asterisk the State for Device is changed
*
* \param device device name like a dial string
*
* Asterisk polls the new extension states and calls the registered
* callbacks for the changed extensions
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*
* \note This is deprecated in favor of ast_devstate_changed_literal()
+ * \version 1.6.1 deprecated
*/
int ast_device_state_changed_literal(const char *device)
__attribute__((deprecated));
-/*!
- * \brief Add device state provider
+/*!
+ * \brief Add device state provider
*
* \param label to use in hint, like label:object
* \param callback Callback
*
* \retval 0 success
* \retval -1 failure
- */
+ */
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback);
-/*!
- * \brief Remove device state provider
+/*!
+ * \brief Remove device state provider
*
* \param label to use in hint, like label:object
*
- * \retval -1 on failure
+ * \retval -1 on failure
* \retval 0 on success
- */
+ */
int ast_devstate_prov_del(const char *label);
/*!
@@ -212,33 +216,36 @@ struct ast_devstate_aggregate;
/*!
* \brief Initialize aggregate device state
*
- * \param agg the state object
+ * \param[in] agg the state object
*
* \return nothing
+ * \since 1.6.1
*/
void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
/*!
* \brief Add a device state to the aggregate device state
*
- * \param agg the state object
- * \param state the state to add
+ * \param[in] agg the state object
+ * \param[in] state the state to add
*
* \return nothing
+ * \since 1.6.1
*/
void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
/*!
* \brief Get the aggregate device state result
*
- * \param agg the state object
+ * \param[in] agg the state object
*
* \return the aggregate device state after adding some number of device states.
+ * \since 1.6.1
*/
enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg);
-/*!
- * \brief You shouldn't care about the contents of this struct
+/*!
+ * \brief You shouldn't care about the contents of this struct
*
* This struct is only here so that it can be easily declared on the stack.
*/
diff --git a/include/asterisk/dlinkedlists.h b/include/asterisk/dlinkedlists.h
index 17bd7a43c..fba69ecdf 100644
--- a/include/asterisk/dlinkedlists.h
+++ b/include/asterisk/dlinkedlists.h
@@ -4,7 +4,7 @@
* Copyright (C) 2007, Digium, Inc.
*
* Steve Murphy <murf@digium.com>
- *
+ *
* Doubly-Linked List Macros--
* Based on linkedlists.h (to the point of plagiarism!), which is by:
*
@@ -40,9 +40,10 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_DLLIST_LOCK(head) \
- ast_mutex_lock(&(head)->lock)
+ ast_mutex_lock(&(head)->lock)
/*!
\brief Write locks a list.
@@ -52,6 +53,7 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_RWDLLIST_WRLOCK(head) \
ast_rwlock_wrlock(&(head)->lock)
@@ -64,10 +66,11 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_RWDLLIST_RDLOCK(head) \
ast_rwlock_rdlock(&(head)->lock)
-
+
/*!
\brief Locks a list, without blocking if the list is locked.
\param head This is a pointer to the list head structure
@@ -76,9 +79,10 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_DLLIST_TRYLOCK(head) \
- ast_mutex_trylock(&(head)->lock)
+ ast_mutex_trylock(&(head)->lock)
/*!
\brief Write locks a list, without blocking if the list is locked.
@@ -88,6 +92,7 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_RWDLLIST_TRYWRLOCK(head) \
ast_rwlock_trywrlock(&(head)->lock)
@@ -100,10 +105,11 @@
list head structure pointed to by head.
\retval 0 on success
\retval non-zero on failure
+ \since 1.6.1
*/
#define AST_RWDLLIST_TRYRDLOCK(head) \
ast_rwlock_tryrdlock(&(head)->lock)
-
+
/*!
\brief Attempts to unlock a list.
\param head This is a pointer to the list head structure
@@ -111,6 +117,7 @@
This macro attempts to remove an exclusive lock from the
list head structure pointed to by head. If the list
was not locked by this thread, this macro has no effect.
+ \since 1.6.1
*/
#define AST_DLLIST_UNLOCK(head) \
ast_mutex_unlock(&(head)->lock)
@@ -122,6 +129,7 @@
This macro attempts to remove a read or write lock from the
list head structure pointed to by head. If the list
was not locked by this thread, this macro has no effect.
+ \since 1.6.1
*/
#define AST_RWDLLIST_UNLOCK(head) \
ast_rwlock_unlock(&(head)->lock)
@@ -144,6 +152,7 @@
This would define \c struct \c entry_list, and declare an instance of it named
\a entries, all intended to hold a list of type \c struct \c entry.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD(name, type) \
struct name { \
@@ -170,6 +179,7 @@ struct name { \
This would define \c struct \c entry_list, and declare an instance of it named
\a entries, all intended to hold a list of type \c struct \c entry.
+ \since 1.6.1
*/
#define AST_RWDLLIST_HEAD(name, type) \
struct name { \
@@ -196,6 +206,7 @@ struct name { \
This would define \c struct \c entry_list, and declare an instance of it named
\a entries, all intended to hold a list of type \c struct \c entry.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_NOLOCK(name, type) \
struct name { \
@@ -205,6 +216,7 @@ struct name { \
/*!
\brief Defines initial values for a declaration of AST_DLLIST_HEAD
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_INIT_VALUE { \
.first = NULL, \
@@ -214,6 +226,7 @@ struct name { \
/*!
\brief Defines initial values for a declaration of AST_RWDLLIST_HEAD
+ \since 1.6.1
*/
#define AST_RWDLLIST_HEAD_INIT_VALUE { \
.first = NULL, \
@@ -223,6 +236,7 @@ struct name { \
/*!
\brief Defines initial values for a declaration of AST_DLLIST_HEAD_NOLOCK
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_NOLOCK_INIT_VALUE { \
.first = NULL, \
@@ -245,6 +259,7 @@ struct name { \
This would define \c struct \c entry_list, intended to hold a list of
type \c struct \c entry.
+ \since 1.6.1
*/
#if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
#define AST_DLLIST_HEAD_STATIC(name, type) \
@@ -287,6 +302,7 @@ struct name { \
This would define \c struct \c entry_list, intended to hold a list of
type \c struct \c entry.
+ \since 1.6.1
*/
#ifndef AST_RWLOCK_INIT_VALUE
#define AST_RWDLLIST_HEAD_STATIC(name, type) \
@@ -317,6 +333,7 @@ struct name { \
\brief Defines a structure to be used to hold a list of specified type, statically initialized.
This is the same as AST_DLLIST_HEAD_STATIC, except without the lock included.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_NOLOCK_STATIC(name, type) \
struct name { \
@@ -331,6 +348,7 @@ struct name { \
This macro initializes a list head structure by setting the head
entry to the supplied value and recreating the embedded lock.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_SET(head, entry) do { \
(head)->first = (entry); \
@@ -345,6 +363,7 @@ struct name { \
This macro initializes a list head structure by setting the head
entry to the supplied value and recreating the embedded lock.
+ \since 1.6.1
*/
#define AST_RWDLLIST_HEAD_SET(head, entry) do { \
(head)->first = (entry); \
@@ -359,6 +378,7 @@ struct name { \
This macro initializes a list head structure by setting the head
entry to the supplied value.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_SET_NOLOCK(head, entry) do { \
(head)->first = (entry); \
@@ -381,6 +401,7 @@ struct name { \
\endcode
The field name \a list here is arbitrary, and can be anything you wish.
+ \since 1.6.1
*/
#define AST_DLLIST_ENTRY(type) \
struct { \
@@ -389,10 +410,11 @@ struct { \
}
#define AST_RWDLLIST_ENTRY AST_DLLIST_ENTRY
-
+
/*!
\brief Returns the first entry contained in a list.
\param head This is a pointer to the list head structure
+ \since 1.6.1
*/
#define AST_DLLIST_FIRST(head) ((head)->first)
@@ -401,6 +423,7 @@ struct { \
/*!
\brief Returns the last entry contained in a list.
\param head This is a pointer to the list head structure
+ \since 1.6.1
*/
#define AST_DLLIST_LAST(head) ((head)->last)
@@ -411,6 +434,7 @@ struct { \
\param elm This is a pointer to the current entry.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
+ \since 1.6.1
*/
#define AST_DLLIST_NEXT(elm, field) ((elm)->field.next)
@@ -421,6 +445,7 @@ struct { \
\param elm This is a pointer to the current entry.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
+ \since 1.6.1
*/
#define AST_DLLIST_PREV(elm, field) ((elm)->field.prev)
@@ -432,6 +457,7 @@ struct { \
\return non-zero if the list has entries
\return zero if not.
+ \since 1.6.1
*/
#define AST_DLLIST_EMPTY(head) (AST_DLLIST_FIRST(head) == NULL)
@@ -472,6 +498,7 @@ struct { \
\li AST_DLLIST_INSERT_AFTER()
\li AST_DLLIST_INSERT_HEAD()
\li AST_DLLIST_INSERT_TAIL()
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE(head,var,field) \
for((var) = (head)->first; (var); (var) = (var)->field.next)
@@ -513,6 +540,7 @@ struct { \
\li AST_DLLIST_INSERT_BEFORE()
\li AST_DLLIST_INSERT_HEAD()
\li AST_DLLIST_INSERT_TAIL()
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE_BACKWARDS(head,var,field) \
for((var) = (head)->last; (var); (var) = (var)->field.prev)
@@ -551,6 +579,7 @@ struct { \
It differs from AST_DLLIST_TRAVERSE() in that the code inside the loop can modify
(or even free, after calling AST_DLLIST_REMOVE_CURRENT()) the entry pointed to by
the \a current pointer without affecting the loop traversal.
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE_SAFE_BEGIN(head, var, field) { \
typeof((head)) __list_head = head; \
@@ -599,6 +628,7 @@ struct { \
It differs from AST_DLLIST_TRAVERSE() in that the code inside the loop can modify
(or even free, after calling AST_DLLIST_REMOVE_CURRENT()) the entry pointed to by
the \a current pointer without affecting the loop traversal.
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN(head, var, field) { \
typeof((head)) __list_head = head; \
@@ -624,6 +654,7 @@ struct { \
block; it is used to unlink the current entry from the list without affecting
the list traversal (and without having to re-traverse the list to modify the
previous entry, if any).
+ \since 1.6.1
*/
#define AST_DLLIST_REMOVE_CURRENT(field) do { \
__new_prev->field.next = NULL; \
@@ -676,6 +707,7 @@ struct { \
\note This macro can \b only be used inside an AST_DLLIST_TRAVERSE_SAFE_BEGIN()
block.
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_BEFORE_CURRENT(elm, field) do { \
if (__list_prev) { \
@@ -698,7 +730,7 @@ struct { \
\brief Inserts a list entry after the current entry during a backwards traversal. Since
this is a backwards traversal, this will insert the entry AFTER the current
element. Since this is a backwards traveral, though, this would be BEFORE
- the current entry in traversal order. Confusing?
+ the current entry in traversal order. Confusing?
\param elm This is a pointer to the entry to be inserted.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
@@ -706,6 +738,7 @@ struct { \
\note This macro can \b only be used inside an AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN()
block. If you use this with the AST_DLLIST_TRAVERSE_SAFE_BEGIN(), be prepared for
strange things!
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_BEFORE_CURRENT_BACKWARDS(elm, field) do { \
if (__list_next) { \
@@ -725,6 +758,7 @@ struct { \
/*!
\brief Closes a safe loop traversal block.
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE_SAFE_END }
@@ -732,6 +766,7 @@ struct { \
/*!
\brief Closes a safe loop traversal block.
+ \since 1.6.1
*/
#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_END }
@@ -743,6 +778,7 @@ struct { \
This macro initializes a list head structure by setting the head
entry to \a NULL (empty list) and recreating the embedded lock.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_INIT(head) { \
(head)->first = NULL; \
@@ -756,6 +792,7 @@ struct { \
This macro initializes a list head structure by setting the head
entry to \a NULL (empty list) and recreating the embedded lock.
+ \since 1.6.1
*/
#define AST_RWDLLIST_HEAD_INIT(head) { \
(head)->first = NULL; \
@@ -770,6 +807,7 @@ struct { \
This macro destroys a list head structure by setting the head
entry to \a NULL (empty list) and destroying the embedded lock.
It does not free the structure from memory.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_DESTROY(head) { \
(head)->first = NULL; \
@@ -784,6 +822,7 @@ struct { \
This macro destroys a list head structure by setting the head
entry to \a NULL (empty list) and destroying the embedded lock.
It does not free the structure from memory.
+ \since 1.6.1
*/
#define AST_RWDLLIST_HEAD_DESTROY(head) { \
(head)->first = NULL; \
@@ -798,6 +837,7 @@ struct { \
This macro initializes a list head structure by setting the head
entry to \a NULL (empty list). There is no embedded lock handling
with this macro.
+ \since 1.6.1
*/
#define AST_DLLIST_HEAD_INIT_NOLOCK(head) { \
(head)->first = NULL; \
@@ -812,6 +852,7 @@ struct { \
\param elm This is a pointer to the entry to be inserted.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_AFTER(head, listelm, elm, field) do { \
(elm)->field.next = (listelm)->field.next; \
@@ -833,6 +874,7 @@ struct { \
\param elm This is a pointer to the entry to be inserted.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_BEFORE(head, listelm, elm, field) do { \
(elm)->field.next = (listelm); \
@@ -852,6 +894,7 @@ struct { \
\param elm This is a pointer to the entry to be inserted.
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_HEAD(head, elm, field) do { \
(elm)->field.next = (head)->first; \
@@ -875,6 +918,7 @@ struct { \
Note: The link field in the appended entry is \b not modified, so if it is
actually the head of a list itself, the entire list will be appended
temporarily (until the next AST_DLLIST_INSERT_TAIL is performed).
+ \since 1.6.1
*/
#define AST_DLLIST_INSERT_TAIL(head, elm, field) do { \
if (!(head)->first) { \
@@ -901,6 +945,7 @@ struct { \
Note: The source list (the \a list parameter) will be empty after
calling this macro (the list entries are \b moved to the target list).
+ \since 1.6.1
*/
#define AST_DLLIST_APPEND_DLLIST(head, list, field) do { \
if (!(head)->first) { \
@@ -925,6 +970,7 @@ struct { \
Removes the head entry from the list, and returns a pointer to it.
This macro is safe to call on an empty list.
+ \since 1.6.1
*/
#define AST_DLLIST_REMOVE_HEAD(head, field) ({ \
typeof((head)->first) cur = (head)->first; \
@@ -948,6 +994,7 @@ struct { \
\param field This is the name of the field (declared using AST_DLLIST_ENTRY())
used to link entries of this list together.
\warning The removed entry is \b not freed nor modified in any way.
+ \since 1.6.1
*/
#define AST_DLLIST_REMOVE(head, elm, field) ({ \
__typeof(elm) __res = (elm); \
diff --git a/include/asterisk/dnsmgr.h b/include/asterisk/dnsmgr.h
index 36011c227..d76733336 100644
--- a/include/asterisk/dnsmgr.h
+++ b/include/asterisk/dnsmgr.h
@@ -50,6 +50,7 @@ struct ast_dnsmgr_entry;
* is already known.
*
* \return a DNS manager entry
+ * \version 1.6.1 result changed from struct in_addr to struct sockaddr_in to store port number
*/
struct ast_dnsmgr_entry *ast_dnsmgr_get(const char *name, struct sockaddr_in *result, const char *service);
@@ -75,6 +76,7 @@ void ast_dnsmgr_release(struct ast_dnsmgr_entry *entry);
*
* \retval 0 success
* \retval non-zero failure
+ * \version 1.6.1 result changed from struct in_addr to struct aockaddr_in to store port number
*/
int ast_dnsmgr_lookup(const char *name, struct sockaddr_in *result, struct ast_dnsmgr_entry **dnsmgr, const char *service);
@@ -82,7 +84,7 @@ int ast_dnsmgr_lookup(const char *name, struct sockaddr_in *result, struct ast_d
* \brief Force a refresh of a dnsmgr entry
*
* \retval non-zero if the result is different than the previous result
- * \retval zero if the result is the same as the previous result
+ * \retval zero if the result is the same as the previous result
*/
int ast_dnsmgr_refresh(struct ast_dnsmgr_entry *entry);
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 6fc2786d5..beb76ff75 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -28,6 +28,7 @@
/*! \page DevDoc Asterisk Developer's Documentation - appendices
* \arg \ref CodeGuide : The must-read document for all developer's
* \arg \ref AstAPI
+ * \arg \ref AstAPIChanges
* \arg \ref Def_Channel : What's a channel, anyway?
* \arg \ref channel_drivers : Existing channel drivers
* \arg \ref AstDebug : Hints on debugging
@@ -78,6 +79,33 @@
* \arg See \ref Def_Channel
*/
+/*! \page AstAPIChanges Asterisk API Changes
+ * \section Changes161 Version 1.6.1
+ * \li ast_install_vm_functions()
+ * \li vmwi_generate()
+ * \li ast_channel_datastore_alloc()
+ * \li ast_channel_datastore_free()
+ * \li ast_channel_cmpwhentohangup()
+ * \li ast_channel_setwhentohangup()
+ * \li ast_settimeout()
+ * \li ast_datastore_alloc()
+ * \li ast_datastore_free()
+ * \li ast_device_state_changed()
+ * \li ast_device_state_changed_literal()
+ * \li ast_dnsmgr_get()
+ * \li ast_dnsmgr_lookup()
+ * \li ast_dsp_set_digitmode()
+ * \li ast_get_txt()
+ * \li ast_event_unsubscribe()
+ * \li localized_context_find_or_create()
+ * \li localized_merge_contexts_and_delete()
+ * \li ast_console_puts_mutable()
+ * \li ast_rtp_get_quality()
+ * \li ast_tcptls_client_start()
+ * \li ast_tcptls_server_start()
+ * \li ast_tcptls_server_stop()
+ */
+
/*! \page AstDebug Debugging
* \section debug Debugging
* \verbinclude backtrace.txt
diff --git a/include/asterisk/dsp.h b/include/asterisk/dsp.h
index 5193ff4dd..b4163893c 100644
--- a/include/asterisk/dsp.h
+++ b/include/asterisk/dsp.h
@@ -47,7 +47,7 @@
#define DSP_FAXMODE_DETECT_ALL (DSP_FAXMODE_DETECT_CNG | DSP_FAXMODE_DETECT_CED)
#define DSP_TONE_STATE_SILENCE 0
-#define DSP_TONE_STATE_RINGING 1
+#define DSP_TONE_STATE_RINGING 1
#define DSP_TONE_STATE_DIALTONE 2
#define DSP_TONE_STATE_TALKING 3
#define DSP_TONE_STATE_BUSY 4
@@ -83,7 +83,7 @@ int ast_dsp_call_progress(struct ast_dsp *dsp, struct ast_frame *inf);
/*! \brief Set zone for doing progress detection */
int ast_dsp_set_call_progress_zone(struct ast_dsp *dsp, char *zone);
-/*! \brief Return AST_FRAME_NULL frames when there is silence, AST_FRAME_BUSY on
+/*! \brief Return AST_FRAME_NULL frames when there is silence, AST_FRAME_BUSY on
busies, and call progress, all dependent upon which features are enabled */
struct ast_frame *ast_dsp_process(struct ast_channel *chan, struct ast_dsp *dsp, struct ast_frame *inf);
@@ -91,8 +91,11 @@ struct ast_frame *ast_dsp_process(struct ast_channel *chan, struct ast_dsp *dsp,
number of seconds of silence */
int ast_dsp_silence(struct ast_dsp *dsp, struct ast_frame *f, int *totalsilence);
-/*! \brief Return non-zero if this is noise. Updates "totalnoise" with the total
- number of seconds of noise */
+/*!
+ * \brief Return non-zero if this is noise. Updates "totalnoise" with the total
+ * number of seconds of noise
+ * \since 1.6.1
+ */
int ast_dsp_noise(struct ast_dsp *dsp, struct ast_frame *f, int *totalnoise);
/*! \brief Return non-zero if historically this should be a busy, request that
@@ -114,14 +117,19 @@ void ast_dsp_set_features(struct ast_dsp *dsp, int features);
/*! \brief Get pending DTMF/MF digits */
int ast_dsp_getdigits(struct ast_dsp *dsp, char *buf, int max);
-/*! \brief Set digit mode */
+/*! \brief Set digit mode
+ * \version 1.6.1 renamed from ast_dsp_digitmode to ast_dsp_set_digitmode
+ */
int ast_dsp_set_digitmode(struct ast_dsp *dsp, int digitmode);
/*! \brief Set fax mode */
int ast_dsp_set_faxmode(struct ast_dsp *dsp, int faxmode);
-/*! \brief Returns true if DSP code was muting any fragment of the last processed frame.
- Muting (squelching) happens when DSP code removes DTMF/MF/generic tones from the audio */
+/*!
+ * \brief Returns true if DSP code was muting any fragment of the last processed frame.
+ * Muting (squelching) happens when DSP code removes DTMF/MF/generic tones from the audio
+ * \since 1.6.1
+ */
int ast_dsp_was_muted(struct ast_dsp *dsp);
/*! \brief Get tstate (Tone State) */
@@ -130,12 +138,22 @@ int ast_dsp_get_tstate(struct ast_dsp *dsp);
/*! \brief Get tcount (Threshold counter) */
int ast_dsp_get_tcount(struct ast_dsp *dsp);
-/*! \brief Get silence threshold from dsp.conf*/
+/*!
+ * \brief Get silence threshold from dsp.conf
+ * \since 1.6.1
+ */
int ast_dsp_get_threshold_from_settings(enum threshold which);
-/* \brief Reloads dsp settings from dsp.conf*/
+/*!
+ * \brief Reloads dsp settings from dsp.conf
+ * \since 1.6.1
+ */
int ast_dsp_reload(void);
+/*!
+ * \brief Load dsp settings from dsp.conf
+ * \since 1.6.1
+ */
int ast_dsp_init(void);
/*!
diff --git a/include/asterisk/enum.h b/include/asterisk/enum.h
index d19368905..877c0c3cf 100644
--- a/include/asterisk/enum.h
+++ b/include/asterisk/enum.h
@@ -53,7 +53,7 @@ struct enum_context {
};
-/*! \brief Lookup entry in ENUM
+/*! \brief Lookup entry in ENUM
\param chan Channel
\param number E164 number with or without the leading +
\param location Number returned (or SIP uri)
@@ -76,16 +76,25 @@ struct enum_context {
\retval 0 if not found
\retval -1 on hangup
*/
-int ast_get_enum(struct ast_channel *chan, const char *number, char *location, int maxloc, char *technology,
+int ast_get_enum(struct ast_channel *chan, const char *number, char *location, int maxloc, char *technology,
int maxtech, char* suffix, char* options, unsigned int record, struct enum_context **argcontext);
-/*! \brief Lookup DNS TXT record (used by app TXTCIDnum
- \param chan Channel
- \param number E164 number with or without the leading +
- \param txt Text string (return value)
- \param maxtxt Max length of "txt"
- \param suffix Zone suffix
-*/
+/*! \brief Lookup DNS TXT record (used by app TXTCIDnum)
+ *
+ * Really has nothing to do with enum, but anyway...
+ * Actually, there is now an internet-draft which describes how callerID should
+ * be stored in ENUM domains: draft-ietf-enum-cnam-04.txt
+ * The algorithm implemented here will thus be obsolete soon.
+ *
+ * \param chan Channel
+ * \param number E164 number with or without the leading +
+ * \param txt Text string (return value)
+ * \param maxtxt Max length of "txt"
+ * \param suffix Zone suffix
+ * \version 1.6.1 new suffix parameter to take into account caller ids that aren't in e164.arpa
+ * \version 1.6.1 removed parameters location, maxloc, technology, maxtech as all the information
+ * is stored the txt string
+ */
int ast_get_txt(struct ast_channel *chan, const char *number, char *txt, int maxtxt, char *suffix);
int ast_enum_init(void);
diff --git a/include/asterisk/event.h b/include/asterisk/event.h
index 45d10fc73..96cf9bd0a 100644
--- a/include/asterisk/event.h
+++ b/include/asterisk/event.h
@@ -63,7 +63,7 @@ extern "C" {
#include "asterisk/event_defs.h"
-/*!
+/*!
* \brief Subscriber event callback type
*
* \param event the event being passed to the subscriber
@@ -73,7 +73,7 @@ extern "C" {
*/
typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
-/*!
+/*!
* \brief Subscribe to events
*
* \param event_type The type of events to subscribe to
@@ -110,45 +110,48 @@ typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
* contained in peer->mailbox. Also, the event callback will be passed a
* pointer to the peer.
*/
-struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
+struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
ast_event_cb_t cb, void *userdata, ...);
/*!
* \brief Allocate a subscription, but do not activate it
*
- * \arg type the event type to subscribe to
- * \arg cb the function to call when an event matches this subscription
- * \arg userdata data to pass to the provided callback
+ * \param type the event type to subscribe to
+ * \param cb the function to call when an event matches this subscription
+ * \param userdata data to pass to the provided callback
*
* This function should be used when you want to dynamically build a
* subscription.
*
* \return the allocated subscription, or NULL on failure
+ * \since 1.6.1
*/
-struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
+struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
ast_event_cb_t cb, void *userdata);
/*!
* \brief Destroy an allocated subscription
*
- * \arg sub the subscription to destroy
+ * \param sub the subscription to destroy
*
* This function should be used when a subscription is allocated with
* ast_event_subscribe_new(), but for some reason, you want to destroy it
* instead of activating it. This could be because of an error when
* reading in the configuration for the dynamically built subscription.
+ * \since 1.6.1
*/
void ast_event_sub_destroy(struct ast_event_sub *sub);
/*!
* \brief Append a uint parameter to a subscription
*
- * \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
- * \arg ie_type the information element type for the parameter
- * \arg uint the value that must be present in the event to match this subscription
+ * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
+ * \param ie_type the information element type for the parameter
+ * \param uint the value that must be present in the event to match this subscription
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
enum ast_event_ie_type ie_type, uint32_t uint);
@@ -156,53 +159,57 @@ int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
/*!
* \brief Append a string parameter to a subscription
*
- * \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
- * \arg ie_type the information element type for the parameter
- * \arg str the string that must be present in the event to match this subscription
+ * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
+ * \param ie_type the information element type for the parameter
+ * \param str the string that must be present in the event to match this subscription
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
-int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
+int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
enum ast_event_ie_type ie_type, const char *str);
/*!
* \brief Append a raw parameter to a subscription
*
- * \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
- * \arg ie_type the information element type for the parameter
- * \arg raw the data that must be present in the event to match this subscription
+ * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
+ * \param ie_type the information element type for the parameter
+ * \param raw the data that must be present in the event to match this subscription
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
-int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
+int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
enum ast_event_ie_type ie_type, void *data, size_t raw_datalen);
/*!
* \brief Append an 'exists' parameter to a subscription
*
- * \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
- * \arg ie_type the information element type that must be present in the event
+ * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
+ * \param ie_type the information element type that must be present in the event
* for it to match this subscription.
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
-int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
+int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
enum ast_event_ie_type ie_type);
/*!
* \brief Activate a dynamically built subscription
*
- * \arg sub the subscription to activate that was allocated using
+ * \param sub the subscription to activate that was allocated using
* ast_event_subscribe_new()
*
- * Once a dynamically built subscription has had all of the parameters added
+ * Once a dynamically built subscription has had all of the parameters added
* to it, it should be activated using this function.
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_event_sub_activate(struct ast_event_sub *sub);
@@ -216,6 +223,7 @@ int ast_event_sub_activate(struct ast_event_sub *sub);
* structures.
*
* \return NULL for convenience.
+ * \version 1.6.1 return changed to NULL
*/
struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
@@ -252,7 +260,7 @@ struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
* }
* \endcode
*
- * This example will check if there are any subscribers to MWI events for the
+ * This example will check if there are any subscribers to MWI events for the
* mailbox defined in the "mailbox" variable.
*/
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
@@ -274,7 +282,10 @@ enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type eve
*/
void ast_event_report_subs(const struct ast_event_sub *sub);
-/*! \brief Dump the event cache for the subscriber */
+/*!
+ * \brief Dump the event cache for the subscriber
+ * \since 1.6.1
+ */
void ast_event_dump_cache(const struct ast_event_sub *event_sub);
/*!
@@ -337,7 +348,7 @@ void ast_event_destroy(struct ast_event *event);
*
* This function queues an event to be dispatched to all of the appropriate
* subscribers. This function will not block while the event is being
- * dispatched because a pool of event dispatching threads handle the event
+ * dispatched because a pool of event dispatching threads handle the event
* queue.
*/
int ast_event_queue(struct ast_event *event);
@@ -350,7 +361,7 @@ int ast_event_queue(struct ast_event *event);
* The rest of the arguments to this function specify information elements to
* use for determining which events in the cache that this event should replace.
* All events in the cache that match the specified criteria will be removed from
- * the cache and then this one will be added. The arguments are specified in
+ * the cache and then this one will be added. The arguments are specified in
* the form:
*
* \code
@@ -481,7 +492,7 @@ int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_
*
* \param event The event to get the IE from
* \param ie_type the type of information element to retrieve
- *
+ *
* \return This returns the payload of the information element with the given type.
* However, an IE with a payload of 0, and the case where no IE is found
* yield the same return value.
@@ -493,7 +504,7 @@ uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_
*
* \param event The event to get the IE from
* \param ie_type the type of information element to retrieve
- *
+ *
* \return This returns the payload of the information element with the given type.
* If the information element isn't found, NULL will be returned.
*/
@@ -504,7 +515,7 @@ const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_i
*
* \param event The event to get the IE from
* \param ie_type the type of information element to retrieve
- *
+ *
* \return This returns the payload of the information element with the given type.
* If the information element isn't found, NULL will be returned.
*/
@@ -513,18 +524,20 @@ const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_i
/*!
* \brief Get the string representation of an information element type
*
- * \arg ie_type the information element type to get the string representation of
+ * \param ie_type the information element type to get the string representation of
*
* \return the string representation of the information element type
+ * \since 1.6.1
*/
const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
/*!
* \brief Get the payload type for a given information element type
*
- * \arg ie_type the information element type to get the payload type of
+ * \param ie_type the information element type to get the payload type of
*
* \return the payload type for the provided IE type
+ * \since 1.6.1
*/
enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
@@ -544,28 +557,31 @@ enum ast_event_type ast_event_get_type(const struct ast_event *event);
* \arg event the event to get the type of
*
* \return the string representation of the event type of the provided event
+ * \since 1.6.1
*/
const char *ast_event_get_type_name(const struct ast_event *event);
/*!
* \brief Convert a string into an event type
*
- * \arg str the string to convert
- * \arg event_type an output parameter for the event type
+ * \param str the string to convert
+ * \param event_type an output parameter for the event type
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
/*!
* \brief Convert a string to an IE type
*
- * \arg str the string to convert
- * \arg ie_type an output parameter for the IE type
+ * \param str the string to convert
+ * \param ie_type an output parameter for the IE type
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
@@ -575,6 +591,7 @@ int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
* \param event the event to get the size of
*
* \return the number of bytes contained in the event
+ * \since 1.6.1
*/
size_t ast_event_get_size(const struct ast_event *event);
diff --git a/include/asterisk/extconf.h b/include/asterisk/extconf.h
index 086271ce5..757ea4dbf 100644
--- a/include/asterisk/extconf.h
+++ b/include/asterisk/extconf.h
@@ -1,4 +1,4 @@
-/*
+/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2007, Digium, Inc.
@@ -15,7 +15,7 @@
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
-/*! \file
+/*! \file
* \brief External configuration handlers (realtime and static configuration)
* \author Steve Murphy <murf@digium.com>
*
@@ -30,7 +30,7 @@ extern "C" {
#ifdef NOTYET
/* I'm going to define all the structs mentioned below, to avoid
- possible conflicts in declarations that might be introduced,
+ possible conflicts in declarations that might be introduced,
if we just include the files that define them-- this may be
unnecessary */
@@ -54,7 +54,7 @@ struct ast_variable {
struct ast_category {
char name[80];
int ignored; /*!< do not let user of the config see this category */
- int include_level;
+ int include_level;
struct ast_comment *precomments;
struct ast_comment *sameline;
struct ast_variable *root;
@@ -174,6 +174,10 @@ struct ast_sw *localized_walk_context_switches(struct ast_context *con,
void localized_context_destroy(struct ast_context *con, const char *registrar);
int localized_pbx_load_module(void);
+/*!
+ * \version 1.6.1 added tab parameter
+ * \version 1.6.1 renamed function from localized_context_create to localized_context_find_or_create
+ */
struct ast_context *localized_context_find_or_create(struct ast_context **extcontexts, void *tab, const char *name, const char *registrar);
int localized_pbx_builtin_setvar(struct ast_channel *chan, void *data);
int localized_context_add_ignorepat2(struct ast_context *con, const char *value, const char *registrar);
@@ -185,6 +189,10 @@ int localized_add_extension2(struct ast_context *con,
int replace, const char *extension, int priority, const char *label, const char *callerid,
const char *application, void *data, void (*datad)(void *),
const char *registrar);
+
+/*!
+ * \version 1.6.1 added tab parameter
+ */
void localized_merge_contexts_and_delete(struct ast_context **extcontexts, void *tab, const char *registrar);
int localized_context_verify_includes(struct ast_context *con);
void localized_use_conf_dir(void);
@@ -228,17 +236,17 @@ struct pbx_find_info {
#define STATUS_NO_EXTENSION 2
#define STATUS_NO_PRIORITY 3
#define STATUS_NO_LABEL 4
-#define STATUS_SUCCESS 5
+#define STATUS_SUCCESS 5
#endif
struct ast_exten *localized_find_extension(struct ast_context *bypass,
struct pbx_find_info *q,
- const char *context,
- const char *exten,
+ const char *context,
+ const char *exten,
int priority,
- const char *label,
- const char *callerid,
+ const char *label,
+ const char *callerid,
enum ext_match_t action);
diff --git a/include/asterisk/heap.h b/include/asterisk/heap.h
index 8148fa5ba..56311ca05 100644
--- a/include/asterisk/heap.h
+++ b/include/asterisk/heap.h
@@ -49,6 +49,8 @@ struct ast_heap;
*
* \note This implementation is of a max heap. However, if a min heap is
* desired, simply swap the return values of this function.
+ *
+ * \since 1.6.1
*/
typedef int (*ast_heap_cmp_fn)(void *elm1, void *elm2);
@@ -93,6 +95,7 @@ typedef int (*ast_heap_cmp_fn)(void *elm1, void *elm2);
* \endcode
*
* \return An instance of a max heap
+ * \since 1.6.1
*/
struct ast_heap *ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_fn,
ssize_t index_offset);
@@ -103,6 +106,7 @@ struct ast_heap *ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_f
* \param h the heap to destroy
*
* \return NULL for convenience
+ * \since 1.6.1
*/
struct ast_heap *ast_heap_destroy(struct ast_heap *h);
@@ -114,6 +118,7 @@ struct ast_heap *ast_heap_destroy(struct ast_heap *h);
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_heap_push(struct ast_heap *h, void *elm);
@@ -126,6 +131,7 @@ int ast_heap_push(struct ast_heap *h, void *elm);
* largest value according to the element comparison function that was
* provided when the heap was created. The element will be removed before
* being returned.
+ * \since 1.6.1
*/
void *ast_heap_pop(struct ast_heap *h);
@@ -139,6 +145,7 @@ void *ast_heap_pop(struct ast_heap *h);
*
* \note the index_offset parameter to ast_heap_create() is required to be able
* to use this function.
+ * \since 1.6.1
*/
void *ast_heap_remove(struct ast_heap *h, void *elm);
@@ -177,6 +184,7 @@ void *ast_heap_remove(struct ast_heap *h, void *elm);
* ast_heap_unlock(h);
*
* \endcode
+ * \since 1.6.1
*/
void *ast_heap_peek(struct ast_heap *h, unsigned int index);
@@ -186,41 +194,45 @@ void *ast_heap_peek(struct ast_heap *h, unsigned int index);
* \param h the heap
*
* \return the number of elements currently in the heap
+ * \since 1.6.1
*/
size_t ast_heap_size(struct ast_heap *h);
/*!
* \brief Write-Lock a heap
*
- * \arg h the heap
+ * \param h the heap
*
* A lock is provided for convenience. It can be assumed that none of the
* ast_heap API calls are thread safe. This lock does not have to be used
* if another one is already available to protect the heap.
*
* \return see the documentation for pthread_rwlock_wrlock()
+ * \since 1.6.1
*/
int ast_heap_wrlock(struct ast_heap *h);
/*!
* \brief Read-Lock a heap
*
- * \arg h the heap
+ * \param h the heap
*
* A lock is provided for convenience. It can be assumed that none of the
* ast_heap API calls are thread safe. This lock does not have to be used
* if another one is already available to protect the heap.
*
* \return see the documentation for pthread_rwlock_rdlock()
+ * \since 1.6.1
*/
int ast_heap_rdlock(struct ast_heap *h);
/*!
* \brief Unlock a heap
*
- * \arg h the heap
+ * \param h the heap
*
* \return see the documentation for pthread_rwlock_unlock()
+ * \since 1.6.1
*/
int ast_heap_unlock(struct ast_heap *h);
@@ -234,6 +246,7 @@ int ast_heap_unlock(struct ast_heap *h);
*
* \note This function is mostly for debugging purposes. It traverses an existing
* heap and verifies that every node is properly placed relative to its children.
+ * \since 1.6.1
*/
int ast_heap_verify(struct ast_heap *h);
diff --git a/include/asterisk/http.h b/include/asterisk/http.h
index 218ac3f1a..25de13352 100644
--- a/include/asterisk/http.h
+++ b/include/asterisk/http.h
@@ -58,11 +58,11 @@
\note The method and the path as arguments and should
return the content, allocated with malloc(). Status should be changed to reflect
the status of the request if it isn't 200 and title may be set to a malloc()'d string
- to an appropriate title for non-200 responses. Content length may also be specified.
-\verbatim
- The return value may include additional headers at the front and MUST include a blank
+ to an appropriate title for non-200 responses. Content length may also be specified.
+\verbatim
+ The return value may include additional headers at the front and MUST include a blank
line with \r\n to provide separation between user headers and content (even if no
- content is specified)
+ content is specified)
\endverbatim
*/
@@ -109,7 +109,12 @@ void ast_http_uri_unlink_all_with_key(const char *key);
/*! \brief Return an ast_str malloc()'d string containing an HTTP error message */
struct ast_str *ast_http_error(int status, const char *title, const char *extra_header, const char *text);
-/*! \brief Return the current prefix */
+/*!
+ * \brief Return the current prefix
+ * \param buf[out] destination buffer for previous
+ * \param len[in] length of prefix to copy
+ * \since 1.6.1
+ */
void ast_http_prefix(char *buf, int len);
#endif /* _ASTERISK_SRV_H */
diff --git a/include/asterisk/linkedlists.h b/include/asterisk/linkedlists.h
index e172d91bc..1db0ae2db 100644
--- a/include/asterisk/linkedlists.h
+++ b/include/asterisk/linkedlists.h
@@ -37,7 +37,7 @@
\retval non-zero on failure
*/
#define AST_LIST_LOCK(head) \
- ast_mutex_lock(&(head)->lock)
+ ast_mutex_lock(&(head)->lock)
/*!
\brief Write locks a list.
@@ -62,7 +62,7 @@
*/
#define AST_RWLIST_RDLOCK(head) \
ast_rwlock_rdlock(&(head)->lock)
-
+
/*!
\brief Locks a list, without blocking if the list is locked.
\param head This is a pointer to the list head structure
@@ -73,7 +73,7 @@
\retval non-zero on failure
*/
#define AST_LIST_TRYLOCK(head) \
- ast_mutex_trylock(&(head)->lock)
+ ast_mutex_trylock(&(head)->lock)
/*!
\brief Write locks a list, without blocking if the list is locked.
@@ -98,7 +98,7 @@
*/
#define AST_RWLIST_TRYRDLOCK(head) \
ast_rwlock_tryrdlock(&(head)->lock)
-
+
/*!
\brief Attempts to unlock a list.
\param head This is a pointer to the list head structure
@@ -383,7 +383,7 @@ struct { \
}
#define AST_RWLIST_ENTRY AST_LIST_ENTRY
-
+
/*!
\brief Returns the first entry contained in a list.
\param head This is a pointer to the list head structure
@@ -701,6 +701,7 @@ struct { \
* \param elm Pointer to the entry to be inserted
* \param field Name of the list entry field (declared using AST_LIST_ENTRY())
* \param sortfield Name of the field on which the list is sorted
+ * \since 1.6.1
*/
#define AST_LIST_INSERT_SORTALPHA(head, elm, field, sortfield) do { \
if (!(head)->first) { \
diff --git a/include/asterisk/lock.h b/include/asterisk/lock.h
index 8b48da9b2..1b2e1813f 100644
--- a/include/asterisk/lock.h
+++ b/include/asterisk/lock.h
@@ -138,7 +138,7 @@ struct ast_lock_track {
struct ast_mutex_info {
/*! Track which thread holds this mutex */
- struct ast_lock_track track;
+ struct ast_lock_track track;
unsigned int tracking:1;
pthread_mutex_t mutex;
};
@@ -240,6 +240,8 @@ static inline void __dump_backtrace(struct ast_bt *bt, int canlog)
* that is unexpectedly but momentarily locked, and you wonder who
* are fighting with for the lock, this routine could be called, IF
* you have the thread debugging stuff turned on.
+ * \param this_lock_addr lock address to return lock information
+ * \since 1.6.1
*/
void log_show_lock(void *this_lock_addr);
@@ -367,7 +369,7 @@ static inline void delete_reentrancy_cs(struct ast_lock_track *lt)
}
static inline int __ast_pthread_mutex_init(int tracking, const char *filename, int lineno, const char *func,
- const char *mutex_name, ast_mutex_t *t)
+ const char *mutex_name, ast_mutex_t *t)
{
int res;
pthread_mutexattr_t attr;
@@ -412,7 +414,7 @@ static inline int __ast_pthread_mutex_destroy(const char *filename, int lineno,
if ((t->mutex) == ((pthread_mutex_t) PTHREAD_MUTEX_INITIALIZER)) {
/* Don't try to uninitialize non initialized mutex
* This may no effect on linux
- * And always ganerate core on *BSD with
+ * And always ganerate core on *BSD with
* linked libpthread
* This not error condition if the mutex created on the fly.
*/
@@ -491,7 +493,7 @@ static inline int __ast_pthread_mutex_lock(const char *filename, int lineno, con
__ast_mutex_logger("%s line %d (%s): Error: mutex '%s' is uninitialized and unable to initialize.\n",
filename, lineno, func, mutex_name);
return res;
- }
+ }
}
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
@@ -613,7 +615,7 @@ static inline int __ast_pthread_mutex_trylock(const char *filename, int lineno,
__ast_mutex_logger("%s line %d (%s): Error: mutex '%s' is uninitialized and unable to initialize.\n",
filename, lineno, func, mutex_name);
return res;
- }
+ }
}
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
@@ -716,7 +718,7 @@ static inline int __ast_pthread_mutex_unlock(const char *filename, int lineno, c
}
if ((res = pthread_mutex_unlock(&t->mutex))) {
- __ast_mutex_logger("%s line %d (%s): Error releasing mutex: %s\n",
+ __ast_mutex_logger("%s line %d (%s): Error releasing mutex: %s\n",
filename, lineno, func, strerror(res));
DO_THREAD_CRASH;
}
@@ -813,7 +815,7 @@ static inline int __ast_cond_wait(const char *filename, int lineno, const char *
}
if ((res = pthread_cond_wait(cond, &t->mutex))) {
- __ast_mutex_logger("%s line %d (%s): Error waiting on condition mutex '%s'\n",
+ __ast_mutex_logger("%s line %d (%s): Error waiting on condition mutex '%s'\n",
filename, lineno, func, strerror(res));
DO_THREAD_CRASH;
} else {
@@ -908,9 +910,9 @@ static inline int __ast_cond_timedwait(const char *filename, int lineno, const c
ast_remove_lock_info(t);
#endif
}
-
+
if ((res = pthread_cond_timedwait(cond, &t->mutex, abstime)) && (res != ETIMEDOUT)) {
- __ast_mutex_logger("%s line %d (%s): Error waiting on condition mutex '%s'\n",
+ __ast_mutex_logger("%s line %d (%s): Error waiting on condition mutex '%s'\n",
filename, lineno, func, strerror(res));
DO_THREAD_CRASH;
} else {
@@ -963,7 +965,18 @@ struct ast_rwlock_info {
typedef struct ast_rwlock_info ast_rwlock_t;
+/*!
+ * \brief wrapper for rwlock with tracking enabled
+ * \return 0 on success, non zero for error
+ * \since 1.6.1
+ */
#define ast_rwlock_init(rwlock) __ast_rwlock_init(1, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
+
+/*!
+ * \brief wrapper for ast_rwlock_init with tracking disabled
+ * \return 0 on success, non zero for error
+ * \since 1.6.1
+ */
#define ast_rwlock_init_notracking(rwlock) __ast_rwlock_init(0, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
#define ast_rwlock_destroy(rwlock) __ast_rwlock_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
@@ -977,7 +990,7 @@ typedef struct ast_rwlock_info ast_rwlock_t;
#ifdef HAVE_PTHREAD_RWLOCK_INITIALIZER
#define __AST_RWLOCK_INIT_VALUE PTHREAD_RWLOCK_INITIALIZER
#else /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
-#define __AST_RWLOCK_INIT_VALUE {0}
+#define __AST_RWLOCK_INIT_VALUE {0}
#endif /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
#define AST_RWLOCK_INIT_VALUE \
@@ -1027,7 +1040,7 @@ static inline int __ast_rwlock_destroy(const char *filename, int lineno, const c
return 0;
}
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
-
+
if ((res = pthread_rwlock_destroy(&t->lock))) {
__ast_mutex_logger("%s line %d (%s): Error destroying rwlock %s: %s\n",
filename, lineno, func, rwlock_name, strerror(res));
@@ -1070,7 +1083,7 @@ static inline int _ast_rwlock_unlock(ast_rwlock_t *t, const char *name,
return res;
}
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
-
+
ast_reentrancy_lock(lt);
if (lt->reentrancy) {
int lock_found = 0;
@@ -1160,13 +1173,13 @@ static inline int _ast_rwlock_rdlock(ast_rwlock_t *t, const char *name,
ast_reentrancy_lock(lt);
ast_bt_get_addresses(&lt->backtrace[lt->reentrancy]);
bt = &lt->backtrace[lt->reentrancy];
- ast_reentrancy_unlock(lt);
+ ast_reentrancy_unlock(lt);
ast_store_lock_info(AST_RDLOCK, filename, line, func, name, t, bt);
#else
ast_store_lock_info(AST_RDLOCK, filename, line, func, name, t);
#endif
}
-
+
#ifdef DETECT_DEADLOCKS
{
time_t seconds = time(NULL);
@@ -1198,7 +1211,7 @@ static inline int _ast_rwlock_rdlock(ast_rwlock_t *t, const char *name,
#else /* !DETECT_DEADLOCKS */
res = pthread_rwlock_rdlock(&t->lock);
#endif /* !DETECT_DEADLOCKS */
-
+
if (!res) {
ast_reentrancy_lock(lt);
if (lt->reentrancy < AST_MAX_REENTRANCY) {
@@ -1371,7 +1384,7 @@ static inline int _ast_rwlock_tryrdlock(ast_rwlock_t *t, const char *name,
}
}
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
-
+
if (t->tracking) {
#ifdef HAVE_BKTR
ast_reentrancy_lock(lt);
@@ -1383,7 +1396,7 @@ static inline int _ast_rwlock_tryrdlock(ast_rwlock_t *t, const char *name,
ast_store_lock_info(AST_RDLOCK, filename, line, func, name, t);
#endif
}
-
+
if (!(res = pthread_rwlock_tryrdlock(&t->lock))) {
ast_reentrancy_lock(lt);
if (lt->reentrancy < AST_MAX_REENTRANCY) {
@@ -1443,7 +1456,7 @@ static inline int _ast_rwlock_trywrlock(ast_rwlock_t *t, const char *name,
ast_store_lock_info(AST_WRLOCK, filename, line, func, name, t);
#endif
}
-
+
if (!(res = pthread_rwlock_trywrlock(&t->lock))) {
ast_reentrancy_lock(lt);
if (lt->reentrancy < AST_MAX_REENTRANCY) {
@@ -1635,7 +1648,7 @@ static void __attribute__((destructor)) fini_##mutex(void) \
ast_mutex_destroy(&mutex); \
}
#else /* !AST_MUTEX_INIT_W_CONSTRUCTORS */
-/* By default, use static initialization of mutexes. */
+/* By default, use static initialization of mutexes. */
#define __AST_MUTEX_DEFINE(scope, mutex, init_val, track) scope ast_mutex_t mutex = init_val
#endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
@@ -1733,7 +1746,7 @@ AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
{
__asm __volatile (
" lock; xaddl %0, %1 ; "
- : "+r" (v), /* 0 (result) */
+ : "+r" (v), /* 0 (result) */
"=m" (*p) /* 1 */
: "m" (*p)); /* 2 */
return (v);
@@ -1743,7 +1756,7 @@ AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
{
__asm __volatile (
" lock xaddl %0, %1 ; "
- : "+r" (v), /* 0 (result) */
+ : "+r" (v), /* 0 (result) */
"=m" (*p) /* 1 */
: "m" (*p)); /* 2 */
return (v);
@@ -1782,13 +1795,13 @@ AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
#endif
#ifndef DEBUG_CHANNEL_LOCKS
-/*! \brief Lock a channel. If DEBUG_CHANNEL_LOCKS is defined
+/*! \brief Lock a channel. If DEBUG_CHANNEL_LOCKS is defined
in the Makefile, print relevant output for debugging */
#define ast_channel_lock(x) ast_mutex_lock(&x->lock_dont_use)
-/*! \brief Unlock a channel. If DEBUG_CHANNEL_LOCKS is defined
+/*! \brief Unlock a channel. If DEBUG_CHANNEL_LOCKS is defined
in the Makefile, print relevant output for debugging */
#define ast_channel_unlock(x) ast_mutex_unlock(&x->lock_dont_use)
-/*! \brief Try locking a channel. If DEBUG_CHANNEL_LOCKS is defined
+/*! \brief Try locking a channel. If DEBUG_CHANNEL_LOCKS is defined
in the Makefile, print relevant output for debugging */
#define ast_channel_trylock(x) ast_mutex_trylock(&x->lock_dont_use)
#else
diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index 06f3f5206..65448cfe4 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -43,7 +43,7 @@ extern "C" {
#define VERBOSE_PREFIX_3 " -- "
#define VERBOSE_PREFIX_4 " > "
-/*! \brief Used for sending a log message
+/*! \brief Used for sending a log message
This is the standard logger function. Probably the only way you will invoke it would be something like this:
ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain. We should get some more. Will %d be enough?\n", "flux capacitor", 10);
where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
@@ -89,9 +89,18 @@ int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_
void ast_console_puts(const char *string);
+/*!
+ * \brief log the string to the console, and all attached
+ * console clients
+ * \version 1.6.1 added level parameter
+ */
void ast_console_puts_mutable(const char *string, int level);
void ast_console_toggle_mute(int fd, int silent);
-void ast_console_toggle_loglevel(int fd, int leve, int state);
+
+/*!
+ * \since 1.6.1
+ */
+void ast_console_toggle_loglevel(int fd, int level, int state);
/* Note: The AST_LOG_* macros below are the same as
* the LOG_* macros and are intended to eventually replace
@@ -229,7 +238,7 @@ unsigned int ast_verbose_get_by_file(const char *file);
#define AST_MAX_BT_FRAMES 32
/* \brief
*
- * A structure to hold backtrace information. This structure provides an easy means to
+ * A structure to hold backtrace information. This structure provides an easy means to
* store backtrace information or pass backtraces to other functions.
*/
struct ast_bt {
@@ -245,6 +254,7 @@ struct ast_bt {
* Allocates memory for an ast_bt and stores addresses and symbols.
*
* \return Returns NULL on failure, or the allocated ast_bt on success
+ * \since 1.6.1
*/
struct ast_bt *ast_bt_create(void);
@@ -253,14 +263,16 @@ struct ast_bt *ast_bt_create(void);
*
* \retval 0 Success
* \retval -1 Failure
+ * \since 1.6.1
*/
int ast_bt_get_addresses(struct ast_bt *bt);
/* \brief
- *
+ *
* Free dynamically allocated portions of an ast_bt
*
* \retval NULL.
+ * \since 1.6.1
*/
void *ast_bt_destroy(struct ast_bt *bt);
diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h
index 631933cc4..d9e33e538 100644
--- a/include/asterisk/manager.h
+++ b/include/asterisk/manager.h
@@ -219,6 +219,7 @@ int reload_manager(void);
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
@@ -228,6 +229,7 @@ int astman_datastore_add(struct mansession *s, struct ast_datastore *datastore);
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastore);
@@ -236,6 +238,7 @@ int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastor
*
* \retval pointer to the datastore if found
* \retval NULL if not found
+ * \since 1.6.1
*/
struct ast_datastore *astman_datastore_find(struct mansession *s, const struct ast_datastore_info *info, const char *uid);
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index f6fca62fb..c6b3c7cb8 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -921,7 +921,9 @@ int pbx_set_extenpatternmatchnew(int newval);
/*! Set "overrideswitch" field. If set and of nonzero length, all contexts
* will be tried directly through the named switch prior to any other
- * matching within that context. */
+ * matching within that context.
+ * \since 1.6.1
+ */
void pbx_set_overrideswitch(const char *newval);
/*!
diff --git a/include/asterisk/res_odbc.h b/include/asterisk/res_odbc.h
index ad22045db..db27cc583 100644
--- a/include/asterisk/res_odbc.h
+++ b/include/asterisk/res_odbc.h
@@ -159,6 +159,7 @@ SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_c
* \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
* When a structure is returned, the contained columns list will be
* rdlock'ed, to ensure that it will be retained in memory.
+ * \since 1.6.1
*/
struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename);
@@ -167,6 +168,7 @@ struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *
* \param table Cached table structure, as returned from ast_odbc_find_table()
* \param colname The column name requested
* \retval A structure describing the column type, or NULL, if the column is not found.
+ * \since 1.6.1
*/
struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
@@ -175,6 +177,7 @@ struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table,
* \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
* \param table Tablename for which a cached record should be removed
* \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
+ * \since 1.6.1
*/
int ast_odbc_clear_cache(const char *database, const char *tablename);
diff --git a/include/asterisk/rtp.h b/include/asterisk/rtp.h
index 800519572..b6a31d30b 100644
--- a/include/asterisk/rtp.h
+++ b/include/asterisk/rtp.h
@@ -277,13 +277,19 @@ int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, i
having to send a re-invite later */
int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
-/*! \brief Get QOS stats on a RTP channel */
+/*! \brief Get QOS stats on a RTP channel
+ * \since 1.6.1
+ */
int ast_rtp_get_qos(struct ast_rtp *rtp, const char *qos, char *buf, unsigned int buflen);
-/*! \brief Return RTP and RTCP QoS values */
+/*! \brief Return RTP and RTCP QoS values
+ * \since 1.6.1
+ */
unsigned int ast_rtp_get_qosvalue(struct ast_rtp *rtp, enum ast_rtp_qos_vars value);
-/*! \brief Set RTPAUDIOQOS(...) variables on a channel when it is being hung up */
+/*! \brief Set RTPAUDIOQOS(...) variables on a channel when it is being hung up
+ * \since 1.6.1
+ */
void ast_rtp_set_vars(struct ast_channel *chan, struct ast_rtp *rtp);
/*! \brief Return RTCP quality string
@@ -305,6 +311,7 @@ void ast_rtp_set_vars(struct ast_channel *chan, struct ast_rtp *rtp);
* other types are RTPQOS_JITTER, RTPQOS_LOSS and
* RTPQOS_RTT which will return more specific
* statistics.
+ * \version 1.6.1 added qtype parameter
*/
char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual, enum ast_rtp_quality_type qtype);
/*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message in SIP */
@@ -343,12 +350,10 @@ void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
* \param red_pt payloadtype for RTP packet
* \param pt payloadtype numbers for each generation including primary data
* \param num_gen number of redundant generations, primary data excluded
+ * \since 1.6.1
*/
int rtp_red_init(struct ast_rtp *rtp, int ti, int *pt, int num_gen);
-void red_init(struct rtp_red *red, const struct ast_frame *f);
-
-
/*! \brief Buffer t.140 data */
void red_buffer_t140(struct ast_rtp *rtp, struct ast_frame *f);
diff --git a/include/asterisk/sched.h b/include/asterisk/sched.h
index 6508da41e..63ea80bd4 100644
--- a/include/asterisk/sched.h
+++ b/include/asterisk/sched.h
@@ -59,6 +59,11 @@ extern "C" {
id = -1; \
} while (0);
+/*!
+ * \brief schedule task to get deleted and call unref function
+ * \sa AST_SCHED_DEL
+ * \since 1.6.1
+ */
#define AST_SCHED_DEL_UNREF(sched, id, refcall) \
do { \
int _count = 0; \
@@ -72,6 +77,10 @@ extern "C" {
id = -1; \
} while (0);
+/*!
+ * \brief schedule task to get deleted releasing the lock between attempts
+ * \since 1.6.1
+ */
#define AST_SCHED_DEL_SPINLOCK(sched, id, lock) \
({ \
int _count = 0; \
@@ -102,6 +111,10 @@ extern "C" {
#define AST_SCHED_REPLACE(id, sched, when, callback, data) \
AST_SCHED_REPLACE_VARIABLE(id, sched, when, callback, data, 0)
+/*!
+ * \note Not currently used in the source?
+ * \since 1.6.1
+ */
#define AST_SCHED_REPLACE_VARIABLE_UNREF(id, sched, when, callback, data, variable, unrefcall, addfailcall, refcall) \
do { \
int _count = 0, _res=1; \
@@ -150,6 +163,14 @@ struct ast_cb_names {
char *list[10];
ast_sched_cb cblist[10];
};
+
+/*!
+ * \brief Show statics on what it is in the schedule queue
+ * \param con Schedule context to check
+ * \param buf dynamic string to store report
+ * \param cbnames to check against
+ * \since 1.6.1
+ */
void ast_sched_report(struct sched_context *con, struct ast_str **buf, struct ast_cb_names *cbnames);
/*! \brief Adds a scheduled event
@@ -207,10 +228,12 @@ int ast_sched_add_variable(struct sched_context *con, int when, ast_sched_cb cal
int ast_sched_replace_variable(int old_id, struct sched_context *con, int when, ast_sched_cb callback, const void *data, int variable) attribute_warn_unused_result;
-/*! \brief Find a sched structure and return the data field associated with it.
+/*!
+ * \brief Find a sched structure and return the data field associated with it.
* \param con scheduling context in which to search fro the matching id
* \param id ID of the scheduled item to find
* \return the data field from the matching sched struct if found; else return NULL if not found.
+ * \since 1.6.1
*/
const void *ast_sched_find_data(struct sched_context *con, int id);
diff --git a/include/asterisk/taskprocessor.h b/include/asterisk/taskprocessor.h
index 72d810c26..6929b8fb4 100644
--- a/include/asterisk/taskprocessor.h
+++ b/include/asterisk/taskprocessor.h
@@ -70,7 +70,9 @@ enum ast_tps_options {
* \param create Use 0 by default or specify TPS_REF_IF_EXISTS to return NULL if the taskprocessor does
* not already exist
* return A pointer to a reference counted taskprocessor under normal conditions, or NULL if the
- * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist */
+ * TPS_REF_IF_EXISTS reference type is specified and the taskprocessor does not exist
+ * \since 1.6.1
+ */
struct ast_taskprocessor *ast_taskprocessor_get(char *name, enum ast_tps_options create);
/*! \brief Unreference the specified taskprocessor and its reference count will decrement.
@@ -78,17 +80,23 @@ struct ast_taskprocessor *ast_taskprocessor_get(char *name, enum ast_tps_options
* Taskprocessors use astobj2 and will unlink from the taskprocessor singleton container and destroy
* themself when the taskprocessor reference count reaches zero.
* \param tps taskprocessor to unreference
- * \return NULL */
+ * \return NULL
+ * \since 1.6.1
+ */
void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps);
/*! \brief Push a task into the specified taskprocessor queue and signal the taskprocessor thread
* \param tps The taskprocessor structure
* \param task_exe The task handling function to push into the taskprocessor queue
* \param datap The data to be used by the task handling function
- * \return zero on success, -1 on failure */
+ * \return zero on success, -1 on failure
+ * \since 1.6.1
+ */
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap);
-/*! \brief Return the name of the taskprocessor singleton */
+/*! \brief Return the name of the taskprocessor singleton
+ * \since 1.6.1
+ */
const char *ast_taskprocessor_name(struct ast_taskprocessor *tps);
#endif
diff --git a/include/asterisk/tcptls.h b/include/asterisk/tcptls.h
index 226e2ad59..a6f71b751 100644
--- a/include/asterisk/tcptls.h
+++ b/include/asterisk/tcptls.h
@@ -149,10 +149,27 @@ struct ast_tcptls_session_instance {
#define LEN_T size_t
#endif
+/*!
+ * \brief A generic client routine for a TCP client
+ * and starts a thread for handling accept()
+ * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
+ */
struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_args *desc);
void *ast_tcptls_server_root(void *);
+
+/*!
+ * \brief This is a generic (re)start routine for a TCP server,
+ * which does the socket/bind/listen and starts a thread for handling
+ * accept().
+ * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
+ */
void ast_tcptls_server_start(struct ast_tcptls_session_args *desc);
+
+/*!
+ * \brief Shutdown a running server if there is one
+ * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
+ */
void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc);
int ast_ssl_setup(struct ast_tls_config *cfg);
diff --git a/include/asterisk/timing.h b/include/asterisk/timing.h
index 0bfb527f7..c9a8fcba9 100644
--- a/include/asterisk/timing.h
+++ b/include/asterisk/timing.h
@@ -89,6 +89,7 @@ struct ast_timing_interface {
*
* \retval NULL failure
* \retval non-Null handle to be passed to ast_unregister_timing_interface() on success
+ * \since 1.6.1
*/
#define ast_register_timing_interface(i) _ast_register_timing_interface(i, ast_module_info->self)
void *_ast_register_timing_interface(struct ast_timing_interface *funcs,
@@ -102,6 +103,7 @@ void *_ast_register_timing_interface(struct ast_timing_interface *funcs,
*
* \retval 0 success
* \retval non-zero failure
+ * \since 1.6.1
*/
int ast_unregister_timing_interface(void *handle);
@@ -110,6 +112,7 @@ int ast_unregister_timing_interface(void *handle);
*
* \retval -1 error, with errno set
* \retval >=0 success
+ * \since 1.6.1
*/
int ast_timer_open(void);
@@ -119,6 +122,7 @@ int ast_timer_open(void);
* \param handle timing fd returned from timer_open()
*
* \return nothing
+ * \since 1.6.1
*/
void ast_timer_close(int handle);
@@ -134,6 +138,7 @@ void ast_timer_close(int handle);
*
* \retval -1 error, with errno set
* \retval 0 success
+ * \since 1.6.1
*/
int ast_timer_set_rate(int handle, unsigned int rate);
@@ -147,6 +152,7 @@ int ast_timer_set_rate(int handle, unsigned int rate);
* returned AST_TIMING_EVENT_EXPIRED.
*
* \return nothing
+ * \since 1.6.1
*/
void ast_timer_ack(int handle, unsigned int quantity);
@@ -160,6 +166,7 @@ void ast_timer_ack(int handle, unsigned int quantity);
*
* \retval -1 failure, with errno set
* \retval 0 success
+ * \since 1.6.1
*/
int ast_timer_enable_continuous(int handle);
@@ -170,6 +177,7 @@ int ast_timer_enable_continuous(int handle);
*
* \retval -1 failure, with errno set
* \retval 0 success
+ * \since 1.6.1
*/
int ast_timer_disable_continuous(int handle);
@@ -182,6 +190,7 @@ int ast_timer_disable_continuous(int handle);
* be called to find out what triggered it.
*
* \return which event triggered the timing fd
+ * \since 1.6.1
*/
enum ast_timer_event ast_timer_get_event(int handle);
@@ -191,6 +200,7 @@ enum ast_timer_event ast_timer_get_event(int handle);
* \param handle timing fd returned by timer_open()
*
* \return maximum rate supported for timing handle
+ * \since 1.6.1
*/
unsigned int ast_timer_get_max_rate(int handle);
diff --git a/include/asterisk/udptl.h b/include/asterisk/udptl.h
index 0d9e8d803..4d6b89068 100644
--- a/include/asterisk/udptl.h
+++ b/include/asterisk/udptl.h
@@ -118,6 +118,9 @@ void ast_udptl_stop(struct ast_udptl *udptl);
void ast_udptl_init(void);
+/*!
+ * \version 1.6.1 return changed to int
+ */
int ast_udptl_reload(void);
#if defined(__cplusplus) || defined(c_plusplus)
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index ee8bbd511..c2c88cca2 100644
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -705,11 +705,13 @@ extern struct ast_eid g_eid;
/*!
* \brief Fill in an ast_eid with the default eid of this machine
+ * \since 1.6.1
*/
void ast_set_default_eid(struct ast_eid *eid);
/*!
* /brief Convert an EID to a string
+ * \since 1.6.1
*/
char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
@@ -720,6 +722,7 @@ char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
* 00:11:22:33:44:55
*
* \return 0 success, non-zero failure
+ * \since 1.6.1
*/
int ast_str_to_eid(struct ast_eid *eid, const char *s);
@@ -727,6 +730,7 @@ int ast_str_to_eid(struct ast_eid *eid, const char *s);
* \brief Compare two EIDs
*
* \return 0 if the two are the same, non-zero otherwise
+ * \since 1.6.1
*/
int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-27 08:45:15 +0000