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);
}
}