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

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/

)

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

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...

Chapter 1. About this Book

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.

Chapter 2. Welcome to the Jungle: Hacking Asterisk

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.

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