Pingtel Telephony API Overview
Author: Rich Schaaf

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