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