PIKA HMP 3.0
Table of Contents
1 Copyright Information
1
2 Contacting PIKA Technologies
2
3 Introduction
3
3.1 Purpose and Scope
4
3.2 Assumed Knowledge
4
3.3 Related Documentation
5
4 High Level API Architecture
6
4.1 High Level API Object Descriptions
7
4.1.1 System Object States 9
4.2 High Level API Object Relationships
9
5 Application Development
11
5.1 API Principles
11
5.2 Design Guidelines
13
5.3 Basic Functions
15
5.3.1 System Start 16 5.3.2 Event Queue 18 5.3.3 Application Logging 22Log File Management 22
User Application Logging 24
5.3.4 Call Processing 25
Call Analysis 33
Called and Calling Number Formats 37
Call Initiation Examples 44
Receiving a Call 44
Collect Call Blocking 47
Early Media 49
Joining Calls 51
Hold and Resume 53
Call Transfer 60
Basic Call Transfer 60
ISDN Call Transfer 71
Terminating a Call 76
5.3.5 Media Processing 78
Playing a Stored Message 78
Recording Audio Data From a Channel 84
Collecting DTMF Digits From a Channel 88
Sending DTMF Digits to a Channel 90
Generating Tones on a Channel 91
Detecting Tones on a Channel 93
Detecting Speech on a Channel 94
Audio Flags 95
Media Processing Termination Conditions 97
Fax Processing 100
Fax Diagnostics 110
5.3.6 Conferencing 110
Virtual Channels in Conferences 112
5.3.7 Phones 113
6 Building a High Level API Application
116
7.1 Distributing a PIKA High Level API Application on Windows
121
7.2 Distributing a PIKA High Level API Application on Linux
122
8 Advanced Topics
125
8.1 Configuring a Channel
125
8.2 SIP
126
8.2.1 User Management 126
Dynamic User Management 126
8.3 Modifying the High Level API Source Code
132
8.3.1 Building the High Level API Libraries in Windows 137 8.3.2 Building the High Level API Libraries in Linux 139
8.4 Bypassing the High Level API to Make Low-level Function Calls
140
9 Sample Applications
143
10 Glossary
144
1 Copyright Information
COPYRIGHTSCopyright 2010 PIKA Technologies Inc.
TRADEMARKS
PIKA is a registered trademark of PIKA Technologies Inc. All other trademarks, product names and company names and/or logos cited herein, if any, are the property of their respective holders.
DISCLAIMER
This document is provided to you for informational purposes only and is believed to be accurate as of the date of its publication, and is subject to change without notice. PIKA Technologies Inc. assumes no responsibility for any errors or omissions in this document and shall have no obligation to you as a result of having made this document available to you or based upon the information it contains.
2 Contacting PIKA Technologies
Customer Care
For support issues, phone or e-mail our Customer Care department at the following: Tel: +1-613-591-1555
FAX: +1-613-591-9295 Email: [email protected]
International Headquarters
PIKA Technologies Inc. 535 Legget Drive, Suite 400 Ottawa, Ontario, Canada K2K 3B8 Tel: +1-613-591-1555 FAX: +1-613-591-9295 Email: [email protected]
Internet
Visit our website at www.pikatechnologies.com for the latest news, product announcements, downloads, online community, documentation updates, and contact information.
3 Introduction
The PIKA HMP SDK suite is made up two components: the low level API ( previously referred to as AoH), and the high level API (GrandPrix (GP)). Hardware boards provide connectivity to digital (T1 and E1) and analog devices. The PIKA Low Level API SDK is a low-level API providing detailed control of voice media processing and call protocol messaging. The PIKA High Level API SDK is a high-level API providing an abstraction of call signaling (analog, digital, and IP) and call control for SIP, ISDN, CAS, and Analog with Caller-ID. The high level API is designed to work directly with the low level API and provides mechanisms allowing user applications to access the finer control provided by the low level API.
The high level API is a collection of high-level function calls that make it easier and faster for designers to develop user applications based on PIKA hardware and software. It removes most of the in-depth knowledge required to develop user applications to make calls (TDM, Analog or VoIP); play and record files; and perform media analysis such as digit and tone detection, call progress, and call analysis. At the same time, it has the flexibility to co-exist with the low-level API.
The following features are available with the high level API: • Abstraction of low level HSP technology
• Basic call progress and call analysis for all call protocols
• Play to and record from a file or buffer, with terminating conditions • Digit collection with terminating conditions
• Tone detection and generation • Switching and conferencing
NOTE: Only one user application can be supported by the high level API on each deployment platform at the same time.
Guide Organization - This guide is organized as follows:
• Introduction - explains the purpose and scope of the guide, how to use the guide, and lists other related documents. • Architecture (pg. 6) - provides a detailed description of the high level API architecture, including what high-level
objects can be accessed through the API.
• Application Development (pg. 11) - provides the basic information required to develop an application using GP, including system start up and shutdown, event queues, media processing, call processing, and conferencing.
• Building Applications with the PIKA GrandPrix SDK (pg. 116) - provides guidelines for building user applications on Linux and Windows platforms.
• Distributing Applications - (pg. 121) describes the components that must be distributed with the user application, and where these components must reside on the target platform for proper user application operation.
• Advanced Topics - (pg. 125) describes how to modify the source code and how to call the low-level API functions from a GP user application.
The PIKA MonteCarlo Software License Agreement constitutes a legal agreement ("License Agreement") between you and PIKA Technologies Inc. ("PIKA") and covers software, media, and accompanying on-line or printed documentation distributed by PIKA. The full version of the agreement appears as you install the software.
3.1
Purpose and Scope
The high level API makes full use of host media processing technology. It builds on the the rich feature set of the low level API to allow for simpler system architectures, reduced development time, and significantly reduced cost of ownership in comparison to the traditional Computer Telephony Integration (CTI) solutions.
This guide describes how to use the low level API to create typical voice processing applications based on the low level API. These applications include VoIP and ISDN call processing, and voice processing such as record, play, DTMF detection, and tone detection and generation.
3.2
Assumed Knowledge
The high level API is highly flexible. We assume you are familiar with:
• Telephony concepts (such as pulse dialing, hookflash, ring patterns, and general call processing states and events) • An understanding of ISDN to provision configuration files (See http://www.itu.int/home/index.html for more
information on the ISDN standard)
• An understanding of VoIP to provision configuration files:
• SIP (See http://www.ietf.org/ for more information on the SIP standard)
3
• RTP (See http://www.ietf.org/ for more information on the RTP standard) • PC hardware and software usage and architecture
• C/C++ programming
3.3
Related Documentation
The following documents are related to the PIKA High Level API Programmers Guide. These documents are linked together and constitute the complete set of documentation for the high level API component of the HMP SDK.
PIKA HMP Getting Started Guide: This guide provides a step-by-step procedure for installing the HMP SDK.
PIKA HMP High Level API Configuration Guide: This guide describes how to use the GPConfig tool, how configuration files are set up, and how to modify the configuration files.
PIKA HMP High Level API Reference: This guide provides a reference for all function calls, error codes, event codes, type codes, and other important information for GP.
PIKA HMP Release Notes: These notes describe the contents of the release. This includes a list of new hardware and software, new software features, and known product issues.
4 High Level API Architecture
This topic describes the architecture of the high level API. To develop a call processing user application, it is important to understand what objects are defined in the API and the relationships between them. The architectural description is broken into the following topics:
• PIKA High Level API Object Descriptions (pg. 7) that describes the objects in the architecture
• PIKA High Level API Object Relationships (pg. 9) that describes how the objects are related to each other The following diagram shows the architecture:
Typically, the user application has at least two threads: one thread to manage the interface with the user, and a second thread to wait for and process events generated by the high level API. Both threads communicate through the high level
4
API interface with the low level components.
High Level API Main spawns three other threads:
• High level API Timer Thread: responsible for managing timers within the high level API.
• Low level API Thread: responsible for executing user application requests on low level resources and for handling low level events and converting them into high level API events.
NOTE: Only one user application can be supported by the high level API on each deployment platform.
4.1
High Level API Object Descriptions
The following diagram shows the objects available through GP.
All GP objects can generate events. An event is a message about a significant occurrence that has happened to the object during its operation. Events are specific to each type of object. See the Event Queue (pg. 18) section for more information on the generation and processing of events.
The System object allows the user application to: • Load in the system configuration
• Start and stop GP call processing engines • Retrieve an event for processing
• Get and set the user data field for object events • Inject events into the event queue
Group objects allow user applications to group together related channels of the same type. The group defines the number of channels controlled by the group and the protocols used for incoming and outgoing calls on those channels. The group types are:
• VoIP groups • SIP • TDM groups
• ISDN • CAS
• FXO (analog trunks) • FXS (analog phones) • Virtual groups
Group objects defined in configuration files are automatically created when the system object is opened.
Channel objects represent bearer channels that carry voice media. Media processing functions, such as play, record, tone detection, tone generation, digit detection, and digit generation, can be applied to channels. Channels can be connected to other channels to make full- or half-duplex connections. Channel objects are defined in configuration files and are automatically created when the system object is opened. Virtual channels are an exception in that they are created and destroyed dynamically by the user application.
Conference objects represent audio conferences, which allow more than two channels to be joined. Channels can be added to and removed from conference objects. Conference objects are dynamically created by the user application.
Call objects represent incoming or outgoing calls made or received by the user application. The interface to call objects is the same, regardless of the protocol used for the call. Call objects are automatically created when calls are received or
4
made by the user application.
User (pg. 126) objects hold all of the configuration information associated with a user. Users defined in configuration files are automatically created when the system object is opened. Dynamic users are created and destroyed by the user application.
Message objects represent messages that are dynamically created by the user application to use custom messages in call and non call situations.
4.1.1
System Object States
The typical GP object transitions through the life-cycle states shown in the following figure: disabled, enabled, and running. In the disabled state, nothing happens. In the enabled state, an object handle can be retrieved by the user application for configuration purposes, but no events are raised. In the running state, events can occur at any time.
4.2
High Level API Object Relationships
The following diagram shows the relationships between GP objects.
There is one system object that contains many groups.
A group can contain many channels, and a channel belongs to one group. A group can contain many users, but a user can only belong to one group.
A call is associated with one channel and a channel may be associated with at most one call.
A channel may be connected to at most one other channel, and a connection can be made between two channels. A channel may be a member of one conference and a conference may have many channels as members.
A virtual channel may be connected to one other channel, but may not be associated with any CALL object (may not make or accept calls).
A virtual channel may be a member of one conference, but may not be associated with any CALL object (may not make or accept calls).
Many media processing functions can be applied to a channel and many channels can have a media processing function applied to them.
Many messages can be used for call-related functions while a connection is active and messages can be associated with at most one group for non-call functions.
5 Application Development
This topic provides the information required to successfully develop a user application using GP. It is organized as follows:
• API Principles - (pg. 11) provides information on the basic features of GP, such as functions, structures, and configuration files.
• Design Guidelines - (pg. 13) describes requirements for designing user applications with GP.
• Basic Functions - (pg. 15) describes the basic functions common to all user applications, such as system start-up, event queues, application logging, timers, application licenses, call processing, switching, conferencing, and media streams.
Note: Only one user application can be supported by the high level API on each deployment platform at the same time.
5.1
API Principles
GrandPrix comprises:
• Sets of C function interfaces • Structures used by the functions • Configuration files
GP Functions - Detailed information on purpose, parameters, and return values for each function is provided in the PIKA HMP High Level API Reference. All GP functions have the prefix PKX_. GP functions are broken into groups based on the GP object or processing function they perform. The function groups are:
• PKX_CALL - Functions to accept incoming calls and to make outgoing calls.
• PKX_CHANNEL - Functions to connect and disconnect channels (half duplex or full duplex), and to perform media processing functions (such as play, record, tone generation and detection, and digit detection and generation) on a channel.
• PKX_CONF - Functions to create and destroy conference objects, and to add channels to and remove channels from conferences.
• PKX_ERROR - A function to translate PK_STATUS error codes from a numeric value to a meaningful text string.
• PKX_EVENT - A function to translate event identifiers from a numeric value to a meaningful text string. • PKX_GROUP - Functions to get group object handles and information about the configuration of the group. • PKX_MESSAGE - Functions to customize protocol messages.
• PKX_SYSTEM - Functions to allow the user application to control the state of the system object, and to configure, inject, and retrieve events from the event queue.
• PKX_USER - Functions to dynamically create and manage user configurations.
All functions (except PKX_ERROR_GetText and PKX_EVENT_GetText) return a value of type PK_STATUS. A return value of PK_SUCCESS indicates the function was performed properly. Any other return value indicates an error occurred. PIKA Errors in the PIKA GrandPrix API Reference lists the return values that may be returned from GP functions. All error return values are negative and are in the range of 0X5000 to 0X5FFF.
PKX_ERROR_GetText and PKX_EVENT_GetText return PK_CHAR* pointers to a string, which simplifies using them in string generation functions (for example, printf).
When the system object is opened, the configuration files are read and all objects are created. The configuration files define the groups that can be created and the channels that belong to each group. The system object provides the list of the names of the groups defined in the configuration files through the PKX_SYSTEM_GetConfig function. Handles to the group objects can be retrieved by passing the group name to the PKX_GROUP_GetHandle function. Handles to the channels for each group can be retrieved through the PKX_CHANNEL_GetHandle function.
The user application may retrieve these handles and determine group types and configurations before calling the PKX_SYSTEM_Start function. The PKX_SYSTEM_Start function starts all call processing. This means that call events may be generated immediately after the PKX_SYSTEM_Start function is called.
When a call arrives at the user application, a PKX_EVENT_GROUP_INCOMING_CALL event is generated. The event specifies the group and channel on which the call is arriving as well as the call handle created to manage the call. When initiating a call, the user application may select any unused channel of the appropriate type of group. Two channels can be connected to each other using either the PKX_CHANNEL_HalfDuplexConnect or the PKX_CHANNEL_FullDuplexConnect functions. Channels can be added to a conference through the PKX_CONF_AddMember function. Media processing functions, such as play, record, tone detection, and tone generation, can be applied to channels.
GP Structures - Detailed information on the structures used by the functions is provided in the PIKA HMP High
5
Level API Reference. All GP structures have the prefix PKX_T. Information about the base types and constants used in GP is found in Base Types in the PIKA GrandPrix API Reference.
GP Configuration Files - Detailed information on the format and contents of the configuration files can be found in the PIKA HMP High Level API Configuration Guide.
5.2
Design Guidelines
User applications should be designed to take into account the asynchronous, real-time nature of typical telephony application and follow best practices coding standards.
Asynchronous Applications - To develop an effective application using GP, the design must take into account the asynchronous nature of the GP architecture. Events can be generated at any time. These events reflect significant changes (such as the arrival of an incoming call, calls being disconnected from the other end, or call state change protocol messages being received) on the underlying interface boards. As these events are generated, they are placed, in chronological order, in the event queue. The user application is responsible for retrieving the events from the queue and processing the event. Events are retrieved from the queue in the order in which they were placed in the queue.
Real-Time Applications - When designing a media processing application, it is important to consider the real-time aspects of the system, the resource needs of the system, and what other devices and applications will compete for processor resources. If the deployment platform does not have sufficient resources to meet the requirements of the user application and all other applications running on it, the quality of the media processed by the user application may deteriorate. To design user applications, you must take into account:
• Typical Deployed System Sizes - Tests should be performed to determine the minimum requirements for the applications to be deployed. This allows you to specify system requirements (such as CPU power, memory, and number of threads), ensuring sufficient resources are available for the application to run efficiently. The application may need different configuration specifications for small, medium, or large deployments.
• Operating System I/O - In a real-time system, it is important to limit the file open, close, read, and write
operations. For example, when audio messages and prompts are played often, read and store them into memory at application start. This reduces the file I/O burden on the system during application operation.
• Memory Management - System calls are very processor intensive. If the application can avoid executing system calls during normal operations, the application uses fewer processor resources. One method of reducing system calls is to create a self-managed memory pool within the application, which is much more efficient than requesting and
returning memory to the operating system each time it is required.
• The user application can create or open sufficient conference objects for typical operation at system start-up. The user application then manages pools of these objects, assigning them as needed. This reduces processing time during peak load application operation.
• One approach to memory management is to allocate memory and objects at program initialization, based on a typical deployment. As more memory or objects are required, allocate or create them and add them to the pools. This allows the amount of memory in the pool and the number of objects created to grow, ensuring all
requirements of the application are met.
• Another approach to memory management is to create templates for different system deployment sizes (for example: small, medium, and large). Have each template allocate and create sufficient memory and objects for the expected maximum use for the deployment size.
• Logging - During application development, application logging is an extremely useful tool, however, extensive logging can significantly reduce application performance. When an application is deployed, it should perform a minimal amount of application logging.
• If more logging information is required to debug field issues, the logging level can be increased as required to isolate the problem. The logging level should be returned to normal once the problem is resolved.
• If more extensive debugging is required, a debugger can be attached to a deployed application. Where possible, send the debug information to a separate platform. This reduces the effect the debugger has on the processor of the deployed application. Please contact Customer Care (pg. 2) for the symbol files.
• Competing Resources - Hard drives, NICs, and other third-party devices can heavily load a system. It is important to choose the right devices. It is also important to use a device's native drivers. The default OS drivers for these devices are not as efficient as the native drivers.
• Backups and virus checkers heavily load a system as well. These applications should be scheduled for off-peak hours and not be run during busy times on a real-time system.
• Multi-threading and Multi-processor Configurations - To allow the application to take advantage of multi-processor and hyper-threading processor systems, use the following compile option:
• Windows: In Visual Studio, under Configuration Options / C/C++ / Code Generation, the runtime library "Multi-threaded (/MT)" or "Multi-threaded Debug (/MTd)" should be selected.
Coding Guidelines - PIKA Technologies recommends that software developers follow a standard set of coding guidelines. Each of these guidelines helps to produce code easy to understand, debug, and modify. These guidelines become especially important when contacting PIKA Technologies Customer Care department. A properly designed program helps technical support personnel identify problem areas in code, resulting in faster, more efficient technical support.
• Checking GP Return Status - All API functions return a status of type PK_STATUS. User applications should compare this status to PK_SUCCESS after every API function call. A complete list of API error return status codes can be found in PIKA HMP High Level API Reference - PIKA Errors.
• Defines and Type Definitions - The API uses a specific set of defines and type definitions for identifying
5
parameters passed to and from functions. These defines and type definitions should be used whenever possible to keep GP-specific code consistent. See PIKA HMP High Level API Reference - Base Types for a complete listing.
5.3
Basic Functions
Basic GP functions can be broken into the following categories: • System Start and Shutdown (pg. 16)
• Event Queue (pg. 18) • Application Logging (pg. 22) • Call Processing • Initiating a Call (pg. 29) • Receiving a Call (pg. 44) • Joining Calls (pg. 51) • Call Transfer (pg. 60) • Terminating a Call (pg. 76) • Media Processing
• Playing a Stored Message (pg. 78)
• Recording Audio Data from a Channel (pg. 84)
• Collecting DTMF Digits from a Channel (pg. 88)
• Sending DTMF Digits to a Channel (pg. 90)
• Generating Tones on a Channel (pg. 91)
• Detecting Tones on a Channel (pg. 93)
• Detecting Speech on a Channel (pg. 94)
• Audio Flags (pg. 95)
• Media Processing Termination Conditions (pg. 97)
• Fax Processing (pg. 100)
• Conferencing (pg. 110)
• Phones (pg. 113)
5.3.1
System Start
The first function called when the user application starts must be PKX_SYSTEM_Open function. This function reads the configuration files and creates all the group and channel objects specified by the configuration files. The user application can then retrieve the group object handles using the PKX_SYSTEM_GetConfig and
PKX_GROUP_GetHandle functions. The group type and number of channels can be determined using the
PKX_GROUP_GetConfig function. The user application typically initializes its own internal structures in anticipation of processing calls. At this point, no media processing can be performed and no events are generated. After the user application is ready to process calls, it calls the PKX_SYSTEM_Start function. PKX_SYSTEM_Start initializes any underlying hardware, starts the call processing message stacks, and makes the media processing function available. Immediately after the PKX_SYSTEM_Start function is called, the user application can receive events and perform media processing.
The user application then either initiates calls using the PKX_CALL_Make function or waits for an event using the PKX_SYSTEM_WaitOnEvent function.
The following diagram shows the typical flow of processing during the user application start-up.
5
When the user application is shutting down, it should first call the PKX_SYSTEM_Stop function. This terminates all call and media processing within the system. All existing calls are terminated. The user application should then call PKX_SYSTEM_Close as the last function to shut down the PIKA software cleanly. This invalidates all handles, closes all opened low-level resources, and discards any outstanding events. Pending calls to PKX_SYSTEM_WaitOnEvent immediately return the PKX_EVENT_SYSTEM_SHUTDOWN event. Subsequent calls to
PKX_SYSTEM_WaitOnEvent fail and return a status of PKX_ERROR_SYSTEM_IS_NOT_ENABLED.
A user application can determine the current state of the system object using the PKX_SYSTEM_GetState function. The following table lists the object states returned by this function:
Object State
Value Returned
The object does not exist or has not been opened. PKX_OBJECT_STATE_DISABLED
The object has been opened but not started. PKX_OBJECT_STATE_ENABLED
The object has been started. PKX_OBJECT_STATE_RUNNING
Tips
For user applications that do not initiate calls (such as IVR applications), it is not necessary to get the group names and handles at application start-up. The PKX_EVENT_GROUP_INCOMING_CALL event contains the group handle in the event handle field, the channel handle in the event p0 field, and the call handle in the event p1 field.
Example
This example shows the Initialize and Cleanup functions in ivr.cpp source file of the Interactive Voice Response sample application.
The initialization function: • Opens the system object • Retrieves the group names • Retrieves the group handles
• Retrieves the number of channels in each group • Retrieves the channel handles
• Starts the system object The Cleanup function: • Stops the system object • Closes the system object
5.3.2
Event Queue
All GP objects generate events asynchronously. An event is a message about a significant occurrence that happened to the object during its operation.
To manage events, GP creates an event queue when the system is started. As events are created, they are placed in the event queue in chronological order. The user application retrieves events from the event queue using the
PKX_SYSTEM_WaitOnEvent function. Event information is placed in the application-supplied PKX_TEvent
5
structure. The PKX_TEvent structure returned contains the following information:
Event
Member
Description
id The event identifier. See PIKA Events for a description of the event identifiers associated with each type of object.
handle The handle of the object that generated the event. This handle can be PK_HANDLE_NONE for an application-injected event, a PKX_EVENT_SYSTEM_WAIT_TIMEOUT event and a
PKX_EVENT_SYSTEM_SHUTDOWN event.
timestamp The time the event occurred (in milliseconds since the computer was started). This value can be used to determine the relative time between events.
userData The userData value for the object set through the PKX_SYSTEM_SetEventUserData function. A value of NULL is provided unless the user application has called the PKX_SYSTEM_SetEventUserData function to set a new value for the object generating the event.
p0 Event dependent data. See PIKA Events for a description of the data associated with each type of event. p1 Event dependent data. See PIKA Events for a description of the data associated with each type of event. p2 Event dependent data. See PIKA Events for a description of the data associated with each type of event. The timeout parameter provided to the PKX_SYSTEM_WaitOnEvent function determines whether the function blocks until an event is available, returns immediately, or waits for the specified period if no event is available. The following table details the timeout values and under what conditions the PKX_SYSTEM_WaitOnEvent function returns.
Timeout Value
Return Conditions
PKX_SYSTEM_QUEUE_NON_BLOCKING The function returns immediately, whether an event is available in the queue or not. If an event is not available, the function returns an event with an identifier of
PKX_EVENT_SYSTEM_WAIT_TIMEOUT.
PKX_SYSTEM_QUEUE_WAIT_FOREVER If an event is available, the function returns immediately with the event. The function does not return until an event is available.
Any other value If an event is available, the function returns immediately with the event. The function does not return until an event is available. If no event is available before the number of
milliseconds specified by the timeout value, the function returns an event with an identifier of
PKX_EVENT_SYSTEM_WAIT_TIMEOUT. The following diagram shows the AoH thread and the user application (using the PKX_SYSTEM_InjectEvent function) adding events to the end of the queue as they are generated. The user application retrieves these events (using the PKX_SYSTEM_WaitOnEvent function) from the head of the queue.
When events are retrieved from the event queue, they should be checked to determine if the event is a PKX_EVENT_SYSTEM_WAIT_TIMEOUT or PKX_EVENT_SYSTEM_SHUTDOWN event. A PKX_EVENT_SYSTEM_WAIT_TIMEOUT event indicates that no event has been generated in the timeout period. The user application may perform any housekeeping activities and then call the PKX_SYSTEM_WaitOnEvent function again to wait for the next event to occur. The PKX_EVENT_SYSTEM_SHUTDOWN is generated by the PKX_SYSTEM_Close GP function and indicates the application is shutting down. No more events are received and no media processing can be performed.
GP provides the following additional functions to allow the application to manage the event queue:
5
GP API Function
Description
PKX_SYSTEM_FlushEvents Discards all events in the system event queue. Events should not be discarded in a normal production system.
PKX_SYSTEM_SetEventUserData Sets the userData field of the PKX_TEvent structure for all events pertaining to the specified object. This function is normally called the first time a new handle is retrieved by the application.
PKX_SYSTEM_GetEventUserData Retrieves the application-defined information set in the userData field of the PKX_TEvent structure for all events pertaining to the specified object. A value of NULL is returned when the user application has not called the PKX_SYSTEM_SetEventUserData function to set a userData value. PKX_SYSTEM_InjectEvent Allows a user application to raise custom events to their event processing
thread. These events are received in the same fashion as any other event. When injecting an event into the event queue, the user application must provide a valid object handle or specify PK_HANDLE_NONE in the PKX_TEvent handle field. When a valid object handle is used, the userData value for that object is automatically placed in the userData field of the event. User application defined events should use id values in the range 0x7000 to 0x7FFF.
Tips
The value for the event identifier specified is not restricted to the values generated by GP objects. This allows the user application to signal special events to the event handler. Injecting events can be used for a number of purposes: • Signaling from the main application to the event handler thread
• Testing application event handling • Simulating error conditions
• Recreating a series of events that cause an application failure
Example
This example is taken from the EventProcessing function of the ivr.cpp file of the Interactive Voice Response sample. The function waits until an event is available. When an event is received, the event is check to see if it is the shutdown event. When the shutdown event is received, the function exits. Otherwise the function processes the event and then loops back and calls the PKX_SYSTEM_WaitOnEvent function again to wait for the next event.
5.3.3
Application Logging
Logs are used to track the progress of the application and to determine what is happening within the application. The high level API provides extensive capabilities and flexibility to control high level and low level logging for debugging user applications. Log entries can be generated by:
• API calls (high and low level)
• HSP internal media processing engine (low level API) • Objects (high and low level API)
• Internal SIP processing (low level API) • Internal ISDN processing (low level API) • Internal CAS processing (low level API) • Internal objects (high and low level API) • Events (low level API)
• The user application
The high level API controls which log messages are generated for itself and the low level components. Logging for each component can be configured separately. See the PIKA HMP High Level API Configuration Guide for more information about how to configure the generated log messages.
Tips
Take care to log only information necessary to determine that the application is performing correctly. Excessive logging can impair application performance.
5.3.3.1
Log File Management
Managing the log files refers to controlling the location, size, and number of log files generated by the application. These items are controlled by the environment variable PKH_LOGS_DIR, and entries in the configuration file (Default: pikagp.cfg), see the PIKA HMP High Level API Configuration Guide for more information. The size and number of log files determine the amount of disk space consumed by the logs.
Log File Names - The format of log file names is: pikagp_#.log, where # is the log sequence number. The sequence numbers start at one and are incremented by one for each new file.
Log File Location - High level API log files are placed in the directory specified in the PKH_LOGS_DIR environment variable under a separate sub-folder for each run of the application. Default log directories: • Windows XP and Windows Server 2003 - C:\Program Files\PIKA\hmp\logs
• Windows 7 and Windows Server 2008 - C:\ProgramData\PIKA\hmp\logs • Linux - /var/log/pika
The format of the sub-folders name is: gp_<date>_<time in 24 hour format>
Log files generated by the low level API are placed in separate directories. Refer to the low level API documentation, available on the PIKA Support web page.
The timestamps on the log messages are used to coordinate log entries of the high level and low level API components. There are separate configuration entries to control high level and low level component logging.
Log File Size - The size of each log file is controlled by the size and aoh.size keys (default: 12 M) in the log settings section in the configuration file. When a log file grows to be larger than the size specified, the log file is closed. A new log file, with the log number incremented, is opened. New log entries are recorded in the new log file.
Number of Log Files - When opening a new log file causes the number of log files in the current log directory to exceed the maximum number of log files specified by the files and aoh.files keys (default: 2) in the log settings section of the configuration file, the oldest log file is deleted.
Example
Configuration files, log number, and size examples:
Five 20 MB high level API logs are generated. When the sixth file is opened, the first file generated is deleted. Two 100 MB low level API logs are generated. When the third file is opened, the first file generated is deleted.
[logs] level=none files=5 size=20 aoh.level=none aoh.files=2 aoh.size=100
File name examples:
C:\Program Files\PIKA\hmp\logs\gp_060327_154213\pikagp_2.log C:\Program Files\PIKA\hmp\logs\gp_060327_154213\pikagp_3.log
5.3.3.2
User Application Logging
The high level API provides a mechanism to allow the programmer to log messages to the log file from code outside the HMP libraries. The function PKX_SYSTEM_LogUserMessage is used to add messages to the PIKA system log file.
Each call to the PKX_SYSTEM_LogUserMessage function specifies the following information: • Log message type
• Log level
• Log message format string • Optional log message parameters
Log Message Type - The log message type determines how the message is constructed. Normal messages start on a new line and have a header that contains a date and time stamp and thread id prefixed to the message text.
The following table lists the different message types and how the log message is constructed for each type.
Log Message Type
Message Construction
PKX_LOG_TYPE_NORMAL Start the log message with the standard log prefix (new line, time and date stamp, thread id).
PKX_LOG_TYPE_INDENT Start the log message on a new line without a timestamp.
PKX_LOG_TYPE_CONTINUE Display the log message without the standard prefix. This is normally used to continue adding information to an existing log message.
Log Level - This bitmap assigns a user-defined numerical value from 1 to 31 to the log. This value is a means to filter the logs output by the user application. The bits set in the bitmap and the value of the level parameter under the [logs]
section in the root configuration file determine which logs are output. If the level parameter in the configuration file is set to brief, only user logs with levels 1 or 2 are output (0x00000001 or 0x00000010). If level is set to debug, all user logs are output.
Log Message Format String and Parameters - The log message format string and optional parameters follow the same rules as printf. If parameters follow the format string, the format string must contain printf-style format specifications that determine the output format for each parameter.
NOTE: No "\n" is required at the end of the string. Log messages (other than PKX_LOG_TYPE_CONTINUE log messages) automatically start on a new line. Log messages are flushed to the file immediately after being written.
Example
PK_STATUS status;
PK_CHAR errorString[MAX_STRING_LENGTH];
if ((status = PKX_SYSTEM_LogUserMessage(PKX_LOG_ALL_ERROR, PKX_LOG_TYPE_NORMAL,
"Invalid user option entered: %s.",user_option)) != PK_SUCCESS)
cout << "\nUser log call failed." <<
PKX_ERROR_GetText(status,errorString,sizeof(errorString)) << endl; if ((status = PKX_SYSTEM_LogUserMessage(PKX_LOG_ALL_ERROR,
PKX_LOG_TYPE_CONTINUE,
"This line is appended to the last log message")) != PK_SUCCESS)
cout << "\nUser log call failed." <<
PKX_ERROR_GetText(status,errorString,sizeof(errorString)) << endl; if ((status = PKX_SYSTEM_LogUserMessage(PKX_LOG_ALL_ERROR,
PKX_LOG_TYPE_INDENT,
"This line starts on a new line without a time stamp")) != PK_SUCCESS)
cout << "\nUser log call failed." <<
PKX_ERROR_GetText(status,errorString,sizeof(errorString)) << endl;
5.3.4
Call Processing
Call processing includes: • Initiating a call (pg. 29)
• Receiving a call (pg. 44)
• Joining calls (pg. 51)
• Terminating a call (pg. 76)
• Holding and resuming calls (pg. 53)
• Transferring Calls (pg. 60)
Two of the key features GP provides are call progress and call analysis. Call progress defines the meaning of tone
patterns (such as ringing, busy, fast busy) received from remote devices. Refer to the Call Progress section of the GP Configuration Guide for information about configuring call progress tones. Call analysis detects what answered the call (live person, answering machine, modem, FAX, or SIT message). When a call analysis signal is detected, an event is generated and placed in the queue. Refer to section Call Analysis (pg. 33).
Call States
As a call is being made or received, it goes through a number of states. The user application can determine the current state of a call using the PKX_CALL_GetState function. This function can be used at any time during the existence of a call. The state parameter is set to PKX_CALL_STATE_IDLE when the call object no longer exists, and the
PKX_ERROR_OBJECT_INVALID_HANDLE error is returned. The following table lists the call states that can be returned and are defined in enumerated type PKX_TCallState.
Call State
Description
PKX_CALL_STATE_IDLE Call is idle or non-existent.
PKX_CALL_STATE_DIALING Outgoing call is dialing using the specified address information. PKX_CALL_STATE_PROCEEDING Outgoing call has transmitted all necessary address information. PKX_CALL_STATE_ALERTING Incoming or outgoing call is alerting (ringing).
PKX_CALL_STATE_OFFERED Incoming call is being offered to the user application. PKX_CALL_STATE_CONNECTED Incoming or outgoing call is connected.
PKX_CALL_STATE_DISCONNECTED Incoming or outgoing call is disconnected. PKX_CALL_STATE_INITIATED An outgoing call attempt has started.
The following diagrams show the call state machine for outgoing and incoming calls. Call state transitions can be caused by:
• Function calls (for example: PKX_CALL_Drop()) • Actions of the remote device (for example: Remote reject)
• Actions of the lower-level components (for example: Low-level or protocol resources released)
The cause of each state transition is shown in blue. When a call enters some states, events can be generated. The events that can be generated when the call enters a state are shown in red. When a call enters the Idle state, a
PKX_EVENT_CALL_DISCONNECTED event is generated if the remote device caused the disconnection, or a PKX_EVENT_CALL_DROPPED event is generated if the user application disconnected the call using the PKX_CALL_Drop function.
The NULL state indicates the call does not exist and does not have a valid handle. A call is initiated (and has a state) by the user application calling the PKX_CALL_Make or PKX_CALL_Transfer function, or a call is detected by the lower-level components. The call transitions to PKX_CALL_STATE_DIALING shortly after passing through PKX_CALL_STATE_INITIATED. The call handle is provided in the
PKX_EVENT_GROUP_INCOMING_CALL event. The PKX_CALL_Release function releases the call and invalidates the call handle.
The PKX_EVENT_CHANNEL_IN_USE event is only generated by the Offered state if the call has gone from the NULL state to the Offered state directly, without passing through the Detected state. The
PKX_EVENT_CHANNEL_READY event is only generated by the NULL state if the call was rejected.
The PKX_CALL_Release function does not actually change the state of the call but rather destroys the call object, invalidating the call handle.
Channel States
Channels can be in one of the following states:
5
Channel State
Description
PKX_CHANNEL_STATE_DOWN Channel is out-of-service and not available for initiating or receiving calls. PKX_CHANNEL_STATE_READY Channel is in-service and available for initiating or receiving calls.
PKX_CHANNEL_STATE_IN_USE Channel is in-service and in use by an active call.
When a channel changes state, an event is generated indicating its new state. The following diagram shows the channel states, the events generated for each state (in red) and the actions (in blue) that caused the channel to change state. The lower level components move a channel into and out of the Down state. The user application cannot place a channel in or remove a channel from the Down state. A channel in the Down state cannot be used to make a call.
5.3.4.1
Initiating a Call
The user application calls the PKX_CALL_Make function. The following diagram shows the typical processing flow when a call is initiated:
The information that must be specified when initiating a call is channelHandle, info, and settings.
channelHandle
The handle of the channel on which to make the call. Channel handles may be retrieved using the PKX_CHANNEL_GetHandle function.
info
The following information should be supplied in the PKX_TCallInfo structure when placing the call: • to - called party identification
• from - calling party identification
• display - calling party display information
• callingNumberRestricted - a flag indicating to the remote party that they are not authorized to view the calling party information; as opposed to the information is simply not available
• forwardedFrom - indicates the party that forwarded the call to the current destination • custom - custom call settings, not applicable to all channel types
The format of the called and calling number or identification depends on the channel group type. Refer to Called and Calling Number Formats (pg. 37).
NOTE: The far end may ignore calling number and caller identification depending on the protocol used and the terminating device.
settings
Settings that affect call behavior:
• timeout - The amount of time (in milliseconds) to wait for the remote end to answer the call. If the call is not answered within the timeout period, the call is dropped and a PKX_EVENT_CALL_DISCONNECTED event is generated with a disconnected reason of PKX_CALL_DROP_CAUSE_NOANSWER.
• callAnalysis - Specifies the call analysis parameters to use for detection: • enable - indicates whether call analysis should be enabled for the call.
• type - specifies the analysis to perform to determine who/what answered the call: person, answering machine, fax, modem, or SIT message. This value may be ORed combinations of the call analysis detect constants or
PKX_CALL_ANALYSIS_DETECT_SPEECH (default). The table in section Call Analysis (pg. 33) lists the events generated each type entity answers the call.
• speechDebounceOn - minimum time (in milliseconds) of continuous speech before a sound segment is recognized as speech. Filters out short clicks, tones, and noise. [30 to 300 ms; default: 250 ms]
• speechDebounceOff - minimum time (in milliseconds) specified to filter out short periods of time where no speech is detected, for example, a short pause between words. Only if speech is not detected for longer than speechDebounceOff, is an end of speech segment declared. [30 to 300 ms; default: 250 ms]
• livePersonWords - maximum number of live person words. A larger number of words is considered to come from an answering machine. [1 to 10; default: 3]
• maxDuration - maximum time (in milliseconds) to wait before terminating the attempt to identify the specified analysis type [default: 2000 ms]
• speechEndTime - maximum silence time (in milliseconds) after speech for call analysis to determine if the response came from a live person or answering machine. [500 to 3000 ms; default: 1500 ms]
• livePersonMaxTime - maximum duration (in milliseconds) of a speech segment for a live person response. A longer speech segment is considered to come from an answering machine. [500 to 3000 ms; default: 2500 ms] • Refer to the section Call Analysis (pg. 33) for information on how the parameters are used.
The PKX_CALL_Make function returns immediately. At this point, the call has not been made but the processing required to make the call proceeds in another thread. As the call progresses, the user application asynchronously receives call events indicating the call progress. The following table lists the call events the user application may receive after calling the PKX_CALL_Make function.
Call Event
Indicates
PKX_EVENT_CALL_DIALING dialing has started.
PKX_EVENT_CALL_PROCEEDING dialing has successfully
completed
PKX_EVENT_CALL_ALERTING remote device has begun
alerting the called party. PKX_EVENT_CALL_ANALYSIS_DETECTED_ANSWERING_MACHINE call was answered by an
answering machine. PKX_EVENT_CALL_ANALYSIS_DETECTED_LIVE_PERSON call was answered by a live
person.
PKX_EVENT_CALL_ANALYSIS_DETECTED_MODEM_FAX call was answered by either a modem or fax machine.
PKX_EVENT_CALL_ANALYSIS_DETECTED_SILENCE call was answered, but no audio is present
PKX_EVENT_CALL_ANALYSIS_DETECTED_SIT_MESSAGE call was answered by a SIT message: non-standard, no circuit, operator intercept, vacant circuit, or system busy, and is indicated in the event parameter p1
PKX_EVENT_CALL_ANALYSIS_DETECTED_UNKNOWN call was answered but none of the analysis types enabled for the call matched the audio received
PKX_EVENT_CALL_CONNECTED called party has answered the
call.
PKX_EVENT_CALL_DISCONNECTED call has been terminated. The
event parameter p1 contains the reason the call was terminated.
PKX_EVENT_CALL_EARLY_MEDIA there is audio information
present on the bearer channel
PKX_EVENT_CALL_HELD call has been put on hold by a
remote switch as part of a call transfer.
PKX_EVENT_CALL_RESUMED call placed on hold as part of a
call transfer has been resumed.
5
The following table lists the reasons a call may be disconnected.
Call Disconnected Reason
Description
PKX_CALL_DROP_CAUSE_NORMAL The remote end has dropped the call in a normal fashion (hung up). PKX_CALL_DROP_CAUSE_BUSY The remote end is busy and cannot respond to the call attempt. PKX_CALL_DROP_CAUSE_FASTBUSY An error in routing the call has occurred, resulting in a fast busy
tone being received from the remote end.
PKX_CALL_DROP_CAUSE_REORDER An error in routing the call has occurred, resulting in a re-order tone being received from the remote end.
PKX_CALL_DROP_CAUSE_NOANSWER The remote end did not answer the call within the timeout specified. PKX_CALL_DROP_CAUSE_NODIALTONE No dial tone was present on the line when the call was attempted. PKX_CALL_DROP_CAUSE_RESET The call has been reset due to the channel going down or the reset
command being issued.
PKX_CALL_DROP_CAUSE_TRANSFER The call has been transferred to the remote switch.
PKX_CALL_DROP_CAUSE_FAILED The call has been dropped because the bearer path was not established.
If the PKX_CALL_Make call specifies a channel in use (possibly the channel was used by an incoming call and that call's PKX_EVENT_GROUP_INCOMING_CALL has not yet been retrieved from the event queue), the user application receives a PKX_EVENT_CALL_TASK_FAILED event with
PKX_ERROR_CHANNEL_ALREADY_IN_USE specified in the p1 field of the event.
5.3.4.1.1
Call Analysis
Call analysis is the process used to determine who/what has answered the call: live person, answering machine, fax/modem, or Special Information Tone (SIT) message. Call analysis is based on the speech response duration to determine whether a live person or an answering machine answered the call, and tone detection to determine whether a fax/modem or SIT message answered the call. When using call analysis, the detection of a live person will always be enabled.
Some speech analysis application examples are:
• Telemarketing and outbound call centers: connecting an agent to a call only if a live person answers the call. Some centers also wish to differentiate between business and residential phones, only connecting for a residential live person.
• Voice messaging: playing a prerecorded message to live persons and answering machines, but not fax machines. The following table shows some examples of how speech response durations affect the decision: live responses from home/cell phones are short words or phrases with relatively long periods of silence between them, answering machine responses are typically one or more sentences with a few short periods of silence between them, and live responses from business phones fall somewhere between the two.
Response
Usually Indicates
One short word: “Hello?” live person on a home/cell
phone
Short burst word/sentences: “Hello?” “Who is this?” “Hello?” live person on a home/cell phone
Short burst sentences: “PIKA Technologies.” “How can I help you?” live person on a business phone
One long sentence: “Good morning, this is PIKA Technologies.” live person on a business phone
One long sentence: “You have reached the main office of PIKA Technologies, please leave a message.”
answering machine
More than one long sentence: “Welcome to PIKA Technologies. If you know the extension of the person you wish to speak to, enter it now. If you wish to access the directory, press 1 now. If you wish….”
answering machine
One short sentence: “Leave a message.” or “You know what to do.” answering machine
NOTE: The business phone long response is very similar to an answering machine response; an answering machine with one short sentence is very much like a live person.
Debounce is used to remove speech detection glitches, and filter speech segments from clicks, ringback tones, noise, etc. The parameters used to configure debounce are speechDebounceOn and speechDebounceOFF. Speech ON and OFF segments, after debounce, are processed according to livePersonMaxTime, livePersonMaxTotalTime, speechEndTime, and
livePersonWords.
The livePersonMaxTotalTime parameter specifies the maximum accumulated amount of speech on time before concluding that an answering machine has answered the call. This is used when there are multiple short speech segments which are individually shorter than livePersonMaxTime separated by silence segments shorter than speechEndTime, but where the total
5
accumulated speech segment time exceeds the value of livePersonMaxTotalTime.
The maxDuration paremeter specifies the amount of time to allow before ending the attempt to detect the specified analysis type. If this time expires and no audio was detected, the
PKX_EVENT_CALL_ANAYLSIS_DETECTED_SILENCE event will be raised. If audio was detected, but did not match the pattern specified in the type field, the PKX_EVENT_CALL_ANALYSIS_DETECTED_UNKNOWN event will be raised.
If speech is detected and the length of speech after debounce is within specified limits, a live person is assumed to have answered the phone. The following illustration demonstrates how the parameters are used.
Tone detection detects a fax, modem, or SIT message. SIT messages are prerecorded messages played by Telcos indicating a problem handling a call request. Each SIT message is preceded by a sequence of three special tones that are recognized by the call-processing algorithm. The following illustration shows how the tones are processed to determine whether a SIT message was received and which message it is.
Applications may be set up to delete numbers not in service from the database, or move a busy number to the bottom of the queue to try again. SIT message types and the corresponding GP messages (indicated by the p1 field in the event) are described in the following table.
SIT
Message
Indicates
GP Message
Non-standard A user-defined message. The incoming SITs are coded in hexadecimal by multiplying the first detected SIT id by 100 (hex), the second SIT id by 10 (hex), and the third SIT id by 1 (hex). The three results are added and returned as the p2 field in the event. Constants can be defined for non-standard SIT messages and assigned to corresponding p2 values.
PKX_CALL_ANALYSIS_SIT_MESSAGE_USER
5
No Circuit There is a failure to find a trunk or calls affected by network management controls. Try again later.
PKX_CALL_ANALYSIS_SIT_MESSAGE_NO_ CIRCUIT
Operator Intercept
The number has been disconnected, changed, temporarily suspended, has incoming call restrictions, etc. An announcement specifies the reason and gives instructions.
PKX_CALL_ANALYSIS_SIT_MESSAGE_OPE RATOR_INTERCEPT
Vacant Circuit
The number dialed is not currently assigned to a customer. An announcement specifies the reason and gives instructions. For example, "The number you have dialed is not in service."
PKX_CALL_ANALYSIS_SIT_MESSAGE_VACA NT_CIRCUIT
System Busy (ReOrder)
There is congestion in the network. An announcement specifies the reason and gives instructions. For example, "All circuits are currently busy, please hang up and try your call again."
PKX_CALL_ANALYSIS_SIT_MESSAGE_SYST EM_BUSY
New functions to dynamically enable and disable call analysis. PKX_CALL_EnableCallAnalysis and
PKX_CALL_DisableCallAnalysis.
5.3.4.1.2
Called and Calling Number Formats
ISDN, CAS, and Trunk Channels
For calls made on channels controlled by groups of type isdn, cas, trunk, or phone, the format of the calling and called numbers consists of a string containing only the characters: 0 to 9, A to D, *, #. Trunks allow the following additional special characters to be inserted into the string:
Special
Trunk
Character
Meaning
P Use pulse dialing to transmit the remainder of the string.
T Use tone dialing to transmit the remainder of the string.
W Wait for dial tone to be received before dialing the remainder of the string. & Transmit a hook flash on the trunk.
! Ground the tip and ring for ground start lines. This is typically used to trigger the remote switch to generate dial-tone. , Pause for one second.
The user application should insert a "!w" at the beginning of the analog trunk dial string for Ground Start Lines and a "w" at the beginning of the analog trunk dial string for Loop Start Lines.
ISDN Channels
Additional information can be specified in the calling and called party number for ISDN calls. This may be useful, for example, if the information for the calling and called party are different. The additional fields are separated by a "|" in the value. For any of the fields listed below, a hexadecimal value may be specified in the form of "0xXXXXXXXX" to use a value other than those provided.
Both the calling and called party fields may specify the type of number and the numbering plan.
The type of number is specified as numbertype=value. The valid values are: • "unknown" • "international" • "national" • "network" • "subscriber" • "abbreviated"
The default value is defined by the numbertype ISDN configuration parameter or "unknown" if not present.
The numbering plan is specified as numberplan=value.The valid values are: • "unknown" • "isdn" • "data" • "telex" • "standard"
5
• "private"
The default value is defined by the numberplan ISDN configuration parameter or "unknown" if not present. The numbering plan is normally ignored if the type of number field is set to a value other than "unknown", "international", "national", or "subscriber". However, no restriction is enforced.
In addition to the type of number and the numbering plan information, the value for the calling number may also include screening information and presentation indicator information.
The screening value is specified as screening=value. The valid values are: • "user"
• "passed" • "failed" • "network"
Presentation indicator information is specified as presentation=value. The valid values are: • "allowed"
• "restricted" • "notavailable"
A value in this field, if present, will override the callingNumberRestricted field.
The custom field in the PKX_TCallInfo structure can be used to supply custom call information. Currently it is used only for establishing outgoing ISDN calls. The default bearer capability for ISDN calls is speech. The "custom" field can be used to specify alternate bearer capability information. The field is specified as bearercap=value. In addition to the valid values below, a hexadecimal value may be specified in the form of "0xXXXXXXXX" to use a value other than those provided. • speech • unrestricted • restricted • 3.1 kHz • tones • video
The following example shows how the additional fields may be specified when setting the information required to
initiate a call. PKX_TCallInfo info; memset(&info, 0, sizeof(PKX_TCallInfo)); snprintf(info.to, PKX_CALL_MAX_INFO_LENGTH, "%s|numbertype=national|numberplan=isdn", calledNumber); snprintf(info.from, PKX_CALL_MAX_INFO_LENGTH, "%s|numbertype=national|numberplan=abbreviated|screening=user|presentation=all owed", callingNumber);
snprintf(info.display, PKX_CALL_MAX_INFO_LENGTH, "%s", callingName);
snprintf(info.custom, PKX_CALL_MAX_INFO_LENGTH, "bearercap=unrestricted");
SIP Channels
For calls made on channels controlled by SIP groups, the format of the called and calling numbers string consists of a combination of a username, an IP address or hostname, and a port number.
The following list shows a set of valid called number strings, where the username is 'joe.smith', the destination IP address is '192.1.1.3', the hostname is 'sample.com', and the SIP port is '5060'.
• [email protected] • [email protected]:5060 • [email protected] • [email protected]:5060 • joe.smith • sample.com • sample.com:5060 • 192.1.1.3 • 192.1.1.3:5060
The following list shows a set of valid calling number strings, where the username is 'dan.jones', the IP address is '192.168.3.4', and the hostname is 'mypc.com'.
• dan.jones
• [email protected] • [email protected]
Note that the calling number string, or from parameter, can also be left blank when using the function PKX_CALL_Make to initiate SIP calls. This is a special case that will be further explained below.
5
Outgoing SIP calls are routed according to the information provided in the calling and called numbers, as well as the information found in the SIP configuration sections. Refer to the [sip] and [users] sections in the High Level API Configuration Guide for details about configuring individual SIP groups and SIP user agents, respectively.
The sample SIP configuration shown below will be used to describe how outgoing SIP calls are routed. Note that only parameters that affect how the call is routed are shown.
[sip] sip0=SIP_DEFAULT_0 [SIP_DEFAULT_0] interface=192.168.68.19 ua_port=5060 server_port=0 domain=example.com audio.portrange=24000-24008 channels=4
display_name=SIP Default User [users] user0=PEER_USER user1=PROXY_USER [PEER_USER] user_name=PeerUser domain=example.com display_name=Peer User [PROXY_USER] user_name=ProxyUser domain=example.com display_name=Proxy User password=password proxy.address=192.168.78.133 proxy.port=5060 registration=outbound proxy.outbound=enabled expires=3600
Note that the following call scenarios only show the values of the display, from, and to parameters of the PKX_TCallInfo structure. All other parameters do not affect how the SIP call is routed.
