Menu
▾
▴
Tree [00618c] master / History
Robert Jongbloed
rogerh
Craig Southeren
Read Me
Portable Tools Libary
=====================
Contents
--------
1. Introduction
2. Apologies
3. Licensing
4. CVS Access
5. Building PTLib
6. Using PTLib
7. IPv6 issues
8. Using PortAudio
================================================================================
1. Introduction
---------------
PTLib (Portable Tools Library) is a moderately large class library that has it's
genesis many years ago as PWLib (portable Windows Library), a method to product
applications to run on both Microsoft Windows and Unix systems. It has also been
ported to other systems such as Mac OSX, VxWorks and other embedded systems
Since then the system has grown to include many classes that assist in writing
complete multi-platform applications. Classes for I/O portability, multi-
threading portability, aid in producing unix daemons and NT services portably
and all sorts of internet protocols were added over the years. So it became a
Portable Tools Library and was renamed to PTLib.
All this over and above basic "container" classes such as arrays, linear lists,
sorted lists (RB Tree) and dictionaries (hash tables) which were all created
before STL was standardized. Future versions of PTLib will see many of these
classes replaced or supplemented by STL.
The library was used extensively for all our in-house products. Then we decided
to support OpenH323, and then OPAL, by throwing in some of the code written for
one of our products. Thus, required PTLib so it got thrown into the open source
world as well.
================================================================================
2. Apologies (not)
------------------
As you start using the library, the inevitable question "why did they do it that
way?" will come up. The more experienced out there will know that there are
several reasons for the way things are:
* Carefully considered design,
* Workarounds for portability and compiler subtleties,
* History, it may be too hard to change an early design decision,
* Complete arbitrariness, the absence of any compelling reason.
So, when you ask the next question "why didn't you do it this way?" The answer
will be one of the above. The last one being a synonym for "we didn't think of
that!"
The bottom line is, use the library as is or change it as you require. You can
even send in suggestions for improvements (or merely changes) and we may (or may
not) include them in the base line code. Just do not send us any mail starting
with the words "Why did you..." as the answer is quite likely to be "Because!"
This package is far from a "product". There is very limited documentation and
support will be on an ad-hoc basis, send us an e-mail and we will probably
answer your question if it isn't too difficult.
It is supplied mainly to support the OPAL project, but that shouldn't stop
you from using it in whatever project you have in mind if you so desire. We like
it and use it all the time, and we don't want to get into any religious wars of
this class library over that one.
================================================================================
9. Licensing
------------
The bulk of this library is licensed under the MPL (Mozilla Public License)
version 1.0. In simple terms this license allows you to use the library for
any purpose, commercial or otherwise, provided the library is kept in tact
as a separate entity and any changes made to the library are made publicly
available under the same (MPL) license. It is important to realise that that
refers to changes to the library and not your application that is merely
linked to the library.
Note that due to a restriction in the GPL, any application you write that
uses anything another than GPL, eg our library with MPL, is technically in
breach of the GPL license. However, it should be noted that MPL does not
care about the license of the final application, and as only the author of
the GPL application is in breach of his own license and is unlikely to sue
themselves for that breach, in practice there is no problem with a GPL
application using an MPL or any other commercial library.
The random number generator is based on code originally by Bob Jenkins.
Portions of this library are from the REGEX library and is under the
following license:
Copyright 1992, 1993, 1994, 1997 Henry Spencer. All rights reserved.
This software is not subject to any license of the American Telephone
and Telegraph Company or of the Regents of the University of California.
Permission is granted to anyone to use this software for any purpose on
any computer system, and to alter it and redistribute it, subject
to the following restrictions:
1. The author is not responsible for the consequences of use of this
software, no matter how awful, even if they arise from flaws in it.
2. The origin of this software must not be misrepresented, either by
explicit claim or by omission. Since few users ever read sources,
credits must appear in the documentation.
3. Altered versions must be plainly marked as such, and must not be
misrepresented as being the original software. Since few users
ever read sources, credits must appear in the documentation.
4. This notice may not be removed or altered.
The in-band DTMF decoding code was taken from FreeBSD's dtmfdecode.c
application written by Poul-Henning Kamp. It has the following
license:
* ----------------------------------------------------------------------------
* "THE BEER-WARE LICENSE" (Revision 42):
* <phk@FreeBSD.org> wrote this file. As long as you retain this notice you
* can do whatever you want with this stuff. If we meet some day, and you think
* this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
* ----------------------------------------------------------------------------
================================================================================
4. SVN Access
-------------
There is a public SVN archive available at svn.sourceforge.net. To extract the
latest version, use a command line like the following:
svn co http://opalvoip.svn.sourceforge.net/svnroot/opalvoip/ptlib/trunk
More information on stable branches is available at:
http://wiki.opalvoip.org/index.php?n=Main.Subversion
================================================================================
5. Building PTLib
-----------------
This library is multi-platform, however there are only two major build systems
that are used. The Microsoft DevStudio environment for Windows and the GNU make
system for all of the various unix systems.
5.1. For Windows
----------------
See the online documentation at:
http://wiki.opalvoip.org/index.php?n=Main.BuildingPTLib
5.2. For Linux/Unix
-------------------
See the online documentation at:
http://wiki.opalvoip.org/index.php?n=Main.BuildingPTLibUnix
5.3. For MacOS
-------------------
See the online documentation at:
http://wiki.opalvoip.org/index.php?n=Main.BuildingPTLibMacOSX
5.4. For MinGW
Uncomment the appropriate line for 64 or 32 bit builds
-------------------------------------------------------
#!/bin/sh
export HOST_PREFIX=x86_64-w64-mingw32
#export HOST_PREFIX=i586-mingw32msvc
export PKG_CONFIG_LIBDIR=/usr/local/${HOST_PREFIX}/
./configure --host=${HOST_PREFIX}
================================================================================
6. Using PTLib
--------------
What documentation there is consists of this document and all of the header
files. It was intended that a post processer go through the header files and
produces HTML help files, but this never got completed.
6.1. Tutorial
-------------
Detailed tutorials will almost certainly not be forthcoming. However, at least
giving you an indication on how to start an application would be useful, so
here is the infamous "Hello world!" program.
// hello.cxx
#include <ptlib.h>
class Hello : public PProcess
{
PCLASSINFO(Hello, PProcess)
public:
void Main();
};
PCREATE_PROCESS(Hello)
void Hello::Main()
{
cout << "Hello world!\n";
}
// End of hello.cxx
The CREATE_PROCESS macro actually defines the main() function and creates an
instance of Hello. This assures that everything is initialised in the correct
order. C++ does initialisation of global statics badly (and destruction is even
worse), so try to put everything into your PProcess descedent rather than
globals.
A GUI application is very similar but is descended off PApplication rather than
PProcess, and would create a window as a descendent off the PMainWindow class.
The following is a simple Makefile for Unix platforms for the hello world
program.
# Simple makefile for PTLib
PROG = hello
SOURCES = hello.cxx
ifndef PTLIBDIR
PTLIBDIR=$(HOME)/ptlib
endif
include $(PTLIBDIR)/make/ptlib.mak
# End of Makefile
--------------------------------------------------------------------------------
6.2. PTlib Classes
------------------
The classes in PTLib fall into the following broad categories
Containers
I/O
Threads & Processes
6.2.1. Containers
While there are a number of container classes you wourld rarely actually descend
off them, you would use macros that declare type safe descendents. These are
simply templates instantiations when using a compiler that supports templates
in a simple manner (GNU C++ does not qualify in our opinion).
6.2.2. I/O
There are many classes descendend from a basic primitive call a PChannel, which
represents an entity for doing I/O. There are classes for files, serial ports,
various types of socket and pipes to sub-processes.
6.2.3. Threads & Processes
These classes support lightweight threading and functionality to do with the
process as a whole (for example argument parsing). The threading will be
pre-emptive on platforms that support it (Win32, platforms with pthreads eg
Linux and FreeBSD) and cooperative on those that don't.
================================================================================
7. IPv6 support in ptlib
------------------------
The IPv6 support in PTlib is supported and can be enabled or disabled via
the configure program.
When compiled with the IPv6 support, applications using only IPv4 are still
fully backward compatible. PTLib is able to manage simultaneously IPv4 and
IPv6 connections.
7.1. Testing
------------
The test application sources can be found in the directory: opal/samples/simple
Once compiled the binaries are in simple/debug, release, obj_linux_x86_d, or
obj_linux_x86_r.
Under windows, the test application is simpleopal.exe
Under linux, the test application is simpleopal
IPv6 support can be tested on only one machine. Just open two shell/command windows.
7.1.1. IPv6 Address and port notation
-------------------------------------
IPv4 address and port are written in dot notation: xx.xx.xx.xx:4000
IPv6 global address are written in semi-colon notation: [xx:xx:xx:xx::xx]:4000
IPv6 scoped address ad a field for the scope: [xx:xx:xx:xx::xx%scope]:4000
Exemples:
Global address
[3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5]:4000
[3ffe:0b80:0002:f9c1::500b:0ea5]:4000
Scoped address
[fe80::232:56ff:fe95:315%lnc0]:4000
Scoped address are not supported yet.
7.1.2. Tests configuration
--------------------------
Tests 1,2,3 run on a single dual stack machine.
IPv4 Address: 127.0.0.1, 10.0.0.6
IPv6 Address: ::1, 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5
Tests 4,5,6 run on two dual stack machine.
PC1
IPv4 Address: 10.0.0.6
IPv6 Address: ::1, 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5
PC2
IPv4 Address: 10.0.0.8
IPv6 Address: ::1, 3ffe:0b80:0002:f9c1:0000:0000:500b:0eb6
7.1.3. Test 1: IPv4 <--> IPv4 local call
----------------------------------------
This test checks the backward compatibility with IPv4
In first shell/command window, listen on 127.0.0.1, wait for a call.
simple.exe -tttt -n -i 127.0.0.1 -l -a
In second shell/command window, listen on 10.0.0.6, call 127.0.0.1
simple.exe -tttt -n -i 10.0.0.6 -n 127.0.0.1
7.1.4. Test 2: IPv6 <--> IPv6 local call
----------------------------------------
This test checks the IPv6 support
In first shell/command window, listen on ::1, wait for a call.
simple.exe -tttt -n -i ::1 -l -a
In second shell/command window, listen on IPv6 address, call ::1
simple.exe -tttt -n -i 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5 -n [::1]
7.1.5. Test 3: IPv4 <--> IPv6 local call
----------------------------------------
This test checks that simultaneous IPv4 and IPv6 calls are supported.
In first shell/command window, listen on 127.0.0.1, wait for a call.
simple.exe -tttt -n -i 127.0.0.1 -l -a
In second shell/command window, listen on IPv6 address, call 127.0.0.1
simple.exe -tttt -n -i 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5 -n 127.0.0.1
7.1.6. Test 4: IPv4 <--> IPv4 call between two hosts
----------------------------------------------------
This test checks the backward compatibility with IPv4
First host, listen on 10.0.0.6, wait for a call.
simple.exe -tttt -n -i 127.0.0.1 -l -a
Second host, listen on 10.0.0.8, call 10.0.0.6
simple.exe -tttt -n -i 10.0.0.8 -n 10.0.0.6
7.1.7. Test 5: IPv6 <--> IPv6 call between two hosts
----------------------------------------------------
This test checks the IPv6 support
First host, listen on 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5, wait for a call.
simple.exe -tttt -n -i 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5 -l -a
Second host, listen on 3ffe:0b80:0002:f9c1:0000:0000:500b:0eb6, call 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5
simple.exe -tttt -n -i 3ffe:0b80:0002:f9c1:0000:0000:500b:0eb6 -n [3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5]
7.1.8. Test 6: IPv4 <--> IPv6 call between two hosts
----------------------------------------------------
This test checks that simultaneous IPv4 and IPv6 calls are supported.
First host, listen on 10.0.0.6, wait for a call.
simple.exe -tttt -n -i 10.0.0.6 -l -a
Second host, listen on 3ffe:0b80:0002:f9c1:0000:0000:500b:0eb6, call 10.0.0.6
simple.exe -tttt -n -i 3ffe:0b80:0002:f9c1:0000:0000:500b:0eb6 -n 10.0.0.6
--------------------------------------------------------------------------------
7.2. Known limitations
--------------------
You must use IPv6 address with global scope. Tests with IPv6 local link address
fail.
--------------------------------------------------------------------------------
7.3. Questions
--------------
7.3.1. How to get an ipv6 address with a Global scope ?
-----------------------------------------------------
7.3.1.1. Manually
-----------------
Set one manually if you're not connected to IPv4 Internet or IPv6 backbone:
#ip -6 addr add 3ffe:0b80:0002:f9c1:0000:0000:500b:0ea5 dev eth0
(this address is owned by freenet6.net).
Check the address is set.
#ifconfig
eth0 Lien encap:Ethernet HWaddr 00:08:D5:10:C7:BB
inet adr:12.0.0.2 Bcast:12.255.255.255 Masque:255.0.0.0
adr inet6: 3ffe:b80:2:f9c1::500b:ea5/128 Scope:Global <- - - Ok, Global scope
adr inet6: fe80::208:c7ff:fe59:bbc7/10 Scope:Lien <- - - [ Can't use this one ]
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:9 errors:0 dropped:0 overruns:9 carrier:0
collisions:0
RX bytes:0 (0.0 b) TX bytes:534 (534.0 b)
7.3.1.2. Tunnel broker
----------------------
Get one from a free IPv6 tunnel broker.
Exemple:
http://www.freenet6.net : Canadian tunnel broker
http://tb.ngnet.it : Italian tunnel broker (Telecom Italia Research)
Note: The current (10/2002) freenet6 windows binary is buggy, use it to get the
values, and set manually your tunnel.
--------------------------------------------------------------------------------
7.4. Troubles
------------
7.4.1. Listen on ::1:1720 failed: Address family not supported by protocol
-----------------------------------------------------------------------
IPv6 module is not loaded in the kernel.
#modprobe ipv6
================================================================================
8. Using PortAudio
------------------
PTLib can be configured to use PortAudio V19 for audio input and
output. Some distros (Ubuntu, for example) only include PortAudio
V18 so it is necessary to build it manually.
PTLib can also use PortMixer (part of the Audacity project) but
not many distros provide this feature as it requires patching
PortAudio.
The script below will extract latest PortAudio and PortMixer
from the correct source repositories, build and install it
into /opt/portaudio. Once this is done, configure ptlib as
follows:
./configure --with-portaudio-dir=/opt/portaudio
This script has been verified on OSX Mountain Lion and
Ubuntu 12.01 for x64
Craig (craigs@postincrement.com)
17 January, 2013
--------------------------------------------------
#!/bin/sh
PREFIX=/opt/portaudio
svn co https://subversion.assembla.com/svn/portaudio/portaudio/trunk portaudio
svn co http://audacity.googlecode.com/svn/audacity-src/trunk/lib-src/portmixer portmixer
cd portaudio
patch -p4 < ../portmixer/portaudio.patch
cd ..
cd portaudio
make clean
./configure --prefix=${PREFIX}
make
sudo make install
cd ..
cd portmixer
make clean
( export CFLAGS=-fPIC ; ./configure --with-pa-include=../portaudio/include/ --prefix=${PREFIX} )
make
sudo cp libportmixer.a ${PREFIX}/lib
sudo cp include/portmixer.h ${PREFIX}/include
cd ..
================================================================================
9.