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