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