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