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 As-
terisk 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 ex-
tensions 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 parame-
ter 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 neces-
sary 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