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