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
                  //Address of output variable that receives the 
                  //IPropertyStorage interface pointer
);

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] Address of IPropertyStorage* pointer variable that receives the interface pointer to 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.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.