# Managing PPX connections

The fundamental element in the Point-to-Point Switching service is a connection object. A connection is basically a telephone call. Each connection can have one talker. The talker in the connection is driving the output for that connection. Each connection can have one or more listeners. The listeners receive input from the connection.

Use the PPX service to perform the following operations:

- Create a connection

- Set the talker for a connection

- Add listeners to a connection

- Remove listeners from a connection

- Set the silence pattern for a connection

- Open a connection

- Close a connection

- Destroy a named connection

## Creating a connection

Create a connection by calling ppxCreateConnection with a context. A handle (ppxhd) to the connection is returned. The connection handle is used to specify the connection when setting a talker or adding listeners to the connection. When a connection is initially created, there are no telephony bus timeslots associated with it.

A default idle bit pattern (a fixed 8-bit pattern) can be specified in the call to ppxCreateConnection. If there is no talker attached, any listeners added to the connection receive the default pattern sent on the stream attached to the listener.

In the following topics, an example application is used to demonstrate the PPX functions. The example application runs a system in which incoming callers are placed on hold while waiting for an available operator. All callers that are on hold listen to the same voice message.

The following illustration shows the creation of the connection, hold_message_block. A default pattern is set and a pointer to the connection is returned.

When creating a connection, you can assign a name to the connection. A named connection can be accessed by other applications or contexts (as discussed in Opening a connection), allowing the ownership property to be over-ridden.

## Setting the talker for a connection

ppxSetTalker sets a talker for a connection. Specify the address of the talker by the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot.

If listeners are already attached to the connection, the PPX service connects the listeners to the talker using underlying switch connections. The switch connections can involve the allocation of bus timeslots if the talkers and the listeners are on different boards. If there is a talker already attached to the connection, the original talker is automatically disconnected before the new talker is connected.

In the following illustration, the talker is added to the hold_message_block. The talker is a DSP resource playing the on-hold message.

## Adding listeners to a connection

ppxAddListeners adds listeners to a connection. Specify the listeners by an array containing the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot for each listener.

If the connection already has a talker attached, the listeners are connected to the talker using switch connections. The switch connections can involve the allocation of bus timeslots if the talker and the listener are on different boards. If there is no talker attached to the connection, the listeners have the default pattern of the connection sent to them.

In the following illustration, as incoming calls are received, they are connected to the hold_message_block to receive the on-hold message while waiting for an available operator.

## Removing listeners from a connection

ppxRemoveListeners removes listeners from a connection. Specify the listeners by an array containing the switch identification number, bus type (CTBUS or LOCAL), stream, and timeslot for each listener.

If the listeners are connected to a talker, the switch connections are broken. The listeners are put into their default disabled hardware state. For telephony bus output streams, the default hardware state is a high impedance state. Local bus output streams are put into the vendor-specified default state.

As shown in the following illustration, as an operator becomes available, listeners are removed from the hold_message_block so they can be connected to an operator.

## Setting the silence pattern for a connection

ppxSetDefaultPattern sets the default pattern for a connection. If there is no talker attached to a connection, the listeners receive the default pattern. If listeners are connected to a talker and the talker is removed, the listeners receive the default pattern for the connection.

This function overrides the default pattern set when ppxCreateConnection is called to create the connection. The default silence pattern used by the server is 0x7f (mu-law). This default value can be modified by setting a switch fabric attribute within the PPX configuration file, as described in the Switch configuration overview.

## Opening a connection

ppxOpenConnection returns a handle to a named connection.

Typically in Natural Access, each application runs as a separate thread or process. If a connection is assigned a name when it is created, each application can open a handle to that connection and add a talker, add listeners, or remove listeners. Any action taken in one application is reflected in the connection and is apparent in every application that accesses that connection.

Note: The PPX service considers a PPX client to be equivalent to a Natural Access context.

In the previous illustration, the hold_message_block was created with the name hold_msg. In the system, one application is managing incoming calls and transferring them to operators when they are available. Another application is used to manage the operator stations. If an operator needs to place the caller back on-hold, the application can open the connection named hold_msg. The connection handle hold_message_block is returned and the application can then add the caller as a listener to that connection.

## Closing a connection

ppxCloseConnection closes a previously created connection. If the connection is unnamed (refer to Creating a connection for information about naming connections), the resources associated with the connection are freed and all connection outputs become disabled. A named connection is closed by ppxDestroyNamedConnection.

## Destroying a named connection

ppxDestroyNamedConnection frees all resources and disables outputs to all points on a named connection. Even if all applications close a named connection with ppxCloseConnection, the connection remains in the PPX connection database until it is explicitly destroyed with ppxDestroyNamedConnection.

Once destroyed, all open handles to the named connection become invalid in all applications.