Platform SDK: TAPI |
The phoneGetIcon function allows an application to retrieve a service phone device-specific (or provider-specific) icon that can be displayed to the user.
LONG WINAPI phoneGetIcon( DWORD dwDeviceID, LPCSTR lpszDeviceClass, LPHICON lphIcon );
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:
PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.
The phoneGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) associated with the specified phone. The icon handle is for a resource associated with the provider; the application must use CopyIcon if it wants to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the phone open.
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 phoneGetID. For example, if the phone supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone service.
For applications using a TAPI version earlier than 2.0, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony phone device icon. For applications using TAPI version 2.0 or later, TAPI substitutes the default phone icon only if the lpszDeviceClass parameter is "tapi/phone", "", or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, phoneGetIcon returns PHONEERR_INVALDEVICECLASS.
Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, phoneGetID