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