Standardized routines for forking processes (keeps all the specialized code in one...
[asterisk/asterisk.git] / include / asterisk / adsi.h
old mode 100755 (executable)
new mode 100644 (file)
index 5438e48..3c31574
@@ -1,22 +1,31 @@
 /*
- * Asterisk -- A telephony toolkit for Linux.
+ * Asterisk -- An open source telephony toolkit.
  *
- * ADSI Support (built upon Caller*ID) 
- * 
- * Copyright (C) 1999, Mark Spencer
+ * Copyright (C) 1999 - 2005, Digium, Inc.
  *
- * Mark Spencer <markster@linux-support.net>
+ * Mark Spencer <markster@digium.com>
  *
- * This program is free software, distributed under the terms of
- * the GNU General Public License.
- *
- * Includes code and algorithms from the Zapata library.
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
  *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
  */
 
-#ifndef _ADSI_H
-#define _ADSI_H
-#include <asterisk/callerid.h>
+/*! \file
+ * \brief ADSI Support (built upon Caller*ID)
+ */
+
+#ifndef _ASTERISK_ADSI_H
+#define _ASTERISK_ADSI_H
+
+#include "asterisk/callerid.h"
+/*! \name ADSI parameters */
+/*@{ */
 
 /* ADSI Message types */
 #define ADSI_MSG_DISPLAY       132
 #define ADSI_DIR_FROM_LEFT (0)
 #define ADSI_DIR_FROM_RIGHT (1)
 
-//! Perform Asterisk ADSI initialization (for channel drivers that want
-//   to support ADSI when the handset is first lifted) */
-/*! 
+/*@} */
+
+/*! Perform Asterisk ADSI initialization (for channel drivers that want 
+ *    to support ADSI when the handset is first lifted) 
  * \param chan Channel to initialize for ADSI (if supported)
- * 
- * Returns 0 on success (or adsi unavailable) and -1 on hangup
- * 
+ *
+ * \retval 0 on success (or adsi unavailable.
+ * \retval -1 on hangup.
  */
-extern int adsi_channel_init(struct ast_channel *chan);
+extern int (*ast_adsi_channel_init)(struct ast_channel *chan);
 
-extern int adsi_begin_download(struct ast_channel *chan, char *service, char *fdn, char *sec, int version);
+extern int (*ast_adsi_begin_download)(struct ast_channel *chan, char *service, unsigned char *fdn, unsigned char *sec, int version);
 
-extern int adsi_end_download(struct ast_channel *chan);
+extern int (*ast_adsi_end_download)(struct ast_channel *chan);
 
-//! Restore ADSI initialization (for applications that play with ADSI
-//  and want to restore it to normal.  If you touch "INFO" then you
-//  have to use the adsi_channel_init again instead.
-/*!
+/*! Restore ADSI initialization (for applications that play with ADSI 
+ *   and want to restore it to normal.  If you touch "INFO" then you 
+ *   have to use the ast_adsi_channel_init again instead. 
  * \param chan Channel to restore
- * 
- * Returns 0 on success (or adsi unavailable) and -1 on hangup
  *
+ * \retval 0 on success (or adsi unavailable)
+ * \retval -1 on hangup
  */
-extern int adsi_channel_restore(struct ast_channel *chan);
+extern int (*ast_adsi_channel_restore)(struct ast_channel *chan);
 
-//! Display some stuff on the screen
-/*!
+/*! 
+ * \brief Display some stuff on the screen 
  * \param chan Channel to display on
  * \param lines NULL-terminated list of things to print (no more than 4 recommended)
  * \param align list of alignments to use (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CEN, etc..)
+ * \param voice whether to jump into voice mode when finished
  *
- * Return 0 on success (or adsi unavailable) and -1 on hangup
- *
+ * \retval 0 on success (or adsi unavailable) 
+ * \retval -1 on hangup
  */
-extern int adsi_print(struct ast_channel *chan, char **lines, int *align);
+extern int (*ast_adsi_print)(struct ast_channel *chan, char **lines, int *align, int voice);
 
-//! Check if scripts for a given app are already loaded.  Version may be -1
-//  if any version is okay, or 0-255 for a specific version.
-/*!
+/*! 
+ * \brief Check if scripts for a given app are already loaded.
+ * Version may be -1, if any version is okay, or 0-255 for a specific version. 
  * \param chan Channel to test for loaded app
  * \param app Four character app name (must be unique to your application)
  * \param ver optional version number
  * \param data Non-zero if you want to be put in data mode
  *
- * Returns 0 if scripts is not loaded or not an ADSI CPE.  Returns -1
- * on hangup.  Returns 1 if script already loaded.
+ * \retval 0 if scripts is not loaded or not an ADSI CPE
+ * \retval -1 on hangup
+ * \retval 1 if script already loaded.
  */
-extern int adsi_load_session(struct ast_channel *chan, unsigned char *app, int ver, int data);
-extern int adsi_unload_session(struct ast_channel *chan);
+extern int (*ast_adsi_load_session)(struct ast_channel *chan, unsigned char *app, int ver, int data);
+extern int (*ast_adsi_unload_session)(struct ast_channel *chan);
 
 /* ADSI Layer 2 transmission functions */
-extern int adsi_transmit_messages(struct ast_channel *chan, unsigned char **msg, int *msglen, int *msgtype);
-extern int adsi_transmit_message(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype);
+extern int (*ast_adsi_transmit_messages)(struct ast_channel *chan, unsigned char **msg, int *msglen, int *msgtype);
+extern int (*ast_adsi_transmit_message)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype);
+extern int (*ast_adsi_transmit_message_full)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype, int dowait);
+/*! Read some encoded DTMF data. 
+ * Returns number of bytes received
+ */
+extern int (*ast_adsi_read_encoded_dtmf)(struct ast_channel *chan, unsigned char *buf, int maxlen);
 
 /* ADSI Layer 3 creation functions */
 
