Version 0.1.2 from FTP
[asterisk/asterisk.git] / doc / channel.txt
1 Implementing a Channel
2 ======================
3
4 * What is a channel?
5
6 A channel is a unit which brings in a call to the Asterisk PBX.  A channel
7 could be connected to a real telephone (like the Internet Phone Jack) or
8 to a logical call (like an Internet phone call).  Asterisk makes no
9 distinction between "FXO" and "FXS" style channels (that is, it doesn't
10 distinguish between telephone lines and telephones).
11
12 Every call is placed or received on a distinct channel.  Asterisk uses a
13 channel driver (typically named chan_xxx.so) to support each type of
14 hardware.
15
16 * What do I need to create a channel?
17
18 In order to support a new piece of hardware you need to write a channel
19 driver.  The easiest way to do so is to look at an existing channel driver
20 and model your own code after it.  
21
22 * What's the general architecture?
23
24 Typically, a channel reads a configuration file on startup which tells it
25 something about the hardware it's going to be servicing.  Then, it
26 launches a thread which monitors all the idle channels (See the chan_modem
27 or the chan_ixj for an example of this).  When a "RING" or equivalent is
28 detected, the monitoring thread should allocate a channel structure and
29 assign all the callbacks to it (see ixj_new, for example), and then call
30 ast_pbx_start on that channel.  ast_pbx_start will launch a new thread to
31 handle the channel as long as the call is up, so once pbx_start has
32 successfully been run, the monitor should no longer monitor that channel.
33 The PBX thread will use the channel, reading, writing, calling, etc., and
34 multiplexing that channel with others using select() on the channel's
35 file descriptor (if your channel doesn't have an associated file
36 descriptor, you'll need to emulate one somehow, perhaps along the lines of
37 what the translator API does with its channel.  
38
39 When the PBX is finished with the line, it will hang up the line, at which
40 point it the hardware should again be monitored by the monitoring thread.