include/asterisk/frame.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Asterisk internal frame definitions.
00021  * \arg For an explanation of frames, see \ref Def_Frame
00022  * \arg Frames are send of Asterisk channels, see \ref Def_Channel
00023  */
00024 
00025 #ifndef _ASTERISK_FRAME_H
00026 #define _ASTERISK_FRAME_H
00027 
00028 #if defined(__cplusplus) || defined(c_plusplus)
00029 extern "C" {
00030 #endif
00031 
00032 #include <sys/time.h>
00033 
00034 #include "asterisk/format.h"
00035 #include "asterisk/endian.h"
00036 #include "asterisk/linkedlists.h"
00037 
00038 /*!
00039  * \page Def_Frame AST Multimedia and signalling frames
00040  * \section Def_AstFrame What is an ast_frame ?
00041  * A frame of data read used to communicate between
00042  * between channels and applications.
00043  * Frames are divided into frame types and subclasses.
00044  *
00045  * \par Frame types
00046  * \arg \b VOICE:  Voice data, subclass is codec (AST_FORMAT_*)
00047  * \arg \b VIDEO:  Video data, subclass is codec (AST_FORMAT_*)
00048  * \arg \b DTMF:   A DTMF digit, subclass is the digit
00049  * \arg \b IMAGE:  Image transport, mostly used in IAX
00050  * \arg \b TEXT:   Text messages and character by character (real time text)
00051  * \arg \b HTML:   URL's and web pages
00052  * \arg \b MODEM:  Modulated data encodings, such as T.38 and V.150
00053  * \arg \b IAX:    Private frame type for the IAX protocol
00054  * \arg \b CNG:    Comfort noice frames
00055  * \arg \b CONTROL:A control frame, subclass defined as AST_CONTROL_
00056  * \arg \b NULL:   Empty, useless frame
00057  *
00058  * \par Files
00059  * \arg frame.h    Definitions
00060  * \arg frame.c    Function library
00061  * \arg \ref Def_Channel Asterisk channels
00062  * \section Def_ControlFrame Control Frames
00063  * Control frames send signalling information between channels
00064  * and devices. They are prefixed with AST_CONTROL_, like AST_CONTROL_FRAME_HANGUP
00065  * \arg \b HANGUP          The other end has hungup
00066  * \arg \b RING            Local ring
00067  * \arg \b RINGING         The other end is ringing
00068  * \arg \b ANSWER          The other end has answered
00069  * \arg \b BUSY            Remote end is busy
00070  * \arg \b TAKEOFFHOOK     Make it go off hook (what's "it" ? )
00071  * \arg \b OFFHOOK         Line is off hook
00072  * \arg \b CONGESTION      Congestion (circuit is busy, not available)
00073  * \arg \b FLASH           Other end sends flash hook
00074  * \arg \b WINK            Other end sends wink
00075  * \arg \b OPTION          Send low-level option
00076  * \arg \b RADIO_KEY       Key radio (see app_rpt.c)
00077  * \arg \b RADIO_UNKEY     Un-key radio (see app_rpt.c)
00078  * \arg \b PROGRESS        Other end indicates call progress
00079  * \arg \b PROCEEDING      Indicates proceeding
00080  * \arg \b HOLD            Call is placed on hold
00081  * \arg \b UNHOLD          Call is back from hold
00082  * \arg \b VIDUPDATE       Video update requested
00083  * \arg \b SRCUPDATE       The source of media has changed (RTP marker bit must change)
00084  * \arg \b SRCCHANGE       Media source has changed (RTP marker bit and SSRC must change)
00085  * \arg \b CONNECTED_LINE  Connected line has changed
00086  * \arg \b REDIRECTING     Call redirecting information has changed.
00087  */
00088 
00089 /*!
00090  * \brief Frame types
00091  *
00092  * \note It is important that the values of each frame type are never changed,
00093  *       because it will break backwards compatability with older versions.
00094  *       This is because these constants are transmitted directly over IAX2.
00095  */
00096 enum ast_frame_type {
00097    /*! DTMF end event, subclass is the digit */
00098    AST_FRAME_DTMF_END = 1,
00099    /*! Voice data, subclass is AST_FORMAT_* */
00100    AST_FRAME_VOICE,
00101    /*! Video frame, maybe?? :) */
00102    AST_FRAME_VIDEO,
00103    /*! A control frame, subclass is AST_CONTROL_* */
00104    AST_FRAME_CONTROL,
00105    /*! An empty, useless frame */
00106    AST_FRAME_NULL,
00107    /*! Inter Asterisk Exchange private frame type */
00108    AST_FRAME_IAX,
00109    /*! Text messages */
00110    AST_FRAME_TEXT,
00111    /*! Image Frames */
00112    AST_FRAME_IMAGE,
00113    /*! HTML Frame */
00114    AST_FRAME_HTML,
00115    /*! Comfort Noise frame (subclass is level of CNG in -dBov),
00116        body may include zero or more 8-bit quantization coefficients */
00117    AST_FRAME_CNG,
00118    /*! Modem-over-IP data streams */
00119    AST_FRAME_MODEM,
00120    /*! DTMF begin event, subclass is the digit */
00121    AST_FRAME_DTMF_BEGIN,
00122    /*! Internal bridge module action. */
00123    AST_FRAME_BRIDGE_ACTION,
00124    /*! Internal synchronous bridge module action.
00125     * Synchronous bridge actions may be queued onto bridge
00126     * channels, but they absolutely must not ever be written
00127     * directly into bridges.
00128     */
00129    AST_FRAME_BRIDGE_ACTION_SYNC,
00130 };
00131 #define AST_FRAME_DTMF AST_FRAME_DTMF_END
00132 
00133 enum {
00134    /*! This frame contains valid timing information */
00135    AST_FRFLAG_HAS_TIMING_INFO = (1 << 0),
00136 };
00137 
00138 struct ast_frame_subclass {
00139    /*! A frame specific code */
00140    int integer;
00141    /*! The asterisk media format */
00142    struct ast_format *format;
00143    /*! For video formats, an indication that a frame ended */
00144    unsigned int frame_ending;
00145 };
00146 
00147 /*! \brief Data structure associated with a single frame of data
00148  */
00149 struct ast_frame {
00150    /*! Kind of frame */
00151    enum ast_frame_type frametype;
00152    /*! Subclass, frame dependent */
00153    struct ast_frame_subclass subclass;
00154    /*! Length of data */
00155    int datalen;
00156    /*! Number of samples in this frame */
00157    int samples;
00158    /*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
00159    int mallocd;
00160    /*! The number of bytes allocated for a malloc'd frame header */
00161    size_t mallocd_hdr_len;
00162    /*! How many bytes exist _before_ "data" that can be used if needed */
00163    int offset;
00164    /*! Optional source of frame for debugging */
00165    const char *src;
00166    /*! Pointer to actual data */
00167    union { void *ptr; uint32_t uint32; char pad[8]; } data;
00168    /*! Global delivery time */
00169    struct timeval delivery;
00170    /*! For placing in a linked list */
00171    AST_LIST_ENTRY(ast_frame) frame_list;
00172    /*! Misc. frame flags */
00173    unsigned int flags;
00174    /*! Timestamp in milliseconds */
00175    long ts;
00176    /*! Length in milliseconds */
00177    long len;
00178    /*! Sequence number */
00179    int seqno;
00180 };
00181 
00182 /*!
00183  * Set the various field of a frame to point to a buffer.
00184  * Typically you set the base address of the buffer, the offset as
00185  * AST_FRIENDLY_OFFSET, and the datalen as the amount of bytes queued.
00186  * The remaining things (to be done manually) is set the number of
00187  * samples, which cannot be derived from the datalen unless you know
00188  * the number of bits per sample.
00189  */
00190 #define  AST_FRAME_SET_BUFFER(fr, _base, _ofs, _datalen) \
00191    {              \
00192    (fr)->data.ptr = (char *)_base + (_ofs);  \
00193    (fr)->offset = (_ofs);        \
00194    (fr)->datalen = (_datalen);      \
00195    }
00196 
00197 /*! Queueing a null frame is fairly common, so we declare a global null frame object
00198     for this purpose instead of having to declare one on the stack */
00199 extern struct ast_frame ast_null_frame;
00200 
00201 /*! \brief Offset into a frame's data buffer.
00202  *
00203  * By providing some "empty" space prior to the actual data of an ast_frame,
00204  * this gives any consumer of the frame ample space to prepend other necessary
00205  * information without having to create a new buffer.
00206  *
00207  * As an example, RTP can use the data from an ast_frame and simply prepend the
00208  * RTP header information into the space provided by AST_FRIENDLY_OFFSET instead
00209  * of having to create a new buffer with the necessary space allocated.
00210  */
00211 #define AST_FRIENDLY_OFFSET   64
00212 #define AST_MIN_OFFSET     32 /*! Make sure we keep at least this much handy */
00213 
00214 /*! Need the header be free'd? */
00215 #define AST_MALLOCD_HDR    (1 << 0)
00216 /*! Need the data be free'd? */
00217 #define AST_MALLOCD_DATA   (1 << 1)
00218 /*! Need the source be free'd? (haha!) */
00219 #define AST_MALLOCD_SRC    (1 << 2)
00220 
00221 /* MODEM subclasses */
00222 /*! T.38 Fax-over-IP */
00223 #define AST_MODEM_T38      1
00224 /*! V.150 Modem-over-IP */
00225 #define AST_MODEM_V150     2
00226 
00227 /* HTML subclasses */
00228 /*! Sending a URL */
00229 #define AST_HTML_URL    1
00230 /*! Data frame */
00231 #define AST_HTML_DATA      2
00232 /*! Beginning frame */
00233 #define AST_HTML_BEGIN     4
00234 /*! End frame */
00235 #define AST_HTML_END    8
00236 /*! Load is complete */
00237 #define AST_HTML_LDCOMPLETE   16
00238 /*! Peer is unable to support HTML */
00239 #define AST_HTML_NOSUPPORT 17
00240 /*! Send URL, and track */
00241 #define AST_HTML_LINKURL   18
00242 /*! No more HTML linkage */
00243 #define AST_HTML_UNLINK    19
00244 /*! Reject link request */
00245 #define AST_HTML_LINKREJECT   20
00246 
00247 /*!
00248  * \brief Internal control frame subtype field values.
00249  *
00250  * \warning
00251  * IAX2 sends these values out over the wire.  To prevent future
00252  * incompatibilities, pick the next value in the enum from whatever
00253  * is on the current trunk.  If you lose the merge race you need to
00254  * fix the previous branches to match what is on trunk.  In addition
00255  * you need to change chan_iax2 to explicitly allow the control
00256  * frame over the wire if it makes sense for the frame to be passed
00257  * to another Asterisk instance.
00258  */
00259 enum ast_control_frame_type {
00260    AST_CONTROL_HANGUP = 1,       /*!< Other end has hungup */
00261    AST_CONTROL_RING = 2,         /*!< Local ring */
00262    AST_CONTROL_RINGING = 3,      /*!< Remote end is ringing */
00263    AST_CONTROL_ANSWER = 4,       /*!< Remote end has answered */
00264    AST_CONTROL_BUSY = 5,         /*!< Remote end is busy */
00265    AST_CONTROL_TAKEOFFHOOK = 6,  /*!< Make it go off hook */
00266    AST_CONTROL_OFFHOOK = 7,      /*!< Line is off hook */
00267    AST_CONTROL_CONGESTION = 8,      /*!< Congestion (circuits busy) */
00268    AST_CONTROL_FLASH = 9,        /*!< Flash hook */
00269    AST_CONTROL_WINK = 10,        /*!< Wink */
00270    AST_CONTROL_OPTION = 11,      /*!< Set a low-level option */
00271    AST_CONTROL_RADIO_KEY = 12,      /*!< Key Radio */
00272    AST_CONTROL_RADIO_UNKEY = 13, /*!< Un-Key Radio */
00273    AST_CONTROL_PROGRESS = 14,    /*!< Indicate PROGRESS */
00274    AST_CONTROL_PROCEEDING = 15,  /*!< Indicate CALL PROCEEDING */
00275    AST_CONTROL_HOLD = 16,        /*!< Indicate call is placed on hold */
00276    AST_CONTROL_UNHOLD = 17,      /*!< Indicate call is left from hold */
00277    AST_CONTROL_VIDUPDATE = 18,      /*!< Indicate video frame update */
00278    _XXX_AST_CONTROL_T38 = 19,    /*!< T38 state change request/notification \deprecated This is no longer supported. Use AST_CONTROL_T38_PARAMETERS instead. */
00279    AST_CONTROL_SRCUPDATE = 20,      /*!< Indicate source of media has changed */
00280    AST_CONTROL_TRANSFER = 21,    /*!< Indicate status of a transfer request */
00281    AST_CONTROL_CONNECTED_LINE = 22,/*!< Indicate connected line has changed */
00282    AST_CONTROL_REDIRECTING = 23, /*!< Indicate redirecting id has changed */
00283    AST_CONTROL_T38_PARAMETERS = 24,/*!< T38 state change request/notification with parameters */
00284    AST_CONTROL_CC = 25,       /*!< Indication that Call completion service is possible */
00285    AST_CONTROL_SRCCHANGE = 26,      /*!< Media source has changed and requires a new RTP SSRC */
00286    AST_CONTROL_READ_ACTION = 27, /*!< Tell ast_read to take a specific action */
00287    AST_CONTROL_AOC = 28,         /*!< Advice of Charge with encoded generic AOC payload */
00288    AST_CONTROL_END_OF_Q = 29,    /*!< Indicate that this position was the end of the channel queue for a softhangup. */
00289    AST_CONTROL_INCOMPLETE = 30,  /*!< Indication that the extension dialed is incomplete */
00290    AST_CONTROL_MCID = 31,        /*!< Indicate that the caller is being malicious. */
00291    AST_CONTROL_UPDATE_RTP_PEER = 32, /*!< Interrupt the bridge and have it update the peer */
00292    AST_CONTROL_PVT_CAUSE_CODE = 33, /*!< Contains an update to the protocol-specific cause-code stored for branching dials */
00293    AST_CONTROL_MASQUERADE_NOTIFY = 34, /*!< A masquerade is about to begin/end. (Never sent as a frame but directly with ast_indicate_data().) */
00294 
00295    /*
00296     * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00297     *
00298     * IAX2 sends these values out over the wire.  To prevent future
00299     * incompatibilities, pick the next value in the enum from whatever
00300     * is on the current trunk.  If you lose the merge race you need to
00301     * fix the previous branches to match what is on trunk.  In addition
00302     * you need to change chan_iax2 to explicitly allow the control
00303     * frame over the wire if it makes sense for the frame to be passed
00304     * to another Asterisk instance.
00305     *
00306     * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00307     */
00308 
00309    /* Control frames used to manipulate a stream on a channel. The values for these
00310     * must be greater than the allowed value for a 8-bit char, so that they avoid
00311     * conflicts with DTMF values. */
00312    AST_CONTROL_STREAM_STOP = 1000,     /*!< Indicate to a channel in playback to stop the stream */
00313    AST_CONTROL_STREAM_SUSPEND = 1001,  /*!< Indicate to a channel in playback to suspend the stream */
00314    AST_CONTROL_STREAM_RESTART = 1002,  /*!< Indicate to a channel in playback to restart the stream */
00315    AST_CONTROL_STREAM_REVERSE = 1003,  /*!< Indicate to a channel in playback to rewind */
00316    AST_CONTROL_STREAM_FORWARD = 1004,  /*!< Indicate to a channel in playback to fast forward */
00317    /* Control frames to manipulate recording on a channel. */
00318    AST_CONTROL_RECORD_CANCEL = 1100,   /*!< Indicated to a channel in record to stop recording and discard the file */
00319    AST_CONTROL_RECORD_STOP = 1101,  /*!< Indicated to a channel in record to stop recording */
00320    AST_CONTROL_RECORD_SUSPEND = 1102,  /*!< Indicated to a channel in record to suspend/unsuspend recording */
00321    AST_CONTROL_RECORD_MUTE = 1103,  /*!< Indicated to a channel in record to mute/unmute (i.e. write silence) recording */
00322 };
00323 
00324 enum ast_frame_read_action {
00325    AST_FRAME_READ_ACTION_CONNECTED_LINE_MACRO,
00326 };
00327 
00328 struct ast_control_read_action_payload {
00329    /* An indicator to ast_read of what action to
00330     * take with the frame;
00331     */
00332    enum ast_frame_read_action action;
00333    /* The size of the frame's payload
00334     */
00335    size_t payload_size;
00336    /* A payload for the frame.
00337     */
00338    unsigned char payload[0];
00339 };
00340 
00341 enum ast_control_t38 {
00342    AST_T38_REQUEST_NEGOTIATE = 1,   /*!< Request T38 on a channel (voice to fax) */
00343    AST_T38_REQUEST_TERMINATE, /*!< Terminate T38 on a channel (fax to voice) */
00344    AST_T38_NEGOTIATED,     /*!< T38 negotiated (fax mode) */
00345    AST_T38_TERMINATED,     /*!< T38 terminated (back to voice) */
00346    AST_T38_REFUSED,     /*!< T38 refused for some reason (usually rejected by remote end) */
00347    AST_T38_REQUEST_PARMS,     /*!< request far end T.38 parameters for a channel in 'negotiating' state */
00348 };
00349 
00350 enum ast_control_t38_rate {
00351    AST_T38_RATE_2400 = 1,
00352    AST_T38_RATE_4800,
00353    AST_T38_RATE_7200,
00354    AST_T38_RATE_9600,
00355    AST_T38_RATE_12000,
00356    /* Set to 0 so it's taken as default when unspecified.
00357     * See ITU-T T.38 Implementors' Guide (11 May 2012),
00358     * Table H.2: if the T38MaxBitRate attribute is omitted
00359     * it should use a default of 14400. */
00360    AST_T38_RATE_14400 = 0,
00361 };
00362 
00363 enum ast_control_t38_rate_management {
00364    AST_T38_RATE_MANAGEMENT_TRANSFERRED_TCF = 0,
00365    AST_T38_RATE_MANAGEMENT_LOCAL_TCF,
00366 };
00367 
00368 struct ast_control_t38_parameters {
00369    enum ast_control_t38 request_response;       /*!< Request or response of the T38 control frame */
00370    unsigned int version;               /*!< Supported T.38 version */
00371    unsigned int max_ifp;               /*!< Maximum IFP size supported */
00372    enum ast_control_t38_rate rate;           /*!< Maximum fax rate supported */
00373    enum ast_control_t38_rate_management rate_management; /*!< Rate management setting */
00374    unsigned int fill_bit_removal:1;       /*!< Set if fill bit removal can be used */
00375    unsigned int transcoding_mmr:1;           /*!< Set if MMR transcoding can be used */
00376    unsigned int transcoding_jbig:1;       /*!< Set if JBIG transcoding can be used */
00377 };
00378 
00379 enum ast_control_transfer {
00380    AST_TRANSFER_SUCCESS = 0, /*!< Transfer request on the channel worked */
00381    AST_TRANSFER_FAILED,      /*!< Transfer request on the channel failed */
00382 };
00383 
00384 struct ast_control_pvt_cause_code {
00385    char chan_name[AST_CHANNEL_NAME];   /*!< Name of the channel that originated the cause information */
00386    unsigned int emulate_sip_cause:1;   /*!< Indicates whether this should be used to emulate SIP_CAUSE support */
00387    int ast_cause;          /*!< Asterisk cause code associated with this message */
00388    char code[1];           /*!< Tech-specific cause code information, beginning with the name of the tech */
00389 };
00390 
00391 /* Option identifiers and flags */
00392 #define AST_OPTION_FLAG_REQUEST     0
00393 #define AST_OPTION_FLAG_ACCEPT      1
00394 #define AST_OPTION_FLAG_REJECT      2
00395 #define AST_OPTION_FLAG_QUERY    4
00396 #define AST_OPTION_FLAG_ANSWER      5
00397 #define AST_OPTION_FLAG_WTF      6
00398 
00399 /*! Verify touchtones by muting audio transmission
00400  * (and reception) and verify the tone is still present
00401  * Option data is a single signed char value 0 or 1 */
00402 #define AST_OPTION_TONE_VERIFY      1
00403 
00404 /*! Put a compatible channel into TDD (TTY for the hearing-impared) mode
00405  * Option data is a single signed char value 0 or 1 */
00406 #define  AST_OPTION_TDD       2
00407 
00408 /*! Relax the parameters for DTMF reception (mainly for radio use)
00409  * Option data is a single signed char value 0 or 1 */
00410 #define  AST_OPTION_RELAXDTMF    3
00411 
00412 /*! Set (or clear) Audio (Not-Clear) Mode
00413  * Option data is a single signed char value 0 or 1 */
00414 #define  AST_OPTION_AUDIO_MODE      4
00415 
00416 /*! Set channel transmit gain
00417  * Option data is a single signed char representing number of decibels (dB)
00418  * to set gain to (on top of any gain specified in channel driver) */
00419 #define AST_OPTION_TXGAIN     5
00420 
00421 /*! Set channel receive gain
00422  * Option data is a single signed char representing number of decibels (dB)
00423  * to set gain to (on top of any gain specified in channel driver) */
00424 #define AST_OPTION_RXGAIN     6
00425 
00426 /* set channel into "Operator Services" mode
00427  * Option data is a struct oprmode
00428  *
00429  * \note This option should never be sent over the network */
00430 #define  AST_OPTION_OPRMODE      7
00431 
00432 /*! Explicitly enable or disable echo cancelation for the given channel
00433  * Option data is a single signed char value 0 or 1
00434  *
00435  * \note This option appears to be unused in the code. It is handled, but never
00436  * set or queried. */
00437 #define  AST_OPTION_ECHOCAN      8
00438 
00439 /*! \brief Handle channel write data
00440  * If a channel needs to process the data from a func_channel write operation
00441  * after func_channel_write executes, it can define the setoption callback
00442  * and process this option. A pointer to an ast_chan_write_info_t will be passed.
00443  *
00444  * \note This option should never be passed over the network. */
00445 #define AST_OPTION_CHANNEL_WRITE 9
00446 
00447 /* !
00448  * Read-only. Allows query current status of T38 on the channel.
00449  * data: ast_t38state
00450  */
00451 #define AST_OPTION_T38_STATE     10
00452 
00453 /*! Request that the channel driver deliver frames in a specific format
00454  * Option data is a format_t */
00455 #define AST_OPTION_FORMAT_READ          11
00456 
00457 /*! Request that the channel driver be prepared to accept frames in a specific format
00458  * Option data is a format_t */
00459 #define AST_OPTION_FORMAT_WRITE         12
00460 
00461 /*! Request that the channel driver make two channels of the same tech type compatible if possible
00462  * Option data is an ast_channel
00463  *
00464  * \note This option should never be passed over the network */
00465 #define AST_OPTION_MAKE_COMPATIBLE      13
00466 
00467 /*! Get or set the digit detection state of the channel
00468  * Option data is a single signed char value 0 or 1 */
00469 #define AST_OPTION_DIGIT_DETECT     14
00470 
00471 /*! Get or set the fax tone detection state of the channel
00472  * Option data is a single signed char value 0 or 1 */
00473 #define AST_OPTION_FAX_DETECT    15
00474 
00475 /*! Get the device name from the channel (Read only)
00476  * Option data is a character buffer of suitable length */
00477 #define AST_OPTION_DEVICE_NAME      16
00478 
00479 /*! Get the CC agent type from the channel (Read only)
00480  * Option data is a character buffer of suitable length */
00481 #define AST_OPTION_CC_AGENT_TYPE    17
00482 
00483 /*! Get or set the security options on a channel
00484  * Option data is an integer value of 0 or 1 */
00485 #define AST_OPTION_SECURE_SIGNALING        18
00486 #define AST_OPTION_SECURE_MEDIA            19
00487 
00488 struct oprmode {
00489    struct ast_channel *peer;
00490    int mode;
00491 } ;
00492 
00493 struct ast_option_header {
00494    /* Always keep in network byte order */
00495 #if __BYTE_ORDER == __BIG_ENDIAN
00496    uint16_t flag:3;
00497    uint16_t option:13;
00498 #else
00499 #if __BYTE_ORDER == __LITTLE_ENDIAN
00500    uint16_t option:13;
00501    uint16_t flag:3;
00502 #else
00503 #error Byte order not defined
00504 #endif
00505 #endif
00506       uint8_t data[0];
00507 };
00508 
00509 /*! \brief  Requests a frame to be allocated
00510  *
00511  * \param source
00512  * Request a frame be allocated.  source is an optional source of the frame,
00513  * len is the requested length, or "0" if the caller will supply the buffer
00514  */
00515 #if 0 /* Unimplemented */
00516 struct ast_frame *ast_fralloc(char *source, int len);
00517 #endif
00518 
00519 /*!
00520  * \brief Frees a frame or list of frames
00521  *
00522  * \param fr Frame to free, or head of list to free
00523  * \param cache Whether to consider this frame for frame caching
00524  */
00525 void ast_frame_free(struct ast_frame *fr, int cache);
00526 
00527 #define ast_frfree(fr) ast_frame_free(fr, 1)
00528 
00529 /*!
00530  * \brief NULL-safe wrapper for \ref ast_frfree, good for \ref RAII_VAR.
00531  * \param frame Frame to free, or head of list to free.
00532  */
00533 void ast_frame_dtor(struct ast_frame *frame);
00534 
00535 /*! \brief Makes a frame independent of any static storage
00536  * \param fr frame to act upon
00537  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
00538  * and if the data hasn't been malloced then make the
00539  * data malloc'd.  If you need to store frames, say for queueing, then
00540  * you should call this function.
00541  * \return Returns a frame on success, NULL on error
00542  * \note This function may modify the frame passed to it, so you must
00543  * not assume the frame will be intact after the isolated frame has
00544  * been produced. In other words, calling this function on a frame
00545  * should be the last operation you do with that frame before freeing
00546  * it (or exiting the block, if the frame is on the stack.)
00547  */
00548 struct ast_frame *ast_frisolate(struct ast_frame *fr);
00549 
00550 /*! \brief Copies a frame
00551  * \param fr frame to copy
00552  * Duplicates a frame -- should only rarely be used, typically frisolate is good enough
00553  * \return Returns a frame on success, NULL on error
00554  */
00555 struct ast_frame *ast_frdup(const struct ast_frame *fr);
00556 
00557 void ast_swapcopy_samples(void *dst, const void *src, int samples);
00558 
00559 /* Helpers for byteswapping native samples to/from
00560    little-endian and big-endian. */
00561 #if __BYTE_ORDER == __LITTLE_ENDIAN
00562 #define ast_frame_byteswap_le(fr) do { ; } while(0)
00563 #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)
00564 #else
00565 #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)
00566 #define ast_frame_byteswap_be(fr) do { ; } while(0)
00567 #endif
00568 
00569 void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix);
00570 
00571 /*! \brief Appends a frame to the end of a list of frames, truncating the maximum length of the list */
00572 struct ast_frame *ast_frame_enqueue(struct ast_frame *head, struct ast_frame *f, int maxlen, int dupe);
00573 
00574 /*!
00575   \brief Adjusts the volume of the audio samples contained in a frame.
00576   \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
00577   \param adjustment The number of dB to adjust up or down.
00578   \return 0 for success, non-zero for an error
00579  */
00580 int ast_frame_adjust_volume(struct ast_frame *f, int adjustment);
00581 
00582 /*!
00583   \brief Sums two frames of audio samples.
00584   \param f1 The first frame (which will contain the result)
00585   \param f2 The second frame
00586   \return 0 for success, non-zero for an error
00587 
00588   The frames must be AST_FRAME_VOICE and must contain AST_FORMAT_SLINEAR samples,
00589   and must contain the same number of samples.
00590  */
00591 int ast_frame_slinear_sum(struct ast_frame *f1, struct ast_frame *f2);
00592 
00593 /*!
00594  * \brief Clear all audio samples from an ast_frame. The frame must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR
00595  */
00596 int ast_frame_clear(struct ast_frame *frame);
00597 
00598 /*!
00599  * \brief Copy the discription of a frame's subclass into the provided string
00600  *
00601  * \param f The frame to get the information from
00602  * \param subclass Buffer to fill with subclass information
00603  * \param slen Length of subclass buffer
00604  * \param moreinfo Buffer to fill with additional information
00605  * \param mlen Length of moreinfo buffer
00606  * \since 11
00607  */
00608 void ast_frame_subclass2str(struct ast_frame *f, char *subclass, size_t slen, char *moreinfo, size_t mlen);
00609 
00610 /*!
00611  * \brief Copy the discription of a frame type into the provided string
00612  *
00613  * \param frame_type The frame type to be described
00614  * \param ftype Buffer to fill with frame type description
00615  * \param len Length of subclass buffer
00616  * \since 11
00617  */
00618 void ast_frame_type2str(enum ast_frame_type frame_type, char *ftype, size_t len);
00619 
00620 #if defined(__cplusplus) || defined(c_plusplus)
00621 }
00622 #endif
00623 
00624 #endif /* _ASTERISK_FRAME_H */

Generated on Thu Apr 16 06:27:35 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6