-//! Connects an ADSI Display Session */
-/*!
+/*! 
+ * \brief Connects an ADSI Display Session 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param fdn Optional 4 byte Feature Download Number (for loading soft keys)
  * \param ver Optional version number (0-255, or -1 to omit)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
-extern int adsi_connect_session(unsigned char *buf, unsigned char *fdn, int ver);
+extern int (*ast_adsi_connect_session)(unsigned char *buf, unsigned char *fdn, int ver);
 
-//! Begin an ADSI script download */
-/*!
+/*! Build Query CPE ID of equipment. 
+ *  Returns number of bytes added to message
+ */
+extern int (*ast_adsi_query_cpeid)(unsigned char *buf);
+extern int (*ast_adsi_query_cpeinfo)(unsigned char *buf);
+
+/*! Get CPE ID from an attached ADSI compatible CPE. 
+ * Returns 1 on success, storing 4 bytes of CPE ID at buf
+ * or -1 on hangup, or 0 if there was no hangup but it failed to find the
+ * device ID.  Returns to voice mode if "voice" is non-zero.
+ */
+extern int (*ast_adsi_get_cpeid)(struct ast_channel *chan, unsigned char *cpeid, int voice);
+
+extern int (*ast_adsi_get_cpeinfo)(struct ast_channel *chan, int *width, int *height, int *buttons, int voice);
+
+/*! 
+ * \brief Begin an ADSI script download 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
- * \param service, a 1-18 byte name of the feature
+ * \param service a 1-18 byte name of the feature
  * \param fdn 4 byte Feature Download Number (for loading soft keys)
  * \param sec 4 byte vendor security code
  * \param ver version number (0-255, or -1 to omit)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
-extern int adsi_download_connect(unsigned char *buf, unsigned char *service, unsigned char *fdn, unsigned char *sec, int ver);
+extern int (*ast_adsi_download_connect)(unsigned char *buf, char *service, unsigned char *fdn, unsigned char *sec, int ver);
 
-//! Disconnects a running session
-/*!
+/*! 
+ * \brief Disconnects a running session.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_disconnect_session(unsigned char *buf);
+extern int (*ast_adsi_disconnect_session)(unsigned char *buf);
 
-//! Disconnects (and hopefully saves) a downloaded script
-/*!
+/*! 
+ * \brief Disconnects (and hopefully saves) a downloaded script 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_download_disconnect(unsigned char *buf);
+extern int (*ast_adsi_download_disconnect)(unsigned char *buf);
 
-//! Puts CPE in data mode...
-/*!
+/*! 
+ * \brief Puts CPE in data mode.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_data_mode(unsigned char *buf);
+extern int (*ast_adsi_data_mode)(unsigned char *buf);
+extern int (*ast_adsi_clear_soft_keys)(unsigned char *buf);
+extern int (*ast_adsi_clear_screen)(unsigned char *buf);
 
-//! Puts CPE in voice mode...
-/*!
+/*! 
+ * \brief Puts CPE in voice mode.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param when (a time in seconds) to make the switch
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_voice_mode(unsigned char *buf, int when);
+extern int (*ast_adsi_voice_mode)(unsigned char *buf, int when);
 
-//! Returns non-zero if Channel does or might support ADSI
-/*!
+/*! 
+ * \brief Returns non-zero if Channel does or might support ADSI 
  * \param chan Channel to check
- *
  */
