EN
Ce contenu n’est pas disponible dans votre langue. Voici la version anglaise.

StgCreateStorageEx function

The StgCreateStorageEx function creates a new storage object using a provided implementation for the IStorage or IPropertySetStorage interfaces. To open an existing file, use the StgOpenStorageEx function instead.

Applications written for Windows 2000, Windows Server 2003 and Windows XP must use StgCreateStorageEx rather than StgCreateDocfile to take advantage of the enhanced Windows 2000 and Windows XP Structured Storage features.

Syntax


WINOLEAPI StgCreateStorageEx(
  _In_   const WCHAR *pwcsName,
  _In_   DWORD grfMode,
  _In_   STGFMT stgfmt,
  _In_   DWORD grfAttrs,
  _In_   STGOPTIONS *pStgOptions,
  _In_   PSECURITY_DESCRIPTOR *pSecurityDescriptor,
  _In_   REFIID riid,
  _Out_  void **ppObjectOpen
);

Parameters

pwcsName [in]

A pointer to the path of the file to create. It is passed uninterpreted to the file system. This can be a relative name or NULL. If NULL, a temporary file is allocated with a unique name. If non-NULL, the string size must not exceed MAX_PATH characters.

Windows 2000:  Unlike the CreateFile function, you cannot exceed the MAX_PATH limit by using the "\\?\" prefix.

grfMode [in]

A value that specifies the access mode to use when opening the new storage object. For more information, see STGM Constants. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion takes place when the commit operation is called for the root storage. If IStorage::Commit is not called for the root storage object, previous contents of the file will be restored. STGM_CREATE and STGM_CONVERT cannot be combined with the STGM_NOSNAPSHOT flag, because a snapshot copy is required when a file is overwritten or converted in the transacted mode.

stgfmt [in]

A value that specifies the storage file format. For more information, see the STGFMT enumeration.

grfAttrs [in]

A value that depends on the value of the stgfmt parameter.

Parameter ValuesMeaning
STGFMT_DOCFILE

0, or FILE_FLAG_NO_BUFFERING. For more information, see CreateFile. If the sector size of the file, specified in pStgOptions, is not an integer multiple of the underlying disk's physical sector size, this operation will fail.

All other values of stgfmt

Must be 0.

 

pStgOptions [in]

The pStgOptions parameter is valid only if the stgfmt parameter is set to STGFMT_DOCFILE. If the stgfmt parameter is set to STGFMT_DOCFILE, pStgOptions points to the STGOPTIONS structure, which specifies features of the storage object, such as the sector size. This parameter may be NULL, which creates a storage object with a default sector size of 512 bytes. If non-NULL, the ulSectorSize member must be set to either 512 or 4096. If set to 4096, STGM_SIMPLE may not be specified in the grfMode parameter. The usVersion member must be set before calling StgCreateStorageEx. For more information, see STGOPTIONS.

pSecurityDescriptor [in]

Enables the ACLs to be set when the file is created. If not NULL, needs to be a pointer to the SECURITY_ATTRIBUTES structure. See CreateFile for information on how to set ACLs on files.

Windows Server 2003, Windows 2000 Server, Windows XP, and Windows 2000 Professional:  Value must be NULL.

riid [in]

A value that specifies the interface identifier (IID) of the interface pointer to return. This IID may be for the IStorage interface or the IPropertySetStorage interface.

ppObjectOpen [out]

A pointer to an interface pointer variable that receives a pointer for an interface on the new storage object; contains NULL if operation failed.

Return value

S_OK

Indicates that the compound file was successfully created.

STG_E_INVALIDPOINTER

Indicates a non-valid pointer in the ppObjectOpen parameter.

STG_E_INVALIDPARAMETER

Indicates a non-valid value for the grfAttrs, reserved1, pSecurityDescriptor, grfMode, or stgfmt parameters. Can occur if the FILE_FLAG_NO_BUFFERING flag is specified for grfAttrs, but the sector size of the file is not an integer multiple of the underlying disk sector size.

STG_E_INVALIDFLAG

Indicates a non-valid flag combination in the grfMode pointer.

STG_E_INVALIDNAME

Indicates a non-valid name in the pwcsName parameter.

STG_E_FILEALREADYEXISTS

Indicates that the compound file already exists and grfMode is set to STGM_FAILIFTHERE.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_SHAREVIOLATION

