Sat Aug 6 00:39:28 2011

Asterisk developer's documentation


devicestate.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Device state management
00021  */
00022 
00023 #ifndef _ASTERISK_DEVICESTATE_H
00024 #define _ASTERISK_DEVICESTATE_H
00025 
00026 #if defined(__cplusplus) || defined(c_plusplus)
00027 extern "C" {
00028 #endif
00029 
00030 enum ast_device_state {
00031    AST_DEVICE_UNKNOWN,      /*!< Device is valid but channel didn't know state */
00032    AST_DEVICE_NOT_INUSE,    /*!< Device is not used */
00033    AST_DEVICE_INUSE,        /*!< Device is in use */
00034    AST_DEVICE_BUSY,         /*!< Device is busy */
00035    AST_DEVICE_INVALID,      /*!< Device is invalid */
00036    AST_DEVICE_UNAVAILABLE,  /*!< Device is unavailable */
00037    AST_DEVICE_RINGING,      /*!< Device is ringing */
00038    AST_DEVICE_RINGINUSE,    /*!< Device is ringing *and* in use */
00039    AST_DEVICE_ONHOLD,       /*!< Device is on hold */
00040    AST_DEVICE_TOTAL,        /*!< Total num of device states, used for testing */
00041 };
00042 
00043 /*! \brief Devicestate watcher call back */
00044 typedef int (*ast_devstate_cb_type)(const char *dev, int state, void *data);
00045 
00046 /*!  \brief Devicestate provider call back */
00047 typedef int (*ast_devstate_prov_cb_type)(const char *data);
00048 
00049 /*! \brief Convert device state to text string for output 
00050  * \param devstate Current device state 
00051  */
00052 const char *devstate2str(enum ast_device_state devstate);
00053 
00054 /*! \brief Search the Channels by Name
00055  * \param device like a dialstring
00056  * Search the Device in active channels by compare the channelname against 
00057  * the devicename. Compared are only the first chars to the first '-' char.
00058  * Returns an AST_DEVICE_UNKNOWN if no channel found or
00059  * AST_DEVICE_INUSE if a channel is found
00060  */
00061 int ast_parse_device_state(const char *device);
00062 
00063 /*! \brief Asks a channel for device state
00064  * \param device like a dialstring
00065  * Asks a channel for device state, data is  normaly a number from dialstring
00066  * used by the low level module
00067  * Trys the channel devicestate callback if not supported search in the
00068  * active channels list for the device.
00069  * Returns an AST_DEVICE_??? state -1 on failure
00070  */
00071 int ast_device_state(const char *device);
00072 
00073 /*! \brief Tells Asterisk the State for Device is changed
00074  * \param fmt devicename like a dialstring with format parameters
00075  * Asterisk polls the new extensionstates and calls the registered
00076  * callbacks for the changed extensions
00077  * Returns 0 on success, -1 on failure
00078  */
00079 int ast_device_state_changed(const char *fmt, ...)
00080    __attribute__((format(printf, 1, 2)));
00081 
00082 
00083 /*! \brief Tells Asterisk the State for Device is changed 
00084  * \param device devicename like a dialstring
00085  * Asterisk polls the new extensionstates and calls the registered
00086  * callbacks for the changed extensions
00087  * Returns 0 on success, -1 on failure
00088  */
00089 int ast_device_state_changed_literal(const char *device);
00090 
00091 /*! \brief Registers a device state change callback 
00092  * \param callback Callback
00093  * \param data to pass to callback
00094  * The callback is called if the state for extension is changed
00095  * Return -1 on failure, ID on success
00096  */ 
00097 int ast_devstate_add(ast_devstate_cb_type callback, void *data);
00098 
00099 /*! \brief Unregisters a device state change callback 
00100  * \param callback Callback
00101  * \param data to pass to callback
00102  * The callback is called if the state for extension is changed
00103  * Return -1 on failure, ID on success
00104  */ 
00105 void ast_devstate_del(ast_devstate_cb_type callback, void *data);
00106 
00107 /*! \brief Add device state provider 
00108  * \param label to use in hint, like label:object
00109  * \param callback Callback
00110  * \retval -1 failure
00111  * \retval 0 success
00112  */ 
00113 int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback);
00114 
00115 /*! \brief Remove device state provider 
00116  * \param label to use in hint, like label:object
00117  * \return nothing
00118  */ 
00119 void ast_devstate_prov_del(const char *label);
00120 
00121 /*!
00122  * \brief An object to hold state when calculating aggregate device state
00123  */
00124 struct ast_devstate_aggregate;
00125 
00126 /*!
00127  * \brief Initialize aggregate device state
00128  *
00129  * \param[in] agg the state object
00130  *
00131  * \return nothing
00132  */
00133 void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
00134 
00135 /*!
00136  * \brief Add a device state to the aggregate device state
00137  *
00138  * \param[in] agg the state object
00139  * \param[in] state the state to add
00140  *
00141  * \return nothing
00142  */
00143 void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
00144 
00145 /*!
00146  * \brief Get the aggregate device state result
00147  *
00148  * \param[in] agg the state object
00149  *
00150  * \return the aggregate device state after adding some number of device states.
00151  */
00152 enum ast_device_state ast_devstate_aggregate_result(struct ast_devstate_aggregate *agg);
00153 
00154 /*!
00155  * \brief You shouldn't care about the contents of this struct
00156  *
00157  * This struct is only here so that it can be easily declared on the stack.
00158  */
00159 struct ast_devstate_aggregate {
00160    unsigned int all_unavail:1;
00161    unsigned int all_busy:1;
00162    unsigned int all_free:1;
00163    unsigned int all_unknown:1;
00164    unsigned int on_hold:1;
00165    unsigned int busy:1;
00166    unsigned int in_use:1;
00167    unsigned int ring:1;
00168 };
00169 
00170 int ast_device_state_engine_init(void);
00171 
00172 #if defined(__cplusplus) || defined(c_plusplus)
00173 }
00174 #endif
00175 
00176 #endif /* _ASTERISK_DEVICESTATE_H */

Generated on Sat Aug 6 00:39:28 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7