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