CA_TDM_Connect()

Purpose

Makes a connection between two port sets via the TDM bus.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

C Syntax

#include “CA_header.h”
int CA_TDM_Connect (
     const TDM_CONNECT_ST *connect_parm_sp
     unsigned int *connection_id_p
);

Description

This subroutine establishes a connection between the two port sets named in the TDM_CONNECT_ST pointed to by the connection_parm_sp parameter. The port sets must have complementary sources and sinks. Port connections are made in the same order as the sources and sinks specified in the configuration file. For information about TDM connection management, ports, and port sets, see the Blueworx Voice Response for AIX: Designing and Managing State Table Applications information.

When the connection is established successfully, a connection_id is returned to the calling subroutine. This connection_id is used to identify the connection when CA_TDM_Disconnect() is called to break the connection.

The calling subroutine chooses a token which is associated with the connection. This provides a simple security mechanism to ensure that connections cannot be broken by unauthorized processes. The same token must be presented on calling a subsequent routine either to break the connection, or to override it by making a new connection which implicitly breaks this connection.

When writing a custom server that uses TDM subroutines, choose a single token and use it for all calls from that custom server to the TDM subroutines. Multi-process custom servers should share the same token throughout all processes. You can choose any unsigned integer as a token. For example, you can use a date, or a value hashed from the custom server name. Of course, this does not guarantee unique tokens, and it would not prevent a deliberate attempt to misuse a token, but it should prevent accidental token clashes.

The calling routine must also supply two link_id parameters. If a port_set to be connected is a DTNA channel, the corresponding link_id parameters should be set to the ID of the channel process which is running an application on that channel. If a port set is a resource card such as speech recognition, text-to-speech, or fax, set the corresponding link_id parameter to (-1). This parameter associates a TDM connection with a call-in-progress. The call identified by a link_id parameter is considered to own the TDM connection. The connection is broken automatically when the call ends. When two telephony channels are connected, as in the case of matrix switching, two link_id parameters are needed, relating to the calls in progress on each of the telephony channels. The connection is broken automatically when either call ends.

Parameters

connect_parm_sp
A pointer to a TDM_CONNECT_ST input structure that is filled in as described in TDM_CONNECT_ST.
connection_id_p
A pointer to an unsigned integer into which the connection_id will be written.

Return codes

0
Successful
-1
Unsuccessful (CA_errno is set to an error code that indicates the error)

Error names

CA_ADAPTER_ERROR
An error was reported by a TDM adapter or adapter-specific software.
CA_ALREADY_CONNECTED
The port sets specified are already connected to one another.
CA_HANGUP
The call owning this connection has ended.
CA_INCOMPATIBLE_PORT_SET
Port sets are not complementary and could not be connected.
CA_INV_TOKEN
One or both port sets are already involved in an established connection which was not broken, because the token supplied did not match the one used when the connection was made.
CA_INV_ADDR
One of the parameters is an invalid pointer.
CA_INV_PORT_SET
The specified port set name or names are not valid.
CA_NOT_INIT
CA_Init() has not been called.
CA_TERMINATING
The custom server is terminating.
CA_TSLOT_NOT_READY
TDM connection management processes are not running or reported an error.

Related information

CA_TDM_Disconnect().