-extern int adsi_available(struct ast_channel *chan);
+extern int (*ast_adsi_available)(struct ast_channel *chan);
 
-//! Loads a line of info into the display */
-/*!
+/*! 
+ * \brief Loads a line of info into the display.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Page to load (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number to load (1-4 for Comm page, 1-33 for info page)
@@ -246,26 +278,26 @@ extern int adsi_available(struct ast_channel *chan);
  * \param col1 Text to place in first column
  * \param col2 Text to place in second column
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
-extern int adsi_display(unsigned char *buf, int page, int line, int just, int wrap, unsigned char *col1, unsigned char *col2);
+extern int (*ast_adsi_display)(unsigned char *buf, int page, int line, int just, int wrap, char *col1, char *col2);
 
-//! Sets the current line and page */
-/*!
+/*! 
+ * \brief Sets the current line and page. 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Which page (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number (1-33 for info page, 1-4 for comm page)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
-extern int adsi_set_line(unsigned char *buf, int page, int line);
+extern int (*ast_adsi_set_line)(unsigned char *buf, int page, int line);
 
-//! Creates "load soft key" parameters
 /*! 
+ * \brief Creates "load soft key" parameters
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param key Key code from 2 to 33, for which key we are loading
  * \param llabel Long label for key (1-18 bytes)
@@ -273,23 +305,24 @@ extern int adsi_set_line(unsigned char *buf, int page, int line);
  * \param ret Optional return sequence (NULL for none)
  * \param data whether to put CPE in data mode before sending digits
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_load_soft_key(unsigned char *buf, int key, unsigned char *llabel, unsigned char *slabel, unsigned char *ret, int data);
+extern int (*ast_adsi_load_soft_key)(unsigned char *buf, int key, const char *llabel, const char *slabel, char *ret, int data);
 
-//! Set which soft keys should be displayed
-/*!
+/*! 
+ * \brief Set which soft keys should be displayed 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
- * \param keys Array of 6 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
- *
- * Returns number of bytes added to buffer or -1 on error.
+ * \param keys Array of 8 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
+ *             But remember, the last two keys aren't real keys, they're for scrolling
  *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_set_keys(unsigned char *buf, unsigned char *keys);
+extern int (*ast_adsi_set_keys)(unsigned char *buf, unsigned char *keys);
 
-//! Set input information
-/*!
+/*! 
+ * \brief Set input information 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Which page to input on (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number to input on
@@ -297,13 +330,13 @@ extern int adsi_set_keys(unsigned char *buf, unsigned char *keys);
  * \param format Format number to use (0-7)
  * \param just Justification (left, right center, indent)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_input_control(unsigned char *buf, int page, int line, int display, int format, int just);
+extern int (*ast_adsi_input_control)(unsigned char *buf, int page, int line, int display, int format, int just);
 
-//! Set input format
-/*!
+/*! 
+ * \brief Set input format 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param num Which format we are setting
  * \param dir Which direction (ADSI_DIR_FROM_LEFT or ADSI_DIR_FROM_RIGHT)
@@ -311,8 +344,10 @@ extern int adsi_input_control(unsigned char *buf, int page, int line, int displa
  * \param format1 Format for column 1
  * \param format2 Format for column 2
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
-extern int adsi_input_format(unsigned char *buf, int num, int dir, int wrap, unsigned char *format1, unsigned char *format2);
-#endif
+extern int (*ast_adsi_input_format)(unsigned char *buf, int num, int dir, int wrap, char *format1, char *format2);
+
+#endif /* _ASTERISK_ADSI_H */
+