diff --git a/PInvoke/Ole/Ole32/ObjIdl.cs b/PInvoke/Ole/Ole32/ObjIdl.cs index 0869d2a7..f9c137ee 100644 --- a/PInvoke/Ole/Ole32/ObjIdl.cs +++ b/PInvoke/Ole/Ole32/ObjIdl.cs @@ -888,6 +888,739 @@ namespace Vanara.PInvoke HRESULT SendOnDataChange(IDataObject pDataObject, [Optional] uint dwReserved, ADVF advf); } + /// + /// + /// Enables data transfer and notification of changes in data. Data transfer methods specify the format of the transferred data along + /// with the medium through which the data is to be transferred. Optionally, the data can be rendered for a specific target device. + /// In addition to methods for retrieving and storing data, the IDataObject interface specifies methods for enumerating + /// available formats and managing connections to advisory sinks for handling change notifications. + /// + /// + /// The term data object is used to mean any object that supports an implementation of the IDataObject interface. + /// Implementations vary, depending on what the data object is required to do; in some data objects, the implementation of certain + /// methods not supported by the object could simply be the return of E_NOTIMPL. For example, some data objects do not allow callers + /// to send them data. Other data objects do not support advisory connections and change notifications. However, for those data + /// objects that do support change notifications, OLE provides an object called a data advise holder. An interface pointer to this + /// holder is available through a call to the helper function CreateDataAdviseHolder. A data object can have multiple connections, + /// each with its own set of attributes. The OLE data advise holder simplifies the task of managing these connections and sending the + /// appropriate notifications. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nn-objidl-idataobject + [PInvokeData("objidl.h", MSDNShortId = "NN:objidl.IDataObject")] + [ComImport, Guid("0000010e-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDataObjectV + { + /// + /// Called by a data consumer to obtain data from a source data object. The GetData method renders the data described in + /// the specified FORMATETC structure and transfers it through the specified STGMEDIUM structure. The caller then assumes + /// responsibility for releasing the STGMEDIUM structure. + /// + /// + /// A pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. It is + /// possible to specify more than one medium by using the Boolean OR operator, allowing the method to choose the best medium + /// among those specified. + /// + /// + /// A pointer to the STGMEDIUM structure that indicates the storage medium containing the returned data through its tymed member, + /// and the responsibility for releasing the medium through the value of its pUnkForRelease member. If + /// pUnkForRelease is NULL, the receiver of the medium is responsible for releasing it; otherwise, + /// pUnkForRelease points to the IUnknown on the appropriate object so its Release method can be called. The medium must + /// be allocated and filled in by GetData. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// DV_E_LINDEX + /// The value for lindex is not valid; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// The value for pformatetcIn is not valid. + /// + /// + /// DV_E_TYMED + /// The tymed value is not valid. + /// + /// + /// DV_E_DVASPECT + /// The dwAspect value is not valid. + /// + /// + /// OLE_E_NOTRUNNING + /// The object application is not running. + /// + /// + /// STG_E_MEDIUMFULL + /// An error occurred when allocating the medium. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The dwDirection value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// A data consumer calls GetData to retrieve data from a data object, conveyed through a storage medium (defined through + /// the STGMEDIUM structure). + /// + /// Notes to Callers + /// + /// You can specify more than one acceptable tymed medium with the Boolean OR operator. GetData must choose from + /// the OR'd values the medium that best represents the data, do the allocation, and indicate responsibility for releasing the medium. + /// + /// + /// Data transferred across a stream extends from position zero of the stream pointer through to the position immediately before + /// the current stream pointer (that is, the stream pointer position upon exit). + /// + /// Notes to Implementers + /// + /// GetData must check all fields in the FORMATETC structure. It is important that GetData render the requested + /// aspect and, if possible, use the requested medium. If the data object cannot comply with the information specified in the + /// FORMATETC, the method should return DV_E_FORMATETC. If an attempt to allocate the medium fails, the method should + /// return STG_E_MEDIUMFULL. It is important to fill in all of the fields in the STGMEDIUM structure. + /// + /// + /// Although the caller can specify more than one medium for returning the data, GetData can provide only one medium. If + /// the initial transfer fails with the selected medium, this method can be implemented to try one of the other media specified + /// before returning an error. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-getdata HRESULT GetData( [in] FORMATETC + // *pformatetcIn, [out] STGMEDIUM *pmedium ); + [PreserveSig] + HRESULT GetData(in FORMATETC pformatetcIn, out STGMEDIUM pmedium); + + /// + /// Called by a data consumer to obtain data from a source data object. This method differs from the GetData method in that the + /// caller must allocate and free the specified storage medium. + /// + /// + /// A pointer to the FORMATETC structure that defines the format, medium, and target device to use when passing the data. Only + /// one medium can be specified in tymed, and only the following values are valid: TYMED_ISTORAGE, TYMED_ISTREAM, + /// TYMED_HGLOBAL, or TYMED_FILE. + /// + /// + /// A pointer to the STGMEDIUM structure that defines the storage medium containing the data being transferred. The medium must + /// be allocated by the caller and filled in by GetDataHere. The caller must also free the medium. The implementation of + /// this method must always supply a value of NULL for the punkForRelease member of the STGMEDIUM structure + /// to which this parameter points. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// DV_E_LINDEX + /// The value for lindex is not valid; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// The value for pformatetc is not valid. + /// + /// + /// DV_E_TYMED + /// The tymed value is not valid. + /// + /// + /// DV_E_DVASPECT + /// The dwAspect value is not valid. + /// + /// + /// OLE_E_NOTRUNNING + /// The object application is not running. + /// + /// + /// STG_E_MEDIUMFULL + /// An error occurred when allocating the medium. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The dwDirection parameter is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// The GetDataHere method is similar to IDataObject::GetData, except that the caller must both allocate and free the + /// medium specified in pmedium. GetDataHere renders the data described in a FORMATETC structure and copies the + /// data into that caller-provided STGMEDIUM structure. For example, if the medium is TYMED_HGLOBAL, this method cannot resize + /// the medium or allocate a new hGlobal. + /// + /// + /// Some media are not appropriate in a call to GetDataHere, including GDI types such as metafiles. The GetDataHere + /// method cannot put data into a caller-provided metafile. In general, the only storage media it is necessary to support in this + /// method are TYMED_ISTORAGE, TYMED_ISTREAM, and TYMED_FILE. + /// + /// + /// When the transfer medium is a stream, OLE makes assumptions about where the data is being returned and the position of the + /// stream's seek pointer. In a GetData call, the data returned is from stream position zero through just before the current seek + /// pointer of the stream (that is, the position on exit). For GetDataHere, the data returned is from the stream position + /// on entry through just before the position on exit. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-getdatahere HRESULT GetDataHere( [in] + // FORMATETC *pformatetc, [in, out] STGMEDIUM *pmedium ); + [PreserveSig] + HRESULT GetDataHere(in FORMATETC pformatetc, ref STGMEDIUM pmedium); + + /// + /// Determines whether the data object is capable of rendering the data as specified. Objects attempting a paste or drop + /// operation can call this method before calling IDataObject::GetData to get an indication of whether the operation may be successful. + /// + /// + /// A pointer to the FORMATETC structure defining the format, medium, and target device to use for the query. + /// + /// + /// This method returns S_OK on success. Other possible values include the following + /// + /// + /// Return code + /// Description + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// Invalid value for pformatetc. + /// + /// + /// DV_E_TYMED + /// The tymed value is not valid. + /// + /// + /// DV_E_DVASPECT + /// The dwAspect value is not valid. + /// + /// + /// OLE_E_NOTRUNNING + /// The object application is not running. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The dwDirection value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There is insufficient memory available for this operation. + /// + /// + /// + /// + /// The client of a data object calls QueryGetData to determine whether passing the specified FORMATETC structure to a + /// subsequent call to IDataObject::GetData is likely to be successful. A successful return from this method does not necessarily + /// ensure the success of the subsequent paste or drop operation. + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-querygetdata HRESULT QueryGetData( [in] + // FORMATETC *pformatetc ); + [PreserveSig] + HRESULT QueryGetData(in FORMATETC pformatetc); + + /// + /// Provides a potentially different but logically equivalent FORMATETC structure. You use this method to determine whether two + /// different FORMATETC structures would return the same data, removing the need for duplicate rendering. + /// + /// + /// A pointer to the FORMATETC structure that defines the format, medium, and target device that the caller would like to use to + /// retrieve data in a subsequent call such as IDataObject::GetData. The tymed member is not significant in this case and + /// should be ignored. + /// + /// + /// A pointer to a FORMATETC structure that contains the most general information possible for a specific rendering, making it + /// canonically equivalent to pformatetcIn. The caller must allocate this structure and the GetCanonicalFormatEtc + /// method must fill in the data. To retrieve data in a subsequent call like IDataObject::GetData, the caller uses the specified + /// value of pformatetcOut, unless the value specified is NULL. This value is NULL if the method returns + /// DATA_S_SAMEFORMATETC. The tymed member is not significant in this case and should be ignored. + /// + /// + /// This method can return the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The returned FORMATETC structure is different from the one that was passed. + /// + /// + /// DATA_S_SAMEFORMATETC + /// The FORMATETC structures are the same and NULL is returned in pformatetcOut. + /// + /// + /// DV_E_LINDEX + /// The value for lindex is not valid; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// The value for pformatetc is not valid. + /// + /// + /// OLE_E_NOTRUNNING + /// The object application is not running. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The dwDirection parameter is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// If a data object can supply exactly the same data for more than one requested FORMATETC structure, + /// GetCanonicalFormatEtc can supply a "canonical", or standard FORMATETC that gives the same rendering as a set of + /// more complicated FORMATETC structures. For example, it is common for the data returned to be insensitive to the target + /// device specified in any one of a set of otherwise similar FORMATETC structures. + /// + /// Notes to Callers + /// + /// A call to this method can determine whether two calls to IDataObject::GetData on a data object, specifying two different + /// FORMATETC structures, would actually produce the same renderings, thus eliminating the need for the second call and improving + /// performance. If the call to GetCanonicalFormatEtc results in a canonical format being written to the + /// pformatetcOut parameter, the caller then uses that structure in a subsequent call to IDataObject::GetData. + /// + /// Notes to Implementers + /// + /// Conceptually, it is possible to think of FORMATETC structures in groups defined by a canonical FORMATETC that provides + /// the same results as each of the group members. In constructing the canonical FORMATETC, you should make sure it + /// contains the most general information possible that still produces a specific rendering. + /// + /// + /// For data objects that never provide device-specific renderings, the simplest implementation of this method is to copy the + /// input FORMATETC to the output FORMATETC, store a NULL in the ptd member of the output FORMATETC, + /// and return DATA_S_SAMEFORMATETC. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-getcanonicalformatetc HRESULT + // GetCanonicalFormatEtc( [in] FORMATETC *pformatectIn, [out] FORMATETC *pformatetcOut ); + [PreserveSig] + HRESULT GetCanonicalFormatEtc(in FORMATETC pformatectIn, out FORMATETC pformatetcOut); + + /// Called by an object containing a data source to transfer data to the object that implements this method. + /// + /// A pointer to the FORMATETC structure defining the format used by the data object when interpreting the data contained in the + /// storage medium. + /// + /// A pointer to the STGMEDIUM structure defining the storage medium in which the data is being passed. + /// + /// If TRUE, the data object called, which implements SetData, owns the storage medium after the call returns. This + /// means it must free the medium after it has been used by calling the ReleaseStgMedium function. If FALSE, the caller + /// retains ownership of the storage medium and the data object called uses the storage medium for the duration of the call only. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// DV_E_LINDEX + /// Invalid value for lindex; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// The value for pformatetc is not valid. + /// + /// + /// DV_E_TYMED + /// The tymed value is not valid. + /// + /// + /// DV_E_DVASPECT + /// The dwAspect value is not valid. + /// + /// + /// OLE_E_NOTRUNNING + /// The object application is not running. + /// + /// + /// E_FAIL + /// The operation failed. + /// + /// + /// E_UNEXPECTED + /// An unexpected error has occurred. + /// + /// + /// E_INVALIDARG + /// The dwDirection value is not valid. + /// + /// + /// E_OUTOFMEMORY + /// There was insufficient memory available for this operation. + /// + /// + /// + /// + /// + /// SetData allows another object to attempt to send data to the implementing data object. A data object implements this + /// method if it supports receiving data from another object. If it does not support this, it should be implemented to return E_NOTIMPL. + /// + /// + /// The caller allocates the storage medium indicated by the pmedium parameter, in which the data is passed. The data + /// object called does not take ownership of the data until it has successfully received it and no error code is returned. The + /// value of the fRelease parameter indicates the ownership of the medium after the call returns. FALSE indicates + /// the caller still owns the medium, and the data object only has the use of it during the call; TRUE indicates that the + /// data object now owns it and must release it when it is no longer needed. + /// + /// + /// The type of medium specified in the pformatetc and pmedium parameters must be the same. For example, one cannot + /// be a global handle and the other a stream. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-setdata HRESULT SetData( [in] FORMATETC + // *pformatetc, [in] STGMEDIUM *pmedium, [in] BOOL fRelease ); + [PreserveSig] + HRESULT SetData(in FORMATETC pformatetc, in STGMEDIUM pmedium, [MarshalAs(UnmanagedType.Bool)] bool fRelease); + + /// Creates an object to enumerate the formats supported by a data object. + /// + /// The direction of the data. Possible values come from the DATADIR enumeration. + /// + /// The value DATADIR_GET enumerates the formats that can be passed in to a call to IDataObject::GetData. The value DATADIR_SET + /// enumerates those formats that can be passed in to a call to IDataObject::SetData. + /// + /// + /// + /// A pointer to an IEnumFORMATETC pointer variable that receives the interface pointer to the new enumerator object. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_INVALIDARG + /// The supplied dwDirection is invalid. + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory available for this operation. + /// + /// + /// E_NOTIMPL + /// The direction specified by dwDirection is not supported. + /// + /// + /// OLE_S_USEREG + /// Requests that OLE enumerate the formats from the registry. + /// + /// + /// + /// + /// + /// EnumFormatEtc creates an enumerator object that can be used to determine all of the ways the data object can describe + /// data in a FORMATETC structure, and provides a pointer to its IEnumFORMATETC interface. This is one of the standard enumerator interfaces. + /// + /// Notes to Callers + /// + /// Having obtained the pointer, the caller can enumerate the FORMATETC structures by calling the enumeration methods of + /// IEnumFORMATETC. Because the formats can change over time, there is no guarantee that an enumerated format is currently + /// supported because the formats can change over time. Accordingly, applications should treat the enumeration as a hint of the + /// format types that can be passed. The caller is responsible for calling Release when it is finished with the enumerator. + /// + /// EnumFormatEtc is called when one of the following actions occurs: + /// + /// + /// + /// An application calls OleSetClipboard. OLE must determine what data to place on the clipboard and whether it is necessary to + /// put OLE 1 compatibility formats on the clipboard. + /// + /// + /// + /// Data is being pasted from the clipboard or dropped. An application uses the first acceptable format. + /// + /// + /// + /// The Paste Special dialog box is displayed. The target application builds the list of formats from the FORMATETC entries. + /// + /// + /// + /// Notes to Implementers + /// + /// Formats can be registered statically in the registry or dynamically during object initialization. If an object has an + /// unchanging list of formats and these formats are registered in the registry, OLE provides an implementation of a FORMATETC + /// enumeration object that can enumerate formats registered under a specific CLSID in the registry. A pointer to its + /// IEnumFORMATETC interface is available through a call to the helper function OleRegEnumFormatEtc. In this situation, + /// therefore, you can implement the EnumFormatEtc method simply with a call to this function. + /// + /// + /// EXE applications can effectively do the same thing by implementing the method to return the value OLE_S_USEREG. This return + /// value instructs the default object handler to call OleRegEnumFormatEtc. Object applications that are implemented as DLL + /// object applications cannot return OLE_S_USEREG, so must call OleRegEnumFormatEtc directly. + /// + /// + /// Private formats can be enumerated for OLE 1 objects, if they are registered with the RequestDataFormats or SetDataFormats + /// keys in the registry. Also, private formats can be enumerated for OLE objects (all versions after OLE 1), if they are + /// registered with the GetDataFormats or SetDataFormats keys. + /// + /// + /// For OLE 1 objects whose servers do not have RequestDataFormats or SetDataFormats information registered in the registry, a + /// call to EnumFormatEtc passing DATADIR_GET only enumerates the native and metafile formats, regardless of whether they + /// support these formats or others. Calling EnumFormatEtc passing DATADIR_SET on such objects only enumerates native, + /// regardless of whether the object supports being set with other formats. + /// + /// + /// The FORMATETC structure returned by the enumeration usually indicates a NULL target device (ptd). This is appropriate + /// because, unlike the other members of FORMATETC, the target device does not participate in the object's decision as to + /// whether it can accept or provide the data in either a SetData or GetData call. + /// + /// + /// The tymed member of FORMATETC often indicates that more than one kind of storage medium is acceptable. You should + /// always mask and test for this by using a Boolean OR operator. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-enumformatetc HRESULT EnumFormatEtc( [in] + // DWORD dwDirection, [out] IEnumFORMATETC **ppenumFormatEtc ); + [PreserveSig] + HRESULT EnumFormatEtc(DATADIR dwDirection, [MarshalAs(UnmanagedType.Interface)] out IEnumFORMATETC ppenumFormatEtc); + + /// + /// Called by an object supporting an advise sink to create a connection between a data object and the advise sink. This enables + /// the advise sink to be notified of changes in the data of the object. + /// + /// + /// A pointer to a FORMATETC structure that defines the format, target device, aspect, and medium that will be used for future + /// notifications. For example, one sink may want to know only when the bitmap representation of the data in the data object + /// changes. Another sink may be interested in only the metafile format of the same object. Each advise sink is notified when the + /// data of interest changes. This data is passed back to the advise sink when notification occurs. + /// + /// + /// + /// A group of flags for controlling the advisory connection. Possible values are from the ADVF enumeration. However, only some + /// of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values. + /// + /// + /// + /// ADVF Value + /// Description + /// + /// + /// ADVF_NODATA + /// + /// Asks the data object to avoid sending data with the notifications. Typically data is sent. This flag is a way to override the + /// default behavior. When ADVF_NODATA is used, the tymed member of the STGMEDIUM structure that is passed to OnDataChange + /// will usually contain TYMED_NULL. The caller can then retrieve the data with a subsequent IDataObject::GetData call. + /// + /// + /// + /// ADVF_ONLYONCE + /// + /// Causes the advisory connection to be destroyed after the first change notification is sent. An implicit call to + /// IDataObject::DUnadvise is made on behalf of the caller to remove the connection. + /// + /// + /// + /// ADVF_PRIMEFIRST + /// + /// Asks for an additional initial notification. The combination of ADVF_ONLYONCE and ADVF_PRIMEFIRST provides, in effect, an + /// asynchronous IDataObject::GetData call. + /// + /// + /// + /// ADVF_DATAONSTOP + /// + /// When specified with ADVF_NODATA, this flag causes a last notification with the data included to to be sent before the data + /// object is destroyed. If used without ADVF_NODATA, DAdvise can be implemented in one of the following ways: A change + /// notification is sent only in the shutdown case. Data changes prior to shutdown do not cause a notification to be sent. + /// + /// + /// + /// + /// A pointer to the IAdviseSink interface on the advisory sink that will receive the change notification. + /// + /// A token that identifies this connection. You can use this token later to delete the advisory connection (by passing it to + /// IDataObject::DUnadvise). If this value is 0, the connection was not established. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// E_NOTIMPL + /// This method is not implemented on the data object. + /// + /// + /// DV_E_LINDEX + /// The value for lindex is not valid; currently, only -1 is supported. + /// + /// + /// DV_E_FORMATETC + /// The value for pformatetc is not valid. + /// + /// + /// OLE_E_ADVISENOTSUPPORTED + /// The data object does not support change notification. + /// + /// + /// + /// + /// + /// DAdvise creates a change notification connection between a data object and the caller. The caller provides an advisory + /// sink to which the notifications can be sent when the object's data changes. + /// + /// + /// Objects used simply for data transfer typically do not support advisory notifications and return OLE_E_ADVISENOTSUPPORTED + /// from DAdvise. + /// + /// Notes to Callers + /// + /// The object supporting the advise sink calls DAdvise to set up the connection, specifying the format, aspect, medium, + /// and/or target device of interest in the FORMATETC structure passed in. If the data object does not support one or more of the + /// requested attributes or the sending of notifications at all, it can refuse the connection by returning OLE_E_ADVISENOTSUPPORTED. + /// + /// + /// Containers of linked objects can set up advisory connections directly with the bound link source or indirectly through the + /// standard OLE link object that manages the connection. Connections set up with the bound link source are not automatically + /// deleted. The container must explicitly call IDataObject::DUnadvise on the bound link source to delete an advisory connection. + /// The OLE link object, manipulated through the IOleLink interface, is implemented in the default handler. Connections set up + /// through the OLE link object are destroyed when the link object is deleted. + /// + /// + /// The OLE default link object creates a "wildcard advise" with the link source so OLE can maintain the time of last change. + /// This advise is specifically used to note the time that anything changed. OLE ignores all data formats that may have changed, + /// noting only the time of last change. To allow wildcard advises, set the FORMATETC members as follows before calling DAdvise: + /// + /// The advise flags should also include ADVF_NODATA. Wildcard advises from OLE should always be accepted by applications. + /// Notes to Implementers + /// + /// To simplify the implementation of DAdvise and the other notification methods in IDataObject (DUnadvise and + /// EnumDAdvise) that supports notification, OLE provides an advise holder object that manages the registration and sending of + /// notifications. To get a pointer to this object, call the helper function CreateDataAdviseHolder on the first invocation of + /// DAdvise. This supplies a pointer to the object's IDataAdviseHolder interface. Then, delegate the call to the + /// IDataAdviseHolder::Advise method in the data advise holder, which creates, and subsequently manages, the requested connection. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-dadvise HRESULT DAdvise( [in] FORMATETC + // *pformatetc, [in] DWORD advf, [in] IAdviseSink *pAdvSink, [out] DWORD *pdwConnection ); + [PreserveSig] + HRESULT DAdvise(in FORMATETC pformatetc, ADVF advf, [In, Optional, MarshalAs(UnmanagedType.Interface)] IAdviseSink pAdvSink, out uint pdwConnection); + + /// Destroys a notification connection that had been previously set up. + /// + /// A token that specifies the connection to be removed. Use the value returned by IDataObject::DAdvise when the connection was + /// originally established. + /// + /// + /// This method returns S_OK on success. Other possible values include the following. + /// + /// + /// Return code + /// Description + /// + /// + /// OLE_E_NOCONNECTION + /// The specified value for dwConnection is not a valid connection. + /// + /// + /// OLE_E_ADVISENOTSUPPORTED + /// This IDataObject implementation does not support notification. + /// + /// + /// + /// + /// This methods destroys a notification created with a call to the IDataObject::DAdvise method. + /// + /// If the advisory connection being deleted was initially set up by delegating the IDataObject::DAdvise call to + /// IDataAdviseHolder::Advise, you must delegate this call to IDataAdviseHolder::Unadvise to delete it. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-dunadvise HRESULT DUnadvise( [in] DWORD + // dwConnection ); + [PreserveSig] + HRESULT DUnadvise(uint dwConnection); + + /// Creates an object that can be used to enumerate the current advisory connections. + /// + /// A pointer to an IEnumSTATDATA pointer variable that receives the interface pointer to the new enumerator object. If the + /// implementation sets * ppenumAdvise to NULL, there are no connections to advise sinks at this time. + /// + /// + /// + /// This method returns S_OK if the enumerator object is successfully instantiated or there are no connections. Other possible + /// values include the following. + /// + /// + /// + /// Return code + /// Description + /// + /// + /// E_OUTOFMEMORY + /// Insufficient memory is available for the operation. + /// + /// + /// OLE_E_ADVISENOTSUPPORTED + /// Advisory notifications are not supported by this object. + /// + /// + /// + /// + /// + /// The enumerator object created by this method implements the IEnumSTATDATA interface. IEnumSTATDATA permits the + /// enumeration of the data stored in an array of STATDATA structures. Each of these structures provides information on a single + /// advisory connection, and includes FORMATETC and ADVF information, as well as the pointer to the advise sink and the token + /// representing the connection. + /// + /// Notes to Callers + /// + /// It is recommended that you use the OLE data advise holder object to handle advisory connections. With the pointer obtained + /// through a call to CreateDataAdviseHolder, implementing IDataObject::EnumDAdvise becomes a simple matter of delegating + /// the call to IDataAdviseHolder::EnumAdvise. This creates the enumerator and supplies the pointer to the OLE implementation of + /// IEnumSTATDATA. At that point, you can call its methods to enumerate the current advisory connections. + /// + /// + // https://learn.microsoft.com/en-us/windows/win32/api/objidl/nf-objidl-idataobject-enumdadvise HRESULT EnumDAdvise( [out] + // IEnumSTATDATA **ppenumAdvise ); + [PreserveSig] + HRESULT EnumDAdvise([Optional, MarshalAs(UnmanagedType.Interface)] out IEnumSTATDATA ppenumAdvise); + } + /// /// The IDirectWriterLock interface enables a single writer to obtain exclusive write access to a root storage object opened /// in direct mode while allowing concurrent access by multiple readers. This single-writer, multiple-reader mode does not require