Access denied because another caller has the file open and locked.

STG_E_NOTIMPL

Indicates that the StgCreateStorageEx function is not implemented by the operating system. In this case, use the StgCreateDocfile function.

STG_E_ACCESSDENIED

Indicates that the file could not be created because the underlying storage device does not allow such access to the current user. When opening the storage object in transacted mode (STGM_TRANSACTED), this error may also indicate that a temporary file could not be created in the temporary directory as specified by the GetTempPath function. The GetTempPath function retrieves the path of the directory designated for temporary files.

This function can also return any file system errors or system errors wrapped in an HRESULT. For more information, see Error Handling Strategies and Handling Unknown Errors.

Remarks

When an application modifies its file, it usually creates a copy of the original. The StgCreateStorageEx function is one way for creating a copy. This function works indirectly with the Encrypting File System (EFS) duplication API. When you use this function, you will need to set the options for the file storage in the STGOPTIONS structure.

StgCreateStorageEx is a superset of the StgCreateDocfile function, and should be used by new code. Future enhancements to Structured Storage will be exposed through the StgCreateStorageEx function. See the following Requirements section for information on supported platforms.

The StgCreateStorageEx function creates a new storage object using one of the system-provided, structured-storage implementations. This function can be used to obtain an IStorage compound file implementation, an IPropertySetStorage compound file implementation, or to obtain an IPropertySetStorage NTFS implementation.

When a new file is created, the storage implementation used depends on the flag that you specify and on the type of drive on which the file is stored. For more information, see the STGFMT enumeration.

StgCreateStorageEx creates the file if it does not exist. If it does exist, the use of the STGM_CREATE, STGM_CONVERT, and STGM_FAILIFTHERE flags in the grfMode parameter indicate how to proceed. For more information on these values, see STGM Constants. It is not valid, in direct mode, to specify the STGM_READ mode in the grfMode parameter (direct mode is indicated by not specifying the STGM_TRANSACTED flag). This function cannot be used to open an existing file; use the StgOpenStorageEx function instead.

You can use the StgCreateStorageEx function to get access to the root storage of a structured-storage document or the property set storage of any file that supports property sets. See the STGFMT documentation for information about which IIDs are supported for different STGFMT values.

When a file is created with this function to access the NTFS property set implementation, special sharing rules apply. For more information, see IPropertySetStorage-NTFS Implementation.

If a compound file is created in transacted mode (by specifying STGM_TRANSACTED) and read-only mode (by specifying STGM_READ), it is possible to make changes to the returned storage object. For example, it is possible to call IStorage::CreateStream. However, it is not possible to commit those changes by calling IStorage::Commit. Therefore, such changes will be lost.

Specifying STGM_SIMPLE provides a much faster implementation of a compound file object in a limited, but frequently used case involving applications that require a compound file implementation with multiple streams and no storages. For more information, see STGM Constants. It is not valid to specify that STGM_TRANSACTED if STGM_SIMPLE is specified.

The simple mode does not support all the methods on IStorage. Specifically, in simple mode, supported IStorage methods are CreateStream, Commit, and SetClass as well as the COM IUnknown methods of QueryInterface, AddRef and Release. In addition, SetElementTimes is supported with a NULL name, allowing applications to set times on a root storage. All the other methods of IStorage return STG_E_INVALIDFUNCTION.

If the grfMode parameter specifies STGM_TRANSACTED and no file yet exists with the name specified by the pwcsName parameter, the file is created immediately. In an access-controlled file system, the caller must have write permissions for the file system directory in which the compound file is created. If STGM_TRANSACTED is not specified, and STGM_CREATE is specified, an existing file with the same name is destroyed before creating the new file.

You can also use StgCreateStorageEx to create a temporary compound file by passing a NULL value for the pwcsName parameter. However, these files are temporary only in the sense that they have a unique system-provided name – one that is probably meaningless to the user. The caller is responsible for deleting the temporary file when finished with it, unless STGM_DELETEONRELEASE was specified for the grfMode parameter. For more information on these flags, see STGM Constants.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

StgCreateDocfile
StgCreateDocFileOnILockBytes
STGFMT
STGM Constants
StgOpenStorageEx
STGOPTIONS
CreateFile

 

 

Ajouts de la communauté

AJOUTER
Afficher:
© 2014 Microsoft