StgCreatePropSetStg function (coml2api.h)

Article
10/13/2021

The StgCreatePropSetStg function creates a property set storage object from a specified storage object. The property set storage object supplies the system-provided, stand-alone implementation of the IPropertySetStorage interface.

Syntax

HRESULT StgCreatePropSetStg(
  [in]  IStorage            *pStorage,
        DWORD               dwReserved,
  [out] IPropertySetStorage **ppPropSetStg
);

Parameters

[in] pStorage

A pointer to the storage object that contains or will contain one or more property sets.

dwReserved

Reserved for future use; must be zero.

[out] ppPropSetStg

A pointer to IPropertySetStorage* pointer variable that receives the interface pointer to the property-set storage object.

Return value

This function supports the standard return value E_INVALIDARG as well as the following:

Remarks

The StgCreatePropSetStg function creates an IPropertySetStorage interface that will act on the given IStorage interface specified by the pStorage parameter. This function does not modify this IStorage by itself, although subsequent calls to the IPropertySetStorage interface might.

StgCreatePropSetStg calls IUnknown::AddRef on the storage object specified by pStorage. The caller must release the object when it is no longer required by calling Release.

Examples

The following example code shows how this function creates a property set within a storage object.

IPropertyStorage*
CreatePropertySetInStorage( IStorage *pStg, const FMTID &fmtid )
{
    HRESULT hr = S_OK;
    IPropertySetStorage *pPropSetStg = NULL;
    IPropertyStorage *pPropStg = NULL;
 
    try
    {
        hr = StgCreatePropSetStg( pStg, 0, &pPropSetStg );
        if( FAILED(hr) ) throw L"Failed StgCreatePropSetStg (%08x)";
 
        hr = pPropSetStg->Create( fmtid, NULL,
            PROPSETFLAG_DEFAULT,
            STGM_CREATE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE,
            &pPropStg );
        if( FAILED(hr) ) 
            throw L"Failed IPropertySetStorage::Create (%08x)";
 
        // Success. The caller must now call Release on both
        // pPropSetStg and pStg.
 
    }
    catch( const WCHAR *pwszError )
    {
        wprintf( L"Error: %s (%08x)\n", pwszError, hr );
    }
 
    if( NULL != pPropSetStg )
        pPropSetStg->Release();
 
    return( pPropStg );
}

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	coml2api.h (include Propidl.h)
Library	Ole32.lib
DLL	Ole32.dll