lineGetIcon

  • Article

This function allows an application to retrieve a service line device-specific (or provider-specific) icon for display to the user.

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

Parameters

  • dwDeviceID
    Line 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 line 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 Values

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
LINEERR_BADDEVICEID The device identifier is incorrect.
LINEERR_OPERATIONFAILED The operation failed.
LINEERR_INVALPOINTER The pointer is invalid.
LINEERR_RESOURCEUNAVAIL The resources are unavailable.
LINEERR_INVALDEVICECLASS The device class is invalid.
LINEERR_UNINITIALIZED A parameter is uninitialized.
LINEERR_NOMEM Not enough memory is available.
LINEERR_NODEVICE The device was not found.

Remarks

The lineGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) that is associated with the specified line. 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 line 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 the lineGetID function. For example, if the line 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/line", "", or NULL can be used to request the icon for the line service.

For applications using an API 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 Microsoft® Win32® Telephony line device icon. For applications using API version 2.0 or later, TAPI substitutes the default line icon only if the lpszDeviceClass parameter is "tapi/line", "" 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, lineGetIcon returns LINEERR_INVALDEVICECLASS.

Note   This function is for TAPI version 2.0 and later.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Tapi.h.
Link Library: Coredll.lib.

See Also

lineGetID | LoadIcon

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.