include/asterisk/frame.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Asterisk internal frame definitions.
  21  * \arg For an explanation of frames, see \ref Def_Frame
  22  * \arg Frames are send of Asterisk channels, see \ref Def_Channel
  23  */
  24
  25 #ifndef _ASTERISK_FRAME_H
  26 #define _ASTERISK_FRAME_H
  27
  28 #if defined(__cplusplus) || defined(c_plusplus)
  29 extern "C" {
  30 #endif
  31
  32 #include <sys/time.h>
  33
  34 #include "asterisk/format.h"
  35 #include "asterisk/endian.h"
  36 #include "asterisk/linkedlists.h"
  37
  38 /*!
  39  * \page Def_Frame AST Multimedia and signalling frames
  40  * \section Def_AstFrame What is an ast_frame ?
  41  * A frame of data read used to communicate between
  42  * between channels and applications.
  43  * Frames are divided into frame types and subclasses.
  44  *
  45  * \par Frame types
  46  * \arg \b VOICE:  Voice data, subclass is codec (AST_FORMAT_*)
  47  * \arg \b VIDEO:  Video data, subclass is codec (AST_FORMAT_*)
  48  * \arg \b DTMF:   A DTMF digit, subclass is the digit
  49  * \arg \b IMAGE:  Image transport, mostly used in IAX
  50  * \arg \b TEXT:   Text messages and character by character (real time text)
  51  * \arg \b HTML:   URL's and web pages
  52  * \arg \b MODEM:  Modulated data encodings, such as T.38 and V.150
  53  * \arg \b IAX:    Private frame type for the IAX protocol
  54  * \arg \b CNG:    Comfort noice frames
  55  * \arg \b CONTROL:A control frame, subclass defined as AST_CONTROL_
  56  * \arg \b NULL:   Empty, useless frame
  57  *
  58  * \par Files
  59  * \arg frame.h    Definitions
  60  * \arg frame.c    Function library
  61  * \arg \ref Def_Channel Asterisk channels
  62  * \section Def_ControlFrame Control Frames
  63  * Control frames send signalling information between channels
  64  * and devices. They are prefixed with AST_CONTROL_, like AST_CONTROL_FRAME_HANGUP
  65  * \arg \b HANGUP          The other end has hungup
  66  * \arg \b RING            Local ring
  67  * \arg \b RINGING         The other end is ringing
  68  * \arg \b ANSWER          The other end has answered
  69  * \arg \b BUSY            Remote end is busy
  70  * \arg \b TAKEOFFHOOK     Make it go off hook (what's "it" ? )
  71  * \arg \b OFFHOOK         Line is off hook
  72  * \arg \b CONGESTION      Congestion (circuit is busy, not available)
  73  * \arg \b FLASH           Other end sends flash hook
  74  * \arg \b WINK            Other end sends wink
  75  * \arg \b OPTION          Send low-level option
  76  * \arg \b RADIO_KEY       Key radio (see app_rpt.c)
  77  * \arg \b RADIO_UNKEY     Un-key radio (see app_rpt.c)
  78  * \arg \b PROGRESS        Other end indicates call progress
  79  * \arg \b PROCEEDING      Indicates proceeding
  80  * \arg \b HOLD            Call is placed on hold
  81  * \arg \b UNHOLD          Call is back from hold
  82  * \arg \b VIDUPDATE       Video update requested
  83  * \arg \b SRCUPDATE       The source of media has changed (RTP marker bit must change)
  84  * \arg \b SRCCHANGE       Media source has changed (RTP marker bit and SSRC must change)
  85  * \arg \b CONNECTED_LINE  Connected line has changed
  86  * \arg \b REDIRECTING     Call redirecting information has changed.
  87  */
  88
  89 /*!
  90  * \brief Frame types
  91  *
  92  * \note It is important that the values of each frame type are never changed,
  93  *       because it will break backwards compatability with older versions.
  94  *       This is because these constants are transmitted directly over IAX2.
  95  */
  96 enum ast_frame_type {
  97         /*! DTMF end event, subclass is the digit */
  98         AST_FRAME_DTMF_END = 1,
  99         /*! Voice data, subclass is AST_FORMAT_* */
 100         AST_FRAME_VOICE,
 101         /*! Video frame, maybe?? :) */
 102         AST_FRAME_VIDEO,
 103         /*! A control frame, subclass is AST_CONTROL_* */
 104         AST_FRAME_CONTROL,
 105         /*! An empty, useless frame */
 106         AST_FRAME_NULL,
 107         /*! Inter Asterisk Exchange private frame type */
 108         AST_FRAME_IAX,
 109         /*! Text messages */
 110         AST_FRAME_TEXT,
 111         /*! Image Frames */
 112         AST_FRAME_IMAGE,
 113         /*! HTML Frame */
 114         AST_FRAME_HTML,
 115         /*! Comfort Noise frame (subclass is level of CNG in -dBov),
 116             body may include zero or more 8-bit quantization coefficients */
 117         AST_FRAME_CNG,
 118         /*! Modem-over-IP data streams */
 119         AST_FRAME_MODEM,
 120         /*! DTMF begin event, subclass is the digit */
 121         AST_FRAME_DTMF_BEGIN,
 122         /*! Internal bridge module action. */
 123         AST_FRAME_BRIDGE_ACTION,
 124         /*! Internal synchronous bridge module action.
 125          * Synchronous bridge actions may be queued onto bridge
 126          * channels, but they absolutely must not ever be written
 127          * directly into bridges.
 128          */
 129         AST_FRAME_BRIDGE_ACTION_SYNC,
 130 };
 131 #define AST_FRAME_DTMF AST_FRAME_DTMF_END
 132
 133 enum {
 134         /*! This frame contains valid timing information */
 135         AST_FRFLAG_HAS_TIMING_INFO = (1 << 0),
 136         /*! This frame has been requeued */
 137         AST_FRFLAG_REQUEUED = (1 << 1),
 138 };
 139
 140 struct ast_frame_subclass {
 141         /*! A frame specific code */
 142         int integer;
 143         /*! The asterisk media format */
 144         struct ast_format *format;
 145         /*! For video formats, an indication that a frame ended */
 146         unsigned int frame_ending;
 147 };
 148
 149 /*! \brief Data structure associated with a single frame of data
 150  */
 151 struct ast_frame {
 152         /*! Kind of frame */
 153         enum ast_frame_type frametype;
 154         /*! Subclass, frame dependent */
 155         struct ast_frame_subclass subclass;
 156         /*! Length of data */
 157         int datalen;
 158         /*! Number of samples in this frame */
 159         int samples;
 160         /*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
 161         int mallocd;
 162         /*! The number of bytes allocated for a malloc'd frame header */
 163         size_t mallocd_hdr_len;
 164         /*! How many bytes exist _before_ "data" that can be used if needed */
 165         int offset;
 166         /*! Optional source of frame for debugging */
 167         const char *src;
 168         /*! Pointer to actual data */
 169         union { void *ptr; uint32_t uint32; char pad[8]; } data;
 170         /*! Global delivery time */
 171         struct timeval delivery;
 172         /*! For placing in a linked list */
 173         AST_LIST_ENTRY(ast_frame) frame_list;
 174         /*! Misc. frame flags */
 175         unsigned int flags;
 176         /*! Timestamp in milliseconds */
 177         long ts;
 178         /*! Length in milliseconds */
 179         long len;
 180         /*! Sequence number */
 181         int seqno;
 182 };
 183
 184 /*!
 185  * Set the various field of a frame to point to a buffer.
 186  * Typically you set the base address of the buffer, the offset as
 187  * AST_FRIENDLY_OFFSET, and the datalen as the amount of bytes queued.
 188  * The remaining things (to be done manually) is set the number of
 189  * samples, which cannot be derived from the datalen unless you know
 190  * the number of bits per sample.
 191  */
 192 #define AST_FRAME_SET_BUFFER(fr, _base, _ofs, _datalen) \
 193         {                                       \
 194         (fr)->data.ptr = (char *)_base + (_ofs);        \
 195         (fr)->offset = (_ofs);                  \
 196         (fr)->datalen = (_datalen);             \
 197         }
 198
 199 /*! Queueing a null frame is fairly common, so we declare a global null frame object
 200     for this purpose instead of having to declare one on the stack */
 201 extern struct ast_frame ast_null_frame;
 202
 203 /*! \brief Offset into a frame's data buffer.
 204  *
 205  * By providing some "empty" space prior to the actual data of an ast_frame,
 206  * this gives any consumer of the frame ample space to prepend other necessary
 207  * information without having to create a new buffer.
 208  *
 209  * As an example, RTP can use the data from an ast_frame and simply prepend the
 210  * RTP header information into the space provided by AST_FRIENDLY_OFFSET instead
 211  * of having to create a new buffer with the necessary space allocated.
 212  */
 213 #define AST_FRIENDLY_OFFSET     64
 214 #define AST_MIN_OFFSET          32      /*! Make sure we keep at least this much handy */
 215
 216 /*! Need the header be free'd? */
 217 #define AST_MALLOCD_HDR         (1 << 0)
 218 /*! Need the data be free'd? */
 219 #define AST_MALLOCD_DATA        (1 << 1)
 220 /*! Need the source be free'd? (haha!) */
 221 #define AST_MALLOCD_SRC         (1 << 2)
 222
 223 /* MODEM subclasses */
 224 /*! T.38 Fax-over-IP */
 225 #define AST_MODEM_T38           1
 226 /*! V.150 Modem-over-IP */
 227 #define AST_MODEM_V150          2
 228
 229 /* HTML subclasses */
 230 /*! Sending a URL */
 231 #define AST_HTML_URL            1
 232 /*! Data frame */
 233 #define AST_HTML_DATA           2
 234 /*! Beginning frame */
 235 #define AST_HTML_BEGIN          4
 236 /*! End frame */
 237 #define AST_HTML_END            8
 238 /*! Load is complete */
 239 #define AST_HTML_LDCOMPLETE     16
 240 /*! Peer is unable to support HTML */
 241 #define AST_HTML_NOSUPPORT      17
 242 /*! Send URL, and track */
 243 #define AST_HTML_LINKURL        18
 244 /*! No more HTML linkage */
 245 #define AST_HTML_UNLINK         19
 246 /*! Reject link request */
 247 #define AST_HTML_LINKREJECT     20
 248
 249 /*!
 250  * \brief Internal control frame subtype field values.
 251  *
 252  * \warning
 253  * IAX2 sends these values out over the wire.  To prevent future
 254  * incompatibilities, pick the next value in the enum from whatever
 255  * is on the current trunk.  If you lose the merge race you need to
 256  * fix the previous branches to match what is on trunk.  In addition
 257  * you need to change chan_iax2 to explicitly allow the control
 258  * frame over the wire if it makes sense for the frame to be passed
 259  * to another Asterisk instance.
 260  */
 261 enum ast_control_frame_type {
 262         AST_CONTROL_HANGUP = 1,                 /*!< Other end has hungup */
 263         AST_CONTROL_RING = 2,                   /*!< Local ring */
 264         AST_CONTROL_RINGING = 3,                /*!< Remote end is ringing */
 265         AST_CONTROL_ANSWER = 4,                 /*!< Remote end has answered */
 266         AST_CONTROL_BUSY = 5,                   /*!< Remote end is busy */
 267         AST_CONTROL_TAKEOFFHOOK = 6,    /*!< Make it go off hook */
 268         AST_CONTROL_OFFHOOK = 7,                /*!< Line is off hook */
 269         AST_CONTROL_CONGESTION = 8,             /*!< Congestion (circuits busy) */
 270         AST_CONTROL_FLASH = 9,                  /*!< Flash hook */
 271         AST_CONTROL_WINK = 10,                  /*!< Wink */
 272         AST_CONTROL_OPTION = 11,                /*!< Set a low-level option */
 273         AST_CONTROL_RADIO_KEY = 12,             /*!< Key Radio */
 274         AST_CONTROL_RADIO_UNKEY = 13,   /*!< Un-Key Radio */
 275         AST_CONTROL_PROGRESS = 14,              /*!< Indicate PROGRESS */
 276         AST_CONTROL_PROCEEDING = 15,    /*!< Indicate CALL PROCEEDING */
 277         AST_CONTROL_HOLD = 16,                  /*!< Indicate call is placed on hold */
 278         AST_CONTROL_UNHOLD = 17,                /*!< Indicate call is left from hold */
 279         AST_CONTROL_VIDUPDATE = 18,             /*!< Indicate video frame update */
 280         _XXX_AST_CONTROL_T38 = 19,              /*!< T38 state change request/notification \deprecated This is no longer supported. Use AST_CONTROL_T38_PARAMETERS instead. */
 281         AST_CONTROL_SRCUPDATE = 20,             /*!< Indicate source of media has changed */
 282         AST_CONTROL_TRANSFER = 21,              /*!< Indicate status of a transfer request */
 283         AST_CONTROL_CONNECTED_LINE = 22,/*!< Indicate connected line has changed */
 284         AST_CONTROL_REDIRECTING = 23,   /*!< Indicate redirecting id has changed */
 285         AST_CONTROL_T38_PARAMETERS = 24,/*!< T38 state change request/notification with parameters */
 286         AST_CONTROL_CC = 25,                    /*!< Indication that Call completion service is possible */
 287         AST_CONTROL_SRCCHANGE = 26,             /*!< Media source has changed and requires a new RTP SSRC */
 288         AST_CONTROL_READ_ACTION = 27,   /*!< Tell ast_read to take a specific action */
 289         AST_CONTROL_AOC = 28,                   /*!< Advice of Charge with encoded generic AOC payload */
 290         AST_CONTROL_END_OF_Q = 29,              /*!< Indicate that this position was the end of the channel queue for a softhangup. */
 291         AST_CONTROL_INCOMPLETE = 30,    /*!< Indication that the extension dialed is incomplete */
 292         AST_CONTROL_MCID = 31,                  /*!< Indicate that the caller is being malicious. */
 293         AST_CONTROL_UPDATE_RTP_PEER = 32, /*!< Interrupt the bridge and have it update the peer */
 294         AST_CONTROL_PVT_CAUSE_CODE = 33, /*!< Contains an update to the protocol-specific cause-code stored for branching dials */
 295         AST_CONTROL_MASQUERADE_NOTIFY = 34,     /*!< A masquerade is about to begin/end. (Never sent as a frame but directly with ast_indicate_data().) */
 296
 297         /*
 298          * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
 299          *
 300          * IAX2 sends these values out over the wire.  To prevent future
 301          * incompatibilities, pick the next value in the enum from whatever
 302          * is on the current trunk.  If you lose the merge race you need to
 303          * fix the previous branches to match what is on trunk.  In addition
 304          * you need to change chan_iax2 to explicitly allow the control
 305          * frame over the wire if it makes sense for the frame to be passed
 306          * to another Asterisk instance.
 307          *
 308          * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
 309          */
 310
 311         /* Control frames used to manipulate a stream on a channel. The values for these
 312          * must be greater than the allowed value for a 8-bit char, so that they avoid
 313          * conflicts with DTMF values. */
 314         AST_CONTROL_STREAM_STOP = 1000,         /*!< Indicate to a channel in playback to stop the stream */
 315         AST_CONTROL_STREAM_SUSPEND = 1001,      /*!< Indicate to a channel in playback to suspend the stream */
 316         AST_CONTROL_STREAM_RESTART = 1002,      /*!< Indicate to a channel in playback to restart the stream */
 317         AST_CONTROL_STREAM_REVERSE = 1003,      /*!< Indicate to a channel in playback to rewind */
 318         AST_CONTROL_STREAM_FORWARD = 1004,      /*!< Indicate to a channel in playback to fast forward */
 319         /* Control frames to manipulate recording on a channel. */
 320         AST_CONTROL_RECORD_CANCEL = 1100,       /*!< Indicated to a channel in record to stop recording and discard the file */
 321         AST_CONTROL_RECORD_STOP = 1101, /*!< Indicated to a channel in record to stop recording */
 322         AST_CONTROL_RECORD_SUSPEND = 1102,      /*!< Indicated to a channel in record to suspend/unsuspend recording */
 323         AST_CONTROL_RECORD_MUTE = 1103, /*!< Indicated to a channel in record to mute/unmute (i.e. write silence) recording */
 324 };
 325
 326 enum ast_frame_read_action {
 327         AST_FRAME_READ_ACTION_CONNECTED_LINE_MACRO,
 328 };
 329
 330 struct ast_control_read_action_payload {
 331         /* An indicator to ast_read of what action to
 332          * take with the frame;
 333          */
 334         enum ast_frame_read_action action;
 335         /* The size of the frame's payload
 336          */
 337         size_t payload_size;
 338         /* A payload for the frame.
 339          */
 340         unsigned char payload[0];
 341 };
 342
 343 enum ast_control_t38 {
 344         AST_T38_REQUEST_NEGOTIATE = 1,  /*!< Request T38 on a channel (voice to fax) */
 345         AST_T38_REQUEST_TERMINATE,      /*!< Terminate T38 on a channel (fax to voice) */
 346         AST_T38_NEGOTIATED,             /*!< T38 negotiated (fax mode) */
 347         AST_T38_TERMINATED,             /*!< T38 terminated (back to voice) */
 348         AST_T38_REFUSED,                /*!< T38 refused for some reason (usually rejected by remote end) */
 349         AST_T38_REQUEST_PARMS,          /*!< request far end T.38 parameters for a channel in 'negotiating' state */
 350 };
 351
 352 enum ast_control_t38_rate {
 353         AST_T38_RATE_2400 = 1,
 354         AST_T38_RATE_4800,
 355         AST_T38_RATE_7200,
 356         AST_T38_RATE_9600,
 357         AST_T38_RATE_12000,
 358         /* Set to 0 so it's taken as default when unspecified.
 359          * See ITU-T T.38 Implementors' Guide (11 May 2012),
 360          * Table H.2: if the T38MaxBitRate attribute is omitted
 361          * it should use a default of 14400. */
 362         AST_T38_RATE_14400 = 0,
 363 };
 364
 365 enum ast_control_t38_rate_management {
 366         AST_T38_RATE_MANAGEMENT_TRANSFERRED_TCF = 0,
 367         AST_T38_RATE_MANAGEMENT_LOCAL_TCF,
 368 };
 369
 370 struct ast_control_t38_parameters {
 371         enum ast_control_t38 request_response;                  /*!< Request or response of the T38 control frame */
 372         unsigned int version;                                   /*!< Supported T.38 version */
 373         unsigned int max_ifp;                                   /*!< Maximum IFP size supported */
 374         enum ast_control_t38_rate rate;                         /*!< Maximum fax rate supported */
 375         enum ast_control_t38_rate_management rate_management;   /*!< Rate management setting */
 376         unsigned int fill_bit_removal:1;                        /*!< Set if fill bit removal can be used */
 377         unsigned int transcoding_mmr:1;                         /*!< Set if MMR transcoding can be used */
 378         unsigned int transcoding_jbig:1;                        /*!< Set if JBIG transcoding can be used */
 379 };
 380
 381 enum ast_control_transfer {
 382         AST_TRANSFER_SUCCESS = 0, /*!< Transfer request on the channel worked */
 383         AST_TRANSFER_FAILED,      /*!< Transfer request on the channel failed */
 384 };
 385
 386 struct ast_control_pvt_cause_code {
 387         char chan_name[AST_CHANNEL_NAME];       /*!< Name of the channel that originated the cause information */
 388         unsigned int emulate_sip_cause:1;       /*!< Indicates whether this should be used to emulate SIP_CAUSE support */
 389         int ast_cause;                          /*!< Asterisk cause code associated with this message */
 390         char code[1];                           /*!< Tech-specific cause code information, beginning with the name of the tech */
 391 };
 392
 393 /* Option identifiers and flags */
 394 #define AST_OPTION_FLAG_REQUEST         0
 395 #define AST_OPTION_FLAG_ACCEPT          1
 396 #define AST_OPTION_FLAG_REJECT          2
 397 #define AST_OPTION_FLAG_QUERY           4
 398 #define AST_OPTION_FLAG_ANSWER          5
 399 #define AST_OPTION_FLAG_WTF             6
 400
 401 /*! Verify touchtones by muting audio transmission
 402  * (and reception) and verify the tone is still present
 403  * Option data is a single signed char value 0 or 1 */
 404 #define AST_OPTION_TONE_VERIFY          1
 405
 406 /*! Put a compatible channel into TDD (TTY for the hearing-impared) mode
 407  * Option data is a single signed char value 0 or 1 */
 408 #define AST_OPTION_TDD                  2
 409
 410 /*! Relax the parameters for DTMF reception (mainly for radio use)
 411  * Option data is a single signed char value 0 or 1 */
 412 #define AST_OPTION_RELAXDTMF            3
 413
 414 /*! Set (or clear) Audio (Not-Clear) Mode
 415  * Option data is a single signed char value 0 or 1 */
 416 #define AST_OPTION_AUDIO_MODE           4
 417
 418 /*! Set channel transmit gain
 419  * Option data is a single signed char representing number of decibels (dB)
 420  * to set gain to (on top of any gain specified in channel driver) */
 421 #define AST_OPTION_TXGAIN               5
 422
 423 /*! Set channel receive gain
 424  * Option data is a single signed char representing number of decibels (dB)
 425  * to set gain to (on top of any gain specified in channel driver) */
 426 #define AST_OPTION_RXGAIN               6
 427
 428 /* set channel into "Operator Services" mode
 429  * Option data is a struct oprmode
 430  *
 431  * \note This option should never be sent over the network */
 432 #define AST_OPTION_OPRMODE              7
 433
 434 /*! Explicitly enable or disable echo cancelation for the given channel
 435  * Option data is a single signed char value 0 or 1
 436  *
 437  * \note This option appears to be unused in the code. It is handled, but never
 438  * set or queried. */
 439 #define AST_OPTION_ECHOCAN              8
 440
 441 /*! \brief Handle channel write data
 442  * If a channel needs to process the data from a func_channel write operation
 443  * after func_channel_write executes, it can define the setoption callback
 444  * and process this option. A pointer to an ast_chan_write_info_t will be passed.
 445  *
 446  * \note This option should never be passed over the network. */
 447 #define AST_OPTION_CHANNEL_WRITE 9
 448
 449 /* !
 450  * Read-only. Allows query current status of T38 on the channel.
 451  * data: ast_t38state
 452  */
 453 #define AST_OPTION_T38_STATE            10
 454
 455 /*! Request that the channel driver deliver frames in a specific format
 456  * Option data is a format_t */
 457 #define AST_OPTION_FORMAT_READ          11
 458
 459 /*! Request that the channel driver be prepared to accept frames in a specific format
 460  * Option data is a format_t */
 461 #define AST_OPTION_FORMAT_WRITE         12
 462
 463 /*! Request that the channel driver make two channels of the same tech type compatible if possible
 464  * Option data is an ast_channel
 465  *
 466  * \note This option should never be passed over the network */
 467 #define AST_OPTION_MAKE_COMPATIBLE      13
 468
 469 /*! Get or set the digit detection state of the channel
 470  * Option data is a single signed char value 0 or 1 */
 471 #define AST_OPTION_DIGIT_DETECT         14
 472
 473 /*! Get or set the fax tone detection state of the channel
 474  * Option data is a single signed char value 0 or 1 */
 475 #define AST_OPTION_FAX_DETECT           15
 476
 477 /*! Get the device name from the channel (Read only)
 478  * Option data is a character buffer of suitable length */
 479 #define AST_OPTION_DEVICE_NAME          16
 480
 481 /*! Get the CC agent type from the channel (Read only)
 482  * Option data is a character buffer of suitable length */
 483 #define AST_OPTION_CC_AGENT_TYPE    17
 484
 485 /*! Get or set the security options on a channel
 486  * Option data is an integer value of 0 or 1 */
 487 #define AST_OPTION_SECURE_SIGNALING        18
 488 #define AST_OPTION_SECURE_MEDIA            19
 489
 490 struct oprmode {
 491         struct ast_channel *peer;
 492         int mode;
 493 } ;
 494
 495 struct ast_option_header {
 496         /* Always keep in network byte order */
 497 #if __BYTE_ORDER == __BIG_ENDIAN
 498         uint16_t flag:3;
 499         uint16_t option:13;
 500 #else
 501 #if __BYTE_ORDER == __LITTLE_ENDIAN
 502         uint16_t option:13;
 503         uint16_t flag:3;
 504 #else
 505 #error Byte order not defined
 506 #endif
 507 #endif
 508                 uint8_t data[0];
 509 };
 510
 511 /*! \brief  Requests a frame to be allocated
 512  *
 513  * \param source
 514  * Request a frame be allocated.  source is an optional source of the frame,
 515  * len is the requested length, or "0" if the caller will supply the buffer
 516  */
 517 #if 0 /* Unimplemented */
 518 struct ast_frame *ast_fralloc(char *source, int len);
 519 #endif
 520
 521 /*!
 522  * \brief Frees a frame or list of frames
 523  *
 524  * \param fr Frame to free, or head of list to free
 525  * \param cache Whether to consider this frame for frame caching
 526  */
 527 void ast_frame_free(struct ast_frame *fr, int cache);
 528
 529 #define ast_frfree(fr) ast_frame_free(fr, 1)
 530
 531 /*!
 532  * \brief NULL-safe wrapper for \ref ast_frfree, good for \ref RAII_VAR.
 533  * \param frame Frame to free, or head of list to free.
 534  */
 535 void ast_frame_dtor(struct ast_frame *frame);
 536
 537 /*! \brief Makes a frame independent of any static storage
 538  * \param fr frame to act upon
 539  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
 540  * and if the data hasn't been malloced then make the
 541  * data malloc'd.  If you need to store frames, say for queueing, then
 542  * you should call this function.
 543  * \return Returns a frame on success, NULL on error
 544  * \note This function may modify the frame passed to it, so you must
 545  * not assume the frame will be intact after the isolated frame has
 546  * been produced. In other words, calling this function on a frame
 547  * should be the last operation you do with that frame before freeing
 548  * it (or exiting the block, if the frame is on the stack.)
 549  */
 550 struct ast_frame *ast_frisolate(struct ast_frame *fr);
 551
 552 /*! \brief Copies a frame
 553  * \param fr frame to copy
 554  * Duplicates a frame -- should only rarely be used, typically frisolate is good enough
 555  * \return Returns a frame on success, NULL on error
 556  */
 557 struct ast_frame *ast_frdup(const struct ast_frame *fr);
 558
 559 void ast_swapcopy_samples(void *dst, const void *src, int samples);
 560
 561 /* Helpers for byteswapping native samples to/from
 562    little-endian and big-endian. */
 563 #if __BYTE_ORDER == __LITTLE_ENDIAN
 564 #define ast_frame_byteswap_le(fr) do { ; } while(0)
 565 #define ast_frame_byteswap_be(fr) do { struct ast_frame *__f = (fr); ast_swapcopy_samples(__f->data.ptr, __f->data.ptr, __f->samples); } while(0)
 566 #else
 567 #define ast_frame_byteswap_le(fr) do { struct ast_frame *__f = (fr); ast_swapcopy_samples(__f->data.ptr, __f->data.ptr, __f->samples); } while(0)
 568 #define ast_frame_byteswap_be(fr) do { ; } while(0)
 569 #endif
 570
 571 void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix);
 572
 573 /*! \brief Appends a frame to the end of a list of frames, truncating the maximum length of the list */
 574 struct ast_frame *ast_frame_enqueue(struct ast_frame *head, struct ast_frame *f, int maxlen, int dupe);
 575
 576 /*!
 577   \brief Adjusts the volume of the audio samples contained in a frame.
 578   \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
 579   \param adjustment The number of dB to adjust up or down.
 580   \return 0 for success, non-zero for an error
 581  */
 582 int ast_frame_adjust_volume(struct ast_frame *f, int adjustment);
 583
 584 /*!
 585   \brief Sums two frames of audio samples.
 586   \param f1 The first frame (which will contain the result)
 587   \param f2 The second frame
 588   \return 0 for success, non-zero for an error
 589
 590   The frames must be AST_FRAME_VOICE and must contain AST_FORMAT_SLINEAR samples,
 591   and must contain the same number of samples.
 592  */
 593 int ast_frame_slinear_sum(struct ast_frame *f1, struct ast_frame *f2);
 594
 595 /*!
 596  * \brief Clear all audio samples from an ast_frame. The frame must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR
 597  */
 598 int ast_frame_clear(struct ast_frame *frame);
 599
 600 /*!
 601  * \brief Copy the discription of a frame's subclass into the provided string
 602  *
 603  * \param f The frame to get the information from
 604  * \param subclass Buffer to fill with subclass information
 605  * \param slen Length of subclass buffer
 606  * \param moreinfo Buffer to fill with additional information
 607  * \param mlen Length of moreinfo buffer
 608  * \since 11
 609  */
 610 void ast_frame_subclass2str(struct ast_frame *f, char *subclass, size_t slen, char *moreinfo, size_t mlen);
 611
 612 /*!
 613  * \brief Copy the discription of a frame type into the provided string
 614  *
 615  * \param frame_type The frame type to be described
 616  * \param ftype Buffer to fill with frame type description
 617  * \param len Length of subclass buffer
 618  * \since 11
 619  */
 620 void ast_frame_type2str(enum ast_frame_type frame_type, char *ftype, size_t len);
 621
 622 #if defined(__cplusplus) || defined(c_plusplus)
 623 }
 624 #endif
 625
 626 #endif /* _ASTERISK_FRAME_H */