PIKA HMP 3.0 High Level API Programmer's Guide

Transcription

1 Copyright (c) All rights reserved.

2

3 Table of Contents 1 Copyright Information 1 2 Contacting PIKA Technologies 2 3 Introduction Purpose and Scope Assumed Knowledge Related Documentation 4 High Level API Architecture 4.1 High Level API Object Descriptions System Object States High Level API Object Relationships Application Development API Principles 11.2 Design Guidelines 13.3 Basic Functions System Start Event Queue Application Logging 22 Log File Management 22 User Application Logging Call Processing 2 Initiating a Call 29 iii

4 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 1 Hold and Resume 3 Call Transfer 60 Basic Call Transfer 60 ISDN Call Transfer 71 Terminating a Call 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 9 Media Processing Termination Conditions 97 Fax Processing 100 Fax Diagnostics Conferencing 110 Virtual Channels in Conferences.3.7 Phones iv Building a High Level API Application Distributing a High Level API Application 121

5 7.1 Distributing a PIKA High Level API Application on Windows Distributing a PIKA High Level API Application on Linux Advanced Topics Configuring a Channel SIP User Management 126 Dynamic User Management Modifying the High Level API Source Code Building the High Level API Libraries in Windows Building the High Level API Libraries in Linux Bypassing the High Level API to Make Low-level Function Calls Sample Applications Glossary 144 Index a v

6

7 1 1 Copyright Information 1 COPYRIGHTS Copyright 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. 1

8 2 2 Contacting PIKA Technologies Customer Care 2 For support issues, phone or our Customer Care department at the following: Tel: FAX: support@pikatech.com International Headquarters PIKA Technologies Inc. 3 Legget Drive, Suite 400 Ottawa, Ontario, Canada K2K 3B8 Tel: FAX: sales@pikatech.com Internet Visit our website at for the latest news, product announcements, downloads, online community, documentation updates, and contact information. 2

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

10 3.2 Assumed Knowledge 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. 12) 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") 3 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 for more information on the ISDN standard) An understanding of VoIP to provision configuration files: SIP (See for more information on the SIP standard) 4

11 3.3 Related Documentation RTP (See for more information on the RTP standard) PC hardware and software usage and architecture C/C++ programming 3.3 Related Documentation 3 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.

12 4 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: 4 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 6

13 4.1 High Level API Object Descriptions 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 4 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. 7

14 4.1 High Level API Object Descriptions 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 4 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 8

15 4.2 High Level API Object Relationships 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 System Object States 4 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. 9

16 4.2 High Level API Object Relationships 4 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. 10

17 .1 API Principles 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. 1) 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..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. 11

18 .1 API Principles 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 0X000 to 0XFFF. 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 12

19 .2 Design Guidelines 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..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 13

20 .2 Design Guidelines 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 14

21 .3 Basic Functions System Start 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..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. 1) 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. 9) Media Processing Termination Conditions (pg. 97) Fax Processing (pg. 100) Conferencing (pg. 110) Phones (pg. 113) 1

22 System Start.3 Basic Functions.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. 16

23 .3 Basic Functions System Start 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 17

24 Event Queue.3 Basic Functions 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.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 18

25 .3 Basic Functions Event Queue structure. The PKX_TEvent structure returned contains the following information: Event Description Member 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. 19

26 Event Queue Any other value.3 Basic Functions 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: 20

27 .3 Basic Functions Application Logging 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. 21

28 Application Logging.3 Basic Functions.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 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. 22

29 .3 Basic Functions Application Logging 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 C:\Program Files\PIKA\hmp\logs Windows 7 and Windows Server 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= size=20 aoh.level=none aoh.files=2 aoh.size=100 File name examples: 23

30 Application Logging.3 Basic Functions C:\Program Files\PIKA\hmp\logs\gp_060327_14213\pikagp_2.log C:\Program Files\PIKA\hmp\logs\gp_060327_14213\pikagp_3.log 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 (0x or 0x ). If level is set to debug, all user logs are output. 24

31 .3 Basic Functions Call Processing 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;.3.4 Call Processing Call processing includes: Initiating a call (pg. 29) Receiving a call (pg. 44) Joining calls (pg. 1) Terminating a call (pg. 76) Holding and resuming calls (pg. 3) Transferring Calls (pg. 60) Two of the key features GP provides are call progress and call analysis. Call progress defines the meaning of tone 2

32 Call Processing.3 Basic Functions 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. 26

33 .3 Basic Functions Call Processing 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. 27

34 Call Processing.3 Basic Functions 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: 28

35 .3 Basic Functions Channel State Call Processing 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 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: 29

36 Call Processing.3 Basic Functions 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 30

