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