See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function sets up a conference call for the addition of the third party.
Syntax
LONG TSPIAPI TSPI_lineSetupConference( DRV_REQUESTID dwRequestID, HDRVCALL hdCall, HDRVLINE hdLine, HTAPICALL htConfCall, LPHDRVCALL lphdConfCall, HTAPICALL htConsultCall, LPHDRVCALL lphdConsultCall, DWORD dwNumParties, LPLINECALLPARAMS const lpCallParams ); |
Parameters
- dwRequestID
-
Identifier of the asynchronous request.
- hdCall
-
Handle to the initial call that identifies the first party of a conference call. In some environments, a call must exist in order to start a conference call. In other telephony environments, no call initially exists and hdCallis left NULL. The call state of hdCall can be connected.
- hdLine
-
Handle to the line device on which to originate the conference call if hdCallis NULL. The hdLineparameter is ignored if hdCallis non-NULL. The service provider reports which model it supports through the setupConfNull flag of the LINEADDRESSCAPSdata structure.
- htConfCall
-
TAPI handle to the new conference call. The service provider must save this and use it in all subsequent calls to the LINEEVENTprocedure reporting events on the new call.
- lphdConfCall
-
Pointer to a HDRVCALLrepresenting the service provider's identifier for the newly created conference call. The service provider must fill this location with its handle for the new call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConfCallis not applicable.
- htConsultCall
-
TAPI handle to the consultation call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must save the htConsultCalland use it in all subsequent calls to the LINEEVENTprocedure reporting events on the new consultation call.
- lphdConsultCall
-
Pointer to a HDRVCALLrepresenting the service provider's identifier for a call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCallis not applicable.
- dwNumParties
-
Expected number of parties in the conference call. The service provider is free to do with this number as it pleases. For example, the service provider can ignore it, or use it as a hint to allocate the right size conference bridge inside the switch. TAPI does not validate this parameter when this function is called.
- lpCallParams
-
Pointer to call parameters to be used when establishing the consultation call. This parameter is set to NULL if no special call setup parameters are desired and the service provider uses default parameters.
Return Value
Returns dwRequestID, or an error number if an error occurs. The lResultactual parameter of the corresponding ASYNC_COMPLETIONis zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this method.
| Value | Description |
|---|---|
|
LINEERR_INVALCALLHANDLE |
The handle to the call is invalid. |
|
LINEERR_INVALADDRESSMODE |
The address mode is invalid. |
|
LINEERR_INVALLINEHANDLE |
The handle to the line is invalid. |
|
LINEERR_INVALBEARERMODE |
The bearer mode is invalid. |
|
LINEERR_INVALCALLSTATE |
The call state is invalid. |
|
LINEERR_INVALCALLPARAMS |
The call parameters are invalid. |
|
LINEERR_CALLUNAVAIL |
The call is unavailable. |
|
LINEERR_INVALLINESTATE |
The line state is invalid. |
|
LINEERR_CONFERENCEFULL |
The conference call is full. |
|
LINEERR_INVALMEDIAMODE |
The media mode is invalid. |
|
LINEERR_NOMEM |
Not enough memory is available. |
|
LINEERR_INVALRATE |
The rate is invalid. |
|
LINEERR_OPERATIONUNAVAIL |
The operation is unavailable. |
|
LINEERR_INUSE |
The line is in use. |
|
LINEERR_OPERATIONFAILED |
The operation failed. |
|
LINEERR_RATEUNAVAIL |
The rate is unavailable. |
|
LINEERR_RESOURCEUNAVAIL |
The resource is unavailable. |
|
LINEERR_USERUSERINFOTOOBIG |
The user user information is too big. |
|
LINEERR_BEARERMODEUNAVAIL |
The bearer mode is unavailable. |
Remarks
The service provider returns LINEERR_INVALLINEHANDLE if the specified line handle for the line containing the conference call is invalid. This error can also indicate that the telephony environment requires an initial line to set up a conference but a non-NULL call handle was supplied instead.
The service provider returns LINEERR_INVALCALLHANDLE if the telephony environment requires an initial call to set up a conference but a NULL call handle was supplied instead.
TSPI_lineSetupConferenceprovides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hdCallparameter is a valid call handle that is initially added to the conference call by the TSPI_ lineSetupConferencerequest and hdLineis ignored. On switches where conference call setup does not start with an existing call, hdCallmust be NULL and hdLinemust be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. TAPI can use the TSPI_lineDialfunction to dial the address of the other party.
The conference call typically transitions into the onHoldPendingConference state, the consultation call dial tone state and the initial call (if one) into the conferenced state.
A conference call can also be set up using a TSPI_lineCompleteTransferfunction that is resolved into a three-way conference.
TAPI may be able to toggle between the consultation call and the conference call using the TSPI_lineSwapHoldfunction.
The TSPI_lineUnholdfunction can recover calls that have the call state onHoldPendingConference. If this is done, any consultation call typically goes to the idle state.
A consultation call can be canceled by invoking the TSPI_lineDropfunction on it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. TAPI and its client applications should observe the LINE_CALLSTATEmessages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call becomes idle and the original participant call may revert to connected.
This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETIONfunction reports success. In other words, it must not issue any LINEEVENTmessages for the new call or include it in call counts in messages or status data structures for the line.
Requirements
| Header | tapicomn.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |