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