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