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