SHCreatePropertyBagOnRegKey

This function presents a registry key as a property bag.

Declaration

HRESULT
SHCreatePropertyBagOnRegKey (
    HKEY hKey,
    LPCWSTR pszSubKey,
    DWORD grfMode,
    REFIID riid,
    void **ppv);

Parameters

The hKey argument provides either a handle to an open key or to a root key.

The pszSubKey argument provides the address of a null-terminated Unicode string that names a subkey that this function is to represent as a property bag. This argument can be NULL to have the property bag represent the key that is already open as hKey.

The grfMode argument provides bit flags, apparently from the STGM enumeration.

access mask (0x03)	STGM_READ (0x00) for read-only, STGM_WRITE (0x01) for write-only, STGM_READWRITE (0x02) for read-write
STGM_CREATE (0x1000)	create subkey if it does not exist already (requires pszSubKey be not NULL)

The riid argument is a reference to an IID for the requested interface to the property bag.

The ppv argument addresses a variable that is to receive the interface pointer.

Return Value

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

Behaviour

If the function cannot get memory for the property bag, it fails, with E_OUTOFMEMORY as the error code.

Interpretation of hKey and pszSubKey depends on the STGM_CREATE bit in grfMode. If this bit is clear, the function opens the given subkey, or if pszSubKey is NULL, opens a new handle to the key already represented by hKey. If the STGM_CREATE bit is set in grfMode, the function opens or creates the subkey named by pszSubKey, which must be non-NULL. (Specifically, the function obtains the behaviour of passing hKey and pszSubKey to the standard API function RegOpenKeyEx if the flag is clear but RegCreateKeyEx if the flag is set.)

Access to the registry key depends on the 0x03 mask in grfMode. The function asks for read access unless the mask produces STGM_WRITE and for write access unless the mask produces STGM_READ.

If the function cannot open or create as required, it fails.

Otherwise, the property bag is created and the function queries for the interface given by riid, returning the interface pointer at the address given by ppv. The property bag implements the IPropertyBag and IPropertyBag2 interfaces. However, the IPropertyBag2 methods are all implemented to fail, returning E_NOTIMPL.

Availability

The SHCreatePropertyBagOnRegKey function is exported from SHLWAPI as ordinal 471 in version 5.50 and higher.

Though this function dates from as long ago as 2000, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.