include/asterisk/frame.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   3  *
   4  * Asterisk internal frame definitions.
   5  *
   6  * Copyright (C) 1999 - 2005, Digium, Inc.
   7  *
   8  * Mark Spencer <markster@digium.com>
   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 <sys/types.h>
  24 #include <sys/time.h>
  25 #include <asterisk/endian.h>
  26
  27 struct ast_codec_pref {
  28         char order[32];
  29 };
  30
  31
  32 /*! Data structure associated with a single frame of data */
  33 /* A frame of data read used to communicate between
  34    between channels and applications */
  35 struct ast_frame {
  36         /*! Kind of frame */
  37         int frametype;
  38         /*! Subclass, frame dependent */
  39         int subclass;
  40         /*! Length of data */
  41         int datalen;
  42         /*! Number of 8khz samples in this frame */
  43         int samples;
  44         /*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
  45         int mallocd;
  46         /*! How far into "data" the data really starts */
  47         int offset;
  48         /*! Optional source of frame for debugging */
  49         const char *src;
  50         /*! Pointer to actual data */
  51         void *data;
  52         /*! Global delivery time */
  53         struct timeval delivery;
  54         /*! Next/Prev for linking stand alone frames */
  55         struct ast_frame *prev;
  56         /*! Next/Prev for linking stand alone frames */
  57         struct ast_frame *next;
  58                                                                 /* Unused except if debugging is turned on, but left
  59                                                                    in the struct so that it can be turned on without
  60                                                                    requiring a recompile of the whole thing */
  61 };
  62
  63 struct ast_frame_chain {
  64         /* XXX Should ast_frame chain's be just prt of frames, i.e. should they just link? XXX */
  65         struct ast_frame *fr;
  66         struct ast_frame_chain *next;
  67 };
  68
  69 #define AST_FRIENDLY_OFFSET     64              /*! It's polite for a a new frame to
  70                                                                                 have this number of bytes for additional
  71                                                                                         headers.  */
  72 #define AST_MIN_OFFSET          32              /*! Make sure we keep at least this much handy */
  73
  74 /*! Need the header be free'd? */
  75 #define AST_MALLOCD_HDR         (1 << 0)
  76 /*! Need the data be free'd? */
  77 #define AST_MALLOCD_DATA        (1 << 1)
  78 /*! Need the source be free'd? (haha!) */
  79 #define AST_MALLOCD_SRC         (1 << 2)
  80
  81 /* Frame types */
  82 /*! A DTMF digit, subclass is the digit */
  83 #define AST_FRAME_DTMF          1
  84 /*! Voice data, subclass is AST_FORMAT_* */
  85 #define AST_FRAME_VOICE         2
  86 /*! Video frame, maybe?? :) */
  87 #define AST_FRAME_VIDEO         3
  88 /*! A control frame, subclass is AST_CONTROL_* */
  89 #define AST_FRAME_CONTROL       4
  90 /*! An empty, useless frame */
  91 #define AST_FRAME_NULL          5
  92 /*! Inter Asterisk Exchange private frame type */
  93 #define AST_FRAME_IAX           6
  94 /*! Text messages */
  95 #define AST_FRAME_TEXT          7
  96 /*! Image Frames */
  97 #define AST_FRAME_IMAGE         8
  98 /*! HTML Frame */
  99 #define AST_FRAME_HTML          9
 100 /*! Comfort Noise frame (subclass is level of CNG in -dBov),
 101     body may include zero or more 8-bit quantization coefficients */
 102 #define AST_FRAME_CNG           10
 103
 104 /* HTML subclasses */
 105 /*! Sending a URL */
 106 #define AST_HTML_URL            1
 107 /*! Data frame */
 108 #define AST_HTML_DATA           2
 109 /*! Beginning frame */
 110 #define AST_HTML_BEGIN          4
 111 /*! End frame */
 112 #define AST_HTML_END            8
 113 /*! Load is complete */
 114 #define AST_HTML_LDCOMPLETE     16
 115 /*! Peer is unable to support HTML */
 116 #define AST_HTML_NOSUPPORT      17
 117 /*! Send URL, and track */
 118 #define AST_HTML_LINKURL        18
 119 /*! No more HTML linkage */
 120 #define AST_HTML_UNLINK         19
 121 /*! Reject link request */
 122 #define AST_HTML_LINKREJECT     20
 123
 124 /* Data formats for capabilities and frames alike */
 125 /*! G.723.1 compression */
 126 #define AST_FORMAT_G723_1       (1 << 0)
 127 /*! GSM compression */
 128 #define AST_FORMAT_GSM          (1 << 1)
 129 /*! Raw mu-law data (G.711) */
 130 #define AST_FORMAT_ULAW         (1 << 2)
 131 /*! Raw A-law data (G.711) */
 132 #define AST_FORMAT_ALAW         (1 << 3)
 133 /*! ADPCM (G.726, 32kbps) */
 134 #define AST_FORMAT_G726         (1 << 4)
 135 /*! ADPCM (IMA) */
 136 #define AST_FORMAT_ADPCM        (1 << 5)
 137 /*! Raw 16-bit Signed Linear (8000 Hz) PCM */
 138 #define AST_FORMAT_SLINEAR      (1 << 6)
 139 /*! LPC10, 180 samples/frame */
 140 #define AST_FORMAT_LPC10        (1 << 7)
 141 /*! G.729A audio */
 142 #define AST_FORMAT_G729A        (1 << 8)
 143 /*! SpeeX Free Compression */
 144 #define AST_FORMAT_SPEEX        (1 << 9)
 145 /*! iLBC Free Compression */
 146 #define AST_FORMAT_ILBC         (1 << 10)
 147 /*! Maximum audio format */
 148 #define AST_FORMAT_MAX_AUDIO    (1 << 15)
 149 /*! JPEG Images */
 150 #define AST_FORMAT_JPEG         (1 << 16)
 151 /*! PNG Images */
 152 #define AST_FORMAT_PNG          (1 << 17)
 153 /*! H.261 Video */
 154 #define AST_FORMAT_H261         (1 << 18)
 155 /*! H.263 Video */
 156 #define AST_FORMAT_H263         (1 << 19)
 157 /*! H.263+ Video */
 158 #define AST_FORMAT_H263_PLUS    (1 << 20)
 159 /*! Max one */
 160 #define AST_FORMAT_MAX_VIDEO    (1 << 24)
 161
 162 /* Control frame types */
 163 /*! Other end has hungup */
 164 #define AST_CONTROL_HANGUP              1
 165 /*! Local ring */
 166 #define AST_CONTROL_RING                2
 167 /*! Remote end is ringing */
 168 #define AST_CONTROL_RINGING             3
 169 /*! Remote end has answered */
 170 #define AST_CONTROL_ANSWER              4
 171 /*! Remote end is busy */
 172 #define AST_CONTROL_BUSY                5
 173 /*! Make it go off hook */
 174 #define AST_CONTROL_TAKEOFFHOOK         6
 175 /*! Line is off hook */
 176 #define AST_CONTROL_OFFHOOK             7
 177 /*! Congestion (circuits busy) */
 178 #define AST_CONTROL_CONGESTION          8
 179 /*! Flash hook */
 180 #define AST_CONTROL_FLASH               9
 181 /*! Wink */
 182 #define AST_CONTROL_WINK                10
 183 /*! Set a low-level option */
 184 #define AST_CONTROL_OPTION              11
 185 /*! Key Radio */
 186 #define AST_CONTROL_RADIO_KEY           12
 187 /*! Un-Key Radio */
 188 #define AST_CONTROL_RADIO_UNKEY         13
 189 /*! Indicate PROGRESS */
 190 #define AST_CONTROL_PROGRESS            14
 191 /*! Indicate CALL PROCEEDING */
 192 #define AST_CONTROL_PROCEEDING          15
 193 /*! Indicate call is placed on hold */
 194 #define AST_CONTROL_HOLD                        16
 195 /*! Indicate call is left from hold */
 196 #define AST_CONTROL_UNHOLD                      17
 197
 198 #define AST_SMOOTHER_FLAG_G729          (1 << 0)
 199
 200 /* Option identifiers and flags */
 201 #define AST_OPTION_FLAG_REQUEST         0
 202 #define AST_OPTION_FLAG_ACCEPT          1
 203 #define AST_OPTION_FLAG_REJECT          2
 204 #define AST_OPTION_FLAG_QUERY           4
 205 #define AST_OPTION_FLAG_ANSWER          5
 206 #define AST_OPTION_FLAG_WTF             6
 207
 208 /* Verify touchtones by muting audio transmission
 209         (and reception) and verify the tone is still present */
 210 #define AST_OPTION_TONE_VERIFY          1
 211
 212 /* Put a compatible channel into TDD (TTY for the hearing-impared) mode */
 213 #define AST_OPTION_TDD                  2
 214
 215 /* Relax the parameters for DTMF reception (mainly for radio use) */
 216 #define AST_OPTION_RELAXDTMF            3
 217
 218 /* Set (or clear) Audio (Not-Clear) Mode */
 219 #define AST_OPTION_AUDIO_MODE           4
 220
 221 struct ast_option_header {
 222         /* Always keep in network byte order */
 223 #if __BYTE_ORDER == __BIG_ENDIAN
 224         u_int16_t flag:3;
 225         u_int16_t option:13;
 226 #else
 227 #if __BYTE_ORDER == __LITTLE_ENDIAN
 228         u_int16_t option:13;
 229         u_int16_t flag:3;
 230 #else
 231 #error Byte order not defined
 232 #endif
 233 #endif
 234                 u_int8_t data[0];
 235 };
 236
 237 /*  Requests a frame to be allocated */
 238 /*
 239  * \param source
 240  * Request a frame be allocated.  source is an optional source of the frame,
 241  * len is the requested length, or "0" if the caller will supply the buffer
 242  */
 243 #if 0 /* Unimplemented */
 244 struct ast_frame *ast_fralloc(char *source, int len);
 245 #endif
 246
 247 /*! Frees a frame */
 248 /*!
 249  * \param fr Frame to free
 250  * Free a frame, and the memory it used if applicable
 251  * no return.
 252  */
 253 void ast_frfree(struct ast_frame *fr);
 254
 255 /*! Copies a frame */
 256 /*!
 257  * \param fr frame to act upon
 258  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
 259  * and if the data hasn't been malloced then make the
 260  * data malloc'd.  If you need to store frames, say for queueing, then
 261  * you should call this function.
 262  * Returns a frame on success, NULL on error
 263  */
 264 struct ast_frame *ast_frisolate(struct ast_frame *fr);
 265
 266 /*! Copies a frame */
 267 /*!
 268  * \param fr frame to copy
 269  * Dupliates a frame -- should only rarely be used, typically frisolate is good enough
 270  * Returns a frame on success, NULL on error
 271  */
 272 struct ast_frame *ast_frdup(struct ast_frame *fr);
 273
 274 /*! Chains a frame -- unimplemented */
 275 #if 0 /* unimplemented */
 276 void ast_frchain(struct ast_frame_chain *fc);
 277 #endif
 278
 279 /*! Reads a frame from an fd */
 280 /*!
 281  * \param fd an opened fd to read from
 282  * Read a frame from a stream or packet fd, as written by fd_write
 283  * returns a frame on success, NULL on error
 284  */
 285 struct ast_frame *ast_fr_fdread(int fd);
 286
 287 /*! Writes a frame to an fd */
 288 /*!
 289  * \param fd Which fd to write to
 290  * \param frame frame to write to the fd
 291  * Write a frame to an fd
 292  * Returns 0 on success, -1 on failure
 293  */
 294 int ast_fr_fdwrite(int fd, struct ast_frame *frame);
 295
 296 /*! Sends a hangup to an fd */
 297 /*!
 298  * \param fd fd to write to
 299  * Send a hangup (NULL equivalent) on an fd
 300  * Returns 0 on success, -1 on failure
 301  */
 302 int ast_fr_fdhangup(int fd);
 303
 304 void ast_swapcopy_samples(void *dst, void *src, int samples);
 305
 306 /* Helpers for byteswapping native samples to/from
 307    little-endian and big-endian. */
 308 #if __BYTE_ORDER == __LITTLE_ENDIAN
 309 #define ast_frame_byteswap_le(fr) do { ; } while(0)
 310 #define ast_frame_byteswap_be(fr) do { struct ast_frame *__f = (fr); ast_swapcopy_samples(__f->data, __f->data, __f->samples); } while(0)
 311 #else
 312 #define ast_frame_byteswap_le(fr) do { struct ast_frame *__f = (fr); ast_swapcopy_samples(__f->data, __f->data, __f->samples); } while(0)
 313 #define ast_frame_byteswap_be(fr) do { ; } while(0)
 314 #endif
 315
 316
 317 /*! Get the name of a format */
 318 /*!
 319  * \param format id of format
 320  * \return A static string containing the name of the format or "UNKN" if unknown.
 321  */
 322 extern char* ast_getformatname(int format);
 323
 324 /*! Get the names of a set of formats */
 325 /*!
 326  * \param buf a buffer for the output string
 327  * \param n size of buf (bytes)
 328  * \param format the format (combined IDs of codecs)
 329  * Prints a list of readable codec names corresponding to "format".
 330  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
 331  * \return The return value is buf.
 332  */
 333 extern char* ast_getformatname_multiple(char *buf, size_t size, int format);
 334
 335 /*!
 336  * \param name string of format
 337  * Gets a format from a name.
 338  * This returns the form of the format in binary on success, 0 on error.
 339  */
 340 extern int ast_getformatbyname(char *name);
 341
 342 /*! Get a name from a format */
 343 /*!
 344  * \param codec codec number (1,2,4,8,16,etc.)
 345  * Gets a name from a format
 346  * This returns a static string identifying the format on success, 0 on error.
 347  */
 348 extern char *ast_codec2str(int codec);
 349
 350 /*! Pick the best codec  */
 351 /* Choose the best codec...  Uhhh...   Yah. */
 352 extern int ast_best_codec(int fmts);
 353
 354 struct ast_smoother;
 355
 356 extern struct ast_format_list *ast_get_format_list_index(int index);
 357 extern struct ast_format_list *ast_get_format_list(size_t *size);
 358 extern struct ast_smoother *ast_smoother_new(int bytes);
 359 extern void ast_smoother_set_flags(struct ast_smoother *smoother, int flags);
 360 extern int ast_smoother_get_flags(struct ast_smoother *smoother);
 361 extern void ast_smoother_free(struct ast_smoother *s);
 362 extern void ast_smoother_reset(struct ast_smoother *s, int bytes);
 363 extern int __ast_smoother_feed(struct ast_smoother *s, struct ast_frame *f, int swap);
 364 extern struct ast_frame *ast_smoother_read(struct ast_smoother *s);
 365 #define ast_smoother_feed(s,f) do { __ast_smoother_feed(s, f, 0); } while(0)
 366 #if __BYTE_ORDER == __LITTLE_ENDIAN
 367 #define ast_smoother_feed_be(s,f) do { __ast_smoother_feed(s, f, 1); } while(0)
 368 #define ast_smoother_feed_le(s,f) do { __ast_smoother_feed(s, f, 0); } while(0)
 369 #else
 370 #define ast_smoother_feed_be(s,f) do { __ast_smoother_feed(s, f, 0); } while(0)
 371 #define ast_smoother_feed_le(s,f) do { __ast_smoother_feed(s, f, 1); } while(0)
 372 #endif
 373
 374 extern void ast_frame_dump(char *name, struct ast_frame *f, char *prefix);
 375
 376 /* Initialize a codec preference to "no preference" */
 377 extern void ast_codec_pref_init(struct ast_codec_pref *pref);
 378
 379 /* Codec located at  a particular place in the preference index */
 380 extern int ast_codec_pref_index(struct ast_codec_pref *pref, int index);
 381
 382 /* Remove a codec from a preference list */
 383 extern void ast_codec_pref_remove(struct ast_codec_pref *pref, int format);
 384
 385 /* Append a codec to a preference list, removing it first if it was already there */
 386 extern int ast_codec_pref_append(struct ast_codec_pref *pref, int format);
 387
 388 /* Select the best format according to preference list from supplied options.
 389    If "find_best" is non-zero then if nothing is found, the "Best" format of
 390    the format list is selected, otherwise 0 is returned. */
 391 extern int ast_codec_choose(struct ast_codec_pref *pref, int formats, int find_best);
 392
 393 /* Parse an "allow" or "deny" line and update the mask and pref if provided */
 394 extern void ast_parse_allow_disallow(struct ast_codec_pref *pref, int *mask, char *list, int allowing);
 395
 396 /* Dump codec preference list into a string */
 397 extern int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
 398
 399 /* Shift a codec preference list up or down 65 bytes so that it becomes an ASCII string */
 400 extern void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
 401
 402 #if defined(__cplusplus) || defined(c_plusplus)
 403 }
 404 #endif
 405
 406
 407 #endif