The TSPI_lineConditionalMediaDetection function is invoked by TAPI whenever a client application uses LINEMAPPER as the dwDeviceID in a lineOpen function to request that lines be scanned to find one that supports the desired media modes and call parameters. TAPI scans based on the union of the desired media mode and the other media modes currently being monitored on the line, to give the service provider the opportunity to indicate if it cannot simultaneously monitor for all of the requested media modes. If the service provider can monitor for the indicated set of media modes and support the capabilities indicated in lpCallParams, it replies with a success indication. It leaves the active media monitoring modes for the line unchanged.
LONG TSPI_lineConditionalMediaDetection(
HDRVLINE hdLine,
DWORD dwMediaModes,
LPLINECALLPARAMS const lpCallParams
);
dwBearerMode
dwMinRate
dwMaxRate
dwMediaMode
dwCallParamFlags
dwAddressMode
If dwAddressMode is LINEADDRESSMODE_ADDRESSID, any address on the line is acceptable. If dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension, additional information can be contained in the dwDeviceSpecific variably sized field. All other fields are irrelevant to the function.
Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:
LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONUNAVAIL.
A TAPI lineOpen function that specifies a device identifier of LINEMAPPER typically results in calling this procedure for multiple line devices to hunt for a suitable line, possibly also opening as-yet unopened lines. A success result indicates that the line is suitable for the calling application's requirements.
Note The media monitoring modes demanded at the TSPI level are the union of monitoring modes demanded by multiple applications at the TAPI level. As a consequence, it is most common for multiple media mode flags to be set simultaneously at this level. The service provider must test to determine if it can support at least the specified set, regardless of what modes are currently in effect. TAPI ensures that the dwMediaModes parameter has at least one bit set and that no reserved bits are set. It is the service provider's responsibility to do any further validity checks on the media modes, such as checking whether any media modes are supported by the service provider.
The TSPI_lineConditionalMediaDetection function checks the bits set in the dwCallParamFlags member of the LINECALLPARAMS structure and handles the following cases:
The TSPI_lineConditionalMediaDetection function returns success if passing the same bit values to the TSPI_lineMakeCall function would also return success.
If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_ADDRESSID, the function returns success if it can succeed on one or more addresses on the line.
If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_DIALABLEADDR, the function returns success if it can succeed on the address identified by the dwOrigAddress parameter.
The service provider returns an error (for example, LINEERR_RESOURCEUNAVAIL) if, at the time this function is called, it is impossible to place a new call on the specified line device (if it would return LINEERR_CALLUNAVAIL or LINEERR_RESOURCEUNAVAIL should TSPI_lineMakeCall be invoked immediately after opening the line).
There is no directly corresponding function at the TAPI level. This procedure corresponds to the test implied for each individual line by the lineOpen procedure when it is called with the device identifier LINEMAPPER.
LINECALLPARAMS, LINEMEDIAMODE_ Constants, TSPI_lineMakeCall