Version 0.1.7 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 #define AST_CHANNEL_NAME 80
29 #define AST_CHANNEL_MAX_STACK 32
30
31 #define MAX_LANGUAGE 20
32
33 /* Max length an extension can be (unique) is this number */
34 #define AST_MAX_EXTENSION 80
35
36 struct ast_channel {
37         char name[AST_CHANNEL_NAME];            /* ASCII Description of channel name */
38         char language[MAX_LANGUAGE];            /* Language requested */
39         char *type;                             /* Type of channel */
40         int fd;                                 /* File descriptor for channel -- all must have
41                                                    a file descriptor! */
42                                                    
43         int blocking;                                           /* Whether or not we're blocking */
44         pthread_t blocker;                                      /* If anyone is blocking, this is them */
45         pthread_mutex_t lock;                           /* Lock, can be used to lock a channel for some operations */
46         char *blockproc;                                        /* Procedure causing blocking */
47         
48         char *appl;                                                     /* Current application */
49         char *data;                                                     /* Data passed to current application */
50         
51         int exception;                                          /* Has an exception been detected */
52         struct sched_context *sched;            /* Schedule context */
53
54         int streamid;                                   /* For streaming playback, the schedule ID */
55         struct ast_filestream *stream;  /* Stream itself. */
56         int oldwriteformat;                             /* Original writer format */
57
58         int state;                              /* State of line */
59         int rings;                              /* Number of rings so far */
60         int stack;                              /* Current level of application */
61
62         int nativeformats;              /* Kinds of data this channel can
63                                                            natively handle */
64         int readformat;                 /* Requested read format */
65         int writeformat;                /* Requested write format */
66         
67         char *dnid;                             /* Malloc'd Dialed Number Identifier */
68         char *callerid;                 /* Malloc'd Caller ID */
69         
70         char context[AST_MAX_EXTENSION];        /* Current extension context */
71         char exten[AST_MAX_EXTENSION];          /* Current extension number */
72         int priority;                                           /* Current extension priority */
73         void *app[AST_CHANNEL_MAX_STACK];       /* Application information -- see assigned numbers */
74         struct ast_channel_pvt *pvt;
75                                                 /* Private channel implementation details */
76         jmp_buf jmp[AST_CHANNEL_MAX_STACK];             /* Jump buffer used for returning from applications */
77         struct ast_pbx *pbx;
78         struct ast_channel *next;               /* For easy linking */
79 };
80
81
82 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
83
84 #define AST_STATE_DOWN          0               /* Channel is down and available */
85 #define AST_STATE_RESERVED      1               /* Channel is down, but reserved */
86 #define AST_STATE_OFFHOOK       2               /* Channel is off hook */
87 #define AST_STATE_DIALING       3               /* Digits (or equivalent) have been dialed */
88 #define AST_STATE_RING          4               /* Line is ringing */
89 #define AST_STATE_RINGING       5               /* Remote end is ringing */
90 #define AST_STATE_UP            6               /* Line is up */
91 #define AST_STATE_BUSY          7               /* Line is busy */
92
93 /* Bits 16-32 of state are reserved for flags */
94
95 #define AST_STATE_MUTE          (1 << 16)       /* Do not transmit voice data */
96
97 /* Request a channel of a given type, with data as optional information used
98    by the low level module */
99 struct ast_channel *ast_request(char *type, int format, void *data);
100
101 /* Called by a channel module to register the kind of channels it supports.
102    It supplies a brief type, a longer, but still short description, and a
103    routine that creates a channel */
104 int ast_channel_register(char *type, char *description, int capabilities, 
105                         struct ast_channel* (*requester)(char *type, int format, void *data));
106
107 /* Unregister a channel class */
108 void ast_channel_unregister(char *type);
109
110 /* Hang up a channel -- chan is no longer valid after this call! */
111 int ast_hangup(struct ast_channel *chan);
112
113 /* Softly hangup up a channel -- call the protocol layer, but don't
114    destroy the channel structure (use this if you are trying to
115    safely hangup a channel managed by another thread. */
116 int ast_softhangup(struct ast_channel *chan);
117
118 /* Answer a ringing call */
119 int ast_answer(struct ast_channel *chan);
120
121 /* Place a call, take no longer than timeout ms.  Returns -1 on failure, 
122    0 on not enough time (does not auto matically stop ringing), and  
123    the number of seconds the connect took otherwise.  */
124 int ast_call(struct ast_channel *chan, char *addr, int timeout);
125
126 /* Misc stuff */
127
128 /* Wait for input on a channel for a given # of milliseconds (<0 for indefinite).  
129   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
130 int ast_waitfor(struct ast_channel *chan, int ms);
131
132 /* Wait for input on an array of channels for a given # of milliseconds. Return channel
133    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
134
135 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
136
137 /* This version works on fd's only.  Be careful with it. */
138 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
139
140 /* Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
141    best just stop reading frames and assume the channel has been
142    disconnected. */
143 struct ast_frame *ast_read(struct ast_channel *chan);
144
145 /* Write a frame to a channel */
146 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
147
148 /* Set read format for channelto whichever component of "format" is best. */
149 int ast_set_read_format(struct ast_channel *chan, int format);
150
151 /* Set write format for channel to whichever compoent of "format" is best. */
152 int ast_set_write_format(struct ast_channel *chan, int format);
153
154 /* Write text to a display on a channel */
155 int ast_sendtext(struct ast_channel *chan, char *text);
156
157 /* Browse the channels currently in use */
158 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
159
160 /* Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
161 char ast_waitfordigit(struct ast_channel *c, int ms);
162
163 /* Read in a digit string "s", max length "len", maximum timeout between 
164    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
165    for the first digit */
166 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
167
168 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                /* Report DTMF on channel 0 */
169 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                /* Report DTMF on channel 1 */
170 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                /* Return all voice frames on channel 0 */
171 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                /* Return all voice frames on channel 1 */
172 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                /* Ignore all signal frames except NULL */
173
174
175 /* Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
176    and -1 if it could not be done */
177 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
178
179 /* Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
180    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
181 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
182
183 #ifdef DO_CRASH
184 #define CRASH do { *((int *)0) = 0; } while(0)
185 #else
186 #define CRASH do { } while(0)
187 #endif
188
189 #define CHECK_BLOCKING(c) {      \
190                                                         if ((c)->blocking) {\
191                                                                 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); \
192                                                                 CRASH; \
193                                                         } else { \
194                                                                 (c)->blocker = pthread_self(); \
195                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
196                                                                         c->blocking = -1; \
197                                                                         } }
198
199 #if defined(__cplusplus) || defined(c_plusplus)
200 }
201 #endif
202
203
204 #endif