TSPI_phoneGetIcon (Windows CE 5.0)
This function retrieves a service phone device-specific (or provider-specific) icon to display to the user.
LONG TSPIAPI TSPI_phoneGetIcon(DWORDdwDeviceID,LPCWSTRlpszDeviceClass,LPHICONlphIcon);
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 Values
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_phoneGetIcon causes the provider to return a handle (in the DWORD pointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIcon function) associated with the specified phone. The icon handle is for a resource associated with the provider.
The lpszDeviceClass parameter 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_phoneGetID function.
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 lpszDeviceClass and/or phone number), a single icon (such as for the manufacturer, which would be returned for all phoneGetIcon requests regardless of the lpszDeviceClass selected), or no icons, in which case it sets the DWORD pointed to by lphIcon to 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
OS Versions: Windows CE 3.0 and later.
Header: Tapicomn.h.
Link Library: Coredll.lib.
See Also
TSPI_phoneConfigDialog | TSPI_phoneGetID
Send Feedback on this topic to the authors