[asterisk-commits] rmudgett: branch group/CCSS r237965 - /team/group/CCSS/include/asterisk/ccss.h
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Jan 5 18:18:11 CST 2010
Author: rmudgett
Date: Tue Jan 5 18:18:08 2010
New Revision: 237965
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=237965
Log:
Doxygen comment changes.
Modified:
team/group/CCSS/include/asterisk/ccss.h
Modified: team/group/CCSS/include/asterisk/ccss.h
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/include/asterisk/ccss.h?view=diff&rev=237965&r1=237964&r2=237965
==============================================================================
--- team/group/CCSS/include/asterisk/ccss.h (original)
+++ team/group/CCSS/include/asterisk/ccss.h Tue Jan 5 18:18:08 2010
@@ -94,6 +94,7 @@
* \since 1.8
* \brief Queue an AST_CONTROL_CC frame
*
+ * \note
* Since this function calls ast_queue_frame, the channel will be
* locked during the course of this function.
*
@@ -110,6 +111,7 @@
/*!
* \brief Allocate and initialize an ast_cc_config_params structure
*
+ * \note
* Reasonable default values are chosen for the parameters upon allocation.
*
* \retval NULL Unable to allocate the structure
@@ -117,11 +119,21 @@
*/
struct ast_cc_config_params *__ast_cc_config_params_init(const char *file, int line, const char *function);
+/*!
+ * \brief Allocate and initialize an ast_cc_config_params structure
+ *
+ * \note
+ * Reasonable default values are chosen for the parameters upon allocation.
+ *
+ * \retval NULL Unable to allocate the structure
+ * \retval non-NULL A pointer to the newly allocated and initialized structure
+ */
#define ast_cc_config_params_init() __ast_cc_config_params_init(__FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Free memory from CCSS configuration params
*
+ * \note
* Just a call to ast_free for now...
*
* \param params Pointer to structure whose memory we need to free
@@ -132,6 +144,7 @@
/*!
* \brief set a CCSS configuration parameter, given its name
*
+ * \note
* Useful when parsing config files when used in conjunction
* with ast_ccss_is_cc_config_param.
*
@@ -147,6 +160,7 @@
/*!
* \brief get a CCSS configuration parameter, given its name
*
+ * \note
* Useful when reading input as a string, like from dialplan or
* manager.
*
@@ -173,6 +187,7 @@
* \since 1.8
* \brief copy CCSS configuration parameters from one structure to another
*
+ * \details
* For now, this is a simple memcpy, but this function is necessary since
* the size of an ast_cc_config_params structure is unknown outside of
* main/ccss.c. Also, this allows for easier expansion of the function in
@@ -333,6 +348,7 @@
* \since 1.8
* \brief Register a set of monitor callbacks with the core
*
+ * \details
* This is made so that at monitor creation time, the proper callbacks
* may be installed and the proper .init callback may be called for the
* monitor to establish private data.
@@ -349,6 +365,7 @@
* \since 1.8
* \brief Register a set of agent callbacks with the core
*
+ * \details
* This is made so that at agent creation time, the proper callbacks
* may be installed and the proper .init callback may be called for the
* monitor to establish private data.
@@ -377,6 +394,7 @@
* \brief a link that connects two monitors in the weighted graph of
* monitor structures.
*
+ * \details
* The parent and child pointers are ao2 objects. This way, when a
* monitor has no more links pointing to it, it will be automatically
* destroyed.
@@ -399,9 +417,10 @@
/* Which service is being requested? */
enum ast_cc_service_type service;
/*!
- * An ID for the available timer for a corresponding child device
+ * \brief An ID for the available timer of a corresponding child device
* monitor.
*
+ * \details
* Really, it would seem a bit more logical to have this
* ID reside on the monitor itself, but as far as ease-of-coding
* is concerned, links already exist as something unique per
@@ -442,6 +461,7 @@
/*!
* \brief Structure that represents a CCSS monitor
+ * \details
* Both extension and device monitors will be represented
* with this structure. Information specific to each monitor
* type can be retrieved through the monitor_data union.
@@ -471,23 +491,27 @@
struct ast_cc_monitor_callbacks {
/*!
- * Type of the monitor callbacks
- *
+ * \brief Type of the monitor callbacks
+ *
+ * \note
* Examples include "generic" and "SIP"
*/
const char *type;
/*!
- * Init callback
- *
- * Implementors must allocate the monitor's private_data
+ * \brief Init callback
+ *
+ * \details
+ * Implementers must allocate the monitor's private_data
* and initialize it to whatever may be necessary.
*
- * Return 0 on success and -1 on failure.
+ * \retval 0 on success
+ * \retval -1 on failure.
*/
int (*init)(struct ast_cc_monitor *monitor, const int core_id);
/*!
- * Request CCSS callback
- *
+ * \brief Request CCSS callback
+ *
+ * \details
* Perform whatever steps are necessary in order to request CC.
* In addition, the monitor implementation is responsible for
* starting the available timer in this callback. The scheduler
@@ -496,29 +520,32 @@
*/
int (*request_cc)(struct ast_cc_monitor *monitor, const int core_id, struct ast_cc_monitor_link *parent_link);
/*!
- * Suspend monitoring callback
- *
- * Implementors must perform the necessary steps to suspend
+ * \brief Suspend monitoring callback
+ *
+ * \details
+ * Implementers must perform the necessary steps to suspend
* monitoring.
*/
int (*suspend)(struct ast_cc_monitor *monitor, const int core_id);
/*!
- * Status response callback
- *
+ * \brief Status response callback
+ *
+ * \details
* Alert a monitor as to the status of the agent for which
* the monitor had previously requested a status request.
- *
*/
int (*status_response)(struct ast_cc_monitor *monitor, const int core_id, enum ast_device_state devstate);
/*!
- * Unsuspend monitoring callback
- *
+ * \brief Unsuspend monitoring callback
+ *
+ * \details
* Perform the necessary steps to unsuspend monitoring.
*/
int (*unsuspend)(struct ast_cc_monitor *monitor, const int core_id);
/*!
- * Cancel the running available timer.
- *
+ * \brief Cancel the running available timer.
+ *
+ * \details
* In most cases, this function will likely consist of just a
* call to AST_SCHED_DEL. It might have been possible to do this
* within the core, but unfortunately the mixture of sched_thread
@@ -526,30 +553,33 @@
*/
int (*cancel_available_timer)(struct ast_cc_monitor *monitor, const int core_id, int *sched_id);
/*!
- * Destroy callback
- *
- * Implementors of this callback are responsible for destroying
+ * \brief Destroy callback
+ *
+ * \details
+ * Implementers of this callback are responsible for destroying
* all heap-allocated data in the monitor's private_data pointer, including
* the private_data itself.
*/
- void (*destructor)(void *monitor);
- /*!
- * Instance destroy callback
- *
- * This callback is called when a specific call completion transaction
- * fails or completes. The main difference between this and the monitor destructor
- * is that this will be called for every CC call that occurs, whereas the destructor
- * function is only called when all activities on a monitor are completed. To drive
- * the point home, this destructor only has a core ID as a parameter. Use this to
- * locate the correct data to destroy.
- */
- void (*instance_destructor)(const int core_id);
+ void (*destructor)(void *monitor);
+ /*!
+ * \brief Instance destroy callback
+ *
+ * \details
+ * This callback is called when a specific call completion transaction
+ * fails or completes. The main difference between this and the monitor destructor
+ * is that this will be called for every CC call that occurs, whereas the destructor
+ * function is only called when all activities on a monitor are completed. To drive
+ * the point home, this destructor only has a core ID as a parameter. Use this to
+ * locate the correct data to destroy.
+ */
+ void (*instance_destructor)(const int core_id);
};
/*!
* \since 1.8
* \brief Scheduler callback for available timer expiration
*
+ * \note
* When arming the available timer from within a device monitor, you MUST
* use this function as the callback for the scheduler.
*
@@ -567,6 +597,7 @@
*
* \brief Mark the channel to ignore further CC activity.
*
+ * \details
* When a CC-capable application, such as Dial, has finished
* with all CC processing for a channel and knows that any further
* CC processing should be ignored, this function should be called.
@@ -581,6 +612,7 @@
*
* \brief Set the dialable name for an extension
*
+ * \details
* An extension will look like "exten at context." But when it
* comes time to dial the extension again, what we actually will
* need to dial may be "Local/exten at context" or "Local/exten at context/n"
@@ -598,6 +630,7 @@
*
* \brief Properly react to a CC control frame.
*
+ * \details
* When a CC-capable application, such as Dial, receives a frame
* of type AST_CONTROL_CC, then it may call this function in order
* to have the device which sent the frame added to the tree of interfaces
@@ -615,6 +648,7 @@
*
* \brief Start the CC process on a call.
*
+ * \details
* Whenever a CC-capable application, such as Dial, wishes to
* engage in CC activity, it initiates the process by calling this
* function. If the CC core should discover that a previous application
@@ -637,6 +671,7 @@
* \brief Check if the incoming CC request is within the bounds
* set by the cc_max_requests configuration option
*
+ * \details
* It is recommended that an entity which receives an incoming
* CC request calls this function before calling
* ast_cc_agent_accept_request. This way, immediate feedback can be
@@ -656,6 +691,7 @@
* \since 1.8
* \brief Get the core id for the current call
*
+ * \details
* The main use of this function is for channel drivers
* who queue an AST_CONTROL_CC frame. A channel driver may
* call this function in order to get the core_id for what
@@ -667,7 +703,7 @@
* channel. Both will have the necessary info on it.
*
* \param chan The channel from which to get the core_id.
- * \retval 0 Success
+ * \retval core_id on success
* \retval -1 Failure
*/
int ast_cc_get_current_core_id(struct ast_channel *chan);
@@ -677,6 +713,7 @@
/*!
* \brief Structure with information about an outbound interface
*
+ * \details
* This structure is first created when an outbound interface indicates that
* it is capable of accepting a CC request. It is stored in a "tree" on a datastore on
* the caller's channel. Once an agent structure is created, the agent gains
@@ -684,7 +721,7 @@
* interface tree on the agent is converted into a tree of monitors. Each
* monitor will contain a pointer to an individual ast_cc_interface. Finally,
* the tree of interfaces is also present on a second datastore during a
- * CC recall so thta the CC_INTERFACES channel variable may be properly
+ * CC recall so that the CC_INTERFACES channel variable may be properly
* populated.
*/
struct ast_cc_interface {
@@ -692,9 +729,10 @@
*/
enum ast_cc_monitor_class monitor_class;
/*!
- * The type of monitor that should be used for this interface
- *
- * This will be something like "extension" "generic" or "SIP"
+ * \brief The type of monitor that should be used for this interface
+ *
+ * \details
+ * This will be something like "extension" "generic" or "SIP".
* This should point to a static const char *, so there is
* no reason to make a new copy.
*/
@@ -729,8 +767,9 @@
*/
struct ast_cc_config_params *cc_params;
/*!
- * \The "tree" of interfaces dialed by the caller
- *
+ * \brief The "tree" of interfaces dialed by the caller
+ *
+ * \details
* In actuality, this is a linked list. Each element
* contains an integer which tells who its parent is
* in the tree. The tree is arranged in such a way that
@@ -740,8 +779,9 @@
*/
struct ast_cc_interface_tree *interface_tree;
/*!
- * \flags for agent operation
- *
+ * \brief Flags for agent operation
+ *
+ * \details
* There are some attributes of certain agent types
* that can alter the behavior of certain CC functions.
* For a list of these flags, see the ast_cc_agent_flags
@@ -760,12 +800,14 @@
/*!
* \brief Type of agent the callbacks belong to.
*
+ * \note
* Examples are "SIP" "ISDN" and "generic"
*/
const char *type;
/*!
* \brief Initialization callback.
*
+ * \details
* This callback is called when the CC core
* is initialized. Agents should allocate
* any private data necessary for the
@@ -778,6 +820,7 @@
/*!
* \brief Offer CC to caller
*
+ * \details
* This is called separately as each callee announces
* his ability to accept CC. The agent's behavior will
* likely vary widely between implementations. For instance,
@@ -793,6 +836,7 @@
/*!
* \brief Start the offer timer
*
+ * \details
* This is called by the core when the caller hangs up after
* a call for which CC may be requested. The agent should
* begin the timer as configured.
@@ -808,6 +852,7 @@
/*!
* \brief Stop the offer timer
*
+ * \details
* This callback is called by the CC core when the caller
* has requested CC.
*/
@@ -815,6 +860,7 @@
/*!
* \brief Acknowledge CC request callback.
*
+ * \details
* When the core receives knowledge that a called
* party has accepted a CC request, it will call
* this callback.
@@ -826,6 +872,7 @@
/*!
* \brief Request the status of the agent's device
*
+ * \details
* Asynchronous request for the status of any caller
* which may be a valid caller for the CC transaction.
* Status responses should be made using the
@@ -835,6 +882,7 @@
/*!
* \brief Request for an agent's phone to stop ringing
*
+ * \details
* The usefulness of this is quite limited. The only specific
* known case for this is if Asterisk requests CC over an ISDN
* PTMP link as the TE side. If other phones are in the same
@@ -853,6 +901,7 @@
* but that the caller cannot attempt to call back because
* he is either busy or there is congestion on his line.
*
+ * \details
* This is something that really only affects a scenario where
* a phone places a call over ISDN PTMP to Asterisk, who then
* connects over PTMP again to the ISDN network. For most agent
@@ -866,6 +915,7 @@
/*!
* \brief Begin monitoring a busy device
*
+ * \details
* The core will call this callback if the callee becomes
* available but the caller has reported that he is busy.
* The agent should begin monitoring the caller's device.
@@ -876,6 +926,7 @@
/*!
* \brief Alert the caller that it is time to try recalling.
*
+ * \details
* The core will call this function when it receives notice
* that a monitored party has become available.
*
@@ -889,6 +940,7 @@
/*!
* \brief Destroy private data on the agent
*
+ * \details
* The core will call this function upon completion
* or failure of CC.
*/
@@ -898,6 +950,7 @@
/*!
* \brief Call a callback on all agents of a specific type
*
+ * \details
* Since the container of CC core instances is private, and so
* are the items which the container contains, we have to provide
* an ao2_callback-like method so that a specific agent may be
@@ -921,6 +974,7 @@
* \since 1.8
* \brief Offer CC to a caller
*
+ * \details
* This function is called from ast_hangup if the caller is
* eligible to be offered call completion service.
*
@@ -939,6 +993,7 @@
* \since 1.8
* \brief Accept inbound CC request
*
+ * \details
* When a caller requests CC, this function should be called to let
* the core know that the request has been accepted.
*
@@ -953,6 +1008,7 @@
* \since 1.8
* \brief Indicate that an outbound entity has accepted our CC request
*
+ * \details
* When we receive confirmation that an outbound device has accepted the
* CC request we sent it, this function must be called.
*
@@ -967,6 +1023,7 @@
* \since 1.8
* \brief Indicate that the caller is busy
*
+ * \details
* When the callee makes it known that he is available, the core
* will let the caller's channel driver know that it may attempt
* to let the caller know to attempt a recall. If the channel
@@ -974,7 +1031,7 @@
* the channel driver should call this function to let the CC
* core know.
*
- * \param core_id cor_id of the CC transaction
+ * \param core_id core_id of the CC transaction
* \param debug optional string to print for debugging purposes
* \retval 0 Success
* \retval -1 Failure
@@ -985,6 +1042,7 @@
* \since 1.8
* \brief Indicate that a previously unavailable caller has become available
*
+ * \details
* If a monitor is suspended due to a caller becoming unavailable, then this
* function should be called to indicate that the caller has become available.
*
@@ -999,6 +1057,7 @@
* \since 1.8
* \brief Tell the CC core that a caller is currently recalling
*
+ * \details
* The main purpose of this is so that the core can alert the monitor
* to stop its available timer since the caller has begun its recall
* phase.
@@ -1014,6 +1073,7 @@
* \since 1.8
* \brief Indicate recall has been acknowledged
*
+ * \details
* When we receive confirmation that an endpoint has responded to our
* CC recall, we call this function.
*
@@ -1028,6 +1088,7 @@
* \since 1.8
* \brief Indicate failure has occurred
*
+ * \details
* If at any point a failure occurs, this is the function to call
* so that the core can initiate cleanup procedures.
*
@@ -1042,6 +1103,7 @@
* \since 1.8
* \brief Indicate that a failure has occurred on a specific monitor
*
+ * \details
* If a monitor should detect that a failure has occurred when communicating
* with its endpoint, then ast_cc_monitor_failed should be called. The big
* difference between ast_cc_monitor_failed and ast_cc_failed is that ast_cc_failed
@@ -1063,7 +1125,7 @@
/* END STATE CHANGE API */
/* The following are all functions which are required due to the unique
- * case where Asterisk is is acting as the NT side of an ISDN PTMP
+ * case where Asterisk is acting as the NT side of an ISDN PTMP
* connection to the caller and as the TE side of an ISDN PTMP connection
* to the callee. In such a case, there are several times where the
* PTMP monitor needs information from the agent in order to formulate
@@ -1073,6 +1135,7 @@
/*!
* \brief Request the status of a caller or callers.
*
+ * \details
* When an ISDN PTMP monitor senses that the callee has become
* available, it needs to know the current status of the caller
* in order to determine the appropriate response to send to
@@ -1087,6 +1150,7 @@
/*!
* \brief Response with a caller's current status
*
+ * \details
* When an ISDN PTMP monitor requests the caller's status, the
* agent must respond to the request using this function. For
* simplicity it is recommended that the devstate parameter
@@ -1102,6 +1166,7 @@
/*!
* \brief Alert a caller to stop ringing
*
+ * \details
* When an ISDN PTMP monitor becomes available, it is assumed
* that the agent will then cause the caller's phone to ring. In
* some cases, this is literally what happens. In other cases, it may
@@ -1123,7 +1188,8 @@
/*!
* \brief Alert a caller that though the callee has become free, the caller
* himself is not and may not call back.
- *
+ *
+ * \details
* When an ISDN PTMP monitor senses that his monitored party has become
* available, he will request the status of the called party. If he determines
* that the caller is currently not available, then he will call this function
@@ -1161,6 +1227,7 @@
* \since 1.8
* \brief Alert the core that a device being monitored has become available.
*
+ * \note
* The code in the core will take care of making sure that the information gets passed
* up the ladder correctly.
*
@@ -1178,11 +1245,12 @@
* \since 1.8
* \brief Set up a CC recall datastore on a channel
*
- * Implementors of protocol-specific CC agents will need to call this
+ * \details
+ * Implementers of protocol-specific CC agents will need to call this
* function in order for the channel to have the necessary interfaces
* to recall.
*
- * This function must be called by the implementor once it has been detected
+ * This function must be called by the implementer once it has been detected
* that an inbound call is a cc_recall. After allocating the channel, call this
* function, followed by ast_cc_set_cc_interfaces_chanvar. While it would be nice to
* be able to have the core do this automatically, it just cannot be done given
@@ -1194,6 +1262,7 @@
* \since 1.8
* \brief Decide if a call to a particular channel is a CC recall
*
+ * \details
* When a CC recall happens, it is important on the called side to
* know that the call is a CC recall and not a normal call. This function
* will determine first if the call in question is a CC recall. Then it
@@ -1209,7 +1278,7 @@
* channel were passed into this function, then the return would be 0 since
* SIP/2000 was not one of the original devices dialed.
*
- * Note also that this function may be called on a calling channel as well to
+ * \note This function may be called on a calling channel as well to
* determine if it is part of a CC recall.
*
* \param chan The channel to check
@@ -1224,9 +1293,11 @@
* \since 1.8
* \brief Set the CC_INTERFACES channel variable for a channel
*
- * Implementors of protocol-specific CC agents should call this function after
+ * \note
+ * Implementers of protocol-specific CC agents should call this function after
* calling ast_setup_cc_recall_datastore.
*
+ * \details
* The CC_INTERFACES channel variable will have the interfaces that should be
* called back for a specific PBX instance.
*/
@@ -1236,6 +1307,7 @@
* \since 1.8
* \brief Callback made from ast_cc_callback for certain channel types
*
+ * \details
* For channel types that fail ast_request when the device is busy, we call into the
* channel driver with ast_cc_callback. This is the callback that is called in that
* case for each device found which could have been returned by ast_request.
@@ -1258,6 +1330,7 @@
* \since 1.8
* \brief Create a CC Control frame
*
+ * \details
* chan_dahdi is weird. It doesn't seem to actually queue frames when it needs to tell
* an application something. Instead it wakes up, tells the application that it has data
* ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
@@ -1266,7 +1339,7 @@
* \param chan A channel involved in the call. What we want is on a datastore on both incoming and outgoing so either may be provided
* \param cc_params The CC configuration parameters for the outbound target
* \param interface_name The name of the outbound target
- * \param dialable_name The dialstring used when calling this specific interface
+ * \param dialable_name The dial string used when calling this specific interface
* \param[out] frame. The frame we will be returning to the caller. It is vital that ast_frame_free be called on this frame since the
* payload will be allocated on the heap.
* \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
@@ -1283,6 +1356,7 @@
* \since 1.8
* \brief Run a callback for potential matching destinations.
*
+ * \note
* See the explanation in ast_channel_tech::cc_callback for more
* details.
*
More information about the asterisk-commits
mailing list