|
// ------------------------------------------------------------------------------
// <auto-generated>
// This code was generated by a tool.
//
// Changes to this file may cause incorrect behavior and will be lost if
// the code is regenerated.
// </auto-generated>
// ------------------------------------------------------------------------------
#pragma warning disable CS1591,CS1573,CS0465,CS0649,CS8019,CS1570,CS1584,CS1658,CS0436,CS8981
using global::System;
using global::System.Diagnostics;
using global::System.Diagnostics.CodeAnalysis;
using global::System.Runtime.CompilerServices;
using global::System.Runtime.InteropServices;
using global::System.Runtime.Versioning;
using winmdroot = global::Windows.Win32;
namespace Windows.Win32
{
/// <content>
/// Contains extern methods from "OLE32.dll".
/// </content>
internal static partial class PInvoke
{
/// <inheritdoc cref="CoGetClassObject(global::System.Guid*, winmdroot.System.Com.CLSCTX, void*, global::System.Guid*, void**)"/>
[SupportedOSPlatform("windows5.0")]
internal static unsafe winmdroot.Foundation.HRESULT CoGetClassObject(in global::System.Guid rclsid, winmdroot.System.Com.CLSCTX dwClsContext, void* pvReserved, in global::System.Guid riid, out void* ppv)
{
fixed (void** ppvLocal = &ppv)
{
fixed (global::System.Guid* riidLocal = &riid)
{
fixed (global::System.Guid* rclsidLocal = &rclsid)
{
winmdroot.Foundation.HRESULT __result = PInvoke.CoGetClassObject(rclsidLocal, dwClsContext, pvReserved, riidLocal, ppvLocal);
return __result;
}
}
}
}
/// <summary>Provides a pointer to an interface on a class object associated with a specified CLSID.</summary>
/// <param name="rclsid">The CLSID associated with the data and code that you will use to create the objects.</param>
/// <param name="dwClsContext">The context in which the executable code is to be run. To enable a remote activation, include CLSCTX_REMOTE_SERVER. For more information on the context values and their use, see the <a href="https://docs.microsoft.com/windows/desktop/api/wtypesbase/ne-wtypesbase-clsctx">CLSCTX</a> enumeration.</param>
/// <param name="pvReserved">A pointer to computer on which to instantiate the class object. If this parameter is <b>NULL</b>, the class object is instantiated on the current computer or at the computer specified under the class's <a href="https://docs.microsoft.com/windows/desktop/com/remoteservername">RemoteServerName</a> key, according to the interpretation of the <i>dwClsCtx</i> parameter. See <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ns-objidl-coserverinfo">COSERVERINFO</a>.</param>
/// <param name="riid">Reference to the identifier of the interface, which will be supplied in _ppv_ on successful return. This interface will be used to communicate with the class object. Typically this value is IID_IClassFactory, although other values such as IID_IClassFactory2 which supports a form of licensing are allowed. All OLE-defined interface IIDs are defined in the OLE header files as IID_interfacename, where interfacename is the name of the interface.</param>
/// <param name="ppv">The address of pointer variable that receives the interface pointer requested in <i>riid</i>. Upon successful return, *<i>ppv</i> contains the requested interface pointer.</param>
/// <returns>
/// <para>This function can return the following values. </para>
/// <para>This doc was truncated.</para>
/// </returns>
/// <remarks>
/// <para>A class object in OLE is an intermediate object that supports an interface that permits operations common to a group of objects. The objects in this group are instances derived from the same object definition represented by a single CLSID. Usually, the interface implemented on a class object is <a href="https://docs.microsoft.com/windows/desktop/com/implementing-iclassfactory">IClassFactory</a>, through which you can create object instances of a given definition (class).</para>
/// <para>A call to <b>CoGetClassObject</b> creates, initializes, and gives the caller access (through a pointer to an interface specified with the <i>riid</i> parameter) to the class object. The class object is the one associated with the CLSID that you specify in the <i>rclsid</i> parameter. The details of how the system locates the associated code and data within a computer are transparent to the caller, as is the dynamic loading of any code that is not already loaded.</para>
/// <para>If the class context is CLSCTX_REMOTE_SERVER, indicating remote activation is required, the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ns-objidl-coserverinfo">COSERVERINFO</a> structure provided in the <i>pServerInfo</i> parameter allows you to specify the computer on which the server is located. For information on the algorithm used to locate a remote server when <i>pServerInfo</i> is <b>NULL</b>, refer to the <a href="https://docs.microsoft.com/windows/desktop/api/wtypesbase/ne-wtypesbase-clsctx">CLSCTX</a> enumeration.</para>
/// <para>There are two places to find a CLSID for a class: </para>
/// <para>This doc was truncated.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-cogetclassobject#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[SupportedOSPlatform("windows5.0")]
internal static unsafe winmdroot.Foundation.HRESULT CoGetClassObject(global::System.Guid* rclsid, winmdroot.System.Com.CLSCTX dwClsContext, [Optional] void* pvReserved, global::System.Guid* riid, void** ppv)
{
winmdroot.Foundation.HRESULT __retVal = LocalExternFunction(rclsid, (uint)dwClsContext, pvReserved, riid, ppv);
return __retVal;
[DllImport("OLE32.dll", ExactSpelling = true, EntryPoint = "CoGetClassObject"),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
static extern unsafe winmdroot.Foundation.HRESULT LocalExternFunction(global::System.Guid* rclsid, uint dwClsContext, [Optional] void* pvReserved, global::System.Guid* riid, void** ppv);
}
/// <summary>Registers with OLE the instance of an IMessageFilter interface, which is to be used for handling concurrency issues on the current thread.</summary>
/// <param name="lpMessageFilter">
/// <para>A pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-imessagefilter">IMessageFilter</a> interface on the message filter. This message filter should be registered on the current thread, replacing the previous message filter (if any). This parameter can be <b>NULL</b>, indicating that no message filter should be registered on the current thread. Note that this function calls <a href="https://docs.microsoft.com/windows/desktop/api/unknwn/nf-unknwn-iunknown-addref">AddRef</a> on the interface pointer to the message filter.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/objbase/nf-objbase-coregistermessagefilter#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <param name="lplpMessageFilter">Address of the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-imessagefilter">IMessageFilter</a>* pointer variable that receives the interface pointer to the previously registered message filter. If there was no previously registered message filter for the current thread, the value of *<i>lplpMessageFilter</i> is <b>NULL</b>.</param>
/// <returns>If the instance was registered or revoked successfully, the return value is S_OK; otherwise, it is S_FALSE.</returns>
/// <remarks>To revoke the registered message filter, pass the previous message filter (possibly <b>NULL</b>) as the <i>lpMessageFilter</i> parameter to <b>CoRegisterMessageFilter</b>.</remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT CoRegisterMessageFilter([Optional] winmdroot.Media.Audio.IMessageFilter* lpMessageFilter, [Optional] winmdroot.Media.Audio.IMessageFilter** lplpMessageFilter);
/// <summary>Creates a byte array object that uses an HGLOBAL memory handle to store the bytes intended for in-memory storage of a compound file.</summary>
/// <param name="hGlobal">A memory handle allocated by the <a href="https://docs.microsoft.com/windows/desktop/api/winbase/nf-winbase-globalalloc">GlobalAlloc</a> function, or if <b>NULL</b> a new handle is to be allocated instead. The handle must be allocated as moveable and nondiscardable.</param>
/// <param name="fDeleteOnRelease">A flag that specifies whether the underlying handle for this byte array object should be automatically freed when the object is released. If set to <b>FALSE</b>, the caller must free the <i>hGlobal</i> after the final release. If set to <b>TRUE</b>, the final release will automatically free the <i>hGlobal</i> parameter.</param>
/// <param name="pplkbyt">
/// <para>The address of <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> pointer variable that receives the interface pointer to the new byte array object.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-createilockbytesonhglobal#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <returns>This function supports the standard return values <b>E_INVALIDARG</b> and <b>E_OUTOFMEMORY</b>, as well as the following:</returns>
/// <remarks>
/// <para>If <i>hGlobal</i> is <b>NULL</b>, the <b>CreateILockBytesOnHGlobal</b> allocates a new memory handle and the byte array is empty initially. If <i>hGlobal</i> is not <b>NULL</b>, the initial contents of the byte array object are the current contents of the memory block. Thus, this function can be used to open an existing byte array in memory, for example to reload a storage object previously created by the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes">StgCreateDocfileOnILockBytes</a> function. The memory handle and its contents are undisturbed by the creation of the new byte array object. The initial size of the byte array is the size of <i>hGlobal</i> as returned by the <a href="https://docs.microsoft.com/windows/desktop/api/winbase/nf-winbase-globalsize">GlobalSize</a> function. This is not necessarily the same size that was originally allocated for the handle because of rounding. If the logical size of the byte array is important, follow the call to <b>CreateILockBytesOnHGlobal</b> with a call to <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-ilockbytes-setsize">ILockBytes::SetSize</a>. After creating the byte array object with <a href="https://docs.microsoft.com/windows/desktop/api/combaseapi/nf-combaseapi-createstreamonhglobal">CreateStreamOnHGlobal</a>, <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes">StgCreateDocfileOnILockBytes</a> can be used to create a new storage object in memory, or <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgopenstorageonilockbytes">StgOpenStorageOnILockBytes</a> can be used to reopen a previously existing storage object that is already contained in the memory block. <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-gethglobalfromilockbytes">GetHGlobalFromILockBytes</a> can be called to retrieve the memory handle associated with the byte array object. If a memory handle is passed to <b>CreateILockBytesOnHGlobal</b> or if <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-gethglobalfromilockbytes">GetHGlobalFromILockBytes</a> is called, the memory handle of this function can be directly accessed by the caller while it is still in use by the byte array object. Appropriate caution should be exercised in the use of this capability and its implications: </para>
/// <para>This doc was truncated.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-createilockbytesonhglobal#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT CreateILockBytesOnHGlobal(winmdroot.Foundation.HGLOBAL hGlobal, winmdroot.Foundation.BOOL fDeleteOnRelease, winmdroot.System.Com.StructuredStorage.ILockBytes** pplkbyt);
/// <summary>Creates an advise holder object for managing compound document notifications. It returns a pointer to the object's OLE implementation of the IOleAdviseHolder interface.</summary>
/// <param name="ppOAHolder">Address of <a href="https://docs.microsoft.com/windows/desktop/api/oleidl/nn-oleidl-ioleadviseholder">IOleAdviseHolder</a> pointer variable that receives the interface pointer to the new advise holder object.</param>
/// <returns>This function returns S_OK on success and supports the standard return value E_OUTOFMEMORY.</returns>
/// <remarks>The function <b>CreateOleAdviseHolder</b> creates an instance of an advise holder, which supports the OLE implementation of the <a href="https://docs.microsoft.com/windows/desktop/api/oleidl/nn-oleidl-ioleadviseholder">IOleAdviseHolder</a> interface. The methods of this interface are intended to be used to implement the advisory methods of <a href="https://docs.microsoft.com/windows/desktop/api/oleidl/nn-oleidl-ioleobject">IOleObject</a>, and, when advisory connections have been set up with objects supporting an advisory sink, to send notifications of changes in the object to the advisory sink. The advise holder returned by <b>CreateOleAdviseHolder</b> will suffice for the great majority of applications. The OLE-provided implementation does not, however, support <a href="https://docs.microsoft.com/windows/desktop/api/oleidl/nf-oleidl-ioleadviseholder-enumadvise">IOleAdviseHolder::EnumAdvise</a>, so if you need to use this method, you will need to implement your own advise holder.</remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT CreateOleAdviseHolder(winmdroot.System.Ole.IOleAdviseHolder** ppOAHolder);
/// <summary>The GetHGlobalFromILockBytes function retrieves a global memory handle to a byte array object created using the CreateILockBytesOnHGlobal function.</summary>
/// <param name="plkbyt">
/// <para>Pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> interface on the byte-array object previously created by a call to the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-createilockbytesonhglobal">CreateILockBytesOnHGlobal</a> function.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-gethglobalfromilockbytes#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <param name="phglobal">Pointer to the current memory handle used by the specified byte-array object.</param>
/// <returns>This function returns HRESULT.</returns>
/// <remarks>
/// <para>After a call to <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-createilockbytesonhglobal">CreateILockBytesOnHGlobal</a>, which creates a byte array object on global memory, <b>GetHGlobalFromILockBytes</b> retrieves a pointer to the handle of the global memory underlying the byte array object. The handle this function returns might be different from the original handle due to intervening calls to the <a href="https://docs.microsoft.com/windows/desktop/api/winbase/nf-winbase-globalrealloc">GlobalReAlloc</a> function. The contents of the returned memory handle can be written to a clean disk file, and then opened as a storage object using the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgopenstorage">StgOpenStorage</a> function. This function only works within the same process from which the byte array was created.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-gethglobalfromilockbytes#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT GetHGlobalFromILockBytes(winmdroot.System.Com.StructuredStorage.ILockBytes* plkbyt, winmdroot.Foundation.HGLOBAL* phglobal);
/// <inheritdoc cref="IsAccelerator(winmdroot.UI.WindowsAndMessaging.HACCEL, int, winmdroot.UI.WindowsAndMessaging.MSG*, ushort*)"/>
[SupportedOSPlatform("windows5.0")]
internal static unsafe winmdroot.Foundation.BOOL IsAccelerator(winmdroot.UI.WindowsAndMessaging.HACCEL hAccel, int cAccelEntries, in winmdroot.UI.WindowsAndMessaging.MSG lpMsg, out ushort lpwCmd)
{
fixed (ushort* lpwCmdLocal = &lpwCmd)
{
fixed (winmdroot.UI.WindowsAndMessaging.MSG* lpMsgLocal = &lpMsg)
{
winmdroot.Foundation.BOOL __result = PInvoke.IsAccelerator(hAccel, cAccelEntries, lpMsgLocal, lpwCmdLocal);
return __result;
}
}
}
/// <summary>Determines whether the specified keystroke maps to an accelerator in the specified accelerator table.</summary>
/// <param name="hAccel">A handle to the accelerator table.</param>
/// <param name="cAccelEntries">The number of entries in the accelerator table.</param>
/// <param name="lpMsg">A pointer to the keystroke message to be translated.</param>
/// <param name="lpwCmd">A pointer to a variable to receive the corresponding command identifier if there is an accelerator for the keystroke. This parameter may be <b>NULL</b>.</param>
/// <returns>If the message is for the object application, the return value is <b>TRUE</b>. If the message is not for the object and should be forwarded to the container, the return value is <b>FALSE</b>.</returns>
/// <remarks>
/// <para>While an object is active in-place, the object always has first chance to translate the keystrokes into accelerators. If the keystroke corresponds to one of its accelerators, the object must not call the <a href="https://docs.microsoft.com/windows/desktop/api/ole2/nf-ole2-oletranslateaccelerator">OleTranslateAccelerator</a> function - even if its call to the <a href="https://docs.microsoft.com/windows/desktop/DirectShow/cbasepropertypage-translateaccelerator">TranslateAccelerator</a> function fails. Failure to process keystrokes in this manner can lead to inconsistent behavior. If the keystroke is not one of the object's accelerators, then the object must call <a href="https://docs.microsoft.com/windows/desktop/api/ole2/nf-ole2-oletranslateaccelerator">OleTranslateAccelerator</a> to let the container try its accelerator translation. The object's server can call <b>IsAccelerator</b> to determine if the accelerator message belongs to it. Some servers do accelerator translation on their own and do not call <a href="https://docs.microsoft.com/windows/desktop/DirectShow/cbasepropertypage-translateaccelerator">TranslateAccelerator</a>. Those applications will not call <b>IsAccelerator</b>, because they already have the information.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/ole2/nf-ole2-isaccelerator#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.BOOL IsAccelerator(winmdroot.UI.WindowsAndMessaging.HACCEL hAccel, int cAccelEntries, winmdroot.UI.WindowsAndMessaging.MSG* lpMsg, ushort* lpwCmd);
/// <inheritdoc cref="ReadClassStg(winmdroot.System.Com.StructuredStorage.IStorage*, global::System.Guid*)"/>
[SupportedOSPlatform("windows5.0")]
internal static unsafe winmdroot.Foundation.HRESULT ReadClassStg(winmdroot.System.Com.StructuredStorage.IStorage* pStg, out global::System.Guid pclsid)
{
fixed (global::System.Guid* pclsidLocal = &pclsid)
{
winmdroot.Foundation.HRESULT __result = PInvoke.ReadClassStg(pStg, pclsidLocal);
return __result;
}
}
/// <summary>The ReadClassStg function reads the CLSID previously written to a storage object with the WriteClassStg function.</summary>
/// <param name="pStg">
/// <para>Pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> interface on the storage object containing the CLSID to be retrieved.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-readclassstg#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <param name="pclsid">Pointer to where the CLSID is written. May return CLSID_NULL.</param>
/// <returns>
/// <para>This function supports the standard return value E_OUTOFMEMORY, in addition to the following: This function also returns any of the error values returned by the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-istorage-stat">IStorage::Stat</a> method.</para>
/// </returns>
/// <remarks>
/// <para><b>ReadClassStg</b> is a helper function that calls the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-istorage-stat">IStorage::Stat</a> method and retrieves the CLSID previously written to the storage object with a call to <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-writeclassstg">WriteClassStg</a> from the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ns-objidl-statstg">STATSTG</a> structure.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-readclassstg#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT ReadClassStg(winmdroot.System.Com.StructuredStorage.IStorage* pStg, global::System.Guid* pclsid);
/// <summary>Creates and opens a new compound file storage object on top of a byte-array object provided by the caller.</summary>
/// <param name="plkbyt">
/// <para>A pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> interface on the underlying byte-array object on which to create a compound file.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <param name="grfMode">Specifies the access mode to use when opening the new compound file. For more information, see <a href="https://docs.microsoft.com/windows/desktop/Stg/stgm-constants">STGM Constants</a> and the Remarks section below.</param>
/// <param name="reserved">Reserved for future use; must be zero.</param>
/// <param name="ppstgOpen">
/// <para>A pointer to the location of the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> pointer on the new storage object.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <returns>
/// <para>The <b>StgCreateDocfileOnILockBytes</b> function can also return any file system errors, or system errors wrapped in an <b>HRESULT</b>, or <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> interface error return values. For more information, see <a href="https://docs.microsoft.com/windows/desktop/com/error-handling-strategies">Error Handling Strategies</a> and <a href="https://docs.microsoft.com/windows/desktop/com/handling-unknown-errors">Handling Unknown Errors</a>.</para>
/// </returns>
/// <remarks>
/// <para>The <b>StgCreateDocfileOnILockBytes</b> function creates a storage object on top of a byte array object using the COM-provided, compound-file implementation of the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> interface. <b>StgCreateDocfileOnILockBytes</b> can be used to store a document in an arbitrary data store, such as memory or a relational database. The byte array (indicated by the <i>pLkbyt</i> parameter, which points to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> interface on the object) is used for the underlying storage in place of a disk file. Except for specifying a programmer-provided byte-array object, <b>StgCreateDocfileOnILockBytes</b> is similar to the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgcreatedocfile">StgCreateDocfile</a> function. The newly created compound file is opened according to the access modes in the <i>grfMode</i> parameter, subject to the following restrictions: Sharing mode behavior and transactional isolation depend on the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> implementation supporting <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-ilockbytes-lockregion">LockRegion</a> and <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-ilockbytes-unlockregion">UnlockRegion</a> with <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ne-objidl-locktype">LOCK_ONLYONCE</a> semantics. Implementations can indicate to structured storage they support this functionality by setting the <b>LOCK_ONLYONCE</b> bit in the <b>grfLocksSupported</b> member of <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ns-objidl-statstg">STATSTG</a>. If an <b>ILockBytes</b> implementation does not support this functionality, sharing modes will not be enforced, and root-level transactional commits will not coordinate properly with other transactional instances opened on the same byte array. Applications that use an <b>ILockBytes</b> implementation that does not support region locking, such as the <a href="https://docs.microsoft.com/windows/desktop/api/combaseapi/nf-combaseapi-createstreamonhglobal">CreateStreamOnHGlobal</a> implementation, should avoid opening multiple concurrent instances on the same byte array. <b>StgCreateDocfileOnILockBytes</b> does not support simple mode. The <a href="https://docs.microsoft.com/windows/desktop/Stg/stgm-constants">STGM_SIMPLE</a> flag, if present, is ignored. For conversion purposes, the file is considered to already exist. As a result, it is not useful to use the <a href="https://docs.microsoft.com/windows/desktop/Stg/stgm-constants">STGM_FAILIFTHERE</a> value, because it causes an error to be returned. However, both STGM_CREATE and STGM_CONVERT remain useful. The ability to build a compound file on top of a byte-array object is provided to support having the data (underneath an <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> and <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istream">IStream</a> tree structure) live in a nonpersistent space. Given this capability, there is nothing preventing a document that is stored in a file from using this facility. For example, a container might do this to minimize the impact on its file format caused by adopting COM. However, it is recommended that COM documents adopt the <b>IStorage</b> interface for their own outer-level storage. This has the following advantages: </para>
/// <para>This doc was truncated.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT StgCreateDocfileOnILockBytes(winmdroot.System.Com.StructuredStorage.ILockBytes* plkbyt, winmdroot.System.Com.STGM grfMode, uint reserved, winmdroot.System.Com.StructuredStorage.IStorage** ppstgOpen);
/// <inheritdoc cref="StgOpenStorageOnILockBytes(winmdroot.System.Com.StructuredStorage.ILockBytes*, winmdroot.System.Com.StructuredStorage.IStorage*, winmdroot.System.Com.STGM, ushort**, uint, winmdroot.System.Com.StructuredStorage.IStorage**)"/>
[SupportedOSPlatform("windows5.0")]
internal static unsafe winmdroot.Foundation.HRESULT StgOpenStorageOnILockBytes(winmdroot.System.Com.StructuredStorage.ILockBytes* plkbyt, winmdroot.System.Com.StructuredStorage.IStorage* pstgPriority, winmdroot.System.Com.STGM grfMode, ushort** snbExclude, winmdroot.System.Com.StructuredStorage.IStorage** ppstgOpen)
{
winmdroot.Foundation.HRESULT __result = PInvoke.StgOpenStorageOnILockBytes(plkbyt, pstgPriority, grfMode, snbExclude, default, ppstgOpen);
return __result;
}
/// <summary>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.</summary>
/// <param name="plkbyt"><a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> pointer to the underlying byte array object that contains the storage object to be opened.</param>
/// <param name="pstgPriority">
/// <para>A pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> interface that should be <b>NULL</b>. If not <b>NULL</b>, this parameter is used as described below in the Remarks section. After <b>StgOpenStorageOnILockBytes</b> returns, the storage object specified in <i>pStgPriority</i> may have been released and should no longer be used.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgopenstorageonilockbytes#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <param name="grfMode">Specifies the access mode to use to open the storage object. For more information, see <a href="https://docs.microsoft.com/windows/desktop/Stg/stgm-constants">STGM Constants</a> and the Remarks section below.</param>
/// <param name="snbExclude">Can be <b>NULL</b>. If not <b>NULL</b>, 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.</param>
/// <param name="reserved">Indicates reserved for future use; must be zero.</param>
/// <param name="ppstgOpen">
/// <para>Points to the location of an <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> pointer to the opened storage on successful return.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgopenstorageonilockbytes#parameters">Read more on docs.microsoft.com</see>.</para>
/// </param>
/// <returns>
/// <para>The <b>StgOpenStorageOnILockBytes</b> function can also return any file system errors, or system errors wrapped in an <b>HRESULT</b>, or <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> interface error return values. See <a href="https://docs.microsoft.com/windows/desktop/com/error-handling-strategies">Error Handling Strategies</a> and <a href="https://docs.microsoft.com/windows/desktop/com/handling-unknown-errors">Handling Unknown Errors</a>.</para>
/// </returns>
/// <remarks>
/// <para><b>StgOpenStorageOnILockBytes</b> opens the specified root storage object. A pointer to the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-istorage">IStorage</a> interface on the opened storage object is supplied through the <i>ppstgOpen</i> parameter. The storage object must have been previously created by the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgcreatedocfileonilockbytes">StgCreateDocfileOnILockBytes</a> function. Except for specifying a programmer-provided byte-array object, <b>StgOpenStorageOnILockBytes</b> is similar to the <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgopenstorage">StgOpenStorage</a> function. The storage object is opened according to the access modes in the <i>grfMode</i> parameter, subject to the following restrictions: Sharing mode behavior and transactional isolation depend on the <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nn-objidl-ilockbytes">ILockBytes</a> implementation supporting <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-ilockbytes-lockregion">LockRegion</a> and <a href="https://docs.microsoft.com/windows/desktop/api/objidl/nf-objidl-ilockbytes-unlockregion">UnlockRegion</a> with <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ne-objidl-locktype">LOCK_ONLYONCE</a> semantics. Implementations can indicate to structured storage they support this functionality by setting the <b>LOCK_ONLYONCE</b> bit in the <b>grfLocksSupported</b> member of <a href="https://docs.microsoft.com/windows/desktop/api/objidl/ns-objidl-statstg">STATSTG</a>. If an <b>ILockBytes</b> implementation does not support this functionality, sharing modes will not be enforced, and root-level transactional commits will not coordinate properly with other transactional instances opened on the same byte array. Applications that use an <b>ILockBytes</b> implementation that does not support region locking, such as the <a href="https://docs.microsoft.com/windows/desktop/api/combaseapi/nf-combaseapi-createstreamonhglobal">CreateStreamOnHGlobal</a> implementation, should avoid opening multiple concurrent instances on the same byte array. <b>StgOpenStorageOnILockBytes</b> does not support simple mode. The <a href="https://docs.microsoft.com/windows/desktop/Stg/stgm-constants">STGM_SIMPLE</a> flag, if present, is ignored. The <i>pStgPriority</i> parameter is intended as a convenience for callers replacing an existing storage object, often one opened in priority mode, with a new storage object opened on the same byte array. Unlike the <i>pStgPriority</i> parameter of <a href="https://docs.microsoft.com/windows/desktop/api/coml2api/nf-coml2api-stgopenstorage">StgOpenStorage</a>, this parameter does not affect the open operation performed by <b>StgOpenStorageOnILockBytes</b> and is simply an existing storage object the caller would like released. Callers should always pass <b>NULL</b> for this parameter because <b>StgOpenStorageOnILockBytes</b> releases the object under some circumstances, and does not release it under other circumstances. The use of the <i>pStgPriority</i> parameter can be duplicated by the caller in a safer manner by instead releasing the object before calling <b>StgOpenStorageOnILockBytes</b>, as shown in the following example:</para>
/// <para></para>
/// <para>This doc was truncated.</para>
/// <para><see href="https://learn.microsoft.com/windows/win32/api/coml2api/nf-coml2api-stgopenstorageonilockbytes#">Read more on docs.microsoft.com</see>.</para>
/// </remarks>
[DllImport("OLE32.dll", ExactSpelling = true),DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[SupportedOSPlatform("windows5.0")]
internal static extern unsafe winmdroot.Foundation.HRESULT StgOpenStorageOnILockBytes(winmdroot.System.Com.StructuredStorage.ILockBytes* plkbyt, [Optional] winmdroot.System.Com.StructuredStorage.IStorage* pstgPriority, winmdroot.System.Com.STGM grfMode, [Optional] ushort** snbExclude, uint reserved, winmdroot.System.Com.StructuredStorage.IStorage** ppstgOpen);
}
}
|