mspConnect

Connects a media channel to two endpoints.

Prototype

DWORD mspConnect ( MSPHD ephd1, MSPHD chnhd, MSPHD ephd2 )

Argument	Description
ephd1	First MSPP endpoint handle.
chnhd	MSPP channel handle.
ephd2	Second MSPP endpoint handle.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	Function argument includes an invalid value or a required pointer argument is NULL.
CTAERR_INVALID_CTAHD	Handle is invalid.
CTAERR_INVALID_HANDLE	Invalid handle was passed as an argument to this function.
MSPERR_INTERNAL_HANDLE	Specified MSPP endpoint or channel is not valid.
MSPERR_INVALID_CONNECTION	The specified MSPP connection cannot be found.
MSPERR_INVALID_HANDLE	Specified MSPP endpoint or channel is not valid.

Events

Event

Description

MSPEVN_CONNECT_DONE

Generated when the MSPP service connects a media channel to two endpoints in response to an mspConnect call. MSPEVN_CONNECT_DONE events return the chnhd of the connected channel, but not the ephds associated with the connected endpoints.

The event.value field can contain the following:

CTA_REASON_FINISHED

MSPRSN_FAILED_TO_ALLOCATE

The MSPP service is unable to allocate on-board resources.

MSPRSN_FAILED_TO_INTRACONNECT

The MSPP service is unable to connect filters within the channel.

MSPRSN_FAILED_TO_INTERCONNECT

The MSPP service is unable to connect the channel to an endpoint.

The event.objHd indicates the chnhd of the associated channel.

Details

When invoking mspConnect, specify two endpoint handles and a channel handle. These handles specify the endpoints through which the data flows, and the processes that will take place (for example, encoding and decoding) as the transferred data flows through a channel. The order of the endpoints in the argument list must correspond to the channel type.

The following restrictions apply when applications use mspConnect to connect pairs of MSPP endpoints to MSPP channels:

Connection type	Channel	Endpoints
Voice	Voice	ephd1: RTP (IPv4 or IPv6) ephd2: DS0
RTP switching	Switch	ephd1: RTP FDX or RTP receive (IPv4 or IPv6) ephd2: RTP FDX or RTP send (IPv4 or IPv6, but must match ephd1)
T.38 fax	Voice	ephd1: T38UDP ephd2: DS0
ThroughPacket	Fax relay	ephd1: TPKT ephd2: DS0

MSPEVN_CONNECT_DONE returns the chnhd of the channel associated with the connection, but does not return the ephds associated with the connected endpoints. For more information, refer to Connecting MSPP endpoints with channels.

Example

DWORD ret;
CTAHD                   hCtaHd[MAX_CONNECTIONS];
CTAQUEUEHD              hCtaQueue;
CTA_EVENT               Event;
MSPHD hEp1, hEp2, hChan;
ret = mspConnect(hEp1, hChan, hEp2);
if (ret != SUCCESS)
    return FAILURE;
ctaWaitEvent( hCtaQueHd, &Event, CTA_WAIT_FOREVER );
if ( Event.id    != MSPEVN_CONNECT_DONE ||
     Event.value != CTA_REASON_FINISHED )
    return FAILURE;