SHCreatePropertyBagOnProfileSection

This function presents a .INI file section as a property bag.

Declaration

HRESULT
SHCreatePropertyBagOnProfileSection (
    LPCWSTR pszFileName,
    LPCWSTR pszSectionName,
    DWORD grfMode,
    REFIID riid,
    void **ppv);

Parameters

The pszFileName argument provides the address of a null-terminated Unicode string that names the .INI file.

The pszSectionName argument provides the address of a null-terminated Unicode string that names a profile section. This argument can be NULL to have the property bag represent entries that are not in any section.

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 .INI file if it does not exist already

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 STGM_CREATE is set in grfMode, then if file named by pszFileName does not already exist, the function creates the file, giving it hidden and system attributes, and sets its containing directory as a system folder, meaning mostly to give it the read-only and system attributes (but see PathMakeSystemFolder for details).

If the file named by pszFileName does not exist or if the function cannot get memory for the property bag, it fails, with E_OUTOFMEMORY as the error code.

With the property bag created, 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 SHCreatePropertyBagOnProfileSection function is exported from SHLWAPI as ordinal 472 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.