Share via


phoneGetIcon (Windows Embedded CE 6.0)

1/6/2010

This function allows an application to retrieve a service phone device-specific (or provider-specific) icon that can be displayed to the user.

Syntax

LONG WINAPI phoneGetIcon(
  DWORD dwDeviceID,
  LPCWSTR lpszDeviceClass,
  LPHICON lphIcon 
);

Parameters

  • dwDeviceID
    Phone device whose icon is requested.
  • lpszDeviceClass
    Pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the phone device rather than a specified media stream device would be selected.
  • lphIcon
    Pointer to a memory location in which the handle to the icon is returned.

Return Value

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

Value Description

PHONEERR_BADDEVICEID

The device identifier is incorrect.

PHONEERR_RESOURCEUNAVAIL

The resources are unavailable.

PHONEERR_INVALPOINTER

The pointer is invalid.

PHONEERR_OPERATIONFAILED

The operation failed.

PHONEERR_INVALDEVICECLASS

The device class is invalid.

PHONEERR_UNINITIALIZED

A parameter is uninitialized.

PHONEERR_NOMEM

Not enough memory is available.

PHONEERR_NODEVICE

The device was not found.

Remarks

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 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 phoneGetID function. 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.

Note

This function is for TAPI version 2.0 and later.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later

See Also

Reference

phoneGetID

Concepts

TAPI Phone Device Functions

Other Resources

LoadIcon