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 retrieves a service phone device-specific (or provider-specific) icon to display to the user.

Syntax 

LONG TSPIAPI TSPI_phoneGetIcon(
  DWORD 
dwDeviceID, 
  LPCWSTR 
lpszDeviceClass,  
  LPHICON 
lphIcon 
);

Parameters

dwDeviceID

Phone device whose icon is requested.

lpszDeviceClass

Pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific sub icon applicable to that device class. This parameter is optional and can be left NULL or be empty, in which case the highest level icon associated with the phone device rather than a specified media stream device is selected.

lphIcon

Pointer to a memory location in which the handle to the icon is returned.

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 method.

Value Description

PHONEERR_INVALDEVICECLASS

The device class is invalid.

PHONEERR_OPERATIONFAILED

The operation failed.

PHONEERR_NOMEM

Not enough memory is available.

PHONEERR_OPERATIONUNAVAIL

The operation is unavailable.

PHONEERR_RESOURCEUNAVAIL

The resource is unavailable.

Remarks

TSPI_phoneGetIconcauses the provider to return a handle (in the DWORDpointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIconfunction) associated with the specified phone. The icon handle is for a resource associated with the provider.

The lpszDeviceClassparameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for the TSPI_phoneGetIDfunction.

The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone device. A provider can choose to support many icons (selected by lpszDeviceClassand/or phone number), a single icon (such as for the manufacturer, which would be returned for all phoneGetIconrequests regardless of the lpszDeviceClassselected), or no icons, in which case it sets the DWORDpointed to by lphIconto NULL. TAPI examines the handle returned by the provider, and if the provider returns NULL, TAPI substitutes a generic Win32 Telephony icon included as a resource in TAPI (the generic phone icon).

If the service provider supports no icons, it can leave this function unimplemented, in which case TAPI provides a generic phone icon for the application.

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