Asterisk - The Open Source Telephony Project  GIT-master-0190e70
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)
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  */
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 
141 enum {
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 */
152  int integer;
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  */
165 struct ast_frame {
166  /*! Kind of frame */
167  enum ast_frame_type frametype;
168  /*! Subclass, frame dependent */
169  struct ast_frame_subclass subclass;
170  /*! Length of data */
171  int datalen;
172  /*! Number of samples in this frame */
173  int samples;
174  /*! Was the data malloc'd? i.e. should we free it when we discard the frame? */
175  int mallocd;
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 */
179  int offset;
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 */
217 extern 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  */
364  size_t payload_size;
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-impared) 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 #define AST_OPTION_ECHOCAN 8
467 
468 /*! \brief Handle channel write data
469  * If a channel needs to process the data from a func_channel write operation
470  * after func_channel_write executes, it can define the setoption callback
471  * and process this option. A pointer to an ast_chan_write_info_t will be passed.
472  *
473  * \note This option should never be passed over the network. */
474 #define AST_OPTION_CHANNEL_WRITE 9
475 
476 /* !
477  * Read-only. Allows query current status of T38 on the channel.
478  * data: ast_t38state
479  */
480 #define AST_OPTION_T38_STATE 10
481 
482 /*! Request that the channel driver deliver frames in a specific format
483  * Option data is a format_t */
484 #define AST_OPTION_FORMAT_READ 11
485 
486 /*! Request that the channel driver be prepared to accept frames in a specific format
487  * Option data is a format_t */
488 #define AST_OPTION_FORMAT_WRITE 12
489 
490 /*! Request that the channel driver make two channels of the same tech type compatible if possible
491  * Option data is an ast_channel
492  *
493  * \note This option should never be passed over the network */
494 #define AST_OPTION_MAKE_COMPATIBLE 13
495 
496 /*! Get or set the digit detection state of the channel
497  * Option data is a single signed char value 0 or 1 */
498 #define AST_OPTION_DIGIT_DETECT 14
499 
500 /*! Get or set the fax tone detection state of the channel
501  * Option data is a single signed char value 0 or 1 */
502 #define AST_OPTION_FAX_DETECT 15
503 
504 /*! Get the device name from the channel (Read only)
505  * Option data is a character buffer of suitable length */
506 #define AST_OPTION_DEVICE_NAME 16
507 
508 /*! Get the CC agent type from the channel (Read only)
509  * Option data is a character buffer of suitable length */
510 #define AST_OPTION_CC_AGENT_TYPE 17
511 
512 /*! Get or set the security options on a channel
513  * Option data is an integer value of 0 or 1 */
514 #define AST_OPTION_SECURE_SIGNALING 18
515 #define AST_OPTION_SECURE_MEDIA 19
516 
517 struct oprmode {
518  struct ast_channel *peer;
519  int mode;
520 } ;
521 
523  /* Always keep in network byte order */
524 #if __BYTE_ORDER == __BIG_ENDIAN
525  uint16_t flag:3;
526  uint16_t option:13;
527 #else
528 #if __BYTE_ORDER == __LITTLE_ENDIAN
529  uint16_t option:13;
530  uint16_t flag:3;
531 #else
532 #error Byte order not defined
533 #endif
534 #endif
535  uint8_t data[0];
536 };
537 
538 /*! \brief Requests a frame to be allocated
539  *
540  * \param source
541  * Request a frame be allocated. source is an optional source of the frame,
542  * len is the requested length, or "0" if the caller will supply the buffer
543  */
544 #if 0 /* Unimplemented */
545 struct ast_frame *ast_fralloc(char *source, int len);
546 #endif
547 
548 /*!
549  * \brief Frees a frame or list of frames
550  *
551  * \param fr Frame to free, or head of list to free
552  * \param cache Whether to consider this frame for frame caching
553  */
554 void ast_frame_free(struct ast_frame *fr, int cache);
555 
556 #define ast_frfree(fr) ast_frame_free(fr, 1)
557 
558 /*!
559  * \brief NULL-safe wrapper for \ref ast_frfree, good for \ref RAII_VAR.
560  * \param frame Frame to free, or head of list to free.
561  */
562 void ast_frame_dtor(struct ast_frame *frame);
563 
564 /*! \brief Makes a frame independent of any static storage
565  * \param fr frame to act upon
566  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
567  * and if the data hasn't been malloced then make the
568  * data malloc'd. If you need to store frames, say for queueing, then
569  * you should call this function.
570  * \return Returns a frame on success, NULL on error
571  * \note This function may modify the frame passed to it, so you must
572  * not assume the frame will be intact after the isolated frame has
573  * been produced. In other words, calling this function on a frame
574  * should be the last operation you do with that frame before freeing
575  * it (or exiting the block, if the frame is on the stack.)
576  */
577 #define ast_frisolate(fr) __ast_frisolate(fr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
578 struct ast_frame *__ast_frisolate(struct ast_frame *fr, const char *file, int line, const char *func);
579 
580 /*! \brief Copies a frame
581  * \param fr frame to copy
582  * Duplicates a frame -- should only rarely be used, typically frisolate is good enough
583  * \return Returns a frame on success, NULL on error
584  */
585 #define ast_frdup(fr) __ast_frdup(fr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
586 struct ast_frame *__ast_frdup(const struct ast_frame *fr, const char *file, int line, const char *func);
587 
588 void ast_swapcopy_samples(void *dst, const void *src, int samples);
589 
590 /* Helpers for byteswapping native samples to/from
591  little-endian and big-endian. */
592 #if __BYTE_ORDER == __LITTLE_ENDIAN
593 #define ast_frame_byteswap_le(fr) do { ; } while(0)
594 #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)
595 #else
596 #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)
597 #define ast_frame_byteswap_be(fr) do { ; } while(0)
598 #endif
599 
600 void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix);
601 
602 /*! \brief Appends a frame to the end of a list of frames, truncating the maximum length of the list */
603 struct ast_frame *ast_frame_enqueue(struct ast_frame *head, struct ast_frame *f, int maxlen, int dupe);
604 
605 /*!
606  \brief Adjusts the volume of the audio samples contained in a frame.
607  \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
608  \param adjustment The number of dB to adjust up or down.
609  \return 0 for success, non-zero for an error
610  */
611 int ast_frame_adjust_volume(struct ast_frame *f, int adjustment);
612 
613 /*!
614  \brief Adjusts the volume of the audio samples contained in a frame.
615  \param f The frame containing the samples (must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR)
616  \param adjustment The number of dB to adjust up or down.
617  \return 0 for success, non-zero for an error
618  */
619 int ast_frame_adjust_volume_float(struct ast_frame *f, float adjustment);
620 
621 /*!
622  \brief Sums two frames of audio samples.
623  \param f1 The first frame (which will contain the result)
624  \param f2 The second frame
625  \return 0 for success, non-zero for an error
626 
627  The frames must be AST_FRAME_VOICE and must contain AST_FORMAT_SLINEAR samples,
628  and must contain the same number of samples.
629  */
630 int ast_frame_slinear_sum(struct ast_frame *f1, struct ast_frame *f2);
631 
632 /*!
633  * \brief Clear all audio samples from an ast_frame. The frame must be AST_FRAME_VOICE and AST_FORMAT_SLINEAR
634  */
635 int ast_frame_clear(struct ast_frame *frame);
636 
637 /*!
638  * \brief Copy the discription of a frame's subclass into the provided string
639  *
640  * \param f The frame to get the information from
641  * \param subclass Buffer to fill with subclass information
642  * \param slen Length of subclass buffer
643  * \param moreinfo Buffer to fill with additional information
644  * \param mlen Length of moreinfo buffer
645  * \return Pointer to subclass
646  * \since 11
647  */
648 char *ast_frame_subclass2str(struct ast_frame *f, char *subclass, size_t slen, char *moreinfo, size_t mlen);
649 
650 /*!
651  * \brief Copy the discription of a frame type into the provided string
652  *
653  * \param frame_type The frame type to be described
654  * \param ftype Buffer to fill with frame type description
655  * \param len Length of subclass buffer
656  * \return Pointer to ftype
657  * \since 11
658  */
659 char *ast_frame_type2str(enum ast_frame_type frame_type, char *ftype, size_t len);
660 
661 #if defined(__cplusplus) || defined(c_plusplus)
662 }
663 #endif
664 
665 #endif /* _ASTERISK_FRAME_H */
Main Channel structure associated with a channel.
struct ast_frame * __ast_frdup(const struct ast_frame *fr, const char *file, int line, const char *func)
Definition: main/frame.c:305
int ast_frame_slinear_sum(struct ast_frame *f1, struct ast_frame *f2)
Sums two frames of audio samples.
Definition: main/frame.c:828
ast_control_transfer
void ast_swapcopy_samples(void *dst, const void *src, int samples)
Definition: main/frame.c:396
void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix)
Definition: main/frame.c:722
Definition of a media format.
Definition: format.c:43
ast_control_frame_type
Internal control frame subtype field values.
void ast_frame_free(struct ast_frame *fr, int cache)
Requests a frame to be allocated.
Definition: main/frame.c:176
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...
struct ast_frame_subclass subclass
Media Format API.
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:803
void ast_frame_dtor(struct ast_frame *frame)
NULL-safe wrapper for ast_frfree, good for RAII_VAR.
Definition: main/frame.c:187
const char * src
Asterisk architecture endianess compatibility definitions.
char * ast_frame_subclass2str(struct ast_frame *f, char *subclass, size_t slen, char *moreinfo, size_t mlen)
Copy the discription of a frame&#39;s subclass into the provided string.
Definition: main/frame.c:406
A set of macros to manage forward-linked lists.
ast_frame_type
Frame types.
ast_control_t38_rate_management
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
struct ast_frame * __ast_frisolate(struct ast_frame *fr, const char *file, int line, const char *func)
&#39;isolates&#39; a frame by duplicating non-malloc&#39;ed components (header, src, data). On return all compone...
Definition: main/frame.c:197
frame_type
Definition: codec_builtin.c:44
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
long int flag
Definition: f2c.h:83
static const char name[]
Definition: cdr_mysql.c:74
ast_control_t38_rate
#define AST_CHANNEL_NAME
Definition: channel.h:172
unsigned int flags
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:662
struct ast_channel * peer
struct ao2_container * cache
Definition: pbx_realtime.c:77
struct ast_frame ast_null_frame
Definition: main/frame.c:79
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:850
Data structure associated with a single frame of data.
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:778
struct ast_format * format
ast_frame_read_action
Actions to indicate to, and be handled on channel read.
struct ast_stream_topology * topology
static char prefix[MAX_PREFIX]
Definition: http.c:141