Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:47 2009

## Asterisk developer's documentation

# adsi.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 ADSI Support (built upon Caller*ID)
    00021  */
    00022
    00023 #ifndef _ASTERISK_ADSI_H
    00024 #define _ASTERISK_ADSI_H
    00025
    00026 #include "asterisk/callerid.h"
    00027
    00028 /* ADSI Message types */
    00029 #define ADSI_MSG_DISPLAY   132
    00030 #define ADSI_MSG_DOWNLOAD  133
    00031
    00032 /* ADSI Parameters (display) */
    00033 #define ADSI_LOAD_SOFTKEY  128
    00034 #define ADSI_INIT_SOFTKEY_LINE   129
    00035 #define ADSI_LOAD_VIRTUAL_DISP   130
    00036 #define ADSI_LINE_CONTROL  131
    00037 #define ADSI_INFORMATION   132
    00038 #define ADSI_DISC_SESSION  133
    00039 #define ADSI_SWITCH_TO_DATA   134
    00040 #define ADSI_SWITCH_TO_VOICE  135
    00041 #define ADSI_CLEAR_SOFTKEY 136
    00042 #define ADSI_INPUT_CONTROL 137
    00043 #define ADSI_INPUT_FORMAT  138
    00044 #define ADSI_SWITCH_TO_PERIPH 139
    00045 #define ADSI_MOVE_DATA     140
    00046 #define ADSI_LOAD_DEFAULT  141
    00047 #define ADSI_CONNECT_SESSION  142
    00048 #define ADSI_CLEAR_TYPE_AHEAD 143
    00049 #define ADSI_DISPLAY_CALL_BUF 144
    00050 #define ADSI_CLEAR_CALL_BUF   145
    00051 #define ADSI_SWITCH_TO_ALT 146
    00052 #define ADSI_SWITCH_TO_GRAPHICS  147
    00053 #define ADSI_CLEAR_SCREEN  148
    00054 #define ADSI_QUERY_CONFIG  149
    00055 #define ADSI_QUERY_CPEID   150
    00056 #define ADSI_SWITCH_TO_APP 151
    00057
    00058 /* Feature download messages */
    00059 #define ADSI_LOAD_SOFTKEY_TABLE  128   /* Conveniently identical to the soft version */
    00060 #define ADSI_LOAD_PREDEF_DISP 129   /* Load predefined display */
    00061 #define ADSI_LOAD_SCRIPT   130
    00062 #define ADSI_DOWNLOAD_CONNECT 131
    00063 #define ADSI_DOWNLOAD_DISC 132
    00064
    00065 /* Special return string codes */
    00066 #define ADSI_ENCODED_DTMF  0x80  /* Transmit following chars with encoded dtmf */
    00067 #define ADSI_ON_HOOK    0x81  /* Open switch-hook */
    00068 #define ADSI_OFF_HOOK      0x82  /* Close switch-hook */
    00069 #define ADSI_FLASH      0x83  /* Flash switch-hook */
    00070 #define ADSI_DIAL_TONE_DETECT 0x84  /* Wait for dialtone */
    00071 #define ADSI_LINE_NUMBER   0x85  /* Send current line number using DTMF/encoded DTMF */
    00072 #define ADSI_BLANK      0x86  /* Blank (does nothing) */
    00073 #define ADSI_SEND_CHARS    0x87  /* Send collected digits/characters */
    00074 #define ADSI_CLEAR_CHARS   0x88  /* Clear characters/digits collected */
    00075 #define ADSI_BACKSPACE     0x89  /* Erase last collected digit */
    00076 #define ADSI_TAB_COLUMN    0x8A  /* Display specified display column of current line */
    00077 #define ADSI_GOTO_LINE     0x8B  /* Go to given page and line number */
    00078 #define ADSI_GOTO_LINE_REL 0x8C  /* Go to given line (relative to current) */
    00079 #define ADSI_PAGE_UP    0x8D  /* Go up one page */
    00080 #define ADSI_PAGE_DOWN     0x8E  /* Go down one page */
    00081 #define ADSI_EXTENDED_DTMF 0x8F  /* Send DTMF tones for 250ms instead of 60 ms */
    00082 #define ADSI_DELAY      0x90  /* Delay for given # (times 10) of ms */
    00083 #define ADSI_DIAL_PULSE_ONE   0x91  /* Send a dial pulse "1" */
    00084 #define ADSI_SWITCH_TO_DATA2  0x92  /* Switch CPE to data mode */
    00085 #define ADSI_SWITCH_TO_VOICE2 0x93  /* Switch CPE to voice mode */
    00086 #define ADSI_DISP_CALL_BUF 0x94  /* Display specified call buffer */
    00087 #define ADSI_CLEAR_CALL_B  0x95  /* Clear specified call buffer */
    00088
    00089 #ifdef __ADSI_CPE
    00090 /* These messages are reserved for the ADSI CPE only */
    00091 #define ADSI_DISPLAY_CONTROL  0x98  /* Store predefined display identified next / Display status display page */
    00092 #define ADSI_DISPLAY_SOFT_KEYS   0x99  /* Display the script soft keys identified next */
    00093 #define ADSI_CHANGE_STATE  0x9A  /* Change state of service script */
    00094 #define ADSI_START_CLEAR_TIMER   0x9B  /* Start / Clear timer */
    00095 #define ADSI_SET_SCRIPT_FLAG  0x9C  /* Set / clear a script flag */
    00096 #define ADSI_JUMP_TO_SUBSCRIPT   0x9D  /* Jump to specified subscript */
    00097 #define ADSI_EVENT_22_TRIGGER 0x9E  /* Trigger an occurance of event 22 */
    00098 #define ADSI_EVENT_23_TRIGGER 0x9f  /* Trigger an occurance of event 23 */
    00099 #define ADSI_EXIT    0xA0  /* Exit the service script interpreter */
    00100 #endif
    00101
    00102 /* Display pages */
    00103 #define ADSI_INFO_PAGE  0x0
    00104 #define ADSI_COMM_PAGE  0x1
    00105
    00106 #define ADSI_KEY_APPS   16 /* 16 to 33 reserved for applications */
    00107
    00108 /* Justification */
    00109 #define ADSI_JUST_LEFT  0x2
    00110 #define ADSI_JUST_RIGHT 0x1
    00111 #define ADSI_JUST_CENT  0x0   /* Center */
    00112 #define ADSI_JUST_IND   0x3   /* Indent */
    00113
    00114 #define ADSI_KEY_SKT 0x80  /* Load from SKT */
    00115 #define ADSI_KEY_HILITE 0x40  /* Highlight key */
    00116
    00117 #define ADSI_DIR_FROM_LEFT (0)
    00118 #define ADSI_DIR_FROM_RIGHT (1)
    00119
    00120 /*! Perform Asterisk ADSI initialization (for channel drivers that want */
    00121 /*    to support ADSI when the handset is first lifted) */
    00122 /*!
    00123  * \param chan Channel to initialize for ADSI (if supported)
    00124  *
    00125  * Returns 0 on success (or adsi unavailable) and -1 on hangup
    00126  *
    00127  */
    00128 extern int adsi_channel_init(struct ast_channel *chan);
    00129
    00130 extern int adsi_begin_download(struct ast_channel *chan, char *service, unsigned char *fdn, unsigned char *sec, int version);
    00131
    00132 extern int adsi_end_download(struct ast_channel *chan);
    00133
    00134 /*! Restore ADSI initialization (for applications that play with ADSI */
    00135 /*   and want to restore it to normal.  If you touch "INFO" then you */
    00136 /*   have to use the adsi_channel_init again instead. */
    00137 /*!
    00138  * \param chan Channel to restore
    00139  *
    00140  * Returns 0 on success (or adsi unavailable) and -1 on hangup
    00141  *
    00142  */
    00143 extern int adsi_channel_restore(struct ast_channel *chan);
    00144
    00145 /*! Display some stuff on the screen */
    00146 /*!
    00147  * \param chan Channel to display on
    00148  * \param lines NULL-terminated list of things to print (no more than 4 recommended)
    00149  * \param align list of alignments to use (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CEN, etc..)
    00150  * \param voice whether to jump into voice mode when finished
    00151  *
    00152  * Return 0 on success (or adsi unavailable) and -1 on hangup
    00153  *
    00154  */
    00155 extern int adsi_print(struct ast_channel *chan, char **lines, int *align, int voice);
    00156
    00157 /*! Check if scripts for a given app are already loaded.  Version may be -1 */
    00158 /*   if any version is okay, or 0-255 for a specific version. */
    00159 /*!
    00160  * \param chan Channel to test for loaded app
    00161  * \param app Four character app name (must be unique to your application)
    00162  * \param ver optional version number
    00163  * \param data Non-zero if you want to be put in data mode
    00164  *
    00165  * Returns 0 if scripts is not loaded or not an ADSI CPE.  Returns -1
    00166  * on hangup.  Returns 1 if script already loaded.
    00167  */
    00168 extern int adsi_load_session(struct ast_channel *chan, unsigned char *app, int ver, int data);
    00169 extern int adsi_unload_session(struct ast_channel *chan);
    00170
    00171 /* ADSI Layer 2 transmission functions */
    00172 extern int adsi_transmit_messages(struct ast_channel *chan, unsigned char **msg, int *msglen, int *msgtype);
    00173 extern int adsi_transmit_message(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype);
    00174 extern int adsi_transmit_message_full(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype, int dowait);
    00175 /*! Read some encoded DTMF data.   */
    00176 /*!
    00177  * Returns number of bytes received
    00178  */
    00179 extern int adsi_read_encoded_dtmf(struct ast_channel *chan, unsigned char *buf, int maxlen);
    00180
    00181 /* ADSI Layer 3 creation functions */
    00182
    00183 /*! Connects an ADSI Display Session */
    00184 /*!
    00185  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00186  * \param fdn Optional 4 byte Feature Download Number (for loading soft keys)
    00187  * \param ver Optional version number (0-255, or -1 to omit)
    00188  *
    00189  * Returns number of bytes added to buffer or -1 on error.
    00190  *
    00191  */
    00192
    00193 extern int adsi_connect_session(unsigned char *buf, unsigned char *fdn, int ver);
    00194
    00195 /*! Build Query CPE ID of equipment */
    00196 /*!
    00197  *  Returns number of bytes added to message
    00198  */
    00199 extern int adsi_query_cpeid(unsigned char *buf);
    00200 extern int adsi_query_cpeinfo(unsigned char *buf);
    00201
    00202 /*! Get CPE ID from an attached ADSI compatible CPE. */
    00203 /*!
    00204  * Returns 1 on success, storing 4 bytes of CPE ID at buf
    00205  * or -1 on hangup, or 0 if there was no hangup but it failed to find the
    00206  * device ID.  Returns to voice mode if "voice" is non-zero.
    00207  */
    00208 extern int adsi_get_cpeid(struct ast_channel *chan, unsigned char *cpeid, int voice);
    00209
    00210 extern int adsi_get_cpeinfo(struct ast_channel *chan, int *width, int *height, int *buttons, int voice);
    00211
    00212 /*! Begin an ADSI script download */
    00213 /*!
    00214  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00215  * \param service a 1-18 byte name of the feature
    00216  * \param fdn 4 byte Feature Download Number (for loading soft keys)
    00217  * \param sec 4 byte vendor security code
    00218  * \param ver version number (0-255, or -1 to omit)
    00219  *
    00220  * Returns number of bytes added to buffer or -1 on error.
    00221  *
    00222  */
    00223
    00224 extern int adsi_download_connect(unsigned char *buf, char *service, unsigned char *fdn, unsigned char *sec, int ver);
    00225
    00226 /*! Disconnects a running session */
    00227 /*!
    00228  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00229  *
    00230  * Returns number of bytes added to buffer or -1 on error.
    00231  *
    00232  */
    00233 extern int adsi_disconnect_session(unsigned char *buf);
    00234
    00235 /*! Disconnects (and hopefully saves) a downloaded script */
    00236 /*!
    00237  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00238  *
    00239  * Returns number of bytes added to buffer or -1 on error.
    00240  *
    00241  */
    00242 extern int adsi_download_disconnect(unsigned char *buf);
    00243
    00244 /*! Puts CPE in data mode... */
    00245 /*!
    00246  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00247  *
    00248  * Returns number of bytes added to buffer or -1 on error.
    00249  *
    00250  */
    00251 extern int adsi_data_mode(unsigned char *buf);
    00252 extern int adsi_clear_soft_keys(unsigned char *buf);
    00253 extern int adsi_clear_screen(unsigned char *buf);
    00254
    00255 /*! Puts CPE in voice mode... */
    00256 /*!
    00257  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00258  * \param when (a time in seconds) to make the switch
    00259  *
    00260  * Returns number of bytes added to buffer or -1 on error.
    00261  *
    00262  */
    00263 extern int adsi_voice_mode(unsigned char *buf, int when);
    00264
    00265 /*! Returns non-zero if Channel does or might support ADSI */
    00266 /*!
    00267  * \param chan Channel to check
    00268  *
    00269  */
    00270 extern int adsi_available(struct ast_channel *chan);
    00271
    00272 /*! Loads a line of info into the display */
    00273 /*!
    00274  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00275  * \param page Page to load (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
    00276  * \param line Line number to load (1-4 for Comm page, 1-33 for info page)
    00277  * \param just Line justification (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CENT, ADSI_JUST_IND)
    00278  * \param wrap Wrap (1 = yes, 0 = no)
    00279  * \param col1 Text to place in first column
    00280  * \param col2 Text to place in second column
    00281  *
    00282  * Returns number of bytes added to buffer or -1 on error.
    00283  *
    00284  */
    00285
    00286 extern int adsi_display(unsigned char *buf, int page, int line, int just, int wrap, char *col1, char *col2);
    00287
    00288 /*! Sets the current line and page */
    00289 /*!
    00290  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00291  * \param page Which page (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
    00292  * \param line Line number (1-33 for info page, 1-4 for comm page)
    00293  *
    00294  * Returns number of bytes added to buffer or -1 on error.
    00295  *
    00296  */
    00297
    00298 extern int adsi_set_line(unsigned char *buf, int page, int line);
    00299
    00300 /*! Creates "load soft key" parameters */
    00301 /*!
    00302  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00303  * \param key Key code from 2 to 33, for which key we are loading
    00304  * \param llabel Long label for key (1-18 bytes)
    00305  * \param slabel Short label for key (1-7 bytes)
    00306  * \param ret Optional return sequence (NULL for none)
    00307  * \param data whether to put CPE in data mode before sending digits
    00308  *
    00309  * Returns number of bytes added to buffer or -1 on error.
    00310  *
    00311  */
    00312 extern int adsi_load_soft_key(unsigned char *buf, int key, char *llabel, char *slabel, char *ret, int data);
    00313
    00314 /*! Set which soft keys should be displayed */
    00315 /*!
    00316  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00317  * \param keys Array of 8 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
    00318  *             But remember, the last two keys aren't real keys, they're for scrolling
    00319  *
    00320  * Returns number of bytes added to buffer or -1 on error.
    00321  *
    00322  */
    00323 extern int adsi_set_keys(unsigned char *buf, unsigned char *keys);
    00324
    00325 /*! Set input information */
    00326 /*!
    00327  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00328  * \param page Which page to input on (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
    00329  * \param line Line number to input on
    00330  * \param display Set to zero to obscure input, or 1 to leave visible
    00331  * \param format Format number to use (0-7)
    00332  * \param just Justification (left, right center, indent)
    00333  *
    00334  * Returns number of bytes added to buffer or -1 on error.
    00335  *
    00336  */
    00337 extern int adsi_input_control(unsigned char *buf, int page, int line, int display, int format, int just);
    00338
    00339 /*! Set input format */
    00340 /*!
    00341  * \param buf Character buffer to create parameter in (must have at least 256 free)
    00342  * \param num Which format we are setting
    00343  * \param dir Which direction (ADSI_DIR_FROM_LEFT or ADSI_DIR_FROM_RIGHT)
    00344  * \param wrap Set to 1 to permit line wrap, or 0 if not
    00345  * \param format1 Format for column 1
    00346  * \param format2 Format for column 2
    00347  *
    00348  * Returns number of bytes added to buffer or -1 on error.
    00349  *
    00350  */
    00351 extern int adsi_input_format(unsigned char *buf, int num, int dir, int wrap, char *format1, char *format2);
    00352
    00353 #endif /* _ASTERISK_ADSI_H */