lineAddToConference
The lineAddToConference
function adds the call specified by hConsultCall to the conference call
specified by hConfCall.
LONG lineAddToConference(
|
HCALL hConfCall, |
|
|
HCALL hConsultCall |
|
|
); |
|
Parameters
hConfCall
A 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 hConfCall must
be onHoldPendingConference or onHold.
hConsultCall
A 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 hConsultCall may not necessarily have been established using lineSetupConference or linePrepareAddToConference. The call state of hConsultCall
must be connected, onHold, proceeding, or ringback.
Many PBXs allow calls to be added to conferences before they are actually
answered.
Return Values
Returns a
positive request ID if the function will be completed asynchronously, or a
negative error number if an error has occurred. The dwParam2 parameter
of the corresponding LINE_REPLY
message is zero if the function is successful, or it is a negative error number
if an error has occurred. Possible return values are:
LINEERR_CONFERENCEFULL,
LINEERR_NOTOWNER, LINEERR_INVALCONFCALLHANDLE, LINEERR_OPERATIONUNAVAIL,
LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE,
LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.
Remarks
If
LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added
call is invalid, hConsultCall is a parent of another conference or
already a participant in a conference, hConsultCall cannot be added for
other reasons (such as, it must have been established using lineSetupConference or linePrepareAddToConference), or hConsultCall
and hConfCall are 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 lineGetConfRelatedCalls, 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.
Note that if lineGetConfRelatedCalls
is called immediately after lineAddToConference, it may not return a
complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message 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). Once the application has received the LINE_CALLSTATE
message, lineGetConfRelatedCalls returns complete information. Note that
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 may
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 lineSetupConference or lineCompleteTransfer.
The call added to a conference is typically established using lineSetupConference
or linePrepareAddToConference. Some switches may allow adding arbitrary
calls to the conference, and such a call may have been set up using lineMakeCall
and be on (hard) hold. The application may examine the dwAddrCapFlags
field of the LINEADDRESSCAPS structure to determine the permitted
operations.
See Also