Merge experimental codec preferences for IAX2 (bug #2971)
[asterisk/asterisk.git] / include / asterisk / frame.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * Asterisk internal frame definitions.
5  * 
6  * Copyright (C) 1999-2004, Digium, Inc.
7  *
8  * Mark Spencer <markster@digium.com>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU Lesser General Public License.  Other components of
12  * Asterisk are distributed under The GNU General Public License
13  * only.
14  */
15
16 #ifndef _ASTERISK_FRAME_H
17 #define _ASTERISK_FRAME_H
18
19 #if defined(__cplusplus) || defined(c_plusplus)
20 extern "C" {
21 #endif
22
23 #include <sys/types.h>
24 #include <sys/time.h>
25
26 #ifdef SOLARIS
27 #include "solaris-compat/compat.h"
28 #endif
29         
30 /*
31  * Autodetect system endianess
32  */
33 #ifndef __BYTE_ORDER
34 #ifdef __linux__
35 #include <endian.h>
36 #elif defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__APPLE__)
37 #if defined(__OpenBSD__)
38 #include <machine/types.h>
39 #endif /* __OpenBSD__ */
40 #include <machine/endian.h>
41 #define __BYTE_ORDER BYTE_ORDER
42 #define __LITTLE_ENDIAN LITTLE_ENDIAN
43 #define __BIG_ENDIAN BIG_ENDIAN
44 #else
45 #ifdef __LITTLE_ENDIAN__
46 #define __BYTE_ORDER __LITTLE_ENDIAN
47 #endif /* __LITTLE_ENDIAN */
48
49 #if defined(i386) || defined(__i386__)
50 #define __BYTE_ORDER __LITTLE_ENDIAN
51 #endif /* defined i386 */
52
53 #if defined(sun) && defined(unix) && defined(sparc)
54 #define __BYTE_ORDER __BIG_ENDIAN
55 #endif /* sun unix sparc */
56
57 #endif /* linux */
58
59 #endif /* __BYTE_ORDER */
60
61 #ifndef __BYTE_ORDER
62 #error Need to know endianess
63 #endif /* __BYTE_ORDER */
64
65 struct ast_codec_pref {
66         char order[32];
67 };
68
69
70 //! Data structure associated with a single frame of data
71 /* A frame of data read used to communicate between 
72    between channels and applications */
73 struct ast_frame {
74         /*! Kind of frame */
75         int frametype;                          
76         /*! Subclass, frame dependent */
77         int subclass;                           
78         /*! Length of data */
79         int datalen;                            
80         /*! Number of 8khz samples in this frame */
81         int samples;                            
82         /*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
83         int mallocd;                            
84         /*! How far into "data" the data really starts */
85         int offset;                             
86         /*! Optional source of frame for debugging */
87         char *src;                              
88         /*! Pointer to actual data */
89         void *data;             
90         /*! Global delivery time */             
91         struct timeval delivery;
92         /*! Next/Prev for linking stand alone frames */
93         struct ast_frame *prev;                 
94         /*! Next/Prev for linking stand alone frames */
95         struct ast_frame *next;                 
96                                                                 /* Unused except if debugging is turned on, but left
97                                                                    in the struct so that it can be turned on without
98                                                                    requiring a recompile of the whole thing */
99 };
100
101 struct ast_frame_chain {
102         /* XXX Should ast_frame chain's be just prt of frames, i.e. should they just link? XXX */
103         struct ast_frame *fr;
104         struct ast_frame_chain *next;
105 };
106
107 #define AST_FRIENDLY_OFFSET     64              /*! It's polite for a a new frame to
108                                                                                 have this number of bytes for additional
109                                                                                         headers.  */
110 #define AST_MIN_OFFSET          32              /*! Make sure we keep at least this much handy */
111
112 /*! Need the header be free'd? */
113 #define AST_MALLOCD_HDR         (1 << 0)
114 /*! Need the data be free'd? */
115 #define AST_MALLOCD_DATA        (1 << 1)
116 /*! Need the source be free'd? (haha!) */
117 #define AST_MALLOCD_SRC         (1 << 2)
118
119 /* Frame types */
120 /*! A DTMF digit, subclass is the digit */
121 #define AST_FRAME_DTMF          1
122 /*! Voice data, subclass is AST_FORMAT_* */
123 #define AST_FRAME_VOICE         2
124 /*! Video frame, maybe?? :) */
125 #define AST_FRAME_VIDEO         3
126 /*! A control frame, subclass is AST_CONTROL_* */
127 #define AST_FRAME_CONTROL       4
128 /*! An empty, useless frame */
129 #define AST_FRAME_NULL          5
130 /*! Inter Asterisk Exchange private frame type */
131 #define AST_FRAME_IAX           6
132 /*! Text messages */
133 #define AST_FRAME_TEXT          7
134 /*! Image Frames */
135 #define AST_FRAME_IMAGE         8
136 /*! HTML Frame */
137 #define AST_FRAME_HTML          9
138 /*! Comfort Noise frame (subclass is level of CNG in -dBov), 
139     body may include zero or more 8-bit quantization coefficients */
140 #define AST_FRAME_CNG           10
141
142 /* HTML subclasses */
143 /*! Sending a URL */
144 #define AST_HTML_URL            1
145 /*! Data frame */
146 #define AST_HTML_DATA           2
147 /*! Beginning frame */
148 #define AST_HTML_BEGIN          4
149 /*! End frame */
150 #define AST_HTML_END            8
151 /*! Load is complete */
152 #define AST_HTML_LDCOMPLETE     16
153 /*! Peer is unable to support HTML */
154 #define AST_HTML_NOSUPPORT      17
155 /*! Send URL, and track */
156 #define AST_HTML_LINKURL        18
157 /*! No more HTML linkage */
158 #define AST_HTML_UNLINK         19
159 /*! Reject link request */
160 #define AST_HTML_LINKREJECT     20
161
162 /* Data formats for capabilities and frames alike */
163 /*! G.723.1 compression */
164 #define AST_FORMAT_G723_1       (1 << 0)
165 /*! GSM compression */
166 #define AST_FORMAT_GSM          (1 << 1)
167 /*! Raw mu-law data (G.711) */
168 #define AST_FORMAT_ULAW         (1 << 2)
169 /*! Raw A-law data (G.711) */
170 #define AST_FORMAT_ALAW         (1 << 3)
171 /*! ADPCM (G.726, 32kbps) */
172 #define AST_FORMAT_G726         (1 << 4)
173 /*! ADPCM (IMA) */
174 #define AST_FORMAT_ADPCM        (1 << 5)
175 /*! Raw 16-bit Signed Linear (8000 Hz) PCM */
176 #define AST_FORMAT_SLINEAR      (1 << 6)
177 /*! LPC10, 180 samples/frame */
178 #define AST_FORMAT_LPC10        (1 << 7)
179 /*! G.729A audio */
180 #define AST_FORMAT_G729A        (1 << 8)
181 /*! SpeeX Free Compression */
182 #define AST_FORMAT_SPEEX        (1 << 9)
183 /*! iLBC Free Compression */
184 #define AST_FORMAT_ILBC         (1 << 10)
185 /*! Maximum audio format */
186 #define AST_FORMAT_MAX_AUDIO    (1 << 15)
187 /*! JPEG Images */
188 #define AST_FORMAT_JPEG         (1 << 16)
189 /*! PNG Images */
190 #define AST_FORMAT_PNG          (1 << 17)
191 /*! H.261 Video */
192 #define AST_FORMAT_H261         (1 << 18)
193 /*! H.263 Video */
194 #define AST_FORMAT_H263         (1 << 19)
195 /*! Max one */
196 #define AST_FORMAT_MAX_VIDEO    (1 << 24)
197
198 /* Control frame types */
199 /*! Other end has hungup */
200 #define AST_CONTROL_HANGUP              1
201 /*! Local ring */
202 #define AST_CONTROL_RING                2
203 /*! Remote end is ringing */
204 #define AST_CONTROL_RINGING             3
205 /*! Remote end has answered */
206 #define AST_CONTROL_ANSWER              4
207 /*! Remote end is busy */
208 #define AST_CONTROL_BUSY                5
209 /*! Make it go off hook */
210 #define AST_CONTROL_TAKEOFFHOOK         6
211 /*! Line is off hook */
212 #define AST_CONTROL_OFFHOOK             7
213 /*! Congestion (circuits busy) */
214 #define AST_CONTROL_CONGESTION          8
215 /*! Flash hook */
216 #define AST_CONTROL_FLASH               9
217 /*! Wink */
218 #define AST_CONTROL_WINK                10
219 /*! Set a low-level option */
220 #define AST_CONTROL_OPTION              11
221 /*! Key Radio */
222 #define AST_CONTROL_RADIO_KEY           12
223 /*! Un-Key Radio */
224 #define AST_CONTROL_RADIO_UNKEY         13
225 /*! Indicate PROGRESS */
226 #define AST_CONTROL_PROGRESS            14
227 /*! Indicate CALL PROCEEDING */
228 #define AST_CONTROL_PROCEEDING          15
229
230 #define AST_SMOOTHER_FLAG_G729          (1 << 0)
231
232 /* Option identifiers and flags */
233 #define AST_OPTION_FLAG_REQUEST         0
234 #define AST_OPTION_FLAG_ACCEPT          1
235 #define AST_OPTION_FLAG_REJECT          2
236 #define AST_OPTION_FLAG_QUERY           4
237 #define AST_OPTION_FLAG_ANSWER          5
238 #define AST_OPTION_FLAG_WTF             6
239
240 /* Verify touchtones by muting audio transmission 
241         (and reception) and verify the tone is still present */
242 #define AST_OPTION_TONE_VERIFY          1               
243
244 /* Put a compatible channel into TDD (TTY for the hearing-impared) mode */
245 #define AST_OPTION_TDD                  2
246
247 /* Relax the parameters for DTMF reception (mainly for radio use) */
248 #define AST_OPTION_RELAXDTMF            3
249
250 /* Set (or clear) Audio (Not-Clear) Mode */
251 #define AST_OPTION_AUDIO_MODE           4
252
253 struct ast_option_header {
254         /* Always keep in network byte order */
255 #if __BYTE_ORDER == __BIG_ENDIAN
256         u_int16_t flag:3;
257         u_int16_t option:13;
258 #else
259 #if __BYTE_ORDER == __LITTLE_ENDIAN
260         u_int16_t option:13;
261         u_int16_t flag:3;
262 #else
263 #error Byte order not defined
264 #endif
265 #endif
266                 u_int8_t data[0];
267 };
268
269 // Requests a frame to be allocated
270 /* 
271  * \param source 
272  * Request a frame be allocated.  source is an optional source of the frame, 
273  * len is the requested length, or "0" if the caller will supply the buffer 
274  */
275 #if 0 /* Unimplemented */
276 struct ast_frame *ast_fralloc(char *source, int len);
277 #endif
278
279 //! Frees a frame
280 /*! 
281  * \param fr Frame to free
282  * Free a frame, and the memory it used if applicable
283  * no return.
284  */
285 void ast_frfree(struct ast_frame *fr);
286
287 //! Copies a frame
288 /*! 
289  * \param fr frame to act upon
290  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
291  * and if the data hasn't been malloced then make the
292  * data malloc'd.  If you need to store frames, say for queueing, then
293  * you should call this function.
294  * Returns a frame on success, NULL on error
295  */
296 struct ast_frame *ast_frisolate(struct ast_frame *fr);
297
298 //! Copies a frame
299 /*! 
300  * \param fr frame to copy
301  * Dupliates a frame -- should only rarely be used, typically frisolate is good enough
302  * Returns a frame on success, NULL on error
303  */
304 struct ast_frame *ast_frdup(struct ast_frame *fr);
305
306 //! Chains a frame -- unimplemented
307 #if 0 /* unimplemented */
308 void ast_frchain(struct ast_frame_chain *fc);
309 #endif
310
311 //! Reads a frame from an fd
312 /*! 
313  * \param fd an opened fd to read from
314  * Read a frame from a stream or packet fd, as written by fd_write
315  * returns a frame on success, NULL on error
316  */
317 struct ast_frame *ast_fr_fdread(int fd);
318
319 //! Writes a frame to an fd
320 /*! 
321  * \param fd Which fd to write to
322  * \param frame frame to write to the fd
323  * Write a frame to an fd
324  * Returns 0 on success, -1 on failure
325  */
326 int ast_fr_fdwrite(int fd, struct ast_frame *frame);
327
328 //! Sends a hangup to an fd
329 /*! 
330  * \param fd fd to write to
331  * Send a hangup (NULL equivalent) on an fd
332  * Returns 0 on success, -1 on failure
333  */
334 int ast_fr_fdhangup(int fd);
335
336 //! Get the name of a format
337 /*!
338  * \param format id of format
339  * \return A static string containing the name of the format or "UNKN" if unknown.
340  */
341 extern char* ast_getformatname(int format);
342
343 //! Get the names of a set of formats
344 /*!
345  * \param buf a buffer for the output string
346  * \param n size of buf (bytes)
347  * \param format the format (combined IDs of codecs)
348  * Prints a list of readable codec names corresponding to "format".
349  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
350  * \return The return value is buf.
351  */
352 extern char* ast_getformatname_multiple(char *buf, size_t size, int format);
353
354 /*!
355  * \param name string of format
356  * Gets a format from a name.
357  * This returns the form of the format in binary on success, 0 on error.
358  */
359 extern int ast_getformatbyname(char *name);
360
361 //! Get a name from a format
362 /*!
363  * \param codec codec number (1,2,4,8,16,etc.)
364  * Gets a name from a format
365  * This returns a static string identifying the format on success, 0 on error.
366  */
367 extern char *ast_codec2str(int codec);
368
369 //! Pick the best codec 
370 /* Choose the best codec...  Uhhh...   Yah. */
371 extern int ast_best_codec(int fmts);
372
373 struct ast_smoother;
374
375 extern struct ast_format_list *ast_get_format_list_index(int index);
376 extern struct ast_format_list *ast_get_format_list(size_t *size);
377 extern struct ast_smoother *ast_smoother_new(int bytes);
378 extern void ast_smoother_set_flags(struct ast_smoother *smoother, int flags);
379 extern int ast_smoother_get_flags(struct ast_smoother *smoother);
380 extern void ast_smoother_free(struct ast_smoother *s);
381 extern void ast_smoother_reset(struct ast_smoother *s, int bytes);
382 extern int ast_smoother_feed(struct ast_smoother *s, struct ast_frame *f);
383 extern struct ast_frame *ast_smoother_read(struct ast_smoother *s);
384
385 extern void ast_frame_dump(char *name, struct ast_frame *f, char *prefix);
386
387 /* Initialize a codec preference to "no preference" */
388 extern void ast_codec_pref_init(struct ast_codec_pref *pref);
389
390 /* Codec located at  a particular place in the preference index */
391 extern int ast_codec_pref_index(struct ast_codec_pref *pref, int index);
392
393 /* Remove a codec from a preference list */
394 extern void ast_codec_pref_remove(struct ast_codec_pref *pref, int format);
395
396 /* Append a codec to a preference list, removing it first if it was already there */
397 extern int ast_codec_pref_append(struct ast_codec_pref *pref, int format);
398
399 /* Select the best format according to preference list from supplied options. 
400    If "find_best" is non-zero then if nothing is found, the "Best" format of 
401    the format list is selected, otherwise 0 is returned. */
402 extern int ast_codec_choose(struct ast_codec_pref *pref, int formats, int find_best);
403
404 /* Parse an "allow" or "deny" line and update the mask and pref if provided */
405 extern void ast_parse_allow_disallow(struct ast_codec_pref *pref, int *mask, char *list, int allowing);
406
407 /* Dump codec preference list into a string */
408 extern int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
409
410 /* Shift a codec preference list up or down 65 bytes so that it becomes an ASCII string */
411 extern void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
412
413 #if defined(__cplusplus) || defined(c_plusplus)
414 }
415 #endif
416
417
418 #endif