include/asterisk/adsi.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief ADSI Support (built upon Caller*ID)
  21  */
  22
  23 #ifndef _ASTERISK_ADSI_H
  24 #define _ASTERISK_ADSI_H
  25
  26 #include "asterisk/callerid.h"
  27 #include "asterisk/optional_api.h"
  28
  29 /*! \name ADSI parameters */
  30 /*@{ */
  31
  32 /* ADSI Message types */
  33 #define ADSI_MSG_DISPLAY        132
  34 #define ADSI_MSG_DOWNLOAD       133
  35
  36 /* ADSI Parameters (display) */
  37 #define ADSI_LOAD_SOFTKEY       128
  38 #define ADSI_INIT_SOFTKEY_LINE  129
  39 #define ADSI_LOAD_VIRTUAL_DISP  130
  40 #define ADSI_LINE_CONTROL       131
  41 #define ADSI_INFORMATION        132
  42 #define ADSI_DISC_SESSION       133
  43 #define ADSI_SWITCH_TO_DATA     134
  44 #define ADSI_SWITCH_TO_VOICE    135
  45 #define ADSI_CLEAR_SOFTKEY      136
  46 #define ADSI_INPUT_CONTROL      137
  47 #define ADSI_INPUT_FORMAT       138
  48 #define ADSI_SWITCH_TO_PERIPH   139
  49 #define ADSI_MOVE_DATA          140
  50 #define ADSI_LOAD_DEFAULT       141
  51 #define ADSI_CONNECT_SESSION    142
  52 #define ADSI_CLEAR_TYPE_AHEAD   143
  53 #define ADSI_DISPLAY_CALL_BUF   144
  54 #define ADSI_CLEAR_CALL_BUF     145
  55 #define ADSI_SWITCH_TO_ALT      146
  56 #define ADSI_SWITCH_TO_GRAPHICS 147
  57 #define ADSI_CLEAR_SCREEN       148
  58 #define ADSI_QUERY_CONFIG       149
  59 #define ADSI_QUERY_CPEID        150
  60 #define ADSI_SWITCH_TO_APP      151
  61
  62 /* Feature download messages */
  63 #define ADSI_LOAD_SOFTKEY_TABLE 128     /* Conveniently identical to the soft version */
  64 #define ADSI_LOAD_PREDEF_DISP   129     /* Load predefined display */
  65 #define ADSI_LOAD_SCRIPT        130
  66 #define ADSI_DOWNLOAD_CONNECT   131
  67 #define ADSI_DOWNLOAD_DISC      132
  68
  69 /* Special return string codes */
  70 #define ADSI_ENCODED_DTMF       0x80    /* Transmit following chars with encoded dtmf */
  71 #define ADSI_ON_HOOK            0x81    /* Open switch-hook */
  72 #define ADSI_OFF_HOOK           0x82    /* Close switch-hook */
  73 #define ADSI_FLASH              0x83    /* Flash switch-hook */
  74 #define ADSI_DIAL_TONE_DETECT   0x84    /* Wait for dialtone */
  75 #define ADSI_LINE_NUMBER        0x85    /* Send current line number using DTMF/encoded DTMF */
  76 #define ADSI_BLANK              0x86    /* Blank (does nothing) */
  77 #define ADSI_SEND_CHARS         0x87    /* Send collected digits/characters */
  78 #define ADSI_CLEAR_CHARS        0x88    /* Clear characters/digits collected */
  79 #define ADSI_BACKSPACE          0x89    /* Erase last collected digit */
  80 #define ADSI_TAB_COLUMN         0x8A    /* Display specified display column of current line */
  81 #define ADSI_GOTO_LINE          0x8B    /* Go to given page and line number */
  82 #define ADSI_GOTO_LINE_REL      0x8C    /* Go to given line (relative to current) */
  83 #define ADSI_PAGE_UP            0x8D    /* Go up one page */
  84 #define ADSI_PAGE_DOWN          0x8E    /* Go down one page */
  85 #define ADSI_EXTENDED_DTMF      0x8F    /* Send DTMF tones for 250ms instead of 60 ms */
  86 #define ADSI_DELAY              0x90    /* Delay for given # (times 10) of ms */
  87 #define ADSI_DIAL_PULSE_ONE     0x91    /* Send a dial pulse "1" */
  88 #define ADSI_SWITCH_TO_DATA2    0x92    /* Switch CPE to data mode */
  89 #define ADSI_SWITCH_TO_VOICE2   0x93    /* Switch CPE to voice mode */
  90 #define ADSI_DISP_CALL_BUF      0x94    /* Display specified call buffer */
  91 #define ADSI_CLEAR_CALL_B       0x95    /* Clear specified call buffer */
  92
  93 #ifdef __ADSI_CPE
  94 /* These messages are reserved for the ADSI CPE only */
  95 #define ADSI_DISPLAY_CONTROL    0x98    /* Store predefined display identified next / Display status display page */
  96 #define ADSI_DISPLAY_SOFT_KEYS  0x99    /* Display the script soft keys identified next */
  97 #define ADSI_CHANGE_STATE       0x9A    /* Change state of service script */
  98 #define ADSI_START_CLEAR_TIMER  0x9B    /* Start / Clear timer */
  99 #define ADSI_SET_SCRIPT_FLAG    0x9C    /* Set / clear a script flag */
 100 #define ADSI_JUMP_TO_SUBSCRIPT  0x9D    /* Jump to specified subscript */
 101 #define ADSI_EVENT_22_TRIGGER   0x9E    /* Trigger an occurance of event 22 */
 102 #define ADSI_EVENT_23_TRIGGER   0x9f    /* Trigger an occurance of event 23 */
 103 #define ADSI_EXIT               0xA0    /* Exit the service script interpreter */
 104 #endif
 105
 106 /* Display pages */
 107 #define ADSI_INFO_PAGE  0x0
 108 #define ADSI_COMM_PAGE  0x1
 109
 110 #define ADSI_KEY_APPS   16      /* 16 to 33 reserved for applications */
 111
 112 /* Justification */
 113 #define ADSI_JUST_LEFT  0x2
 114 #define ADSI_JUST_RIGHT 0x1
 115 #define ADSI_JUST_CENT  0x0     /* Center */
 116 #define ADSI_JUST_IND   0x3     /* Indent */
 117
 118 #define ADSI_KEY_SKT    0x80    /* Load from SKT */
 119 #define ADSI_KEY_HILITE 0x40    /* Highlight key */
 120
 121 #define ADSI_DIR_FROM_LEFT (0)
 122 #define ADSI_DIR_FROM_RIGHT (1)
 123
 124 /*@} */
 125
 126 AST_OPTIONAL_API(int, ast_adsi_begin_download, (struct ast_channel *chan, char *service, unsigned char *fdn, unsigned char *sec, int version), { return 0; });
 127
 128 AST_OPTIONAL_API(int, ast_adsi_end_download, (struct ast_channel *chan), { return 0; });
 129
 130 /*! Restore ADSI initialization (for applications that play with ADSI
 131  *   and want to restore it to normal.  If you touch "INFO" then you
 132  *   have to use the ast_adsi_channel_init again instead.
 133  * \param chan Channel to restore
 134  *
 135  * \retval 0 on success (or adsi unavailable)
 136  * \retval -1 on hangup
 137  */
 138 AST_OPTIONAL_API(int, ast_adsi_channel_restore, (struct ast_channel *chan), { return 0; });
 139
 140 /*!
 141  * \brief Display some stuff on the screen
 142  * \param chan Channel to display on
 143  * \param lines NULL-terminated list of things to print (no more than 4 recommended)
 144  * \param align list of alignments to use (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CEN, etc..)
 145  * \param voice whether to jump into voice mode when finished
 146  *
 147  * \retval 0 on success (or adsi unavailable)
 148  * \retval -1 on hangup
 149  */
 150 AST_OPTIONAL_API(int, ast_adsi_print, (struct ast_channel *chan, char **lines, int *align, int voice), { return 0; });
 151
 152 /*!
 153  * \brief Check if scripts for a given app are already loaded.
 154  * Version may be -1, if any version is okay, or 0-255 for a specific version.
 155  * \param chan Channel to test for loaded app
 156  * \param app Four character app name (must be unique to your application)
 157  * \param ver optional version number
 158  * \param data Non-zero if you want to be put in data mode
 159  *
 160  * \retval 0 if scripts is not loaded or not an ADSI CPE
 161  * \retval -1 on hangup
 162  * \retval 1 if script already loaded.
 163  */
 164 AST_OPTIONAL_API(int, ast_adsi_load_session, (struct ast_channel *chan, unsigned char *app, int ver, int data), { return 0; });
 165 AST_OPTIONAL_API(int, ast_adsi_unload_session, (struct ast_channel *chan), { return 0; });
 166
 167 /* ADSI Layer 2 transmission functions */
 168 AST_OPTIONAL_API(int, ast_adsi_transmit_message, (struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype), { return 0; });
 169 AST_OPTIONAL_API(int, ast_adsi_transmit_message_full, (struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype, int dowait), { return 0; });
 170 /*! Read some encoded DTMF data.
 171  * Returns number of bytes received
 172  */
 173 AST_OPTIONAL_API(int, ast_adsi_read_encoded_dtmf, (struct ast_channel *chan, unsigned char *buf, int maxlen), { return 0; });
 174
 175 /* ADSI Layer 3 creation functions */
 176
 177 /*!
 178  * \brief Connects an ADSI Display Session
 179  * \param buf Character buffer to create parameter in (must have at least 256 free)
 180  * \param fdn Optional 4 byte Feature Download Number (for loading soft keys)
 181  * \param ver Optional version number (0-255, or -1 to omit)
 182  *
 183  * \retval number of bytes added to buffer
 184  * \retval -1 on error.
 185  */
 186
 187 AST_OPTIONAL_API(int, ast_adsi_connect_session, (unsigned char *buf, unsigned char *fdn, int ver), { return 0; });
 188
 189 /*! Build Query CPE ID of equipment.
 190  *  Returns number of bytes added to message
 191  */
 192 AST_OPTIONAL_API(int, ast_adsi_query_cpeid, (unsigned char *buf), { return 0; });
 193 AST_OPTIONAL_API(int, ast_adsi_query_cpeinfo, (unsigned char *buf), { return 0; });
 194
 195 /*! Get CPE ID from an attached ADSI compatible CPE.
 196  * Returns 1 on success, storing 4 bytes of CPE ID at buf
 197  * or -1 on hangup, or 0 if there was no hangup but it failed to find the
 198  * device ID.  Returns to voice mode if "voice" is non-zero.
 199  */
 200 AST_OPTIONAL_API(int, ast_adsi_get_cpeid, (struct ast_channel *chan, unsigned char *cpeid, int voice), { return 0; });
 201
 202 AST_OPTIONAL_API(int, ast_adsi_get_cpeinfo, (struct ast_channel *chan, int *width, int *height, int *buttons, int voice), { return 0; });
 203
 204 /*!
 205  * \brief Begin an ADSI script download
 206  * \param buf Character buffer to create parameter in (must have at least 256 free)
 207  * \param service a 1-18 byte name of the feature
 208  * \param fdn 4 byte Feature Download Number (for loading soft keys)
 209  * \param sec 4 byte vendor security code
 210  * \param ver version number (0-255, or -1 to omit)
 211  *
 212  * \retval number of bytes added to buffer
 213  * \retval -1 on error.
 214  */
 215
 216 AST_OPTIONAL_API(int, ast_adsi_download_connect, (unsigned char *buf, char *service, unsigned char *fdn, unsigned char *sec, int ver), { return 0; });
 217
 218 /*!
 219  * \brief Disconnects a running session.
 220  * \param buf Character buffer to create parameter in (must have at least 256 free)
 221  *
 222  * \retval number of bytes added to buffer
 223  * \retval -1 on error.
 224  */
 225 AST_OPTIONAL_API(int, ast_adsi_disconnect_session, (unsigned char *buf), { return 0; });
 226
 227 /*!
 228  * \brief Disconnects (and hopefully saves) a downloaded script
 229  * \param buf Character buffer to create parameter in (must have at least 256 free)
 230  *
 231  * \retval number of bytes added to buffer
 232  * \retval -1 on error.
 233  */
 234 AST_OPTIONAL_API(int, ast_adsi_download_disconnect, (unsigned char *buf), { return 0; });
 235
 236 /*!
 237  * \brief Puts CPE in data mode.
 238  * \param buf Character buffer to create parameter in (must have at least 256 free)
 239  *
 240  * \retval number of bytes added to buffer
 241  * \retval -1 on error.
 242  */
 243 AST_OPTIONAL_API(int, ast_adsi_data_mode, (unsigned char *buf), { return 0; });
 244 AST_OPTIONAL_API(int, ast_adsi_clear_soft_keys, (unsigned char *buf), { return 0; });
 245 AST_OPTIONAL_API(int, ast_adsi_clear_screen, (unsigned char *buf), { return 0; });
 246
 247 /*!
 248  * \brief Puts CPE in voice mode.
 249  * \param buf Character buffer to create parameter in (must have at least 256 free)
 250  * \param when (a time in seconds) to make the switch
 251  *
 252  * \retval number of bytes added to buffer
 253  * \retval -1 on error.
 254  */
 255 AST_OPTIONAL_API(int, ast_adsi_voice_mode, (unsigned char *buf, int when), { return 0; });
 256
 257 /*!
 258  * \brief Returns non-zero if Channel does or might support ADSI
 259  * \param chan Channel to check
 260  */
 261 AST_OPTIONAL_API(int, ast_adsi_available, (struct ast_channel *chan), { return 0; });
 262
 263 /*!
 264  * \brief Loads a line of info into the display.
 265  * \param buf Character buffer to create parameter in (must have at least 256 free)
 266  * \param page Page to load (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
 267  * \param line Line number to load (1-4 for Comm page, 1-33 for info page)
 268  * \param just Line justification (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CENT, ADSI_JUST_IND)
 269  * \param wrap Wrap (1 = yes, 0 = no)
 270  * \param col1 Text to place in first column
 271  * \param col2 Text to place in second column
 272  *
 273  * \retval number of bytes added to buffer
 274  * \retval -1 on error.
 275  */
 276
 277 AST_OPTIONAL_API(int, ast_adsi_display, (unsigned char *buf, int page, int line, int just, int wrap, char *col1, char *col2), { return 0; });
 278
 279 /*!
 280  * \brief Sets the current line and page.
 281  * \param buf Character buffer to create parameter in (must have at least 256 free)
 282  * \param page Which page (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
 283  * \param line Line number (1-33 for info page, 1-4 for comm page)
 284  *
 285  * \retval number of bytes added to buffer
 286  * \retval -1 on error.
 287  */
 288
 289 AST_OPTIONAL_API(int, ast_adsi_set_line, (unsigned char *buf, int page, int line), { return 0; });
 290
 291 /*!
 292  * \brief Creates "load soft key" parameters
 293  * \param buf Character buffer to create parameter in (must have at least 256 free)
 294  * \param key Key code from 2 to 33, for which key we are loading
 295  * \param llabel Long label for key (1-18 bytes)
 296  * \param slabel Short label for key (1-7 bytes)
 297  * \param ret Optional return sequence (NULL for none)
 298  * \param data whether to put CPE in data mode before sending digits
 299  *
 300  * \retval number of bytes added to buffer
 301  * \retval -1 on error.
 302  */
 303 AST_OPTIONAL_API(int, ast_adsi_load_soft_key, (unsigned char *buf, int key, const char *llabel, const char *slabel, char *ret, int data), { return 0; });
 304
 305 /*!
 306  * \brief Set which soft keys should be displayed
 307  * \param buf Character buffer to create parameter in (must have at least 256 free)
 308  * \param keys Array of 8 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
 309  *             But remember, the last two keys aren't real keys, they're for scrolling
 310  *
 311  * \retval number of bytes added to buffer
 312  * \retval -1 on error.
 313  */
 314 AST_OPTIONAL_API(int, ast_adsi_set_keys, (unsigned char *buf, unsigned char *keys), { return 0; });
 315
 316 /*!
 317  * \brief Set input information
 318  * \param buf Character buffer to create parameter in (must have at least 256 free)
 319  * \param page Which page to input on (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
 320  * \param line Line number to input on
 321  * \param display Set to zero to obscure input, or 1 to leave visible
 322  * \param format Format number to use (0-7)
 323  * \param just Justification (left, right center, indent)
 324  *
 325  * \retval number of bytes added to buffer
 326  * \retval -1 on error.
 327  */
 328 AST_OPTIONAL_API(int, ast_adsi_input_control, (unsigned char *buf, int page, int line, int display, int format, int just), { return 0; });
 329
 330 /*!
 331  * \brief Set input format
 332  * \param buf Character buffer to create parameter in (must have at least 256 free)
 333  * \param num Which format we are setting
 334  * \param dir Which direction (ADSI_DIR_FROM_LEFT or ADSI_DIR_FROM_RIGHT)
 335  * \param wrap Set to 1 to permit line wrap, or 0 if not
 336  * \param format1 Format for column 1
 337  * \param format2 Format for column 2
 338  *
 339  * \retval number of bytes added to buffer
 340  * \retval -1 on error.
 341  */
 342 AST_OPTIONAL_API(int, ast_adsi_input_format, (unsigned char *buf, int num, int dir, int wrap, char *format1, char *format2), { return 0; });
 343
 344 #endif /* _ASTERISK_ADSI_H */
 345