TSPI_lineConditionalMediaDetection

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function is invoked by TAPI whenever a client application uses LINEMAPPER as the dwDeviceID in a lineOpen function call to request that lines be scanned to find one that supports the desired media types and call parameters. TAPI scans based on the union of the desired media type and the other media types 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 types. If the service provider can monitor for the indicated set of media types and support the capabilities indicated in the lpCallParams parameter, it replies with a success indication. It leaves the active media monitoring modes for the line unchanged.

Syntax

LONG TSPIAPI TSPI_lineConditionalMediaDetection(
  HDRVLINE hdLine, 
  hdConsultCall dwMediaModes, 
  hdConsultCall const lpCallParams 
);

Parameters

• hdLine
  Service provider's handle to the line on which media monitoring and parameter capabilities are to be set.

• dwMediaModes
  Media types currently of interest to the calling application. This parameter uses one of the LINEMEDIAMODE constants.

• lpCallParams
  Pointer to a structure of type LINECALLPARAMS. It describes the call parameters that the line device should be able to provide. The following table shows the only relevant fields of lpCallParams for the purposes of this test.

  Value	Description
  dwBearerMod	Bearer mode for the call.
  dwMinRate	Data rate range requested for the call's data stream in bps (bits per second).
  dwMaxRate	Data rate range requested for the call's data stream in bps (bits per second).
  dwMediaMode	Expected media mode of the call. For exact values see LINECALLPARAMS.
  dwCallParamFlags	Collection of Boolean call-setup parameters. For exact values see LINECALLPARAMS.
  dwAddressMode	Mode by which the originating address is specified. For exact values see LINECALLPARAMS.

  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.

Return Value

Returns zero if the function succeeds or an error number if an error occurs. The following table shows the return values for this function.

Remarks

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.

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 type 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 types, such as checking whether any media types 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.

Requirements

See Also

Reference

TSPI_lineMakeCall