520 lines
21 KiB
C
520 lines
21 KiB
C
/*++
|
||
|
||
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...
|
||
}
|
||
|
||
|