Interface IStorage
Call the methods of IStorage to manage substorages or streams within the current storage. This management includes creating, opening, or destroying substorages or streams, as well as managing aspects such as time stamps, names, and so forth.
Namespace: Syncfusion.CompoundFile.DocIO.Native
Assembly: Syncfusion.DocIO.Base.dll
Syntax
public interface IStorageMethods
Commit(UInt32)
The Commit method ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage.
Declaration
int Commit(uint grfCommitFlags)Parameters
| Type | Name | Description |
|---|---|---|
| System.UInt32 | grfCommitFlags | Controls how the changes are committed to the storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - Changes to the storage object were successfully committed to the parent level. If STGC_CONSOLIDATE was specified, the storage was successfully consolidated, or the storage was already too compact to consolidate further Otherwise error code. |
CopyTo(UInt32, IntPtr, IntPtr, IStorage)
The CopyTo method copies the entire contents of an open storage object to another storage object.
Declaration
int CopyTo(uint ciidExclude, IntPtr rgiidExclude, IntPtr snbExclude, IStorage pstgDest)Parameters
| Type | Name | Description |
|---|---|---|
| System.UInt32 | ciidExclude | The number of elements in the array pointed to by rgiidExclude. If rgiidExclude is NULL, then ciidExclude is ignored. |
| System.IntPtr | rgiidExclude | An array of interface identifiers (IIDs) that either the caller knows about and does not want copied or that the storage object does not support but whose state the caller will later explicitly copy. |
| System.IntPtr | snbExclude | A string name block (refer to SNB) that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL. |
| IStorage | pstgDest | Pointer to the open storage object into which this storage object is to be copied. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The storage object was successfully copied. E_PENDING - Asynchronous Storage only: Part or all of the data to be copied is currently unavailable. STG_E_ACCESSDENIED - The destination storage object is a child of the source storage object. STG_E_INSUFFICIENTMEMORY - The copy was not completed due to a lack of memory. Otherwise - Error code. |
CreateStorage(String, STGM, UInt32, UInt32, out IStorage)
The CreateStorage method creates and opens a new storage object nested within this storage object with the specified name in the specified access mode.
Declaration
int CreateStorage(string pwcsName, STGM grfMode, uint reserved1, uint reserved2, out IStorage ppstg)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | A pointer to a wide character null-terminated Unicode string that contains the name of the newly created storage object. The name can be used later to reopen the storage object. The name must not exceed 31 characters in length, not including the string terminator. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. |
| STGM | grfMode | A value that specifies the access mode to use when opening the newly created storage object. For more information and a description of possible values |
| System.UInt32 | reserved1 | Reserved for future use; must be zero. |
| System.UInt32 | reserved2 | Reserved for future use; must be zero. |
| IStorage | ppstg | A pointer, when successful, to the location of the IStorage pointer to the newly created storage object. This parameter is set to NULL if an error occurs. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The storage object was created successfully. E_PENDING - Asynchronous Storage only: Part or all of the necessary data is currently unavailable. STG_E_ACCESSDENIED - Not enough permissions to create storage object. STG_E_FILEALREADYEXISTS - The name specified for the storage object already exists in the storage object and the grfMode parameter includes the flag STGM_FAILIFTHERE. STG_E_INSUFFICIENTMEMORY - The storage object was not created due to a lack of memory. STG_E_INVALIDFLAG - The value specified for the grfMode parameter is not a valid STGM Constants value. STG_E_INVALIDFUNCTION - The specified combination of flags in the grfMode parameter is not supported. STG_E_INVALIDNAME - Not a valid value for pwcsName. STG_E_INVALIDPOINTER - The pointer specified for the storage object was not valid. STG_E_INVALIDPARAMETER - One of the parameters was not valid. STG_E_REVERTED - The storage object has been invalidated by a revert operation above it in the transaction tree. STG_E_TOOMANYOPENFILES - The storage object was not created because there are too many open files. STG_S_CONVERTED - The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. The new storage object will be added. |
CreateStream(String, STGM, UInt32, UInt32, ref IStream)
The CreateStream method creates and opens a stream object with the specified name contained in this storage object. All elements within a storage objects, both streams and other storage objects, are kept in the same name space.
Declaration
int CreateStream(string pwcsName, STGM grfMode, uint reserved1, uint reserved2, ref IStream ppstm)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | A pointer to a wide character null-terminated Unicode string that contains the name of the newly created stream. The name can be used later to open or reopen the stream. The name must not exceed 31 characters in length, not including the string terminator. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. |
| STGM | grfMode | Specifies the access mode to use when opening the newly created stream. For more information and descriptions of the possible values, see STGM Constants. |
| System.UInt32 | reserved1 | Reserved for future use; must be zero. |
| System.UInt32 | reserved2 | Reserved for future use; must be zero. |
| IStream | ppstm | On return, pointer to the location of the new IStream interface pointer. This is only valid if the operation is successful. When an error occurs, this parameter is set to NULL. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The new stream was successfully created. E_PENDING - Asynchronous Storage only: Part or all of the necessary data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage. STG_E_ACCESSDENIED - Not enough permissions to create stream. STG_E_FILEALREADYEXISTS - The name specified for the stream already exists in the storage object and the grfMode parameter includes the value STGM_FAILIFTHERE. STG_E_INSUFFICIENTMEMORY - The stream was not created due to a lack of memory. STG_E_INVALIDFLAG - The value specified for the grfMode parameter is not a valid STGM Constants value. STG_E_INVALIDFUNCTION - The specified combination of flags in the grfMode parameter is not supported; for example, when this method is called without the STGM_SHARE_EXCLUSIVE flag. STG_E_INVALIDNAME - Invalid value for pwcsName. STG_E_INVALIDPOINTER - The pointer specified for the stream object was invalid. STG_E_INVALIDPARAMETER - One of the parameters was invalid. STG_E_REVERTED - The storage object has been invalidated by a revert operation above it in the transaction tree. STG_E_TOOMANYOPENFILES - The stream was not created because there are too many open files. |
DestroyElement(String)
The DestroyElement method removes the specified storage or stream from this storage object.
Declaration
int DestroyElement(string pwcsName)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | Pointer to a wide character null-terminated Unicode string that contains the name of the storage or stream to be removed. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The element was successfully removed. Otherwise error code. |
EnumElements(UInt32, IntPtr, UInt32, ref IEnumSTATSTG)
The EnumElements method retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.
Declaration
int EnumElements(uint reserved1, IntPtr reserved2, uint reserved3, ref IEnumSTATSTG ppenum)Parameters
| Type | Name | Description |
|---|---|---|
| System.UInt32 | reserved1 | Reserved for future use; must be zero. |
| System.IntPtr | reserved2 | Reserved for future use; must be zero. |
| System.UInt32 | reserved3 | Reserved for future use; must be zero. |
| IEnumSTATSTG | ppenum | Pointer to IEnumSTATSTG* pointer variable that receives the interface pointer to the new enumerator object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The enumerator object was successfully returned. Otherwise error code. |
MoveElementTo(String, IStorage, String, UInt32)
The MoveElementTo method copies or moves a substorage or stream from this storage object to another storage object.
Declaration
int MoveElementTo(string pwcsName, IStorage pstgDest, string pwcsNewName, uint grfFlags)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | Pointer to a wide character null-terminated Unicode string that contains the name of the element in this storage object to be moved or copied. |
| IStorage | pstgDest | IStorage pointer to the destination storage object. |
| System.String | pwcsNewName | Pointer to a wide character null-terminated unicode string that contains the new name for the element in its new storage object. |
| System.UInt32 | grfFlags | Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy (STGMOVE_COPY). See the STGMOVE enumeration. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The storage object was successfully copied or moved. Otherwise error code. |
OpenStorage(String, IntPtr, STGM, IntPtr, UInt32, out IStorage)
The OpenStorage method opens an existing storage object with the specified name in the specified access mode.
Declaration
int OpenStorage(string pwcsName, IntPtr pstgPriority, STGM grfMode, IntPtr snbExclude, uint reserved, out IStorage ppstg)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | A pointer to a wide character null-terminated Unicode string that contains the name of the storage object to open. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. It is ignored if pstgPriority is non-NULL. |
| System.IntPtr | pstgPriority | Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER. |
| STGM | grfMode | Specifies the access mode to use when opening the storage object. For descriptions of the possible values, see STGM Constants. Other modes you choose must at least specify STGM_SHARE_EXCLUSIVE when calling this method. |
| System.IntPtr | snbExclude | Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER. |
| System.UInt32 | reserved | Reserved for future use; must be zero. |
| IStorage | ppstg | When successful, pointer to the location of an IStorage pointer to the opened storage object. This parameter is set to NULL if an error occurs. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The storage object was opened successfully. E_PENDING - Asynchronous Storage only: Part or all of the storage's data is currently unavailable. STG_E_ACCESSDENIED - Not enough permissions to open storage object. STG_E_FILENOTFOUND - The storage object with the specified name does not exist. STG_E_INSUFFICIENTMEMORY - The storage object was not opened due to a lack of memory. STG_E_INVALIDFLAG - The value specified for the grfMode parameter is not a valid STGM Constants value. STG_E_INVALIDFUNCTION - The specified combination of flags in the grfMode parameter is not supported. STG_E_INVALIDNAME - Not a valid value for pwcsName. STG_E_INVALIDPOINTER - The pointer specified for the storage object was not valid. STG_E_INVALIDPARAMETER - One of the parameters was not valid. STG_E_REVERTED - The storage object has been invalidated by a revert operation above it in the transaction tree. STG_E_TOOMANYOPENFILES - The storage object was not created because there are too many open files. STG_S_CONVERTED - The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. In direct mode, the new storage is immediately written to disk. In transacted mode, the new storage is written to a temporary storage in memory and later written to disk when it is committed. |
OpenStream(String, UInt32, STGM, UInt32, out IStream)
The OpenStream method opens an existing stream object within this storage object in the specified access mode.
Declaration
int OpenStream(string pwcsName, uint cbReserved1, STGM grfMode, uint reserved2, out IStream ppstm)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | A pointer to a wide character null-terminated Unicode string that contains the name of the stream to open. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. |
| System.UInt32 | cbReserved1 | Reserved for future use; must be NULL. |
| STGM | grfMode | Specifies the access mode to be assigned to the open stream. For more information and descriptions of possible values, see STGM Constants. Other modes you choose must at least specify STGM_SHARE_EXCLUSIVE when calling this method in the compound file implementation. |
| System.UInt32 | reserved2 | Reserved for future use; must be zero. |
| IStream | ppstm | A pointer to IStream pointer variable that receives the interface pointer to the newly opened stream object. If an error occurs, *ppstm must be set to NULL. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The stream was successfully opened. E_PENDING - Asynchronous Storage only: Part or all of the stream data is currently unavailable. STG_E_ACCESSDENIED - Not enough permissions to open stream. STG_E_FILENOTFOUND - The stream with specified name does not exist. STG_E_INSUFFICIENTMEMORY - The stream was not opened due to a lack of memory. STG_E_INVALIDFLAG - The value specified for the grfMode parameter is not a valid STGM Constants value. STG_E_INVALIDFUNCTION - The specified combination of flags in the grfMode parameter is not supported; for example, when this method is called without the STGM_SHARE_EXCLUSIVE flag. STG_E_INVALIDNAME - Invalid value for pwcsName. STG_E_INVALIDPOINTER - The pointer specified for the stream object was not valid. STG_E_INVALIDPARAMETER - One of the parameters was not valid. STG_E_REVERTED - The storage object has been invalidated by a revert operation above it in the transaction tree. STG_E_TOOMANYOPENFILES - The stream was not opened because there are too many open files. |
RenameElement(String, String)
The RenameElement method renames the specified substorage or stream in this storage object.
Declaration
int RenameElement(string pwcsOldName, string pwcsNewName)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsOldName | Pointer to a wide character null-terminated Unicode string that contains the name of the substorage or stream to be changed. |
| System.String | pwcsNewName | Pointer to a wide character null-terminated unicode string that contains the new name for the specified substorage or stream. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The element was successfully renamed. Otherwise error code. |
Revert()
The Revert method discards all changes that have been made to the storage object since the last commit operation.
Declaration
int Revert()Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The revert operation was successful. Otherwise error code. |
SetClass(ref Guid)
The SetClass method assigns the specified class identifier (CLSID) to this storage object.
Declaration
int SetClass(ref Guid clsid)Parameters
| Type | Name | Description |
|---|---|---|
| System.Guid | clsid | The CLSID that is to be associated with the storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The CLSID was successfully assigned. Otherwise error code. |
SetElementTimes(String, ref FILETIME, ref FILETIME, ref FILETIME)
The SetElementTimes method sets the modification, access, and creation times of the specified storage element, if the underlying file system supports this method.
Declaration
int SetElementTimes(string pwcsName, ref FILETIME pctime, ref FILETIME patime, ref FILETIME pmtime)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | The name of the storage object element whose times are to be modified. If NULL, the time is set on the root storage rather than one of its elements. |
| System.Runtime.InteropServices.ComTypes.FILETIME | pctime | Either the new creation time for the element or NULL if the creation time is not to be modified. |
| System.Runtime.InteropServices.ComTypes.FILETIME | patime | Either the new access time for the element or NULL if the access time is not to be modified. |
| System.Runtime.InteropServices.ComTypes.FILETIME | pmtime | Either the new modification time for the element or NULL if the modification time is not to be modified. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The time values were successfully set. Otherwise error code. |
SetStateBits(UInt32, UInt32)
The SetStateBits method stores up to 32 bits of state information in this storage object. This method is reserved for future use.
Declaration
int SetStateBits(uint grfStateBits, uint grfMask)Parameters
| Type | Name | Description |
|---|---|---|
| System.UInt32 | grfStateBits | Specifies the new values of the bits to set. No legal values are defined for these bits; they are all reserved for future use and must not be used by applications. |
| System.UInt32 | grfMask | A binary mask indicating which bits in grfStateBits are significant in this call. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The state information was successfully set. Otherwise error code. |
Stat(ref STATSTG, UInt32)
The Stat method retrieves the STATSTG structure for this open storage object.
Declaration
int Stat(ref STATSTG pstatstg, uint grfStatFlag)Parameters
| Type | Name | Description |
|---|---|---|
| STATSTG | pstatstg | On return, pointer to a STATSTG structure where this method places information about the open storage object. This parameter is NULL if an error occurs. |
| System.UInt32 | grfStatFlag | Specifies that some of the members in the STATSTG structure are not returned, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The STATSTG structure was successfully returned at the specified location. Otherwise error code. |