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         pthread_t blocker;                                      /* If anyone is blocking, this is them */
40         pthread_mutex_t lock;                           /* Lock, can be used to lock a channel for some operations */
41         char *blockproc;                                        /* Procedure causing blocking */
42         char *appl;                                                     /* Current application */
43         char *data;                                                     /* Data passed to current application */
44         int blocking;                                           /* Whether or not we're blocking */
45         struct sched_context *sched;            /* Schedule context */
46         int streamid;                                   /* For streaming playback, the schedule ID */
47         struct ast_filestream *stream;  /* Stream itself. */
48         struct ast_channel *trans;              /* Translator if present */
49         struct ast_channel *master;             /* Master channel, if this is a translator */
50         int fd;                                 /* File descriptor for channel -- all must have
51                                                    a file descriptor! */
52         char *type;                             /* Type of channel */
53         int state;                              /* State of line */
54         int rings;                              /* Number of rings so far */
55         int stack;                              /* Current level of application */
56         int format;                             /* Kinds of data this channel can
57                                                            natively handle */
58         char *dnid;                             /* Malloc'd Dialed Number Identifier */
59         char *callerid;                 /* Malloc'd Caller ID */
60         char context[AST_MAX_EXTENSION];        /* Current extension context */
61         char exten[AST_MAX_EXTENSION];          /* Current extension number */
62         int priority;                                           /* Current extension priority */
63         void *app[AST_CHANNEL_MAX_STACK];       /* Application information -- see assigned numbers */
64         struct ast_channel_pvt *pvt;
65                                                 /* Private channel implementation details */
66         jmp_buf jmp[AST_CHANNEL_MAX_STACK];             /* Jump buffer used for returning from applications */
67         struct ast_pbx *pbx;
68         struct ast_channel *next;               /* For easy linking */
69 };
70
71
72 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
73
74 #define AST_STATE_DOWN          0               /* Channel is down and available */
75 #define AST_STATE_RESERVED      1               /* Channel is down, but reserved */
76 #define AST_STATE_OFFHOOK       2               /* Channel is off hook */
77 #define AST_STATE_DIALING       3               /* Digits (or equivalent) have been dialed */
78 #define AST_STATE_RING          4               /* Line is ringing */
79 #define AST_STATE_RINGING       5               /* Remote end is ringing */
80 #define AST_STATE_UP            6               /* Line is up */
81 #define AST_STATE_BUSY          7               /* Line is busy */
82
83 /* Bits 16-32 of state are reserved for flags */
84
85 #define AST_STATE_MUTE          (1 << 16)       /* Do not transmit voice data */
86
87 /* Request a channel of a given type, with data as optional information used
88    by the low level module */
89 struct ast_channel *ast_request(char *type, int format, void *data);
90
91 /* Called by a channel module to register the kind of channels it supports.
92    It supplies a brief type, a longer, but still short description, and a
93    routine that creates a channel */
94 int ast_channel_register(char *type, char *description, int capabilities, 
95                         struct ast_channel* (*requester)(char *type, int format, void *data));
96
97 /* Unregister a channel class */
98 void ast_channel_unregister(char *type);
99
100 /* Hang up a channel -- chan is no longer valid after this call! */
101 int ast_hangup(struct ast_channel *chan);
102
103 /* Softly hangup up a channel -- call the protocol layer, but don't
104    destroy the channel structure (use this if you are trying to
105    safely hangup a channel managed by another thread. */
106 int ast_softhangup(struct ast_channel *chan);
107
108 /* Answer a ringing call */
109 int ast_answer(struct ast_channel *chan);
110
111 /* Place a call, take no longer than timeout ms.  Returns -1 on failure, 
112    0 on not enough time (does not auto matically stop ringing), and  
113    the number of seconds the connect took otherwise.  */
114 int ast_call(struct ast_channel *chan, char *addr, int timeout);
115
116 /* Misc stuff */
117
118 /* Wait for input on a channel for a given # of milliseconds (<0 for indefinite).  
119   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
120 int ast_waitfor(struct ast_channel *chan, int ms);
121
122 /* Wait for input on an array of channels for a given # of milliseconds. Return channel
123    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
124
125 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
126
127 /* This version works on fd's only.  Be careful with it. */
128 int ast_waitfor_n_fd(int *fds, int n, int *ms);
129
130 /* Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
131    best just stop reading frames and assume the channel has been
132    disconnected. */
133 struct ast_frame *ast_read(struct ast_channel *chan);
134
135 /* Write a frame to a channel */
136 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
137
138 /* Write text to a display on a channel */
139 int ast_sendtext(struct ast_channel *chan, char *text);
140
141 /* Browse the channels currently in use */
142 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
143
144 /* Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
145 char ast_waitfordigit(struct ast_channel *c, int ms);
146
147 /* Read in a digit string "s", max length "len", maximum timeout between 
148    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
149    for the first digit */
150 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
151 #define CHECK_BLOCKING(c) {      \
152                                                         if ((c)->blocking) {\
153                                                                 ast_log(LOG_WARNING, "Blocking '%s', already blocked by thread %ld in procedure %s\n", (c)->name, (c)->blocker, (c)->blockproc); \
154                                                                 /* *((int *)0)=0; */ \
155                                                         } else { \
156                                                                 (c)->blocker = pthread_self(); \
157                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
158                                                                         c->blocking = -1; \
159                                                                         } }
160
161 #if defined(__cplusplus) || defined(c_plusplus)
162 }
163 #endif
164
165
166 #endif