The Design and Implementation of the Asterisk Open-Source PBX Volume III of the Asterisk Documentation Project Series
Nicholas Bachmann Steven Critchfield
The Design and Implementation of the Asterisk Open-Source PBX: Volume III of the Asterisk Documentation Project Series by Nicholas Bachmann and Steven Critchfield Copyright © 2005 The Asterisk Documentation Project A guide to the internals of Asterisk
This document may be distributed subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/1 )
Revision History Revision $Revision: 1.2 $ $Author: nbachmann $ $Date: 2005/02/07 04:04:14 $
Table of Contents Prologos. ................................................................................................................................1 1. About this Book ........................................................................................................1 Our Approach to Documentation ....................................................................1 Where to Find the Documentation Team ........................................................1 2. Welcome to the Jungle: Hacking Asterisk ............................................................3 The Asterisk Philosophy....................................................................................3 CVS and Such......................................................................................................3 Mantis...................................................................................................................3 Coding Style ........................................................................................................3 Finding Help .......................................................................................................3 I. The Asterisk API ...............................................................................................................5 3. Core C API.................................................................................................................5 The Config API....................................................................................................5 The Astobj API ....................................................................................................5 The Channel API.................................................................................................5 Codecs ..................................................................................................................5 Formats.................................................................................................................5 Resources .............................................................................................................6 4. External APIs ............................................................................................................7 AGI........................................................................................................................7 Manager ...............................................................................................................7 II. The Channels....................................................................................................................9 5. An Introduction to Channels..................................................................................9 6. Local Channels........................................................................................................11 Zaptel..................................................................................................................11 CAPI ...................................................................................................................11 vpb ......................................................................................................................11 7. VoIP Channels.........................................................................................................13 IAX2 ....................................................................................................................13 SIP .......................................................................................................................13 H.323...................................................................................................................13 Skinny.................................................................................................................13 MGCP .................................................................................................................13 8. Pseudo-Channels....................................................................................................15 Agent ..................................................................................................................15 Local....................................................................................................................15 III. Asterisk Protocols ........................................................................................................17 9. IAX2..........................................................................................................................17 VoIP.....................................................................................................................17 State Data ...........................................................................................................17 10. TDMoE...................................................................................................................19 La.........................................................................................................................19 11. DUNDi ...................................................................................................................21 Blah .....................................................................................................................21 Colophon ..............................................................................................................................23
iii
iv
Chapter 1. About this Book Our Approach to Documentation Cruising Altitude of 30k Feet
Where to Find the Documentation Team #asterisk-docs or -docs mailing list...
1
Chapter 1. About this Book
2
Chapter 2. Welcome to the Jungle: Hacking Asterisk The Asterisk Philosophy In one word: simple
CVS and Such
Mantis don’t forget ’script’
Coding Style
Finding Help -users,-dev,-security,-biz,#asterisk-dev,#asterisk-bugs,etc.
3
Chapter 2. Welcome to the Jungle: Hacking Asterisk
4
Chapter 3. Core C API The Config API
The Astobj API Kevin Fleming, this one’s for you!
The Channel API
Codecs
Formats This section will take you through the creation of a format and what is important. Most simply, you will need the following functions with unique names; open rewrite write seek trunc tell read close getcomment You will register your format with Asterisk with the name of your format, the extensions your format will accept delimited by a pipe, the codec you expect to be presented to your format, and the list of functions listed above. The open function is actually called after the file has been opened. The only parameter to open is an open file descriptor. Open is expected to return a valid ast_filestream structure . Rewrite... Looks like open just short some code. Close do basic house keeping on the file and close the open file descriptor. Close takes a ast_filestream structure as it’s only argument and returns void. Close must also free the ast_filestream structure and set the variable to null. Read accepts an ast_filestream structure to be populated with data about the read and an int pointer for when next to ask for more audio data. Read will populate the ast_filestream structures fr structure with the appropriate data as well as the audio date to the appropriate buffer space. Read returns the fr structure from ast_filestream. Write accepts an ast_filestream structure and an ast_frame structure. The ast_filestream will contain the appropriate open file descriptor for use when writing the data to the disk. The ast_frame structure contains the data coming from the channel to be dealt with. Write should return 0 on no error and -1 for an error. Seek takes an ast_filestream, the number of samples to move the file pointer by and the offset chooser. Your seek function should take into account headers or any other file structure necessary to get to the specific sample spot. The offset chooser is the normal lseek whence option of SEEK_SET, SEEK_END, and SEEK_CUR. Seek returns the value from the actual lseek function. As of this writing, the only asterisk app that uses seek is AGI and it will only use SEEK_SET. Trunc needs only truncate the file at the current location and do any cleanup necessary such as updating headers. Tell accepts the ast_filestream structure as it’s only argument. Returns 0 for success and -1 for error. 5
Chapter 3. Core C API Tell accepts the ast_filestream function as it’s only argument. Tell needs to return the number of samples into a file the file pointer is located at taking into account the headers and any other file structure information. Getcomment... What does this do?
Resources
6
Chapter 4. External APIs AGI
Manager
7
Chapter 4. External APIs
8
Chapter 5. An Introduction to Channels This would be a nice place to build a very minimal channel for demo purposes
9
Chapter 5. An Introduction to Channels
10
Chapter 6. Local Channels Zaptel
CAPI
vpb
11
Chapter 6. Local Channels
12
Chapter 7. VoIP Channels IAX2
SIP
H.323
Skinny
MGCP
13
Chapter 7. VoIP Channels
14
Chapter 8. Pseudo-Channels Agent
Local
15
Chapter 8. Pseudo-Channels
16
Chapter 9. IAX2 VoIP
State Data
17
Chapter 9. IAX2
18
Chapter 10. TDMoE La
19
Chapter 10. TDMoE
20
Chapter 11. DUNDi Blah
21
Chapter 11. DUNDi
22
Colophon The Liger is bred for its skills in magic.
23
24