# IPropertySetStorage::Create

Creates and opens a new property set in the property set storage object.

HRESULT Create(

REFFMTID fmtid, | //Format identifier of the property set to be created
CLSID * pclsid, | //Pointer to initial CLSID for this property set
DWORD grfFlags, | //PROPSETFLAG values
DWORD grfMode, | //Storage mode of new property set
IPropertyStorage** ppPropStg | //Indirect pointer to property storage sub-object
); |

Parameters

fmtid
  [in] Format identifier of the property set to be created.
pclsid
  [in] Pointer to the initial CLSID for this property set. May be NULL, in which case it is set to all zeroes.
grfFlags
  [in] Values from the PROPSETFLAG enumeration.
grfMode
  [in] Access mode in which the newly created property set is to be opened, taken from certain values of the STGM enumeration, as described in the Remarks.
ppPropStg
  [out] Indirect pointer to the IPropertyStorage interface on the new property storage sub-object.

Return Values

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

S_OK
  The property set was created.
STG_E_FILEALREADYEXISTS
  A property set of the indicated name already exists, and STGM_CREATE was not specified.
STG_E_ACCESSDENIED
  The requested access to the property storage object has been denied.
STG_E_INSUFFICIENTMEMORY
  There is not sufficient memory to perform this operation.
STG_E_INVALIDPARAMETER
  A parameter is invalid.

Remarks

IPropertySetStorage::Create creates and opens a new property set sub-object (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 current system default, and the current user default, respectively.

The grfFlags parameter is a combination of values taken from the enumeration PROPSETFLAG.

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 like-named parameter to IPropertySetStorage::Open, with the addition of the following values:

Value | Meaning
STGM_FAILIFTHERE | If another property set with the specified fmtid already 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 already exists, it is removed and replaced with this new one.
STGM_DIRECT | Open the property set without an additional level of transaction nesting. This is the default (the behavior if neither STGM_DIRECT nor STGM_TRANSACTED is specified).
STGM_TRANSACTED | Open the property set with an additional level of transaction nesting (beyond the transaction, if any, on this property set storage). This is possible only when you specify PROPSETFLAG_NONSIMPLE in the grfFlags parameter. Changes in the property set must be committed with IPropertyStorage::Commit before they are visible to the transaction on this property set storage.
STGM_READ | Read access is desired on the property set. Read permission is required on the property set storage.
STGM_WRITE | Write access is desired on the property set. Write permission is not required on the property set storage; however, such write permission is required for changes in the storage to be committed.
STGM_READWRITE | Read-write access is desired on the property set. Note that this flag is not the binary OR of the values STGM_READ and STGM_WRITE.
STGM_SHARE_EXCLUSIVE | Prevents others from subsequently opening the property set either in STGM_READ or STGM_WRITE mode.

Note The only access mode supported by Create is STGM_SHARE_EXCLUSIVE. To use the resulting property set in an access mode other than STGM_SHARE_EXCLUSIVE, the caller should close the stream and then re-open it with a call to IPropertySetStorage::Open.

See Also

IPropertySetStorage::Open