Version 0.1.9 from FTP
[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 /* A frame of data read used to communicate between 
27    between channels and applications */
28 struct ast_frame {
29         int frametype;                          /* Kind of frame */
30         int subclass;                           /* Subclass, frame dependent */
31         int datalen;                            /* Length of data */
32         int timelen;                            /* Amount of time associated with this frame */
33         int mallocd;                            /* Was the data malloc'd?  i.e. should we
34                                                                    free it when we discard the frame? */
35         int offset;                                     /* How far into "data" the data really starts */
36         char *src;                                      /* Optional source of frame for debugging */
37         void *data;                                     /* Pointer to actual data */
38         struct ast_frame *prev;         /* Next/Prev for linking stand alone frames */
39         struct ast_frame *next;         /* Next/Prev for linking stand alone frames */
40                                                                 /* Unused except if debugging is turned on, but left
41                                                                    in the struct so that it can be turned on without
42                                                                    requiring a recompile of the whole thing */
43 };
44
45 struct ast_frame_chain {
46         /* XXX Should ast_frame chain's be just prt of frames, i.e. should they just link? XXX */
47         struct ast_frame *fr;
48         struct ast_frame_chain *next;
49 };
50
51 #define AST_FRIENDLY_OFFSET     64              /* It's polite for a a new frame to
52                                                                                    have at least this number of bytes
53                                                                                    of offset before your real frame data
54                                                                                    so that additional headers can be
55                                                                                    added. */
56
57 #define AST_MALLOCD_HDR         (1 << 0)        /* Need the header be free'd? */
58 #define AST_MALLOCD_DATA        (1 << 1)        /* Need the data be free'd? */
59 #define AST_MALLOCD_SRC         (1 << 2)        /* Need the source be free'd? (haha!) */
60
61 /* Frame types */
62 #define AST_FRAME_DTMF          1               /* A DTMF digit, subclass is the digit */
63 #define AST_FRAME_VOICE         2               /* Voice data, subclass is AST_FORMAT_* */
64 #define AST_FRAME_VIDEO         3               /* Video frame, maybe?? :) */
65 #define AST_FRAME_CONTROL       4               /* A control frame, subclass is AST_CONTROL_* */
66 #define AST_FRAME_NULL          5               /* An empty, useless frame */
67 #define AST_FRAME_IAX           6               /* Inter Aterisk Exchange private frame type */
68 #define AST_FRAME_TEXT          7               /* Text messages */
69 #define AST_FRAME_IMAGE         8               /* Image Frames */
70 #define AST_FRAME_HTML          9               /* HTML Frame */
71
72 /* HTML subclasses */
73 #define AST_HTML_URL            1               /* Sending a URL */
74 #define AST_HTML_DATA           2               /* Data frame */
75 #define AST_HTML_BEGIN          4               /* Beginning frame */
76 #define AST_HTML_END            8               /* End frame */
77 #define AST_HTML_LDCOMPLETE     16              /* Load is complete */
78 #define AST_HTML_NOSUPPORT      17              /* Peer is unable to support HTML */
79 #define AST_HTML_LINKURL        18              /* Send URL, and track */
80
81 /* Data formats for capabilities and frames alike */
82 #define AST_FORMAT_G723_1       (1 << 0)        /* G.723.1 compression */
83 #define AST_FORMAT_GSM          (1 << 1)        /* GSM compression */
84 #define AST_FORMAT_ULAW         (1 << 2)        /* Raw mu-law data (G.711) */
85 #define AST_FORMAT_ALAW         (1 << 3)        /* Raw A-law data (G.711) */
86 #define AST_FORMAT_MP3          (1 << 4)        /* MPEG-2 layer 3 */
87 #define AST_FORMAT_ADPCM        (1 << 5)        /* ADPCM (whose?) */
88 #define AST_FORMAT_SLINEAR      (1 << 6)        /* Raw 16-bit Signed Linear (8000 Hz) PCM */
89 #define AST_FORMAT_LPC10        (1 << 7)        /* LPC10, 180 samples/frame */
90 #define AST_FORMAT_MAX_AUDIO (1 << 15)  /* Maximum audio format */
91 #define AST_FORMAT_JPEG         (1 << 16)       /* JPEG Images */
92 #define AST_FORMAT_PNG          (1 << 17)       /* PNG Images */
93 #define AST_FORMAT_H261         (1 << 18)       /* H.261 Video */
94 #define AST_FORMAT_H263         (1 << 19)       /* H.263 Video */
95
96 /* Control frame types */
97 #define AST_CONTROL_HANGUP              1                       /* Other end has hungup */
98 #define AST_CONTROL_RING                2                       /* Local ring */
99 #define AST_CONTROL_RINGING     3                       /* Remote end is ringing */
100 #define AST_CONTROL_ANSWER              4                       /* Remote end has answered */
101 #define AST_CONTROL_BUSY                5                       /* Remote end is busy */
102 #define AST_CONTROL_TAKEOFFHOOK 6                       /* Make it go off hook */
103 #define AST_CONTROL_OFFHOOK             7                       /* Line is off hook */
104 #define AST_CONTROL_CONGESTION  8                       /* Congestion (circuits busy) */
105 #define AST_CONTROL_FLASH               9                       /* Flash hook */
106 #define AST_CONTROL_WINK                10                      /* Wink */
107 #define AST_CONTROL_OPTION              11                      /* Set a low-level option */
108
109 /* Option identifiers and flags */
110 #define AST_OPTION_FLAG_REQUEST         0
111 #define AST_OPTION_FLAG_ACCEPT          1
112 #define AST_OPTION_FLAG_REJECT          2
113 #define AST_OPTION_FLAG_QUERY           4
114 #define AST_OPTION_FLAG_ANSWER          5
115 #define AST_OPTION_FLAG_WTF                     6
116
117 #define AST_OPTION_TONE_VERIFY          1               /* Verify touchtones by muting audio
118                                                                                            transmission (and reception) and
119                                                                                            verify the tone is still present */
120
121 struct ast_option_header {
122         /* Always keep in network byte order */
123 #if __BYTE_ORDER == __BIG_ENDIAN
124         u_int16_t flag:3;
125         u_int16_t option:13;
126 #else
127 #if __BYTE_ORDER == __LITTLE_ENDIAN
128         u_int16_t option:13;
129         u_int16_t flag:3;
130 #else
131 #error Byte order not defined
132 #endif
133 #endif
134                 u_int8_t data[0];
135 };
136
137 /* Request a frame be allocated.  source is an optional source of the frame, 
138    len is the requested length, or "0" if the caller will supply the buffer */
139 struct ast_frame *ast_fralloc(char *source, int len);
140
141 /* Free a frame, and the memory it used if applicable */
142 void ast_frfree(struct ast_frame *fr);
143
144 /* Take a frame, and if it's not been malloc'd, make a malloc'd copy
145    and if the data hasn't been malloced then make the
146    data malloc'd.  If you need to store frames, say for queueing, then
147    you should call this function. */
148 struct ast_frame *ast_frisolate(struct ast_frame *fr);
149
150 /* Dupliates a frame -- should only rarely be used, typically frisolate is
151    good enough */
152 struct ast_frame *ast_frdup(struct ast_frame *fr);
153
154 void ast_frchain(struct ast_frame_chain *fc);
155
156 /* Read a frame from a stream or packet fd, as written by fd_write */
157 struct ast_frame *ast_fr_fdread(int fd);
158
159 /* Write a frame to an fd */
160 int ast_fr_fdwrite(int fd, struct ast_frame *frame);
161
162 /* Send a hangup (NULL equivalent) on an fd */
163 int ast_fr_fdhangup(int fd);
164
165 /* Get a format by its name */
166 extern int ast_getformatbyname(char *name);
167
168 /* Choose the best codec...  Uhhh...   Yah. */
169 extern int ast_best_codec(int fmts);
170
171 #if defined(__cplusplus) || defined(c_plusplus)
172 }
173 #endif
174
175
176 #endif