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