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