Class API
Class provide access to STG API functions.
Inheritance
Inherited Members
Namespace: Syncfusion.CompoundFile.DocIO.Native
Assembly: Syncfusion.DocIO.Base.dll
Syntax
[CLSCompliant(false)]
public sealed class APIMethods
CreateILockBytesOnHGlobal(IntPtr, Boolean, out ILockBytes)
The CreateILockBytesOnHGlobal function creates a byte array object, using global memory as the physical device, which is intended to be the compound file foundation.
Declaration
public static int CreateILockBytesOnHGlobal(IntPtr hGlobal, bool fDeleteOnRelease, out ILockBytes ppLkbyt)Parameters
| Type | Name | Description |
|---|---|---|
| System.IntPtr | hGlobal | The memory handle allocated by the GlobalAlloc function. |
| System.Boolean | fDeleteOnRelease | A flag that specifies whether the underlying handle for this byte array object should be automatically freed when the object is released. |
| ILockBytes | ppLkbyt | The address of ILockBytes pointer variable that receives the interface pointer to the new byte array object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The byte array object was created successfully. |
GlobalAlloc(API.GlobalAllocFlags, Int32)
The GlobalAlloc function allocates the specified number of bytes from the heap. Windows memory management does not provide a separate local heap and global heap.
Declaration
public static IntPtr GlobalAlloc(API.GlobalAllocFlags flags, int size)Parameters
| Type | Name | Description |
|---|---|---|
| API.GlobalAllocFlags | flags | Memory allocation attributes. |
| System.Int32 | size | Number of bytes to allocate. |
Returns
| Type | Description |
|---|---|
| System.IntPtr | If the function succeeds, the return value is a handle to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError. |
GlobalFree(IntPtr)
Declaration
public static IntPtr GlobalFree(IntPtr hMem)Parameters
| Type | Name | Description |
|---|---|---|
| System.IntPtr | hMem |
Returns
| Type |
|---|
| System.IntPtr |
GlobalReAlloc(IntPtr, Int32, API.GlobalAllocFlags)
Declaration
public static IntPtr GlobalReAlloc(IntPtr hMem, int bytes, API.GlobalAllocFlags flags)Parameters
| Type | Name | Description |
|---|---|---|
| System.IntPtr | hMem | |
| System.Int32 | bytes | |
| API.GlobalAllocFlags | flags |
Returns
| Type |
|---|
| System.IntPtr |
StgCreateDocfile(String, STGM, UInt32, out IStorage)
StgCreateDocfile creates a new compound file storage object using the COM-provided compound file implementation for the IStorage interface.
Declaration
public static int StgCreateDocfile(string pwcsName, STGM grfMode, uint reserved, out IStorage ppstgOpen)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | [in] Pointer to a NULL-terminated Unicode string name for the compound file being created. It is passed uninterpreted to the file system. This can be a relative name or NULL. If NULL, a temporary compound file is allocated with a unique name. |
| STGM | grfMode | [in] Specifies the access mode to use when opening the new storage object. For more information, see the STGM enumeration. 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. |
| System.UInt32 | reserved | [in] Reserved for future use; must be zero. |
| IStorage | ppstgOpen | [out] Pointer to the location of the IStorage pointer to the new storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - Indicates that the compound file was successfully created. STG_E_ACCESSDENIED - Access denied because the caller does not have enough permissions or another caller has the file open and locked. STG_E_FILEALREADYEXISTS Indicates that the compound file already exists and grfMode is set to STGM_FAILIFTHERE. STG_E_INSUFFICIENTMEMORY Indicates that the compound file was not created due to inadequate memory. STG_E_INVALIDFLAG Indicates a non-valid flag combination in the grfMode parameter. STG_E_INVALIDNAME Indicates a non-valid name in the pwcsName parameter. STG_E_INVALIDPOINTER Indicates a non-valid pointer in the pwcsName parameter or the ppStgOpen parameter. 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_TOOMANYOPENFILES Indicates that the compound file was not created due to a lack of file handles. STG_S_CONVERTED Indicates that the specified file was successfully converted to storage format. |
StgCreateDocfileOnILockBytes(ILockBytes, STGM, Int32, out IStorage)
The StgCreateDocfileOnILockBytes function creates and opens a new compound file storage object on top of a byte-array object provided by the caller.
Declaration
public static int StgCreateDocfileOnILockBytes(ILockBytes plkbyt, STGM grfMode, int reserved, out IStorage ppstgOpen)Parameters
| Type | Name | Description |
|---|---|---|
| ILockBytes | plkbyt | A pointer to the ILockBytes interface on the underlying byte-array object on which to create a compound file. |
| STGM | grfMode | Specifies the access mode to use when opening the new compound file. For more information, see STGM Constants. |
| System.Int32 | reserved | Reserved for future use; must be zero. |
| IStorage | ppstgOpen | A pointer to the location of the IStorage pointer on the new storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - Indicates that the compound file was successfully created. Otherwise error code. |
StgCreatePropSetStg(IStorage, UInt32, out IPropertySetStorage)
The StgCreatePropSetStg function creates a property set storage object from a specified storage object.
Declaration
public static int StgCreatePropSetStg(IStorage pStorage, uint dwReserved, out IPropertySetStorage ppPropSetStg)Parameters
| Type | Name | Description |
|---|---|---|
| IStorage | pStorage | Pointer to the storage object that contains or is to contain one or more property sets. |
| System.UInt32 | dwReserved | Reserved for future use; must be zero. |
| IPropertySetStorage | ppPropSetStg | Pointer to IPropertySetStorage* pointer variable that receives the interface pointer to the property-set storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The property set storage object was successfully created. |
StgCreatePropSetStgOle(IStorage, UInt32, out IPropertySetStorage)
The StgCreatePropSetStg function creates a property set storage object from a specified storage object.
Declaration
public static int StgCreatePropSetStgOle(IStorage pStorage, uint dwReserved, out IPropertySetStorage ppPropSetStg)Parameters
| Type | Name | Description |
|---|---|---|
| IStorage | pStorage | Pointer to the storage object that contains or is to contain one or more property sets. |
| System.UInt32 | dwReserved | Reserved for future use; must be zero. |
| IPropertySetStorage | ppPropSetStg | Pointer to IPropertySetStorage* pointer variable that receives the interface pointer to the property-set storage object. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The property set storage object was successfully created. |
StgOpenStorage(String, IntPtr, STGM, IntPtr, UInt32, out IStorage)
StgOpenStorage opens an existing root storage object in the file system. You can use this function to open compound files but you cannot use it to open directories, files, or summary catalogs. Nested storage objects can only be opened using their parents' IStorage::OpenStorage method.
Declaration
public static int StgOpenStorage(string wcsName, IntPtr stgPriority, STGM grfMode, IntPtr snbExclude, uint reserved, out IStorage storage)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | wcsName | [in] Pointer to the path of the NULL-terminated Unicode string file containing the storage object to open. This parameter is ignored if the pstgPriority parameter is not NULL. |
| System.IntPtr | stgPriority | Most often NULL. If not NULL, this parameter is used instead of the pwcsName parameter to specify the pointer to the IStorage interface on the storage object to open. It points to a previous opening of a root storage object, most often one that was opened in priority mode. After the StgOpenStorage function returns, the storage object specified in the pstgPriority parameter on function entry is not valid and can no longer be used. Instead, use the storage object specified in the ppStgOpen parameter. |
| STGM | grfMode | Specifies the access mode to use to open the storage object. |
| System.IntPtr | snbExclude | If not NULL, pointer to a block of elements in the storage that are to be excluded as the storage object is opened. The exclusion occurs regardless of whether a snapshot copy happens on the open. May be NULL. |
| System.UInt32 | reserved | Indicates reserved for future use; must be zero. |
| IStorage | storage | [out] Pointer IStorage* pointer variable that receives the interface pointer to the opened storage. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK Indicates that the storage object was successfully opened. STG_E_FILENOTFOUND Indicates that the specified file does not exist. STG_E_ACCESSDENIED Access denied because the caller does not have enough permissions, or another caller has the file open and locked. 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_FILEALREADYEXISTS Indicates that the file exists but is not a storage object. STG_E_TOOMANYOPENFILES Indicates that the storage object was not opened because there are too many open files. STG_E_INSUFFICIENTMEMORY Indicates that the storage object was not opened due to inadequate memory. STG_E_INVALIDNAME Indicates a non-valid name in the pwcsName parameter. STG_E_INVALIDPOINTER Indicates a non-valid pointer in one of the parameters: snbExclude, pwcsName, pstgPriority, or ppStgOpen. STG_E_INVALIDFLAG Indicates a non-valid flag combination in the grfMode parameter. STG_E_INVALIDFUNCTION Indicates STGM_DELETEONRELEASE specified in the grfMode parameter. STG_E_OLDFORMAT Indicates that the storage object being opened was created by the Beta 1 storage provider. This format is no longer supported. STG_E_NOTSIMPLEFORMAT Indicates that the STGM_SIMPLE flag was specified in the grfMode parameter and the storage object being opened was not written in simple mode. STG_E_OLDDLL The DLL being used to open this storage object is a version of the DLL that is older than the one used to create it. STG_E_PATHNOTFOUND Specified path does not exist. STG_E_SHAREVIOLATION Access denied because another caller has the file open and locked. |
StgOpenStorageEx(String, STGM, STGFMT, UInt32, IntPtr, IntPtr, ref Guid, out IStorage)
Opens an existing root storage object in the file system. You can use this function to open compound files and regular files. To create a new file, use the StgCreateStorageEx function.
Declaration
public static int StgOpenStorageEx(string pwcsName, STGM grfMode, STGFMT stgfmt, uint grfAttrs, IntPtr stgOptions, IntPtr reserved2, ref Guid riid, out IStorage ppObjectOpen)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | pwcsName | [in] Pointer to the path of the NULL-terminated Unicode string file containing the storage object. This string size must not exceed MAX_PATH characters. |
| STGM | grfMode | [in] Specifies the access mode to open the new storage object. For more information, see the STGM enumeration. 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 | stgfmt | [in] Specifies the storage file format. For more information, see the STGFMT enumeration. |
| System.UInt32 | grfAttrs | [in] Depends on the value of the stgfmt parameter. STGFMT_DOCFILE should be zero (0) or FILE_FLAG_NO_BUFFERING. |
| System.IntPtr | stgOptions | [in, out] Pointer to a STGOPTIONS structure that contains information about the storage object being opened. The pStgOptions parameter is valid only if the stgfmt parameter is set to STGFMT_DOCFILE. |
| System.IntPtr | reserved2 | [in] Reserved for future use; must be zero. |
| System.Guid | riid | [in] Specifies the Guid of the interface pointer to return. |
| IStorage | ppObjectOpen | [out] Address of an interface pointer variable that receives a pointer for an interface on the storage object being opened; contains NULL if operation failed. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK Indicates that the storage object was successfully opened. STG_E_INVALIDPOINTER Indicates a non-valid pointer in the ppObjectOpen parameter. STG_E_INVALIDPARAMETER Indicates a non-valid value for the grfAttrs, reserved1, reserved2, 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's sector size. E_NOINTERFACE Indicates that the specified interface is not supported. STG_E_INVALIDFLAG Indicates a non-valid flag combination in the grfMode pointer (includes both STGM_DELETEONRELEASE and STGM_CONVERT flags). STG_E_INVALIDNAME Indicates a non-valid name in the pwcsName parameter. STG_E_INVALIDFUNCTION Indicates that the grfMode is set to STGM_DELETEONRELEASE. 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_UNIMPLEMENTEDFUNCTION Indicates that the StgOpenStorageEx function is not implemented by the operating system. In this case, use the StgOpenStorage function instead. STG_E_INCOMPLETE Indicates that the file could not be opened because it is on a high-latency device. This can only occur if the parameter is IID_IPropertySetStorage, and the stgfmt parameter is STGFMT_FILE. STG_E_ACCESSDENIED Indicates that the file could not be opened 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. |
StgOpenStorageOnILockBytes(ILockBytes, IStorage, STGM, Int32, Int32, out IStorage)
The StgOpenStorageOnILockBytes function opens an existing storage object that does not reside in a disk file, but instead has an underlying byte array provided by the caller.
Declaration
public static int StgOpenStorageOnILockBytes(ILockBytes plkbyt, IStorage pStgPriority, STGM grfMode, int snbExclude, int reserved, out IStorage ppstgOpen)Parameters
| Type | Name | Description |
|---|---|---|
| ILockBytes | plkbyt | ILockBytes pointer to the underlying byte array object that contains the storage object to be opened. |
| IStorage | pStgPriority | Most often NULL. If not NULL, this parameter is used instead of the plkbyt parameter to specify the storage object to open. In this case, it points to the IStorage interface on a previously opened root storage object, most often one that was opened in priority mode. |
| STGM | grfMode | Specifies the access mode to use to open the storage object. |
| System.Int32 | snbExclude | Can be NULL. If not NULL, this parameter points to a block of elements in this storage that are to be excluded as the storage object is opened. This exclusion occurs independently of whether a snapshot copy happens on the open. |
| System.Int32 | reserved | Indicates reserved for future use; must be zero. |
| IStorage | ppstgOpen | Points to the location of an IStorage pointer to the opened storage on successful return. |
Returns
| Type | Description |
|---|---|
| System.Int32 | S_OK - The storage object was successfully opened. Otherwise error code. |