Version 0.1.8 from FTP
[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, Mark Spencer
7  *
8  * Mark Spencer <markster@linux-support.net>
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 <setjmp.h>
20 #include <pthread.h>
21
22 #if defined(__cplusplus) || defined(c_plusplus)
23 extern "C" {
24 #endif
25
26 #include <pthread.h>
27
28 #ifdef DEBUG_THREADS
29
30 #define TRIES 500
31
32 #include <errno.h>
33 #include <string.h>
34 #include <stdio.h>
35 #include <unistd.h>
36
37 struct mutex_info {
38         pthread_mutex_t *mutex;
39         char *file;
40         int lineno;
41         char *func;
42         struct mutex_info *next;
43 };
44
45 static inline int __ast_pthread_mutex_lock(char *filename, int lineno, char *func, pthread_mutex_t *t) {
46         int res;
47         int tries = TRIES;
48         do {
49                 res = pthread_mutex_trylock(t);
50                 /* If we can't run, yield */
51                 if (res) {
52                         sched_yield();
53                         usleep(1);
54                 }
55         } while(res && tries--);
56         if (res) {
57                 fprintf(stderr, "%s line %d (%s): Error obtaining mutex: %s\n", 
58                                 filename, lineno, func, strerror(res));
59                 res = pthread_mutex_lock(t);
60                 fprintf(stderr, "%s line %d (%s): Got it eventually...\n",
61                                 filename, lineno, func);
62         }
63         return res;
64 }
65
66 #define ast_pthread_mutex_lock(a) __ast_pthread_mutex_lock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a)
67
68 static inline int __ast_pthread_mutex_unlock(char *filename, int lineno, char *func, pthread_mutex_t *t) {
69         int res;
70         res = pthread_mutex_unlock(t);
71         if (res) 
72                 fprintf(stderr, "%s line %d (%s): Error releasing mutex: %s\n", 
73                                 filename, lineno, func, strerror(res));
74         return res;
75 }
76 #define ast_pthread_mutex_unlock(a) __ast_pthread_mutex_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a)
77 #else
78 #define ast_pthread_mutex_lock pthread_mutex_lock
79 #define ast_pthread_mutex_unlock pthread_mutex_unlock
80 #endif
81
82 #define AST_CHANNEL_NAME 80
83 #define AST_CHANNEL_MAX_STACK 32
84
85 #define MAX_LANGUAGE 20
86
87 /* Max length an extension can be (unique) is this number */
88 #define AST_MAX_EXTENSION 80
89
90 #define AST_MAX_FDS 4
91
92 struct ast_channel {
93         char name[AST_CHANNEL_NAME];            /* ASCII Description of channel name */
94         char language[MAX_LANGUAGE];            /* Language requested */
95         char *type;                             /* Type of channel */
96         int fds[AST_MAX_FDS];                   /* File descriptor for channel -- Drivers will poll
97                                                                    on these file descriptors, so at least one must be
98                                                                    non -1.  */
99                                                    
100         struct ast_channel *bridge;                     /* Who are we bridged to, if we're bridged */
101         struct ast_channel *masq;                       /* Channel that will masquerade as us */
102         struct ast_channel *masqr;                      /* Who we are masquerading as */
103         int cdrflags;                                           /* Call Detail Record Flags */                                             
104
105         int blocking;                                           /* Whether or not we're blocking */
106         int softhangup;                                         /* Whether or not we have been hung up */
107         int zombie;                                                     /* Non-zero if this is a zombie channel */      
108         pthread_t blocker;                                      /* If anyone is blocking, this is them */
109         pthread_mutex_t lock;                           /* Lock, can be used to lock a channel for some operations */
110         char *blockproc;                                        /* Procedure causing blocking */
111         
112         char *appl;                                                     /* Current application */
113         char *data;                                                     /* Data passed to current application */
114         
115         int exception;                                          /* Has an exception been detected */
116         int fdno;                                                       /* Which fd had an event detected on */
117         struct sched_context *sched;            /* Schedule context */
118
119         int streamid;                                   /* For streaming playback, the schedule ID */
120         struct ast_filestream *stream;  /* Stream itself. */
121         int oldwriteformat;                             /* Original writer format */
122
123         int state;                              /* State of line */
124         int rings;                              /* Number of rings so far */
125         int stack;                              /* Current level of application */
126
127         int nativeformats;              /* Kinds of data this channel can
128                                                            natively handle */
129         int readformat;                 /* Requested read format */
130         int writeformat;                /* Requested write format */
131         
132         char *dnid;                             /* Malloc'd Dialed Number Identifier */
133         char *callerid;                 /* Malloc'd Caller ID */
134         
135         char context[AST_MAX_EXTENSION];        /* Current extension context */
136         char exten[AST_MAX_EXTENSION];          /* Current extension number */
137         int priority;                                           /* Current extension priority */
138         void *app[AST_CHANNEL_MAX_STACK];       /* Application information -- see assigned numbers */
139         struct ast_channel_pvt *pvt;
140                                                 /* Private channel implementation details */
141         jmp_buf jmp[AST_CHANNEL_MAX_STACK];             /* Jump buffer used for returning from applications */
142         struct ast_pbx *pbx;
143         struct ast_channel *next;               /* For easy linking */
144 };
145
146
147 #define AST_CDR_TRANSFER        (1 << 0)
148 #define AST_CDR_FORWARD         (1 << 1)
149 #define AST_CDR_CALLWAIT        (1 << 2)
150 #define AST_CDR_CONFERENCE      (1 << 3)
151
152 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
153
154 #define AST_STATE_DOWN          0               /* Channel is down and available */
155 #define AST_STATE_RESERVED      1               /* Channel is down, but reserved */
156 #define AST_STATE_OFFHOOK       2               /* Channel is off hook */
157 #define AST_STATE_DIALING       3               /* Digits (or equivalent) have been dialed */
158 #define AST_STATE_RING          4               /* Line is ringing */
159 #define AST_STATE_RINGING       5               /* Remote end is ringing */
160 #define AST_STATE_UP            6               /* Line is up */
161 #define AST_STATE_BUSY          7               /* Line is busy */
162
163 /* Bits 16-32 of state are reserved for flags */
164
165 #define AST_STATE_MUTE          (1 << 16)       /* Do not transmit voice data */
166
167 /* Request a channel of a given type, with data as optional information used
168    by the low level module */
169 struct ast_channel *ast_request(char *type, int format, void *data);
170
171 /* Called by a channel module to register the kind of channels it supports.
172    It supplies a brief type, a longer, but still short description, and a
173    routine that creates a channel */
174 int ast_channel_register(char *type, char *description, int capabilities, 
175                         struct ast_channel* (*requester)(char *type, int format, void *data));
176
177 /* Unregister a channel class */
178 void ast_channel_unregister(char *type);
179
180 /* Hang up a channel -- chan is no longer valid after this call! */
181 int ast_hangup(struct ast_channel *chan);
182
183 /* Softly hangup up a channel -- call the protocol layer, but don't
184    destroy the channel structure (use this if you are trying to
185    safely hangup a channel managed by another thread. */
186 int ast_softhangup(struct ast_channel *chan);
187
188 /* Answer a ringing call */
189 int ast_answer(struct ast_channel *chan);
190
191 /* Place a call, take no longer than timeout ms.  Returns -1 on failure, 
192    0 on not enough time (does not auto matically stop ringing), and  
193    the number of seconds the connect took otherwise.  */
194 int ast_call(struct ast_channel *chan, char *addr, int timeout);
195
196 /* Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel */
197 int ast_indicate(struct ast_channel *chan, int condition);
198
199 /* Misc stuff */
200
201 /* Wait for input on a channel for a given # of milliseconds (<0 for indefinite).  
202   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
203 int ast_waitfor(struct ast_channel *chan, int ms);
204
205 /* Wait for input on an array of channels for a given # of milliseconds. Return channel
206    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
207
208 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
209
210 /* This version works on fd's only.  Be careful with it. */
211 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
212
213 /* Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
214    best just stop reading frames and assume the channel has been
215    disconnected. */
216 struct ast_frame *ast_read(struct ast_channel *chan);
217
218 /* Write a frame to a channel */
219 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
220
221 /* Set read format for channelto whichever component of "format" is best. */
222 int ast_set_read_format(struct ast_channel *chan, int format);
223
224 /* Set write format for channel to whichever compoent of "format" is best. */
225 int ast_set_write_format(struct ast_channel *chan, int format);
226
227 /* Write text to a display on a channel */
228 int ast_sendtext(struct ast_channel *chan, char *text);
229
230 /* Browse the channels currently in use */
231 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
232
233 /* Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
234 char ast_waitfordigit(struct ast_channel *c, int ms);
235
236 /* Read in a digit string "s", max length "len", maximum timeout between 
237    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
238    for the first digit */
239 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
240
241 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                /* Report DTMF on channel 0 */
242 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                /* Report DTMF on channel 1 */
243 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                /* Return all voice frames on channel 0 */
244 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                /* Return all voice frames on channel 1 */
245 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                /* Ignore all signal frames except NULL */
246
247
248 /* Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
249    and -1 if it could not be done */
250 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
251
252 /* Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
253    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
254 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
255
256 /* This is a very strange and freaky function used primarily for transfer.  Suppose that
257    "original" and "clone" are two channels in random situations.  This function takes
258    the guts out of "clone" and puts them into the "original" channel, then alerts the
259    channel driver of the change, asking it to fixup any private information (like the
260    p->owner pointer) that is affected by the change.  The physical layer of the original
261    channel is hung up.  */
262 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
263
264 /* Give a name to a state */
265 char *ast_state2str(int state);
266
267 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
268    low level channel.  See frame.h for options.  Note that many channel drivers may support
269    none or a subset of those features, and you should not count on this if you want your
270    asterisk application to be portable.  They're mainly useful for tweaking performance */
271
272 /* Set an option on a channel (see frame.h), optionally blocking awaiting the reply */
273 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
274
275 /* Query the value of an option, optionally blocking until a reply is received */
276 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
277
278 #ifdef DO_CRASH
279 #define CRASH do { *((int *)0) = 0; } while(0)
280 #else
281 #define CRASH do { } while(0)
282 #endif
283
284 #define CHECK_BLOCKING(c) {      \
285                                                         if ((c)->blocking) {\
286                                                                 ast_log(LOG_WARNING, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", pthread_self(), (c)->name, (c)->blocker, (c)->blockproc); \
287                                                                 CRASH; \
288                                                         } else { \
289                                                                 (c)->blocker = pthread_self(); \
290                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
291                                                                         c->blocking = -1; \
292                                                                         } }
293
294 #if defined(__cplusplus) || defined(c_plusplus)
295 }
296 #endif
297
298
299 #endif