mirror of https://github.com/tongzx/nt5src
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
519 lines
21 KiB
519 lines
21 KiB
/*++
|
|
|
|
Copyright (c) 1997 Microsoft Corporation
|
|
|
|
Module Name:
|
|
|
|
confcall.c
|
|
|
|
Abstract:
|
|
|
|
TAPI Service Provider functions related to conference calls.
|
|
|
|
TSPI_lineAddToConference
|
|
TSPI_lineCompleteTransfer
|
|
TSPI_linePrepareAddToConference
|
|
TSPI_lineRemoveFromConference
|
|
TSPI_lineSetupConference
|
|
|
|
Environment:
|
|
|
|
User Mode - Win32
|
|
|
|
--*/
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
// //
|
|
// Include files //
|
|
// //
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
|
|
#include "globals.h"
|
|
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
// //
|
|
// TSPI procedures //
|
|
// //
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
|
|
LONG
|
|
TSPIAPI
|
|
TSPI_lineAddToConference(
|
|
DRV_REQUESTID dwRequestID,
|
|
HDRVCALL hdConfCall,
|
|
HDRVCALL hdConsultCall
|
|
)
|
|
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
This function adds the call specified by hdConsultCall to the conference
|
|
call specified by hdConfCall.
|
|
|
|
Note that the call handle of the added party remains valid after adding
|
|
the call to a conference; its state will typically change to conferenced
|
|
while the state of the conference call will typically become connected.
|
|
The handle to an individual participating call can be used later to remove
|
|
that party from the conference call using TSPI_lineRemoveFromConference.
|
|
|
|
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. The TAPI DLL may consult
|
|
the line's device capabilities to determine what form of conference removal
|
|
is available. The TAPI DLL or its client applications should track the
|
|
LINE_CALLSTATE messages to determine what really happened to the calls
|
|
involved.
|
|
|
|
The conference call is established either via TSPI_lineSetupConference or
|
|
TSPI_lineCompleteTransfer. The call added to a conference will typically be
|
|
established using TSPI_lineSetupConference or
|
|
TSPI_linePrepareAddToConference. Some switches may allow adding of an
|
|
arbitrary calls to conference, and such a call may have been set up using
|
|
TSPI_lineMakeCall and be on (hard) hold.
|
|
|
|
Arguments:
|
|
|
|
dwRequestID - Specifies the identifier of the asynchronous request.
|
|
The Service Provider returns this value if the function completes
|
|
asynchronously.
|
|
|
|
hdConfCall - Specifies the Service Provider's opaque handle to the
|
|
conference call. Valid call states: onHoldPendingConference, onHold.
|
|
|
|
hdAddCall - Specifies the Service Provider's opaque handle to the call to
|
|
be added to the conference call. Valid call states: connected, onHold.
|
|
|
|
Return Values:
|
|
|
|
Returns zero if the function is successful, the (positive) dwRequestID
|
|
value if the function will be completed asynchronously, or a negative error
|
|
number if an error has occurred. Possible error returns are:
|
|
|
|
LINEERR_INVALCONFCALLHANDLE - The specified call handle for the
|
|
conference call is invalid or is not a handle for a conference
|
|
call.
|
|
|
|
LINEERR_INVALCALLHANDLE - The specified call handle for the added
|
|
call is invalid.
|
|
|
|
LINEERR_INVALCALLSTATE - One or both of the specified calls are not
|
|
in a valid state for the requested operation.
|
|
|
|
LINEERR_CONFERENCEFULL - The maximum number of parties for a
|
|
conference has been reached.
|
|
|
|
LINEERR_OPERATIONUNAVAIL - The specified operation is not available.
|
|
|
|
LINEERR_OPERATIONFAILED - The specified operation failed for
|
|
unspecified reason.
|
|
|
|
--*/
|
|
|
|
{
|
|
return LINEERR_OPERATIONUNAVAIL; // CODEWORK...
|
|
}
|
|
|
|
|
|
LONG
|
|
TSPIAPI
|
|
TSPI_lineCompleteTransfer(
|
|
DRV_REQUESTID dwRequestID,
|
|
HDRVCALL hdCall,
|
|
HDRVCALL hdConsultCall,
|
|
HTAPICALL htConfCall,
|
|
LPHDRVCALL lphdConfCall,
|
|
DWORD dwTransferMode
|
|
)
|
|
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
This function completes the transfer of the specified call to the party
|
|
connected in the consultation call.
|
|
|
|
This operation completes the transfer of the original call, hdCall, to
|
|
the party currently connected via hdConsultCall. The consultation call
|
|
will typically have been dialed on the consultation call allocated as
|
|
part of TSPI_lineSetupTransfer, but it may be any call to which the
|
|
switch is capable of transferring hdCall.
|
|
|
|
The transfer request can be resolved either as a transfer or as a
|
|
three-way conference call. When resolved as a transfer, the parties
|
|
connected via hdCall and hdConsultCall will be connected to each other,
|
|
and both hdCall and hdConsultCall will typically be removed from the line
|
|
they were on and both will transition to the idle state. Note that the
|
|
Service Provider's opaque handles for these calls must remain valid after
|
|
the transfer has completed. The TAPI DLL causes these handles to be
|
|
invalidated when it is no longer interested in them using
|
|
TSPI_lineCloseCall.
|
|
|
|
When resolved as a conference, all three parties will enter in a
|
|
conference call. Both existing call handles remain valid, but will
|
|
transition to the conferenced state. A conference call handle will created
|
|
and returned, and it will transition to the connected state.
|
|
|
|
It may also be possible to perform a blind transfer of a call using
|
|
TSPI_lineBlindTransfer.
|
|
|
|
Arguments:
|
|
|
|
dwRequestID - Specifies the identifier of the asynchronous request.
|
|
The Service Provider returns this value if the function completes
|
|
asynchronously.
|
|
|
|
hdCall - Specifies the Service Provider's opaque handle to the call to be
|
|
transferred. Valid call states: onHoldPendingTransfer.
|
|
|
|
hdConsultCall - Specifies a handle to the call that represents a connection
|
|
with the destination of the transfer. Valid call states: connected,
|
|
ringback, busy.
|
|
|
|
htConfCall - Specifies the TAPI DLL's opaque handle to the new call. If
|
|
dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE then the
|
|
Service Provider must save this and use it in all subsequent calls to
|
|
the LINEEVENT procedure reporting events on the call. Otherwise this
|
|
parameter is ignored.
|
|
|
|
lphdConfCall - Specifies a far pointer to an opaque HDRVCALL representing
|
|
the Service Provider's identifier for the call. If dwTransferMode is
|
|
specified as LINETRANSFERMODE_CONFERENCE then the Service Provider must
|
|
fill this location with its opaque handle for the new conference call
|
|
before this procedure returns, whether it decides to execute the
|
|
request sychronously or asynchronously. This handle is invalid if the
|
|
function results in an error (either synchronously or asynchronously).
|
|
If dwTransferMode is some other value this parameter is ignored.
|
|
|
|
dwTransferMode - Specifies how the initiated transfer request is to be
|
|
resolved, of type LINETRANSFERMODE. Values are:
|
|
|
|
LINETRANSFERMODE_TRANSFER - Resolve the initiated transfer by
|
|
transferring the initial call to the consultation call.
|
|
|
|
LINETRANSFERMODE_CONFERENCE - Resolve the initiated transfer by
|
|
conferencing all three parties into a three-way conference call.
|
|
A conference call is created and returned to the TAPI DLL.
|
|
|
|
Return Values:
|
|
|
|
Returns zero if the function is successful, the (positive) dwRequestID
|
|
value if the function will be completed asynchronously, or a negative error
|
|
number if an error has occurred. Possible error returns are:
|
|
|
|
LINEERR_INVALCALLHANDLE - The specified call handle is invalid.
|
|
|
|
LINEERR_INVALCONSULTCALLHANDLE - The specified consultation call
|
|
handle is invalid.
|
|
|
|
LINEERR_INVALCALLSTATE - One or both calls are not in a valid state
|
|
for the requested operation.
|
|
|
|
LINEERR_INVALTRANSFERMODE - The specified transfer mode parameter is
|
|
invalid.
|
|
|
|
LINEERR_INVALPOINTER - The specified pointer parameter is invalid.
|
|
|
|
LINEERR_OPERATIONUNAVAIL - The specified operation is not available.
|
|
|
|
LINEERR_OPERATIONFAILED - The specified operation failed for
|
|
unspecified reason.
|
|
|
|
--*/
|
|
|
|
{
|
|
return LINEERR_OPERATIONUNAVAIL; // CODEWORK...
|
|
}
|
|
|
|
|
|
LONG
|
|
TSPIAPI
|
|
TSPI_linePrepareAddToConference(
|
|
DRV_REQUESTID dwRequestID,
|
|
HDRVCALL hdConfCall,
|
|
HTAPICALL htConsultCall,
|
|
LPHDRVCALL lphdConsultCall,
|
|
LPLINECALLPARAMS const lpCallParams
|
|
)
|
|
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
This function prepares an existing conference call for the addition of
|
|
another party. It creates a new, temporary consultation call. The new
|
|
consulatation call can be subsequently added to the conference call.
|
|
|
|
A conference call handle can be obtained via TSPI_lineSetupConference or
|
|
via TSPI_lineCompleteTransfer that is resolved as a three-way conference
|
|
call. The function TSPI_linePrepareAddToConference typically places the
|
|
existing conference call in the onHoldPendingConference state and creates
|
|
a consultation call that can be added later to the existing conference
|
|
call via TSPI_lineAddToConference.
|
|
|
|
The consultation call can be canceled using TSPI_lineDrop. It may also
|
|
be possible for the TAPI DLL to swap between the consultation call and
|
|
the held conference call via TSPI_lineSwapHold.
|
|
|
|
The Service Provider initially does media monitoring on the new call for
|
|
at least the set of media modes that were monitored for on the line.
|
|
|
|
Arguments:
|
|
|
|
dwRequestID - Specifies the identifier of the asynchronous request.
|
|
The Service Provider returns this value if the function completes
|
|
asynchronously.
|
|
|
|
hdConfCall - Specifies the Service Provider's opaque handle to a
|
|
conference call. Valid call states: connected.
|
|
|
|
htAddCall - Specifies the TAPI DLL's opaque handle to the new, temporary
|
|
consultation call. The Service Provider must save this and use it in
|
|
all subsequent calls to the LINEEVENT procedure reporting events on
|
|
the new call.
|
|
|
|
lphdAddCall - Specifies a far pointer to an opaque HDRVCALL representing
|
|
the Service Provider's identifier for the new, temporary consultation
|
|
call. The Service Provider must fill this location with its opaque
|
|
handle for the new call before this procedure returns, whether it
|
|
decides to execute the request sychronously or asynchronously. This
|
|
handle is invalid if the function results in an error (either
|
|
synchronously or asynchronously).
|
|
|
|
lpCallParams - Specifies a far pointer to call parameters to be used when
|
|
establishing the consultation call. This parameter may be set to NULL
|
|
if no special call setup parameters are desired.
|
|
|
|
Return Values:
|
|
|
|
Returns zero if the function is successful, the (positive) dwRequestID
|
|
value if the function will be completed asynchronously, or a negative error
|
|
number if an error has occurred. Possible error returns are:
|
|
|
|
LINEERR_INVALCONFCALLHANDLE - The specified call handle for the
|
|
conference call is invalid.
|
|
|
|
LINEERR_INVALPOINTER - One or more of the specified pointer
|
|
parameters are invalid.
|
|
|
|
LINEERR_INVALCALLSTATE - The conference call is not in a valid state
|
|
for the requested operation.
|
|
|
|
LINEERR_CALLUNAVAIL - All call appearances on the specified address
|
|
are currently allocated.
|
|
|
|
LINEERR_CONFERENCEFULL - The maximum number of parties for a
|
|
conference has been reached.
|
|
|
|
LINEERR_INVALCALLPARAMS - The specified call parameters are invalid.
|
|
|
|
LINEERR_OPERATIONUNAVAIL - The specified operation is not available.
|
|
|
|
LINEERR_OPERATIONFAILED - The specified operation failed for
|
|
unspecified reason.
|
|
|
|
--*/
|
|
|
|
{
|
|
return LINEERR_OPERATIONUNAVAIL; // CODEWORK...
|
|
}
|
|
|
|
|
|
LONG
|
|
TSPIAPI
|
|
TSPI_lineSetupConference(
|
|
DRV_REQUESTID dwRequestID,
|
|
HDRVCALL hdCall,
|
|
HDRVLINE hdLine,
|
|
HTAPICALL htConfCall,
|
|
LPHDRVCALL lphdConfCall,
|
|
HTAPICALL htConsultCall,
|
|
LPHDRVCALL lphdConsultCall,
|
|
DWORD dwNumParties,
|
|
LPLINECALLPARAMS const lpCallParams
|
|
)
|
|
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
This function sets up a conference call for the addition of the third
|
|
party.
|
|
|
|
TSPI_lineSetupConference provides two ways for establishing 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 hdCall parameter is a valid call handle that is
|
|
initially added to the conference call by the TSPI_lineSetupConference
|
|
request and hdLine is ignored. On switches where conference call setup
|
|
does not start with an existing call, hdCall must be NULL and hdLine
|
|
must 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 TAPI DLL
|
|
can use TSPI_lineDial to dial the address of the other party.
|
|
|
|
The conference call will typically transition into the
|
|
onHoldPendingConference state, the consultation call dialtone state and
|
|
the initial call (if one) into the conferenced state.
|
|
|
|
A conference call can also be set up via a TSPI_lineCompleteTransfer that
|
|
is resolved into a three-way conference.
|
|
|
|
The TAPI DLL may be able to toggle between the consultation call and the
|
|
conference call by using TSPI_lineSwapHold.
|
|
|
|
Arguments:
|
|
|
|
dwRequestID - Specifies the identifier of the asynchronous request.
|
|
The Service Provider returns this value if the function completes
|
|
asynchronously.
|
|
|
|
hdCall - Specifies the Service Provider's opaque 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 hdCall
|
|
is left NULL. Valid call states: connected.
|
|
|
|
hdLine - Specifies the Service Provider's opaque handle to the line device
|
|
on which to originate the conference call if hdCall is NULL. The
|
|
hdLine parameter is ignored if hdCall is non-NULL. The Service
|
|
Provider reports which model it supports through the setupConfNull
|
|
flag of the LINEADDRESSCAPS data structure.
|
|
|
|
htConfCall - Specifies the TAPI DLL's opaque handle to the new conference
|
|
call. The Service Provider must save this and use it in all subsequent
|
|
calls to the LINEEVENT procedure reporting events on the new call.
|
|
|
|
lphdConfCall - Specifies a far pointer to an opaque HDRVCALL representing
|
|
the Service Provider's identifier for the newly created conference
|
|
call. The Service Provider must fill this location with its opaque
|
|
handle for the new call before this procedure returns, whether it
|
|
decides to execute the request sychronously or asynchronously. This
|
|
handle is invalid if the function results in an error (either
|
|
synchronously or asynchronously).
|
|
|
|
htAddCall - Specifies the TAPI DLL's opaque handle to a new 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 htAddCall and use it in all subsequent calls to the
|
|
LINEEVENT procedure reporting events on the new consultation call.
|
|
|
|
lphdAddCall - Specifies a far pointer to an opaque HDRVCALL representing
|
|
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 opaque handle for the new consultation call before
|
|
this procedure returns, whether it decides to execute the request
|
|
sychronously or asynchronously. This handle is invalid if the
|
|
function results in an error (either synchronously or asynchronously).
|
|
|
|
dwNumParties - Specifies the expected number of parties in the conference
|
|
call. The service provider is free to do with this number as it
|
|
pleases; ignore it, use it a hint to allocate the right size
|
|
conference bridge inside the switch, etc.
|
|
|
|
lpCallParams - Specifies a far pointer to call parameters to be used when
|
|
establishing the consultation call. This parameter may be set to NULL
|
|
if no special call setup parameters are desired.
|
|
|
|
Return Values:
|
|
|
|
Returns zero if the function is successful, the (positive) dwRequestID
|
|
value if the function will be completed asynchronously, or a negative error
|
|
number if an error has occurred. Possible error returns are:
|
|
|
|
LINEERR_INVALCALLHANDLE - The specified call handle for the conference
|
|
call is invalid. This error may also indicate that the telephony
|
|
environment requires an initial call to set up a conference but a
|
|
NULL call handle was supplied.
|
|
|
|
LINEERR_INVALLINEHANDLE - The specified line handle for the line
|
|
containing the conference call is invalid. This error may also
|
|
indicate that the telephony environment requires an initial line
|
|
to set up a conference but a non-NULL call handle was supplied
|
|
instead.
|
|
|
|
LINEERR_INVALCALLSTATE - The call is not in a valid state for the
|
|
requested operation.
|
|
|
|
LINEERR_CALLUNAVAIL - All call appearances on the specified address
|
|
are currently allocated.
|
|
|
|
LINEERR_CONFERENCEFULL - The requested number of parties cannot be
|
|
satisfied.
|
|
|
|
LINEERR_INVALPOINTER - One or more of the specified pointer
|
|
parameters are invalid.
|
|
|
|
LINEERR_INVALCALLPARAMS - The specified call parameters are invalid.
|
|
|
|
LINEERR_OPERATIONUNAVAIL - The specified operation is not available.
|
|
|
|
LINEERR_OPERATIONFAILED - The specified operation failed for
|
|
unspecified reason.
|
|
|
|
--*/
|
|
|
|
{
|
|
return LINEERR_OPERATIONUNAVAIL; // CODEWORK...
|
|
}
|
|
|
|
|
|
LONG
|
|
TSPIAPI
|
|
TSPI_lineRemoveFromConference(
|
|
DRV_REQUESTID dwRequestID,
|
|
HDRVCALL hdCall
|
|
)
|
|
|
|
/*++
|
|
|
|
Routine Description:
|
|
|
|
This function removes the specified call from the conference call to
|
|
which it currently belongs. The remaining calls in the conference
|
|
call are unaffected.
|
|
|
|
This operation removes a party that currently belongs to a conference
|
|
call. After the call has been successfully removed, it may be possible
|
|
to further manipulate it using its handle. The availability of this
|
|
operation and its result are likely to be limited in many
|
|
implementations. For example, in many implementations, only the most
|
|
recently added party may be removed from a conference, and the removed
|
|
call may be automatically dropped (becomes idle). Consult the line's
|
|
device capabilities to determine the available effects of removing a
|
|
call from a conference.
|
|
|
|
Arguments:
|
|
|
|
dwRequestID - Specifies the identifier of the asynchronous request.
|
|
The Service Provider returns this value if the function completes
|
|
asynchronously.
|
|
|
|
hdCall - Specifies the Service Provider's opaque handle to the call
|
|
to be removed from the conference. Valid call states: conferenced.
|
|
|
|
Return Values:
|
|
|
|
Returns zero if the function is successful, the (positive) dwRequestID
|
|
value if the function will be completed asynchronously, or a negative error
|
|
number if an error has occurred. Possible error returns are:
|
|
|
|
LINEERR_INVALCALLHANDLE - The specified call handle is invalid.
|
|
|
|
LINEERR_INVALCALLSTATE - The call is not in a valid state for the
|
|
requested operation.
|
|
|
|
LINEERR_OPERATIONUNAVAIL - The specified operation is not available.
|
|
|
|
LINEERR_OPERATIONFAILED - The specified operation failed for
|
|
unspecified reasons.
|
|
|
|
--*/
|
|
|
|
{
|
|
return LINEERR_OPERATIONUNAVAIL; // CODEWORK...
|
|
}
|
|
|
|
|