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

channel.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- A telephony toolkit for Linux.
00003  *
00004  * General Asterisk channel 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 General Public License
00012  */
00013 
00014 #ifndef _ASTERISK_CHANNEL_H
00015 #define _ASTERISK_CHANNEL_H
00016 
00017 #include <asterisk/frame.h>
00018 #include <asterisk/sched.h>
00019 #include <asterisk/chanvars.h>
00020 #include <unistd.h>
00021 #include <setjmp.h>
00022 #include <pthread.h>
00023 
00024 #if defined(__cplusplus) || defined(c_plusplus)
00025 extern "C" {
00026 #endif
00027 
00028 #include <asterisk/lock.h>
00029 
00030 //! Max length of an extension
00031 #define AST_MAX_EXTENSION 80
00032 
00033 #include <asterisk/cdr.h>
00034 #include <asterisk/monitor.h>
00035 
00036 
00037 #define AST_CHANNEL_NAME 80
00038 #define AST_CHANNEL_MAX_STACK 32
00039 
00040 #define MAX_LANGUAGE 20
00041 
00042 
00043 #define AST_MAX_FDS 8
00044 
00045 struct ast_generator {
00046    void *(*alloc)(struct ast_channel *chan, void *params);
00047    void (*release)(struct ast_channel *chan, void *data);
00048    int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
00049 };
00050 
00051 //! Main Channel structure associated with a channel.
00052 /*! 
00053  * This is the side of it mostly used by the pbx and call management.
00054  */
00055 struct ast_channel {
00056    /*! ASCII Description of channel name */
00057    char name[AST_CHANNEL_NAME];     
00058    /*! Language requested */
00059    char language[MAX_LANGUAGE];     
00060    /*! Type of channel */
00061    char *type;          
00062    /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
00063    int fds[AST_MAX_FDS];         
00064 
00065    /*! Default music class */
00066    char musicclass[MAX_LANGUAGE];
00067 
00068    /*! Current generator data if there is any */
00069    void *generatordata;
00070    /*! Current active data generator */
00071    struct ast_generator *generator;
00072    /*! Whether or not the generator should be interrupted by write */
00073    int writeinterrupt;
00074 
00075    /*! Who are we bridged to, if we're bridged */
00076    struct ast_channel *bridge;
00077    /*! Who did we call? */
00078    struct ast_channel *dialed;
00079    /*! Who called us? */
00080    struct ast_channel *dialing;
00081    /*! Reverse the dialed link (0 false, 1 true) */
00082    int reversedialed;
00083    /*! Channel that will masquerade as us */
00084    struct ast_channel *masq;     
00085    /*! Who we are masquerading as */
00086    struct ast_channel *masqr;    
00087    /*! Call Detail Record Flags */
00088    int cdrflags;                                
00089    /*! Whether or not we're blocking */
00090    int blocking;           
00091    /*! Whether or not we have been hung up...  Do not set this value
00092        directly, use ast_softhangup */
00093    int _softhangup;           
00094    /*! Non-zero if this is a zombie channel */
00095    int zombie;             
00096    /*! Non-zero, set to actual time when channel is to be hung up */
00097    time_t   whentohangup;
00098    /*! If anyone is blocking, this is them */
00099    pthread_t blocker;         
00100    /*! Lock, can be used to lock a channel for some operations */
00101    ast_mutex_t lock;       
00102    /*! Procedure causing blocking */
00103    char *blockproc;        
00104 
00105    /*! Current application */
00106    char *appl;          
00107    /*! Data passed to current application */
00108    char *data;          
00109    
00110    /*! Has an exception been detected */
00111    int exception;          
00112    /*! Which fd had an event detected on */
00113    int fdno;            
00114    /*! Schedule context */
00115    struct sched_context *sched;     
00116    /*! For streaming playback, the schedule ID */
00117    int streamid;           
00118    /*! Stream itself. */
00119    struct ast_filestream *stream;      
00120    /*! For streaming playback, the schedule ID */
00121    int vstreamid;          
00122    /*! Stream itself. */
00123    struct ast_filestream *vstream;     
00124    /*! Original writer format */
00125    int oldwriteformat;        
00126    
00127    /*! Timing fd */
00128    int timingfd;
00129    int (*timingfunc)(void *data);
00130    void *timingdata;
00131 
00132    /*! State of line -- Don't write directly, use ast_setstate */
00133    int _state;          
00134    /*! Number of rings so far */
00135    int rings;           
00136    /*! Current level of application */
00137    int stack;
00138 
00139 
00140    /*! Kinds of data this channel can natively handle */
00141    int nativeformats;         
00142    /*! Requested read format */
00143    int readformat;            
00144    /*! Requested write format */
00145    int writeformat;        
00146 
00147    
00148    /*! Malloc'd Dialed Number Identifier */
00149    char *dnid;          
00150    /*! Malloc'd Caller ID */
00151    char *callerid;            
00152    /*! Malloc'd ANI */
00153    char *ani;        
00154    /*! Malloc'd RDNIS */
00155    char *rdnis;
00156    /*! Hide callerid from user */
00157    int restrictcid;
00158    /*! Callerid presentation/screening */
00159    int callingpres;
00160 
00161    
00162    /*! Current extension context */
00163    char context[AST_MAX_EXTENSION]; 
00164    /*! Current non-macro context */
00165    char macrocontext[AST_MAX_EXTENSION];  
00166    /*! Current non-macro extension */
00167    char macroexten[AST_MAX_EXTENSION];
00168    /*! Current non-macro priority */
00169    int macropriority;
00170    /*! Current extension number */
00171    char exten[AST_MAX_EXTENSION];      
00172    /* Current extension priority */
00173    int priority;                 
00174    /*! Application information -- see assigned numbers */
00175    void *app[AST_CHANNEL_MAX_STACK];   
00176    /*! Any/all queued DTMF characters */
00177    char dtmfq[AST_MAX_EXTENSION];      
00178    /*! Are DTMF digits being deferred */
00179    int deferdtmf;          
00180    /*! DTMF frame */
00181    struct ast_frame dtmff;       
00182    /*! Private channel implementation details */
00183    struct ast_channel_pvt *pvt;
00184 
00185                   
00186    /*! Jump buffer used for returning from applications */
00187    jmp_buf jmp[AST_CHANNEL_MAX_STACK]; 
00188 
00189    struct ast_pbx *pbx;
00190    /*! Set BEFORE PBX is started to determine AMA flags */
00191    int   amaflags;         
00192    /*! Account code for billing */
00193    char  accountcode[20];     
00194    /*! Call Detail Record */
00195    struct ast_cdr *cdr;       
00196    /*! Whether or not ADSI is detected on CPE */
00197    int   adsicpe;
00198    /*! Where to forward to if asked to dial on this interface */
00199    char call_forward[AST_MAX_EXTENSION];
00200 
00201    /*! Tone zone */
00202    struct tone_zone *zone;
00203 
00204    /* Channel monitoring */
00205    struct ast_channel_monitor *monitor;
00206 
00207    /*! Track the read/written samples for monitor use */
00208    unsigned long insmpl;
00209    unsigned long outsmpl;
00210 
00211    /* Frames in/out counters */
00212    unsigned int fin;
00213    unsigned int fout;
00214 
00215    /* Unique Channel Identifier */
00216    char uniqueid[32];
00217 
00218    /* Why is the channel hanged up */
00219    int hangupcause;
00220    
00221    /* A linked list for variables */
00222    struct ast_var_t *vars; 
00223    AST_LIST_HEAD(varshead,ast_var_t) varshead;
00224 
00225    unsigned int callgroup;
00226    unsigned int pickupgroup;
00227 
00228    /*! channel flags of AST_FLAG_ type */
00229    int flag;
00230    
00231    /*! For easy linking */
00232    struct ast_channel *next;
00233 
00234 };
00235 
00236 #define AST_FLAG_DIGITAL   1  /* if the call is a digital ISDN call */
00237 
00238 static inline int ast_test_flag(struct ast_channel *chan, int mode)
00239 {
00240    return chan->flag & mode;
00241 }
00242 
00243 static inline void ast_set_flag(struct ast_channel *chan, int mode)
00244 {
00245    chan->flag |= mode;
00246 }
00247 
00248 static inline void ast_clear_flag(struct ast_channel *chan, int mode)
00249 {
00250    chan->flag &= ~mode;
00251 }
00252 
00253 static inline void ast_set2_flag(struct ast_channel *chan, int value, int mode)
00254 {
00255    if (value)
00256       ast_set_flag(chan, mode);
00257    else
00258       ast_clear_flag(chan, mode);
00259 }
00260 
00261 static inline void ast_dup_flag(struct ast_channel *dstchan, struct ast_channel *srcchan, int mode)
00262 {
00263    if (ast_test_flag(srcchan, mode))
00264       ast_set_flag(dstchan, mode);
00265    else
00266       ast_clear_flag(dstchan, mode);
00267 }  
00268 
00269 struct chanmon;
00270 
00271 #define LOAD_OH(oh) {   \
00272    oh.context = context; \
00273    oh.exten = exten; \
00274    oh.priority = priority; \
00275    oh.callerid = callerid; \
00276    oh.variable = variable; \
00277    oh.account = account; \
00278 } 
00279 
00280 struct outgoing_helper {
00281    char *context;
00282    char *exten;
00283    int priority;
00284    char *callerid;
00285    char *variable;
00286    char *account;
00287 };
00288 
00289 #define AST_CDR_TRANSFER   (1 << 0)
00290 #define AST_CDR_FORWARD    (1 << 1)
00291 #define AST_CDR_CALLWAIT   (1 << 2)
00292 #define AST_CDR_CONFERENCE (1 << 3)
00293 
00294 #define AST_ADSI_UNKNOWN   (0)
00295 #define AST_ADSI_AVAILABLE (1)
00296 #define AST_ADSI_UNAVAILABLE  (2)
00297 #define AST_ADSI_OFFHOOKONLY  (3)
00298 
00299 #define AST_SOFTHANGUP_DEV       (1 << 0) /* Soft hangup by device */
00300 #define AST_SOFTHANGUP_ASYNCGOTO (1 << 1) /* Soft hangup for async goto */
00301 #define AST_SOFTHANGUP_SHUTDOWN     (1 << 2)
00302 #define AST_SOFTHANGUP_TIMEOUT      (1 << 3)
00303 #define AST_SOFTHANGUP_APPUNLOAD (1 << 4)
00304 #define AST_SOFTHANGUP_EXPLICIT     (1 << 5)
00305 
00306 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
00307 /*! Channel is down and available */
00308 #define AST_STATE_DOWN     0     
00309 /*! Channel is down, but reserved */
00310 #define AST_STATE_RESERVED 1     
00311 /*! Channel is off hook */
00312 #define AST_STATE_OFFHOOK  2     
00313 /*! Digits (or equivalent) have been dialed */
00314 #define AST_STATE_DIALING  3     
00315 /*! Line is ringing */
00316 #define AST_STATE_RING     4     
00317 /*! Remote end is ringing */
00318 #define AST_STATE_RINGING  5     
00319 /*! Line is up */
00320 #define AST_STATE_UP    6     
00321 /*! Line is busy */
00322 #define AST_STATE_BUSY     7     
00323 /*! Digits (or equivalent) have been dialed while offhook */
00324 #define AST_STATE_DIALING_OFFHOOK   8
00325 
00326 /* Bits 16-32 of state are reserved for flags */
00327 /*! Do not transmit voice data */
00328 #define AST_STATE_MUTE     (1 << 16)   
00329 
00330 /*! Device is valid but channel didn't know state */
00331 #define AST_DEVICE_UNKNOWN 0
00332 /*! Device is not used */
00333 #define AST_DEVICE_NOT_INUSE  1
00334 /*! Device is in use */
00335 #define AST_DEVICE_INUSE   2
00336 /*! Device is busy */
00337 #define AST_DEVICE_BUSY    3
00338 /*! Device is invalid */
00339 #define AST_DEVICE_INVALID 4
00340 /*! Device is unavailable */
00341 #define AST_DEVICE_UNAVAILABLE   5
00342 
00343 //! Requests a channel
00344 /*! 
00345  * \param type type of channel to request
00346  * \param format requested channel format
00347  * \param data data to pass to the channel requester
00348  * Request a channel of a given type, with data as optional information used 
00349  * by the low level module
00350  * Returns an ast_channel on success, NULL on failure.
00351  */
00352 struct ast_channel *ast_request(char *type, int format, void *data);
00353 
00354 //! Search the Channels by Name
00355 /*!
00356  * \param device like a dialstring
00357  * Search the Device in active channels by compare the channelname against 
00358  * the devicename. Compared are only the first chars to the first '-' char.
00359  * Returns an AST_DEVICE_UNKNOWN if no channel found or
00360  * AST_DEVICE_INUSE if a channel is found
00361  */
00362 int ast_parse_device_state(char *device);
00363 
00364 //! Asks a channel for device state
00365 /*!
00366  * \param device like a dialstring
00367  * Asks a channel for device state, data is  normaly a number from dialstring
00368  * used by the low level module
00369  * Trys the channel devicestate callback if not supported search in the
00370  * active channels list for the device.
00371  * Returns an AST_DEVICE_??? state -1 on failure
00372  */
00373 int ast_device_state(char *device);
00374 
00375 /*!
00376  * \param type type of channel to request
00377  * \param format requested channel format
00378  * \param data data to pass to the channel requester
00379  * \param timeout maximum amount of time to wait for an answer
00380  * \param why unsuccessful (if unsuceessful)
00381  * Request a channel of a given type, with data as optional information used 
00382  * by the low level module and attempt to place a call on it
00383  * Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
00384  * to know if the call was answered or not.
00385  */
00386 struct ast_channel *ast_request_and_dial(char *type, int format, void *data, int timeout, int *reason, char *callerid);
00387 
00388 struct ast_channel *__ast_request_and_dial(char *type, int format, void *data, int timeout, int *reason, char *callerid, struct outgoing_helper *oh);
00389 
00390 //! Registers a channel
00391 /*! 
00392  * \param type type of channel you are registering
00393  * \param description short description of the channel
00394  * \param capabilities a bit mask of the capabilities of the channel
00395  * \param requester a function pointer that properly responds to a call.  See one of the channel drivers for details.
00396  * Called by a channel module to register the kind of channels it supports.
00397  * It supplies a brief type, a longer, but still short description, and a
00398  * routine that creates a channel
00399  * Returns 0 on success, -1 on failure.
00400  */
00401 int ast_channel_register(char *type, char *description, int capabilities, 
00402          struct ast_channel* (*requester)(char *type, int format, void *data));
00403 
00404 /* Same like the upper function but with support for devicestate */
00405 int ast_channel_register_ex(char *type, char *description, int capabilities,
00406       struct ast_channel *(*requester)(char *type, int format, void *data),
00407       int (*devicestate)(void *data));
00408 
00409 //! Unregister a channel class
00410 /*
00411  * \param type the character string that corresponds to the channel you wish to unregister
00412  * Basically just unregisters the channel with the asterisk channel system
00413  * No return value.
00414  */
00415 void ast_channel_unregister(char *type);
00416 
00417 //! Hang up a channel 
00418 /*! 
00419  * \param chan channel to hang up
00420  * This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
00421  * performs all stream stopping, etc, on the channel that needs to end.
00422  * chan is no longer valid after this call.
00423  * Returns 0 on success, -1 on failure.
00424  */
00425 int ast_hangup(struct ast_channel *chan);
00426 
00427 //! Softly hangup up a channel
00428 /*! 
00429  * \param chan channel to be soft-hung-up
00430  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
00431  * safely hangup a channel managed by another thread.
00432  * Returns 0 regardless
00433  */
00434 int ast_softhangup(struct ast_channel *chan, int cause);
00435 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
00436 
00437 //! Check to see if a channel is needing hang up
00438 /*! 
00439  * \param chan channel on which to check for hang up
00440  * This function determines if the channel is being requested to be hung up.
00441  * Returns 0 if not, or 1 if hang up is requested (including time-out).
00442  */
00443 int ast_check_hangup(struct ast_channel *chan);
00444 
00445 //! Set when to hang a channel up
00446 /*! 
00447  * \param chan channel on which to check for hang up
00448  * \param offset offset in seconds from current time of when to hang up
00449  * This function sets the absolute time out on a channel (when to hang up).
00450  */
00451 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
00452 
00453 //! Answer a ringing call
00454 /*!
00455  * \param chan channel to answer
00456  * This function answers a channel and handles all necessary call
00457  * setup functions.
00458  * Returns 0 on success, -1 on failure
00459  */
00460 int ast_answer(struct ast_channel *chan);
00461 
00462 //! Make a call
00463 /*! 
00464  * \param chan which channel to make the call on
00465  * \param addr destination of the call
00466  * \param timeout time to wait on for connect
00467  * Place a call, take no longer than timeout ms.  Returns -1 on failure, 
00468    0 on not enough time (does not auto matically stop ringing), and  
00469    the number of seconds the connect took otherwise.
00470    Returns 0 on success, -1 on failure
00471    */
00472 int ast_call(struct ast_channel *chan, char *addr, int timeout);
00473 
00474 //! Indicates condition of channel
00475 /*! 
00476  * \param chan channel to change the indication
00477  * \param condition which condition to indicate on the channel
00478  * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
00479  * Returns 0 on success, -1 on failure
00480  */
00481 int ast_indicate(struct ast_channel *chan, int condition);
00482 
00483 /* Misc stuff */
00484 
00485 //! Wait for input on a channel
00486 /*! 
00487  * \param chan channel to wait on
00488  * \param ms length of time to wait on the channel
00489  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
00490   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
00491 int ast_waitfor(struct ast_channel *chan, int ms);
00492 
00493 //! Wait for a specied amount of time, looking for hangups
00494 /*!
00495  * \param chan channel to wait for
00496  * \param ms length of time in milliseconds to sleep
00497  * Waits for a specified amount of time, servicing the channel as required.
00498  * returns -1 on hangup, otherwise 0.
00499  */
00500 int ast_safe_sleep(struct ast_channel *chan, int ms);
00501 
00502 //! Wait for a specied amount of time, looking for hangups and a condition argument
00503 /*!
00504  * \param chan channel to wait for
00505  * \param ms length of time in milliseconds to sleep
00506  * \param cond a function pointer for testing continue condition
00507  * \param data argument to be passed to the condition test function
00508  * Waits for a specified amount of time, servicing the channel as required. If cond
00509  * returns 0, this function returns.
00510  * returns -1 on hangup, otherwise 0.
00511  */
00512 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
00513 
00514 //! Waits for activity on a group of channels
00515 /*! 
00516  * \param chan an array of pointers to channels
00517  * \param n number of channels that are to be waited upon
00518  * \param fds an array of fds to wait upon
00519  * \param nfds the number of fds to wait upon
00520  * \param exception exception flag
00521  * \param outfd fd that had activity on it
00522  * \param ms how long the wait was
00523  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
00524    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
00525    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
00526    will be -1 */
00527 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
00528 
00529 //! Waits for input on a group of channels
00530 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
00531    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
00532 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
00533 
00534 //! Waits for input on an fd
00535 /*! This version works on fd's only.  Be careful with it. */
00536 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
00537 
00538 
00539 //! Reads a frame
00540 /*!
00541  * \param chan channel to read a frame from
00542  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
00543    best just stop reading frames and assume the channel has been
00544    disconnected. */
00545 struct ast_frame *ast_read(struct ast_channel *chan);
00546 
00547 //! Write a frame to a channel
00548 /*!
00549  * \param chan destination channel of the frame
00550  * \param frame frame that will be written
00551  * This function writes the given frame to the indicated channel.
00552  * It returns 0 on success, -1 on failure.
00553  */
00554 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
00555 
00556 //! Write video frame to a channel
00557 /*!
00558  * \param chan destination channel of the frame
00559  * \param frame frame that will be written
00560  * This function writes the given frame to the indicated channel.
00561  * It returns 1 on success, 0 if not implemented, and -1 on failure.
00562  */
00563 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
00564 
00565 /* Send empty audio to prime a channel driver */
00566 int ast_prod(struct ast_channel *chan);
00567 
00568 //! Sets read format on channel chan
00569 /*! 
00570  * \param chan channel to change
00571  * \param format format to change to
00572  * Set read format for channel to whichever component of "format" is best. 
00573  * Returns 0 on success, -1 on failure
00574  */
00575 int ast_set_read_format(struct ast_channel *chan, int format);
00576 
00577 //! Sets write format on channel chan
00578 /*! 
00579  * \param chan channel to change
00580  * \param format new format for writing
00581  * Set write format for channel to whichever compoent of "format" is best. 
00582  * Returns 0 on success, -1 on failure
00583  */
00584 int ast_set_write_format(struct ast_channel *chan, int format);
00585 
00586 //! Sends text to a channel
00587 /*! 
00588  * \param chan channel to act upon
00589  * \param text string of text to send on the channel
00590  * Write text to a display on a channel
00591  * Returns 0 on success, -1 on failure
00592  */
00593 int ast_sendtext(struct ast_channel *chan, char *text);
00594 
00595 //! Receives a text character from a channel
00596 /*! 
00597  * \param chan channel to act upon
00598  * \param timeout timeout in milliseconds (0 for infinite wait)
00599  * Read a char of text from a channel
00600  * Returns 0 on success, -1 on failure
00601  */
00602 int ast_recvchar(struct ast_channel *chan, int timeout);
00603 
00604 //! Browse channels in use
00605 /*! 
00606  * \param prev where you want to start in the channel list
00607  * Browse the channels currently in use 
00608  * Returns the next channel in the list, NULL on end.
00609  */
00610 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
00611 
00612 //! Waits for a digit
00613 /*! 
00614  * \param c channel to wait for a digit on
00615  * \param ms how many milliseconds to wait
00616  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
00617 char ast_waitfordigit(struct ast_channel *c, int ms);
00618 
00619 /* Same as above with audio fd for outputing read audio and ctrlfd to monitor for
00620    reading. Returns 1 if ctrlfd becomes available */
00621 char ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
00622 
00623 //! Reads multiple digits
00624 /*! 
00625  * \param c channel to read from
00626  * \param s string to read in to.  Must be at least the size of your length
00627  * \param len how many digits to read (maximum)
00628  * \param timeout how long to timeout between digits
00629  * \param rtimeout timeout to wait on the first digit
00630  * \param enders digits to end the string
00631  * Read in a digit string "s", max length "len", maximum timeout between 
00632    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
00633    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
00634    a timeout, any digits that were read before the timeout will still be available in s.  
00635    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
00636 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
00637 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
00638 
00639 /*! Report DTMF on channel 0 */
00640 #define AST_BRIDGE_DTMF_CHANNEL_0      (1 << 0)    
00641 /*! Report DTMF on channel 1 */
00642 #define AST_BRIDGE_DTMF_CHANNEL_1      (1 << 1)    
00643 /*! Return all voice frames on channel 0 */
00644 #define AST_BRIDGE_REC_CHANNEL_0    (1 << 2)    
00645 /*! Return all voice frames on channel 1 */
00646 #define AST_BRIDGE_REC_CHANNEL_1    (1 << 3)    
00647 /*! Ignore all signal frames except NULL */
00648 #define AST_BRIDGE_IGNORE_SIGS         (1 << 4)    
00649 
00650 
00651 //! Makes two channel formats compatible
00652 /*! 
00653  * \param c0 first channel to make compatible
00654  * \param c1 other channel to make compatible
00655  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
00656    and -1 if it could not be done */
00657 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
00658 
00659 //! Bridge two channels together
00660 /*! 
00661  * \param c0 first channel to bridge
00662  * \param c1 second channel to bridge
00663  * \param flags for the channels
00664  * \param fo destination frame(?)
00665  * \param rc destination channel(?)
00666  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
00667    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
00668 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
00669 
00670 //! Weird function made for call transfers
00671 /*! 
00672  * \param original channel to make a copy of
00673  * \param clone copy of the original channel
00674  * This is a very strange and freaky function used primarily for transfer.  Suppose that
00675    "original" and "clone" are two channels in random situations.  This function takes
00676    the guts out of "clone" and puts them into the "original" channel, then alerts the
00677    channel driver of the change, asking it to fixup any private information (like the
00678    p->owner pointer) that is affected by the change.  The physical layer of the original
00679    channel is hung up.  */
00680 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
00681 
00682 //! Gives the string form of a given state
00683 /*! 
00684  * \param state state to get the name of
00685  * Give a name to a state 
00686  * Pretty self explanatory.
00687  * Returns the text form of the binary state given
00688  */
00689 char *ast_state2str(int state);
00690 
00691 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
00692    low level channel.  See frame.h for options.  Note that many channel drivers may support
00693    none or a subset of those features, and you should not count on this if you want your
00694    asterisk application to be portable.  They're mainly useful for tweaking performance */
00695 
00696 //! Sets an option on a channel
00697 /*! 
00698  * \param channel channel to set options on
00699  * \param option option to change
00700  * \param data data specific to option
00701  * \param datalen length of the data
00702  * \param block blocking or not
00703  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
00704  * Returns 0 on success and -1 on failure
00705  */
00706 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
00707 
00708 //! Checks the value of an option
00709 /*! 
00710  * Query the value of an option, optionally blocking until a reply is received
00711  * Works similarly to setoption except only reads the options.
00712  */
00713 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
00714 
00715 //! Checks for HTML support on a channel
00716 /*! Returns 0 if channel does not support HTML or non-zero if it does */
00717 int ast_channel_supports_html(struct ast_channel *channel);
00718 
00719 //! Sends HTML on given channel
00720 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
00721 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, char *data, int datalen);
00722 
00723 //! Sends a URL on a given link
00724 /*! Send URL on link.  Returns 0 on success or -1 on failure */
00725 int ast_channel_sendurl(struct ast_channel *channel, char *url);
00726 
00727 //! Defers DTMF
00728 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
00729    non-zero if channel was already DTMF-deferred or 0 if channel is just now
00730    being DTMF-deferred */
00731 int ast_channel_defer_dtmf(struct ast_channel *chan);
00732 
00733 //! Undeos a defer
00734 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
00735 void ast_channel_undefer_dtmf(struct ast_channel *chan);
00736 
00737 /*! Initiate system shutdown -- prevents new channels from being allocated.
00738     If "hangup" is non-zero, all existing channels will receive soft
00739      hangups */
00740 void ast_begin_shutdown(int hangup);
00741 
00742 /*! Cancels an existing shutdown and returns to normal operation */
00743 void ast_cancel_shutdown(void);
00744 
00745 /*! Returns number of active/allocated channels */
00746 int ast_active_channels(void);
00747 
00748 /*! Returns non-zero if Asterisk is being shut down */
00749 int ast_shutting_down(void);
00750 
00751 /*! Activate a given generator */
00752 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
00753 
00754 /*! Deactive an active generator */
00755 void ast_deactivate_generator(struct ast_channel *chan);
00756 
00757 void ast_set_callerid(struct ast_channel *chan, char *callerid, int  anitoo);
00758 
00759 /*! Start a tone going */
00760 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
00761 /*! Stop a tone from playing */
00762 void ast_tonepair_stop(struct ast_channel *chan);
00763 /*! Play a tone pair for a given amount of time */
00764 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
00765 
00766 /*! Automatically service a channel for us... */
00767 int ast_autoservice_start(struct ast_channel *chan);
00768 
00769 /*! Stop servicing a channel for us...  Returns -1 on error or if channel has been hungup */
00770 int ast_autoservice_stop(struct ast_channel *chan);
00771 
00772 /* If built with zaptel optimizations, force a scheduled expiration on the
00773    timer fd, at which point we call the callback function / data */
00774 int ast_settimeout(struct ast_channel *c, int samples, int (*func)(void *data), void *data);
00775 
00776 /* Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
00777    and 1 if supported and requested */
00778 int ast_transfer(struct ast_channel *chan, char *dest);
00779 
00780 /* Misc. functions below */
00781 
00782 //! Waits for activity on a group of channels
00783 /*! 
00784  * \param nfds the maximum number of file descriptors in the sets
00785  * \param rfds file descriptors to check for read availability
00786  * \param wfds file descriptors to check for write availability
00787  * \param efds file descriptors to check for exceptions (OOB data)
00788  * \param tvp timeout while waiting for events
00789  * This is the same as a standard select(), except it guarantees the
00790  * behaviour where the passed struct timeval is updated with how much
00791  * time was not slept while waiting for the specified events
00792  */
00793 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
00794 {
00795 #ifdef __linux__
00796    return select(nfds, rfds, wfds, efds, tvp);
00797 #else
00798    if (tvp) {
00799       struct timeval tv, tvstart, tvend, tvlen;
00800       int res;
00801 
00802       tv = *tvp;
00803       gettimeofday(&tvstart, NULL);
00804       res = select(nfds, rfds, wfds, efds, tvp);
00805       gettimeofday(&tvend, NULL);
00806       timersub(&tvend, &tvstart, &tvlen);
00807       timersub(&tv, &tvlen, tvp);
00808       if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
00809          tvp->tv_sec = 0;
00810          tvp->tv_usec = 0;
00811       }
00812       return res;
00813    }
00814    else
00815       return select(nfds, rfds, wfds, efds, NULL);
00816 #endif
00817 }
00818 
00819 #if !defined(ast_strdupa) && defined(__GNUC__)
00820 # define ast_strdupa(s)                         \
00821   (__extension__                             \
00822     ({                                       \
00823       __const char *__old = (s);                \
00824       size_t __len = strlen (__old) + 1;           \
00825       char *__new = (char *) __builtin_alloca (__len);   \
00826       (char *) memcpy (__new, __old, __len);       \
00827     }))
00828 #endif
00829 
00830 #ifdef DO_CRASH
00831 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
00832 #else
00833 #define CRASH do { } while(0)
00834 #endif
00835 
00836 #define CHECK_BLOCKING(c) {    \
00837                      if ((c)->blocking) {\
00838                         ast_log(LOG_WARNING, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", (long) pthread_self(), (c)->name, (long) (c)->blocker, (c)->blockproc); \
00839                         CRASH; \
00840                      } else { \
00841                         (c)->blocker = pthread_self(); \
00842                         (c)->blockproc = __PRETTY_FUNCTION__; \
00843                            c->blocking = -1; \
00844                            } }
00845 
00846 extern unsigned int ast_get_group(char *s);
00847 
00848 #if defined(__cplusplus) || defined(c_plusplus)
00849 }
00850 #endif
00851 
00852 
00853 #endif

Generated on Sun Apr 18 23:33:49 2004 for Asterisk by doxygen 1.3.6-20040222