IPropertySetStorage::Create method (propidl.h)

The Create method creates and opens a new property set in the property set storage object.

Syntax

HRESULT Create(
  [in]  REFFMTID         rfmtid,
  [in]  const CLSID      *pclsid,
  [in]  DWORD            grfFlags,
  [in]  DWORD            grfMode,
  [out] IPropertyStorage **ppprstg
);

Parameters

[in] rfmtid

The FMTID of the property set to be created. For information about FMTIDs that are well-known and predefined in the Platform SDK, see Predefined Property Set Format Identifiers.

[in] pclsid

A pointer to the initial class identifier CLSID for this property set. May be NULL, in which case it is set to all zeroes. The CLSID is the CLSID of a class that displays and/or provides programmatic access to the property values. If there is no such class, it is recommended that the FMTID be used.

[in] grfFlags

The values from PROPSETFLAG Constants.

[in] grfMode

An access mode in which the newly created property set is to be opened, taken from certain values of STGM_Constants, as described in the following Remarks section.

[out] ppprstg

A pointer to the output variable that receives the IPropertyStorage interface pointer.

Return value

This method supports the standard return value E_UNEXPECTED, as well as the following:

Remarks

IPropertySetStorage::Create creates and opens a new property set subobject (supporting the IPropertyStorage interface) contained in this property set storage object. The property set automatically contains code page and locale ID properties. These are set to the Unicode and the current user default, respectively.

The grfFlags parameter is a combination of values taken from PROPSETFLAG Constants. If the PROPSETFLAG_ANSI value from this enumeration is used, the code page is set to the current system default, rather than Unicode.

The grfMode parameter specifies the access mode in which the newly created set is to be opened. Values for this parameter are as in the grfMode parameter to IPropertySetStorage::Open, with the addition of the values listed in the following table.

Value Meaning
STGM_FAILIFTHERE If another property set with the specified fmtid parameter exists, the call fails. This is the default action; that is, unless STGM_CREATE is specified, STGM_FAILIFTHERE is implied.
STGM_CREATE If another property set with the specified fmtid parameter already exists, it is removed and replaced with this new one.
 

The created property set is simple by default, but the caller may request a nonsimple property set by specifying the PROPSETFLAG_NONSIMPLE value in the grfFlags parameter. For more information about simple and nonsimple property sets, see Storage and Stream Objects for a Property Set.

This method is subject to the constraints of the underlying IStorage::CreateStream (for simple property sets) or IStorage::CreateStorage (for nonsimple property sets). For example, when using the IPropertySetStorage-Compound File Implementation, specify STGM_SHARE_EXCLUSIVE in the grfMode parameter to IPropertySetStorage::Create. Conversely, if using the IPropertySetStorage-Stand-alone Implementation, IPropertySetStorage::Create is subject to constraints that apply to the caller-specified IStorage.

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 propidl.h (include Objbase.h)
Library Uuid.lib
DLL Ole32.dll

See also

IPropertySetStorage

IPropertySetStorage::Open

PROPSETFLAG Constants

Samples

StgCreatePropSetStg Sample

WriteRead Sample