namespace Vanara.PInvoke; /// Items from the OleDb.dll. public static partial class OleDb { /// A flag that specifies the result of the comparison. [PInvokeData("oledb.h")] public enum DBCOMPARE { /// The first bookmark is before the second. DBCOMPARE_LT = 0, /// The two bookmarks are equal. DBCOMPARE_EQ = (DBCOMPARE_LT + 1), /// The first bookmark is after the second. DBCOMPARE_GT = (DBCOMPARE_EQ + 1), /// The bookmarks are not equal and not ordered. DBCOMPARE_NE = (DBCOMPARE_GT + 1), /// /// The two bookmarks cannot be compared. When to return DBCOMPARE_NOTCOMPARABLE: /// /// /// When calling IRowsetLocate::Compare, the consumer passed a bookmark for a row that does not belong to the chapter designated by /// hChapter. This bookmark could have been handed out on the base rowset or on another chapter for this rowset. /// /// /// The provider supports key value bookmarks, and one of the bookmarks passed to IRowsetLocate::Compare is now disassociated from /// the row due to a prior update of a key value. /// /// /// DBCOMPARE_NOTCOMPARABLE = (DBCOMPARE_NE + 1) } /// A bitmask describing the options of the range. [PInvokeData("oledb.h")] [Flags] public enum DBRANGE : uint { /// The start boundary is inclusive (the default). DBRANGE_INCLUSIVESTART = 0, /// The end boundary is inclusive (the default). DBRANGE_INCLUSIVEEND = 0, /// The start boundary is exclusive. DBRANGE_EXCLUSIVESTART = 0x1, /// The end boundary is exclusive. DBRANGE_EXCLUSIVEEND = 0x2, /// Exclude NULLs from the range. DBRANGE_EXCLUDENULLS = 0x4, /// /// Use *pStartData as a prefix. pEndData must be a null pointer. Prefix matching can be specified entirely using the inclusive and /// exclusive flags. However, because prefix matching is an important common case, this flag enables the consumer to specify only the /// *pStartData values and enables the provider to interpret this request quickly. /// DBRANGE_PREFIX = 0x8, /// /// Set the range to all keys that match *pStartData. *pStartData must specify a full key. pEndData must be a null pointer. Used for /// fast equality match. /// DBRANGE_MATCH = 0x10, /// Equal to 24 to indicate the number of bits to shift to get the number N. DBRANGE_MATCH_N_SHIFT = 0x18, /// Equal to 0xff. DBRANGE_MATCH_N_MASK = 0xff } /// A bitmask describing the options for the IRowsetIndex::Seek method. [PInvokeData("oledb.h")] [Flags] public enum DBSEEK : uint { /// DBSEEK_INVALID = 0, /// First key with values equal to the values in *pData, in index order. DBSEEK_FIRSTEQ = 0x1, /// Last key with values equal to the values in *pData. DBSEEK_LASTEQ = 0x2, /// /// Last key with values equal to the values in *pData or, if there are no keys equal to the values in *pData, first key with values /// after the values in *pData, in index order. /// DBSEEK_AFTEREQ = 0x4, /// First key with values following the values in *pData, in index order. DBSEEK_AFTER = 0x8, /// /// First key with values equal to the values in *pData or, if there are no keys equal to the values in *pData, last key with values /// before the values in *pData, in index order. /// DBSEEK_BEFOREEQ = 0x10, /// Last key with values before the values in *pData, in index order. DBSEEK_BEFORE = 0x20 } /// /// The IRow interface allows a consumer to read column data from a row object or to obtain the source rowset of the row object. /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721261(v=vs.85) [ComImport, Guid("0c733ab4-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRow { /// Retrieves the values of one or more named columns from the row object. /// /// [in] Count of columns specified in the rgColumns array. If cColumns is zero, no columns are created or updated. /// /// /// [in/out] A caller-supplied array of DBCOLUMNACCESS structures. The DBCOLUMNACCESS structure is defined as follows: /// /// /// /// /// /// S_OK The provider successfully retrieved all of the columns. /// /// /// /// /// E_INVALIDARG rgColumns was a null pointer, and cColumns was not zero. /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The provider was unable to access any of the columns. /// /// /// /// /// /// DB_E_ERRORSOCCURRED The provider was unable to retrieve any of the specified columns. The caller should check dwStatus of each /// element of rgColumns to determine why each column was not retrieved. /// /// /// /// /// /// /// DB_S_ERRORSOCCURRED The provider was unable to retrieve some of the specified columns. The caller should check dwStatus of each /// element of rgColumns to determine whether a column was retrieved. /// /// /// /// /// /// /// DB_E_DELETEDROW The row was either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718107(v=vs.85) HRESULT GetColumns( DBORDINAL cColumns, // DBCOLUMNACCESS rgColumns[ ] ); [PreserveSig] HRESULT GetColumns(DBORDINAL cColumns, [In, Out] DBCOLUMNACCESS[] rgColumns); /// Returns an interface pointer on the rowset that contains the row represented by a row object. /// /// [in] The interface ID (IID) of the requested interface to return in ppRowset. This argument is ignored if ppRowset is a null pointer. /// /// /// [out] A pointer to memory in which to return the interface for the rowset. If the caller sets ppRowset to a null pointer, no /// rowset is returned. If the provider does not have a rowset object as the source for the row, it sets *ppRowset to a null pointer. /// If IRow::GetSourceRowset fails, the provider must attempt to set *ppRowset to a null pointer. /// /// /// [out] A pointer to memory in which to return the row handle of this row within the source rowset. If phRow is a null pointer, no /// row handle is returned. If the provider does not have a rowset object as the source for the row, it sets *phRow to NULL. If /// IRow::GetSourceRowset fails, the provider must attempt to set *phRow to NULL. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_E_DELETEDROW The row was either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// /// DB_E_NOSOURCEOBJECT The provider did not have a rowset object as the source for the row. Therefore, it set *ppRowset and *phRow /// to NULL. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG ppRowSet and phRow were null pointers. /// /// /// /// /// E_NOINTERFACE The rowset did not support the interface specified in riid. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725450(v=vs.85) HRESULT GetSourceRowset( REFIID riid, // IUnknown **ppRowset, HROW *phRow ); [PreserveSig] HRESULT GetSourceRowset(in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset, out HROW phRow); /// /// Returns an interface pointer to be used to access an object-valued column. IRow::Open will generally return a rowset, row, /// or stream object, allowing the provider to create the appropriate object for tabular columns and streams. The returned object /// inherits the access privileges from the original flags used for binding to the row. IRow::Open can also return an /// interface pointer to a child rowset when called on a chapter-valued column. /// /// /// [in] The controlling IUnknown if the returned interface is to be aggregated; otherwise, a null pointer. /// /// /// [in] A pointer to a DBID containing the name of the column to open. Must not be a null pointer. When a chapter-valued column, /// rguidColumnType must be DBGUID_ROWSET and riid should be a rowset interface. /// /// /// /// [in] A pointer to a GUID that identifies the type of object to be opened from this column. If the GUID does not match the column /// type, DB_E_OBJECTMISMATCH is returned. Possible values are described in the following table. /// /// /// /// Object type /// Description /// /// /// DBGUID_STREAM /// Column contains a stream of binary data. Use IStream or ISequentialStream. /// /// /// DBGUID_ROW /// Column contains a nested collection of columns. Use IRow. /// /// /// DBGUID_ROWSET /// Column contains a nested rowset. Use IRowset. /// /// /// GUID_NULL /// Column contains a COM object. Open the object as its native type, and return the interface specified by riid. /// /// /// /// [in] Reserved for flags to control the open operation. Must be zero. /// [in] Interface ID of the interface pointer to be returned. /// /// [out] A pointer to memory in which to return the requested interface pointer. If an error code is returned and ppUnk is not a /// null pointer, *ppUnk should be set to NULL. /// /// /// /// /// /// S_OK The object was successfully opened. The caller becomes responsible for releasing the returned interface pointer. /// /// /// /// /// /// DB_E_BADCOLUMNID pColumnID was an invalid DBID or a shortcut DBID, such as DBROWCOL_DEFAULTSTREAM, that does not exist on this row. /// /// /// /// /// /// /// DB_E_COLUMNUNAVAILABLE Requested column is valid, but could not be retrieved. The caller should check that the DBPROP_ACCESSORDER /// property is compatible with this operation. /// /// /// /// /// /// /// DB_E_DELETEDROW The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and riid was not IID_IUnknown. /// The provider does not support aggregation. /// The object has already been created. /// /// /// /// /// DB_E_NOTFOUND The data value of this column is NULL. /// /// /// /// /// DB_E_OBJECTMISMATCH rguidColumnType pointed to a GUID that did not match the object type of this column. /// pcolumnID is a chapter-valued column, and rguidColumnType is not DBGUID_ROWSET. /// /// /// /// /// /// DB_E_OBJECTOPEN The provider can support only a single open storage object at a time (DBPROP_MULTIPLESTORAGEOBJECTS = /// VARIANT_FALSE) and already has a storage object open. /// /// The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pColumnID or ppUnk was a null pointer. /// /// /// /// /// E_NOINTERFACE The object does not support the interface requested in riid, or riid was IID_NULL. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716947(v=vs.85) HRESULT Open( IUnknown *pUnkOuter, DBID // *pColumnID, REFGUID rguidColumnType, DWORD dwFlags, REFIID riid, IUnknown **ppUnk ); [PreserveSig] HRESULT Open([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in DBID pColumnID, in Guid rguidColumnType, [In, Optional] uint dwBindFlags, in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppUnk); } /// The IRowChange interface allows a consumer to quickly set columns of a row. // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716799(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733ab5-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowChange { /// Sets the values of one or more named columns of a row object. /// [in] Count of columns specified in the rgColumns array. If cColumns is zero, no columns are set. /// /// /// [ ] [in/out] A caller-supplied array of DBCOLUMNACCESS structures. The DBCOLUMNACCESS structure is described in the reference /// entry for IRow::GetColumns. /// /// /// For setting column values, the elements of each DBCOLUMNACCESS structure are used in the manner described in the following table. /// /// /// /// Element /// Description /// /// /// columnid /// Unique DBID that identifies the column to be accessed. /// /// /// wType /// Identifies the type of the value pointed to by pData. /// /// /// pData /// /// Caller-allocated pointer to storage of the data type specified by wType. On input, the area pointed to contains the value /// of the column specified by columnid. The caller must allocate and initialize the area of storage pointed to by /// pData. The provider should attempt to coerce the value from wType to the underlying value of the column. If /// wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed to by the VARIANT. /// /// /// /// cbMaxLen /// /// The maximum length of the caller-initialized memory pointed to by pData. The provider checks the length in bytes of /// variable-length data types against cbMaxLen. If the length is greater than cbMaxLen, this is an error and the /// provider sets the status to DBSTATUS_E_CANTCONVERTVALUE. /// /// /// /// bPrecision /// Indicates the precision of the value stored in *pData for data types equiring precision. /// /// /// bScale /// Indicates the scale of the value stored in *pData for data types requiring scale. /// /// /// dwStatus /// /// On input, dwStatus indicates whether pData or some other value should be used. When value DBSTATUS_S_ISNULL is used /// to set the column to null, other fields ( wType, pData, cbDataLen) are ignored. On return, dwStatus /// indicates whether the field was successfully set. The following status values may apply when setting column values. For more /// information, see Status. /// /// /// /// cbDataLen /// On input, the length of the data value pointed to by pData. Ignored for fixed-length types. /// /// /// /// /// /// /// /// S_OK The provider successfully set all of the columns. /// /// /// /// /// E_INVALIDARG cColumns was not zero, and rgColumns was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory for this operation. /// /// /// /// /// /// DB_S_ERRORSOCCURRED The provider was able to set at least one column but was unable to set at least one column. The caller should /// examine dwStatus of each element of rgColumns to determine whether, and why, an individual column was not set. /// /// /// /// /// /// /// DB_E_DELETEDROW The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while setting data for one or more columns, and data was not successfully set for any /// columns. The caller should examine dwStatus of each element of rgColumns to determine why each individual column was not set. /// /// /// /// /// /// /// DB_E_NEWLYINSERTED The value of the DBPROP_CHANGEINSERTEDROWS property on the source rowset was VARIANT_FALSE, and the method was /// called on a row for which the insertion has been transmitted to the data store. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The provider was unable to set any columns because of a permission failure. /// /// /// /// /// E_FAIL A provider-specific error occurred. No columns were set. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714307(v=vs.85) HRESULT SetColumns( DBORDINAL cColumns, // DBCOLUMNACCESS rgColumns[ ] ); [PreserveSig] HRESULT SetColumns(DBORDINAL cColumns, [In, MarshalAs(UnmanagedType.LPArray)] DBCOLUMNACCESS[] rgColumns); } /// [PInvokeData("oledb.h")] [ComImport, Guid("0c733aae-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowSchemaChange : IRowChange { /// Sets the values of one or more named columns of a row object. /// [in] Count of columns specified in the rgColumns array. If cColumns is zero, no columns are set. /// /// /// [ ] [in/out] A caller-supplied array of DBCOLUMNACCESS structures. The DBCOLUMNACCESS structure is described in the reference /// entry for IRow::GetColumns. /// /// /// For setting column values, the elements of each DBCOLUMNACCESS structure are used in the manner described in the following table. /// /// /// /// Element /// Description /// /// /// columnid /// Unique DBID that identifies the column to be accessed. /// /// /// wType /// Identifies the type of the value pointed to by pData. /// /// /// pData /// /// Caller-allocated pointer to storage of the data type specified by wType. On input, the area pointed to contains the value /// of the column specified by columnid. The caller must allocate and initialize the area of storage pointed to by /// pData. The provider should attempt to coerce the value from wType to the underlying value of the column. If /// wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed to by the VARIANT. /// /// /// /// cbMaxLen /// /// The maximum length of the caller-initialized memory pointed to by pData. The provider checks the length in bytes of /// variable-length data types against cbMaxLen. If the length is greater than cbMaxLen, this is an error and the /// provider sets the status to DBSTATUS_E_CANTCONVERTVALUE. /// /// /// /// bPrecision /// Indicates the precision of the value stored in *pData for data types equiring precision. /// /// /// bScale /// Indicates the scale of the value stored in *pData for data types requiring scale. /// /// /// dwStatus /// /// On input, dwStatus indicates whether pData or some other value should be used. When value DBSTATUS_S_ISNULL is used /// to set the column to null, other fields ( wType, pData, cbDataLen) are ignored. On return, dwStatus /// indicates whether the field was successfully set. The following status values may apply when setting column values. For more /// information, see Status. /// /// /// /// cbDataLen /// On input, the length of the data value pointed to by pData. Ignored for fixed-length types. /// /// /// /// /// /// /// /// S_OK The provider successfully set all of the columns. /// /// /// /// /// E_INVALIDARG cColumns was not zero, and rgColumns was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory for this operation. /// /// /// /// /// /// DB_S_ERRORSOCCURRED The provider was able to set at least one column but was unable to set at least one column. The caller should /// examine dwStatus of each element of rgColumns to determine whether, and why, an individual column was not set. /// /// /// /// /// /// /// DB_E_DELETEDROW The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while setting data for one or more columns, and data was not successfully set for any /// columns. The caller should examine dwStatus of each element of rgColumns to determine why each individual column was not set. /// /// /// /// /// /// /// DB_E_NEWLYINSERTED The value of the DBPROP_CHANGEINSERTEDROWS property on the source rowset was VARIANT_FALSE, and the method was /// called on a row for which the insertion has been transmitted to the data store. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The provider was unable to set any columns because of a permission failure. /// /// /// /// /// E_FAIL A provider-specific error occurred. No columns were set. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714307(v=vs.85) HRESULT SetColumns( DBORDINAL cColumns, // DBCOLUMNACCESS rgColumns[ ] ); [PreserveSig] new HRESULT SetColumns(DBORDINAL cColumns, [In, MarshalAs(UnmanagedType.LPArray)] DBCOLUMNACCESS[] rgColumns); /// /// Deletes one or more named columns from a row. For row-specific columns of a row that is in immediate update mode, this is an /// immediate schema operation. /// /// /// [in] Count of column names specified in the rgColumnIDs array. If cColumns is zero, no column values are deleted. /// /// /// [ ] [in] Consumer-allocated array of cColumns names of the columns to be deleted. It is not necessary to specify columns in any /// particular order in the array. If cColumns is zero, rgColumnIDs is ignored. If cColumns is not zero and rgColumnIDs is a null /// pointer, the provider returns E_INVALIDARG. It is not an error if a column name is specified more than once. /// /// /// /// [ ] [in/out] Optional consumer-allocated array of cColumns status fields indicating whether the value of the corresponding /// element of rgColumnIDs was deleted*.* Consumers not interested in receiving status may set rgdwStatus to null. The status fields /// described in the following table apply to the deletion of column values. /// /// /// /// Status field /// Description /// /// /// DBSTATUS_S_OK /// Indicates that the column value was deleted. /// /// /// DBROWSTATUS_S_ROWSETCOLUMN /// /// Providers may return this status flag when asked to delete a rowset column from a row. The value is actually nulled, but the /// column remains in the row and rowset. /// /// /// /// DBSTATUS_E_DOESNOTEXIST /// Indicates that the column does not exist on this row. /// /// /// DBSTATUS_E_PERMISSIONDENIED /// The consumer did not have sufficient permission to delete the column. /// /// /// The order of status elements must match the order of the column names in rgColumnIDs. /// For more information, see Status. /// /// /// /// /// /// S_OK The provider successfully deleted values for all of the requested column names. /// /// /// /// /// E_INVALIDARG cColumns was not zero, and rgColumnIDs was a null pointer. /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The provider was unable to delete any column values because of a permission failure. /// /// /// /// /// /// DB_S_ERRORSOCCURRED The provider was able to delete at least one column value but was unable to delete at least one column value. /// The caller should examine each element of rgdwStatus to determine whether, and why, an individual column was not set. /// /// /// /// /// /// DB_E_DELETEDROW The row has been deleted or moved. (A delete either is pending or has been transmitted to the data store.) /// /// /// /// /// /// DB_E_ERRORSOCCURRED The provider was unable to delete values of any of the named columns. The caller should examine each element /// of rgdwStatus to determine why each individual column was not set. /// /// /// /// /// /// /// DB_E_NEWLYINSERTED DBPROP_CHANGEINSERTEDROWS on the source rowset was VARIANT_FALSE, and the method was called on a row for which /// the insertion has been transmitted to the data store. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. No columns were deleted. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718065(v=vs.85) HRESULT DeleteColumns( DBORDINAL cColumns, // const DBID rgColumnIDs[ ], DBSTATUS rgdwStatus[ ] ); [PreserveSig] HRESULT DeleteColumns(DBORDINAL cColumns, [In, Optional] DBID[]? rgColumnIDs, [In, Out, Optional] DBSTATUS[]? rgdwStatus); /// /// Creates or sets the values of one or more named columns of a row object. If the columns do not already exist, they are created. /// /// /// [in] Count of columns specified in the rgNewColumnInfo array. If cColumns is zero, no columns are created or set. /// /// /// /// [in] A consumer-allocated array of cColumns DBCOLUMNINFO structures that define the additional columns to be added to the row /// object. If cColumns is zero, rgNewColumnInfo is ignored. The order of columns in rgColumns must match the order of columns in rgNewColumnInfo. /// /// /// Note /// For information about DBCOLUMNINFO structures, see IColumnsInfo::GetColumnInfo. /// /// The following table lists special instructions for defining row columns using DBCOLUMNINFO. /// /// /// Element /// Instructions for row columns /// /// /// pwszName /// Ignored on input when creating columns with AddColumns. /// /// /// iOrdinal /// Ignored on input when creating columns with AddColumns. /// /// /// dwFlags /// /// A bitmask that describes consumer-specified row column characteristics. The DBCOLUMNFLAGS enumerated type specifies the bits in /// the bitmask, which are described in the reference entry for IColumnsInfo::GetColumnInfo. The following flag values may apply when /// creating row columns: /// /// /// /// ulColumnSize /// /// Minimum size required to store the consumer's largest data for this column. For fixed-length data types, this is the size of the /// data type in bytes. For variable-length data types, this is the maximum number of bytes (for DBTYPE_BYTES) or characters (for /// DBTYPE_STR or DBTYPE_WSTR). For more information, see the description of DBCOLUMNINFO in the reference entry for IColumnsInfo::GetColumnInfo. /// /// /// /// wType /// Requested DBTYPE data type for this column. /// /// /// bPrecision /// Maximum precision of the column. /// /// /// bScale /// Number of digits to the right of the decimal point. /// /// /// columnid /// /// Unique DBID used to name this row column. For example, if columns are named ( eKind is DBKIND_NAME), uName.pwszName /// points to the column name. /// /// /// /// /// /// [in/out] An optional consumer-allocated array of cColumns DBCOLUMNACCESS structures. /// /// Note /// The DBCOLUMNACCESS structure is described in the reference entry for IRow::GetColumns. /// /// /// The order of columns in rgColumns must match the order of columns in rgNewColumnInfo. If rgColumns is a null pointer, new columns /// are created but no values are set (except for default values defined by the provider). /// /// /// For setting column values, the elements of each DBCOLUMNACCESS structure are used in the manner described in the following table. /// /// /// /// Element /// Description /// /// /// columnid /// /// This element is ignored by AddColumns. The column DBID is designated by the columnid element of the corresponding /// member of rgNewColumnInfo. (This is done so that consumers do not need to allocate two sets of DBIDs.) /// /// /// /// wType /// Identifies the type of the value pointed to by pData. /// /// /// pData /// /// Caller-allocated pointer to storage of the DBTYPE defined by wType. On input, the area pointed to contains the value of /// the column specified by the columnid element of rgNewColumnInfo. The caller must allocate and initialize the area /// of storage pointed to by pData. The provider should attempt to coerce the value from wType to the underlying value /// of the column. If wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed /// to by the VARIANT. /// /// /// /// cbMaxLen /// /// The maximum length of the caller-initialized memory pointed to by pData. The provider checks the length in bytes of /// variable-length data types against cbMaxLen. If the length is greater than cbMaxLen, this is an error and the /// provider sets the status to DBSTATUS_E_CANTCONVERTVALUE. /// /// /// /// bPrecision /// Indicates the precision of the value stored in *pData for data types requiring precision. /// /// /// bScale /// Indicates the scale of the value stored in *pData for data types requiring scale. /// /// /// dwStatus /// /// On input, dwStatus indicates whether pData or some other value should be used. All status values used in OLE DB for /// rowset columns apply to row columns. On input, if dwStatus is DBSTATUS_S_DEFAULT or DBSTATUS_S_IGNORE, the provider skips /// this column when setting data. On return, dwStatus indicates whether the field was successfully set. The following status /// values may apply when updating column values. Standard status values when setting data do apply in addition to those listed in /// the following table. For more information about Status, see Getting and Setting Data.) /// /// /// /// cbDataLen /// On input, the length of the data value pointed to by pData. Ignored for fixed-length types. /// /// /// /// /// /// /// /// S_OK The provider successfully created or set the values of all of the columns. /// /// /// /// /// E_INVALIDARG cColumns was not zero, and rgNewColumnInfo was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory for this operation. /// /// /// /// /// /// DB_S_ERRORSOCCURRED The provider was able to add or set the value of at least one column but was unable to do so for at least one /// column. The caller should examine the dwStatus value of each element of rgColumns to determine whether, and why, an individual /// column was not set. /// /// /// /// /// /// /// DB_E_DELETEDROW The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while setting data for one or more columns, and data was not successfully set for any /// columns. The caller should examine the dwStatus value of each element of rgColumns to determine whether, and why, an individual /// column was not set. /// /// /// /// /// /// /// DB_E_NEWLYINSERTED DBPROP_CHANGEINSERTEDROWS on the source rowset was VARIANT_FALSE, and the method was called on a row for which /// the insertion has been transmitted to the data store. /// /// /// /// /// /// DB_E_NOTSUPPORTED The provider does not support this method. /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The provider was unable to set any columns due to a permission failure. /// /// /// /// /// E_FAIL A provider-specific error occurred. No columns were added. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709723(v=vs.85) HRESULT AddColumns( DBORDINAL cColumns, // const DBCOLUMNINFO rgNewColumnInfo[ ], DBCOLUMNACCESS rgColumns[ ] ); [PreserveSig] HRESULT AddColumns(DBORDINAL cColumns, [In, Optional] DBCOLUMNINFO[]? rgNewColumnInfo, [In, Out, Optional] DBCOLUMNACCESS[]? rgColumns); } /// /// /// IRowset is the base rowset interface. It provides methods for fetching rows sequentially, getting the data from those rows, /// and managing rows. /// /// IRowset requires IAccessor and IRowsetInfo. /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720986(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733a7c-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowset { /// Adds a reference count to an existing row handle. /// [in] The number of rows for which to increment the reference count. /// /// [in] An array of row handles for which to increment the reference count. The reference count of row handles is incremented by one /// for each time they appear in the array. /// /// /// [out] An array with cRows elements in which to return the new reference count for each row handle. The consumer allocates memory /// for this array. If rgRefCounts is a null pointer, no reference counts are returned. /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors /// occur while incrementing the reference count of a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an /// error occurs while incrementing the reference count of a row, the corresponding element is set as specified in /// DB_S_ERRORSOCCURRED. The consumer allocates memory for this array. If rgRowStatus is a null pointer, no row statuses are returned. /// /// /// /// /// /// /// S_OK The method succeeded. The reference count of all rows was successfully incremented. The following value can be returned in *prgRowStatus: /// /// The reference count of the row was successfully incremented. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while incrementing the reference count of a row, but the reference count of at least one /// row was incremented. Successes can occur for the reason listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer, and cRows was not zero. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while incrementing the reference count of all of the rows. Errors can occur for the reasons /// listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719619(v=vs.85) HRESULT AddRefRows( DBCOUNTITEM cRows, const // HROW rghRows[], DBREFCOUNT rgRefCounts[], DBROWSTATUS rgRowStatus[]); [PreserveSig] HRESULT AddRefRows(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] HROW[] rghRows, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBREFCOUNT[]? rgRefCounts, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBROWSTATUS[]? rgRowStatus); /// Retrieves data from the rowset's copy of the row. /// /// [in] The handle of the row from which to get the data. /// /// Warning /// /// The consumer must ensure that hRow contains a valid row handle; the provider might not validate hRow before using it. The result /// of passing the handle of a deleted row is provider-specific, although the provider cannot terminate abnormally. For example, the /// provider might return DB_E_BADROWHANDLE, DB_E_DELETEDROW, or it might get data from a different row. The result of passing an /// invalid row handle in hRow is undefined. /// /// /// /// /// /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in /// IAccessor::CreateAccessor was zero), IRowset::GetData does not get any data values. /// /// /// Warning /// /// The consumer must ensure that hAccessor contains a valid accessor handle; the provider might not validate hAccessor before using /// it. The result of passing an invalid accessor handle in hAccessor is undefined. /// /// /// /// /// [out] A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer. This pointer must be a /// valid pointer to a contiguous block of consumer-owned memory into which the data will be written. /// /// /// /// /// /// /// S_OK The method succeeded. The status of all columns bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED. /// /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while returning data for one or more columns, but data was successfully returned for at /// least one column. To determine the columns for which data was returned, the consumer checks the status values. For a list of /// status values that can be returned by this method, see "Status Values Used When Getting Data" in Status. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pData was a null pointer, and the accessor was not a null accessor. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. Providers are not required to check for this condition, because doing so might slow /// the method significantly. /// /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of /// this error code when command accessors are passed to the rowset. /// /// /// /// /// /// /// DB_E_BADROWHANDLE hRow was invalid. Providers are not required to check for this condition, because doing so might slow the /// method significantly. /// /// /// /// /// /// /// DB_E_DELETEDROW hRow referred to a pending delete row or a row for which a deletion had been transmitted to the data store. /// Providers are not required to check for this condition, because doing so might slow the method significantly. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while returning data for all columns. To determine what errors occurred, the consumer checks /// the status values. For a list of status values that can be returned by this method, see "Status Values Used When Getting Data" in Status. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716988(v=vs.85) HRESULT GetData ( HROW hRow, HACCESSOR // hAccessor, void *pData); [PreserveSig] HRESULT GetData([In] HROW hRow, [In] HACCESSOR hAccessor, [Out] IntPtr pData); /// Fetches rows sequentially, remembering the previous position. /// /// [in] The chapter handle designating the rows to fetch. For nonchaptered rowsets, the caller must set hChapter to /// DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset. /// /// /// /// [in] The signed count of rows to skip before fetching rows. Deleted rows that the provider has removed from the rowset are not /// counted in the skip. If this value is zero and cRows continues in the same direction as the previous call either to /// IRowset::GetNextRows or to IRowsetFind::FindNextRow with a null pBookmark value, the first row fetched will be the next /// row after the last one fetched in the previous call. If this value is zero and cRows reverses direction, the first row fetched /// will be the last one fetched in the previous call. /// /// /// lRowsOffset can be a negative number only if the value of the DBPROP_CANSCROLLBACKWARDS property is VARIANT_TRUE. A negative /// value means skipping the rows in a backward direction. There is no guarantee that skipping rows is done efficiently on a /// sequential rowset. If the data store resides on a remote server, there may be remote support for skipping without transferring /// the intervening records across the network but this is not guaranteed. For information about how the provider implements /// skipping, see the documentation for the provider. /// /// /// /// /// [in] The number of rows to fetch. A negative number means to fetch backward. cRows can be a negative number only if the value of /// the DBPROP_CANFETCHBACKWARDS property is VARIANT_TRUE. /// /// /// If cRows is zero, the provider sets *pcRowsObtained to zero and performs no further processing, returning immediately from the /// method invocation. No rows are fetched, the fetch direction and the next fetch position are unchanged, and lRowsOffset is ignored. /// /// /// If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific. /// /// /// /// [out] A pointer to memory in which to return the actual number of fetched rows. If a warning condition occurs, this number may be /// less than the number of rows available or requested and is the number of rows actually fetched before the warning condition /// occurred. If the consumer has insufficient permission to fetch all rows, IRowset::GetNextRows fetches all rows for which /// the consumer has sufficient permission and skips all other rows. If the method fails, *pcRowsObtained is set to zero. /// /// /// [out] A pointer to memory in which to return an array of handles of the fetched rows. /// /// If *prghRows is not a null pointer on input, it must be a pointer to consumer-allocated memory large enough to return the handles /// of the requested number of rows. If the consumer-allocated memory is larger than needed, the provider fills in as many row /// handles as specified by pcRowsObtained; the contents of the remaining memory are undefined. /// /// /// If *prghRows is a null pointer on input, the rowset allocates memory for the row handles and returns the address to this memory; /// the consumer releases this memory with IMalloc::Free after it releases the row handles. If *prghRows is a null pointer on /// input and *pcRowsObtained is zero on output or if the method fails, the provider does not allocate any memory and ensures that /// *prghRows is a null pointer on output. /// /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_S_ENDOFROWSET IRowset::GetNextRows reached the start or the end of the rowset or chapter or the start or end of the /// range on an index rowset and could not fetch all requested rows because the count extended beyond the end. The next fetch /// position is before the start or after the end of the rowset. The number of rows actually fetched is returned in *pcRowsObtained; /// this will be less than cRows. /// /// /// The rowset is being populated asynchronously, and no additional rows are available at this time. To determine whether additional /// rows may be available, the consumer should call IDBAsynchStatus::GetStatus or listen for the IDBAsynchNotify::OnStop notification. /// /// /// lRowsOffset indicated a position either more than one row before the first row of the rowset or more than one row after the last /// row, and the provider was a version 2.0 or greater provider. *pcRowsObtained is set to zero, and no rows are returned. /// /// /// /// /// /// /// DB_S_ROWLIMITEXCEEDED Fetching the number of rows specified in cRows would have exceeded the total number of active rows /// supported by the rowset, as reported by DBPROP_MAXOPENROWS. The number of rows that were actually fetched is returned in *pcRowsObtained. /// /// /// /// /// /// /// DB_S_STOPLIMITREACHED Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. /// Execution has been stopped because a resource limit has been reached. The number of rows that were actually fetched is returned /// in *pcRowsObtained. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pcRowsObtained or prghRows was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory to complete the request. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_BADSTARTPOSITION lRowsOffset indicated a position either more than one row before the first row of the rowset or more than /// one row after the last row, and the provider was a 1.x provider. /// /// /// /// /// /// DB_E_CANCELED Fetching rows was canceled during notification. No rows were fetched. /// /// /// /// /// DB_E_CANTFETCHBACKWARDS cRows was negative, and the rowset cannot fetch backward. /// /// /// /// /// DB_E_CANTSCROLLBACKWARDS lRowsOffset was negative, and the rowset cannot scroll backward. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider /// does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to fetch any of the rows; no rows were fetched. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709827(v=vs.85) HRESULT GetNextRows ( HCHAPTER hChapter, // DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, DBCOUNTITEM *pcRowsObtained, HROW **prghRows); [PreserveSig] HRESULT GetNextRows([In] HCHAPTER hChapter, DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); /// Releases rows. /// [in] The number of rows to release. If cRows is zero, IRowset::ReleaseRows does not do anything. /// /// [in] An array of handles of the rows to be released. The row handles need not form a logical cluster; they may have been obtained /// at separate times and need not be for contiguous underlying rows. Row handles are decremented by one reference count for each /// time they appear in the array. /// /// /// [in] An array of cRows elements containing bitmasks indicating additional options to be specified when releasing a row. This /// parameter is reserved for future use and should be set to a null pointer. /// /// /// [out] An array with cRows elements in which to return the new reference count of each row. If rgRefCounts is a null pointer, no /// counts are returned. The consumer allocates, but is not required to initialize, memory for this array and passes the address of /// this memory to the provider. The provider returns the reference counts in the array. /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors /// or warnings occur while releasing a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an error or /// warning occurs while releasing a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer /// allocates memory for this array. If rgRowStatus is a null pointer, no row statuses are returned. /// /// /// /// /// /// S_OK The method succeeded. All rows were successfully released. The following values can be returned in *prgRowStatus: /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while releasing a row, but at least one row was successfully released. Successes and /// warnings can occur for the reasons listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer, and cRows was not equal to zero. /// /// /// /// /// /// E_UNEXPECTED DBPROP_BLOCKINGSTORAGEOBJECTS is VARIANT_TRUE, and IRowset::ReleaseRows is called on a row with an open /// storage object. If the consumer, on cleanup, encounters an error while releasing the row, it should release the storage object first. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while releasing all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719771(v=vs.85) HRESULT ReleaseRows ( DBCOUNTITEM cRows, // const HROW rghRows[], DBROWOPTIONS rgRowOptions[], DBREFCOUNT rgRefCounts[], DBROWSTATUS rgRowStatus[]); [PreserveSig] HRESULT ReleaseRows(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] HROW[] rghRows, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] uint[]? rgRowOptions, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBREFCOUNT[]? rgRefCounts, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBROWSTATUS[]? rgRowStatus); /// /// Repositions the next fetch position used by IRowset::GetNextRows or IRowsetFind::FindNextRow to its initial position ? that is, /// its position when the rowset was first created. /// /// /// /// /// /// /// S_OK The method succeeded. The provider did not have to re-execute the command, either because the rowset supports positioning on /// the first row without re-executing the command or because the rowset is already positioned on the first row. /// /// /// /// /// /// /// DB_S_COLUMNSCHANGED The order of the columns was not specified in the object that created the rowset. The provider had to /// re-execute the command to reposition the next fetch position to its initial position, and the order of the columns changed. /// /// /// The provider had to re-execute the command to reposition the next fetch position to its initial position, and columns were added /// or removed from the rowset. This is generally due to a change in the underlying schema and is extremely uncommon. /// /// /// This return code takes precedence over DB_S_COMMANDREEXECUTED. That is, if the conditions described here and in those described /// in DB_S_COMMANDREEXECUTED both occur, the provider returns this code. A change to the columns generally implies that the command /// was re-executed. /// /// /// /// /// /// /// DB_S_COMMANDREEXECUTED The command associated with this rowset was re-executed. If the properties DBPROP_OWNINSERT and /// DBPROP_OWNUPDATEDELETE are VARIANT_TRUE, the consumer will see its own changes. If the properties DBPROP_OWNINSERT or /// DBPROP_OWNUPDATEDELETE are VARIANT_FALSE, the rowset may see its changes. The order of the columns remains unchanged. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// DB_E_CANCELED IRowset::RestartPosition was canceled during notification. The next fetch position remains unmodified. /// /// /// /// /// /// DB_E_CANNOTRESTART The rowset was built over a live data stream (for example, a stock feed), and the position cannot be restarted. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider /// does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before restarting because the rowset will be regenerated. /// This may be required even if the provider supports a value of VARIANT_TRUE for DBPROP_CANHOLDROWS. For more information, see /// DBPROP_CANHOLDROWS and DBPROP_QUICKRESTART in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to reposition the next fetch position. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712877(v=vs.85) HRESULT RestartPosition ( HCHAPTER hChapter); [PreserveSig] HRESULT RestartPosition(HCHAPTER hReserved); } /// /// /// IRowsetBookmark is an optional interface on the TRowset cotype that enables rowsets that support bookmarks to set the next /// fetch position based on a bookmark. /// /// /// When IRowsetBookmark is present on a rowset, column 0 is the bookmark for the rows. Reading this column will obtain a bookmark /// value that can be used to reposition to the same row. Support for IRowsetBookmark does not imply that IRowsetLocate is /// supported on the rowset, although it does not preclude it. /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714246(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733ac2-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowsetBookmark { /// Sets the next fetch position for the rowset to be immediately before the specified bookmark. /// [in] The chapter handle. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER. /// [in] The length in bytes of the bookmark. /// /// [in] A pointer to a bookmark that identifies the row to be used. The bookmark can be for a designated row or either DBBMK_FIRST /// or DBBMK_LAST. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG cbBookmark was zero. /// pBookmark was a null pointer. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADBOOKMARK *pBookmark was invalid, incorrectly formed, or DBBMK_INVALID. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify (in the consumer) that had not yet returned, and the provider /// does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Appendix C, "OLE DB Properties." /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714382(v=vs.85) HRESULT PositionOnBookmark ( HCHAPTER // hChapter, DBBKMARK cbBookmark, const BYTE *pBookmark); [PreserveSig] HRESULT PositionOnBookmark(HCHAPTER hChapter, DBBKMARK cbBookmark, [In] IntPtr pBookmark); } /// /// /// The methods in IRowsetChange are used to update the values of columns in existing rows, delete existing rows, and insert new rows. /// /// IRowsetChange requires IAccessor and IRowset. /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715790(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733a05-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowsetChange { /// Deletes rows. /// /// [in] The chapter handle. Providers are allowed to ignore this argument. For maximum interoperability, consumers should set /// hChapter to DB_NULL_HCHAPTER. /// /// [in] The number of rows to be deleted. If cRows is zero, IRowsetChange::DeleteRows does not do anything. /// /// [in] An array of handles of the rows to be deleted. /// /// If rghRows includes a duplicate row handle, IRowsetChange::DeleteRows behaves as follows. If the row handle is valid, it /// is provider-specific whether the returned row status information for each row or a single instance of the row is set to /// DBROWSTATUS_S_OK. If the row handle is invalid, the row status information for each occurrence of the row contains the /// appropriate error. /// /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors /// or warnings occur while deleting a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If a warning occurs /// while deleting a row, the corresponding element is set as specified in S_OK. If an error occurs while deleting a row, the /// corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory for this array. If rgRowStatus is /// a null pointer, no row status information is returned. /// /// /// /// /// /// S_OK The method succeeded. All rows were successfully deleted. The following values can be returned in rgRowStatus: /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while deleting a row, but at least one row was successfully deleted. Successes and warnings /// can occur for the reasons listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer, and cRows was greater than or equal to one. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_ABORTLIMITREACHED The rowset was in immediate update mode, and the row was not deleted due to reaching a limit on the /// server, such as a query execution timing out. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while deleting all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// /// DB_E_NOTREENTRANT The consumer called this method while it was processing a notification, and it is an error to call this method /// while processing the specified DBREASON value. /// /// /// /// /// /// DB_E_NOTSUPPORTED The provider does not support this method, or the corresponding bit of DBPROP_UPDATABILITY is not set. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724362(v=vs.85) HRESULT DeleteRows ( HCHAPTER hChapter, // DBCOUNTITEM cRows, const HROW rghRows[], DBROWSTATUS rgRowStatus[]); [PreserveSig] HRESULT DeleteRows(HCHAPTER hChapter, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray)] HROW[] rghRows, [Out, Optional, MarshalAs(UnmanagedType.LPArray)] DBROWSTATUS[]? rgRowStatus); /// /// Sets data values in one or more columns in a row. /// /// Note /// IRowsetChange::SetData does not work in multi-threaded environments. /// /// /// [in] The handle of the row in which to set data. /// /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in /// IAccessor::CreateAccessor was zero), IRowsetChange::SetData does not set any data values. /// /// /// [in] A pointer to memory containing the new data values, at offsets that correspond to the bindings in the accessor. /// /// /// /// /// /// S_OK The method succeeded. The status of all columns bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while setting data for one or more columns, but data was successfully set for at least one /// column. To determine the columns for which data was returned, the consumer checks the status values. For a list of status values /// that can be returned by this method, see "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// /// DB_S_MULTIPLECHANGES The rowset was in immediate update mode, and updating the row caused more than one row to be updated in the /// data store. For more information, see DBPROP_REPORTMULTIPLECHANGES in Rowset Property Group in Appendix C. /// /// /// This return code takes precedence over DB_S_ERRORSOCCURRED. That is, if the conditions described here and in those described in /// DB_S_ERRORSOCCURRED both occur, the provider returns this code. When the consumer receives this return code, it should also check /// for the conditions described in DB_S_ERRORSOCCURRED. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pData was a null pointer, and the accessor was not a null accessor. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_ABORTLIMITREACHED The rowset was in immediate update mode, and the row was not updated due to reaching a limit on the /// server, such as a query execution timing out. /// /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor or was a reference accessor. Some providers may return /// DB_E_BADACCESSORHANDLE instead of this error code when command accessors are passed to the rowset. /// /// /// /// /// /// DB_E_BADROWHANDLE hRow was invalid. /// /// /// /// /// DB_E_CANCELED The change was canceled during notification. No columns are changed. /// /// /// /// /// /// DB_E_CANTCONVERTVALUE The data value for one or more columns couldn't be converted for reasons other than sign mismatch or data /// overflow, and the provider was unable to determine which columns couldn't be converted. Providers that can detect which columns /// could not be converted return DB_S_ERRORSOCCURRED and set the status flag for the columns that couldn't be converted to DBSTATUS_E_CANTCONVERTVALUE. /// /// /// /// /// /// /// DB_E_CONCURRENCYVIOLATION The rowset was using optimistic concurrency and the value of a column has been changed since the /// containing row was last fetched or resynchronized. IRowsetChange::SetData returns this error only when the rowset is in /// immediate update mode. /// /// /// /// /// /// /// DB_E_DATAOVERFLOW Conversion failed because the data value for one or more columns overflowed the type used by the provider and /// the provider was unable to determine which columns caused the overflow. Providers that can detect which columns caused the /// overflow return DB_S_ERRORSOCCURRED and set the status flag for the columns in violation to DBSTATUS_E_DATAOVERFLOW. /// /// /// /// /// /// DB_E_DELETEDROW hRow referred to a row with a pending delete or for which a deletion had been transmitted to the data store. /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while setting data for one or more columns, and data was not successfully set for any /// columns. To determine the columns for which values were invalid, the consumer checks the status values. For a list of status /// values that can be returned by this method, see "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// /// DB_E_INTEGRITYVIOLATION The data violated the integrity constraints for one or more columns of the rowset, and the provider was /// unable to determine which columns violated the integrity constraints. Providers that can detect which columns violated the /// integrity constraints return DB_S_ERRORSOCCURRED and set the status flag for the columns in violation to DBSTATUS_E_INTEGRITYVIOLATION. /// /// /// /// /// /// /// DB_E_MAXPENDCHANGESEXCEEDED The number of rows that have pending changes has exceeded the limit specified by the /// DBPROP_MAXPENDINGROWS property. /// /// /// /// /// /// /// DB_E_NEWLYINSERTED DBPROP_CHANGEINSERTEDROWS was VARIANT_FALSE, and hRow referred to a row for which the insertion has been /// transmitted to the data store. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The consumer called this method while it was processing a notification, and it is an error to call this method /// while processing the specified DBREASON value. /// /// /// /// /// /// DB_E_NOTSUPPORTED The provider does not support this method, or the corresponding bit of DBPROP_UPDATABILITY is not set. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to update the row, or the row was not in a state /// suitable for updating. (Typical reasons for returning this code are the row is read-only, or changes have not yet been committed /// on a rowset in delayed update mode.) /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721232(v=vs.85) HRESULT SetData ( HROW hRow, HACCESSOR // hAccessor, void *pData); [PreserveSig] HRESULT SetData([In] HROW hRow, [In] HACCESSOR hAccessor, [In] IntPtr pData); /// Creates and initializes a new row. /// /// [in] The chapter handle. Providers are allowed to ignore this argument. For maximum interoperability, consumers should set /// hChapter to DB_NULL_HCHAPTER. /// /// /// [in] The handle of the accessor to use. /// /// If hAccessor is a null accessor (that is, an accessor for which cBindings in IAccessor::CreateAccessor was zero), pData is /// ignored and the rows are initialized as specified in the Comments. Thus, the role of a null accessor is to construct a default /// row; it is a convenient way for a consumer to obtain a handle for a new row without having to set any values in that row /// initially. Passing an accessor with all columns set to DB_S_IGNORE is equivalent to passing a null accessor. /// /// /// /// [in] A pointer to memory containing the new data values, at offsets that correspond to the bindings in the accessor. /// /// /// /// [out] A pointer to memory in which to return the handle of the new row. If this is a null pointer, no reference count is held on /// the row. Consumers should set this to null if they do not require the ability to make further changes to, or retrieve data from, /// the newly inserted row. Whether or not default or computed values from the server are available when calling /// IRowset::GetData for this row handle depends on the setting of the DBPROP_SERVERDATAONINSERT. If /// IRowsetChange::InsertRow returns an error and phRow is not a null pointer on input, *phRow is set to null on output and no /// row handle is returned. /// /// /// Note /// /// Passing in a null pointer for phRow or releasing the row handle returned in *phRow does not release the row until the change is /// transmitted to the data store. If DBPROP_CANHOLDROWS is VARIANT_FALSE and the rowset is in deferred update mode, then, in /// addition to freeing any reference counts on the row handle, the consumer must call IRowsetUpdate::Update in order to /// transmit the pending change to the data store before attempting to insert or retrieve any additional rows. /// /// /// /// /// /// /// /// S_OK The method succeeded. The status of all columns bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while setting data for one or more columns, but data was successfully set for at least one /// column. To determine the columns for which values were invalid, the consumer checks the status values. For a list of status /// values that can be returned by this method, see "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pData was a null pointer, and hAccessor was not a null accessor. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to instantiate the row. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_ABORTLIMITREACHED The rowset was in immediate update mode, and the row was not inserted due to reaching a limit on the /// server, such as a query execution timing out. /// /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor or was a reference accessor. Some providers may return /// DB_E_BADACCESSORHANDLE instead of this error code when command accessors are passed to the rowset. /// /// /// /// /// /// DB_E_CANCELED The insertion was canceled during notification. The row was not inserted. /// /// /// /// /// /// DB_E_CANTCONVERTVALUE The data value for one or more columns could not be converted for reasons other than sign mismatch or data /// overflow, and the provider was unable to determine which columns couldn't be converted. Providers that can detect which columns /// could not be converted return DB_S_ERRORSOCCURRED and set the status flag for the columns that couldn't be converted to DBSTATUS_E_CANTCONVERTVALUE. /// /// /// /// /// /// /// DB_E_DATAOVERFLOW Conversion failed because the data value for one or more columns overflowed the type used by the provider and /// the provider was unable to determine which columns caused the overflow. Providers that can detect which columns caused the /// overflow return DB_S_ERRORSOCCURRED and set the status flag for the columns in violation to DBSTATUS_E_DATAOVERFLOW. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while setting data for one or more columns, and data was not successfully set for any /// columns. To determine the columns for which values were invalid, the consumer checks the status values. For a list of status /// values that can be returned by this method, see "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// /// DB_E_INTEGRITYVIOLATION The data violated the integrity constraints for one or more columns of the rowset, and the provider was /// unable to determine which columns violated the integrity constraints. Providers that can detect which columns violated the /// integrity constraints return DB_S_ERRORSOCCURRED and set the status flag for the columns in violation to DBSTATUS_E_INTEGRITYVIOLATION. /// /// /// /// /// /// /// DB_E_MAXPENDCHANGESEXCEEDED The number of rows that have pending changes has exceeded the limit specified by the /// DBPROP_MAXPENDINGROWS property. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer, and the method has not yet returned. /// /// /// /// /// DB_E_NOTSUPPORTED The provider does not support this method, or the corresponding bit of DBPROP_UPDATABILITY is not set. /// /// /// /// /// DB_E_ROWLIMITEXCEEDED Creating another row would have exceeded the total number of active rows supported by the rowset. /// /// The provider does not allow a rowset containing more than DBPROP_MAXROWS rows, and the insert would cause the rowset to exceed /// this limit. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The consumer attempted to insert a new row before releasing previously retrieved row handles or transmitting /// pending changes to the data store, and DBPROP_CANHOLDROWS is VARIANT_FALSE. /// /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to insert a new row. If the rowset is in delayed update /// mode, this error might not be returned until IRowsetUpdate::Update is called. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716921(v=vs.85) HRESULT InsertRow ( HCHAPTER hChapter, // HACCESSOR hAccessor, void *pData, HROW *phRow); [PreserveSig] HRESULT InsertRow([In] HCHAPTER hChapter, [In] HACCESSOR hAccessor, [In] IntPtr pData, out HROW phRow); } /// The IRowsetChapterMember interface detects whether or not a row is a member of a chapter. // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725430(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733aa8-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowsetChapterMember { /// Determines whether or not a row is a member of a chapter. /// /// [in] The chapter handle identifying the chapter in which the row is to be tested for membership. Providers should return S_OK if /// hRow is a member of the rowset identified by hChapter. An hChapter value of DB_NULL_HCHAPTER refers to the entire rowset. For a /// chaptered rowset, such as one involved in a hierarchy or in a filter or sort operation, this includes hRows that are members of /// any chapter of the rowset. Providers that do not support access to the unchaptered rowset may return DB_E_BADCHAPTER. /// /// [in] The row handle. /// /// /// /// /// S_FALSE The method succeeded, and the row handle is not a member of this chapter. /// /// /// /// /// S_OK The method succeeded, and the row handle is a member of the chapter. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADROWHANDLE hRow is invalid. /// /// /// /// /// DB_E_BADCHAPTER hChapter is invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722631(v=vs.85) HRESULT IsRowInChapter ( HCHAPTER hChapter, // HROW hRow); [PreserveSig] HRESULT IsRowInChapter([In] HCHAPTER hChapter, [In] HROW hRow); } /// /// IRowsetCurrentIndex is the interface for determining and selecting a specific index for a rowset. This is limited to rowsets /// that expose IRowsetIndex. IRowsetCurrentIndex provides a mechanism for providers to reorder their rows without /// reopening the rowset. This interface can be effective for both integrated and nonintegrated indexes. For a complete description of /// indexes, see Index Rowsets and Integrated Indexes. /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709700(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733abd-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowsetCurrentIndex : IRowsetIndex { /// Returns information about the index rowset capabilities. /// [out] A pointer to memory in which to return the number of key columns in the index. /// /// /// [out] A pointer to memory in which to return an array of DBINDEXCOLUMNDESC structures in key column order. The size of the array /// is equal to *pcKeyColumns. /// /// /// The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with /// IMalloc::Free when it no longer needs the structures. If *pcKeyColumns is zero on output or if an error occurs, the /// provider does not allocate any memory and ensures that *prgIndexColumnDesc is a null pointer on output. /// /// For more information, see IIndexDefinition::CreateIndex. /// /// /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgIndexPropertySets. /// *pcIndexPropertySets is the total number of property sets for which the provider supports at least one property in the Index /// property group. If an error occurs, *pcIndexPropertySets is set to zero. /// /// /// /// [out] A pointer to memory in which to return an array of DBPROPSET structures. One structure is returned for each property set /// that contains at least one property belonging to the Index property group. For information about the properties in the Index /// property group that are defined by OLE DB, see Index Property Group in Appendix C. /// /// /// The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with /// IMalloc::Free when it no longer needs the structures. Before calling IMalloc::Free for *prgPropertySets, the /// consumer should call IMalloc::Free for the rgProperties element within each element of *prgPropertySets. The consumer must /// also call VariantClear for the vValue member of each DBPROP structure in order to prevent a memory leak in cases where the /// variant contains a reference type (such as a BSTR.) If *pcIndexPropertySets is zero on output or if an error occurs, the provider /// does not allocate any memory and ensures that *prgIndexPropertySets is a null pointer on output. /// /// For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pcKeyColumns, prgIndexColumnDesc, pcIndexPropertySets, or prgIndexPropertySets was a null pointer. /// /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column description structures or /// properties of the index. /// /// /// /// /// /// DB_E_NOINDEX The rowset uses integrated indexes, and there is no current index. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713717(v=vs.85) [PreserveSig] new HRESULT GetIndexInfo(out DBORDINAL pcKeyColumns, out SafeIMallocHandle prgIndexColumnDesc, out uint pcIndexPropertySets, out SafeIMallocHandle prgIndexPropertySets); /// /// Allows direct positioning at a key value within the current range established by the IRowsetIndex::SetRange method. /// /// /// /// [in] The handle of the accessor to use. This accessor must meet the following criteria, which are illustrated with a key that /// consists of columns A, B, and C, where A is the most significant column and C is the least significant column: /// /// /// /// /// /// For each key column this accessor binds, it must also bind all more significant key columns. For example, the accessor can bind /// column A, columns A and B, or columns A, B, and C. /// /// /// /// /// /// /// Key columns must be bound in order from most significant key column to least significant key column. For example, if the accessor /// binds columns A and B, the first binding must bind column A and the second binding must bind column B. /// /// /// /// /// /// /// If the accessor binds any non-key columns, key columns must be bound first. For example, if the accessor binds columns A, B, and /// the bookmark column, the first binding must bind column A, the second binding must bind column B, and the third binding must bind /// the bookmark column. /// /// /// /// /// /// If the accessor does not meet these criteria, the method returns DB_E_BADBINDINFO or a status of DBSTATUS_E_BADACCESSOR for the /// offending column. /// /// /// If hAccessor is the handle of a null accessor (cBindings in IAccessor::CreateAccessor was zero), IRowsetIndex::Seek /// does not change the next fetch position. /// /// /// /// [in] The number of bindings in hAccessor for which *pData contains valid data. IRowsetIndex::Seek retrieves data from the /// first cKeyValues key columns from *pData. For example, suppose the accessor binds columns A, B, and C of the key in the previous /// example and cKeyValues is 2. IRowsetIndex::Seek retrieves data for columns A and B. /// /// /// [in] A pointer to a buffer containing the key values to which to seek, at offsets that correspond to the bindings in the accessor. /// /// /// /// [in] A bitmask describing the options for the IRowsetIndex::Seek method. The values in DBSEEKENUM have the meanings /// described in the following table. /// /// /// /// Value /// Description /// /// /// DBSEEK_FIRSTEQ /// First key with values equal to the values in * pData, in index order. /// /// /// DBSEEK_LASTEQ /// Last key with values equal to the values in * pData. /// /// /// DBSEEK_AFTEREQ /// /// Last key with values equal to the values in * pData or, if there are no keys equal to the values in * pData, first /// key with values after the values in * pData, in index order. /// /// /// /// DBSEEK_AFTER /// First key with values following the values in * pData, in index order. /// /// /// DBSEEK_BEFOREEQ /// /// First key with values equal to the values in * pData or, if there are no keys equal to the values in * pData, last /// key with values before the values in * pData, in index order. /// /// /// /// DBSEEK_BEFORE /// Last key with values before the values in * pData, in index order. /// /// /// dwSeekOptions examples /// The following table shows the expected results when given the columns and index value for the DBSEEK predicates above. /// /// /// Col 1 /// Col 2 /// Col 3 /// With index setting of /// Predicate /// Result /// /// /// 0 1 2 3 /// /// /// index = col1 asc /// BEFORE (2) BEFOREEQ (2) /// (1) (2) /// /// /// 1 2 2 3 /// 1 2 3 4 /// /// index = (col1 asc) /// BEFOREEQ (2) AFTEREQ (2) /// (2,2) (2,3) /// /// /// 1 3 3 4 /// 4 3 3 1 /// 0 1 2 3 /// index = (col1 asc, col2 desc) /// BEFOREEQ (3,3) AFTEREQ (3,3) /// (3,3,1) (3,3,2) /// /// /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG dwSeekOptions was invalid. /// hAccessor was the handle of a null accessor. /// cKeyValues was zero or was greater than the number of bindings specified in hAccessor. /// pData was a null pointer. /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of /// this error code when command accessors are passed to the rowset. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while transferring data for one or more key columns. To determine the columns for which /// values were invalid, the consumer checks the status values. For a list of status values that can be returned by this method, see /// "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// DB_E_NOINDEX The rowset uses integrated indexes, and there is no current index. /// /// /// /// /// DB_E_NOTFOUND No key value matching the described characteristics could be found within the current range. /// /// /// /// /// /// DB_E_NOTREENTRANT The consumer called this method while it was processing a notification, and it is an error to call this method /// while processing the specified DBREASON value. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Appendix C: OLE DB Properties. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723942(v=vs.85) [PreserveSig] new HRESULT Seek([In] HACCESSOR hAccessor, DBORDINAL cKeyValues, [In] IntPtr pData, DBSEEK dwSeekOptions); /// Restricts the set of row entries visible through calls to IRowset::GetNextRows and IRowsetIndex::Seek. /// /// [in] /// /// The handle of the accessor to use for both *pStartData and *pEndData. This accessor must meet the following criteria, which are /// illustrated with a key that consists of columns A, B, and C, where A is the most significant column and C is the least /// significant column: /// /// /// /// /// /// For each key column this accessor binds, it must also bind all more significant key columns. For example, the accessor can bind /// column A, columns A and B, or columns A, B, and C. /// /// /// /// /// /// /// Key columns must be bound in order from most significant key column to least significant key column. For example, if the accessor /// binds columns A and B, the first binding must bind column A and the second binding must bind column B. /// /// /// /// /// /// /// If the accessor binds any non-key columns, key columns must be bound first. For example, if the accessor binds columns A, B, and /// the bookmark column, the first binding must bind column A, the second binding must bind column B, and the third binding must bind /// the bookmark column. /// /// /// /// /// /// If the accessor does not meet these criteria, the method returns DB_E_BADBINDINFO or a status of DBSTATUS_E_BADACCESSOR for the /// offending column. /// /// /// If hAccessor is the handle of a null accessor (cBindings in IAccessor::CreateAccessor was zero), /// IRowsetIndex::SetRange does not set a range. /// /// /// /// [in] /// /// The number of bindings in hAccessor for which *pStartData contains valid data. IRowsetIndex::SetRange retrieves data from /// the first cStartKeyValues key columns from *pStartData. For example, suppose the accessor binds columns A, B, and C of the key in /// the previous example and that cStartKeyValues is 2. IRowsetIndex::SetRange retrieves data for columns A and B. /// /// /// /// [in] /// /// A pointer to a buffer containing the starting key values of the range, at offsets that correspond to the bindings in the accessor. /// /// /// /// [in] /// /// The number of bindings in hAccessor for which *pEndData contains valid data. IRowsetIndex::SetRange retrieves data from /// the first cEndKeyValues key columns from *pEndData. For example, suppose the accessor binds columns A, B, and C of the key in the /// previous example and that cEndKeyValues is 2. IRowsetIndex::SetRange retrieves data for columns A and B. /// /// /// /// [in] /// /// A pointer to a buffer containing the ending key values of the range, at offsets that correspond to the bindings in the accessor. /// /// /// /// [in] /// A bitmask describing the options of the range. The values in DBRANGEENUM have the meanings described in the following table. /// /// /// Value /// Description /// /// /// DBRANGE_INCLUSIVESTART /// The start boundary is inclusive (the default). /// /// /// DBRANGE_EXCLUSIVESTART /// The start boundary is exclusive. /// /// /// DBRANGE_INCLUSIVEEND /// The end boundary is inclusive (the default). /// /// /// DBRANGE_EXCLUSIVEEND /// The end boundary is exclusive. /// /// /// DBRANGE_EXCLUDENULLS /// Exclude NULLs from the range. /// /// /// DBRANGE_PREFIX /// /// Use * pStartData as a prefix. pEndData must be a null pointer. Prefix matching can be specified entirely using the /// inclusive and exclusive flags. However, because prefix matching is an important common case, this flag enables the consumer to /// specify only the * pStartData values and enables the provider to interpret this request quickly. /// /// /// /// DBRANGE_MATCH /// /// Set the range to all keys that match * pStartData. * pStartData must specify a full key. pEndData must be a /// null pointer. Used for fast equality match. /// /// /// /// DBRANGE_MATCH_N_MASK /// Equal to 0xff. /// /// /// DBRANGE_MATCH_N_SHIFT /// Equal to 24 to indicate the number of bits to shift to get the number N. /// /// /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG dwRangeOptions was invalid. /// dwRangeOptions included DBRANGE_PREFIX or DBRANGE_MATCH, and pEndData was not a NULL pointer. /// /// dwRangeOptions was DBRANGE_MATCH_N, and the provider did not support that option. For more information about DBRANGE_MATCH_N, see /// "Equality Matching." /// /// cStartKeyValues was not zero, and pStartData was a null pointer. /// cEndKeyValues was not zero, and pEndData was a null pointer. /// hAccessor was the handle of a null accessor. /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of /// this error code when command accessors are passed to the rowset. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED An error occurred while transferring data for one or more key columns. To determine the columns for which /// values were invalid, the consumer checks the status values. For a list of status values that can be returned by this method, see /// "Status Values Used When Setting Data" in Status. /// /// /// /// /// /// DB_E_NOINDEX The rowset uses integrated indexes, and there is no current index. /// /// /// /// Comments /// /// If this method performs deferred accessor validation and that validation takes place before any data is transferred, it can also /// return any of the following return codes for the reasons listed in the corresponding DBBINDSTATUS values in IAccessor::CreateAccessor: /// /// /// /// /// E_NOINTERFACE /// /// /// /// /// DB_E_BADBINDINFO /// /// /// /// /// DB_E_BADORDINAL /// /// /// /// /// DB_E_BADSTORAGEFLAGS /// /// /// /// /// DB_E_UNSUPPORTEDCONVERSION /// /// /// /// /// A range defines a view in the index containing a contiguous set of key values. The *pStartData and *pEndData values always /// specify the starting and ending positions in the range, respectively. Therefore, for an ascending index, *pStartData contains the /// smaller value and *pEndData contains the larger value; for a descending index, *pStartData contains the larger value and /// *pEndData contains the smaller value. /// /// /// As long as the *pStartData and *pEndData values specified are valid for the column, IRowsetIndex::SetRange should succeed, /// even if the start and end values are outside of the range of values contained in the index. If the index does not contain any /// rows within the range, calling IRowset::GetNextRows after the call to IRowsetIndex::SetRange should return DB_S_ENDOFROWSET. /// /// /// A range on the entire index is defined by calling IRowsetIndex::SetRange (hAcc, 0, NULL, 0, NULL, 0). When a range is set, /// IRowsetIndex::Seek can position only to rows in the current range. /// /// For information about how IRowsetIndex::SetRange transfers data from *pDataStart and *pDataEnd, see Setting Data. /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725416(v=vs.85) HRESULT SetRange ( HACCESSOR hAccessor, // DBORDINAL cStartKeyColumns, void *pStartData, DBORDINAL cEndKeyColumns, void *pEndData, DBRANGE dwRangeOptions); [PreserveSig] new HRESULT SetRange([In] HACCESSOR hAccessor, DBORDINAL cStartKeyColumns, [In] IntPtr pStartData, DBORDINAL cEndKeyColumns, [In] IntPtr pEndData, DBRANGE dwRangeOptions); /// Gets the current index on the rowset. /// [out] The DBID of the active index on the base table. /// /// /// /// /// S_OK The method succeeded. If there is no current index, ppIndexID is set to NULL. /// /// /// /// /// E_INVALIDARG ppIndexID was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return ppIndexID. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715829(v=vs.85) HRESULT GetIndex ( DBID **ppIndexID); [PreserveSig] HRESULT GetIndex(out IntPtr ppIndexID); /// Sets the current index on the rowset. /// [in] The DBID of the current index on the rowset. /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_S_COLUMNSCHANGED The metadata for the rowset changed based on the index selected. The provider had to reexecute the command /// for the newly selected index, and the order of the columns changed. /// /// /// /// /// /// E_INVALIDARG pIndexID was a null pointer. /// /// /// /// /// DB_E_BADINDEXID *pIndexID was an invalid index ID. /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before changing the index because the rowset will be /// regenerated. This may be required even if the provider supports a value of VARIANT_TRUE for DBPROP_CANHOLDROWS. For more /// information, see DBPROP_CANHOLDROWS in Appendix C. /// /// /// /// /// /// DB_E_NOINDEX The index specified in pIndexID did not exist. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709703(v=vs.85) HRESULT SetIndex ( DBID *pIndexID); [PreserveSig] HRESULT SetIndex(in DBID pIndexID); } /// Gives an exact position and and exact rowcount for a given bookmark into the Rowset. // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965357(v=vs.85) [PInvokeData("oledb.h")] [ComImport, Guid("0c733a7f-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IRowsetExactScroll : IRowsetScroll { /// Adds a reference count to an existing row handle. /// [in] The number of rows for which to increment the reference count. /// /// [in] An array of row handles for which to increment the reference count. The reference count of row handles is incremented by one /// for each time they appear in the array. /// /// /// [out] An array with cRows elements in which to return the new reference count for each row handle. The consumer allocates memory /// for this array. If rgRefCounts is a null pointer, no reference counts are returned. /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors /// occur while incrementing the reference count of a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an /// error occurs while incrementing the reference count of a row, the corresponding element is set as specified in /// DB_S_ERRORSOCCURRED. The consumer allocates memory for this array. If rgRowStatus is a null pointer, no row statuses are returned. /// /// /// /// /// /// /// S_OK The method succeeded. The reference count of all rows was successfully incremented. The following value can be returned in *prgRowStatus: /// /// The reference count of the row was successfully incremented. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while incrementing the reference count of a row, but the reference count of at least one /// row was incremented. Successes can occur for the reason listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer, and cRows was not zero. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while incrementing the reference count of all of the rows. Errors can occur for the reasons /// listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719619(v=vs.85) HRESULT AddRefRows( DBCOUNTITEM cRows, const // HROW rghRows[], DBREFCOUNT rgRefCounts[], DBROWSTATUS rgRowStatus[]); [PreserveSig] new HRESULT AddRefRows(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] HROW[] rghRows, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBREFCOUNT[]? rgRefCounts, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBROWSTATUS[]? rgRowStatus); /// Retrieves data from the rowset's copy of the row. /// /// [in] The handle of the row from which to get the data. /// /// Warning /// /// The consumer must ensure that hRow contains a valid row handle; the provider might not validate hRow before using it. The result /// of passing the handle of a deleted row is provider-specific, although the provider cannot terminate abnormally. For example, the /// provider might return DB_E_BADROWHANDLE, DB_E_DELETEDROW, or it might get data from a different row. The result of passing an /// invalid row handle in hRow is undefined. /// /// /// /// /// /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in /// IAccessor::CreateAccessor was zero), IRowset::GetData does not get any data values. /// /// /// Warning /// /// The consumer must ensure that hAccessor contains a valid accessor handle; the provider might not validate hAccessor before using /// it. The result of passing an invalid accessor handle in hAccessor is undefined. /// /// /// /// /// [out] A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer. This pointer must be a /// valid pointer to a contiguous block of consumer-owned memory into which the data will be written. /// /// /// /// /// /// /// S_OK The method succeeded. The status of all columns bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED. /// /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while returning data for one or more columns, but data was successfully returned for at /// least one column. To determine the columns for which data was returned, the consumer checks the status values. For a list of /// status values that can be returned by this method, see "Status Values Used When Getting Data" in Status. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pData was a null pointer, and the accessor was not a null accessor. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// /// DB_E_BADACCESSORHANDLE hAccessor was invalid. Providers are not required to check for this condition, because doing so might slow /// the method significantly. /// /// /// /// /// /// /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor. Some providers may return DB_E_BADACCESSORHANDLE instead of /// this error code when command accessors are passed to the rowset. /// /// /// /// /// /// /// DB_E_BADROWHANDLE hRow was invalid. Providers are not required to check for this condition, because doing so might slow the /// method significantly. /// /// /// /// /// /// /// DB_E_DELETEDROW hRow referred to a pending delete row or a row for which a deletion had been transmitted to the data store. /// Providers are not required to check for this condition, because doing so might slow the method significantly. /// /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while returning data for all columns. To determine what errors occurred, the consumer checks /// the status values. For a list of status values that can be returned by this method, see "Status Values Used When Getting Data" in Status. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716988(v=vs.85) HRESULT GetData ( HROW hRow, HACCESSOR // hAccessor, void *pData); [PreserveSig] new HRESULT GetData([In] HROW hRow, [In] HACCESSOR hAccessor, [Out] IntPtr pData); /// Fetches rows sequentially, remembering the previous position. /// /// [in] The chapter handle designating the rows to fetch. For nonchaptered rowsets, the caller must set hChapter to /// DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset. /// /// /// /// [in] The signed count of rows to skip before fetching rows. Deleted rows that the provider has removed from the rowset are not /// counted in the skip. If this value is zero and cRows continues in the same direction as the previous call either to /// IRowset::GetNextRows or to IRowsetFind::FindNextRow with a null pBookmark value, the first row fetched will be the next /// row after the last one fetched in the previous call. If this value is zero and cRows reverses direction, the first row fetched /// will be the last one fetched in the previous call. /// /// /// lRowsOffset can be a negative number only if the value of the DBPROP_CANSCROLLBACKWARDS property is VARIANT_TRUE. A negative /// value means skipping the rows in a backward direction. There is no guarantee that skipping rows is done efficiently on a /// sequential rowset. If the data store resides on a remote server, there may be remote support for skipping without transferring /// the intervening records across the network but this is not guaranteed. For information about how the provider implements /// skipping, see the documentation for the provider. /// /// /// /// /// [in] The number of rows to fetch. A negative number means to fetch backward. cRows can be a negative number only if the value of /// the DBPROP_CANFETCHBACKWARDS property is VARIANT_TRUE. /// /// /// If cRows is zero, the provider sets *pcRowsObtained to zero and performs no further processing, returning immediately from the /// method invocation. No rows are fetched, the fetch direction and the next fetch position are unchanged, and lRowsOffset is ignored. /// /// /// If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific. /// /// /// /// [out] A pointer to memory in which to return the actual number of fetched rows. If a warning condition occurs, this number may be /// less than the number of rows available or requested and is the number of rows actually fetched before the warning condition /// occurred. If the consumer has insufficient permission to fetch all rows, IRowset::GetNextRows fetches all rows for which /// the consumer has sufficient permission and skips all other rows. If the method fails, *pcRowsObtained is set to zero. /// /// /// [out] A pointer to memory in which to return an array of handles of the fetched rows. /// /// If *prghRows is not a null pointer on input, it must be a pointer to consumer-allocated memory large enough to return the handles /// of the requested number of rows. If the consumer-allocated memory is larger than needed, the provider fills in as many row /// handles as specified by pcRowsObtained; the contents of the remaining memory are undefined. /// /// /// If *prghRows is a null pointer on input, the rowset allocates memory for the row handles and returns the address to this memory; /// the consumer releases this memory with IMalloc::Free after it releases the row handles. If *prghRows is a null pointer on /// input and *pcRowsObtained is zero on output or if the method fails, the provider does not allocate any memory and ensures that /// *prghRows is a null pointer on output. /// /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_S_ENDOFROWSET IRowset::GetNextRows reached the start or the end of the rowset or chapter or the start or end of the /// range on an index rowset and could not fetch all requested rows because the count extended beyond the end. The next fetch /// position is before the start or after the end of the rowset. The number of rows actually fetched is returned in *pcRowsObtained; /// this will be less than cRows. /// /// /// The rowset is being populated asynchronously, and no additional rows are available at this time. To determine whether additional /// rows may be available, the consumer should call IDBAsynchStatus::GetStatus or listen for the IDBAsynchNotify::OnStop notification. /// /// /// lRowsOffset indicated a position either more than one row before the first row of the rowset or more than one row after the last /// row, and the provider was a version 2.0 or greater provider. *pcRowsObtained is set to zero, and no rows are returned. /// /// /// /// /// /// /// DB_S_ROWLIMITEXCEEDED Fetching the number of rows specified in cRows would have exceeded the total number of active rows /// supported by the rowset, as reported by DBPROP_MAXOPENROWS. The number of rows that were actually fetched is returned in *pcRowsObtained. /// /// /// /// /// /// /// DB_S_STOPLIMITREACHED Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. /// Execution has been stopped because a resource limit has been reached. The number of rows that were actually fetched is returned /// in *pcRowsObtained. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pcRowsObtained or prghRows was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory to complete the request. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_BADSTARTPOSITION lRowsOffset indicated a position either more than one row before the first row of the rowset or more than /// one row after the last row, and the provider was a 1.x provider. /// /// /// /// /// /// DB_E_CANCELED Fetching rows was canceled during notification. No rows were fetched. /// /// /// /// /// DB_E_CANTFETCHBACKWARDS cRows was negative, and the rowset cannot fetch backward. /// /// /// /// /// DB_E_CANTSCROLLBACKWARDS lRowsOffset was negative, and the rowset cannot scroll backward. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider /// does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to fetch any of the rows; no rows were fetched. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709827(v=vs.85) HRESULT GetNextRows ( HCHAPTER hChapter, // DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, DBCOUNTITEM *pcRowsObtained, HROW **prghRows); [PreserveSig] new HRESULT GetNextRows([In] HCHAPTER hChapter, DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); /// Releases rows. /// [in] The number of rows to release. If cRows is zero, IRowset::ReleaseRows does not do anything. /// /// [in] An array of handles of the rows to be released. The row handles need not form a logical cluster; they may have been obtained /// at separate times and need not be for contiguous underlying rows. Row handles are decremented by one reference count for each /// time they appear in the array. /// /// /// [in] An array of cRows elements containing bitmasks indicating additional options to be specified when releasing a row. This /// parameter is reserved for future use and should be set to a null pointer. /// /// /// [out] An array with cRows elements in which to return the new reference count of each row. If rgRefCounts is a null pointer, no /// counts are returned. The consumer allocates, but is not required to initialize, memory for this array and passes the address of /// this memory to the provider. The provider returns the reference counts in the array. /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rghRows. If no errors /// or warnings occur while releasing a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an error or /// warning occurs while releasing a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer /// allocates memory for this array. If rgRowStatus is a null pointer, no row statuses are returned. /// /// /// /// /// /// S_OK The method succeeded. All rows were successfully released. The following values can be returned in *prgRowStatus: /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while releasing a row, but at least one row was successfully released. Successes and /// warnings can occur for the reasons listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer, and cRows was not equal to zero. /// /// /// /// /// /// E_UNEXPECTED DBPROP_BLOCKINGSTORAGEOBJECTS is VARIANT_TRUE, and IRowset::ReleaseRows is called on a row with an open /// storage object. If the consumer, on cleanup, encounters an error while releasing the row, it should release the storage object first. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while releasing all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719771(v=vs.85) HRESULT ReleaseRows ( DBCOUNTITEM cRows, // const HROW rghRows[], DBROWOPTIONS rgRowOptions[], DBREFCOUNT rgRefCounts[], DBROWSTATUS rgRowStatus[]); [PreserveSig] new HRESULT ReleaseRows(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] HROW[] rghRows, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] uint[]? rgRowOptions, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBREFCOUNT[]? rgRefCounts, [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBROWSTATUS[]? rgRowStatus); /// /// Repositions the next fetch position used by IRowset::GetNextRows or IRowsetFind::FindNextRow to its initial position ? that is, /// its position when the rowset was first created. /// /// /// /// /// /// /// S_OK The method succeeded. The provider did not have to re-execute the command, either because the rowset supports positioning on /// the first row without re-executing the command or because the rowset is already positioned on the first row. /// /// /// /// /// /// /// DB_S_COLUMNSCHANGED The order of the columns was not specified in the object that created the rowset. The provider had to /// re-execute the command to reposition the next fetch position to its initial position, and the order of the columns changed. /// /// /// The provider had to re-execute the command to reposition the next fetch position to its initial position, and columns were added /// or removed from the rowset. This is generally due to a change in the underlying schema and is extremely uncommon. /// /// /// This return code takes precedence over DB_S_COMMANDREEXECUTED. That is, if the conditions described here and in those described /// in DB_S_COMMANDREEXECUTED both occur, the provider returns this code. A change to the columns generally implies that the command /// was re-executed. /// /// /// /// /// /// /// DB_S_COMMANDREEXECUTED The command associated with this rowset was re-executed. If the properties DBPROP_OWNINSERT and /// DBPROP_OWNUPDATEDELETE are VARIANT_TRUE, the consumer will see its own changes. If the properties DBPROP_OWNINSERT or /// DBPROP_OWNUPDATEDELETE are VARIANT_FALSE, the rowset may see its changes. The order of the columns remains unchanged. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// DB_E_CANCELED IRowset::RestartPosition was canceled during notification. The next fetch position remains unmodified. /// /// /// /// /// /// DB_E_CANNOTRESTART The rowset was built over a live data stream (for example, a stock feed), and the position cannot be restarted. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider /// does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before restarting because the rowset will be regenerated. /// This may be required even if the provider supports a value of VARIANT_TRUE for DBPROP_CANHOLDROWS. For more information, see /// DBPROP_CANHOLDROWS and DBPROP_QUICKRESTART in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to reposition the next fetch position. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712877(v=vs.85) HRESULT RestartPosition ( HCHAPTER hChapter); [PreserveSig] new HRESULT RestartPosition(HCHAPTER hReserved); /// Compares two bookmarks. /// /// [in] The chapter handle. For nonchaptered rowsets or to designate the root rowset, the caller must set hChapter to DB_NULL_HCHAPTER. /// /// When comparing literal bookmarks and hChapter is DB_NULL_HCHAPTER, IRowsetLocate::Compare must return the same ordering as /// an arithmetic comparison. If hChapter is not DB_NULL_HCHAPTER, IRowsetLocate::Compare must reflect the ordering within /// that chapter. Also, the row designated by the special bookmarks DBBMK_FIRST or DBBMK_LAST depends on the chapter. /// /// /// [in] The length in bytes of the first bookmark. /// [in] A pointer to the first bookmark. This can be a pointer to DBBMK_FIRST or DBBMK_LAST. /// [in] The length in bytes of the second bookmark. /// [in] A pointer to the second bookmark. This can be a pointer to DBBMK_FIRST or DBBMK_LAST. /// /// /// [out] A pointer to memory in which to return a flag that specifies the result of the comparison. The returned flag will be one of /// the values in the following table. /// /// /// /// Value /// Description /// /// /// DBCOMPARE_LT /// The first bookmark is before the second. /// /// /// DBCOMPARE_EQ /// The two bookmarks are equal. /// /// /// DBCOMPARE_GT /// The first bookmark is after the second. /// /// /// DBCOMPARE_NE /// The bookmarks are not equal and not ordered. /// /// /// DBCOMPARE_NOTCOMPARABLE /// The two bookmarks cannot be compared. When to return DBCOMPARE_NOTCOMPARABLE: /// /// /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG cbBookmark1 or cbBookmark2 was zero. /// pBookmark1, pBookmark2, or pComparison was a null pointer. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADBOOKMARK *pBookmark1 or *pBookmark2 was invalid, incorrectly formed, or DBBMK_INVALID. /// /// /// /// /// Note /// /// Consumers should attempt to use only bookmarks that they have received from the provider. The provider is guaranteed to handle /// only bookmarks it gives out in a predictable manner. Attempting to use a random value as a bookmark is undefined; the provider /// may return DB_E_BADBOOKMARK, may return an unexpected row, or may terminate abnormally. /// /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709539(v=vs.85) HRESULT Compare ( HCHAPTER hChapter, // DBBKMARK cbBookmark1, const BYTE *pBookmark1, DBBKMARK cbBookmark2, const BYTE *pBookmark2, DBCOMPARE *pComparison); [PreserveSig] new HRESULT Compare([In] HCHAPTER hChapter, DBBKMARK cbBookmark1, [In] IntPtr pBookmark1, DBBKMARK cbBookmark2, [In] IntPtr pBookmark2, out DBCOMPARE pComparison); /// Fetches rows starting with the row specified by an offset from a bookmark. /// [in] Reserved for future use. Providers ignore this parameter. /// /// [in] The chapter handle. For nonchaptered rowsets or to designate the root rowset, the caller must set hChapter to DB_NULL_HCHAPTER. /// /// [in] The length in bytes of the bookmark. This must not be zero. /// /// [in] A pointer to a bookmark that identifies the base row to be used. This can be a pointer to DBBMK_FIRST or DBBMK_LAST. If /// lRowsOffset is zero, the provider fetches this row first; otherwise, the provider skips this and subsequent rows up to the count /// specified in the offset and then fetches the following rows. /// /// /// /// [in] The signed count of rows from the origin bookmark to the target row. Deleted rows that the provider has removed from the /// rowset are not counted in the skip. The first row fetched is determined by the bookmark and this offset. For example, if /// lRowsOffset is zero, the first row fetched is the bookmarked row; if lRowsOffset is 1, the first row fetched is the row after the /// bookmarked row; if lRowsOffset is ?1, the first row fetched is the row before the bookmarked row. /// /// lRowsOffset can be a negative number only if the value of the DBPROP_CANSCROLLBACKWARDS property is VARIANT_TRUE. /// /// /// /// [in] The number of rows to fetch. A negative number means to fetch backward. cRows can be a negative number only if the value of /// the DBPROP_CANFETCHBACKWARDS property is VARIANT_TRUE. /// /// /// If cRows is zero, no rows are fetched; the fetch direction and the next fetch position are unchanged, and the provider performs /// no processing, returning immediately from the method invocation. Specifically, lRowsOffset is ignored in this situation. /// /// /// If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific. /// /// See the Comments section for a full description of the semantics of lRowsOffset and cRows parameters. /// /// /// [out] A pointer to memory in which to return the actual number of fetched rows. If the consumer has insufficient permission to /// fetch all rows, IRowsetLocate::GetRowsAt fetches all rows for which the consumer has sufficient permission and skips all /// other rows. If the method fails, *pcRowsObtained is set to zero. /// /// /// [in/out] A pointer to memory in which to return an array of handles of the fetched rows. If *prghRows is not a null pointer on /// input, it must be a pointer to memory large enough to return the handles of the requested number of rows. If *prghRows is a null /// pointer on input, the rowset allocates memory for the row handles and returns the address to this memory. The consumer releases /// this memory with IMalloc::Free after it releases the row handles. If *prghRows was a null pointer on input and /// *pcRowsObtained is zero on output or if the method fails, the provider does not allocate any memory and ensures that *prghRows is /// a null pointer on output. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_S_BOOKMARKSKIPPED The following behavior is supported only on rowsets that set the DBPROP_BOOKMARKSKIPPED property to /// VARIANT_TRUE. If this property is VARIANT_FALSE, this return code is never returned. /// /// /// lRowsOffset was zero and the row specified by *pBookmark was deleted or is no longer a member of the rowset, or the row specified /// by the combination of *pBookmark and lRowsOffset is a row to which the consumer does not have access rights. /// IRowsetLocate::GetRowsAt skipped that row. The full count of actual rows (cRows) will be met if there are enough rows /// available. The array of returned row handles does not have gaps for missing rows; the returned count is the number of rows /// actually fetched. /// /// /// If a row is skipped, it is counted as one of the rows to be skipped for lRowsOffset. For example, if an offset of 1 is requested /// and the bookmark points to a row that is now missing, the offset is decremented by 1 and the provider begins by fetching the next row. /// /// /// If this condition occurs along with another warning condition, the method returns the code for the other warning condition. /// Therefore, whenever a consumer receives the return code for another warning condition, it should check to see whether this /// condition occurred. /// /// /// /// /// /// /// DB_S_ENDOFROWSET IRowsetLocate::GetRowsAt reached the start or the end of the rowset or chapter and could not fetch all of /// the requested rows because the count extended beyond the end. The number of rows actually fetched is returned in *pcRowsObtained; /// this will be less than cRows. /// /// /// The rowset is being populated asynchronously, and no additional rows are available at this time. To determine whether additional /// rows may be available, the consumer should call IDBAsynchStatus::GetStatus or listen for the /// IDBAsynchNotify::OnStop notification. /// /// /// lRowsOffset indicated a position either more than one row before the first row of the rowset or more than one row after the last /// row, and the provider was a version 2.0 or later provider. *pcRowsObtained is set to zero, and no rows are returned. /// /// /// /// /// /// /// DB_S_ROWLIMITEXCEEDED Fetching the number of rows specified in cRows would have exceeded the total number of active rows /// supported by the rowset. The number of rows that were actually fetched is returned in *pcRowsObtained. This condition can occur /// only when there are more rows available than can be handled by the rowset. Therefore, this condition never conflicts with those /// described in DB_S_ENDOFROWSET and DB_S_STOPLIMITREACHED, both of which imply that no more rows were available. /// /// /// /// /// /// /// DB_S_STOPLIMITREACHED Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. /// Execution has been stopped because a resource limit has been reached. The number of rows that were actually fetched is returned /// in *pcRowsObtained. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG cbBookmark was zero, or pBookmark was a null pointer. /// pcRowsObtained or prghRows was a null pointer. /// /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to instantiate the rows or return the row handles. /// /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADBOOKMARK *pBookmark was invalid, incorrectly formed, or DBBMK_INVALID. /// /// *pBookmark did not match any rows in the rowset. This includes the case when the row corresponding to the bookmark has been /// deleted and DBPROP_BOOKMARKSKIPPED was VARIANT_FALSE. /// /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered, and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_BADSTARTPOSITION lRowsOffset indicated a position either more than one row before the first row of the rowset or more than /// one row after the last row, and the provider was a 1.x provider. /// /// /// /// /// /// DB_E_CANTFETCHBACKWARDS cRows was negative, and the rowset cannot fetch backward. /// /// /// /// /// DB_E_CANTSCROLLBACKWARDS lRowsOffset was negative, and the rowset cannot scroll backward. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to fetch any of the rows; no rows were fetched. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723031(v=vs.85) HRESULT GetRowsAt ( HWATCHREGION hReserved1, // HCHAPTER hChapter, DBBKMARK cbBookmark, const BYTE *pBookmark, DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, DBCOUNTITEM // *pcRowsObtained, HROW **prghRows); [PreserveSig] new HRESULT GetRowsAt([In, Optional] HWATCHREGION hReserved1, [In] HCHAPTER hChapter, DBBKMARK cbBookmark, [In] IntPtr pBookmark, DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); /// Fetches the rows that match the specified bookmarks. /// /// [in] The chapter handle. For nonchaptered rowsets or to designate the root rowset, the caller must set hChapter to DB_NULL_HCHAPTER. /// /// /// [in] The number of rows to fetch. /// /// If cRows is zero, no rows are fetched; the fetch direction and the next fetch position are unchanged, and the provider performs /// no processing, returning immediately from the method invocation. /// /// /// If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific. /// /// /// [in] An array containing the length in bytes of each bookmark. /// /// [in] An array containing a pointer to the bookmark of each row sought. These cannot be pointers to a standard bookmark /// (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). If rgpBookmarks contains a duplicate bookmark, the corresponding row is fetched and the /// reference count incremented once for each occurrence of the bookmark. /// /// /// [out] An array with cRows elements in which to return the handles of the fetched rows. The consumer allocates this array but is /// not required to initialize the elements of it. In each element of this array, if the row was fetched, the provider returns the /// handle of the row identified by the bookmark in the corresponding element of rgpBookmarks. If the row was not fetched, the /// provider returns DB_NULL_HROW. /// /// /// [out] An array with cRows elements in which to return values indicating the status of each row specified in rgpBookmarks. If no /// errors or warnings occur while fetching a row, the corresponding element of rgRowStatus is set to DBROWSTATUS_S_OK. If an error /// occurs while fetching a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. The consumer allocates memory /// for this array but is not required to initialize it. If rgRowStatus is a null pointer, no row statuses are returned. /// /// /// /// /// /// S_OK The method succeeded. All rows were successfully fetched. The following value can be returned in rgRowStatus: /// The row was successfully fetched. The corresponding element of rgRowStatus contains DBROWSTATUS_S_OK. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while fetching a row, but at least one row was successfully fetched. Successes can occur /// for the reasons listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG rghRows was a null pointer. /// rgcbBookmarks or rgpBookmarks was a null pointer. /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the row handles. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered, and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while fetching all of the rows. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Rowset Properties in Appendix C. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725420(v=vs.85) HRESULT GetRowsByBookmark ( HCHAPTER // hChapter, DBCOUNTITEM cRows, const DBBKMARK rgcbBookmarks[], const BYTE *rgpBookmarks[], HROW rghRows[], DBROWSTATUS rgRowStatus[]); [PreserveSig] new HRESULT GetRowsByBookmark([In] HCHAPTER hChapter, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBKMARK[] rgcbBookmarks, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] IntPtr[] rgpBookmarks, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] HROW[] rghRows, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBROWSTATUS[] rgRowStatus); /// Returns hash values for the specified bookmarks. /// /// [in] The chapter handle. hChapter is ignored. For maximum interoperability, consumers should set hChapter to DB_NULL_HCHAPTER. /// /// /// [in] The number of bookmarks to hash. If cBookmarks is zero, IRowsetLocate::Hash does not do anything. /// /// [in] An array containing the length in bytes for each bookmark. /// /// /// [in] An array of pointers to bookmarks. The bookmarks cannot be standard bookmarks (DBBMK_FIRST, DBBMK_LAST, DBBMK_INVALID). If /// rgpBookmarks contains a duplicate bookmark, a hash value is returned once for each occurrence of the bookmark. /// /// /// Warning /// /// The consumer must ensure that all bookmarks in rgpBookmarks are valid. The provider is not required to validate bookmarks before /// hashing them. Therefore, hash values might be returned for invalid bookmarks. /// /// /// /// /// [out] An array of cBookmarks hash values corresponding to the elements of rgpBookmarks. The consumer allocates, but is not /// required to initialize, memory for this array and passes the address of this memory to the provider. The provider returns the /// hash values in the array. /// /// /// [out] An array with cBookmarks elements in which to return values indicating the status of each bookmark specified in /// rgpBookmarks. If no errors occur while hashing a bookmark, the corresponding element of rgBookmarkStatus is set to /// DBROWSTATUS_S_OK. If an error occurs while hashing a bookmark, the corresponding element is set as specified in /// DB_S_ERRORSOCCURRED. The consumer allocates memory for this array but is not required to initialize it. If rgBookmarkStatus is a /// null pointer, no bookmark statuses are returned. /// /// /// /// /// /// S_OK The method succeeded. All bookmarks were successfully hashed. The following value can be returned in rgRowStatus: /// The bookmark was successfully hashed. The corresponding element of rgRowStatus contains DBROWSTATUS_S_OK. /// /// /// /// /// /// DB_S_ERRORSOCCURRED An error occurred while hashing a bookmark, but at least one bookmark was successfully hashed. Successes can /// occur for the reason listed under S_OK. The following errors can occur: /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG cBookmarks was not zero, and rgcbBookmarks or rgpBookmarks was a null pointer. /// rgHashedValues was a null pointer. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered, and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// DB_E_ERRORSOCCURRED Errors occurred while hashing all of the bookmarks. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709697(v=vs.85) HRESULT Hash ( HCHAPTER hChapter, DBBKMARK // cBookmarks, const DBBKMARK rgcbBookmarks[], const BYTE *rgpBookmarks[], DBHASHVALUE rgHashedValues[], DBROWSTATUS rgBookmarkStatus[]); [PreserveSig] new HRESULT Hash([In] HCHAPTER hChapter, DBBKMARK cBookmarks, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBKMARK[] rgcbBookmarks, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] IntPtr[] rgpBookmarks, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBHASHVALUE[] rgHashedValues, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBROWSTATUS[] rgBookmarkStatus); /// Gets the approximate position of a row corresponding to a specified bookmark. /// /// [in] The chapter handle designating the rows on which to position. For nonchaptered rowsets, the caller must set hChapter to /// DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset. /// /// /// [in] The length in bytes of the bookmark. If this is zero, pBookmark is ignored, *pcRows is set to the count of rows, and no /// position is returned in *pulPosition. /// /// /// [in] A pointer to a bookmark that identifies the row of which to find the position. This can be a pointer to DBBMK_FIRST or /// DBBMK_LAST. The consumer is not required to have permission to read the row. /// /// /// [out] A pointer to memory in which to return the position of the row identified by the bookmark. The returned number is /// one-based; that is, the first row in the rowset is 1 and the last row is equal to *pcRows. If *pcRows is zero, the provider sets /// *pulPosition to zero also, regardless of the bookmark that was passed. If pulPosition is a null pointer, no position is returned. /// In case of error, *pulPosition is not changed. /// /// /// [out] A pointer to memory in which to return the total number of rows. This number is zero if there are no rows. If pcRows is a /// null pointer, no count of rows is returned. In case of error, *pcRows is not changed. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG cbBookmark was not zero, and pBookmark was a null pointer. /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called and the object is in a zombie state. /// /// /// /// /// DB_E_BADBOOKMARK *pBookmark was invalid, incorrectly formed, or DBBMK_INVALID. /// /// *pBookmark did not match any of the rows in the rowset. This includes the case when the row corresponding to the bookmark was /// deleted and either DBPROP_BOOKMARKSKIPPED was VARIANT_FALSE or the provider is a 1.x provider that does not support getting the /// approximate position of a deleted row. /// /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered, and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712901(v=vs.85) HRESULT GetApproximatePosition ( HCHAPTER // hChapter, DBBKMARK cbBookmark, const BYTE *pBookmark, DBCOUNTITEM *pulPosition, DBCOUNTITEM *pcRows); [PreserveSig] new HRESULT GetApproximatePosition([In] HCHAPTER hChapter, DBBKMARK cbBookmark, [In] IntPtr pBookmark, out DBCOUNTITEM pulPosition, out DBCOUNTITEM pcRows); /// Fetches rows starting from a fractional position in the rowset. /// [in] Reserved for future use. Providers ignore this parameter. /// [in] The chapter handle. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER. /// [in] See ulDenominator below. /// /// [in] The provider determines the first row to fetch from the ratio of ulNumerator to ulDenominator, roughly using the formula: /// /// If the rowset is being populated asynchronously, ulNumerator and ulDenominator specify the relative position within the rows /// fetched so far. /// /// /// How accurately the provider applies this ratio is provider-specific. For example, if ulNumerator is 1 and ulDenominator is 2, /// some providers will fetch rows starting exactly halfway through the rowset while other providers will fetch rows starting 40 /// percent of the way through the rowset. /// /// However, all providers must handle the following conditions correctly. /// /// /// Condition /// IRowsetScroll::GetRowsAtRatio action /// /// /// ( ulNumerator = 0) AND ( cRows > 0) /// Fetches rows starting with the first row in the rowset. /// /// /// ( ulNumerator = 0) AND ( cRows < 0) /// Returns DB_S_ENDOFROWSET. /// /// /// ( ulNumerator = ulDenominator) AND ( cRows > 0) /// Returns DB_S_ENDOFROWSET. /// /// /// ( ulNumerator = ulDenominator) AND ( cRows < 0) /// Fetches rows starting with the last row in the rowset. /// /// /// /// /// /// [in] The number of rows to fetch. A negative number means to fetch backward. cRows can be a negative number only if the value of /// the DBPROP_CANFETCHBACKWARDS property is VARIANT_TRUE. The rows are returned in rowset-traversal order ? that is, the direction /// in which they were fetched. /// /// /// If cRows is zero, no rows are fetched. If the provider does not discover any other errors, the method returns S_OK; whether the /// provider checks for any other errors is provider-specific. /// /// /// /// [out] A pointer to memory in which to return the number of rows fetched. If the consumer has insufficient permissions to return /// all rows, IRowsetScroll::GetRowsAtRatio fetches all rows for which the consumer has sufficient permission and skips all /// other rows. If the method fails, *pcRowsObtained is set to 0. /// /// /// [in/out] A pointer to memory in which to return an array of handles of the fetched rows. If *prghRows is not a null pointer on /// input, it must be a pointer to memory large enough to return the handles of the requested number of rows. If *prghRows is a null /// pointer on input, the rowset allocates memory for the row handles and returns the address to this memory; the consumer releases /// this memory with IMalloc::Free after it releases the row handles. If *prghRows was a null pointer on input and /// *pcRowsObtained is zero on output or the method fails, the provider does not allocate any memory and ensures that *prghRows is a /// null pointer on output. /// /// /// /// /// /// S_OK The method succeeded. /// /// /// /// /// /// DB_S_ENDOFROWSET IRowsetScroll::GetRowsAtRatio reached the start or the end of the rowset or chapter and could not fetch /// all requested rows because the count extended beyond the end. The number of rows actually fetched is returned in *pcRowsObtained; /// this will be less than cRows. /// /// /// The rowset is being populated asynchronously, and no additional rows are available at this time. To determine whether additional /// rows may be available, the consumer should call IDBAsynchStatus::GetStatus or listen for the /// IDBAsynchNotify::OnStop notification. /// /// /// /// /// /// /// DB_S_ROWLIMITEXCEEDED Fetching the number of rows specified in cRows would have exceeded the total number of active rows /// supported by the rowset. The number of rows that were actually fetched is returned in *pcRowsObtained. This condition can occur /// only when there are more rows available than can be handled by the rowset. Therefore, this condition never conflicts with those /// described in DB_S_ENDOFROWSET and DB_S_STOPLIMITREACHED, both of which imply that no more rows were available. /// /// /// /// /// /// /// DB_S_STOPLIMITREACHED Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. /// Execution was stopped because a resource limit was reached. The number of rows that were actually fetched is returned in *pcRowsObtained. /// /// /// /// /// /// E_FAIL A provider-specific error occurred. /// /// /// /// /// E_INVALIDARG pcRowsObtained or prghRows was a null pointer. /// /// /// /// /// /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to instantiate the rows or return the row handles. /// /// /// /// /// /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// /// /// DB_E_BADCHAPTER The rowset was chaptered, and hChapter was invalid. /// /// The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the /// currently open chapter or release the currently open chapter before specifying a new chapter. /// /// /// /// /// /// DB_E_BADRATIO ulNumerator was greater than ulDenominator. /// ulDenominator was zero. /// /// /// /// /// DB_E_CANTFETCHBACKWARDS cRows was negative, and the rowset cannot fetch backward. /// /// /// /// /// /// DB_E_NOTREENTRANT The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the /// provider does not support reentrancy in this method. /// /// /// /// /// /// /// DB_E_ROWSNOTRELEASED The provider requires release of existing rows before new ones can be fetched. For more information, see /// DBPROP_CANHOLDROWS in Rowset Properties in Appendix C. /// /// /// /// /// /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to fetch any of the rows; no rows were fetched. /// /// /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709602(v=vs.85) HRESULT GetRowsAtRatio ( HWATCHREGION // hReserved1, HCHAPTER hChapter, DBCOUNTITEM ulNumerator, DBCOUNTITEM ulDenominator, DBROWCOUNT cRows, DBCOUNTITEM *pcRowsObtained, // HROW **prghRows); [PreserveSig] new HRESULT GetRowsAtRatio([In, Optional] HWATCHREGION hReserved1, [In] HCHAPTER hChapter, DBCOUNTITEM ulNumerator, DBCOUNTITEM ulDenominator, DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); /// Returns the exact position of the specified bookmark and the exact rowcount. /// [in] A chapter handle, used to limit the scope of the operations to the relevant rows. /// /// [in] The number of bytes in the data of the bookmark. This will be a 32-bit field on 32-bit platform and a 64-bit field on 64-bit platforms. /// /// [in] Pointer to the bookmark data (a opaque sequence of bytes). /// /// [out] Pointer to an unsigned field (32 bits on 32-bit platforms and 64 bits on 64-bit platforms) that returns the exact position /// of the bookmark relative to the beginning. /// /// /// [out] Pointer to an unsigned field (32 bits on 32-bit platforms and 64 bits on 64-bit platforms) that returns the number of rows /// in the rowset. /// /// // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965358(v=vs.85) HRESULT GetExactPosition( HCHAPTER hChapter, // DBBKMARK cbBookmark, const BYTE *pBookmark, DBCOUNTITEM *pulPosition, DBCOUNTITEM *pcRows ); [PreserveSig] HRESULT GetExactPosition([In] HCHAPTER hChapter, DBBKMARK cbBookmark, [In] IntPtr pBookmark, out DBCOUNTITEM pulPosition, out DBCOUNTITEM pcRows); } }