37 .3 Basic Functions Call Processing 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: 20 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: 20 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. [00 to 3000 ms; default: 100 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. [00 to 3000 ms; default: 200 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. 31

38 Call Processing.3 Basic Functions 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. 32 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.

39 .3 Basic Functions Call Processing 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 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. 33

40 Call Processing.3 Basic Functions 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 34

41 .3 Basic Functions Call Processing 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. 3

42 Call Processing.3 Basic Functions 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 PKX_CALL_ANALYSIS_SIT_MESSAGE_USER 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. 36

43 .3 Basic Functions Call Processing No Circuit There is a failure to find a trunk or calls affected PKX_CALL_ANALYSIS_SIT_MESSAGE_NO_ by network management controls. Try again CIRCUIT later. Operator Intercept The number has been disconnected, changed, PKX_CALL_ANALYSIS_SIT_MESSAGE_OPE temporarily suspended, has incoming call RATOR_INTERCEPT restrictions, etc. An announcement specifies the reason and gives instructions. Vacant Circuit The number dialed is not currently assigned to a PKX_CALL_ANALYSIS_SIT_MESSAGE_VACA customer. An announcement specifies the NT_CIRCUIT reason and gives instructions. For example, "The number you have dialed is not in service." 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 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 Meaning Trunk Character 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. 37

44 Call Processing! 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..3 Basic Functions 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" 38

45 .3 Basic Functions Call Processing "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 39

46 Call Processing.3 Basic Functions 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 ' ', the hostname is 'sample.com', and the SIP port is '060'. joe.smith@sample.com joe.smith@sample.com:060 joe.smith@ joe.smith@ :060 joe.smith sample.com sample.com: :060 The following list shows a set of valid calling number strings, where the username is 'dan.jones', the IP address is ' ', and the hostname is 'mypc.com'. dan.jones dan.jones@ dan.jones@mypc.com 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. 40

47 .3 Basic Functions Call Processing 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= ua_port=060 server_port=0 domain=example.com audio.portrange= 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= proxy.port=060 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. 41

48 Call Processing.3 Basic Functions Scenario Function Parameters Explanation 1 The display and from parameter, or caller id and calling number parameters, are left blank. GrandPrix uses the SIP group information when building the SIP INVITE message. PKX_CALL_Make(display=, from=, to= ) The SIP 'From' and 'To' fields would be built as follows: From: SIP Default User" <sip:example.com:060> To: <sip: > 2 PKX_CALL_Make(display= Hello World, from=, to= ) GrandPrix uses the SIP group information when building the SIP INVITE message since the from parameter is blank. However, the "Hello World" string would replace the caller id information provided by the display_name configuration key in the SIP group. The SIP 'From' and 'To' fields would be built as follows: From: Hello World <sip:example.com:060> To: <sip: > 3 PKX_CALL_Make(display=, from= PeerUser, to= ) GrandPrix uses the information provided in the configuration of the " PeerUser " agent to build the INVITE message. The SIP 'From' and 'To' fields would be built as follows: From: Peer User <sip:peeruser@example.com:060> To: <sip: > 4 PKX_CALL_Make(display= Hello World, from= PeerUser@example.com, to= ) Scenario 4 would result in the same outcome as scenario 3 with the updated caller id. PKX_CALL_Make(display= Hello World, from= PeerUser@ , to= ) Scenario would result in the same outcome as scenario 3. However, the IP address would be used in the 'From' header instead of the domain. The SIP 'From' and 'To' fields would be built as follows: From: Hello World <sip:peeruser@example.com> To: <sip: > The SIP 'From' and 'To' fields would be built as follows: From: Hello World <sip:peeruser@ > To: <sip: > 42

49 .3 Basic Functions 6 Call Processing GrandPrix uses the information provided in the configuration PKX_CALL_Make(display=, from= ProxyUser, to= ) of the "ProxyUser" agent to build the INVITE message. The SIP 'From' and 'To' fields would be built as follows: From: Proxy User <sip:proxyuser@example.com> To: <sip: > 7 8 PKX_CALL_Make(display=, from= ProxyUser@ , to= ) This would result in the same outcome as scenario 6. PKX_CALL_Make(display=, from= Testing, to= ) GrandPrix uses the SIP group information when building the SIP INVITE message since the "Testing" user was not configured. The SIP 'From' and 'To' fields would be built as follows: From: From: Proxy User <sip:proxyuser@ > To: <sip: > The SIP 'From' and 'To' fields would be built as follows: From: SIP Default User" <sip:testing@example.com:060> To: <sip: > 9 PKX_CALL_Make(display=, from=, to= :090 ) This would behave the same way as scenario 1. The only difference is that the INVITE message would be sent to SIP port 090 instead. The SIP 'From' and 'To' fields would be built as follows: From: SIP Default User" <sip:example.com:060> To: <sip: :090> 10 PKX_CALL_Make(display=, from=, to= pika@ :090 ) This would behave the same way as scenario 9. The only difference is that the INVITE message will be sent to SIP user 'pika'. The SIP 'From' and 'To' fields would be built as follows: From: SIP Default User" <sip:example.com:060> To: <sip:pika@ :090> 43

50 Call Processing 11 PKX_CALL_Make(display=, from= ProxyUser, to="sipura ).3 Basic Functions This scenario could behave in two different ways depending on the value of the proxy.outbound key in the "ProxyUser" user configuration section. If proxy.outbound is enabled, "sipura" is used as a username/extension and the SIP 'From' and 'To' fields would be built as follows: From: Proxy User <sip:proxyuser@example.com> To: <sip:sipura@ :060> If proxy.outbound is disabled, "sipura" is used as a hostname and the SIP 'From' and 'To' fields would be built as follows: From: Proxy User <sip:proxyuser@example.com> To: <sip:sipura:060> Call Initiation Examples Example The first example is taken from the initialize function in msgblast.cpp of the Message Distribution sample application and sets up the caller information used for all outgoing calls. The second example is taken from the getnextphonenumber function in the same source file and demonstrates how to make an outgoing call using the high level API. The number to call is retrieved from a file and inserted into call information structure Receiving a Call When an incoming call arrives, the user application receives a PKX_EVENT_GROUP_INCOMING_CALL event. The handle of the group receiving the call is specified in the event handle field. The handle of the channel on which the call was received is specified in the p0 field. The handle of the object created to represent the call is specified in the p1 field. The user application then calls the PKX_CALL_GetInfo function which returns the call information (PKX_TCallInfo), including the called address and calling identification information. The user application uses this information to determine who is calling and who they are attempting to call. The PKX_TCallInfo structure contains the following: 44

51 .3 Basic Functions Call Processing to - the called number or identification from - the calling number or identification display - caller identification information callingnumberrestricted - if set to PK_TRUE, the calling number information has been restricted by the remote party forwardedfrom - indicates the party that forwarded the call to the current destination party custom - custom ISDN call setting used to specify bearer capability information When the call is destined for a device other than the user application, the PKX_CALL_Accept function should be called to indicate the user application is attempting to reach the called party. The PKX_CALL_Accept function returns immediately, while lower level processes send the appropriate accept message to the calling party. When the accept message has been sent, the user application receives a PKX_EVENT_CALL_ACCEPTED event. If the user application does not want to accept the call or doesn't know how to route the call, it can reject the call by calling the PKX_CALL_Reject function. When the called party answers the call, the user application calls the PKX_CALL_Answer function. The PKX_CALL_Answer function returns immediately while lower-level processes send the appropriate answer message to the calling party. When the answer message is acknowledged and the call is established, the user application receives a PKX_EVENT_CALL_ANSWERED event. Billing at the service provider normally starts when a call is answered. The PKX_Call_Answer function has an optional settings parameter for special answer characteristics. Currently, the only characteristics defined are those for Collect Call Blocking (pg. 47). Refer to the section below. If no special characteristics are required, this parameter can be set to null. When the user application is the called party (such as an IVR application), it is not necessary to accept the call before answering it. The following diagrams show the typical processing flow for handling incoming calls. The diagram below shows the process flow when the call must be routed by the user application to another device. The user application accepts the call and makes a call to the destination. When the destination indicates that alerting has started, a one-way voice path from the called party to the calling party is made to provide the audio path for alerting tones being received from the destination to the original caller. When the destination answers, both channels of the calls are connected. 4

52 Call Processing.3 Basic Functions The following diagram shows the process flow when the user application answers the call. In this case, the call is answered immediately, without going through the call accept process. When the call answered event (PKX_EVENT_CALL_ANSWERED) is received, processing is performed on the channels of the call. 46

53 .3 Basic Functions Call Processing Example This example is taken from the EventProcessing function in ivr.cpp of the IVR sample application. It demonstrates the processing of the events received during an incoming call. When the PKX_EVENT_GROUP_INCOMING_CALL event is received, the application retrieves the call information and accepts the call. When the PKX_EVENT_CALL_ACCEPTED event is received, the application answers the call. When the PKX_EVENT_CALL_ANSWERED event is received, the channel is ready to receive or transmit audio data. The channel can be joined with another channel or, as is the case in this application, play the IVR menu Collect Call Blocking In countries such as Brazil, the telephone company provides an automated collect call service that follows a national standard. The service operates as follows: The caller initiates a call using the collect call prefix When the far end answers, an automatic recording is played: "Collect Call, to accept stay on the line after the identification" At the same time, the caller hears: "After answer, say your name and the city you are calling from" If the far end hangs up the call before a specified time, typically 7 seconds, the called party is not billed for long distance charges Companies with automated phone systems (e.g. IVR systems) need to block collect calls to avoid long distances charges. GP provides functionality referred to as double-answer which means that the call will be answered normally, hung up for 1. seconds and then answered again. If it is a collect call, the call is dropped by the telephone company. If not, the call continues normally. In countries where this service is offered, the called party can hang up for up to 90 seconds 47

54 Call Processing.3 Basic Functions without dropping the call (call retention by called party) and for collect calls, the called party controls when the call is dropped. If the collect call block is enabled, GP will perform the double-answer before raising the PKX_EVENT_CALL_ANSWERED event to the user application. settings The PKX_CALL_Answer function parameter settings allows the user application to enable collect call blocking and to adjust the timeouts for the double answer. enable - enables/disables collect call blocking beforeonhooktime - time (in ms) to wait before sending the onhook to the PSTN. [100 to 000; default is 00] collectcalltime - time (in ms) to wait before sending the offhook to the PSTN [1000 to 000; default is 100] afteroffhooktime - time (in ms) to wait before raising the ANSWERED event to the application [100 to 000; default is 200] 48

55 .3 Basic Functions NOTE: Call Processing 1. This feature is not supported for ISDN trunks. 2. The settings parameter is introduced in the 2. release and it must be enabled by adding the USE_ANSW_SETTINGS define to your project files or Makefiles. Refer to the information about the PKX_CALL_Answer function in the API Reference for more information Early Media Early media is the ability of two parties in a call to communicate before the call is actually established. It informs the remote party that in-band audio is present on the bearer channel prior to the call being answered. The in-band audio is normally call progress tones, such as audible ring back or a busy tone, and is typically used in gateway scenarios when joining two parties using different protocols (digital protocols such as SIP and ISDN interworking to an analog channel). Incoming Calls To indicate that in-band audio is present, the user application calls the function PKX_CALL_EarlyMedia. Calling this function does not change the state of the call. The call must be in the offered state if the function is used to indicate that dial tone is present (for example, to indicate that the local side is ready to receive tones for overlap dialing). To use this function to indicate call progress tones, other than dial tone, the application must call PKX_CALL_Accept first and wait for the PKX_EVENT_CALL_ACCEPTED. When the function completes successfully, the application receives the event PKX_EVENT_CALL_EARLY_MEDIA_COMPLETED. If the call was not in either the state PKX_CALL_STATE_OFFERED or the state PKX_CALL_STATE_ALERTING, the application receives the event PKX_CALL_TASK_FAILED. The event parameter p1 indicates the error PKX_ERROR_CALL_IN_WRONG_STATE. The following diagram shows the call flow and events when application uses the early media functionality. 49

56 Call Processing.3 Basic Functions Outgoing Calls The user application may receive the event PKX_CALL_EARLY_MEDIA from the remote party when initiating an outgoing call. GrandPrix automatically handles call progress tones if the callpa channel group key is configured and the incoming tone matches one of the patterns described in the Call Progress Pattern sections. When the user application receives the event on the channel for the outgoing call, it should call the function PKX_CALL_EarlyMedia on the incoming call. This typically occurs in a gateway scenario. The first diagram below shows the typical case where the early media event arrives after the call proceeding event. The second diagram shows the flow for a call using overlap dialing (for example, ISDN BRI). 0

57 .3 Basic Functions Call Processing Joining Calls GP provides the following functions to connect and disconnect channels involved in calls. These functions return immediately, before the channels are connected or disconnected. The user application receives the corresponding event when the channels have been connected or disconnected. GP API Function Description Corresponding Event PKX_CHANNEL_ This function takes two channel handles as input parameters. The media received on the first channel is sent to the second channel and the media received on the second channel is sent to the first channel. PKX_EVENT_CHANNEL_FULL_ FullDuplexConnect DUPLEX_CONNECT 1

58 Call Processing.3 Basic Functions PKX_CHANNEL_ This function takes two channel handles as input FullDuplexDisconnect parameters and disconnects the media path between the two channels. Both directions of the media path are disconnected. PKX_EVENT_CHANNEL_FULL_ PKX_CHANNEL_ PKX_EVENT_CHANNEL_HALF_ HalfDuplexConnect This function takes two channel handles as input parameters. The media received on the first channel is sent to the second channel. PKX_CHANNEL_ This function takes two channel handles as input HalfDuplexDisconnect parameters and disconnects the media path from the first channel to the second channel. When used on a full-duplex connection, the media path from the second channel to the first channel is unaffected. DUPLEX_DISCONNECT DUPLEX_CONNECT PKX_EVENT_CHANNEL_HALF_ DUPLEX_DISCONNECT If a connect or disconnect function fails, a PKX_EVENT_CHANNEL_TASK_FAILED event is generated. The channel on which the failure occurred is identified in the event handle field. The event p1 field contains the error code of the failure. The following table lists the error codes that may be returned: Error Code Description PKX_ERROR_CHANNEL_ALREADY_CONNECTED The channel is already connected to another channel. PKX_ERROR_CHANNEL_INVALID_REMOTE_HANDLE The remote handle does not refer to a channel present in the system. PKX_ERROR_CHANNEL_NOT_CONNECTED A disconnect has been issued for this channel and the channel is not connected. PKX_ERROR_CHANNEL_INVALID_CONNECTION_TYPE A full duplex disconnect function has been issued on a half duplex connection. Echo Cancellation Echo cancellation is automatically applied when connecting an RTP channel to a TDM channel using the PKX_CHANNEL_FullDuplexConnect function. If other configurations of echo cancellation are required by the user application, the bypass (pg. 140) feature must be used. When echo cancellation is enabled, there is a potential delay due to the distance between the echo canceller and the echo source, or tail. Delays can be fixed by setting a value for this tail for the RTP channel. See the parameter taillength 2

59 .3 Basic Functions Call Processing under SIP Resources in the PIKA GrandPrix Configuration Guide for more information on the value range and default Hold and Resume GP provides functions to enable user applications to temporarily hold an active call and resume a held call. Placing a call on hold involves: 1. Establishing a first call. 2. Having a remote switch place the first call on hold. With ISDN, CAS, and FXO channels, the remote switch places the first call on hold. The bearer channel on the local side is now available to use for another call. The following diagram shows the steps. When a call resumes, the switch connection is reestablished and the bearer channel is no longer available for other calls. SIP hold and resume requests are negotiated directly between the two user agents, there is no remote switch involved. The hold request uses a RE-INVITE to change the RTP channel to transmit only. The resume request uses a RE-INVITE to change the RTP channel to transmit and receive. Unlike other channel types, the bearer channel is not released when the call is held. If the local party wants to initiate a second call, it must use a new RTP channel allocated from the SIP group. 3

60 Call Processing.3 Basic Functions Outgoing Requests To put a call on hold using GP, there must be an established call which may be either an incoming or outgoing call. The call must be in the state PKX_CALL_STATE_CONNECTED. After the call is established, the user application calls the PKX_CALL_HoldRequest function to place the other party on hold. The PKX_CALL_HoldRequest function is passed the handle of the call to which the request applies. GP handles the associated messaging with either the switch or the requesting user agent. The following diagram shows an example of a hold and resume sequence for a SIP channel. 4

61 .3 Basic Functions Call Processing When the function PKX_CALL_HoldRequest returns, the user application needs to wait for one of the following events to indicate the result of the hold request. Event PKX_EVENT_CALL_HELD Event Parameters p0 - channel handle of the channel no longer in use for the call p1 - (enumerated type PKX_TCallCombinedHoldState) Description The hold request succeeded. PKX_CALL_NO_HOLD PKX_CALL_LOCAL_HOLD PKX_CALL_REMOTE_HOLD PKX_CALL_MUTUAL_HOLD p2 - indicates whether the local or remote party initiated the hold request, one of: PKX_EVENT_ORIGINATED_LOCALLY PKX_EVENT_ORIGINATED_REMOTELY

62 Call Processing.3 Basic Functions PKX_EVENT_CALL_HOLD_REJECTED p0 - channel handle of the channel still associated The remote party rejected with the call the hold p1 - reason the hold request was rejected, one of request. GP PKX_CALL_CAUSE_XXX only returns this event for ISDN and SIP calls. PKX_EVENT_CALL_TASK_FAILED p0 - channel handle of the channel associated with the call p1 - the error code of the error that caused the failure The PKX_CALL _HoldReque st function failed. This may occur if the call was not in the connected state. To resume a held call, the user application calls PKX_CALL_ResumeRequest. The call must be on hold. When the function returns, the user application needs to wait for one of the following events to indicate the result of the resume request. 6

63 .3 Basic Functions Event Call Processing Event Parameters Descript ion p0 - channel handle of the channel now in use for The resume the call request p1 - (enumerated type succeeded. PKX_TCallCombinedHoldState) PKX_EVENT_CALL_RESUMED PKX_CALL_NO_HOLD PKX_CALL_LOCAL_HOLD PKX_CALL_REMOTE_HOLD PKX_CALL_MUTUAL_HOLD p2 - indicates whether the local or remote party initiated the resume request (enumerated type PKX_TEventOrigination), one of: PKX_EVENT_ORIGINATED_LOCALLY PKX_EVENT_ORIGINATED_REMOTELY PKX_EVENT_CALL_RESUME_REJECTED p0 - channel handle of the channel to which the resume request applied, not in use with the call p1 - reason the hold request was rejected, one of PKX_CALL_CAUSE_XXX The remote party rejected the resume request. GP only returns this event for ISDN and SIP calls. 7

64 Call Processing PKX_EVENT_CALL_TASK_FAILED.3 Basic Functions p0 - channel handle of the channel to which the resume request applied, not in use with the call p1 - the error code of the error that caused the failure The PKX_CA LL_Resu mereque st function failed. This may occur if the call was not on hold. Incoming Requests Incoming requests apply only to SIP and ISDN channels and can be handled either by the application or GP can handle the requests without interacting with the application. The value of the configuration key auto_accept determines how incoming hold and resume requests are handled. If the value is hold, GP handles hold and resume requests without interacting with the user application. If the value is none, hold and resume requests are handled by the application. The following diagrams show an example using SIP messages and events where the application handles the incoming requests. If ISDN channels are used, the messages Hold/Hold Acknowledge and Retrieve/Retrieve Acknowledge are used instead of INVITE/200 OK messages. 8

65 .3 Basic Functions Call Processing The user application receives the event PKX_EVENT_CALL_HOLD_REQUESTED. The event parameters are: p0 - the channel of the call to which the hold request applies p1 - indicates the mode of the bearer channel for the call, (enumerated type PKX_TCallHoldMode) one of: PKX_CALL_MODE_INACTIVE PKX_CALL_MODE_SENDONLY (SIP only) The mode PKX_CALL_MODE_SENDONLY can be used if an application wants to play music on hold to the held party. The user application must respond to the hold request by calling either the function PKX_CALL_HoldAccept or PKX_CALL_HoldReject. The following diagrams show an example using SIP messages and events where GP handles the incoming requests (the value of auto_accept is hold). 9

66 Call Processing.3 Basic Functions The user application receives the event PKX_EVENT_CALL_HELD when GP successfully handles the hold request and receives the event PKX_EVENT_CALL_RESUMED when GP successfully handles the resume request. The event parameters are described above Call Transfer Transferring a call involves: 1. Establishing a first call. 2. Placing the first call on hold. 3. Establishing a second call. 4. Connecting the first and second called parties and remove the person initiating the transfer from the circuit. All channel types support Basic Call Transfer (pg. 60). SIP and ISDN each have additional capabilities which are described in SIP Call Transfer and ISDN Call Transfer (pg. 71), respectively Basic Call Transfer For FXO, CAS and ISDN channels, the hold and transfer takes place at the remote switch. The following diagram shows the steps in transferring a call: 60

67 .3 Basic Functions Call Processing The remote switch must be provisioned with the appropriate call transfer service to allow this feature to operate. Some remote switches require a second hookflash to complete the transfer. If the switch requires the second hookflash, the transfer_extrahf key in the trunk parameters section of the configuration file must be set to yes. SIP channels do not use a remote switch, the parties involved with the transfer communicate directly via SIP messaging to complete the transfer. The following diagram shows the steps. While the diagram shows a peer to peer call scenario, messages to establish the transfer could also be routed through a proxy server. 61

68 Call Processing.3 Basic Functions To transfer a call using GP, the user application requires an established call (or first call). The first call can be either an incoming or outgoing call. After the first call has been established, the user application calls the PKX_CALL_Transfer function to transfer the call to a second called party. The PKX_CALL_Transfer function is passed the handle of the first call, and the call information for the second called party. The first call is placed on hold by the remote switch and the PKX_CALL_Transfer function returns the handle of the second call. After the second call has been established to at least the PKX_CALL_STATE_PROCEEDING state, indicated by the PKX_EVENT_CALL_PROCEEDING event, the call can be transferred by calling the PKX_CALL_Drop function, passing it the handle of the second call and providing a cause of PKX_CALL_CAUSE_TRANSFER. After the transfer process is started, the user application receives the following events indicating the progress of the call: 62

69 .3 Basic Functions Call Processing Call Progress Event Event Handle Description PKX_EVENT_CHANNEL_READY First calls channel Indicates the channel used by the first call is now free for use in the second call. PKX_EVENT_CALL_HELD First call Indicates the first call has been put on hold by the remote switch. PKX_EVENT_CHANNEL_IN_USE Second calls channel (the channel is the same as that used by the first call) Indicates a channel has been seized to make the second call. PKX_EVENT_CALL_DIALING Second call Indicates dialing has been started for the second call. PKX_EVENT_CALL_ALERTING Second call Indicates the dialing for the second call is complete and the far end is ringing. PKX_EVENT_CALL_CONNECTED Second call Indicates the far end has answered the call. PKX_EVENT_CALL_DROPPED Second call Indicates the application has terminated the second call. PKX_EVENT_CALL_DISCONNECTED First call Indicates the remote switch has terminated the connection to the application for the first call. The far end of the first call is still connected to the remote switch. PKX_EVENT_CHANNEL_READY Second calls channel (the channel is the same as that used by the first calls) Indicates the channel used for the first and second call has been released. PKX_EVENT_CALL_RESUMED First call Indicates the original call has been reestablished. This event is only generated after a PKX_CALL_Transfer was issued, but the transfer could not be completed due to a manual or automatic abort. There are two types of call transfer: supervised and blind. The following sections outline the function calls made and events generated for each type of transfer. Supervised Transfer 63

70 Call Processing.3 Basic Functions Transfers may be supervised, where the person initiating the transfer converses with the second called party before transferring the call. This diagram shows an incoming FXO call supervised before it is transferred to a second party. Note that the application waits for the PKX_EVENT_CALL_CONNECTED before completing the transfer. The following diagram shows a supervised ISDN call transfer. In the sequence shown, GP automatically puts the first call on hold when the transfer is initiated. The user application could also use the function PKX_CALL_Hold to put the call on hold before initiating the transfer. 64

71 .3 Basic Functions Call Processing Blind Transfer Transfers may be performed blindly where the person initiating the transfer, transfers the call when the call to the 6

72 Call Processing.3 Basic Functions second party is ringing. This diagram shows an outgoing call transferred blindly. Note that the application completes the transfer after receiving the PKX_EVENT_CALL_ALERTING event, instead of waiting for the PKX_EVENT_CALL_CONNECTED event. When a call is transferred, both the first and second calls must be released to release PIKA GrandPrix SDK resources and invalidate the call handles. The following diagram shows an ISDN blind transfer. 66

73 .3 Basic Functions Call Processing The first call may be resumed, either automatically in the case where a busy signal is received, or manually by the user application calling PKX_CALL_Drop and passing in the second call handle, and a cause of PKX_CALL_CAUSE_NORMAL. If the second call is dropped before the transfer is completed (by dropping with a cause other than PKX_CALL_CAUSE_TRANSFER), the first call is resumed. The following diagrams show the function calls made and the events generated when the first call is resumed. The first diagram shows the first call being 67

74 Call Processing.3 Basic Functions resumed automatically after a busy signal is returned. The second diagram shows the first call being resumed manually by the user application calling PKX_CALL_Drop. 68

75 .3 Basic Functions Call Processing When the first call is resumed, the second call must be released to release GP resources and invalidate the call handle. The following diagram shows the same scenarios using ISDN channels. 69

76 Call Processing.3 Basic Functions 70

77 .3 Basic Functions Call Processing Tips Call progress should always be configured for analog channels, otherwise dial and busy tones are not detected ISDN Call Transfer ISDN PRI supports call transfer between two unrelated calls. The transfer type must be provisioned at the remote switch and the configuration key transfertype must be set to the corresponding value. 71

78 Call Processing.3 Basic Functions Two B-Channel Transfer (TBCT) TBCT is an ISDN supplementary service that enables an ISDN PRI user (the controller) to request the remote switch to connect two independent calls. The two calls can be present on the same PRI trunk or on different PRI trunks between the two switches. The remote switch will then, if successful, connect the two calls locally and release the two channels to the user, freeing them for subsequent calls. Billing is unaffected by the transfer and continues as before. An additional option, Notification to Controller, may be provisioned on the remote switch to allow it to inform the user when the transfer call has dropped. This transfer type is used with NI-2 and Lucent switches. Once two calls are established (either incoming or outgoing calls), the user application calls the function PKX_CALL_TransferBridge, passing in the call handles of the two calls to join. The parameters do not have match the order in which the calls were placed. Incoming calls must be in the connected state and an outgoing call may be in the alerting state (blind transfer) or connected state (supervised transfer). If both calls involved in the transfer attempt are outgoing calls, at least one of the outgoing calls must be in the connected state. The bearer capabilities of the channels must be compatible with one another. Both calls must belong to the same protocol group. However, protocol groups provisioned with the ISDN Two B-channel Transfer transfer type allow two calls from different ISDN protocol groups if both groups are part of the same PRI Serving Group. The PRI Serving Group is provisioned using the priserving configuration key and must match the provisioning setup by the Telco. ISDN protocol groups with the same priserving value are considered to be in the same PRI Serving Group. The number assigned to the priserving configuration key identifies which ISDN protocol groups are in the PRI Serving Group and does not need to match any specific value assigned by the Telco. The user application receives the following events after calling the function PKX_CALL_TransferBridge. Event Event Handle PKX_EVENT_CALL_DISCONNECTED First call (cause PKX_CALL_CAUSE_TRANSFER) PKX_EVENT_CHANNEL_READY 72 Channel used for the first call Description Indicates that the remote switch has terminated the connection to the application for the first call. The far end of the first call is still connected to the remote switch. Indicates that the channel used for the first call has been released.

79 .3 Basic Functions PKX_EVENT_CALL_DISCONNECTED Second (cause PKX_CALL_CAUSE_TRANSFER) call PKX_EVENT_CHANNEL_READY Channel used for the second call Call Processing Indicates that the remote switch has terminated the connection to the application for the second call. The far end of the first call is still connected to the remote switch. Indicates the channel used for the second call has been released. The following diagram shows a successful transfer bridge for TBCT. 73

80 Call Processing.3 Basic Functions If the call transfer fails, the user application receives the event PKX_CALL_TASK_FAILED with event parameter p1 indicating the reason for the failure. A failure may occur if the transfer feature is not provisioned on the remote switch. The call states are unchanged. 74

81 .3 Basic Functions Call Processing Explicit Call Transfer (ECT) This transfer type is used with ETSI switches. There are two types of ECT, implicit linkage and explicit linkage. Ensure that the correct variant is provisioned in the configuration key transfertype. The user application uses the same functions and receives the same events, regardless of the type of ECT. Unlike TBCT, one of the calls involved in the transfer must be on hold. The application can put either of the calls on hold. If one of the calls is not on hold, the user application receives the event PKX_CALL_TASK_FAILED with event parameter p1 set to PKX_ERROR_CALL_IN_WRONG_STATE. The remaining messages are the same as for TBCT. The following diagram shows the steps in a successful ECT call transfer. 7

82 Call Processing.3 Basic Functions Terminating a Call A call can be terminated by one of the following events: The incoming call is rejected. The user application terminates the call. The remote party terminates the call. Rejecting incoming calls - If the user application does not wish to accept an incoming call, it calls the PKX_CALL_Drop function with the cause PKX_CALL_CAUSE_REJECTED after the PKX_EVENT_GROUP_INCOMING_CALL event is retrieved from the event queue. This function must be used immediately after receiving the PKX_EVENT_GROUP_INCOMING_CALL event and before invoking any call function (other than PKX_CALL_GetInfo) using the callhandle specified in p1 of the event. The user application must call the PKX_CALL_Release function after rejecting the call. The user application terminates the call - The user application calls the PKX_CALL_Drop function to terminate a call. The PKX_CALL_Drop function can be used to terminate a call after the incoming call has been accepted, or once a call has been established. The cause parameter should be set to PKX_CALL_DROP_CAUSE_NORMAL. The PKX_CALL_Drop function returns immediately, while lower-level processes send the appropriate messages to terminate the call. When the call has been disconnected, the user application is notified via a PKX_EVENT_CALL_DROPPED event. After the PKX_EVENT_CALL_DROPPED event has been received, the user application must then call the PKX_CALL_Release function to free the resources used by the call. The user application receives a PKX_EVENT_CHANNEL_READY event once all active media operations started during the call are stopped and the channel is ready to process subsequent calls. If the disconnected call was joined to another call, the PKX_CALL_Drop function will not affect the second call or any channel connections established using the PKX_CHANNEL_FullDuplexConnect or PKX_CHANNEL_HalfDuplexConnect functions. It is the responsibility of the user application to terminate the second call and disconnect the channels using the PKX_CHANNEL_FullDuplexDisconnect or PKX_CHANNEL_HalfDuplexDisconnect functions. The remote party terminates the call - When the remote party in a call hangs up, the user application receives a PKX_EVENT_CALL_DISCONNECTED event to indicate the call has been disconnected. The reason the call was disconnected is specified in the p1 parameter of the PKX_EVENT_CALL_DISCONNECTED event. The user application must then call the PKX_CALL_Release function to free the resources used by the call. The user application receives a PKX_EVENT_CHANNEL_READY event once all active media operations started during the call are stopped and the channel is ready to process subsequent calls. If the disconnected call was joined to another call, 76

83 .3 Basic Functions Media Processing the PKX_CALL_Drop function will not affect the second call or any channel connections established using the PKX_CHANNEL_FullDuplexConnect or PKX_CHANNEL_HalfDuplexConnect functions. It is the responsibility of the user application to terminate the second call and disconnect the channels using the PKX_CHANNEL_FullDuplexDisconnect or PKX_CHANNEL_HalfDuplexDisconnect functions. The following diagram shows the process flow for all methods of terminating a call. Example There are two examples shown below. The both examples are taken from the EventProcessing function in ivr.cpp source file of the Interactive Voice Response sample application. The first example demonstrates dropping a call. The second example demonstrates the processing of the events received when a call is terminated. When a PKX_EVENT_CALL_DISCONNECTED event is received (the far-end terminated the call) or a PKX_EVENT_CALL_DROPPED event is received (the application terminated the call), the application retrieves the call handle from the event and releases the call. 77

84 Media Processing.3 Basic Functions.3. Media Processing The following topics describe how to perform media processing functions on a channel: Playing a stored message (pg. 78) Recording (pg. 84) Collecting DTMF digits (pg. 88) Sending DTMF digits (pg. 90) Generating tones (pg. 91) Detecting tones (pg. 93) Detecting speech (pg. 94) Fax Processing (pg. 100).3..1 Playing a Stored Message There are two methods of playing a stored message on a channel: 1. Queue one or more stored messages to the channel using the PKX_CHANNEL_PlayAddData function and then start playing the message(s) using the PKX_CHANNEL_Play function. The messages to be played can be stored in either a memory buffer or a file. A structure (PKX_TAudioData) is passed in as a parameter to the PKX_CHANNEL_PlayAddData function. This structure defines where the stored message is located (in a memory buffer or in a file), which portion (offset and length) of the data to play, and whether this is the last segment of data to play. 2. Play one message file to a channel using the PKX_CHANNEL_PlayFile function. This method can play only one file. Both the PKX_CHANNEL_PlayAddData and PKX_CHANNEL_PlayFile functions use a flags parameter that defines the audio properties of the data. See the Audio Flags (pg. 9) section for more information on the flags that can be passed to these functions. Both the PKX_CHANNEL_Play and PKX_CHANNEL_PlayFile functions are passed a set of termination conditions. See the Media Processing Termination Conditions (pg. 97) section for more information on conditions that can be used to terminate these functions. These functions can also be terminated using the PKX_CHANNEL_Stop function. 78

85 .3 Basic Functions Media Processing The PKX_CHANNEL_PlayAddData function requires a PKX_TAudioData structure to be passed to it. This structure defines the location of the audio data block to be added to the queue of data to be played. The following table describes the fields defined in the PKX_TAudioData structure: PKX_TAudioData Description Field location.buffer Pointer to the memory buffer where the audio data block to play is stored. This location is used if the PKX_AUDIO_DATA_TYPE_FILE flag is not set in the typeflags field. NOTE: The user application must not free this memory buffer until it receives either the PKX_EVENT_CHANNEL_STOPPED_PLAY event or the PKX_EVENT_CHANNEL_DONE_PLAY event. location.filename Name of the file where the audio data block to play is stored. This location is used if the PKX_AUDIO_DATA_TYPE_FILE flag is set in the typeflags field. offset The offset within the location to start processing the audio data. length Number of bytes to play from the specified offset. The PKX_AUDIO_PLAY_ALL_DATA constant is used in this field to indicate that the play function should play all the audio data in the file. This constant cannot be used with buffer locations as it is not possible to determine the size of the buffer. typeflags Bit mask of indicators describing the data. These flags can be ORed together. PKX_AUDIO_LAST_BUFFER indicates to the PKX_CHANNEL_Play function that it should terminate playing after this data block is played. If this flag is not set on the last data block, a PKX_EVENT_CHANNEL_UNDERFLOW_PLAY event is raised and the play function pauses until more data is provided. This flag must be set only on the last data block, regardless of whether the data is stored in a memory buffer or a file. PKX_AUDIO_DATA_TYPE_FILE indicates the audio data to be played is located in the file location field. The PKX_CHANNEL_Play and PKX_CHANNEL_PlayFile functions return immediately. Lower-level processes manage the playing of the audio data blocks. As these lower-level processes play the data, events are generated indicating progress. The following table lists the events that can be generated while playing data: 79

86 Media Processing Play Event.3 Basic Functions Description PKX_EVENT_CHANNEL_UNDERFLOW_PLAY Indicates the PKX_CHANNEL_Play asynchronous function has run out of audio data to play and has not received a PKX_TAudioData structure indicating it is the last block of audio data. The play function plays silence until more data is added, or the media function is terminated by meeting one of its termination conditions or the user application calls the PKX_CHANNEL_Stop function. PKX_EVENT_CHANNEL_DATAREADY_PLAY Indicates a block of data has been played. This event can be used by the user application to maintain a constant number of pending play audio data blocks when playing a very long (or infinitely long) audio stream. PKX_EVENT_CHANNEL_DONE_PLAY Indicates the PKX_CHANNEL_PlayFile or PKX_CHANNEL_Play asynchronous function completed successfully. PKX_EVENT_CHANNEL_STOPPED_PLAY Indicates the PKX_CHANNEL_PlayFile or PKX_CHANNEL_Play asynchronous function terminated successfully using the PKX_CHANNEL_Stop function. PKX_EVENT_CHANNEL_TERM_condition Indicates the PKX_CHANNEL_PlayFile or PKX_CHANNEL_Play asynchronous function terminated because one of its termination conditions has been met. The condition corresponds to the termination condition that was met. See Media Processing Termination Conditions (pg. 97) for more information on which termination conditions are allowed for these functions. If a second call to PKX_CHANNEL_PlayFile is executed before the first call has completed playing the data, the second PKX_CHANNEL_PlayFile returns a status of PKX_ERROR_CHANNEL_MEDIA_IN_USE. The following diagrams demonstrate when these events are generated. While the examples refer to adding a buffer, the stored message can be provided in either a memory buffer or a file. The data is handled in the same way, regardless of how the data is provided and the user application should always set the last buffer flag only on the last data block provided. 80

87 .3 Basic Functions Media Processing In the first scenario, the PKX_CHANNEL_Play function is executed before any buffers have been added. The user application receives a PKX_ERROR_CHANNEL_AUDIO_DATA_NOT_AVAILABLE event. In the second scenario, the buffer with the last buffer flag set is added before the PKX_CHANNEL_Play function is executed. The stored message is played on the channel and the user application receives two events, PKX_EVENT_CHANNEL_DATAREADY_PLAY and PKX_EVENT_CHANNEL_DONE_PLAY, when the message has completed playing. In the third scenario,the PKX_CHANNEL_PlayFile function is used to play data from a file. The stored message is played on the channel and the user application receives two events, PKX_EVENT_CHANNEL_DATAREADY_PLAY and PKX_EVENT_CHANNEL_DONE_PLAY, when the message has completed playing. In the fourth scenario, four buffers are added, with the fourth buffer having the last buffer flag set. Only the last buffer (in this example, the fourth buffer) should have the last buffer flag set. When the PKX_CHANNEL_Play function is executed, the buffers are played sequentially, in the order they were added. The user application receives a 81

88 Media Processing.3 Basic Functions PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. After the fourth buffer is played, the user application receives a PKX_EVENT_CHANNEL_DONE_PLAY event. In the fifth scenario, four buffers are added, with the fourth buffer having the last buffer flag set. Only the last buffer (in this example, the fourth buffer) should have the last buffer flag set. When the PKX_CHANNEL_Play function is executed, the buffers are played sequentially, in the order they were added. The user application receives a PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. In the middle of playing the third buffer, the PKX_CHANNEL_Stop function is executed. This causes the playback of the third buffer to stop. The rest of the third buffer and the fourth buffer are discarded. The user application receives one event, PKX_EVENT_CHANNEL_STOPPED_PLAY. No events are generated for the third or fourth buffers. In the sixth scenario, one of the termination conditions specified in the PKX_CHANNEL_Play function has been met before all the data has been played. When the termination condition is met, the playing of the data stops and a PKX_EVENT_CHANNEL_TERM_xxx is generated. The xxx corresponds to the termination condition that was met. The rest of the third buffer and the fourth buffer are discarded. 82

89 .3 Basic Functions Media Processing In the seventh scenario, two buffers are added and then the PKX_CHANNEL_Play function is executed. While the initial two buffers are playing, two more buffers are added. As long as the additional buffers are added before the initial buffers have completed playing, a continuous audio stream is played. The user application receives a PKX_EVENT_CHANNEL_DATAREADY_PLAY event after each buffer completes playing. After the fourth buffer is played, the user application receives a PKX_EVENT_CHANNEL_DONE_PLAY event. In the eighth scenario, two buffers are added before the PKX_CHANNEL_Play function is executed. The second buffer does not have the last buffer flag set. The first two buffers are played before the third buffer is added. Since there is no more data queued to be played and the last buffer flag was not set in the last buffer played, a PKX_EVENT_CHANNEL_UNDERFLOW_PLAY event is generated. When the third and fourth buffers are added, the data continues playing. 83

90 Media Processing.3 Basic Functions Example Two examples are shown: The first example is the playfile function in ivr.cpp of the Interactive Voice Response sample application. It demonstrates playing a message stored in a file to a channel. The flag for WAVE file header is set. This indicates the specification of the encoding format and sampling rate are contained in the WAVE header appended to the file. No termination conditions are specified so the entire file is played. The second example is the queueplaybuffer function in meetme.cpp of the MeetMe sample application. It demonstrates using a single buffer to store separate message data and then play them back. This approach saves memory if multiple channels need simultaneous access to play the same data Recording Audio Data From a Channel There are two methods of recording audio data from a channel: 1. Start recording the audio data from a channel using the PKX_CHANNEL_Record function. The user application receives PKX_EVENT_CHANNEL_DATAREADY_RECORD events to indicate a block of recorded audio data is ready for the user application to retrieve using the PKX_CHANNEL_RecordGetData function. NOTE: When a PKX_EVENT_CHANNEL_DATAREADY_RECORD event is returned by the PKX_SYSTEM_WaitOnEvent function, the buffer of recorded data must be retrieved before the next call to PKX_SYSTEM_WaitOnEvent or the recorded data is lost. 2. Record the audio data from a channel directly to a file using the PKX_CHANNEL_RecordFile function. Both the PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions are passed a flags parameter that defines the audio properties of the data recorded. See the Audio Flags (pg. 9) section for more information on the flags that can be passed to these functions. Both the PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions are passed a set of termination conditions. See Media Processing Termination Conditions (pg. 97) for more information on conditions used to terminate these functions. These functions can also be terminated using the PKX_CHANNEL_Stop function. The PKX_CHANNEL_RecordGetData function requires a PKX_TAudioData structure to be passed to it. This structure defines the buffer into which the audio data block recorded is copied. The following table describes the fields defined in the PKX_TAudioData structure used for the PKX_CHANNEL_RecordGetData function. 84

91 .3 Basic Functions Media Processing PKX_TAudioData Description Field location.buffer Pointer to the memory buffer where the recorded audio data block is stored. location.filename Not used. offset Not used. length IN: The number of bytes allocated by the user application for the buffer. If the size is insufficient, the error PKX_ERROR_INSUFFICIENT_MEMORY_PROVIDED will be returned. OUT: The actual number of bytes copied into the buffer. The number of bytes of data available in the record buffer is specified in the PKX_EVENT_CHANNEL_DATAREADY_RECORD event. typeflags Not used. The PKX_CHANNEL_Record and PKX_CHANNEL_RecordFile functions return immediately. Low-level processes manage the recording of the audio data blocks. As these low-level processes record the data, events are generated indicating progress. The following table lists the events that can be generated while recording data. Play Event Description PKX_EVENT_CHANNEL_DATAREADY_RECORD Indicates the PKX_CHANNEL_Record asynchronous function has a block of recorded audio data ready for the user application to retrieve using the PKX_CHANNEL_RecordGetData function. The p0 field of the event specifies the number of bytes available in the internal audio buffer. PKX_EVENT_CHANNEL_OVERFLOW_RECORD Indicates the PKX_CHANNEL_Record asynchronous function has run out of internal memory to temporarily store the recorded audio data. Incoming audio data is lost until the user application retrieves a block of audio data using the PKX_CHANNEL_RecordGetData function. There are five 16 kb internal audio buffers. PKX_EVENT_CHANNEL_STOPPED_RECORD Indicates the PKX_CHANNEL_RecordFile or PKX_CHANNEL_Record function has been terminated using the PKX_CHANNEL_Stop function. 8

92 Media Processing PKX_EVENT_CHANNEL_TERM_xxx.3 Basic Functions Indicates the PKX_CHANNEL_RecordFile or PKX_CHANNEL_Record function has been terminated because one of its termination conditions has been met. See Media Processing Termination Conditions (pg. 97) for more information on which termination conditions are allowed for these functions. The following diagrams demonstrate when these events are generated. In the first scenario, the PKX_CHANNEL_RecordFile function is executed. The audio data on the channel is recorded to the file until one of the termination conditions specified in the PKX_CHANNEL_RecordFile function call is met. When the termination condition is met, the recording of the data stops, all the recorded data is written to the file, the file is closed, and a PKX_EVENT_CHANNEL_TERM_xxx is generated. The xxx corresponds to the termination condition that was met. In the second scenario, the PKX_CHANNEL_Record function is executed. As each buffer of audio data is recorded, a PKX_EVENT_CHANNEL_DATAREADY_RECORD event is generated. The user application periodically retrieves the recorded audio data buffers using the PKX_CHANNEL_RecordGetData function and stores or processes the data. The user application stops the recording of audio data using the PKX_CHANNEL_Stop function. This causes recording of audio data on the channel to stop, a final PKX_EVENT_CHANNEL_DATAREADY_RECORD event to be generated, and a PKX_EVENT_CHANNEL_STOPPED_RECORD event to be generated. 86

93 .3 Basic Functions Media Processing In the third scenario, the PKX_CHANNEL_Record function is executed. GP has only five internal audio buffers. The user application receives five PKX_EVENT_CHANNEL_DATAREADY_RECORD events but does not retrieve any of the audio data. A PKX_EVENT_CHANNEL_RECORD_OVERFLOW event is generated and audio data recording stops. Later, the user application executes a PKX_CHANNEL_RecordGetData function, retrieving the data from one of the internal audio data buffers. This frees the audio buffer and audio data recording restarts. The user application stops the audio data recording using the PKX_CHANNEL_Stop function. This causes audio data recording on the channel to stop, a final PKX_EVENT_CHANNEL_DATAREADY_RECORD event to be generated, and a PKX_EVENT_CHANNEL_STOPPED_RECORD event to be generated. The audio data received or transmitted on the channel between the generation of the PKX_EVENT_CHANNEL_RECORD_OVERFLOW event and the PKX_CHANNEL_RecordGetData function call is lost. GP uses large audio buffers (16 kb) for record functions. The size of these buffers may become an issue to some user applications processing the audio because they introduce latency. A user application must wait until the entire buffer is filled with data before getting an event indicating that audio data is available to be processed. Refer to section Configuring a Channel (pg. 12) for information on customizing the recording buffer size. Tips Performing active call logging when two or more calls are conferenced together requires a virtual channel to be used to record the audio. Example There are three examples shown: The first example is the function recordfile and can be found in the ivr.cpp source file of the Interactive Voice Response sample application. It demonstrates recording the audio data from a channel directly into a file. The encoding format is set to mu-law, the sampling rate is set to 8 khz, and the flag to play an initial beep to indicate 87

94 Media Processing.3 Basic Functions recording is being performed is set. Two termination conditions are set for the recording process, either the pound (#) phone key tone or a period of silence is detected on the channel. The second example is taken from from the handleivrevents function in ivr.cpp source file of the Interactive Voice Response sample application. It demonstrates the processing required when one of the termination conditions has been met. In this example the call is dropped. The third example is taken from the the EventProcessing function in the meetme.cpp source file of the MeetMe sample application. It shows how to record data to a buffer. This approach allows the application to access the data as it is recorded instead of waiting until one of the termination conditions is met to retrieve the entire block of data from a file. The example shows data being appended to the end of a buffer to avoid overwriting previously recorded data Collecting DTMF Digits From a Channel The user application uses PKX_CHANNEL_CollectDigits to apply termination conditions to the collection of DTMF digits on a channel. The user application can use the PKX_CHANNEL_GetNumberOfDigits function to determine the number of digits in the received digit buffer for a specified channel. The PKX_CHANNEL_GetDigits function copies the specified number (or fewer, if there are insufficient digits in the channel digit buffer) of digits from the channel digit buffer into a local buffer supplied by the user application. Digits copied into a local buffer are removed from the channel digit buffer. The digits are stored in the local buffer as a null (\0) terminated string, where each digit is an ASCII character (not a numerical value). The user application must ensure the local buffer is large enough to receive all the requested digits plus the null terminator. The user application can use the strlen function on the local buffer to determine the actual number of digits returned. A channel digit buffer can store up to 127 digits. When 127 digits have been collected, without any of the digits having been retrieved by a PKX_CHANNEL_GetDigits function call, additional digits generated on the channel are not placed in the buffer. A PKX_EVENT_CHANNEL_DIGIT_BUFFER_FULL event is generated for every DTMF digit received that is not put in the buffer because the buffer is full: p0 of this event is set to 127, and p1 of this event specifies the DTMF digit received. Subsequent calls to the PKX_CHANNEL_GetDigits function frees space in the channel digit buffer, and digits received after the PKX_CHANNEL_GetDigits function call are collected up to the limit of the channel digit buffer. The PKX_CHANNEL_ClearDigits function deletes any digits stored in the channel digit buffer. The PKX_CHANNEL_Stop function is used to stop the termination conditions applied to the collection of DTMF digits on a channel. When DTMF digits are being collected on a channel and the PKX_CHANNEL_Stop function is 88

95 .3 Basic Functions Media Processing executed on that channel, a PKX_EVENT_CHANNEL_STOPPED_COLLECT_DIGITS event is generated. The p0 field of this event specifies the number of digits in the channel digit buffer when the PKX_CHANNEL_Stop was executed. Whenever a DTMF digit is detected on a channel (whether PKX_CHANNEL_CollectDigits has been called or not), a PKX_EVENT_CHANNEL_DTMF event is generated, indicating the DTMF digit has been received over the channel. The DTMF digit is specified as an ASCII character in the p0 field of the event. The following diagram shows the events generated and the state of the internal digit buffer as DTMF digits are received. In the diagram, a PKX_EVENT_CHANNEL_DTMF event is generated for each digit received. The 89

96 Media Processing.3 Basic Functions PKX_CHANNEL_CollectDigits function (with a termination condition of maxdigits=3) is executed after one digit has been received. After the third digit is received, a PKX_EVENT_CHANNEL_TERM_MAX_DIGITS event is generated. The PKX_CHANNEL_CollectDigits function (with a termination condition of maxdigits=3) is executed again, after four digits have been received. Since there are four digits in the buffer, a PKX_EVENT_CHANNEL_TERM_MAX_DIGITS event is generated immediately. The PKX_CHANNEL_GetDigits function is called with four specified as the number of digits to transfer. Four digits are removed from the internal digit buffer and copied into the local buffer. The PKX_CHANNEL_CollectDigits function (with a termination condition of maxdigits=) is executed after the four digits have been removed from the buffer. The PKX_CHANNEL_Stop function is executed before the ninth digit is received. A PKX_EVENT_CHANNEL_STOPPED_COLLECT_DIGITS event is generated. This means that PKX_EVENT_CHANNEL_TERM_MAX_DIGITS is NOT generated after the ninth digit is received. The digits remaining in the channel internal digit buffer may still be retrieved using the PKX_CHANNEL_GetDigits function. NOTE: If DTMF detection has been disabled using the PKX_CHANNEL_SetConfig API function, digit collection will not be possible, however, no error will be generated. Example There are three examples: the first example is the function selectoption, and the second and third examples are taken from from the handleivrevents function. All examples can be found in ivr.cpp source file of the Interactive Voice Response sample application. The first example demonstrates the setting of termination conditions on the collection of digits on a channel. Two termination conditions are specified, a digit being received, or no tone being received for a timeout period. The second example demonstrates getting one digit from the channel digit buffer. Depending on the digit received, the application plays a canned message or plays a prompt to the caller that instructs them to record a message. The third example demonstrates the action taken if the timeout termination condition is met. In this example, the call is dropped Sending DTMF Digits to a Channel The user application uses the PKX_CHANNEL_PlayDigits function to send DTMF digits to a channel. The user application passes a null terminated string of ASCII characters for the DTMF keys to this function. The ASCII characters supported are: 0 to 9; a to d; A to D; P; T; W;,; &; #; and *. If any other characters are contained in the string, the PKX_CHANNEL_PlayDigits function returns a PKX_ERROR_CHANNEL_INVALID_PLAY_DIGIT_SPECIFIED error status. The DTMF tones are played as a continuous stream. The tone on and off durations are defined in the root 90

97 .3 Basic Functions Media Processing configuration file. See Tone Generation for more information on the specification of tone on and off durations. When the string of DTMF digits has been transmitted, a PKX_EVENT_CHANNEL_DONE_TONE_GENERATION event is generated. The generation of a string of DTMF digits can be terminated using the PKX_CHANNEL_Stop function. The generation of DTMF tones stops, with any unplayed tones discarded. A PKX_EVENT_CHANNEL_STOPPED_TONE_GENERATION is generated. The p0 field of this event specifies the last tone played..3.. Generating Tones on a Channel The tone groups GP can generate are listed in the [tone_generation] section of the root configuration file. To generate a tone group on a channel, the user application uses the PKX_CHANNEL_PlayTone function. The parameters passed to this function are: The channel handle. The index to the entries of the [tone_generation] section of the GP configuration file. The termination conditions to stop the tone playing. See Media Processing Termination Conditions (pg. 97) for more information on the termination conditions that may be used for this function. NOTE: A tone group is a collection of single-frequency tones. For example: a DTMF tone is a tone group made up of two single-frequency tones. GP function calls always deal with the tone group. The tone group is played for the total of the on and off duration specified in the tone definition unless a termination condition is met or the PKX_CHANNEL_Stop function is executed on that channel. When the tone group has been completely played (both on and off periods), a PKX_EVENT_CHANNEL_DONE_TONE_GENERATION event is generated. When the tone generation is stopped by a termination condition, a PKX_EVENT_CHANNEL_TERM_xxx (where xxx specifies the termination condition that was met) event is generated. When the tone generation is stopped by the PKX_CHANNEL_Stop function, a PKX_EVENT_CHANNEL_STOPPED_TONE_GENERATION event is generated. When no termination conditions are specified, the tone group plays for the duration specified in the configuration file (for example toneg3 "dial" plays for five seconds). When termination conditions are specified, the tone group repeats automatically until one of the termination conditions are met. To play a continuous tone group, use the timeout termination condition and set it for the desired time in milliseconds. 91

98 Media Processing.3 Basic Functions Only one tone group can be played at a time. If a second call to the PKX_CHANNEL_PlayTone function is made while a tone group is being played, a PKX_ERROR_CHANNEL_MEDIA_IN_USE status is returned. The tone patterns generated by GP are listed in the [tone_patterns] section of the root configuration file. A tone pattern can be generated on a channel using the PKX_CHANNEL_PlayTonePattern function. The parameters passed to this function are: The channel handle. The index into the entries of the [tone_patterns] section of the root configuration file. The termination conditions to stop the tone playing. See Media Processing Termination Conditions (pg. 97) for more information on the termination conditions that may be used for this function. When no termination conditions are specified, the tone pattern plays for the duration specified in the configuration file (for example, tone_pattern0 "tp_ringback" plays for the duration of toneg36, two seconds on, and toneg37, four seconds off, for a total of six seconds). When termination conditions are specified, the tone pattern repeats automatically until one of the termination conditions is met. To play a continuous tone pattern, use the timeout termination condition and set it for the desired time in milliseconds. The PKX_CHANNEL_Stop function stops the playing of a tone or tone pattern. When the tone pattern has been completely played, a PKX_EVENT_CHANNEL_DONE_TONE_GENERATION event is generated. When the tone generation is stopped by a termination condition, a PKX_EVENT_CHANNEL_TERM_xxx (where xxx specifies the termination condition that was met) event is generated. When the tone pattern generation is stopped by the PKX_CHANNEL_Stop function, the generation of the tone pattern stops, with any unplayed tones discarded. A PKX_EVENT_CHANNEL_STOPPED_TONE_GENERATION event is generated. The p0 field of this event specifies the last tone played. The repeat key in the tone pattern configuration section indicates the number of tone groups, starting at the last tone group, to be replayed during subsequent repetitions. This allows a tone pattern to be defined that begins with a special sequence of tone groups, followed by a regular pattern of tone groups or a continuous tone group. An example of this is the stutter dialtone. This tone is made up of three or more bursts (or beeps) of 100 ms on / 100 ms off followed by continuous on. The following example is a tone pattern configuration section where the first three 92

99 .3 Basic Functions Media Processing cadence entries are the beeps, and the last cadence entry is the standard dialtone. The dialtone portion must be the repeated portion. To achieve this, the repeat key is set to 1 indicating only the last cadence entry is to be repeated. [stutter_dialtone] repeat=1 cadences=2 cadence0=toneg31 cadence1=toneg31 cadence2=toneg31 cadence3=toneg Detecting Tones on a Channel The tone groups that can be detected on a channel are listed in the [tone_detection] section of the root configuration file. To detect a tone group on a channel, the user application uses the PKX_CHANNEL_EnableToneDetection function. The parameters passed to this function are: The channel handle. The index to the tone group entries in the [tone_detection] section of the root configuration file. NOTE: If tone detection has been disabled using the PKX_CHANNEL_SetConfig API function, no tones will be collected until it is enabled. This applies only when using the AoH low-level product. When GP detects a tone group on the channel, a PKX_EVENT_CHANNEL_TONE_ON event is generated. The parameter fields of this event contain the following information: Parameter Description Field p0 The index of the tone group that was detected. p1 Time, in milliseconds, since the last tone stopped being transmitted. Maximum duration is milliseconds with an accuracy of +/-6 milliseconds. p2 Not used. When GP detects a tone group is no longer being transmitted on the channel, a PKX_EVENT_CHANNEL_TONE_OFF event is generated. The parameter fields of this event contain the following information: 93

100 Media Processing.3 Basic Functions Parameter Description Field p0 The index of the tone group that has stopped being transmitted. p1 Time, in milliseconds, since the tone group was detected. Maximum duration is milliseconds with an accuracy of +/-6 milliseconds. p2 Not used. To terminate the detection of a tone group on a channel, the user application uses the PKX_CHANNEL_DisableToneDetection function. The parameters passed to this function are: The channel handle. The index to the tone group entries in the [tone_detection] section of the root configuration file. Multiple tone groups can be enabled for detection at the same time on a single channel Detecting Speech on a Channel To receive notifications of the detection or absence of speech on a channel, the user application calls the function PKX_CHANNEL_EnableSpeechDetection. When speech detection on the channel is enabled and speech is detected, a PKX_EVENT_CHANNEL_SPEECH_ON event is generated, and, when the absence of speech is detected, a PKX_EVENT_CHANNEL_SPEECH_OFF event is generated. The PKX_CHANNEL_DisableSpeechDetection function is called to turn off speech detection on a channel. The following diagram demonstrates when the PKX_EVENT_CHANNEL_SPEECH_ON and PKX_EVENT_CHANNEL_SPEECH_OFF events are generated. 94

101 .3 Basic Functions Media Processing.3..8 Audio Flags An audio flag parameter is passed to the GP play and record functions. The audio flag specifies the encoding format, sampling rate, whether to play an initial beep tone prior to recording, and whether the sample is encoded with a WAVE header. The following table indicates which values can be set for each function: GP API Function Encoding Sampling Initial Beep Format Rate WAVE Header PKX_CHANNEL_PlayFile Required Required Ignored Allowed PKX_CHANNEL_PlayAddData Required Required Ignored Allowed PKX_CHANNEL_RecordFile Required Required Allowed Allowed PKX_CHANNEL_Record Required Required Allowed Ignored Required means a value must be specified for the function. Allowed means a value may be specified for that function. Ignored means the value is ignored for the function. Only one encoding format and one sampling rate may be used at a time. The encoding format, sampling rate, initial beep, and WAVE header values are ORed together. All the audio data buffers added for one play function must use the same encoding format and sampling rate. If audio data is added for a play function from files with the WAVE flag set, the audio format is extracted from the WAVE file header. All the encoding formats and sampling rates must be the same in all the WAVE file headers for one play function. A PKX_ERROR_CHANNEL_INCONSISTENT_AUDIO_FORMAT error is returned when a data block is queued for a play request, where the queued block specifies a different audio format or sampling rate than a previously queued data block. This error is also returned when the PKX_AUDIO_WAVE_HEADER flag is specified for a data buffer. The encoding format values are: Encoding Format Description PKX_AUDIO_ENCODING_LINEAR_16BIT_INTEL Linear 16-bit ITU PCM Intel (Little Endian) encoding. 9

102 Media Processing.3 Basic Functions PKX_AUDIO_ENCODING_LINEAR_16BIT_MOTOROLA Linear 16-bit ITU PCM Motorola (Big Endian) encoding. Supported only on the WARP appliance. PKX_AUDIO_ENCODING_MU_LAW North American mu-law ITU PCM encoding. PKX_AUDIO_ENCODING_A_LAW European a-law ITU PCM encoding. PKX_AUDIO_ENCODING_ADPCM_4BIT_PIKA Adaptive 4-bit PCM encoding. PKX_AUDIO_ENCODING_ADPCM_4BIT_DIALOGIC Dialogic OKI adaptive 4-bit PCM encoding. PKX_AUDIO_ENCODING_GSM_610_MS Microsoft GSM 6.10 encoding. Sampling rate flag PKX_AUDIO_SAMPLING_RATE_8KHZ must be enabled when using this encoding format. The PIKA and Dialogic ADPCM formats are identical, except the upper and lower nibbles of each byte are reversed. Linear encoding should be used when the data provided for playback is uncompressed linear PCM. The sampling rates are: Sampling Rates Description PKX_AUDIO_SAMPLING_RATE_6KHZ 6 khz sampling rate PKX_AUDIO_SAMPLING_RATE_8KHZ 8 khz sampling rate A sampling rate of 6 khz reduces the disk requirements for the stored audio, with a small reduction in the quality of the signal. The PKX_AUDIO_BEEP_BEFORE_RECORDING flag tells the recording functions to play an initial beep tone prior to recording. The PKX_AUDIO_WAVE_HEADER flag tells the play and record functions the audio encoded is specified (or must be written to the file for record) in the WAVE file header. NOTE: This flag can only be used with the PKX_CHANNEL_PlayAddData function when the PKX_TAudioData field specifies a file location. Data buffer locations must not contain a WAVE header. 96

103 .3 Basic Functions Media Processing Example Examples of setting audio flags are found in the Playing a Message Example and the Recording a Message Example Media Processing Termination Conditions A number of functions specify termination conditions. The media function continues until any of the termination conditions specified are met. When a termination condition is met, an event is generated and the media processing that specified the termination condition ends. The p0 field of the event specifies function type that terminated. The following table lists the termination conditions, the event generated when the termination condition is met, and the value specified in the p1 field of the event. Termination Condition Description Event Generated Event p1 Value digitmask Terminate the media function when any of the DTMF digits specified in the mask are received. PKX_EVENT_CHANNEL_TERM_ The DTMF digit DIGIT_MASK received maxdigits Terminate the media function when the specified number of digits has been received. PKX_EVENT_CHANNEL_TERM_ Number of digits MAX_DIGITS received timeout Terminate the media function when the specified period of time, in milliseconds, has passed. PKX_EVENT_CHANNEL_TERM_ Timeout period TIMEOUT initialsilencetimeout Terminate the media function when the PKX_EVENT_CHANNEL_TERM_ Initial specified period of initial silence (no digits INITSILENCE_TIMEOUT silence for digit collection or voice for recording), timeout in milliseconds, has passed. period silencetimeout Terminate the media function when the specified period of silence after receiving voice, in milliseconds, has passed. PKX_EVENT_CHANNEL_TERM_ Silence timeout SILENCE_TIMEOUT period nonsilencetimeout Terminate the media function when the specified period of non-silence (DTMF digit), in milliseconds, has been received. PKX_EVENT_CHANNEL_TERM_ Non-silence timeout NONSILENCE_TIMEOUT period interdigittimeout Terminate the media function when the specified amount of time after receiving a digit, in milliseconds, has passed. PKX_EVENT_CHANNEL_TERM_ Inter-digit timeout INTERDIGIT_TIMEOUT period 97

104 Media Processing Note:.3 Basic Functions For the digitmask and maxdigits termination conditions, digits in the channel digit buffer are considered when determining if the termination condition has been met. See Collecting DTMF Digits (pg. 88) for more information on these termination conditions. For maxdigits, the value returned in p1 matches the value specified in the termination conditions of the media processing call. The timeout values returned in p1 also match the value specified in the termination conditions of the media processing call. The following table lists the values assigned to the p0 field of a termination condition met event: Event p0 Field Value Description Applicable Functions PKX_MEDIA_COLLECT_DIGITS The channel was collecting digits. PKX_CHANNEL_CollectDigits PKX_MEDIA_PLAY_AUDIO PKX_CHANNEL_Play The channel was playing audio. PKX_CHANNEL_PlayFile PKX_MEDIA_RECORD_AUDIO The channel was recording audio. PKX_CHANNEL_Record PKX_CHANNEL_RecordFile PKX_MEDIA_PLAY_TONE The channel was playing a tone. PKX_CHANNEL_PlayTone PKX_CHANNEL_PlayTonePattern The following table lists the media functions that specify termination conditions, and the termination conditions allowed for each function: GP API Function Digit Mask Maximum Timeout Initial Silence Non- InterNumber Silence silence digit of Digits Timeout PKX_CHANNEL_CollectDigits Allowed Allowed Allowed PKX_CHANNEL_Play Allowed Allowed Allowed Allowed PKX_CHANNEL_PlayFile Allowed Allowed Allowed Allowed PKX_CHANNEL_PlayTone Allowed Allowed Allowed Allowed PKX_CHANNEL_PlayTonePattern Allowed Allowed Allowed Allowed Allowed Allowed Allowed Allowed Allowed Allowed PKX_CHANNEL_Record 98 Allowed Allowed Allowed

105 .3 Basic Functions PKX_CHANNEL_RecordFile Allowed Allowed Media Processing Allowed Allowed Allowed Allowed The following table lists the values that can be ORed together to create a digit mask and the corresponding DTMF keys: Mask Constant DTMF Key PKX_MEDIA_DTMF_DIGIT_1 1 PKX_MEDIA_DTMF_DIGIT_2 2 PKX_MEDIA_DTMF_DIGIT_3 3 PKX_MEDIA_DTMF_DIGIT_4 4 PKX_MEDIA_DTMF_DIGIT_ PKX_MEDIA_DTMF_DIGIT_6 6 PKX_MEDIA_DTMF_DIGIT_7 7 PKX_MEDIA_DTMF_DIGIT_8 8 PKX_MEDIA_DTMF_DIGIT_9 9 PKX_MEDIA_DTMF_DIGIT_0 0 PKX_MEDIA_DTMF_DIGIT_STAR * PKX_MEDIA_DTMF_DIGIT_POUND # PKX_MEDIA_DTMF_DIGIT_A A PKX_MEDIA_DTMF_DIGIT_B B PKX_MEDIA_DTMF_DIGIT_C C PKX_MEDIA_DTMF_DIGIT_D D NOTE: Any termination condition involving DTMF digits will never be met if DTMF detection has been disabled using the PKX_CHANNEL_SetConfig API function. This applies only when using the AoH low-level product. Example Examples of setting termination conditions are found in the Recording A Message Example and Collecting Digits Example. Examples of the events generated by the the termination conditions are found in the Record Termination Condition Example, Getting Digits Example, and Collecting Digits Termination Condition Example. 99

106 Media Processing.3 Basic Functions Fax Processing Before sending or receiving a fax, the user application must prepare a list of one or more documents using the function PKX_CHANNEL_FaxAddDocument. This function takes the following parameters: the channel that will be used to send or receive the fax the document information specified in the structure PKX_TFaxDocParms The following document information should be specified: Header - fax header information File name - Name of the fax document file Send/Receive Flag to indicate whether the document will be sent or received, one of: PKX_FAX_DOCUMENT_SEND PKX_FAX_DOCUMENT_RECEIVE The user application may add multiple documents using this function, but not once a fax session is in progress. The default page header string is: To: %r From: %l Date: %d/%m/%y Time: %H:%M Page: %P To specify a custom fax header, the tags listed in the following table can be used. The tags are replaced with the actual values during internal processing. 100 Code Length Name Format %a 3 Day of week Three-character abbreviation %d 2 Date 01 to 31 %m 2 Month 01 to 12 %y 2 Year 00 to 99 %Y 4 Year 0000 to 9999 %I 2 12 hour 01 to 12 %H 2 24 hour 00 to 23 %M 2 Minute 00 to 9 %S 2 Seconds 00 to 9 %p 2 AM/PM AM or PM

107 .3 Basic Functions Media Processing %P 2 Page number 01 to 99 %T 2 Total Pages 01 to 99 %l 20 Local ID (sender) 0-9, + or spaces %r 20 Remote ID (receiver) 0-9, + or spaces %% 1 Percent % Note: Ensure that the printheader flag in the PKX_TFaxConfig structure is set or no header is added to the document. To send or receive a fax, the user application uses the functions PKX_CHANNEL_FaxSend and PKX_CHANNEL_FaxReceive, respectively. When calling these functions, configuration information must be specified to negotiate the fax transmission with the far-end. The function PKX_CHANNEL_FaxGetDefaultConfig should be used to initialize the configuration structure prior to calling the send or receive functions.the following table describes the configuration parameters. Parameter Description Default(s) ECMEnabled Enable error correction mode. PK_TRUE PK_FALSE: Disabled PK_TRUE: Enabled encoding PKX_FAX_ENCODING_MH: 1-D run length encoding. Fixed codes for black and white run lengths. PKX_FAX_ENCODING_MMR PKX_FAX_ENCODING_MMR: 2-D encoding that provides additional compression. Encoding lines are not separated by EOLs. Six EOLs indicate the end of the page. PKX_FAX_ENCODING_MR: 2-D encoding that provides additional compression by encoding two lines at a time. The second line specifies changes form the first. A special code is used for EOL. 101

108 Media Processing eventmask This mask can be used to enable some optional FAX events. Possible events are:.3 Basic Functions 0 PKX_FAX_EVENT_MASK_CONTROL_FRAME PKX_FAX_EVENT_MASK_DEFAULT PKX_FAX_EVENT_MASK_DISCONNECTED PKX_FAX_EVENT_MASK_DISCONNECTING PKX_FAX_EVENT_MASK_PAGE_SUCCESS PKX_FAX_EVENT_MASK_TRAINING idrequired Indicates if an id number is required (PK_TRUE) or not (PK_FALSE). PK_FALSE level Used to change the modem signal level in dbm (dbm0) PKX_FAX_LEVEL_MAX: 0.0 PKX_FAX_LEVEL_DEFAULT: -13. PKX_FAX_LEVEL_MIN: minimumrate The minimum transmit or receive rate in bps: PKX_FAX_RATE_2400 PKX_FAX_RATE_2400 PKX_FAX_RATE_4800 PKX_FAX_RATE_7200 PKX_FAX_RATE_9600 PKX_FAX_RATE_12000 PKX_FAX_RATE_14400 modemtype The type of modem to transmit or receive: PKX_FAX_MODEM_V17 PKX_FAX_MODEM_V27 PKX_FAX_MODEM_V29 PKX_FAX_MODEM_V17 PKX_FAX_MODEM_V29 PKX_FAX_MODEM_V27 PKX_FAX_MODEM_V33 PKX_FAX_MODEM_V33 printheader Indicates if a print header is required (PK_TRUE) or not (PK_FALSE). SID Sender Identification. This field should be set when sending a fax because some fax terminals reject faxes if the calling terminal does not identify itself. timeout Indicates the timeout value, in ms. The possible settings are: PKX_FAX_TIMEOUT_MIN PK_FALSE PKX_FAX_TIMEOUT_DEFAULT PKX_FAX_TIMEOUT_DEFAULT PKX_FAX_TIMEOUT_MAX 102

109 .3 Basic Functions Media Processing Additional configuration parameters available for documents to be sent are: Parameter Description Default CNGEnabled EnableTransmit Calling Tone: Enabled (PK_TRUE) or Disabled (PK_FALSE). PK_TRUE maximumrate Specifies the maximum transmit rate in bps: PKX_FAX_RATE_14400 PKX_FAX_RATE_2400 PKX_FAX_RATE_4800 PKX_FAX_RATE_7200 PKX_FAX_RATE_9600 PKX_FAX_RATE_12000 PKX_FAX_RATE_14400 Additional configuration parameters available for documents to be received are: Parameter Description Default CEDEnabled Enable sending Transmit Called Station Identification PK_TRUE tone: Enabled (PK_TRUE) or Disabled (PK_FALSE). NSF Non-standard Facilities frame NULL NSFLength Size of actual data in NSF array 0 pagewidth Specifies the page width: PKX_FAX_WIDTH_ALL PKX_FAX_WIDTH_A3 (11.7x16. in/297x420 mm) PKX_FAX_WIDTH_A4 (8.3x11.7 in/ 210x297 mm) PKX_FAX_WIDTH_ALL (all supported page widths) PKX_FAX_WIDTH_B4 (9.8x13.8 in/ 27x364 mm) PKX_FAX_WIDTH_LEGAL (8.x14 in/ 216x36 mm) PKX_FAX_WIDTH_LETTER (8.x11 in/216x279 mm) 103

110 Media Processing resolution.3 Basic Functions Specifies the required resolution of the received document in dpi: PKX_FAX_RESOLUTION_SUPER_HIGH PKX_FAX_RESOLUTION_ALL (all supported values) PKX_FAX_RESOLUTION_HIGH (204x196) PKX_FAX_RESOLUTION_LOW (204x98) PKX_FAX_RESOLUTION_SUPER_HIGH (204x391) After the fax session starts, the user application receives the following events indicating the progress of the fax: Event Description Parameters PKX_EVENT_CHANNEL_FAX_STARTED The current fax session started sending or receiving a fax. None PKX_EVENT_CHANNEL_FAX_TRAINING The modems involved in the current fax session are training (optional event) None PKX_EVENT_CHANNEL_FAX_TRAINING_SUCCESS The current fax session has successfully negotiated transmission parameters (optional event) PKX_EVENT_CHANNEL_FAX_TRAINING_FAILED The current fax session has failed to negotiate transmission parameters. Subsequent attempts to train at lower transfer rates may still succeed. (optional event) PKX_EVENT_CHANNEL_FAX_CONTROL_FRAME The current fax session has sent p0: Indicates the or received a control frame. type of control frame PKX_EVENT_CHANNEL_FAX_DOCUMENT_BEGIN The current fax session has started exchanging a document 104 None None None PKX_EVENT_CHANNEL_FAX_PAGE_BEGIN The current fax session started a None page. PKX_EVENT_CHANNEL_FAX_PAGE_END The current fax session finished a page. None

111 .3 Basic Functions Media Processing PKX_EVENT_CHANNEL_FAX_DOCUMENT_END The current fax session finished a document. None PKX_EVENT_CHANNEL_FAX_DISCONNECTING The current fax session is disconnecting (optional event) None PKX_EVENT_CHANNEL_FAX_DISCONNECTED The current fax session has received a DCN message from the remote side (optional event) None PKX_EVENT_CHANNEL_DONE_FAX The current fax session is complete. p0: mode p1: result p2: lasterror All parameters are the same as those in PKX_TFaxStatus. The user application can use the function PKX_CHANNEL_FaxGetStatus at any time to retrieve detailed information about the transmission progress, any errors, and negotiated parameters. Upon completion of the transmission (indicated by receiving the event PKX_EVENT_CHANNEL_DONE_FAX) the application should use this function to determine the final outcome of the fax transmission. The function returns a structure PKX_TFaxStatus which contains the following information. Some fields correspond to those specified in PKX_TFaxConfig and reflect the values chosen when the fax transmission was negotiated with the far end. Field Description PK_UINT rate Current transmission rate. PK_UINT resolution Current transmission resolution. PK_UINT encoding Current transmission encoding. PK_UINT pagewidth Current page width. 10

112 Media Processing PK_UINT mode.3 Basic Functions Current mode of operation. PKX_FAX_MODE_IDLE PKX_FAX_MODE_CONNECTING PKX_FAX_MODE_NEGOTIATING PKX_FAX_MODE_RECEIVING PKX_FAX_MODE_SENDING PKX_FAX_MODE_DISCONNECTING PKX_FAX_MODE_FINISHED PK_UINT result Result of the previous fax attempted. PKX_FAX_RESULT_IN_PROGRESS PKX_FAX_RESULT_SUCCESSFUL PKX_FAX_RESULT_NOFAX PKX_FAX_RESULT_PARTIAL PKX_FAX_RESULT_NEG_FAILED PKX_FAX_RESULT_FAILED_TO_TRAIN PKX_FAX_RESULT_PROTOCOL_ERROR PKX_FAX_RESULT_FAILED 106 PK_UINT lasterror Last error encountered. PK_UINT ECMEnabled Indicates whether the previous fax was ECM. PK_UINT duration Duration in milliseconds. PK_UINT documentnumber Current document in progress. PK_UINT pagenumber Current page of the document. PK_UINT NEG_count Number of negotiating frames processed. PK_UINT FTT_count Failure to train frames processed. PK_UINT CFR_count Confirmation to receive frames processed. PK_UINT MCF_count Message confirmation frames processed. PK_UINT PPR_count Partial page request frames processed. PK_UINT RTN_count Retrain negative frames processed. PK_UINT DCN_count Disconnect frame processed. PK_UINT badlinecount Number of bad lines on current page. PK_UINT RXPages Number of pages received. PK_UINT TXPages Number of pages transmitted.

113 .3 Basic Functions PK_UINT RXBytes Number of bytes received by modem. PK_UINT TXBytes Number of bytes transmitted by modem. PK_UINT RXPageErrors Number of pages with line errors. PK_UINT RXTotalLines Total lines. PK_UINT TXTotalLines Total lines. PK_CHAR documentname Document. PK_CHAR remotesid Received SID. PK_U8 remotensf Received NSF. PK_UINT synopsislength Number of integers in session summary. PK_INT synopsis T.30 protocol session summary. Media Processing When establishing a call to transmit a fax, the user application should enable call analysis to determine whether a fax machine has answered the call. Refer to section Call Analysis (pg. 33). The following diagram shows establishing a call, sending a fax and the events the application can expect to receive. 107

114 Media Processing.3 Basic Functions The user application uses PKX_CHANNEL_Stop to stop a fax transmission (send or receive) already in progress. This function takes the following parameter: the channel on which the fax operation is being executed The event PKX_EVENT_CHANNEL_STOPPED_FAX will be returned to indicate that the fax operation has been stopped. The user application can use the function PKX_CHANNEL_ClearDocument if documents are added but send or receive has not started. This flushes the document queues; no documents are left in the queues. Example The following is an example of setting up a fax document and sending it. 108

115 .3 Basic Functions Media Processing // Send a fax. Channel is passed in from calling function. Header // is re-set to default as an example of how to set it. Minimum // transfer rate is set to 9600 as an example of modifying the // PKX_TFaxConfig struct. This function also adds a second page to // the fax. The opposite of this function (receive) can be achieved // by changing: // -PKX_FAX_DOCUMENT_SEND to PKX_FAX_DOCUMENT_RECEIVE // -PKX_CHANNEL_FaxSend() to PKX_CHANNEL_FaxReceive() // -Remove second PKX_CHANNEL_FaxAddDocument() call (only one // is needed to receive) // NOTES: // FAX_FILE_TO_SEND_P1/P2 are predefined strings containing // the address of the *.tif file PK_BOOL sendfax(tpikahandle channelhandle) { PKX_TFaxConfig faxconfig; PKX_TFaxDocParms faxdocparms; PK_STATUS status = PK_SUCCESS; memset(&faxdocparms, 0, sizeof(pkx_tfaxdocparms)); memset(&faxconfig,0,sizeof(pkx_tfaxconfig)); if ((status = PKX_CHANNEL_FaxGetDefaultConfig(channelHandle,&faxconfig))!= PK_SUCCESS) { // Error getting default configuration } faxconfig.minimumrate = PKX_FAX_RATE_9600; strncpy(faxdocparms.header, "To: %r From: %l Date: %d/%m/%y Time: %H:%M Page: %P", PKX_FAX_MAX_HEADER_LENGTH); strncpy(faxdocparms.filename, FAX_FILE_TO_SEND_P1,PKX_FAX_MAX_FILENAME_LENGTH); faxdocparms.sendorreceive = PKX_FAX_DOCUMENT_SEND; if ((status = PKX_CHANNEL_FaxAddDocument(channelHandle,&faxdocparms))!= PK_SUCCESS) { // Error adding document } strncpy(faxdocparms.filename, FAX_FILE_TO_SEND_P2,PKX_FAX_MAX_FILENAME_LENGTH); if ((status = PKX_CHANNEL_FaxAddDocument(channelHandle,&faxdocparms))!= PK_SUCCESS) { // Error adding document } if ((status = PKX_CHANNEL_FaxSend(channelHandle,&faxconfig))!= PK_SUCCESS) { // Error sending fax 109

116 Conferencing.3 Basic Functions } } Fax Diagnostics Fax includes some advanced logging capabilities that can be used to debug fax specific problems. There are two types of logs that can be enabled: audio recordings and fax protocol logs. It is also possible to have the logging facility only keep logs and recordings from fax sessions that fail. The logging does add additional stress on a system, so logs should not be be enabled on more than a few channels. Audio logging causes less stress than the protocol logging. Deleting successful logs and recordings adds additional system stress since the files are created and then deleted when a successful session completes. There are two methods available for enabling the logging. The easiest method is to set the logging in the configuration file. This method sets the logging on all channels. In the logging section of pikagp_aoh.cfg, the following can be added to enable fax logging: [logs] level=none object.mediastream=0x f ;files=2 ;size=12 ;cref=yes Alternatively, if the user application needs to control the logging using an API call or if an application wants to control the logging on individual channel, the AoH logging API can be used. This mechanism is described in the Low Level API Programmer s Guide, which is available on PIKA's website at SDK: downloads & docs for HMP Boards. To control logging on an individual channel, the function PKX_CHANNEL_GetBypassInfo is required to retrieve the output media stream handle. It is not necessary to enable bypass mode..3.6 Conferencing A conference object is required when more than two channels must be joined together. The PKX_CONF_Create function creates a new conference object of the type specified. The conference types available are: 110

117 .3 Basic Functions Conferencing Conference Type Description PKX_CONF_TYPE_BASIC The voices of all participants are added together and sent to each participant (minus that participant's own voice). PKX_CONF_TYPE_ADVANCED The voice of the loudest speaker is delivered to each participant (the loudest speaker will hear the voice of the next loudest speaker). When the conference object is created, conference members can be managed using the functions listed in the following table. These functions are asynchronous and return immediately. Low-level functions process the adding, changing, or removing of a conference member. When the action is complete, the low-level function generates an event. Failure of a conference function generates a PKX_EVENT_CONF_TASK_FAILED event. The p1 field of the event provides the PK_STATUS error code specifying the reason the function failed. Function Description Event Generated PKX_CONF_AddMember Adds a channel to a conference. The channel conference configuration is specified as a parameter of type PKX_TConfMemberConfig to this function. PKX_EVENT_CONF_ MEMBER_ADDED PKX_CONF_ChangeMember Changes a channel conference configuration by passing in a new PKX_TConfMemberConfig structure. PKX_EVENT_CONF_ PKX_CONF_RemoveMember Removes a channel from a conference. PKX_EVENT_CONF_ MEMBER_MODIFIED MEMBER_REMOVED Configurable conference member parameters are: Conference Description Member Configuration Parameter type Type of member connection to make. PKX_CONF_MEMBER_TYPE_FULL - Full conference member with talking and listening privileges. PKX_CONF_MEMBER_TYPE_MONITOR - Listen-only member. 111

118 Conferencing inputgain.3 Basic Functions Gain (in db) to apply to the voice from the member to the conference. Minimum - PKX_CONF_MEMBER_GAIN_MIN Default - PKX_CONF_MEMBER_GAIN_DEFAULT 0.0 Maximum - PKX_CONF_MEMBER_GAIN_MAX 24.0 outputgain Gain (in db) to apply to the output of the conference to the member. Minimum - PKX_CONF_MEMBER_GAIN_MIN Default - PKX_CONF_MEMBER_GAIN_DEFAULT 0.0 Maximum - PKX_CONF_MEMBER_GAIN_MAX 24.0 Echo Cancellation Echo cancellation is automatically applied when a digital TDM channel is added to the conference. When echo cancellation is enabled, there is a potential delay due to the distance between the echo canceller and the echo source, or tail. Delays can be fixed by setting a value for this tail for the TDM channel. See the parameter taillength under ISDN Resources in the PIKA High Level API Configuration Guide for more information on the value range and default. Example There are three examples; they are taken from the EventProcessing function in meetme.cpp source file of the Conferencing sample application. The first example demonstrates creating the conference. The second example demonstrates adding a member to a conference. The third example demonstrates removing a member from a conference Virtual Channels in Conferences Virtual channels support the same media processing capabilities as physical channels, except they cannot make or accept calls. Virtual channels can be used in a conference for such applications as: playing the same announcement to all conference members recording audio from all conference members playing and recognizing tones from all conference members Virtual channels are created using the PKX_CHANNEL_Create function and destroyed using PKX_CHANNEL_Destroy function. Virtual channels must be removed from a conference before they are destroyed. 112

119 .3 Basic Functions Phones When the PKX_CHANNEL_Create function is used, it returns the virtual channel handle, unlike other channel types that use the PKX_CHANNEL_GetHandle function to return the channel handle. PKX_GROUP_GetConfig returns the number of currently created virtual channels. As shown in the following figure, the information flow between a physical channel and a virtual channel is opposite to the information flow between a physical channel and a conference member. If a recording is being played from a virtual channel to the conference, the information flows from the virtual channel to the physical channel to the conference members. If a recording is being made of the conference, the information flows from the conference members to the physical channel to the virtual channel. Example There are two examples; they are taken from the meetme.cpp source file of the Conferencing sample application. The first example demonstrates creating a virtual channel. The second example demonstrates destroying a virtual channel..3.7 Phones A phone channel does not have the same capabilities as other channels. The only functions a user application can perform on a phone channel are: turn ringing on and off with the PKX_CHANNEL_RingingStart and PKX_CHANNEL_RingingStop functions. send caller identification information (as part of the PKX_CHANNEL_RingingStart function). detect hook state changes on the phone. Changes in hook state generate the following events: 113

120 Phones Phone Channel Event.3 Basic Functions Description PKX_EVENT_CHANNEL_PHONE_HOOKFLASH Indicates the remote phone has just performed a hookflash. PKX_EVENT_CHANNEL_PHONE_OFFHOOK Indicates the remote phone has just gone offhook. PKX_EVENT_CHANNEL_PHONE_ONHOOK Indicates the remote phone has just gone onhook. See the Phone Resources section of the Configuration Guide for phone configuration parameters. Ringing a Channel To generate a ringing pattern on a channel, the user application uses the PKX_CHANNEL_RingingStart function. The parameters passed to this function are: The channel handle. The index into the entries of the [ring_pattern] section of the GP configuration file. This pattern is used to generate the ring pattern transmitted on a channel. The timeout period. Ringing continues until the far end answers or the timeout period expires. Caller information. The caller information to be displayed to the called party. The PKX_CHANNEL_RingingStart function also sends protocol-specific messages to the far-end device to indicate the called party should be alerted. If the call is not answered by the phone in the timeout period specified in the function call, the ringing is stopped and a PKX_EVENT_CHANNEL_DONE_RINGING event is raised. The p0 field of this event specifies the cause and is set to PKX_CALL_DROP_CAUSE_NOANSWER. If the phone is already offhook, the ringing is stopped and a PKX_EVENT_CHANNEL_DONE_RINGING event is raised. The p0 field of this event specifies the cause and is set to PKX_CALL_DROP_CAUSE_BUSY. If the phone goes offhook while ringing, ringing is automatically stopped and no PKX_EVENT_CHANNEL_DONE_RINGING event is raised. Only the PKX_EVENT_CHANNEL_PHONE_OFFHOOK event is raised. The user application uses the PKX_CHANNEL_RingingStop to stop the ringing pattern from being sent to a 114

121 .3 Basic Functions Phones channel. 11

122 6 6 Building a High Level API Application To develop an application based on the high level API: Header files must be included in the application code to allow the code to compile. The high level API library (Windows - pikagpapi.lib, Linux - libpikagpapi.so) must be linked with the application code to create an executable. The high level API is a multi-threaded product. Applications using the high level API must enable the multi-thread flag for Windows software projects. To test an application based on GP: The low level API libraries and drivers must be installed on the testing platform. If you use the installer, these files are automatically installed in the required locations. When PIKA cards are used, the cards must be installed on the testing platform. A license.keys file, licensing the appropriate resources, must be generated and copied to the testing platform. See the License Activation section of the PIKA HMP Getting Started Guide, available on the PIKA Support web page, for more information about generating the license.keys file. Optionally, when PIKA cards are used, the configuration file pika.cfg may be created to statically map card serial numbers to board identifiers. 6 Optionally, environment variables may be set to specify directories, different from the defaults, for the location of configuration files and log files. Header Files Header files provide definitions of the functions and constants used by applications. Windows - On Windows development platforms, the header files can be found in hmpinstalldirectory\inc. The default is: C:\Program Files\PIKA\hmp\inc Linux - On Linux development platforms, the header file (pikagpapi.h) can be found in /usr/include/pika. Libraries Libraries are linked statically or dynamically with the developer's code to create the user application. Windows 116

123 6 The file pikagpapi.lib is the static library used to link the user application. On Windows development platforms, libraries are provided for three versions of Windows in the folder hmpinstalldirectory\lib (default location C:\Program Files\PIKA\hmp\lib): Windows XP/Server bit - hmpinstalldirectory\lib\xp_2k3\win32 Windows 7 32-bit - hmpinstalldirectory\lib\7\win32 Windows 7/Server bit - hmpinstalldirectory\lib\7_2008r2\x64 The libraries for the operating system currently running on the computer are in hmpinstalldirectory\lib. If you want to compile your application for a Windows operating system other than the one currently running on the computer, set the environment variable PKH_LIB_DIR to the corresponding path of the libraries for the platform. For example, to build your application for Windows 7 32-bit, set PKH_LIB_DIR to hmpinstalldirectory\lib\7\win32. The folder C:\WINDOWS\system32 contains dynamically loaded libraries used when executing the user application: libpikagpgwy.dll (for low level API support) pikagpapi.dll libpikasipsrv.dll (for SIP server support) libpikasipua.dll (for SIP user agent support) The directory hmpinstalldirectory\hmp\debug contains debug versions of these libraries: 6 libpikagpgwy.dll (for low level API support) pikagpapi.dll libpikasipsrv.dll (for SIP server support) libpikasipua.dll (for SIP user agent support) Linux Ensure that the appropriate compiler, linker, and make utilities can be found in the PATH environment variable. The required libraries for HMP are in /usr/lib (32-bit operating systems) or /usr/lib64 (64-bit operating systems), where version is the release version number. If you use the installer, these files are automatically installed in the required locations. libpikagpapi.a and libpikagpapi.so.version libpikagpgwy.a and libpikagpgwy.so.version If your application uses SIP, install the following libraries from hmpinstalldirectory/plugins/32-bit to /usr/lib (32-bit operating systems) or from hmpinstalldirectory/plugins/36-bit to /usr/lib64 (64-bit operating systems). If you use the installer, these files are automatically installed in the required locations. libpikasipsrv.so.version 117

124 6 libpikasipua.so.version Configuration Files The following configuration files contain information that does not normally need to be changed. The default configuration file contains includes for the following: Root Configuration Include File Contains inccpa.cfg call progress parameters, see Call Progress in the PIKA High Level API Configuration Guide. inctonepatterns.cfg tone patterns and corresponding tone pattern generation parameters, see Tone Pattern Generation in the PIKA High Level API Configuration Guide. inctonegen.cfg tone generation and corresponding tone generation parameters, see Tone Generation in the PIKA High Level API Configuration Guide. inctonedet.cfg tone detection, see Tone Detection in the PIKA High Level API Configuration Guide. incringpatterns.cfg ring patterns and the corresponding ring pattern parameters, see Ring Patterns in the PIKA High Level API Configuration Guide. 6 Environment Variables The following environment variables can be optionally set when executing user applications on the PIKA GrandPrix SDK platform. Environment Variable Description Default Used If No Value Is Assigned to the Environment Variable PKH_BASE_DIR Specifies the directory where HMP is installed. Windows - C:\Program Files\PIKA\hmp ( the C:\Program Files directory name is dependent on the OS language) Linux - /usr/share/pika/hmp 118

125 6 PKH_LOGS_DIR Specifies the base directory under which the log files are written. A separate sub-directory is created for each run of the user application. Windows XP and Windows Server 2003 %PKH_BASE_DIR%\logs\ Windows 7 and Windows Server 2008 C:\ProgramData\PIKA\hmp\logs Linux - /var/log/pika NOTE: C:\ProgramData is a hidden folder. A shortcut to C:\ProgramData\PIKA\hmp is provided in the submenu PIKA HMP SDK on the Start menu. PKH_CONF_DIR Specifies the directory where the configuration files are located. Windows XP and Windows Server 2003 %PKH_BASE_DIR%\conf\ Windows 7 and Windows Server 2008 C:\ProgramData\PIKA\hmp\conf Linux - /etc/pika NOTE: C:\ProgramData is a hidden folder. A shortcut to C:\ProgramData\PIKA\hmp is provided in the submenu PIKA HMP SDK on the Start menu. Application Tools The following high level API tools are provided with HMP: 6 GPTest: An application used to test and demonstrate high level API functionality by allowing the user to perform functions from the command line, such as making a call, detecting DTMF tones, and creating switch connections. GPConfig: An application used to configure the high level API. Source Files - The source files required to make the high level API libraries and the GPTest and GPConfig applications are provided. Windows - The source code is provided in hmpinstalldirectory\source\gp. The source code for the applications is provided in hmpinstalldirectory\source\gp\applications\applicationname. Visual Studio 200 Professional project files are included with the source code in hmpinstalldirectory\source\gp. Binaries are located in source\gp\output. These workspaces are provided to allow you to modify and rebuild the libraries, and to build the gptest application. Linux - The source code for GP libraries is provided in the /usr/share/pika/hmp/grandprix/source directory.the source code for the applications is provided in the /usr/share/pika/hmp/grandprix/source/applications/applicationname directory. Makefiles are provided to compile the libraries and applications. 119

126 6 NOTE: Always copy the source to a private location before modifying it. Otherwise, subsequent installations of GP overwrite any changes you have made

127 7.1 Distributing a PIKA High Level API 7 Distributing a High Level API Application The same user application can be deployed under either the Windows or Linux operating systems (OSs). The differences between the two OSs are: The applications must be compiled and linked under the appropriate OS. Different library files must be redistributed. 7.1 Distributing a PIKA High Level API Application on Windows To distribute a user application based on the high level API to a Windows deployment platform, perform the following steps. 1. Install the low level API redistribution libraries as described in the PIKA Low Level API Programmer's Guide. 2. Install the HMP drivers as described in the PIKA Low Level API Programmer's Guide, including restarting the computer. 3. Install any required boards as described in the PIKA HMP Getting Started Guide Install the high level API libraries in C:\Windows\System32 on the deployment platform. The redistribution files can be found in hmpinstalldirectory\redist where the default for hmpinstalldirectory is C:\Program Files\PIKA\hmp. There are redistribution files for each of the following operating systems: Windows XP and Windows Server bit - hmpinstalldirectory\redist\xp_2k3\win32 Windows 7 32-bit - hmpinstalldirectory\redist\7\win32 Windows 7 and Windows Server bit - hmpinstalldirectory\redist\7_2008r2\x64 You need to install the following libraries. You can install either the versions from the redistribution directory for the operating system running on the deployment platform, or, if you have modified the GP source, your own versions of these libraries. pikagpapi.dll pikagpgwy.dll 121

128 7.2 Distributing a PIKA High Level API If your application requires SIP support, you need to install the following libraries from the redistribution directory for the operating system running on the deployment platform. Note that building the GP source does not build these libraries. libpikasipsrv.dll libpikasipua.dll. Set the environment variables (optional). If the configuration files or log files are going to be placed in locations other than the default folders, the appropriate environment variable must be set to the new location. Environment Variable Description Default Used If No Value Is Assigned to the Environment Variable PKH_BASE_DIR Specifies the directory where the HMP SDK was installed. C:\Program Files\PIKA\hmp PKH_LOGS_DIR Specifies the base directory under which the log files are written. A separate sub-directory is created for each run of the user application. Windows XP/Windows Server 2003: PKH_BASE_DIR\logs PKH_CONF_DIR Specifies the directory where the pika.cfg file is located. Windows XP/Windows Server 2003: PKH_BASE_DIR\conf Windows 7/Windows Server 2008: C:\ProgramData\PIKA\hmp\logs Windows 7/Windows Server 2008: C:\ProgramData\PIKA\hmp\conf 6. Install the configuration files. Copy the configuration files to the directory specified by the PKH_CONF_DIR environment variable Install the user application. 8. Generate and install the license keys as described in the PIKA HMP Getting Started Guide. 9. Restart the deployment platform. 7.2 Distributing a PIKA High Level API Application on Linux To distribute a user application based on the high level API to a Linux deployment platform, perform the following steps. 122

129 7.2 Distributing a PIKA High Level API 1. Install the low level API redistribution files as described in the PIKA Low Level API Programmer's Guide. 2. Install any required boards. 3. Install the high level API libraries. Copy the following files to the directory /usr/lib (32-bit operating systems) or /usr/lib64 (64-bit operating systems) on the deployment platform, where x.y.z is the release version number. You can build the GP libraries on the deployment platform as described in Building the High Level API Libraries in Linux (pg. 139) or you can copy library files from your development computer. Ensure that you use the correct libraries for the operating system running on the deployment platform. libpikagpapi.so.x.y.z libpikagpgwy.so.x.y.z If the user application uses SIP, install the SIP plug-in libraries. Separate files for 32-bit and 64-bit operating systems are provided as part of the HMP installation. However, only the files for the operating system running when HMP was installed are provided. If you need the files for a different operating system, you must run the installer on the corresponding operating system. Copy the following files from hmpinstalldirectory/plugins/64-bit to /usr/lib64 or hmpinstalldirectory/plugins/32-bit to /usr/lib, depending on the operating system running on the deployment platform. libpikasipsvr.so.x.y.z libpikasipua.so.x.y.z 4. Set the environment variables (optional). If the configuration files or log files are going to be placed in locations other than the default location, the appropriate environment variable must be set to the new location. Environment Variable Description Default Used If No Value Is Assigned to the Environment Variable PKH_BASE_DIR Specifies the directory where the HMP SDK was installed. /usr/share/pika/hmp PKH_LOGS_DIR Specifies the base directory where the log files are written. A separate sub-directory is created for each run of the user application. /var/log/pika PKH_CONF_DIR Specifies the directory where the configuration files are located. /etc/pika 7 NOTE: Some systems require the current user to log out before new environment variables are available. 123

130 7.2 Distributing a PIKA High Level API. Install the configuration files. Copy the configuration files to the directory /etc/pika or the directory specified by the PKH_CONF_DIR environment variable. Ensure that you include the configuration files in hmpinstalldirectory/grandprix/conf as well as the configuration file specific to your application. 6. Install the user application. 7. Generate and install the license keys as described in the PIKA HMP Getting Started Guide. 8. Restart the deployment platform

131 8.1 Configuring a Channel 8 Advanced Topics The following advanced topics are described: Configuring a Channel (pg. 12) Modifying the PIKA GrandPrix SDK Source Code (pg. 132) Bypassing the PIKA GrandPrix SDK to Make Low-level Function Calls (pg. 140) SIP (pg. 126) 8.1 Configuring a Channel Configuring a channel is optional and the default settings should be appropriate for most user applications. However, GP provides the ability to configure individual channels for specialized user applications. The PKX_CHANNEL_SetConfig function can be used to control how the recording and detection functions will operate on a channel. User applications should initialize the PKX_TChannelSettings structure by calling PKX_CHANNEL_GetConfig and passing in the channelsettings parameter. This guarantees that all fields (including fields added in later releases of this software) are set to proper default values. The user application may change the channel settings at any time unless the applicable media processing function is active on the channel. These configuration settings apply only to resources hosted by the AoH low-level product. Record Buffer Sizing The default size of the buffers used to retrieve recorded audio data is large (16 Kb), which may introduce a degree of 8 latency that is not acceptable to some user applications. If a user application requires the audio data in a more timely fashion, the channel may be configured to use smaller audio buffers. The application may change the size of the buffer used to collect recorded data by setting the buffersize field of the PKX_TChannelSettings parameter passed in to the PKX_CHANNEL_SetConfig function. The application can call this function at any time before recording is started. The minimum size of the buffer is specified in the product configuration file using the recordbuffersize parameter. If the application calls the function PKX_CHANNEL_SetConfig while recording is active on the channel, the function retursn the error code PKX_ERROR_CHANNEL_RECORDING_ACTIVE. 12

132 User Management 8.2 SIP Detection Settings By default, GP controls the activation and deactivation of DTMF and tone detection. However, certain types of user applications may want to disable tone or DTMF detection on a channel to reduce CPU usage. For example, a SIP application which handles only INFO messages could disable DTMF detection because digits are received out of band. Media termination conditions requiring tone and DTMF detection will be prevented if detection of tones and/or DTMF is disabled. For example, if detection of a DTMF digit is a termination condition for recording, DTMF detection must be enabled. 8.2 SIP This section describes features of the API that are specific to SIP calls and channels User Management Dynamic User Management SIP users can be defined statically in the pikagp.cfg configuration file or created dynamically at run-time by the user application. The following functions are available to create and manage dynamic users. This functionality is currently only support for SIP users. The functions described below cannot be used on users defined statically using the configuration file. All user creation and configuration functions are synchronous. There are no events associated with the use of these functions. 8 Function Description PKX_USER_Create Creates a user with the specified configuration values. The username and domain fields must be defined. Default values are used for any fields not specified. PKX_USER_SetConfig Updates the configuration for the specified user. With the exception of values related to registration, changes apply to the next call involving the user. PKX_USER_GetConfig Returns the current settings for the user. Configuration values that were not specified, either when the user was created or by calling PKX_USER_SetConfig on an existing user, are not included. 126

133 8.2 SIP PKX_USER_Destroy User Management Destroys a user created using PKX_USER_Create. Fields in the user configuration structure, PKX_TUserConfig, correspond to the configuration keys that can be defined for a user in the configuration file, pikagp.cfg. As with configuration keys defined at the user level in the configuration file, any value not specified in the configuration structure uses the value from the corresponding SIP group for the specified domain. String values must be specified according to the values for the associated key in the SIP User Agents section of the Configuration Guide. To specify that the configuration should use the corresponding group value, fields can be defined as follows: integer fields use the value 0 string fields use the value NULL fields with an associated enumerated type use the 'undefined' value for example, the field prackoutgoingtype uses the value PKX_SIP_PRACK_UNDEFINED all other fields use PKX_TUserConfigFlag value PKX_CONFIG_FLAG_UNDEFINED for example, the field outboundproxy uses the value PKX_CONFIG_FLAG_UNDEFINED The following table shows the configuration fields in the structure PKX_TUserConfig and the corresponding configuration file entries. Refer to the corresponding entry in the Configuration Guide for full information, including default values and ranges, for each parameter. PKX_TUserConfig Field Configuration Entry Description Value Format username user_name The name of the user, not including the domain portion. A string with less than PKX_USER_MAX _NAME_LENGT H characters. A value must be specified for this field

134 User Management domain domain The domain portion of the user name. It must match the domain key for one of groups defined in the configuration file. A string with less than PKX_USER_MAX _DOMAIN_LEN GTH characters. A value must be specified for this field. displayname display_name The name of the user, formatted for human readability. A string with less than PKX_USER_MAX _NAME_LENGT H characters. password password The password that is used to authenticate the user. A string with less than PKX_USER_MAX _PSWD_LENGT H characters. proxyaddr proxy.address The address or fully qualified domain name that identifies the SIP proxy for this user. A string with less than PK_MAX_IP_AD DRESS_LENGT H characters. proxyport proxy.port The IP port that of the user's SIP proxy. Integer value inboundregistration registration Flag indicating if inbound REGISTER requests are expected for this user. PK_TRUE SIP PK_FALSE

135 8.2 SIP outboundregistration registration User Management Flag indicating if outbound REGISTER requests should be generated for this user. PK_TRUE PK_FALSE outboundregistrationexpirydefault expires Default value to use as Integer value the expiry time in outgoing REGISTER requests (in seconds) outboundproxy Flag indicating if outbound INVITE requests should include the value of the proxyaddr field if domain-portion of "To:" is empty. supportedcodecs proxy.outbound codecs PKX_CONFIG_FL AG_UNDEFINED PKX_CONFIG_FL AG_DISABLED PKX_CONFIG_FL AG_ENABLED The set of codecs String value supported for this user. containing any subset of g711u, g711a, g729. When specifying multiple values, separate each value by a (vertical bar), for example, g729 g711u

136 User Management SIP dtmftransport dtmf_mode The DTMF transport String value mechanisms containing any supported for this user. subset of inband, rfc2833, info. When specifying multiple values, separate each value by a (vertical bar), for example, inband rfc2833. autoaccept auto_accept The set of String value hold automatically accepted or none call modifications. autoreject auto_reject The set of automatically rejected call modifications. String value media_address, media_elements or none autodrop auto_drop The set of conditions under which GrandPrix should automatically drop a call. String value in_transfer or none sessiontimerexpirydefault session_timer_length Default value to use as Integer value the expiry time for session timers (in seconds). sessiontimerexpiryminimum session_timer_minimum_length Mimimum value to use as the expiry time for session timers (in seconds). Integer value

137 8.2 SIP prackoutgoingtype reliable_provisional_ response_outgoing User Management Indicates how to deal with PRACK for outgoing calls, see PKX_TProvRespType. PKX_SIP_PRACK _UNDEFINED PKX_SIP_PRACK _DISABLED PKX_SIP_PRACK _SUPPORTED PKX_SIP_PRACK _REQUIRED prackincomingtype reliable_provisional_ response_incoming Indicates how to deal with PRACK for incoming calls, see PKX_TProvRespType. PKX_SIP_PRACK _UNDEFINED PKX_SIP_PRACK _DISABLED PKX_SIP_PRACK _SUPPORTED PKX_SIP_PRACK _REQUIRED externaladdr external_ip The address or fully qualified domain name to be used in "Contact:" headers. PK_MAX_IP_AD DRESS_LENGT H If a user is configured to handle inbound registration events or register with an external registration server, the required registration functions must be used after the user is created and before the user is destroyed. Refer to Incoming and Outgoing Registrations for more information. Example The following shows an example of setting the user configuration values and creating a user. 8 PKX_TUserConfig userconfig; memset(&userconfig,0,sizeof(pkx_tuserconfig)); sprintf(userconfig.username,"pika_dyn_user1"); sprintf(userconfig.displayname,"pika_dyn_user1_display"); sprintf(userconfig.domain,"example1.com"); sprintf(userconfig.supportedcodecs,"g729 g711u"); sprintf(userconfig.proxyaddr," "); sprintf(userconfig.proxyport,080); if ((status = PKX_USER_Create(&userConfig,&m_handle))!= PK_SUCCESS) { TEST_FAIL("PKX_USER_Create() returned %s, expected %s", PKX_ERROR_GetText(status, receivedtext, sizeof(receivedtext)), PKX_ERROR_GetText(PK_SUCCESS, expectedtext, sizeof(expectedtext))); 131

138 8.3 Modifying the High Level API Source Code return; } 8.3 Modifying the High Level API Source Code PIKA provides the source code for GP. This allows you to modify GP to provide new features specific to a user application. The read-only source should be copied from its installation directory to a development directory and its permissions changed before it is modified. This prevents your modifications from being lost when GP is reloaded or upgraded. To take advantage of features in new releases of GP, modifications made by the developer to older versions of the source code must be merged with the new release. Before modifying the GP source code, you must understand how the different threads that make up GP communicate. The main thread communicates with the low level API threads by creating events and injecting these events into the event queue of the low level product. The product threads retrieve these events, process them, and communicate the results to the main thread by creating result events and injecting them into the event queue. Lastly, the user application retrieves the result events from the queue to determine the result of the original function call. The following diagram demonstrates how the threads communicate. Functions in the yellow rectangle are low level API thread functions. Functions in grey and red are executed in the user application thread

139 8.3 Modifying the High Level API Source Code Example As an example of how to modify GP source code, a new function PKX_CONF_RemoveAllMembers is added to the interface. This example demonstrates: 8 adding a function to GP adding new methods to the conference object creating a new message to be sent to the product interfaces modifying both product threads to handle the new event type The following files need to be modified to implement this new function: Main thread functions: gp_conf.cpp 133

140 8.3 Modifying the High Level API Source Code cconference.h cconference.cpp include/pikaapi.h common/gpmsgs.h libpikagpgwy/cgatewayinterface.h libpikagpgwy/cgatewayinterface.cpp Low level API thread functions: libpikagpgwy/cmminterface.h libpikagpgwy/cmminterface.cpp libpikagpgwy/cgatewaysystem.cpp For Windows only, the.def file needs to specify the new function calls to have them exported from the.dll. include/pikagpapi.h - Define the new GP function. 8 /* * Function: PKX_CONF_RemoveAllMembers * * Summary: * Removes all members from a conference. The user application receives a * PKX_EVENT_CONFERENCE_MEMBER_REMOVED for each member removed from the * conference. * * Parameters: * confhandle: * The handle to the conference retrieved through the * PKX_CONF_Create function. * * Return Values: * PKX_ERROR_OBJECT_INVALID_HANDLE: * The confhandle parameter does not refer to a valid * conference * PK_SUCCESS: * The function succeeded. * */ PK_STATUS PK_API PKX_CONF_RemoveAllMembers ( IN TPikaHandle confhandle, ); gp_conf.cpp - Implement the new function. This function calls the removeallmembers method of the conference object. //

141 8.3 Modifying the High Level API Source Code PK_STATUS PK_API PKX_CONF_RemoveAllMembers ( IN TPikaHandle confhandle, ) { PK_STATUS status = PK_SUCCESS; CLogging::Instance()->logApi(PKX_LOG_TYPE_IN_API, PKX_LOG_API_CALL, "PKX_CONF_RemoveAllMembers(IN confhandle %lu)", confhandle); CConference *conf; CHECK_DEVICE(CConference, confhandle, conf); if ((status = conf->removeallmembers())!= PK_SUCCESS) ISSUE_RESULT(status); ISSUE_RESULT(PK_SUCCESS); } cconference.h - Define the new methods that are required. class CConfewrence() {... public:... PK_STATUS removeallmembers(); PK_STATUS deleteallmembers();... } //CConference cconference.cpp - Implement the methods in the conference object to provide the new functionality. // PK_STATUS CConference::removeAllMembers() { if (getobjectstate()!= PKX_OBJECT_STATE_RUNNING) return PKX_ERROR_SYSTEM_IS_NOT_RUNNING; return deleteallmembers(channel); 8 } // PK_STATUS CConference::deleteAllMembers() { // Retrieve product interface object CProductInterface *productinterface = CProductMgr::Instance()->get(m_ProductId); if (productinterface == NULL) return PKX_ERROR_CONFIG_PRODUCT_NOT_LOADED; 13

142 8.3 Modifying the High Level API Source Code return productinterface->conferenceremoveallmembers(gethandle()); } common/gpmsgs.h - Define a new event id used to send the new functionality from the main thread to the low level API thread. #define INTERNAL_CONFERENCE_COMMAND_REMOVE_ALL_MEMBERS_EVENT PKX_PRODUCT_EVENT_MAKE_CODE(0x007) libpikagpgwy/cgatewayinterface.h - Define the new method required in the interface to the low level API library virtual PK_STATUS conferenceremoveallmembers(tpikahandle conferencereference); libpikagpgwy/cgatewayinterface.cpp - Implement the new method required in the interface to the low level API product library. This method sends a new type of event (INTERNAL_CONFERENCE_COMMAND_REMOVE_ALL_MEMBERS_EVENT) to the low level API thread. PK_STATUS CGatewayInterface::conferenceRemoveAllMembers(TPikaHandle conferencereference) { PKX_TPikaEvent event; ::memset(&event, 0, sizeof(pkx_tpikaevent)); event.id = INTERNAL_CONFERENCE_COMMAND_REMOVE_ALL_MEMBERS_EVENT; event.handle = PK_HANDLE_NONE; event.userdata = (PK_VOID *)PK_HANDLE_NONE; event.p0 = (PK_UINTPTR)conferenceReference; event.p1 = 0; event.p2 = 0; return CGatewaySystem::Instance()->injectEvent(&event); } libpikagpgwy/cgatewaysystem.cpp - Add the case for handling the new event type to the low level API thread event processing function. 8 case PKX_CONFERENCE_CHANGE_MEMBER_EVENT: case PKX_CONFERENCE_REMOVE_MEMBER_EVENT: case PKX_CONFERENCE_REMOVE_ALL_MEMBERS_EVENT: case PKX_CONFERENCE_ADD_MEMBER_EVENT: { // Get conference if ((conference = getconference((tpikahandle)event->p0))!= NULL) { conference->onevent(event); } else log(pkx_log_type_normal, PKX_LOG_ALL_ERROR, "CGatewaySystem::onEvent() - Invalid conference reference received: %d (p0 0x%08x, p1 0x%08x, p2 0x%08x)", event->id, event->p0, event->p1, event->p2); break; } libpikagpgwy/cgatewaysystem.cpp - Eliminate each active member in the conference. Eliminating a member causes 136

143 8.3 Modifying the High Level API Source Code Building the High Level API Libraries in a PKX_EVENT_CONF_MEMBER_REMOVED to be sent to the user application. Add the following case immediately after the PKX_CONF_REMOVE_MEMBER_EVENT case in the CConference::onEvent method: case PKX_CONFERENCE_REMOVE_ALL_MEMBERS_EVENT: { CConferenceMember *member = NULL; while ((member = (CConferenceMember *)m_activemembers.pop())!= NULL) { if ((status = eliminatemember(member))!= PK_SUCCESS) { log(pkx_log_type_normal, PKX_LOG_ALL_WARNING, "CConference::close() - Failed to destroy member of conference: %lu", m_externalref); } } break; Building the High Level API Libraries in Windows The GP Windows installation contains pre-compiled binaries. These libraries need to be rebuilt if you modify the code. The GP source code will be overwritten during new GP installations, therefore, the source code has been marked as read-only to remind you that the files should be copied to a new source directory before building. You can build GP for both 32-bit and 64-bit Windows operating systems from the solution file included with the GP source. To build and distribute the files: 1. Log on using an administrator account Change directories to the new source directory. 3. Load the GP project using the corresponding project file grandprix.sln. 4. Compiling the GP source requires installation of the Microsoft Platform SDK (PSDK). Download and run the appropriate Microsoft Platform SDK installation package from the Microsoft Web site. Testing has been performed using the following PSDK versions: 137

144 Building the High Level API Libraries in 8.3 Modifying the High Level API Source Code Win2003 Platform SDK R2 for Windows XP and Windows Server bit Windows 7 Platform SDK Version 7.1 for Windows 7 32-bit, Windows 7 64-bit and Windows Server bit No specific PSDK was tested for Visual Studio.NET. Visual Studio must be updated to specify an additional include file and library: Visual Studio 200: On the Tools menu, click Options Expand Projects and Solutions and click VC++ Directories In the Show Directories for menu, click Include Files Ensure that the PDSK directory for the Include files is added before the Visual Studio directories In the Show Directories for menu, click Library Files Ensure that the PDSK directory for the Lib files is added at before the Visual Studio directories 6. In Visual Studio, under the Build menu, click Batch Build. Select the appropriate projects to build. Click Rebuild Note: The low-level API libraries must be installed prior to building GP. 7. To complete the installation of the newly built GP, files must be copied from the release or debug folders under the new source directory (see item 2 above). The following shows the folder structure after GP has been built. The highlighted items show the location of the release and debug folders. There are separate folders for 32-bit binaries and 64-bit binaries. Ensure that you install the correct versions, based on the operating system running on your computer

145 8.3 Modifying the High Level API Source Code Building the High Level API Libraries in Linux 8. Perform the following steps: Copy the.dll files from newsourcedirectory\release to C:\Windows\system32 Copy the pikagpapi.lib file from newsourcedirectory\release to hmpinstalldirectory\lib Copy gptest.exe and gpconfig.exe from newsourcedirectory\release to hmpinstalldirectory\bin Copy any changed header files from newsourcedirectory\include to hmpinstalldirectory\inc To use the debug versions of the.dll, lib and.exe files, copy the files from the debug directory instead of the release directory Building the High Level API Libraries in Linux The Linux installer builds the high level API libraries during installation. These libraries need to be rebuilt if you modify 8 the code. The GP source includes the makefiles required to build the libraries and programs. The GP source code is overwritten during new GP installations. As such, the source code has been marked as read-only to remind the user that the files should be copied to a new location before building. To build and distribute the files: 1. Login using the root account. 2. Ensure that the appropriate gcc, glibc, and make utilities are installed. The package names to install depend on the Linux distribution running on your computer. 139

146 8.4 Bypassing the High Level API to Make 3. Ensure that the correct low level API libraries and include files are installed for the operating system running on your computer. There are 32-bit and 64-bit versions available. 4. Change to the new source directory.. At the Linux command prompt, type make all to build the libraries. The makefile rules check for the existence of the pikahmpapi.h file in the /usr/include directory to determine if the low level API libraries are present. The following GP libraries are built, where version is the GP release version: libpikagpapi.a and libpikagpapi.so.version libpikagpgwy/libpikagpgwy.a and libpikagpgwy/libpikagpgwy.so.version 7. At the Linux command prompt, type make install to install the libraries and include files: The libraries created are copied to /usr/lib (32-bit OS) or /usr/lib64 (64-bit OS) and the following symbolic links are created, where version is the GP release version. libpikagpapi.so->libpikagpapi.so.version libpikagpgwy.so->libpikagpgwy.so.version The include files pikagpapi.h and pk_basetypes.h are copied into the /usr/include/pika directory. The programs gptest and gpconfig are copied into the /usr/bin directory. 8.4 Bypassing the High Level API to Make Low-level Function Calls Some features of the low level API are not available through GP. To allow GP-based user applications to access low level API features, GP provides bypass functions to access low-level channel and conference resources. The user application uses GP for call control (initiating and receiving calls) and bypass for media processing during the call. 8 For trunk resources, the disconnect parameter in the product configuration file controls whether tones are enabled for disconnect supervision. If a tone is detected during the call with bypass enabled, the application must validate the tone to verify that it is a call progress tone (dial tone, busy, or reorder tone), disable bypass mode and return call control to GP. GP will terminate the call if it is a call progress tone. The following types of bypass functions are provided: 140

147 8.4 Bypassing the High Level API to Make Bypass Function Description PKX_CHANNEL_EnableBypass Informs the high-level API that the user application will be performing low-level functions on the channel resources. PKX_CHANNEL_GetBypassInfo Retrieves the low-level switching and resource handle information for the specified channel in a PKX_TChannelBypassInfo structure. AoH information retrieved: inputmediastreamhandle - Input media stream handle. outputmediastreamhandle - Output media stream handle. PKX_CHANNEL_DisableBypass Informs the high-level API that the user application has finished performing low-level functions on the channel resources. PKX_CONF_EnableBypass Informs the high-level API that the user application will be performing low-level functions on the conference resources. PKX_CONF_GetBypassInfo Retrieves the low-level resource handle information for the specified conference in a PKX_TConfBypassInfo structure. AoH information retrieved: confhandle - Conference group handle. PKX_CONF_DisableBypass Informs the high-level API that the user application has finished performing low-level functions on the conference resources. The following restrictions apply to high level and low level function calls, with respect to the bypass enable and disable function calls: GP user applications can get the low level resource information at any time. GP user applications must only use these resource handles between enable bypass and disable bypass function calls. GP user applications must not use the bypassed channel or conference in any PKX_CHANNEL_xxx or PKX_CONF_xxx function call between enable bypass and disable bypass function calls. 8 The xxx_getbypassinfo functions returns a structure (either PKX_TChannelBypassInfo or PKX_TConfBypassInfo) that contains: a field of type PKX_TProductLibrary. The following value is returned in this field: PKX_PRODUCT_LIBRARY_AOH - low level product library low level resource information The following diagram shows where the bypass and lower-level function calls may be used: 141

148 8.4 Bypassing the High Level API to Make 8 142