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