Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function returns a device identifier for the specified device class associated with the selected line, address, or call.

Syntax 

LONG TSPIAPI TSPI_lineGetID(
  HDRVLINE 
hdLine,
  DWORD 
dwAddressID,
  HDRVCALL 
hdCall,
  DWORD 
dwSelect,
  LPVARSTRING 
lpDeviceID,
  LPCWSTR 
lpszDeviceClass,  
  HANDLE 
hTargetProcess 
);

Parameters

hdLine

Service provider's handle to the line to be queried.

dwAddressID

Address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called.

hdCall

Service provider's handle to the call to be queried.

dwSelect

Value that specifies whether the device identifier requested is associated with the line, address, or a single call. The dwSelectparameter can have only one of the LINECALLSELECTconstants.

lpDeviceID

Pointer to the memory location of type VARSTRINGwhere the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class (API) for naming devices.

lpszDeviceClass

Pointer to a null-terminated Unicode string that specifies the device class of the device whose identifier is requested. The device class is dependent on the service provider.

hTargetProcess

Process handle of the application on behalf of which the TSPI_lineGetIDfunction is invoked. If the information returned in the VARSTRINGstructure includes a handle for use by the application, the service provider should create or duplicate the handle for the process.

If hTargetProcessis set to INVALID_HANDLE_VALUE, then the application is executing on a remote client system and it is not possible to create a duplicate handle directly. Instead, the VARSTRINGstructure should contain a UNC name of a network device or other name that the remote client can use to access the device. If this is not possible, then the function should fail.

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.

Value Description

LINEERR_INVALLINEHANDLE

The handle to the line is invalid.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALADDRESSID

The address id is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_NODEVICE

The device was not found.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

Remarks

The service provider returns LINEERR_INVALLINEHANDLE if dwSelectis LINECALLSELECT_LINE or LINECALLSELECT_ADDRESS, and hdLineis invalid.

The service provider returns LINEERR_INVALCALLHANDLE if dwSelectis LINECALLSELECT_CALL and hdCallis invalid.

The service provider should support the tapi/line device class to allow applications to determine the real line device identifier of an opened line. In that case, the variable data returned is the dwDeviceID.

A vendor that defines a device-specific media type also needs to define the corresponding device-specific (proprietary) API to manage devices of the media type. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies the vendor and then the media type; for example: "Intel/video".

The service provider fills in all the members of the VARSTRINGdata structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSizemember.

The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also