AssocGetPerceivedType

Declaration

HRESULT
AssocGetPerceivedType (
    LPCWSTR pszExt, 
    PERCEIVED *ptype, 
    PERCEIVEDFLAG *pflag, 
    LPWSTR *ppszType);

Parameters

The pszExt argument provides the address of a case-insensitive null-terminated string that describes the type to look up.

The ptype argument provides the address of a variable that is to receive a code that identifies the perceived type.

The pflag argument provides the address of a variable that is to receive flags that describe the perceived type.

The ppszType argument provides the address of a variable that is to receive a string representation of the perceived type. The ppszType argument may be NULL if this information is not wanted.

Return Value

The function returns zero for success, else an error code.

The variables at ptype and pflag are meaningful even on failure.

Behaviour

If the given type is any of many file extensions for which information is hard-coded into SHLWAPI, then the function’s behaviour is determined entirely from the hard-coded information. The following large table shows the complete behaviour. Note that although the function recognises “.lnk” and “.search-ms” and produces data for the ptype and pflag arguments, there is no name for the perceived type and the function fails (returning E_FAIL).

Registration

If the given type is not a recognised file extension, the function looks for the perceived type in either of two registry keys, shown below in order of decreasing precedence:

where ext is the given type (and need not be a file extension). If the function falls back to the second key but cannot fit the longer registry path into MAX_PATH characters, it fails. If the function cannot read the value from either key (with a limit of 40 characters), it fails. In these cases of failure, the perceived type and flags returned through the ptype and pflag arguments are PERCEIVED_TYPE_FOLDER and PERCEIVEDFLAG_UNDEFINED respectively.

The string data for the PerceivedType value is the case-insensitive name of the perceived type. Each perceived type has hard-coded values for the descriptions that are returned through the ptype and pflag arguments: 

If the name from the registry value is recognised, then the name returned through the ppszType argument is the hard-coded name from the table. Otherwise, it is the name from the registry.

Returned Name

If the function cannot duplicate the name in order to return a pointer at the address given by ppszType, it fails. Memory for the name is found by the SHStrDup function and should be freed using CoTaskMemFree when the name is no longer needed.

Comment

Note that although Microsoft defines a PERCEIVED_TYPE_UNKNOWN and (more significantly) a PERCEIVED_TYPE_CONTACTS, it is not currently possible for this function to produce either of these values, and PERCEIVED_TYPE_FOLDER is nothing but the function’s default for an error. Conversely, Microsoft’s documentation has it that PERCEIVED_TYPE_DOCUMENT is “not used”, though plainly it is.

That the large table of hard-coded perceived types for recognised file extensions seems not yet to have been published anywhere (except in the SHLWAPI binary code) seems a little odd. It may be the closest that Microsoft comes to a list of so-called public file types. Surely though ought be listed somewhere, if only so that nobody will even think to try setting a perceived type for them in the registry.

Availability

The AssocGetPerceivedType function is exported by name from SHLWAPI.DLL in builds of version 6.00 from Windows XP SP2 and higher, from Windows Server 2003 SP1 and higher, and from Windows Vista and higher, and presumably in higher versions.