PTAPI Overview
The Pingtel Telephony API (PTAPI) is an object-oriented application programming
interface written in C++. Like the Java Telephony API (JTAPI) on which
it is based, PTAPI supports computer telephony systems, but is not limited
to Java-based systems.
PTAPI defines the interface between computer telephony applications
and Pingtel phone products. It is intended to make programming applications
for Pingtel's IP telephone simple, while supporting features for advanced
telephony applications.
PTAPI is a collection of C++ function definitions, message definitions,
and type and data-structure definitions.
Core Classes
The core classes are:
-
PtAddress
-
A PtAddress object represents what we commonly think of as a phone number.
However, for calls to IP telephony endpoints, the "telephone number" is
a URL or IP address that identifies the endpoint.
-
PtCall
-
A PtCall object models a telephone call. A call can have zero or more connections:
a two-party call has two connections, and a conference call has three or
more connections. Each connection models the relationship between a call
and an address, where an address identifies a particular party or set of
parties on a call.
-
PtConnection
-
A PtConnection represents a link, or association, between a PtCall object
and a PtAddress object. The purpose of a PtConnection object is to describe
the relationship between a PtCall object and a PtAddress object. A PtConnection
object exists if the PtAddress is a part of the telephone call. The state
of each PtConnection describes the particular stage of the relationship
between the call and address.
-
PtProvider
-
A PtProvider represents the software entity that interfaces with an instance
of the "Pingtel Server" to monitor and control a group of Pingtel telephones.
The PtProvider maintains knowledge of the calls currently associated with
it. The provider maintains references to all calls until they move into
the PtCall::INVALID state.
-
PtTerminal
-
A PtTerminal represents a physical hardware endpoint connected to the telephony
domain, such as a computer workstation or a Pingtel phone acting as a physical
endpoint in a telephony network). Each PtTerminal object has a unique string
name. This name is first assigned when the PtTerminal is created and does
not change throughout the lifetime of the object.
-
PtTerminalConnection
-
A PtTerminalConnection object represents the relationship between an PtConnection
and a PtTerminal; a PtTerminalConnection object must always be associated
with a PtConnection object and a PtTerminal object. The association of
the PtConnection and PtTerminal objects to the PtTerminalConnection does
not change throughout the lifetime of the PtTerminalConnection. Because
a PtTerminalConnection is associated with a PtConnection, it is therefore
also associated with some PtCall. The PtTerminalConnection describes the
specific relationship between a physical PtTerminal endpoint with respect
to an address on a call.
Return to
top.
Building on these core classes, the PTAPI also offers groups of classes
that model components of telephone hardware, encapsulate data associated
with an event, listen for and obtain notification of events, and provide
utilities. Descriptions of these classes follow.
Component Classes
The classes relating to the components that model telephone hardware are:
-
PtComponent
-
This is the base class for all individual components used to model telephone
hardware. Each distinct component type is derived from this class.
-
PtPhoneButton
-
Models keypad and feature buttons.
-
PtPhoneDisplay
-
Models the display device for a phone. It is the parent class for the PtPhoneTextDisplay
and PtPhoneGraphicDisplay classes.
-
PtPhoneTextDisplay
-
Models a character display.
-
PtPhoneGraphicDisplay
-
Represents a display device that is pixel-addressable.
-
PtPhoneHookswitch
-
Models the phone hook switch.
-
PtPhoneLamp
-
Models phone lamps and other simple indicators.
-
PtPhoneMicrophone
-
Models a phone microphone.
-
PtPhoneRinger
-
Models a phone ringer.
-
PtPhoneSpeaker
-
Models a phone speaker.
Return to
top.
Event Classes
The base class and subclasses that contain data relating to a particular
type of event are:
-
PtEvent
-
The PtEvent encapsulates data associated with an event notification. PtEvent
is subclassed to contain the PTAPI object(s) and data involved with the
event. An application that is interested in events from a specific object
must implement a PtEventListener that handles the specific type of event(s)
of interest.The PtEvent is sent to an application implementing a PtEventListener
by the Pingtel object in which the event occurs.
-
PtEventMask
-
The PtEventMask is used to filter events which get passed to a PtEventListener.
To provide finer granularity on the control of events that get passed to
a listener, the PtEventMask may be used to define the specific events that
are to be passed.
-
PtAddressEvent
-
A PtAddressEvent contains event data associated with a PtAddress.
-
PtCallEvent
-
A PtCallEvent contains event data associated with a PtCall.
-
PtComponentIntChangeEvent
-
A PtComponentIntChangeEvent contains PtComponent-associated event data,
where a component property represented as an integer has changed.
-
PtComponentStringChangeEvent
-
A PtComponentIntChangeEvent contains PtComponent-associated event data,
where a component property represented as a string has changed.
-
PtConnectionEvent
-
A PtConnectionEvent contains event data that is associated with a PtConnection.
-
PtMultiCallEvent
-
A PtMultiCallEvent contains PtCall-associated event data, where multiple
calls are involved. Multicall events are typically merges of multiple calls
into a single call.
-
PtProviderEvent
-
A PtProviderEvent contains event data that is associated with a PtProvider.
-
PtTerminalComponentEvent
-
A PtTerminalComponentEvent contains event data associated with a PtTerminalComponent.
-
PtTerminalConnectionEvent
-
A PtTerminalConnectionEvent contains event data associated with a PtTerminalConnection.
-
PtTerminalEvent
-
A PtTerminalEvent contains event data associated with a PtTerminal.
Return to
top.
Listener Classes
The listener class is used to register interest and obtain notification
of events of interest on PTAPI objects. The base class and the specialized,
derived classes are:
-
PtEventListener
-
Base class for listener objects. The PtEventListener is specialized, in
the provided derived classes, with methods for each event type that a Pingtel
object may generate. An application that is interested in being notified
of specific events, must implement the derived class for the listener capable
of receiving those events.
-
PtAddressListener
-
The PtAddressListener is used to register with and receive events from
PtAddress objects.
-
PtCallListener
-
The PtCallListener is used to register with PtAddress, PtTerminal, and
PtCall objects to receive events from associated PtCall objects.
-
PtConnectionListener
-
The PtConnectionListener is used to register with PtAddress, PtTerminal
and PtCall objects to receive events from associated PtCall and PtConnection
objects.
-
PtProviderListener
-
The PtProviderListener is used to register with and receive events from
PtProvider objects.
-
PtTerminalComponentListener
-
The PtTerminalComponentListener is used to register with and receive events
from PtTerminal objects.
-
PtTerminalConnectionListener
-
The PtTerminalConnectionListener is used to register with PtAddress, PtTerminal
and PtCall objects to receive events from associated PtCall, PtConnection,
and PtTerminalConnection objects.
-
PtTerminalListener
-
The PtTerminalListener is used to register with and receive events from
PtTerminal objects.
Return to
top.
Utility classes
Utility classes in PTAPI are:
-
PtAddressForwarding
-
The PtAddressForwarding class represents a forwarding instruction. This
instruction indicates how the phone system should forward incoming telephone
calls to a specific address.
-
PtConfigDb
-
This class maintains a configuration database containing key/value pairs.
-
PtSessionDesc
-
This class defines session attributes that are used when setting up a new
connection.
Return to top.