SHDefExtractIconA function (shlobj_core.h)

Article
02/22/2024

Provides a default handler to extract an icon from a file.

Syntax

SHSTDAPI SHDefExtractIconA(
  [in]            LPCSTR pszIconFile,
                  int    iIndex,
  [in]            UINT   uFlags,
  [out, optional] HICON  *phiconLarge,
  [out, optional] HICON  *phiconSmall,
                  UINT   nIconSize
);

Parameters

[in] pszIconFile

Type: LPCTSTR

A pointer to a null-terminated buffer that contains the path and name of the file from which the icon is extracted.

iIndex

Type: int

The location of the icon within the file named in pszIconFile. If this is a positive number, it refers to the zero-based position of the icon in the file. For instance, 0 refers to the 1st icon in the resource file and 2 refers to the 3rd. If this is a negative number, it refers to the icon's resource ID.

[in] uFlags

Type: UINT

A flag that controls the icon extraction.

GIL_SIMULATEDOC

Overlays the extracted icon on the default document icon to create the final icon. This icon can be used when no more appropriate icon can be found or retrieved.

[out, optional] phiconLarge

Type: HICON*

A pointer to an HICON that, when this function returns successfully, receives the handle of the large version of the icon specified in the LOWORD of nIconSize. This value can be NULL.

[out, optional] phiconSmall

Type: HICON*

A pointer to an HICON that, when this function returns successfully, receives the handle of the small version of the icon specified in the HIWORD of nIconSize.

nIconSize

Type: UINT

A value that contains the large icon size in its LOWORD and the small icon size in its HIWORD. Size is measured in pixels. Pass 0 to specify default large and small sizes.

Return value

Type: HRESULT

This function can return one of these values.

Return code	Description
S_OK	Success.
S_FALSE	The requested icon is not present.
E_FAIL	The file cannot be accessed, or is being accessed through a slow link.

Remarks

It is the responsibility of the caller to free the icon resources created through this function when they are no longer needed. This can be done through the DestroyIcon function.

Note

The shlobj_core.h header defines SHDefExtractIcon as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	shlobj_core.h (include Shlobj.h, Shlobj_core.h)
Library	Shell32.lib
DLL	Shell32.dll (version 6.0 or later)
API set	ext-ms-win-shell-shell32-l1-2-1 (introduced in Windows 10, version 10.0.10240)

Share via