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 adds the call specified by the hConsultCallparameter to the conference call specified by the hConfCallparameter.

Syntax 

LONG WINAPI lineAddToConference(
  HCALL 
hConfCall,
  HCALL 
hConsultCall 
);

Parameters

hConfCall

Handle to the conference call. The application must be an owner of this call. Any monitoring (media, tones, digits) on a conference call applies only to the hConfCall, not to the individual participating calls. Call state of hConfCallmust be onHoldPendingConference or onHold.

hConsultCall

Handle to the call to be added to the conference call. The application must be an owner of this call. This call cannot be a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hConsultCallmay not necessarily have been established using the lineSetupConferenceor linePrepareAddToConferencefunctions. The call state of hConsultCallmust be connected, onHold, proceeding, or ringback. Many PBXs allow calls to be added to conferences before they are actually answered.

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_CONFERENCEFULL

The line cannot be added to the conference because the conference is full.

LINEERR_NOTOWNER

The application is not the owner of the call.

LINEERR_INVALCONFCALLHANDLE

The conference call handle is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALCALLHANDLE

The specified call handle for the added call is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALCALLSTATE

The call state is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_UNINITIALIZED

The parameter is uninitialized.

Remarks

If LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added call is invalid; hConsultCallis a parent of another conference or already a participant in a conference; hConsultCallcannot be added for other reasons (such as, it must have been established using lineSetupConferenceor linePrepareAddToConference); or hConsultCalland hConfCallare calls on different open lines.

The call handle of the added party remains valid after adding the call to a conference. Its state typically changes to conferenced while the state of the conference call typically becomes connected. Using the lineGetConfRelatedCallsfunction, you can obtain a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls. The handle to an individual participating call can be used later to remove that party from the conference call using lineRemoveFromConference.

If lineGetConfRelatedCallsis called immediately after lineAddToConference, it may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATEmessage indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCallsreturns complete information.

Note:
All calls that are part of a conference must exist on the same open line.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls can automatically become idle. An application should consult the line's device capabilities to determine what form of conference removal is available. The application should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either by lineSetupConferenceor the lineCompleteTransferfunction. The call added to a conference is typically established using lineSetupConferenceor linePrepareAddToConference. Some switches can allow adding arbitrary calls to the conference, and such a call can have been set up using the lineMakeCallfunction and be on (hard) hold. The application can examine the dwAddrCapFlagsmember of the LINEADDRESSCAPSstructure to determine the permitted operations.

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