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.
A version of this page is also available for
4/8/2010

This function sets up a conference call for the addition of the third party.

Note:
This function is for TAPI version 2.0 and later.

Syntax 

LONG WINAPI lineSetupConference(
  HCALL 
hCall,
  HLINE 
hLine,
  LPHCALL 
lphConfCall,
  LPHCALL 
lphConsultCall,
  DWORD 
dwNumParties,
  LPLINECALLPARAMS const 
lpCallParams 
);

Parameters

hCall

Initial call that identifies the first party of a conference call. In some environments (as described in device capabilities), a call must exist to start a conference call, and the application must be an owner of this call. In other telephony environments, no call initially exists, hCallmust be left NULL, and hLinemust be specified to identify the line on which the conference call is to be initiated. The call state of hCallmust be connected.

hLine

Handle to the line. This handle is used to identify the line device on which to originate the conference call if hCallis NULL. The hLineparameter is ignored if hCallis non-NULL.

lphConfCall

Pointer to an HCALL handle. This location is then loaded with a handle identifying the newly created conference call. The application is the initial sole owner of this call. The call state of hConfCallis not applicable.

lphConsultCall

Pointer to an HCALL handle. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. Initially, the application is the sole owner for this call.

dwNumParties

Expected number of parties in the conference call. This number is passed to the service provider. The service provider is free to do as it pleases with this number: ignore it, use it as a hint to allocate the right size conference bridge inside the switch, and so on.

lpCallParams

Pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Value

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2parameter of the corresponding LINE_REPLYmessage is zero if the function succeeds or it is a negative error number if an error occurs. The following table shows the return values for this function.

Value Description

LINEERR_BEARERMODEUNAVAIL

The bearer mode is unavailable.

LINEERR_UNINITIALIZED

A parameter is uninitialized.

LINEERR_CALLUNAVAIL

The call is unavailable.

LINEERR_INVALMEDIAMODE

The media mode is invalid.

LINEERR_CONFERENCEFULL

The conference call is full.

LINEERR_INVALPOINTER

The pointer is invalid.

LINEERR_INUSE

The line is in use.

LINEERR_INVALRATE

The rate is invalid.

LINEERR_INVALADDRESSMODE

The address mode is invalid.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALBEARERMODE

The bearer mode is invalid.

LINEERR_NOTOWNER

The application is not an owner of this call.

LINEERR_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALCALLSTATE

The call state of hCallis something other than connected.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALCALLPARAMS

The call parameters are unavailable.

LINEERR_RATEUNAVAIL

The rate is unavailable.

LINEERR_INVALLINEHANDLE

The handle to the open line device is invalid.

LINEERR_RESOURCEUNAVAIL

The resources are unavailable.

LINEERR_INVALLINESTATE

The line state is invalid.

LINEERR_STRUCTURETOOSMALL

The structure is too small.

LINEERR_USERUSERINFOTOOBIG

The user-user information is too big.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeaturesmember (of the type LINEFEATURE) in the LINEDEVSTATUSstructure. (Calling lineGetLineDevStatusupdates the information in LINEDEVSTATUS.) If LINEERR_INVALMEDIAMODE is returned, check for supported media types on the line in the dwMediaModesmember in the LINEDEVCAPSstructure.

The lineSetupConferencefunction provides 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 hCallparameter is a valid call handle that is initially added to the conference call by the lineSetupConferencerequest; hLineis ignored. On switches where conference call setup does not start with an existing call, hCallmust be NULL and hLinemust 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. The application can then use the lineDialfunction to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call into the dial tone state, and the initial call (if there is one) into the conferenced state.

A conference call can also be set up by a lineCompleteTransferthat is resolved into a three-way conference. The application may be able to toggle between the consultation call and the conference call using the lineSwapHoldfunction.

A consultation call can be canceled by invoking lineDropon it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. The application 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 can revert to connected.

If an application specifies the handle of the original call ( hCall) in a call to the lineUnholdfunction, both the conference call and the consultation call typically go to idle.

Note:
This function is for TAPI version 2.0 and later.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also