Retrieves an object that represents a specific window's collection of properties, which allows those properties to be queried or set.
Syntax
HRESULT SHGetPropertyStoreForWindow(
HWND hwnd,
REFIID riid,
void **ppv
);
Parameters
- hwnd
-
[in] A handle to the window whose properties are being retrieved.
- riid
-
[in] A reference to the IID of the property store object to retrieve through ppv. This is typically IID_IPropertyStore.
- ppv
-
[out] When this function returns, contains the interface pointer requested in riid. This is typically IPropertyStore.
Return Value
Returns S_OK if successful, or an error value otherwise.
Remarks
An application can use this function to obtain access to a window's property store so that it can set an explicit Application User Model ID (AppUserModelID) in the System.AppUserModel.ID property.
A window's properties must be removed before the window is closed. If this is not done, the resources used by those properties are not returned to the system. A property is removed by setting it to the PROPVARIANT type VT_EMPTY.
When a call is made to IPropertyStore::SetValue on the object retrieved through ppv, the properties and values are immediately stored on the window. Therefore, no call to IPropertyStore::Commit is needed. No error occurs if it is called, but it has no effect.
An application sets AppUserModelIDs on individual windows to control the application's taskbar grouping and Jump List contents. For instance, a suite application might want to provide a different taskbar button for each of its subfeatures, with the windows relating to that subfeature grouped under that button. Without window-level AppUserModelIDs, those windows would all be grouped together under the main process.
Applications should also use this property store to set these relaunch properties so that the system can return the application to that state.
Function Information
| Minimum DLL Version | Shell32.dll version 6.1 or later |
|---|
| Custom Implementation | No |
|---|
| Header | shellapi.h |
|---|
| Import library | shell32.lib |
|---|
| Minimum operating systems |
Windows 7 |
|---|
See Also
Application User Model IDs (AppUserModelIDs)