Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals

frame.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- A telephony toolkit for Linux.
00003  *
00004  * Asterisk internal frame definitions.
00005  * 
00006  * Copyright (C) 1999, Mark Spencer
00007  *
00008  * Mark Spencer <markster@linux-support.net>
00009  *
00010  * This program is free software, distributed under the terms of
00011  * the GNU Lesser General Public License.  Other components of
00012  * Asterisk are distributed under The GNU General Public License
00013  * only.
00014  */
00015 
00016 #ifndef _ASTERISK_FRAME_H
00017 #define _ASTERISK_FRAME_H
00018 
00019 #if defined(__cplusplus) || defined(c_plusplus)
00020 extern "C" {
00021 #endif
00022 
00023 #include <sys/types.h>
00024 #include <sys/time.h>
00025    
00026 /*
00027  * Autodetect system endianess
00028  */
00029 #ifndef __BYTE_ORDER
00030 #ifdef __linux__
00031 #include <endian.h>
00032 #elif defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__APPLE__)
00033 #if defined(__OpenBSD__)
00034 #include <machine/types.h>
00035 #endif /* __OpenBSD__ */
00036 #include <machine/endian.h>
00037 #define __BYTE_ORDER BYTE_ORDER
00038 #define __LITTLE_ENDIAN LITTLE_ENDIAN
00039 #define __BIG_ENDIAN BIG_ENDIAN
00040 #else
00041 #ifdef __LITTLE_ENDIAN__
00042 #define __BYTE_ORDER __LITTLE_ENDIAN
00043 #endif /* __LITTLE_ENDIAN */
00044 
00045 #if defined(i386) || defined(__i386__)
00046 #define __BYTE_ORDER __LITTLE_ENDIAN
00047 #endif /* defined i386 */
00048 
00049 #if defined(sun) && defined(unix) && defined(sparc)
00050 #define __BYTE_ORDER __BIG_ENDIAN
00051 #endif /* sun unix sparc */
00052 
00053 #endif /* linux */
00054 
00055 #endif /* __BYTE_ORDER */
00056 
00057 #ifndef __BYTE_ORDER
00058 #error Need to know endianess
00059 #endif /* __BYTE_ORDER */
00060 
00061 struct ast_codec_pref {
00062    char order[32];
00063 };
00064 
00065 
00066 //! Data structure associated with a single frame of data
00067 /* A frame of data read used to communicate between 
00068    between channels and applications */
00069 struct ast_frame {
00070    /*! Kind of frame */
00071    int frametype;          
00072    /*! Subclass, frame dependent */
00073    int subclass;           
00074    /*! Length of data */
00075    int datalen;            
00076    /*! Number of 8khz samples in this frame */
00077    int samples;            
00078    /*! Was the data malloc'd?  i.e. should we free it when we discard the frame? */
00079    int mallocd;            
00080    /*! How far into "data" the data really starts */
00081    int offset;          
00082    /*! Optional source of frame for debugging */
00083    char *src;           
00084    /*! Pointer to actual data */
00085    void *data;    
00086    /*! Global delivery time */      
00087    struct timeval delivery;
00088    /*! Next/Prev for linking stand alone frames */
00089    struct ast_frame *prev;       
00090    /*! Next/Prev for linking stand alone frames */
00091    struct ast_frame *next;       
00092                         /* Unused except if debugging is turned on, but left
00093                            in the struct so that it can be turned on without
00094                            requiring a recompile of the whole thing */
00095 };
00096 
00097 struct ast_frame_chain {
00098    /* XXX Should ast_frame chain's be just prt of frames, i.e. should they just link? XXX */
00099    struct ast_frame *fr;
00100    struct ast_frame_chain *next;
00101 };
00102 
00103 #define AST_FRIENDLY_OFFSET   64    /*! It's polite for a a new frame to
00104                                  have this number of bytes for additional
00105                                  headers.  */
00106 #define AST_MIN_OFFSET     32    /*! Make sure we keep at least this much handy */
00107 
00108 /*! Need the header be free'd? */
00109 #define AST_MALLOCD_HDR    (1 << 0)
00110 /*! Need the data be free'd? */
00111 #define AST_MALLOCD_DATA   (1 << 1)
00112 /*! Need the source be free'd? (haha!) */
00113 #define AST_MALLOCD_SRC    (1 << 2)
00114 
00115 /* Frame types */
00116 /*! A DTMF digit, subclass is the digit */
00117 #define AST_FRAME_DTMF     1
00118 /*! Voice data, subclass is AST_FORMAT_* */
00119 #define AST_FRAME_VOICE    2
00120 /*! Video frame, maybe?? :) */
00121 #define AST_FRAME_VIDEO    3
00122 /*! A control frame, subclass is AST_CONTROL_* */
00123 #define AST_FRAME_CONTROL  4
00124 /*! An empty, useless frame */
00125 #define AST_FRAME_NULL     5
00126 /*! Inter Asterisk Exchange private frame type */
00127 #define AST_FRAME_IAX      6
00128 /*! Text messages */
00129 #define AST_FRAME_TEXT     7
00130 /*! Image Frames */
00131 #define AST_FRAME_IMAGE    8
00132 /*! HTML Frame */
00133 #define AST_FRAME_HTML     9
00134 /*! Comfort Noise frame (subclass is level of CNG in -dBov), 
00135     body may include zero or more 8-bit quantization coefficients */
00136 #define AST_FRAME_CNG      10
00137 
00138 /* HTML subclasses */
00139 /*! Sending a URL */
00140 #define AST_HTML_URL    1
00141 /*! Data frame */
00142 #define AST_HTML_DATA      2
00143 /*! Beginning frame */
00144 #define AST_HTML_BEGIN     4
00145 /*! End frame */
00146 #define AST_HTML_END    8
00147 /*! Load is complete */
00148 #define AST_HTML_LDCOMPLETE   16
00149 /*! Peer is unable to support HTML */
00150 #define AST_HTML_NOSUPPORT 17
00151 /*! Send URL, and track */
00152 #define AST_HTML_LINKURL   18
00153 /*! No more HTML linkage */
00154 #define AST_HTML_UNLINK    19
00155 /*! Reject link request */
00156 #define AST_HTML_LINKREJECT   20
00157 
00158 /* Data formats for capabilities and frames alike */
00159 /*! G.723.1 compression */
00160 #define AST_FORMAT_G723_1  (1 << 0)
00161 /*! GSM compression */
00162 #define AST_FORMAT_GSM     (1 << 1)
00163 /*! Raw mu-law data (G.711) */
00164 #define AST_FORMAT_ULAW    (1 << 2)
00165 /*! Raw A-law data (G.711) */
00166 #define AST_FORMAT_ALAW    (1 << 3)
00167 /*! ADPCM (G.726, 32kbps) */
00168 #define AST_FORMAT_G726    (1 << 4)
00169 /*! ADPCM (IMA) */
00170 #define AST_FORMAT_ADPCM   (1 << 5)
00171 /*! Raw 16-bit Signed Linear (8000 Hz) PCM */
00172 #define AST_FORMAT_SLINEAR (1 << 6)
00173 /*! LPC10, 180 samples/frame */
00174 #define AST_FORMAT_LPC10   (1 << 7)
00175 /*! G.729A audio */
00176 #define AST_FORMAT_G729A   (1 << 8)
00177 /*! SpeeX Free Compression */
00178 #define AST_FORMAT_SPEEX   (1 << 9)
00179 /*! iLBC Free Compression */
00180 #define AST_FORMAT_ILBC    (1 << 10)
00181 /*! Maximum audio format */
00182 #define AST_FORMAT_MAX_AUDIO  (1 << 15)
00183 /*! JPEG Images */
00184 #define AST_FORMAT_JPEG    (1 << 16)
00185 /*! PNG Images */
00186 #define AST_FORMAT_PNG     (1 << 17)
00187 /*! H.261 Video */
00188 #define AST_FORMAT_H261    (1 << 18)
00189 /*! H.263 Video */
00190 #define AST_FORMAT_H263    (1 << 19)
00191 /*! Max one */
00192 #define AST_FORMAT_MAX_VIDEO  (1 << 24)
00193 
00194 /* Control frame types */
00195 /*! Other end has hungup */
00196 #define AST_CONTROL_HANGUP    1
00197 /*! Local ring */
00198 #define AST_CONTROL_RING      2
00199 /*! Remote end is ringing */
00200 #define AST_CONTROL_RINGING      3
00201 /*! Remote end has answered */
00202 #define AST_CONTROL_ANSWER    4
00203 /*! Remote end is busy */
00204 #define AST_CONTROL_BUSY      5
00205 /*! Make it go off hook */
00206 #define AST_CONTROL_TAKEOFFHOOK     6
00207 /*! Line is off hook */
00208 #define AST_CONTROL_OFFHOOK      7
00209 /*! Congestion (circuits busy) */
00210 #define AST_CONTROL_CONGESTION      8
00211 /*! Flash hook */
00212 #define AST_CONTROL_FLASH     9
00213 /*! Wink */
00214 #define AST_CONTROL_WINK      10
00215 /*! Set a low-level option */
00216 #define AST_CONTROL_OPTION    11
00217 /*! Key Radio */
00218 #define  AST_CONTROL_RADIO_KEY      12
00219 /*! Un-Key Radio */
00220 #define  AST_CONTROL_RADIO_UNKEY    13
00221 /*! Indicate PROGRESS */
00222 #define AST_CONTROL_PROGRESS            14
00223 /*! Indicate CALL PROCEEDING */
00224 #define AST_CONTROL_PROCEEDING      15
00225 
00226 #define AST_SMOOTHER_FLAG_G729      (1 << 0)
00227 
00228 /* Option identifiers and flags */
00229 #define AST_OPTION_FLAG_REQUEST     0
00230 #define AST_OPTION_FLAG_ACCEPT      1
00231 #define AST_OPTION_FLAG_REJECT      2
00232 #define AST_OPTION_FLAG_QUERY    4
00233 #define AST_OPTION_FLAG_ANSWER      5
00234 #define AST_OPTION_FLAG_WTF      6
00235 
00236 /* Verify touchtones by muting audio transmission 
00237    (and reception) and verify the tone is still present */
00238 #define AST_OPTION_TONE_VERIFY      1     
00239 
00240 /* Put a compatible channel into TDD (TTY for the hearing-impared) mode */
00241 #define  AST_OPTION_TDD       2
00242 
00243 /* Relax the parameters for DTMF reception (mainly for radio use) */
00244 #define  AST_OPTION_RELAXDTMF    3
00245 
00246 /* Set (or clear) Audio (Not-Clear) Mode */
00247 #define  AST_OPTION_AUDIO_MODE      4
00248 
00249 struct ast_option_header {
00250    /* Always keep in network byte order */
00251 #if __BYTE_ORDER == __BIG_ENDIAN
00252         u_int16_t flag:3;
00253         u_int16_t option:13;
00254 #else
00255 #if __BYTE_ORDER == __LITTLE_ENDIAN
00256         u_int16_t option:13;
00257         u_int16_t flag:3;
00258 #else
00259 #error Byte order not defined
00260 #endif
00261 #endif
00262       u_int8_t data[0];
00263 };
00264 
00265 // Requests a frame to be allocated
00266 /* 
00267  * \param source 
00268  * Request a frame be allocated.  source is an optional source of the frame, 
00269  * len is the requested length, or "0" if the caller will supply the buffer 
00270  */
00271 #if 0 /* Unimplemented */
00272 struct ast_frame *ast_fralloc(char *source, int len);
00273 #endif
00274 
00275 //! Frees a frame
00276 /*! 
00277  * \param fr Frame to free
00278  * Free a frame, and the memory it used if applicable
00279  * no return.
00280  */
00281 void ast_frfree(struct ast_frame *fr);
00282 
00283 //! Copies a frame
00284 /*! 
00285  * \param fr frame to act upon
00286  * Take a frame, and if it's not been malloc'd, make a malloc'd copy
00287  * and if the data hasn't been malloced then make the
00288  * data malloc'd.  If you need to store frames, say for queueing, then
00289  * you should call this function.
00290  * Returns a frame on success, NULL on error
00291  */
00292 struct ast_frame *ast_frisolate(struct ast_frame *fr);
00293 
00294 //! Copies a frame
00295 /*! 
00296  * \param fr frame to copy
00297  * Dupliates a frame -- should only rarely be used, typically frisolate is good enough
00298  * Returns a frame on success, NULL on error
00299  */
00300 struct ast_frame *ast_frdup(struct ast_frame *fr);
00301 
00302 //! Chains a frame -- unimplemented
00303 #if 0 /* unimplemented */
00304 void ast_frchain(struct ast_frame_chain *fc);
00305 #endif
00306 
00307 //! Reads a frame from an fd
00308 /*! 
00309  * \param fd an opened fd to read from
00310  * Read a frame from a stream or packet fd, as written by fd_write
00311  * returns a frame on success, NULL on error
00312  */
00313 struct ast_frame *ast_fr_fdread(int fd);
00314 
00315 //! Writes a frame to an fd
00316 /*! 
00317  * \param fd Which fd to write to
00318  * \param frame frame to write to the fd
00319  * Write a frame to an fd
00320  * Returns 0 on success, -1 on failure
00321  */
00322 int ast_fr_fdwrite(int fd, struct ast_frame *frame);
00323 
00324 //! Sends a hangup to an fd
00325 /*! 
00326  * \param fd fd to write to
00327  * Send a hangup (NULL equivalent) on an fd
00328  * Returns 0 on success, -1 on failure
00329  */
00330 int ast_fr_fdhangup(int fd);
00331 
00332 //! Get the name of a format
00333 /*!
00334  * \param format id of format
00335  * \return A static string containing the name of the format or "UNKN" if unknown.
00336  */
00337 extern char* ast_getformatname(int format);
00338 
00339 //! Get the names of a set of formats
00340 /*!
00341  * \param buf a buffer for the output string
00342  * \param n size of buf (bytes)
00343  * \param format the format (combined IDs of codecs)
00344  * Prints a list of readable codec names corresponding to "format".
00345  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
00346  * \return The return value is buf.
00347  */
00348 extern char* ast_getformatname_multiple(char *buf, size_t size, int format);
00349 
00350 /*!
00351  * \param name string of format
00352  * Gets a format from a name.
00353  * This returns the form of the format in binary on success, 0 on error.
00354  */
00355 extern int ast_getformatbyname(char *name);
00356 
00357 //! Get a name from a format
00358 /*!
00359  * \param codec codec number (1,2,4,8,16,etc.)
00360  * Gets a name from a format
00361  * This returns a static string identifying the format on success, 0 on error.
00362  */
00363 extern char *ast_codec2str(int codec);
00364 
00365 //! Pick the best codec 
00366 /* Choose the best codec...  Uhhh...   Yah. */
00367 extern int ast_best_codec(int fmts);
00368 
00369 struct ast_smoother;
00370 
00371 extern struct ast_format_list *ast_get_format_list_index(int index);
00372 extern struct ast_format_list *ast_get_format_list(size_t *size);
00373 extern struct ast_smoother *ast_smoother_new(int bytes);
00374 extern void ast_smoother_set_flags(struct ast_smoother *smoother, int flags);
00375 extern int ast_smoother_get_flags(struct ast_smoother *smoother);
00376 extern void ast_smoother_free(struct ast_smoother *s);
00377 extern void ast_smoother_reset(struct ast_smoother *s, int bytes);
00378 extern int ast_smoother_feed(struct ast_smoother *s, struct ast_frame *f);
00379 extern struct ast_frame *ast_smoother_read(struct ast_smoother *s);
00380 
00381 extern void ast_frame_dump(char *name, struct ast_frame *f, char *prefix);
00382 
00383 /* Initialize a codec preference to "no preference" */
00384 extern void ast_codec_pref_init(struct ast_codec_pref *pref);
00385 
00386 /* Codec located at  a particular place in the preference index */
00387 extern int ast_codec_pref_index(struct ast_codec_pref *pref, int index);
00388 
00389 /* Remove a codec from a preference list */
00390 extern void ast_codec_pref_remove(struct ast_codec_pref *pref, int format);
00391 
00392 /* Append a codec to a preference list, removing it first if it was already there */
00393 extern int ast_codec_pref_append(struct ast_codec_pref *pref, int format);
00394 
00395 /* Select the best format according to preference list from supplied options. 
00396    If "find_best" is non-zero then if nothing is found, the "Best" format of 
00397    the format list is selected, otherwise 0 is returned. */
00398 extern int ast_codec_choose(struct ast_codec_pref *pref, int formats, int find_best);
00399 
00400 /* Parse an "allow" or "deny" line and update the mask and pref if provided */
00401 extern void ast_parse_allow_disallow(struct ast_codec_pref *pref, int *mask, char *list, int allowing);
00402 
00403 /* Dump codec preference list into a string */
00404 extern int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
00405 
00406 /* Shift a codec preference list up or down 65 bytes so that it becomes an ASCII string */
00407 extern void ast_codec_pref_shift(struct ast_codec_pref *pref, char *buf, size_t size, int right);
00408 
00409 #if defined(__cplusplus) || defined(c_plusplus)
00410 }
00411 #endif
00412 
00413 
00414 #endif

Generated on Thu Nov 29 22:50:23 2007 for Asterisk by  doxygen 1.4.2