Rework channel structure to eliminate "pvt" portion of channel (bug #3573)
[asterisk/asterisk.git] / include / asterisk / channel.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * General Asterisk channel definitions.
5  * 
6  * Copyright (C) 1999 - 2005, Digium, Inc.
7  *
8  * Mark Spencer <markster@digium.com>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License
12  */
13
14 #ifndef _ASTERISK_CHANNEL_H
15 #define _ASTERISK_CHANNEL_H
16
17 #include <asterisk/frame.h>
18 #include <asterisk/sched.h>
19 #include <asterisk/chanvars.h>
20
21 #include <unistd.h>
22 #include <setjmp.h>
23 #if defined(__APPLE__)
24 #include <asterisk/poll-compat.h>
25 #else
26 #include <sys/poll.h>
27 #endif
28
29 #if defined(__cplusplus) || defined(c_plusplus)
30 extern "C" {
31 #endif
32
33 #include <asterisk/lock.h>
34
35 /*! Max length of an extension */
36 #define AST_MAX_EXTENSION 80
37
38 #include <asterisk/cdr.h>
39 #include <asterisk/monitor.h>
40 #include <asterisk/utils.h>
41
42
43 #define AST_CHANNEL_NAME 80
44
45 #define MAX_LANGUAGE 20
46
47
48 #define AST_MAX_FDS 8
49
50 typedef unsigned long long ast_group_t;
51
52 struct ast_generator {
53         void *(*alloc)(struct ast_channel *chan, void *params);
54         void (*release)(struct ast_channel *chan, void *data);
55         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
56 };
57
58 struct ast_callerid {
59         /*! Malloc'd Dialed Number Identifier */
60         char *cid_dnid;                         
61         /*! Malloc'd Caller Number */
62         char *cid_num;
63         /*! Malloc'd Caller Name */
64         char *cid_name;
65         /*! Malloc'd ANI */
66         char *cid_ani;                  
67         /*! Malloc'd RDNIS */
68         char *cid_rdnis;
69         /*! Callerid presentation/screening */
70         int cid_pres;
71         /*! Callerid ANI 2 (Info digits) */
72         int cid_ani2;
73         /*! Callerid Type of Number */
74         int cid_ton;
75         /*! Callerid Transit Network Select */
76         int cid_tns;
77 };
78
79 /*! Structure to describe a channel "technology" */
80
81 struct ast_channel_tech {
82         const char * const type;
83         const char * const description;
84
85         int capabilities;
86
87         struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
88
89         int (* const devicestate)(void *data);
90
91         /*! Send a literal DTMF digit */
92         int (* const send_digit)(struct ast_channel *chan, char digit);
93
94         /*! Call a given phone number (address, etc), but don't
95            take longer than timeout seconds to do so.  */
96         int (* const call)(struct ast_channel *chan, char *addr, int timeout);
97
98         /*! Hangup (and possibly destroy) the channel */
99         int (* const hangup)(struct ast_channel *chan);
100
101         /*! Answer the line */
102         int (* const answer)(struct ast_channel *chan);
103
104         /*! Read a frame, in standard format */
105         struct ast_frame * (* const read)(struct ast_channel *chan);
106
107         /*! Write a frame, in standard format */
108         int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
109
110         /*! Display or transmit text */
111         int (* const send_text)(struct ast_channel *chan, char *text);
112
113         /*! Display or send an image */
114         int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
115
116         /*! Send HTML data */
117         int (* const send_html)(struct ast_channel *chan, int subclass, char *data, int len);
118
119         /*! Handle an exception, reading a frame */
120         struct ast_frame * (* const exception)(struct ast_channel *chan);
121
122         /*! Bridge two channels of the same type together */
123         int (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
124                              struct ast_frame **fo, struct ast_channel **rc);
125
126         /*! Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
127         int (* const indicate)(struct ast_channel *c, int condition);
128
129         /*! Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
130         int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
131
132         /*! Set a given option */
133         int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
134
135         /*! Query a given option */
136         int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
137
138         /*! Blind transfer other side */
139         int (* const transfer)(struct ast_channel *chan, char *newdest);
140
141         /*! Write a frame, in standard format */
142         int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
143
144         /*! Find bridged channel */
145         struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
146 };
147
148 /*! Main Channel structure associated with a channel. */
149 /*! 
150  * This is the side of it mostly used by the pbx and call management.
151  */
152 struct ast_channel {
153         /*! ASCII Description of channel name */
154         char name[AST_CHANNEL_NAME];            
155
156         /*! Technology */
157         const struct ast_channel_tech *tech;
158         /*! Private data used by the technology driver */
159         void *tech_pvt;
160
161         /*! Language requested */
162         char language[MAX_LANGUAGE];            
163         /*! Type of channel */
164         const char *type;                               
165         /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
166         int fds[AST_MAX_FDS];                   
167
168         /*! Default music class */
169         char musicclass[MAX_LANGUAGE];
170         /*! Music State*/
171         void *music_state;
172         /*! Current generator data if there is any */
173         void *generatordata;
174         /*! Current active data generator */
175         struct ast_generator *generator;
176
177         /*! Who are we bridged to, if we're bridged  Do not access directly,
178             use ast_bridged_channel(chan) */
179         struct ast_channel *_bridge;
180         /*! Channel that will masquerade as us */
181         struct ast_channel *masq;               
182         /*! Who we are masquerading as */
183         struct ast_channel *masqr;              
184         /*! Call Detail Record Flags */
185         int cdrflags;                                                                              
186         /*! Whether or not we have been hung up...  Do not set this value
187             directly, use ast_softhangup */
188         int _softhangup;                                
189         /*! Non-zero, set to actual time when channel is to be hung up */
190         time_t  whentohangup;
191         /*! If anyone is blocking, this is them */
192         pthread_t blocker;                      
193         /*! Lock, can be used to lock a channel for some operations */
194         ast_mutex_t lock;                       
195         /*! Procedure causing blocking */
196         const char *blockproc;                  
197
198         /*! Current application */
199         char *appl;                             
200         /*! Data passed to current application */
201         char *data;                             
202         
203         /*! Which fd had an event detected on */
204         int fdno;                               
205         /*! Schedule context */
206         struct sched_context *sched;            
207         /*! For streaming playback, the schedule ID */
208         int streamid;                           
209         /*! Stream itself. */
210         struct ast_filestream *stream;          
211         /*! For streaming playback, the schedule ID */
212         int vstreamid;                          
213         /*! Stream itself. */
214         struct ast_filestream *vstream;         
215         /*! Original writer format */
216         int oldwriteformat;                     
217         
218         /*! Timing fd */
219         int timingfd;
220         int (*timingfunc)(void *data);
221         void *timingdata;
222
223         /*! State of line -- Don't write directly, use ast_setstate */
224         int _state;                             
225         /*! Number of rings so far */
226         int rings;                              
227
228         /*! Kinds of data this channel can natively handle */
229         int nativeformats;                      
230         /*! Requested read format */
231         int readformat;                         
232         /*! Requested write format */
233         int writeformat;                        
234
235         struct ast_callerid cid;
236                 
237         /*! Current extension context */
238         char context[AST_MAX_EXTENSION];        
239         /*! Current non-macro context */
240         char macrocontext[AST_MAX_EXTENSION];   
241         /*! Current non-macro extension */
242         char macroexten[AST_MAX_EXTENSION];
243         /*! Current non-macro priority */
244         int macropriority;
245         /*! Current extension number */
246         char exten[AST_MAX_EXTENSION];          
247         /* Current extension priority */
248         int priority;                                           
249         /*! Any/all queued DTMF characters */
250         char dtmfq[AST_MAX_EXTENSION];          
251         /*! DTMF frame */
252         struct ast_frame dtmff;                 
253         /*! Private channel implementation details */
254         struct ast_channel_pvt *pvt;
255
256         /*! PBX private structure */
257         struct ast_pbx *pbx;
258         /*! Set BEFORE PBX is started to determine AMA flags */
259         int     amaflags;                       
260         /*! Account code for billing */
261         char    accountcode[20];                
262         /*! Call Detail Record */
263         struct ast_cdr *cdr;                    
264         /*! Whether or not ADSI is detected on CPE */
265         int     adsicpe;
266         /*! Where to forward to if asked to dial on this interface */
267         char call_forward[AST_MAX_EXTENSION];
268
269         /*! Tone zone */
270         struct tone_zone *zone;
271
272         /* Channel monitoring */
273         struct ast_channel_monitor *monitor;
274
275         /*! Track the read/written samples for monitor use */
276         unsigned long insmpl;
277         unsigned long outsmpl;
278
279         /* Frames in/out counters */
280         unsigned int fin;
281         unsigned int fout;
282
283         /* Unique Channel Identifier */
284         char uniqueid[32];
285
286         /* Why is the channel hanged up */
287         int hangupcause;
288         
289         /* A linked list for variables */
290         struct varshead varshead;
291
292         unsigned int callgroup;
293         unsigned int pickupgroup;
294
295         /*! channel flags of AST_FLAG_ type */
296         unsigned int flags;
297         
298         struct ast_frame *readq;
299         int alertpipe[2];
300         /*! Write translation path */
301         struct ast_trans_pvt *writetrans;
302         /*! Read translation path */
303         struct ast_trans_pvt *readtrans;
304         /*! Raw read format */
305         int rawreadformat;
306         /*! Raw write format */
307         int rawwriteformat;
308
309         /*! For easy linking */
310         struct ast_channel *next;
311
312 };
313
314 #define AST_FLAG_DIGITAL        (1 << 0)        /* if the call is a digital ISDN call */
315 #define AST_FLAG_DEFER_DTMF     (1 << 1)        /* if dtmf should be deferred */
316 #define AST_FLAG_WRITE_INT      (1 << 2)        /* if write should be interrupt generator */
317 #define AST_FLAG_BLOCKING       (1 << 3)        /* if we are blocking */
318 #define AST_FLAG_ZOMBIE         (1 << 4)        /* if we are a zombie */
319 #define AST_FLAG_EXCEPTION      (1 << 5)        /* if there is a pending exception */
320 #define AST_FLAG_MOH        (1 << 6)    /* XXX anthm promises me this will disappear XXX listening to moh */
321
322 #define AST_FEATURE_PLAY_WARNING        (1 << 0)
323 #define AST_FEATURE_REDIRECT            (1 << 1)
324 #define AST_FEATURE_DISCONNECT          (1 << 2)
325 #define AST_FEATURE_ATXFER                      (1 << 3)
326 #define AST_FEATURE_AUTOMON                     (1 << 4)
327
328 #define AST_FEATURE_FLAG_NEEDSDTMF              (1 << 0)
329
330 struct ast_bridge_config {
331         struct ast_flags features_caller;
332         struct ast_flags features_callee;
333         long timelimit;
334         long play_warning;
335         long warning_freq;
336         char *warning_sound;
337         char *end_sound;
338         char *start_sound;
339         int firstpass;
340         unsigned int flags;
341 };
342
343 struct chanmon;
344
345 #define LOAD_OH(oh) {   \
346         oh.context = context; \
347         oh.exten = exten; \
348         oh.priority = priority; \
349         oh.cid_num = cid_num; \
350         oh.cid_name = cid_name; \
351         oh.variable = variable; \
352         oh.account = account; \
353
354
355 struct outgoing_helper {
356         const char *context;
357         const char *exten;
358         int priority;
359         const char *cid_num;
360         const char *cid_name;
361         const char *variable;
362         const char *account;
363 };
364
365 #define AST_CDR_TRANSFER        (1 << 0)
366 #define AST_CDR_FORWARD         (1 << 1)
367 #define AST_CDR_CALLWAIT        (1 << 2)
368 #define AST_CDR_CONFERENCE      (1 << 3)
369
370 #define AST_ADSI_UNKNOWN        (0)
371 #define AST_ADSI_AVAILABLE      (1)
372 #define AST_ADSI_UNAVAILABLE    (2)
373 #define AST_ADSI_OFFHOOKONLY    (3)
374
375 #define AST_SOFTHANGUP_DEV                      (1 << 0)        /* Soft hangup by device */
376 #define AST_SOFTHANGUP_ASYNCGOTO        (1 << 1)        /* Soft hangup for async goto */
377 #define AST_SOFTHANGUP_SHUTDOWN         (1 << 2)
378 #define AST_SOFTHANGUP_TIMEOUT          (1 << 3)
379 #define AST_SOFTHANGUP_APPUNLOAD        (1 << 4)
380 #define AST_SOFTHANGUP_EXPLICIT         (1 << 5)
381
382 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
383 /*! Channel is down and available */
384 #define AST_STATE_DOWN          0               
385 /*! Channel is down, but reserved */
386 #define AST_STATE_RESERVED      1               
387 /*! Channel is off hook */
388 #define AST_STATE_OFFHOOK       2               
389 /*! Digits (or equivalent) have been dialed */
390 #define AST_STATE_DIALING       3               
391 /*! Line is ringing */
392 #define AST_STATE_RING          4               
393 /*! Remote end is ringing */
394 #define AST_STATE_RINGING       5               
395 /*! Line is up */
396 #define AST_STATE_UP            6               
397 /*! Line is busy */
398 #define AST_STATE_BUSY          7               
399 /*! Digits (or equivalent) have been dialed while offhook */
400 #define AST_STATE_DIALING_OFFHOOK       8
401 /*! Channel has detected an incoming call and is waiting for ring */
402 #define AST_STATE_PRERING       9
403
404 /* Bits 16-32 of state are reserved for flags */
405 /*! Do not transmit voice data */
406 #define AST_STATE_MUTE          (1 << 16)       
407
408 /*! Device is valid but channel didn't know state */
409 #define AST_DEVICE_UNKNOWN      0
410 /*! Device is not used */
411 #define AST_DEVICE_NOT_INUSE    1
412 /*! Device is in use */
413 #define AST_DEVICE_INUSE        2
414 /*! Device is busy */
415 #define AST_DEVICE_BUSY         3
416 /*! Device is invalid */
417 #define AST_DEVICE_INVALID      4
418 /*! Device is unavailable */
419 #define AST_DEVICE_UNAVAILABLE  5
420
421 /*! Create a channel structure */
422 /*! Returns NULL on failure to allocate */
423 struct ast_channel *ast_channel_alloc(int needalertpipe);
424
425 /*! Queue an outgoing frame */
426 int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
427
428 int ast_queue_hangup(struct ast_channel *chan);
429
430 int ast_queue_control(struct ast_channel *chan, int control);
431
432 /*! Change the state of a channel */
433 int ast_setstate(struct ast_channel *chan, int state);
434
435 void ast_change_name(struct ast_channel *chan, char *newname);
436
437 /*! Free a channel structure */
438 void  ast_channel_free(struct ast_channel *);
439
440 /*! Requests a channel */
441 /*! 
442  * \param type type of channel to request
443  * \param format requested channel format
444  * \param data data to pass to the channel requester
445  * Request a channel of a given type, with data as optional information used 
446  * by the low level module
447  * Returns an ast_channel on success, NULL on failure.
448  */
449 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
450
451 /*! Search the Channels by Name */
452 /*!
453  * \param device like a dialstring
454  * Search the Device in active channels by compare the channelname against 
455  * the devicename. Compared are only the first chars to the first '-' char.
456  * Returns an AST_DEVICE_UNKNOWN if no channel found or
457  * AST_DEVICE_INUSE if a channel is found
458  */
459 int ast_parse_device_state(char *device);
460
461 /*! Asks a channel for device state */
462 /*!
463  * \param device like a dialstring
464  * Asks a channel for device state, data is  normaly a number from dialstring
465  * used by the low level module
466  * Trys the channel devicestate callback if not supported search in the
467  * active channels list for the device.
468  * Returns an AST_DEVICE_??? state -1 on failure
469  */
470 int ast_device_state(char *device);
471
472 /*!
473  * \param type type of channel to request
474  * \param format requested channel format
475  * \param data data to pass to the channel requester
476  * \param timeout maximum amount of time to wait for an answer
477  * \param why unsuccessful (if unsuceessful)
478  * Request a channel of a given type, with data as optional information used 
479  * by the low level module and attempt to place a call on it
480  * Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
481  * to know if the call was answered or not.
482  */
483 struct ast_channel *ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname);
484
485 struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname, struct outgoing_helper *oh);
486
487 /*! Register a channel technology */
488 /*! 
489  * \param tech Structure defining channel technology or "type"
490  * Called by a channel module to register the kind of channels it supports.
491  * Returns 0 on success, -1 on failure.
492  */
493 int ast_channel_register(const struct ast_channel_tech *tech);
494
495 /*! Unregister a channel technology */
496 /*
497  * \param tech Structure defining channel technology or "type" that was previously registered
498  * No return value.
499  */
500 void ast_channel_unregister(const struct ast_channel_tech *tech);
501
502 /*! Hang up a channel  */
503 /*! 
504  * \param chan channel to hang up
505  * This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
506  * performs all stream stopping, etc, on the channel that needs to end.
507  * chan is no longer valid after this call.
508  * Returns 0 on success, -1 on failure.
509  */
510 int ast_hangup(struct ast_channel *chan);
511
512 /*! Softly hangup up a channel */
513 /*! 
514  * \param chan channel to be soft-hung-up
515  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
516  * safely hangup a channel managed by another thread.
517  * Returns 0 regardless
518  */
519 int ast_softhangup(struct ast_channel *chan, int cause);
520 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
521
522 /*! Check to see if a channel is needing hang up */
523 /*! 
524  * \param chan channel on which to check for hang up
525  * This function determines if the channel is being requested to be hung up.
526  * Returns 0 if not, or 1 if hang up is requested (including time-out).
527  */
528 int ast_check_hangup(struct ast_channel *chan);
529
530 /*! Set when to hang a channel up */
531 /*! 
532  * \param chan channel on which to check for hang up
533  * \param offset offset in seconds from current time of when to hang up
534  * This function sets the absolute time out on a channel (when to hang up).
535  */
536 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
537
538 /*! Answer a ringing call */
539 /*!
540  * \param chan channel to answer
541  * This function answers a channel and handles all necessary call
542  * setup functions.
543  * Returns 0 on success, -1 on failure
544  */
545 int ast_answer(struct ast_channel *chan);
546
547 /*! Make a call */
548 /*! 
549  * \param chan which channel to make the call on
550  * \param addr destination of the call
551  * \param timeout time to wait on for connect
552  * Place a call, take no longer than timeout ms.  Returns -1 on failure, 
553    0 on not enough time (does not auto matically stop ringing), and  
554    the number of seconds the connect took otherwise.
555    Returns 0 on success, -1 on failure
556    */
557 int ast_call(struct ast_channel *chan, char *addr, int timeout);
558
559 /*! Indicates condition of channel */
560 /*! 
561  * \param chan channel to change the indication
562  * \param condition which condition to indicate on the channel
563  * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
564  * Returns 0 on success, -1 on failure
565  */
566 int ast_indicate(struct ast_channel *chan, int condition);
567
568 /* Misc stuff */
569
570 /*! Wait for input on a channel */
571 /*! 
572  * \param chan channel to wait on
573  * \param ms length of time to wait on the channel
574  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
575   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
576 int ast_waitfor(struct ast_channel *chan, int ms);
577
578 /*! Wait for a specied amount of time, looking for hangups */
579 /*!
580  * \param chan channel to wait for
581  * \param ms length of time in milliseconds to sleep
582  * Waits for a specified amount of time, servicing the channel as required.
583  * returns -1 on hangup, otherwise 0.
584  */
585 int ast_safe_sleep(struct ast_channel *chan, int ms);
586
587 /*! Wait for a specied amount of time, looking for hangups and a condition argument */
588 /*!
589  * \param chan channel to wait for
590  * \param ms length of time in milliseconds to sleep
591  * \param cond a function pointer for testing continue condition
592  * \param data argument to be passed to the condition test function
593  * Waits for a specified amount of time, servicing the channel as required. If cond
594  * returns 0, this function returns.
595  * returns -1 on hangup, otherwise 0.
596  */
597 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
598
599 /*! Waits for activity on a group of channels */
600 /*! 
601  * \param chan an array of pointers to channels
602  * \param n number of channels that are to be waited upon
603  * \param fds an array of fds to wait upon
604  * \param nfds the number of fds to wait upon
605  * \param exception exception flag
606  * \param outfd fd that had activity on it
607  * \param ms how long the wait was
608  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
609    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
610    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
611    will be -1 */
612 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
613
614 /*! Waits for input on a group of channels */
615 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
616    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
617 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
618
619 /*! Waits for input on an fd */
620 /*! This version works on fd's only.  Be careful with it. */
621 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
622
623
624 /*! Reads a frame */
625 /*!
626  * \param chan channel to read a frame from
627  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
628    best just stop reading frames and assume the channel has been
629    disconnected. */
630 struct ast_frame *ast_read(struct ast_channel *chan);
631
632 /*! Write a frame to a channel */
633 /*!
634  * \param chan destination channel of the frame
635  * \param frame frame that will be written
636  * This function writes the given frame to the indicated channel.
637  * It returns 0 on success, -1 on failure.
638  */
639 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
640
641 /*! Write video frame to a channel */
642 /*!
643  * \param chan destination channel of the frame
644  * \param frame frame that will be written
645  * This function writes the given frame to the indicated channel.
646  * It returns 1 on success, 0 if not implemented, and -1 on failure.
647  */
648 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
649
650 /* Send empty audio to prime a channel driver */
651 int ast_prod(struct ast_channel *chan);
652
653 /*! Sets read format on channel chan */
654 /*! 
655  * \param chan channel to change
656  * \param format format to change to
657  * Set read format for channel to whichever component of "format" is best. 
658  * Returns 0 on success, -1 on failure
659  */
660 int ast_set_read_format(struct ast_channel *chan, int format);
661
662 /*! Sets write format on channel chan */
663 /*! 
664  * \param chan channel to change
665  * \param format new format for writing
666  * Set write format for channel to whichever compoent of "format" is best. 
667  * Returns 0 on success, -1 on failure
668  */
669 int ast_set_write_format(struct ast_channel *chan, int format);
670
671 /*! Sends text to a channel */
672 /*! 
673  * \param chan channel to act upon
674  * \param text string of text to send on the channel
675  * Write text to a display on a channel
676  * Returns 0 on success, -1 on failure
677  */
678 int ast_sendtext(struct ast_channel *chan, char *text);
679
680 /*! Receives a text character from a channel */
681 /*! 
682  * \param chan channel to act upon
683  * \param timeout timeout in milliseconds (0 for infinite wait)
684  * Read a char of text from a channel
685  * Returns 0 on success, -1 on failure
686  */
687
688 int ast_senddigit(struct ast_channel *chan, char digit);
689
690 int ast_recvchar(struct ast_channel *chan, int timeout);
691
692 /*! Browse channels in use */
693 /*! 
694  * \param prev where you want to start in the channel list
695  * Browse the channels currently in use 
696  * Returns the next channel in the list, NULL on end.
697  * If it returns a channel, that channel *has been locked*!
698  */
699 struct ast_channel *ast_channel_walk_locked(struct ast_channel *prev);
700
701 /*! Get channel by name (locks channel) */
702 struct ast_channel *ast_get_channel_by_name_locked(char *channame);
703
704 /*! Waits for a digit */
705 /*! 
706  * \param c channel to wait for a digit on
707  * \param ms how many milliseconds to wait
708  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
709 char ast_waitfordigit(struct ast_channel *c, int ms);
710
711 /* Same as above with audio fd for outputing read audio and ctrlfd to monitor for
712    reading. Returns 1 if ctrlfd becomes available */
713 char ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
714
715 /*! Reads multiple digits */
716 /*! 
717  * \param c channel to read from
718  * \param s string to read in to.  Must be at least the size of your length
719  * \param len how many digits to read (maximum)
720  * \param timeout how long to timeout between digits
721  * \param rtimeout timeout to wait on the first digit
722  * \param enders digits to end the string
723  * Read in a digit string "s", max length "len", maximum timeout between 
724    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
725    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
726    a timeout, any digits that were read before the timeout will still be available in s.  
727    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
728 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
729 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
730
731 /*! Report DTMF on channel 0 */
732 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
733 /*! Report DTMF on channel 1 */
734 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
735 /*! Return all voice frames on channel 0 */
736 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
737 /*! Return all voice frames on channel 1 */
738 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
739 /*! Ignore all signal frames except NULL */
740 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
741
742
743 /*! Makes two channel formats compatible */
744 /*! 
745  * \param c0 first channel to make compatible
746  * \param c1 other channel to make compatible
747  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
748    and -1 if it could not be done */
749 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
750
751 /*! Bridge two channels together */
752 /*! 
753  * \param c0 first channel to bridge
754  * \param c1 second channel to bridge
755  * \param flags for the channels
756  * \param fo destination frame(?)
757  * \param rc destination channel(?)
758  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
759    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
760 /* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
761 int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
762
763 /*! Weird function made for call transfers */
764 /*! 
765  * \param original channel to make a copy of
766  * \param clone copy of the original channel
767  * This is a very strange and freaky function used primarily for transfer.  Suppose that
768    "original" and "clone" are two channels in random situations.  This function takes
769    the guts out of "clone" and puts them into the "original" channel, then alerts the
770    channel driver of the change, asking it to fixup any private information (like the
771    p->owner pointer) that is affected by the change.  The physical layer of the original
772    channel is hung up.  */
773 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
774
775 /*! Gives the string form of a given state */
776 /*! 
777  * \param state state to get the name of
778  * Give a name to a state 
779  * Pretty self explanatory.
780  * Returns the text form of the binary state given
781  */
782 char *ast_state2str(int state);
783
784 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
785    low level channel.  See frame.h for options.  Note that many channel drivers may support
786    none or a subset of those features, and you should not count on this if you want your
787    asterisk application to be portable.  They're mainly useful for tweaking performance */
788
789 /*! Sets an option on a channel */
790 /*! 
791  * \param channel channel to set options on
792  * \param option option to change
793  * \param data data specific to option
794  * \param datalen length of the data
795  * \param block blocking or not
796  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
797  * Returns 0 on success and -1 on failure
798  */
799 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
800
801 /*! Checks the value of an option */
802 /*! 
803  * Query the value of an option, optionally blocking until a reply is received
804  * Works similarly to setoption except only reads the options.
805  */
806 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
807
808 /*! Checks for HTML support on a channel */
809 /*! Returns 0 if channel does not support HTML or non-zero if it does */
810 int ast_channel_supports_html(struct ast_channel *channel);
811
812 /*! Sends HTML on given channel */
813 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
814 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, char *data, int datalen);
815
816 /*! Sends a URL on a given link */
817 /*! Send URL on link.  Returns 0 on success or -1 on failure */
818 int ast_channel_sendurl(struct ast_channel *channel, char *url);
819
820 /*! Defers DTMF */
821 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
822    non-zero if channel was already DTMF-deferred or 0 if channel is just now
823    being DTMF-deferred */
824 int ast_channel_defer_dtmf(struct ast_channel *chan);
825
826 /*! Undeos a defer */
827 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
828 void ast_channel_undefer_dtmf(struct ast_channel *chan);
829
830 /*! Initiate system shutdown -- prevents new channels from being allocated.
831     If "hangup" is non-zero, all existing channels will receive soft
832      hangups */
833 void ast_begin_shutdown(int hangup);
834
835 /*! Cancels an existing shutdown and returns to normal operation */
836 void ast_cancel_shutdown(void);
837
838 /*! Returns number of active/allocated channels */
839 int ast_active_channels(void);
840
841 /*! Returns non-zero if Asterisk is being shut down */
842 int ast_shutting_down(void);
843
844 /*! Activate a given generator */
845 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
846
847 /*! Deactive an active generator */
848 void ast_deactivate_generator(struct ast_channel *chan);
849
850 void ast_set_callerid(struct ast_channel *chan, const char *cidnum, const char *cidname, const char *ani);
851
852 /*! Start a tone going */
853 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
854 /*! Stop a tone from playing */
855 void ast_tonepair_stop(struct ast_channel *chan);
856 /*! Play a tone pair for a given amount of time */
857 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
858
859 /*! Automatically service a channel for us... */
860 int ast_autoservice_start(struct ast_channel *chan);
861
862 /*! Stop servicing a channel for us...  Returns -1 on error or if channel has been hungup */
863 int ast_autoservice_stop(struct ast_channel *chan);
864
865 /* If built with zaptel optimizations, force a scheduled expiration on the
866    timer fd, at which point we call the callback function / data */
867 int ast_settimeout(struct ast_channel *c, int samples, int (*func)(void *data), void *data);
868
869 /* Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
870    and 1 if supported and requested */
871 int ast_transfer(struct ast_channel *chan, char *dest);
872
873 int ast_do_masquerade(struct ast_channel *chan);
874
875 /* Find bridged channel */
876 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
877
878 /*!
879   \brief Inherits channel variable from parent to child channel
880   \param parent Parent channel
881   \param child Child channel
882
883   Scans all channel variables in the parent channel, looking for those
884   that should be copied into the child channel.
885   Variables whose names begin with a single '_' are copied into the
886   child channel with the prefix removed.
887   Variables whose names begin with '__' are copied into the child
888   channel with their names unchanged.
889 */
890 void ast_channel_inherit_variables(const struct ast_channel *parent, struct ast_channel *child);
891
892 /* Misc. functions below */
893
894 /* Helper function for migrating select to poll */
895 static inline int ast_fdisset(struct pollfd *pfds, int fd, int max, int *start)
896 {
897         int x;
898         for (x=start ? *start : 0;x<max;x++)
899                 if (pfds[x].fd == fd) {
900                         if (start) {
901                                 if (x==*start)
902                                         (*start)++;
903                         }
904                         return pfds[x].revents;
905                 }
906         return 0;
907 }
908
909 #ifdef SOLARIS
910 static inline void timersub(struct timeval *tvend, struct timeval *tvstart, struct timeval *tvdiff)
911 {
912         tvdiff->tv_sec = tvend->tv_sec - tvstart->tv_sec;
913         tvdiff->tv_usec = tvend->tv_usec - tvstart->tv_usec;
914         if (tvdiff->tv_usec < 0) {
915                 tvdiff->tv_sec --;
916                 tvdiff->tv_usec += 1000000;
917         }
918
919 }
920 #endif
921
922 /*! Waits for activity on a group of channels */
923 /*! 
924  * \param nfds the maximum number of file descriptors in the sets
925  * \param rfds file descriptors to check for read availability
926  * \param wfds file descriptors to check for write availability
927  * \param efds file descriptors to check for exceptions (OOB data)
928  * \param tvp timeout while waiting for events
929  * This is the same as a standard select(), except it guarantees the
930  * behaviour where the passed struct timeval is updated with how much
931  * time was not slept while waiting for the specified events
932  */
933 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
934 {
935 #ifdef __linux__
936         return select(nfds, rfds, wfds, efds, tvp);
937 #else
938         if (tvp) {
939                 struct timeval tv, tvstart, tvend, tvlen;
940                 int res;
941
942                 tv = *tvp;
943                 gettimeofday(&tvstart, NULL);
944                 res = select(nfds, rfds, wfds, efds, tvp);
945                 gettimeofday(&tvend, NULL);
946                 timersub(&tvend, &tvstart, &tvlen);
947                 timersub(&tv, &tvlen, tvp);
948                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
949                         tvp->tv_sec = 0;
950                         tvp->tv_usec = 0;
951                 }
952                 return res;
953         }
954         else
955                 return select(nfds, rfds, wfds, efds, NULL);
956 #endif
957 }
958
959 #if !defined(ast_strdupa) && defined(__GNUC__)
960 # define ast_strdupa(s)                                                                 \
961   (__extension__                                                                                \
962     ({                                                                                                  \
963       __const char *__old = (s);                                                \
964       size_t __len = strlen (__old) + 1;                                \
965       char *__new = (char *) __builtin_alloca (__len);  \
966       (char *) memcpy (__new, __old, __len);                    \
967     }))
968 #endif
969
970 #ifdef DO_CRASH
971 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
972 #else
973 #define CRASH do { } while(0)
974 #endif
975
976 #define CHECK_BLOCKING(c) {      \
977                                                         if (ast_test_flag(c, AST_FLAG_BLOCKING)) {\
978                                                                 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); \
979                                                                 CRASH; \
980                                                         } else { \
981                                                                 (c)->blocker = pthread_self(); \
982                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
983                                                                         ast_set_flag(c, AST_FLAG_BLOCKING); \
984                                                                         } }
985
986 extern ast_group_t ast_get_group(char *s);
987 /* print call- and pickup groups into buffer */
988 extern char *ast_print_group(char *buf, int buflen, ast_group_t group);
989
990
991 #if defined(__cplusplus) || defined(c_plusplus)
992 }
993 #endif
994
995 #endif