From ffd679991029741da9bfa1b9292dcd45dca8941b Mon Sep 17 00:00:00 2001 From: David Hall Date: Tue, 7 May 2024 12:18:21 -0600 Subject: [PATCH] Completed all interfaces for OleDb --- PInvoke/OleDb/DbS.cs | 141 +- PInvoke/OleDb/Globals.cs | 26 + PInvoke/OleDb/OleDb1.cs | 5299 +++++++++++++++++++++++++ PInvoke/OleDb/{OleDb.cs => OleDb2.cs} | 5479 ++++++++++---------------- PInvoke/OleDb/OleDb3.cs | 4039 +++++++++++++++++++ PInvoke/OleDb/OleDb4.cs | 4169 ++++++++++++++++++++ PInvoke/OleDb/OleDb5.cs | 6934 +++++++++++++++++++++++++++++++++ PInvoke/OleDb/Transact.cs | 861 ++++ PInvoke/OleDb/adoint.cs | 41 + PInvoke/OleDb/msdasc.cs | 49 +- 10 files changed, 23696 insertions(+), 3342 deletions(-) create mode 100644 PInvoke/OleDb/Globals.cs create mode 100644 PInvoke/OleDb/OleDb1.cs rename PInvoke/OleDb/{OleDb.cs => OleDb2.cs} (52%) create mode 100644 PInvoke/OleDb/OleDb3.cs create mode 100644 PInvoke/OleDb/OleDb4.cs create mode 100644 PInvoke/OleDb/OleDb5.cs create mode 100644 PInvoke/OleDb/Transact.cs create mode 100644 PInvoke/OleDb/adoint.cs diff --git a/PInvoke/OleDb/DbS.cs b/PInvoke/OleDb/DbS.cs index a786a7f4..71330d68 100644 --- a/PInvoke/OleDb/DbS.cs +++ b/PInvoke/OleDb/DbS.cs @@ -706,29 +706,60 @@ public static partial class OleDb DBCOLUMNFLAGS_ROWSPECIFICCOLUMN = 0x400000 } + /// Options for persisting command definition. [Flags] public enum DBCOMMANDPERSISTFLAG { + /// The behavior of DBCOMMANDPERSISTFLAGS_DEFAULT is provider specific. DBCOMMANDPERSISTFLAG_DEFAULT = 0, + /// You can use DBCOMMANDPERSISTFLAG_NOSAVE to associate or obtain a new DBID for the command without actually persisting the definition. DBCOMMANDPERSISTFLAG_NOSAVE = 0x1, + /// The command is to be persisted as a view. Views are row-returning objects that do not contain parameters or return values and can generally be used anywhere a base table is used. Views can be enumerated through the DBSCHEMA_VIEWS schema rowset. DBCOMMANDPERSISTFLAG_PERSISTVIEW = 0x2, + /// The command is to be persisted as a procedure. Procedures may or may not return rows and may or may not contain parameters or return values. Procedures can be enumerated through the DBSCHEMA_PROCEDURES schema rowset. DBCOMMANDPERSISTFLAG_PERSISTPROCEDURE = 0x4 } + /// + /// Operation to use in comparing the row values. + /// + [PInvokeData("oledb.h")] public enum DBCOMPAREOPS { + /// Match the first value that is less than the search value. DBCOMPAREOPS_LT, + /// Match the first value that is less than or equal to the search value. DBCOMPAREOPS_LE = 1, + /// Match the first value that is equal to the search value. DBCOMPAREOPS_EQ = 2, + /// Match the first value that is greater than or equal to the search value. DBCOMPAREOPS_GE = 3, + /// Match the first value that is greater than the search value. DBCOMPAREOPS_GT = 4, + /// Match the first value that has the search value as its first characters. This is valid only for values bound as string data types. DBCOMPAREOPS_BEGINSWITH = 5, + /// Match the first value that contains the search value. This is valid only for values bound as string data types. DBCOMPAREOPS_CONTAINS = 6, + /// Match the first value that is not equal to the search value. If the search value is NULL, this matches the first non-NULL value. If the search value is non-NULL, this matches the first non-NULL value that is not equal to the search value. DBCOMPAREOPS_NE = 7, + /// + /// Ignore the corresponding value. + /// The provider ignores pFindValue and returns the next cRows rows starting from the row indicated by pBookmark, skipping the number of rows indicated by lRowsOffset. + /// DBCOMPAREOPS_IGNORE = 8, + /// + /// Specify whether the search is case-sensitive or case-insensitive. + /// You can join DBCOMPAREOPS_CASESENSITIVE or DBCOMPAREOPS_CASEINSENSITIVE with any of the other DBCOMPAREOPS values in a bitwise OR operation. If neither is used, the search is handled according to the provider's implementation. Both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE are ignored when searching for nonstring values. + /// DBCOMPAREOPS_CASESENSITIVE = 0x1000, + /// + /// Specify whether the search is case-sensitive or case-insensitive. + /// You can join DBCOMPAREOPS_CASESENSITIVE or DBCOMPAREOPS_CASEINSENSITIVE with any of the other DBCOMPAREOPS values in a bitwise OR operation. If neither is used, the search is handled according to the provider's implementation. Both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE are ignored when searching for nonstring values. + /// DBCOMPAREOPS_CASEINSENSITIVE = 0x2000, + /// Match the first value that does not have the search value as its first characters. This is valid only for values bound as string data types. DBCOMPAREOPS_NOTBEGINSWITH = 9, + /// Match the first value that does not contain the search value. This is valid only for values bound as string data types. DBCOMPAREOPS_NOTCONTAINS = 10 } @@ -4201,17 +4232,35 @@ public static partial class OleDb public byte bScale; } + /// Gets or sets the value of the specified column in the rowset. + [PInvokeData("oledb.h")] [StructLayout(LayoutKind.Sequential)] public struct DBCOLUMNACCESS { + /// + /// Pointer of type wType to caller-allocated storage. On return, the area of storage contains the value stored in the column specified by columnid. The provider should attempt to coerce the column value to type wType. If wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed to by the VARIANT. If the caller passes a null pointer, the provider returns only the untruncated length (cbDataLen) and status (dwStatus) and does not return a data value. + /// If the row is in immediate mode and a row-specific columns has been deleted, the provider returns DBSTATUS_E_DOESNOTEXIST. If the row is in deferred mode and a row-specific column has been deleted, the provider returns a null value and DBSTATUS_S_ISNULL. + /// For more information, see Getting and Setting Data. + /// public IntPtr pData; + /// columnid is a DBID that identifies the column to be accessed. columnid values must be unique within a row. public DBID columnid; + /// The returned length of the value contained in *pData. If the length of the column value is greater than cbMaxLen, the provider truncates the data to fit the buffer, returns the full data size in cbDataLen, and sets dwStatus to DBSTATUS_S_TRUNCATED. public DBLENGTH cbDataLen; + /// A DBSTATUS status field set by the provider on return, indicating whether pData or some other value should be used. On return, dwStatus indicates whether the field was successfully retrieved and provides other information about this column. For more information about status values, see Status in Getting and Setting Data. public DBSTATUS dwStatus; + /// The maximum length of the caller-initialized memory pointed to by pData. For more information on cbMaxLen in the binding structure, see DBBINDING Structures in Getting and Setting Data. public DBLENGTH cbMaxLen; + /// Reserved. Consumers should set this parameter to zero. public DB_DWRESERVE dwReserved; + /// + /// On input, wType identifies the data type requested by the consumer. The provider attempts to convert the value from the type of the column to this type. + /// wType should not change on return; if the provider could not convert, a status of DBSTATUS_E_CANTCONVERTVALUE would be returned. + /// public DBTYPE wType; + /// The maximum precision to use when getting data and wType is DBTYPE_NUMERIC. bPrecision is ignored when setting data or if wType is not DBTYPE_NUMERIC. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types. public byte bPrecision; + /// The scale to use when getting data and wType is DBTYPE_NUMERIC or DBTYPE_DECIMAL. This is ignored when setting data. It is also ignored if wType is not DBTYPE_NUMERIC or DBTYPE_DECIMAL. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types. public byte bScale; } @@ -4230,17 +4279,34 @@ public static partial class OleDb public byte bScale; } - [StructLayout(LayoutKind.Sequential)] + /// + /// Defines the columns of a row object. + /// + [PInvokeData("oledb.h")] + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] public struct DBCOLUMNINFO { - public StrPtrUni pwszName; + /// + /// Pointer to the name of the column; this might not be unique. If this cannot be determined, a null pointer is returned. + /// The name can be different from the string part of the column ID if the column has been renamed by the command text. This name always reflects the most recent renaming of the column in the current view or command text. + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string? pwszName; + /// Reserved for future use. Providers should return a null pointer in pTypeInfo. public IntPtr pTypeInfo; + /// The ordinal of the column. This is zero for the bookmark column of the row, if any. Other columns are numbered starting from one. public DBORDINAL iOrdinal; + /// 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. public DBCOLUMNFLAGS dwFlags; + /// 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. public DBLENGTH ulColumnSize; + /// Requested DBTYPE data type for this column. public DBTYPE wType; + /// Maximum precision of the column. public byte bPrecision; + /// Number of digits to the right of the decimal point. public byte bScale; + /// 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. public DBID columnid; } @@ -4314,11 +4380,25 @@ public static partial class OleDb public IntPtr pSession; } + /// Describes how to construct the index. + [PInvokeData("dbs.h")] [StructLayout(LayoutKind.Sequential)] public struct DBINDEXCOLUMNDESC { + /// A pointer to the ID of the base table column. public IntPtr pColumnID; + + /// + /// Whether the index is ascending or descending in this column. + /// + /// DBINDEX_COL_ORDER_ASC ? Ascending + /// DBINDEX_COL_ORDER_DESC ? Descending + /// + /// public DBINDEX_COL_ORDER eIndexColOrder; + + /// The ID of the base table column. + public readonly DBID? ColumnId => pColumnID.ToNullableStructure(); } [StructLayout(LayoutKind.Sequential)] @@ -4331,13 +4411,66 @@ public static partial class OleDb [StructLayout(LayoutKind.Sequential)] public struct DBPARAMINFO { + /// + /// A bitmask describing parameter characteristics; these values have the following meaning: + /// + /// DBPARAMFLAGS_ISINPUT ? Whether a parameter accepts values on input. Not set if this is unknown. + /// + /// DBPARAMFLAGS_ISOUTPUT ? Whether a parameter returns values on output. Not set if this is unknown. Providers support only those + /// parameter types that make sense for their data store. + /// + /// + /// DBPARAMFLAGS_ISSIGNED ? Whether a parameter is signed. This is ignored if the type is inherently signed, such as DBTYPE_I2 or if + /// the sign does not apply to the type, such as DBTYPE_BSTR. It is generally used in ICommandWithParameters::SetParameterInfo so + /// that the consumer can tell the provider if a provider-specific type name refers to a signed or unsigned type. + /// + /// DBPARAMFLAGS_ISNULLABLE ? Whether a parameter accepts NULLs. If nullability is unknown, this flag is set. + /// + /// + /// DBPARAMFLAGS_ISLONG ? Whether a parameter contains a BLOB that contains very long data. The definition of very long data is + /// provider specific. The flag setting corresponds to the value of the IS_LONG column in the PROVIDER_TYPES schema rowset for the + /// data type. + /// + /// + /// When this flag is set, the BLOB is best manipulated through one of the storage interfaces. Although such BLOBs can be sent in a + /// single piece with ICommand::Execute, there can be provider-specific problems in doing so. For example, the BLOB might be + /// truncated due to machine limits on memory. Furthermore, when this flag is set, the provider might not be able to accurately + /// return the maximum length of the BLOB data in ulParamSize in ICommandWithParameters::GetParameterInfo. + /// + /// When this flag is not set, the BLOB can be accessed either through ICommand::Execute or through a storage interface. + /// For more information, see Accessing BLOB Data. + /// + /// + /// DBPARAMFLAGS_SCALEISNEGATIVE ? Set if the parameter type is DBTYPE_VARNUMERIC and bScale represents the absolute value of the + /// negative scale of the parameter. This flag is used when setting data in a DBTYPE_VARNUMERIC parameter. For more information, + /// refer to Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A. + /// + /// + /// public DBPARAMFLAGS dwFlags; + /// The ordinal of the parameter. Parameters are numbered from left to right as they appear in the command, with the first parameter in the command having an iOrdinal value of 1. public DBORDINAL iOrdinal; - public StrPtrUni pwszName; - public IntPtr pTypeInfo; + /// The name of the parameter; it is a null pointer if there is no name. Names are normal names. The colon prefix (where used within SQL text) is stripped. + [MarshalAs(UnmanagedType.LPWStr)] + public string? pwszName; + /// ITypeInfo describes the type, if pTypeInfo is not a null pointer. + [MarshalAs(UnmanagedType.IUnknown)] + public ITypeInfo? pTypeInfo; + /// + /// The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of the data type. For parameters that use a variable-length data type, this is one of the following: + /// + /// The maximum length of the parameters in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), if one is defined. For example, a parameter for a CHAR(5) column in an SQL table has a maximum length of 5. + /// The maximum length of the data type in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), if the parameter does not have a defined length. + /// ~0 (bitwise, the value is not 0; all bits are set to 1) if neither the parameter nor the data type has a defined maximum length. + /// + /// For data types that do not have a length, this is set to ~0 (bitwise, the value is not 0; all bits are set to 1). + /// public DBLENGTH ulParamSize; + /// The indicator of the parameter's data type, or a type from which the data can be converted for the parameter if the provider cannot determine the exact data type of the parameter. public DBTYPE wType; + /// If wType is a numeric type or DBTYPE_DBTIMESTAMP, bPrecision is the maximum number of digits, expressed in base 10. Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). public byte bPrecision; + /// If wType is a numeric type with a fixed scale or if wType is DBTYPE_DBTIMESTAMP, bScale is the number of digits to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). public byte bScale; } diff --git a/PInvoke/OleDb/Globals.cs b/PInvoke/OleDb/Globals.cs new file mode 100644 index 00000000..43dd6f69 --- /dev/null +++ b/PInvoke/OleDb/Globals.cs @@ -0,0 +1,26 @@ +global using static Vanara.PInvoke.Ole32; +global using HWATCHREGION = System.IntPtr; +global using HACCESSOR = System.IntPtr; +global using HROW = System.IntPtr; +global using HCHAPTER = System.IntPtr; +global using DB_DWRESERVE = nuint; +global using DB_LORDINAL = nint; +global using DB_LPARAMS = nint; +global using DB_LRESERVE = nint; +global using DB_UPARAMS = nuint; +global using DB_URESERVE = nuint; +global using DBBKMARK = nuint; +global using DBBYTEOFFSET = nuint; +global using DBCOUNTITEM = nuint; +global using DBKIND = uint; +global using DBHASHVALUE = uint; +global using DBLENGTH = nuint; +global using DBNUMBERIC = Vanara.PInvoke.Odbc32.SQL_NUMERIC_STRUCT; +global using DBDATE = Vanara.PInvoke.Odbc32.DATE_STRUCT; +global using DBTIME = Vanara.PInvoke.Odbc32.TIME_STRUCT; +global using DBTIMESTAMP = Vanara.PInvoke.Odbc32.TIMESTAMP_STRUCT; +global using DBORDINAL = nuint; +global using DBREFCOUNT = uint; +global using DBROWCOUNT = nint; +global using DBROWOFFSET = nint; +global using DISPPARAMS = System.Runtime.InteropServices.ComTypes.DISPPARAMS; \ No newline at end of file diff --git a/PInvoke/OleDb/OleDb1.cs b/PInvoke/OleDb/OleDb1.cs new file mode 100644 index 00000000..5d68b378 --- /dev/null +++ b/PInvoke/OleDb/OleDb1.cs @@ -0,0 +1,5299 @@ +namespace Vanara.PInvoke; + +/// Items from the OleDb.dll. +public static partial class OleDb +{ + /// Undocumented. + public const uint IDENTIFIER_SDK_ERROR = 0x10000000; + + /// Undocumented. + public const uint IDENTIFIER_SDK_MASK = 0xF0000000; + + private const string Lib_OleDb = "OleDb.dll"; + + /// Whether IConvertType::CanConvert is to determine if the conversion is supported on the rowset or on the command. + [PInvokeData("oledb.h")] + [Flags] + public enum DBCONVERTFLAGS + { + /// + /// IConvertType::CanConvert is to determine whether the conversion is supported when setting, getting, finding, filtering, or + /// seeking on columns of the rowset or row. This flag is mutually exclusive with DBCONVERTFLAGS_PARAMETER. + /// + DBCONVERTFLAGS_COLUMN = 0, + + /// IConvertType::CanConvert is to determine whether the conversion is supported on the parameters of the command. + DBCONVERTFLAGS_PARAMETER = 0x1, + + /// + /// IConvertType::CanConvert is to determine whether the long version of the DBTYPE specified in the dwFromType can be + /// converted to the DBTYPE specified in wToType. This flag is valid only when used in conjunction with a variable-length + /// DBTYPE. This flag can coexist with either DBCONVERTFLAGS_COLUMN or DBCONVERTFLAGS_PARAMETER. This flag is supported only by OLE + /// DB version 2.0 or later providers. + /// + DBCONVERTFLAGS_ISLONG = 0x2, + + /// + /// IConvertType::CanConvert is to determine whether a fixed-length value of the DBTYPE specified in the dwFromType can + /// be converted to the DBTYPE specified in wToType. This flag can coexist with either DBCONVERTFLAGS_COLUMN or + /// DBCONVERTFLAGS_PARAMETER. This flag is supported only by OLE DB version 2.0 or later providers. + /// + DBCONVERTFLAGS_ISFIXEDLENGTH = 0x4, + + /// + /// The DBTYPE specified in the wFromType represents a type within a VARIANT. IConvertType::CanConvert returns whether + /// the conversion from a VARIANT of that type to the type specified in wToType is allowed. For providers that support + /// PROPVARIANT, this applies to conversions from PROPVARIANT as well. + /// + DBCONVERTFLAGS_FROMVARIANT = 0x8 + } + + /// + /// IAccessor provides methods for accessor management. For information about accessors, see the section about Accessors in Getting and + /// Setting Data. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719672(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a8c-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IAccessor + { + /// Adds a reference count to an existing accessor. + /// [in] The handle of the accessor for which to increment the reference count. + /// + /// [out] A pointer to memory in which to return the reference count of the accessor handle. If pcRefCount is a null pointer, no + /// reference count is returned. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714978(v=vs.85) HRESULT AddRefAccessor ( HACCESSOR + // hAccessor, DBREFCOUNT *pcRefCount); + void AddRefAccessor(HACCESSOR hAccessor, out DBREFCOUNT pcRefCount); + + /// Creates an accessor from a set of bindings. + /// + /// [in] A bitmask that describes the properties of the accessor and how it is to be used. These flags have the following meanings. + /// + /// + /// Value + /// Description + /// + /// + /// DBACCESSOR_INVALID + /// This flag is used by IAccessor::GetBindings to indicate that the method failed. + /// + /// + /// DBACCESSOR_PASSBYREF + /// + /// The accessor is a reference accessor. The value passed in the consumer buffer is a pointer to the passer's internal buffer. This + /// pointer need not point to the start of the internal buffer as long as the relative offsets of all elements of the buffer align + /// with the offsets specified in the accessor. The passee must know the internal structure of the passer's buffer in order to read + /// information from it. The passee must not free the buffer at the pointer nor may it write to this buffer. For row accessors, this + /// buffer is the rowset's copy of the row. The consumer reads information directly from this copy of the row at a later point in + /// time, so the provider must guarantee that the pointer remains valid. For parameter accessors, this buffer is the consumer's + /// buffer. The provider reads data from this buffer only when ICommand::Execute is called; therefore, the pointer is not + /// required to remain valid after Execute returns. Support for this flag is optional. A consumer determines whether a + /// provider supports this bit by calling IDBProperties::GetProperties for the DBPROP_BYREFACCESSORS property. When this flag + /// is used, the dwMemOwner in the DBBINDING structure is ignored. If the accessor is used for row data, the accessor refers + /// to the provider's memory; the consumer must not write to or free this memory. If the accessor is used for input parameters, the + /// provider copies the row of data without assuming ownership. It is an error to specify an output or input/output parameter in a + /// reference accessor. For more information, see Reference Accessors in Getting and Setting Data (OLE DB). + /// + /// + /// + /// DBACCESSOR_ROWDATA + /// + /// The accessor is a row accessor and describes bindings to columns in the rowset. An accessor may be a row accessor, a parameter + /// accessor, or both. + /// + /// + /// + /// DBACCESSOR_PARAMETERDATA + /// + /// The accessor is a parameter accessor and describes bindings to parameters in the command text. In a parameter accessor, it is an + /// error to bind an input or an input/output parameter more than one time. + /// + /// + /// + /// DBACCESSOR_OPTIMIZED + /// + /// The row accessor is to be optimized. This hint may affect how a provider structures its internal buffers. A particular column can + /// be bound by only one optimized accessor. The column can also be bound by other, nonoptimized accessors, but the types specified + /// in the nonoptimized accessors must be convertible from the type in the optimized accessor. All optimized accessors must be + /// created before the first row is fetched with IRowset::GetNextRows, IRowsetLocate::GetRowsAt, + /// IRowsetLocate::GetRowsByBookmark, or IRowsetScroll::GetRowsAtRatio. This flag is ignored for parameter accessors + /// and may be ignored by providers that do not provide further optimizations or restrictions based on its setting. Providers that + /// enforce restrictions, such as limiting the number or types of columns bound in optimized accessors, must set this flag when + /// IAccessor::GetBindings is called on an optimized accessor. Providers that do not impose any restrictions on optimized + /// accessors or that ignore this flag entirely are not required to return this flag when IAccessor::GetBindings is called. + /// + /// + /// + /// DBACCESSOR_INHERITED + /// + /// Indicates an accessor on a command should be inherited by a rowset when the rowset implementation is in a separate component from + /// the command object. IAccessor::CreateAccessor is then used to pass an existing command accessor to the rowset + /// implementation. When DBACCESSOR_INHERITED is specified, phAccessor is used as an [in] argument and contains a pointer to + /// the value of the existing accessor handle. The rowset component then creates an internal accessor according to the specified + /// bindings for this handle value. + /// + /// + /// + /// + /// + /// [in] The number of bindings in the accessor. + /// + /// If cBindings is zero, IAccessor::CreateAccessor creates a null accessor. Null accessors are used only by + /// IRowsetChange::InsertRow to create a new row in which each column is set to its default value, NULL, or a status of + /// DBSTATUS_E_UNAVAILABLE. Providers that support IRowsetChange::InsertRow must support the creation of null accessors. For + /// more information, see InsertRow. + /// + /// + /// [in] An array of DBBINDING structures. For more information, see DBBINDING Structures. + /// + /// [in] The number of bytes allocated for a single set of parameters or criteria values in the consumer's buffer. + /// + /// cbRowSize is used by ICommand::Execute to process multiple sets of parameters and by IViewFilter::GetFilter and + /// IViewFilter::SetFilter to get and set multiple OR conditions in criteria. In either case, a single accessor may describe + /// multiple sets of values. cbRowSize is generally the size of the structure that contains a single set of parameter or criteria + /// values and is used as the offset to the start of the next set of values within the array of structures. For example, if + /// cParamSets is greater than 1 in the DBPARAMS structure passed to ICommand::Execute, the provider assumes that the pData + /// element of this structure points to an array of structures containing parameter values, each cbRowSize bytes in size. Similarly, + /// if cRows is greater than 1 in IViewFilter::SetFilter, the provider assumes that the pCriteriaData argument points to an + /// array of structures containing criteria values, each cbRowSize bytes in size. + /// + /// + /// cbRowSize must be large enough to contain the structure defined by the bindings in rgBindings. The provider is not required to + /// verify this, although it may. + /// + /// cbRowSize is not used when fetching rowset data. + /// + /// + /// [out] A pointer to memory in which to return the handle of the created accessor. If IAccessor::CreateAccessor fails, it + /// must attempt to set *phAccessor to a null handle. + /// + /// + /// + /// [out] An array of cBindings DBBINDSTATUS values in which IAccessor::CreateAccessor returns the status of each binding ? + /// that is, whether or not it was successfully validated. If rgStatus is a null pointer, no bind status values are returned. The + /// consumer allocates and owns the memory for this array. The bind status values are returned for the reasons described in the + /// following table. + /// + /// + /// + /// Value + /// Description + /// + /// + /// DBBINDSTATUS_OK + /// + /// No errors were found in the binding. Because accessor validation can be deferred, a status of DBBINDSTATUS_OK does not + /// necessarily mean that the binding was successfully validated. + /// + /// + /// + /// DBBINDSTATUS_BADORDINAL + /// + /// A parameter ordinal was zero in a parameter accessor. If the accessor is validated against the metadata when + /// IAccessor::CreateAccessor is called, DBBINDSTATUS_BADORDINAL can be returned for the following reasons: These reasons + /// cause a status value of DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. Some providers may support + /// binding more parameters than the number of parameters in the command text, and such providers do not return + /// DBBINDSTATUS_BADORDINAL in this case. + /// + /// + /// + /// DBBINDSTATUS_UNSUPPORTEDCONVERSION + /// + /// If the accessor is validated against the metadata when IAccessor::CreateAccessor is called, + /// DBBINDSTATUS_UNSUPPORTEDCONVERSION can be returned for the following reasons: These reasons cause a status value of + /// DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. + /// + /// + /// + /// DBBINDSTATUS_BADBINDINFO + /// + /// dwPart in a binding was not a combination of two or more of the following: DBPART_VALUE DBPART_LENGTH DBPART_STATUS + /// eParamIO in a binding in a parameter accessor was not one of the following: DBPARAMIO_INPUT DBPARAMIO_OUTPUT + /// DBPARAMIO_INPUT | DBPARAMIO_OUTPUT A row accessor was optimized, and a column ordinal in a binding was already used in another + /// optimized accessor. In a parameter accessor, two or more bindings contained the same ordinal for an input or input/output + /// parameter. wType in a binding was DBTYPE_EMPTY or DBTYPE_NULL. wType in a binding was one of the following: + /// DBTYPE_BYREF | DBTYPE _EMPTY, DBTYPE_BYREF | DBTYPE_NULL, or DBTYPE_BYREF | DBTYPE_RESERVED. wType in a binding was used + /// with more than one of the following mutually exclusive type indicators: DBTYPE_BYREF, DBTYPE_ARRAY, or DBTYPE_VECTOR. + /// wType in a binding was DBTYPE_IUNKNOWN, pObject in the same binding was a null pointer, and the provider did not + /// assume that the bound interface is IID_IUnknown. Provider-owned memory was specified for a nonpointer type in a + /// nonreference row accessor. Provider-owned memory was specified for a column, and the provider does not support binding to + /// provider-owned memory for this column. Provider-owned memory was specified for a column for which + /// IColumnsInfo::GetColumnInfo returned DBCOLUMNFLAGS_ISLONG, and the provider does not support binding long data to provider + /// owned memory. In a nonreference parameter accessor, a binding specified provider-owned memory. An output or input/output + /// parameter was specified in a parameter reference accessor. dwFlags in a binding was set to DBBINDFLAG_HTML, and + /// wType for the same binding was not a string value. The provider is an OLE DB 2.5 or later provider, and dwFlags was + /// set to an unknown or invalid value. dwMemOwner was invalid. Providers are not required to return DBBINDSTATUS_BADBINDINFO. + /// If they ignore an invalid value of dwMemOwner, they must default to DBMEMOWNER_CLIENTOWNED. If the accessor is validated + /// against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_BADBINDINFO can be returned for the following reasons: + /// + /// + /// + /// DBBINDSTATUS_BADSTORAGEFLAGS + /// + /// dwFlags, in the DBOBJECT structure pointed to by a binding, specified invalid storage flags. If the accessor is validated + /// against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_BADSTORAGEFLAGS can be returned if + /// dwFlags, in the DBOBJECT structure pointed to by a binding, specified a valid storage flag that was not supported by the + /// object. This causes a status value of DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. + /// + /// + /// + /// DBBINDSTATUS_NOINTERFACE + /// + /// If the accessor is validated against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_NOINTERFACE can + /// be returned for the following reasons: These reasons cause a status value of DBSTATUS_E_BADACCESSOR to be returned if the + /// accessor is validated when used. + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. If rgStatus is not a null pointer, each element is set to DBBINDSTATUS_OK. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG phAccessor was a null pointer. + /// cBindings was not zero, and rgBindings was a null pointer. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// DB_E_BADACCESSORFLAGS dwAccessorFlags was invalid. + /// The DBACCESSOR_PARAMETERDATA bit was set in dwAccessorFlags, and the provider does not support parameters. + /// Neither the DBACCESSOR_PARAMETERDATA bit nor the DBACCESSOR_ROWDATA bit was set in dwAccessorFlags. + /// + /// A method that fetches rows ( IRowset::GetNextRows, IRowsetLocate::GetRowsAt, + /// IRowsetLocate::GetRowsByBookmark, or IRowsetScroll::GetRowsAtRatio) had already been called, and the + /// DBACCESSOR_OPTIMIZED bit in dwAccessorFlags was set. + /// + /// The DBACCESSOR_ PARAMETERDATA bit was set, and IAccessor::CreateAccessor was called on a rowset. + /// + /// + /// + /// + /// + /// DB_E_BYREFACCESSORNOTSUPPORTED dwAccessorFlags was DBACCESSOR_PASSBYREF, and the value of the DBPROP_BYREFACCESSORS property is VARIANT_FALSE. + /// + /// + /// Consumers should always check to see whether the provider supports the property DBPROP_BYREFACCESSORS and call + /// IAccessor::CreateAccessor with the DBACCESSOR_PASSBYREF flag only if the provider supports this property. For performance + /// reasons, some service providers might be unable to detect whether the underlying data provider supports DBACCESSOR_PASSBYREF on + /// the CreateAccessor call and might return DB_E_BYREFACCESSORNOTSUPPORTED. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Accessor validation failed. To determine which bindings failed, the consumer checks the values returned in + /// rgStatus, at least one of which is not DBBINDSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// 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_NULLACCESSORNOTSUPPORTED cBindings was zero, and either the rowset does not expose IRowsetChange::InsertRow or + /// IAccessor::CreateAccessor was called on a command. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720969(v=vs.85) HRESULT CreateAccessor ( DBACCESSORFLAGS + // dwAccessorFlags, DBCOUNTITEM cBindings, const DBBINDING rgBindings[], DBLENGTH cbRowSize, HACCESSOR *phAccessor, DBBINDSTATUS rgStatus[]); + [PreserveSig] + HRESULT CreateAccessor(DBACCESSORFLAGS dwAccessorFlags, DBCOUNTITEM cBindings, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBINDING[] rgBindings, + [Optional] DBLENGTH cbRowSize, out HACCESSOR phAccessor, [In, Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBINDSTATUS[]? rgStatus); + + /// Returns the bindings in an accessor. + /// [in] The handle of the accessor for which to return the bindings. + /// + /// [out] A pointer to memory in which to return a bitmask that describes the properties of the accessor and how it is intended to be + /// used. For more information, see dwAccessorFlags in CreateAccessor. If this method fails, *pdwAccessorFlags is set to DBACCESSOR_INVALID. + /// + /// + /// [out] A pointer to memory in which to return the number of bindings in the accessor. If this method fails, *pcBindings is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of DBBINDING structures. One DBBINDING structure is returned for each + /// binding in the accessor. The provider allocates memory for these structures and any structures pointed to by elements of these + /// structures; for example, if pObject in a binding structure is not a null pointer, the provider allocates a DBOBJECT structure for + /// return to the consumer. The provider returns the address to the memory for these structures; the consumer releases the memory for + /// these structures with IMalloc::Free when it no longer needs the bindings. If *pcBindings is zero on output or the method + /// fails, the provider does not allocate any memory and ensures that *prgBindings is a null pointer on output. For information about + /// bindings, see DBBINDING Structures. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721253(v=vs.85) HRESULT GetBindings ( HACCESSOR hAccessor, + // DBACCESSORFLAGS *pdwAccessorFlags, DBCOUNTITEM *pcBindings, DBBINDING **prgBindings); + void GetBindings(HACCESSOR hAccessor, out DBACCESSORFLAGS pdwAccessorFlags, out DBCOUNTITEM pcBindings, + out SafeIMallocHandle prgBindings); + + /// Releases an accessor. + /// [in] The handle of the accessor to release. + /// + /// [out] A pointer to memory in which to return the remaining reference count of the accessor handle. If pcRefCount is a null + /// pointer, no reference count is returned. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719717(v=vs.85) HRESULT ReleaseAccessor ( HACCESSOR + // hAccessor, DBREFCOUNT *pcRefCount); + void ReleaseAccessor(HACCESSOR hAccessor, out DBREFCOUNT pcRefCount); + } + + /// + /// The IAlterIndex interface exposes methods to alter indexes. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714943(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aa6-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IAlterIndex + { + /// Alters the ID and/or properties associated with an index. + /// [in] The DBID of the indexed base table. + /// [in] The DBID of the existing index to alter. + /// + /// [in] The new DBID of the index. If this is the same as pIndexID or is a null pointer, the ID of the index is unchanged. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the index property set. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The index was altered but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// pIndexID was a null pointer. + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_BADINDEXID *pIndexID or *pNewIndexID was an invalid index ID. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_DUPLICATEINDEXID The index specified in *pNewIndexID already exists in the data store and is not the same as pIndexID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The index was not altered because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties + /// for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not possible to set the property. + /// + /// + /// + /// + /// + /// DB_E_INDEXINUSE The specified index was in use. + /// + /// + /// + /// + /// DB_E_NOINDEX The index specified in *pIndexID does not exist in the data store or does not apply to the specified table. + /// + /// + /// + /// + /// DB_E_NOTABLE The table specified in *pTableID does not exist in the data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not modify the index with the table open. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to alter the index. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714965(v=vs.85) HRESULT AlterIndex( DBID *pTableID, DBID + // *pIndexID, DBID *pNewIndexID, ULONG cPropertySets, DBPROPSET rgPropertySets[]); + [PreserveSig] + HRESULT AlterIndex(in DBID pTableId, in DBID pIndexId, in DBID pNewIndexId, uint cPropertySets, [In] SafeDBPROPSETListHandle rgPropertySets); + } + + /// + /// The IAlterTable interface exposes methods to alter the definition of tables and columns. + /// Providers that implement IAlterTable should expose the data source information property DBPROP_ALTERCOLUMN. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719764(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aa5-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IAlterTable + { + /// Alters the column ID and/or properties associated with a column in a table. + /// [in] The DBID of the base table containing the column to alter. + /// [in] The current DBID of the column to alter. + /// + /// + /// [in] Values as described in the enumeration DBCOLUMNDESCFLAGS. As illustrated in the following table, these bits define which + /// portions of the DBCOLUMNDESC structure defined in pColumnDesc should be used when altering the column. A provider returns values + /// it supports in the DBPROP_ALTERCOLUMN property. For more information about this field, please see the Comments section. + /// + /// + /// + /// DBCOLUMNDESCFLAGS values + /// Associated portion of DBCOLUMNDESC + /// + /// + /// DBCOLUMNDESCFLAGS_TYPENAME + /// pwszTypeName + /// + /// + /// DBCOLUMNDESCFLAGS_ITYPEINFO + /// ITypeInfo * + /// + /// + /// DBCOLUMNDESCFLAGS_PROPERTIES + /// rgPropertySets AND cPropertySets + /// + /// + /// DBCOLUMNDESCFLAGS_CLSID + /// pclsid + /// + /// + /// DBCOLUMNDESCFLAGS_COLSIZE + /// ulColumnSize + /// + /// + /// DBCOLUMNDESCFLAGS_DBCID + /// dbcid + /// + /// + /// DBCOLUMNDESCFLAGS_WTYPE + /// wType + /// + /// + /// DBCOLUMNDESCFLAGS_PRECISION + /// bPrecision + /// + /// + /// DBCOLUMNDESCFLAGS_SCALE + /// bScale + /// + /// + /// + /// + /// [in] A pointer to a DBCOLUMNDESCstructure defining new values for the columns. Only the values defined in dwColumnDescFlags are + /// used ? the provider ignores other fields in the structure. For a description of the DBCOLUMNDESC structure, please refer to ITableDefinition::CreateTable. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The column was altered, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnID was a null pointer. + /// pColumnDesc was a null pointer. + /// + /// + /// + /// + /// DB_E_ALTERRESTRICTED The provider could not alter the column because it was referenced by a constraint. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID The dbcid member of *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADPRECISION The bPrecision member of *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The bScale member of *pColumnDesc was invalid. + /// + /// + /// + /// + /// + /// DB_E_BADTYPE One or more of the wType, pwszTypeName, or *pTypeInfo members of *pColumnDesc was invalid, or the provider was + /// unable to change the existing column type to the new column type. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID The column ID specified in the dbcid member of *pColumnDesc was the same as an existing column ID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The column was not altered because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP + /// structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOCOLUMN The column specified in *pColumnID does not exist in the specified table. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the data store. + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED dwColumnDescFlags was an invalid value. Providers return valid values in the property DBPROP_ALTERCOLUMN. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not alter the column while the table was open. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to alter the columns of this table. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711636(v=vs.85) HRESULT AlterColumn( DBID *pTableID, DBID + // *pColumnID, DBCOLUMNDESCFLAGS dwColumnDescFlags, DBCOLUMNDESC *pColumnDesc); + [PreserveSig] + HRESULT AlterColumn(in DBID pTableId, in DBID pColumnId, DBCOLUMNDESCFLAGS dwColumnDescFlags, in DBCOLUMNDESC pColumnDesc); + + /// Alters the ID and/or properties associated with a table. + /// [in] The DBID of the base table to alter. + /// + /// [in] The new DBID of the base table. If this is the same as pTableID or is a null pointer, the ID of the table is unchanged. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the table property set. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was altered, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// cPropertySets was not zero and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_ALTERRESTRICTED The provider could not alter the table because it was referenced by a constraint. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pNewTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_DUPLICATETABLEID The table specified in *pNewTableID already exists in the data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not altered because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP + /// structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The table specified in *pTableID does not exist in the data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not alter the table while it was open. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to alter the table or index. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725407(v=vs.85) HRESULT AlterTable( DBID *pTableID, DBID + // *pNewTableID, ULONG cPropertySets, DBPROPSET rgPropertySets[]); + [PreserveSig] + HRESULT AlterTable(in DBID pTableId, in DBID pNewTableId, uint cPropertySets, [In, Out] SafeDBPROPSETListHandle rgPropertySets); + } + + /// + /// + /// IBindResource binds to an object named by a URL and returns a data source, session, rowset, row, command, or stream object. + /// + /// + /// Note + /// The term "resource" in the name of this interface refers to the use of URLs to name OLE DB objects. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714936(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733ab1-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IBindResource + { + /// + /// Binds to an object named by a URL. When implemented on a row object, binds to a tree-structured namespace, such as a file system + /// directory, named by the URL. Returns a data source, session, rowset, row, command, or stream object. + /// + /// + /// + /// [in] If the returned object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, + /// it is a null pointer. + /// + /// + /// Note + /// + /// When IBindResource is implemented on an object other than a binder and Bind is requesting a data source or session + /// object, pUnkOuter must be a null pointer because the data source and session objects have already been created. + /// + /// + /// + /// [in] The canonical URL of the object for which an OLE DB object is to be returned. + /// + /// [in] Bitmask of bind flags that control how the OLE DB object is opened. + /// + /// + /// Flag + /// Meaning + /// + /// + /// DBBINDURLFLAG_READ + /// Open object for reading only. + /// + /// + /// DBBINDURLFLAG_WRITE + /// Open object for writing only. See note above for DBBINDURLFLAG_READ. + /// + /// + /// DBBINDURLFLAG_READWRITE + /// Open object for reading and writing. See note above for DBBINDURLFLAG_READ. + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_READ + /// Deny others read access. + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_WRITE + /// + /// Deny others write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not support + /// this type of DENY semantics. + /// + /// + /// + /// DBBINDURLFLAG_SHARE_EXCLUSIVE + /// + /// Deny others read and write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not + /// support this type of DENY semantics. + /// + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_NONE + /// Do not deny others read or write access (equivalent to the omission of SHARE_DENY_READ and SHARE_DENY_WRITE). + /// + /// + /// DBBINDURLFLAG_RECURSIVE + /// + /// Modifies DBBINDURLFLAG_SHARE_*. Propagate sharing restrictions to all objects in the subtree. Has no effect when binding to leaf + /// nodes. Specifying this flag with only DBBINDURLFLAG_SHARE_DENY_NONE (or equivalently, with no SHARE_DENY flags) will result in E_INVALIDARG. + /// + /// + /// + /// DBBINDURLFLAG_OUTPUT + /// + /// Bind to the resource's executed output rather than its source. For example, this will retrieve the HTML generated by an ASP file + /// rather than its source. This flag is ignored on binds to collections. + /// + /// + /// + /// DBBINDURLFLAG_ASYNCHRONOUS + /// + /// Return immediately and perform the binding on a separate thread. If DBBINDURLFLAG_WAITFORINIT is not specified, this flag affects + /// the behavior of the IBindResource::Bind or ICreateRow::CreateRow call. If DBBINDURLFLAG_WAITFORINIT is specified, + /// this flag affects the behavior of the IDBInitialize::Initialize call. For more information, see the "Comments" section below. + /// + /// + /// + /// DBBINDURLFLAG_WAITFORINIT + /// + /// Return an interface supported on an uninitialized object, but do not initiate the bind. Used in the following cases: The consumer + /// may ask only for interfaces supported on uninitialized objects. The provider returns E_NOINTERFACE if any other interface is requested. + /// + /// + /// + /// DBBINDURLFLAG_DELAYFETCHSTREAM + /// + /// On a bind to a row, overrides the consumer's intent to immediately open the default stream. Absence of this flag is a hint to the + /// provider to instantiate the default stream object and prefetch its contents. + /// + /// + /// + /// DBBINDURLFLAG_DELAYFETCHCOLUMNS + /// + /// On a bind to a row, this flag overrides the consumer's intent to immediately access the row's columns. Absence of this flag is a + /// hint to the provider to download or prefetch the row's columns. + /// + /// + /// + /// + /// Most of the options specified by these flags can also be specified by setting DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS + /// initialization properties. (See " IBindResource::Bind Flags and Initialization Property Flags" below.) If any flags are + /// specified in dwBindURLFlags (that is, dwBindURLFlags does not equal zero), this set of flags overrides any flags that are + /// specified in DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS. If dwBindURLFlags is zero, the flags specified in DBPROP_INIT_MODE and + /// DBPROP_INIT_BINDFLAGS are used instead. + /// + /// + /// If dwBindURLFlags is zero and DBPROP_INIT_MODE is not explicitly set on the bind, the provider returns E_INVALIDARG because one + /// of DBBINDURLFLAG_READ or DBBINDURLFLAG_WRITE was not set. If dwBindURLFlags is zero and DBPROP_INIT_BINDFLAGS is not explicitly + /// set, DBPROP_INIT_BINDFLAGS defaults to zero (no options set). + /// + /// + /// Note + /// + /// The sets of flags that can be specified in DBPROP_INIT_MODE and DBPROP_INIT_BINDFLAGS are deliberately disjoint so that flags + /// from both sets can be used in the same call to IBindResource::Bind. Nevertheless, the division of flags between the two + /// properties specified below in " IBindResource::Bind Flags and Initialization Property Flags" must be honored. If the + /// client specifies flags from DBPROP_INIT_MODE in the DBPROP_INIT_BINDFLAGS property, or vice versa, they will be ignored. + /// + /// + /// + /// Not all bind flags may be used with all object types (as specified in the rguid parameter). The following table describes the + /// restrictions. If a client does not adhere to these restrictions, the bind will fail with E_INVALIDARG. + /// + /// + /// + /// Object type + /// Restrictions + /// + /// + /// DBGUID_DSO + /// Only the following flags may be used: + /// + /// + /// DBGUID_SESSION + /// Only the following flag may be used: + /// + /// + /// DBGUID_COMMAND + /// Only the following flags may be used: + /// + /// + /// DBGUID_ROW + /// No restrictions. All flags are allowed. + /// + /// + /// DBGUID_ROWSET + /// The following flags are disallowed: A consumer may bind to a rowset object, but the behavior is provider-specific. + /// + /// + /// DBGUID_STREAM + /// The following flags are disallowed: + /// + /// + /// + /// + /// [in] A pointer to a GUID indicating the type of OLE DB object to be returned. The GUID must be one of the following values: + /// + /// + /// + /// DBGUID_DSO + /// + /// + /// + /// + /// DBGUID_SESSION + /// + /// + /// + /// + /// DBGUID_COMMAND + /// + /// + /// + /// + /// DBGUID_ROW + /// + /// + /// + /// + /// DBGUID_ROWSET + /// + /// + /// + /// + /// DBGUID_STREAM + /// + /// + /// + /// + /// Note + /// When implemented on a row object, the GUID must be set to one of the following values: + /// DBGUID_ROW + /// DBGUID_ROWSET (can be requested only if the row represents a collection) + /// DBGUID_STREAM + /// + /// + /// [in] Interface ID of the interface pointer to be returned. + /// + /// [in] Optional pointer to the caller's IAuthenticate interface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// + /// [in/out] A pointer to a DBIMPLICITSESSION structure used to request and return aggregation information for the implicit session + /// object. If the bind fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL. The + /// DBIMPLICITSESSION structure is defined as follows: + /// + /// + /// + /// Element + /// Description + /// + /// + /// pUnkOuter + /// + /// If the implicit session object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. + /// Otherwise, it is a null pointer. + /// + /// + /// + /// piid + /// + /// A pointer to the IID of the interface (on the implicit session) on which to return a pointer. Cannot be NULL. If pUnkOuter + /// is not a null pointer, this IID must be IID_IUnknown. + /// + /// + /// + /// pSession + /// + /// An interface pointer to the implicit session object returned by the provider. If the session object is aggregated, this is a + /// pointer to the IUnknown interface of the inner object. + /// + /// + /// + /// + /// Note + /// + /// IBindResource::Bind uses pImplSession only when implemented on a binder object and binding to a row, rowset, or stream + /// object (rguid is DBGUID_ROW, DBGUID_ROWSET, or DBGUID_STREAM). When binding to a data source or session object (rguid is + /// DBGUID_DSO or DBGUID_SESSION), the provider ignores pImplSession because no recursive backing session is created. If implemented + /// on any other object (for example, a session or row object), the provider ignores pImplSession because the existing object already + /// has a session context. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return a bitmask containing warning status values for the requested bind flags. If + /// pdwBindStatus is a null pointer, no status values are returned. If IBindResource::Bind returns a result other than + /// DB_S_ERRORSOCCURRED and pdwBindStatus is not a null pointer, the provider returns DBBINDURLSTATUS_S_OK. The values described in + /// the following table may be returned. + /// + /// + /// + /// Status value + /// Description + /// + /// + /// DBBINDURLSTATUS_S_ DENYNOTSUPPORTED + /// + /// The bind succeeded, but the provider does not support any DENY semantics. No lock was obtained. If the consumer requires the + /// lock, it should release the object and report that a lock could not be obtained. + /// + /// + /// + /// DBBINDURLSTATUS_S_ DENYTYPENOTSUPPORTED + /// + /// The bind succeeded, but the provider does not support the requested kind of DENY semantics. For example, the provider may support + /// only DENY_WRITE or DENY_EXCLUSIVE. No lock was obtained. If the consumer requires the lock type, it should release the object and + /// report that the type of lock could not be obtained. + /// + /// + /// + /// DBBINDURLSTATUS_S_REDIRECTED + /// + /// The bind was successful, but the server for the object indicated that its URL has changed. The client should query the + /// RESOURCE_ABSOLUTEPARSENAME column on the returned object to determine the new URL. This column is available on the resource + /// rowset, so this status should be used only by document source providers. (DBPROP_DATASOURCE_TYPE is DBPROPVAL_DST_DOCSOURCE.) + /// + /// + /// + /// DBBINDURLSTATUS_S_OK + /// + /// The bind was successful and the status is reported as OK, because the provider returned a result other than DB_S_ERRORSOCCURRED + /// and pdwBindStatus was not a null pointer. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an interface pointer on the requested object. If IBindResource::Bind fails, + /// *ppUnk is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The bind succeeded. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The call to IBindResource::Bind has initiated asynchronous binding to the data source, rowset, or row. + /// The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous + /// processing. Until asynchronous processing completes, the data source, rowset, row, or stream object remains in an uninitialized state. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The bind succeeded, but some bind flags or properties were not satisfied. The consumer should examine the + /// bind status reported in *pdwBindStatus. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous binding. + /// + /// + /// + /// + /// DB_E_CANNOTCONNECT The provider could not connect to the server for this object. + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the object being created does not support aggregation. + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and pImplSession->piid did not point + /// to IID_IUnknown. + /// + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and the object being created does not + /// support aggregation. + /// + /// + /// IBindResource was implemented on an object other than a binder, rguid was DBGUID_DSO or DBGUID_SESSION, and pUnkOuter was + /// not a null pointer. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTCOLLECTION The client requested an object type that is valid only for a collection (such as a rowset), but the resource + /// at the specified URL is not a collection. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider was unable to locate an object named by the specified URL. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid. + /// + /// + /// + /// + /// + /// DB_E_OBJECTMISMATCH The object named by rguid does not represent the resource named by pwszURL. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support this operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// DB_E_READONLY The caller requested write access to a read-only object. + /// + /// + /// + /// + /// + /// DB_E_RESOURCELOCKED One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by + /// this URL. If a provider supports extended error information, IErrorInfo::GetDescription returns a string consisting of + /// user names separated by semicolons. These are the names of the users who have the object locked. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCEOUTOFSCOPE IBindResource is implemented on a session object, and the caller tried to bind to a URL that is + /// not within the scope of this session. + /// + /// + /// + /// + /// + /// DB_E_TIMEOUT The attempt to bind to the object timed out. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller's authentication context does not permit access to the object. + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and pwszURL specified an unsafe URL. + /// + /// + /// + /// + /// REGDB_E_CLASSNOTREG The root binder was unable to instantiate the provider binder. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL or ppUnk was null. + /// pImplSession was not a null pointer, and pImplSession->piid was null. + /// + /// dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the table above but did not contain the flag to be modified. + /// + /// The provider does not support one or more values of dwBindURLFlags. + /// + /// One of more of the bind flags in dwBindURLFlags are either not supported by the provider or disallowed for the object type + /// denoted by rguid. For flags allowed for each object type, see the table in the reference entry for IBindResource::Bind. + /// + /// + /// + /// + /// + /// E_NOINTERFACE The object did not support the interface specified in riid, or riid was IID_NULL. + /// The provider binder did not implement IBindResource. + /// + /// + /// + /// + /// + /// E_UNEXPECTED IBindResource::Bind is implemented on a row object; 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/ms721010(v=vs.85) + [PreserveSig] + HRESULT Bind([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, MarshalAs(UnmanagedType.LPWStr)] string pwszURL, DBBINDURLFLAG dwBindURLFlags, + in Guid rguid, in Guid riid, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, [In, Out, Optional] IntPtr pImplSession, + out DBBINDURLSTATUS pdwBindStatus, [MarshalAs(UnmanagedType.IUnknown)] out object? ppUnk); + } + + /// IChapteredRowset is the interface that allows consumers to manage chapters. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718180(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a93-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IChapteredRowset + { + /// Adds a reference count to an existing chapter. + /// [in] The handle of the chapter for which to increment the reference count. + /// + /// [out] A pointer to memory in which to return the reference count of the chapter handle. If pcRefCount is a null pointer, no + /// reference count is returned. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// DB_E_BADCHAPTER hChapter was invalid. + /// + /// + /// + /// + /// 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/ms719762(v=vs.85) HRESULT AddRefChapter ( HCHAPTER hChapter, + // DBREFCOUNT *pcRefCount); + [PreserveSig] + HRESULT AddRefChapter(HCHAPTER hChapter, out DBREFCOUNT pcRefCount); + + /// Releases a chapter. + /// [in] The chapter handle. + /// + /// [out] A pointer to memory in which to return the reference count of the chapter handle. If pcRefCount is a null pointer, no + /// reference count is returned. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG The rowset was not chaptered. + /// + /// + /// + /// + /// DB_E_BADCHAPTER hChapter was invalid. + /// + /// + /// + /// + /// + /// 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/ms715966(v=vs.85) HRESULT ReleaseChapter ( HCHAPTER hChapter, + // DBREFCOUNT *pcRefCount); + [PreserveSig] + HRESULT ReleaseChapter(HCHAPTER hChapter, out DBREFCOUNT pcRefCount); + } + + /// + /// IColumnsInfo is the simpler of two interfaces that can be used to expose information about columns of a rowset or prepared + /// command. It provides a limited set of information in an array. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725401(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a11-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IColumnsInfo + { + /// Returns the column metadata needed by most consumers. + /// + /// [out] A pointer to memory in which to return the number of columns in the rowset; this number includes the bookmark column, if + /// there is one. If IColumnsInfo::GetColumnInfo is called on a command that does not return rows, *pcColumns is set to zero. + /// If this method terminates due to an error, *pcColumns is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in + /// the rowset. 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 column information. If *pcColumns is 0 on output or terminates due + /// to an error, the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more + /// information, see "DBCOLUMNINFO Structures" in the Comments section. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used either within columnid or for + /// pwszName) within a single allocation block. If no returned columns have either form of string name or if this method terminates + /// due to error, this parameter returns a null pointer. If there are any string names, this will be a buffer containing all the + /// values of those names. The consumer should free the buffer with IMalloc::Free when finished working with the names. If + /// *pcColumns is zero on output, the provider does not allocate any memory and ensures that *ppStringsBuffer is a null pointer on + /// output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the + /// buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcColumns, prgInfo, or ppStringsBuffer was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details + /// about the errors. + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This + /// error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) HRESULT GetColumnInfo ( DBORDINAL + // *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); + [PreserveSig] + HRESULT GetColumnInfo(out DBORDINAL pcColumns, out SafeIMallocHandle prgInfo, out SafeIMallocHandle ppStringsBuffer); + + /// Returns an array of ordinals of the columns in a rowset that are identified by the specified column IDs. + /// + /// [in] The number of column IDs to map. If cColumnIDs is 0, IColumnsInfo::MapColumnIDs does nothing and returns S_OK. + /// + /// + /// [in] An array of IDs of the columns of which to determine the column ordinals. If rgColumnIDs contains a duplicate column ID, a + /// column ordinal is returned once for each occurrence of the column ID. If the column ID is invalid, the corresponding element of + /// rgColumns is set to DB_INVALIDCOLUMN. + /// + /// + /// [out] An array of cColumnIDs ordinals of the columns identified by the elements of rgColumnIDs. 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 + /// column IDs in the array. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. All elements of rgColumns are set to values other than DB_INVALIDCOLUMN. + /// + /// cColumnIDs was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cColumnIDs was zero and + /// either or both rgColumnIDs and rgColumns was a null pointer. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An element of rgColumnIDs was invalid. If the column ID is invalid, the corresponding element of rgColumns is + /// set to DB_INVALIDCOLUMN. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cColumnIDs was not 0, and rgColumnIDs was a null pointer. + /// rgColumns was a null pointer. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All elements of rgColumnIDs were invalid. All elements of rgColumns are set to DB_INVALIDCOLUMN. + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This + /// error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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/ms714200(v=vs.85) HRESULT MapColumnIDs ( DBORDINAL cColumnIDs, + // const DBID rgColumnIDs[], DBORDINAL rgColumns[]); + [PreserveSig] + HRESULT MapColumnIDs(DBORDINAL cColumnIDs, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDs, + [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBORDINAL[]? rgColumns); + } + + /// The IColumnsInfo2 interface allows a consumer to obtain column names or metadata for the columns in a row or rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712953(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733ab8-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IColumnsInfo2 : IColumnsInfo + { + /// Returns the column metadata needed by most consumers. + /// + /// [out] A pointer to memory in which to return the number of columns in the rowset; this number includes the bookmark column, if + /// there is one. If IColumnsInfo::GetColumnInfo is called on a command that does not return rows, *pcColumns is set to zero. + /// If this method terminates due to an error, *pcColumns is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in + /// the rowset. 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 column information. If *pcColumns is 0 on output or terminates due + /// to an error, the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more + /// information, see "DBCOLUMNINFO Structures" in the Comments section. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used either within columnid or for + /// pwszName) within a single allocation block. If no returned columns have either form of string name or if this method terminates + /// due to error, this parameter returns a null pointer. If there are any string names, this will be a buffer containing all the + /// values of those names. The consumer should free the buffer with IMalloc::Free when finished working with the names. If + /// *pcColumns is zero on output, the provider does not allocate any memory and ensures that *ppStringsBuffer is a null pointer on + /// output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the + /// buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcColumns, prgInfo, or ppStringsBuffer was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details + /// about the errors. + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This + /// error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) HRESULT GetColumnInfo ( DBORDINAL + // *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); + [PreserveSig] + new HRESULT GetColumnInfo(out DBORDINAL pcColumns, out SafeIMallocHandle prgInfo, out SafeIMallocHandle ppStringsBuffer); + + /// Returns an array of ordinals of the columns in a rowset that are identified by the specified column IDs. + /// + /// [in] The number of column IDs to map. If cColumnIDs is 0, IColumnsInfo::MapColumnIDs does nothing and returns S_OK. + /// + /// + /// [in] An array of IDs of the columns of which to determine the column ordinals. If rgColumnIDs contains a duplicate column ID, a + /// column ordinal is returned once for each occurrence of the column ID. If the column ID is invalid, the corresponding element of + /// rgColumns is set to DB_INVALIDCOLUMN. + /// + /// + /// [out] An array of cColumnIDs ordinals of the columns identified by the elements of rgColumnIDs. 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 + /// column IDs in the array. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. All elements of rgColumns are set to values other than DB_INVALIDCOLUMN. + /// + /// cColumnIDs was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cColumnIDs was zero and + /// either or both rgColumnIDs and rgColumns was a null pointer. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An element of rgColumnIDs was invalid. If the column ID is invalid, the corresponding element of rgColumns is + /// set to DB_INVALIDCOLUMN. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cColumnIDs was not 0, and rgColumnIDs was a null pointer. + /// rgColumns was a null pointer. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All elements of rgColumnIDs were invalid. All elements of rgColumns are set to DB_INVALIDCOLUMN. + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This + /// error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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/ms714200(v=vs.85) HRESULT MapColumnIDs ( DBORDINAL cColumnIDs, + // const DBID rgColumnIDs[], DBORDINAL rgColumns[]); + [PreserveSig] + new HRESULT MapColumnIDs(DBORDINAL cColumnIDs, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDs, + [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBORDINAL[]? rgColumns); + + /// + /// + /// Retrieves column names or column metadata for a row or rowset. Column names are returned in an array of column IDs (DBIDs). + /// Column metadata is returned in an array of DBCOLUMNINFO structures. + /// + /// For information about column IDs, see Column IDs. For information about DBCOLUMNINFO structures, see IColumnsInfo::GetColumnInfo. + /// + /// + /// [in] The count of column name masks in rgColumnIDMasks. If cColumnIDMasks is zero, IColumnsInfo2::GetRestrictedColumnInfo + /// enumerates all columns in the row. + /// + /// + /// [in] An array of cColumnIDMasks column name masks used to restrict the set of columns enumerated. All columns whose DBID matches + /// the elements of rgColumnIDMasks or whose names begin with the string contained in the pwszName element of any of the DBIDs in + /// this array will be returned in the enumeration. If cColumnIDMasks is zero, rgColumnIDMasks is ignored. + /// + /// [in] Reserved. Must be zero. + /// + /// [out] A pointer to memory in which to return a count of the column names and DBCOLUMNINFO structures returned in prgColumnIDs and + /// prgColumnInfo, respectively. If no columns are described or if the method terminates with an error, ***pcColumns is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of column IDs (DBIDs) containing the requested column names. + /// IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. This argument + /// duplicates the DBIDs provided in the prgColumnInfo argument but is provided for direct use with methods such as + /// IRowSchemaChange::DeleteColumns that require an array of DBIDs. The provider allocates memory for the DBIDs. The consumer is + /// responsible for releasing this memory with IMalloc::Free. If an error code is returned and prgColumnIDs is not a null pointer, + /// ***prgColumnIDs should be set to NULL. + /// + /// + /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures containing the requested column names. + /// IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. The provider + /// allocates memory for the DBCOLUMNINFO structures. The consumer is responsible for releasing this memory with IMalloc::Free. If an + /// error code is returned and prgColumnInfo is not a null pointer, ***prgColumnInfo should be set to NULL. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used with either columnid or + /// *pwszName of the DBCOLUMNINFO structure) within a single allocation block. If no columns are returned, ppStringsBuffer should be + /// set to NULL. If there are any string names, ppStringsBuffer points to a buffer containing all the values of those names. The + /// consumer is responsible for releasing this memory with IMalloc::Free. If an error code is returned and ppStringsBuffer is not a + /// null pointer, ***ppStringsBuffer should be set to NULL. + /// + /// + /// + /// + /// + /// S_OK The requested columns were successfully enumerated. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID An element of rgColumnIDMasks was an invalid DBID. + /// + /// + /// + /// + /// DB_E_DELETEDROW The row was deleted or moved. + /// + /// + /// + /// + /// + /// DB_E_NOCOLUMN No columns matched the mask criteria. The provider sets ***pcColumns to zero and other output arguments to NULL. + /// + /// + /// + /// + /// + /// + /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. + /// + /// + /// + /// + /// E_INVALIDARG cColumnIDMasks was not zero, and rgColumnIDMasks was a null pointer. + /// pcColumns was a null pointer. + /// ppStringsBuffer was a null pointer. + /// prgColumnIDs and prgColumnInfo are both null pointers. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures or + /// string buffer. + /// + /// + /// + /// + /// + /// 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/ms712988(v=vs.85) HRESULT GetRestrictedColumnInfo( DBORDINAL + // cColumnIDMasks, const DBID rgColumnIDMasks[ ], DWORD dwFlags, DBORDINAL *pcColumns, DBID **prgColumnIDs, DBCOLUMNINFO + // **prgColumnInfo, OLECHAR **ppStringsBuffer); + void GetRestrictedColumnInfo(DBORDINAL cColumnIDMasks, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDMasks, + [Optional] uint dwFlags, out DBORDINAL pcColumns, out SafeIMallocHandle prgColumnIDs, out SafeIMallocHandle prgColumnInfo, out SafeIMallocHandle ppStringsBuffer); + } + + /// + /// This interface supplies complete information about columns in a rowset. The methods in it can be called from a rowset or a command. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722657(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a10-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IColumnsRowset + { + /// Returns a list of optional metadata columns that can be supplied in a column metadata rowset. + /// + /// [out] A pointer to memory in which to return the count of the elements in *prgOptColumns. If an error occurs, *pcOptColumns is + /// set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of the optional columns this provider can supply. In addition to the + /// optional columns listed in IColumnsRowset::GetColumnsRowset, the provider can return provider-specific columns. The rowset + /// or command 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 list of columns. If *pcOptColumns is zero on output or an error occurs, the + /// provider does not allocate any memory and ensures that *prgOptColumns is a null pointer on output. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcOptColumns or prgOptColumns was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column IDs. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This + /// error can be returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This + /// error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the available optional metadata columns. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718245(v=vs.85) HRESULT GetAvailableColumns ( DBORDINAL + // *pcOptColumns, DBID **prgOptColumns); + [PreserveSig] + HRESULT GetAvailableColumns(out DBORDINAL pcOptColumns, out SafeIMallocHandle prgOptColumns); + + /// + /// Returns a rowset containing metadata about each column in the current rowset. This rowset is known as the column metadata rowset + /// and is read-only. + /// + /// + /// [in] A pointer to the controlling IUnknown interface if the column metadata rowset is being created as part of an + /// aggregate. It is a null pointer if the rowset is not part of an aggregate. + /// + /// + /// [in] The number of the elements in rgOptColumns. If cOptColumns is zero, rgOptColumns is ignored and the provider returns all + /// available columns in the columns rowset. + /// + /// + /// [in] An array that specifies the optional columns to return. In addition to the optional columns listed below, the consumer can + /// request provider-specific columns. + /// + /// + /// [in] The IID of the requested rowset interface. This interface is conceptually added to the list of required interfaces on the + /// resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, it is + /// provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix + /// C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on the column metadata rowset. If an error occurs, + /// the returned pointer is null. If IColumnsRowset::GetColumnsRowset is called on a command that does not return rows, the + /// column metadata rowset will be empty. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to + /// poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call + /// any other interfaces may fail, and the full set of interfaces may not be available on the object until asynchronous + /// initialization of the rowset has completed. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The rowset was opened, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including: + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. Of course, the + /// properties-in-error are not available, but for any properties that could not be set, the provider should report that status in + /// the property array passed to IColumnsRowset::GetColumnsRowset.Thisassumes that property failures can all be determined + /// ahead of rowset population. + /// + /// + /// + /// + /// + /// + /// DB_S_NOTSINGLETON The provider supports returning row objects on IColumnsRowset::GetColumnsRowset, and the consumer + /// requested a row object but the result was not a singleton. A row object of the first row of the rowset is returned if the + /// provider supports returning the row object. Because returning this result may be expensive, providers are not required to do so. + /// If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes precedence over DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppColRowset was a null pointer. + /// cPropertySets was greater than zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// cOptColumns was greater than zero, and rgOptColumns was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The column metadata 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. This error can be + /// returned only when the method is called on a rowset. + /// + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED The method failed because a resource limit has been reached. For example, a query used to implement the + /// method timed out. No rowset is returned. + /// + /// + /// + /// + /// + /// DB_E_BADCOLUMNID An element of rgOptColumns was an invalid DBID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No rowset was returned because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties + /// for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was + /// requested via riid or DBPROP_IRow, and no rows existed in the rowset. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This error + /// can be returned only when this method is called from the command object. + /// + /// + /// + /// + /// + /// + /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the column metadata rowset. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712925(v=vs.85) HRESULT GetColumnsRowset ( IUnknown + // *pUnkOuter, DBORDINAL cOptColumns, const DBID rgOptColumns[], REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[], + // IUnknown **ppColRowset); + [PreserveSig] + HRESULT GetColumnsRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, DBORDINAL cOptColumns, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBID[] rgOptColumns, in Guid riid, uint cPropertySets, + [In, Out] SafeDBPROPSETListHandle rgPropertySets, [MarshalAs(UnmanagedType.IUnknown)] out object? ppColRowset); + } + + /// + /// + /// ICommand contains methods to execute commands. A command can be executed many times, and the parameter values can vary. This + /// interface is mandatory on commands. + /// + /// A command object contains a single text command, which is specified through ICommandText + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709737(v=vs.85) + [PInvokeData("")] + [ComImport, Guid("0c733a63-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommand + { + /// Cancels the current command execution. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714402(v=vs.85) HRESULT Cancel(); + void Cancel(); + + /// Executes the command. + /// + /// [in] A pointer to the controlling IUnknown interface if the rowset is being created as part of an aggregate; otherwise, it + /// is null. + /// + /// + /// + /// [in] The requested IID for the rowset returned in *ppRowset. This interface is conceptually added to the list of required + /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting + /// rowset. If the command has any open rowsets, requesting an interface that is not supported on those open rowsets will generally + /// return E_NOINTERFACE as it is not possible to change the properties supported on a command with open rowsets. In addition, + /// specifying the IID of a nonmandatory interface that has not been explicitly requested through rowset properties set on a prepared + /// command might reduce the provider's ability to optimize the command, because the provider might have to rebuild the access plan + /// to satisfy the additional interface. + /// + /// + /// If this is IID_NULL, ppRowset is ignored and no rowset is returned, even if the command would otherwise generate a rowset. + /// Specifying IID_NULL is useful in the case of text commands that do not generate rowsets, such as data definition commands, as a + /// hint to the provider that no rowset properties need to be verified. + /// + /// + /// If riid is IID_IMultipleResults, the provider creates a multiple results object and returns a pointer to it in *ppRowset; + /// it does this even if the command generates a single result. If the provider supports multiple results and the command generates + /// multiple results but riid is not IID_IMultipleResults, the provider returns the first result and discards any remaining + /// results. If riid is IID_IMultipleResults and the provider does not support multiple results, ICommand::Execute + /// returns E_NOINTERFACE. + /// + /// + /// + /// + /// [in/out] A pointer to a DBPARAMS structure that specifies the values for one or more parameters. In text commands that use + /// parameters, if no value is specified for a parameter through pParams, an error occurs. + /// + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// pData + /// + /// Pointer to a buffer from which the provider retrieves input parameter data and to which the provider returns output parameter + /// data, according to the bindings specified by hAccessor. This pointer must be a valid pointer to a contiguous block of + /// consumer-owned memory for the input and output parameter values. For more information, see Getting Data and Setting Data. When + /// output parameter data is available to the consumer depends on the DBPROP_OUTPUTPARAMETERAVAILABILITY property. + /// + /// + /// + /// cParamSets + /// + /// The number of sets of parameters in * pData. If cParamSets is greater than one, the bindings described by + /// hAccessor define the offsets within * pData for each set of parameters and cbRowSize (as specified in + /// IAccessor::CreateAccessor) defines a single fixed offset between each of those values and the corresponding values for the + /// next set of parameters. Sets of multiple parameters ( cParamSets is greater than one) can be specified only if + /// DBPROP_MULTIPLEPARAMSETS is VARIANT_TRUE and the command does not return any rowsets. + /// + /// + /// + /// hAccessor + /// + /// Handle of the accessor to use. If hAccessor is the handle of a null accessor ( cBindings in + /// IAccessor::CreateAccessor was 0), ICommand::Execute does not retrieve or return any parameter values. + /// + /// + /// + /// + /// If the provider is able to determine the number of parameters in the command and the command text does not include parameters, + /// the provider ignores this argument. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the count of rows affected by a command that updates, deletes, or inserts rows. If + /// cParamSets is greater than one, *pcRowsAffected is the total number of rows affected by all of the sets of parameters specified + /// in the execution. If the number of affected rows is not available, *pcRowsAffected is set to DB_COUNTUNAVAILABLE on output. If + /// riid is IID_IMultipleResults, the value returned in *pcRowsAffected is either DB_COUNTUNAVAILABLE or the total number of + /// rows affected by the entire command; to retrieve individual row counts, the consumer calls IMultipleResults::GetResult. If + /// the command does not update, delete, or insert rows, *pcRowsAffected is undefined on output. If pcRowsAffected is a null pointer, + /// no count of rows is returned. + /// + /// + /// pcRowsAffected is undefined if ICommand::Execute returns DB_S_ASYNCHRONOUS. For asynchronously executed commands, the + /// consumer should call IDBAsynchStatus::GetStatus to obtain the number of rows affected in pulProgress. + /// + /// + /// + /// + /// [in/out] A pointer to the memory in which to return the rowset's pointer. If ppRowset is a null pointer, no rowset is created. + /// However, if the DBPROP_OUTPUTSTREAM property is set and the result of ICommand::Execute is a stream object, a null pointer + /// is an acceptable value. + /// + /// + /// If ppRowset is not a null pointer and an interface on a stream object was requested, the provider returns to *ppRowset the + /// interface pointer set in the DBPROP_OUTPUTSTREAM property. The consumer must release the interface pointer in *ppRowset when it + /// is no longer needed. + /// + /// If *ppRowset is a null pointer, the provider did not write any results to the stream specified in DBPROP_OUTPUTSTREAM. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK; the status of all + /// input parameters bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL; and the status of all output parameters + /// bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED ? or is unknown because the parameter + /// value has not been returned yet. + /// + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to + /// poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any + /// other interfaces may fail, and the full set of interfaces may not be available on the object until asynchronous initialization of + /// the rowset has completed. DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED This can be returned for any of the following reasons: + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// DB_S_ERRORSOCCURRED should be returned before DB_S_NOTSINGLETON because the status values can be checked, and providers are not + /// required to return DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// + /// DB_S_NOTSINGLETON The provider supports returning row objects on ICommand::Execute, and the consumer requested a row + /// object but the result was not a singleton. A row object of the first row of the rowset is returned. Returning this result may be + /// expensive, so providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes + /// precedence over DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// + /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been + /// returned. Execution cannot be resumed. + /// + /// + /// Multiple sets of parameters were specified, and one or more (but not all) of the parameters have been processed prior to the + /// command being canceled by ICommand::Cancel or IDBAsynchStatus::Abort. + /// + /// + /// 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 riid was not IID_NULL, and ppRowset was a null pointer. Any streams used to pass input parameters are not released. + /// + /// + /// The parameter information was invalid. Parameter information may be invalid for any of the following reasons. In all cases, any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_IMultipleResults, and the provider did not support multiple results objects. + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED Execution has been aborted because a resource limit has been reached. For example, a query timed out. No + /// results have been returned. + /// + /// + /// + /// + /// + /// + /// DB_E_BADACCESSORHANDLE pParams was not ignored, and hAccessor in the DBPARAMS structure pointed to by pParams was invalid. Any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// + /// DB_E_BADACCESSORTYPE hAccessor in the DBPARAMS structure pointed to by pParams was not the handle of a parameter accessor. Any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// DB_E_CANCELED The command was canceled by a call to ICommand::Cancel on another thread. No records were affected. + /// + /// + /// + /// + /// + /// DB_E_CANTCONVERTVALUE A literal value in the command text could not be converted to the type of the associated column for reasons + /// other than data overflow. + /// + /// + /// + /// + /// + /// DB_E_DATAOVERFLOW A literal value in the command text overflowed the type specified by the associated column. + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details + /// about the errors. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The method failed due to one or more nonvalid input parameter values. To determine which input parameter + /// values were not valid, 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.) If any streams were used to pass input parameters, only those with the + /// status value equal to DBSTATUS_S_OK on input are released; otherwise, no attempt is made to release the stream. If the consumer + /// provides storage objects for additional bound parameters that are not used by the current command, it is a consumer programming + /// error and the provider does not attempt to release these parameters. + /// + /// + /// The command was not executed, and no rowset was returned because one or more properties ? for which the dwOptions element of the + /// DBPROP structure was DBPROPOPTIONS_REQUIRED ? were not set. + /// + /// Multiple parameter sets were passed with a command that returns a rowset. (Some providers might not return this error.) + /// + /// + /// + /// + /// DB_E_INTEGRITYVIOLATION A literal value in the command text violated the integrity constraints for the column. + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. Any streams used to pass input parameters are not released. + /// + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. Any streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was currently set on the command object. Any streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider supports row objects, a row was requested via riid or DBPROP_IRow, and no rows satisfied the selection + /// criteria of the command. + /// + /// + /// + /// + /// + /// DB_E_PARAMNOTOPTIONAL A value was not supplied for a required parameter. + /// The command text used parameters and pParams was a null pointer. + /// + /// + /// + /// + /// + /// DB_E_PARAMUNAVAILABLE Provider cannot derive parameter information, and ICommandWithParameters::SetParameterInfo has not + /// been called. + /// + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to execute the command. For example, a rowset-returning + /// command specified a column for which the consumer does not have read permission, or an update command specified a column for + /// which the consumer does not have write permission. + /// + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. Any streams used to pass input parameters are not released. + /// + /// + /// If a session is enlisted in a global transaction and a command requires the creation of an additional connection, the provider + /// should return DB_E_OBJECTOPEN. Providers written prior to OLE DB 2.6 may return E_FAIL. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718095(v=vs.85) HRESULT Execute ( IUnknown *pUnkOuter, + // REFIID riid, DBPARAMS *pParams, DBROWCOUNT *pcRowsAffected, IUnknown **ppRowset); + [PreserveSig] + HRESULT Execute([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [In, Out, Optional] DBPARAMS? pParams, + out DBROWCOUNT pcRowsAffected, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Returns an interface pointer to the session that created the command. + /// [in] The IID of the interface on which to return a pointer. + /// + /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the + /// command, it sets *ppSession to a null pointer. If ICommand::GetDBSession fails, it must attempt to set *ppSession to a + /// null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// S_FALSE The provider did not have an object that created the command. Therefore, it set *ppSession to a null pointer. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppSession was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The session did not support the interface specified in riid. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719622(v=vs.85) HRESULT GetDBSession ( REFIID riid, IUnknown **ppSession); + [PreserveSig] + HRESULT GetDBSession(in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppSession); + } + + /// + /// + /// Command objects support ICommandPersist for persisting the state of a command object. Persisting a command object does not + /// persist any active rowsets that may have resulted from the execution of the command object, nor does it persist accessors, property + /// settings, or parameter information associated with the command object. + /// + /// + /// Persisted commands can be enumerated through the PROCEDURES rowset. Persisted commands that can act as the source of a new command + /// (that is, a table in an SQL FROM clause) can be enumerated through the VIEWS rowset. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722664(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aa7-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandPersist + { + /// Deletes a persisted command definition. + /// [in] The DBID of the command to be deleted. + /// + /// + /// + /// + /// S_OK The command was successfully deleted. + /// + /// + /// + /// + /// DB_E_BADCOMMANDID The command specified in *pCommandID does not exist. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN An attempt was made to delete a command(view) used to create one or more open rowsets. The provider determines if + /// the DeleteCommand succeeds. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pCommandID was a null pointer. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723766(v=vs.85) HRESULT DeleteCommand( DBID *pCommandID); + [PreserveSig] + HRESULT DeleteCommand(in DBID pCommandID); + + /// Returns the DBID of the current command. + /// [out] A pointer to memory in which to return the pointer to the DBID of the current command. + /// + /// + /// + /// + /// S_OK The DBID of the command was successfully returned. + /// + /// + /// + /// + /// E_OUTOFMEMORY There is not enough memory to successfully return the command's DBID. + /// + /// + /// + /// + /// DB_E_COMMANDNOTPERSISTED The current command does not yet have a DBID. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppCommandID was a null pointer. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716792(v=vs.85) HRESULT GetCurrentCommand( DBID **ppCommandID); + [PreserveSig] + HRESULT GetCurrentCommand(out IntPtr ppCommandID); + + /// Loads a persisted command definition. + /// [in] The DBID of the command to load. + /// [in] Reserved for future use. Consumers should set this value to zero. Providers should ignore this argument. + /// + /// + /// + /// + /// S_OK The command was successfully loaded. + /// + /// + /// + /// + /// E_OUTOFMEMORY There is not enough memory to successfully load the command. + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset was open on the command. + /// + /// + /// + /// + /// DB_E_BADCOMMANDID The command specified in *pCommandID does not exist. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pCommandID was a null pointer, or dwFlags was not zero. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714946(v=vs.85) HRESULT LoadCommand( DBID *pCommandID, DWORD dwFlags); + [PreserveSig] + HRESULT LoadCommand(in DBID pCommandID, uint dwFlags = 0); + + /// Persists the current command definition. + /// + /// [in] The DBID to assign to the persisted command. If this is a null pointer and the command already has a DBID, the provider + /// saves the current version with the same DBID. If this is a null pointer and the command does not already have a DBID, the + /// provider assigns an ID to the command. The ID must be unique. + /// + /// + /// [in] Options for persisting command definition. The following flags are possible: + /// + /// + /// Flag + /// Description + /// + /// + /// DBCOMMANDPERSISTFLAG_NOSAVE + /// + /// You can use DBCOMMANDPERSISTFLAG_NOSAVE to associate or obtain a new DBID for the command without actually persisting the definition. + /// + /// + /// + /// DBCOMMANDPERSISTFLAG_PERSISTVIEW + /// + /// The command is to be persisted as a view. Views are row-returning objects that do not contain parameters or return values and can + /// generally be used anywhere a base table is used. Views can be enumerated through the DBSCHEMA_VIEWS schema rowset. + /// + /// + /// + /// DBCOMMANDPERSISTFLAG_PERSISTPROCEDURE + /// + /// The command is to be persisted as a procedure. Procedures may or may not return rows and may or may not contain parameters or + /// return values. Procedures can be enumerated through the DBSCHEMA_PROCEDURES schema rowset. + /// + /// + /// + /// DBCOMMANDPERSISTFLAG_DEFAULT + /// The behavior of DBCOMMANDPERSISTFLAGS_DEFAULT is provider specific. + /// + /// + /// + /// DBCOMMANDPERSISTFLAG_PERSISTVIEW and DBCOMMANDPERSISTFLAG_PERSISTPROCEDURE are mutually exclusive. If neither is specified, the + /// provider persists the command as a default type. + /// + /// + /// + /// + /// + /// + /// S_OK The command was successfully saved. + /// + /// + /// + /// + /// DB_E_BADCOMMANDID The DBID specified in *pCommandID was invalid. + /// + /// + /// + /// + /// DB_E_BADCOMMANDFLAGS dwFlags was invalid. + /// In dwFlags, both DBCOMMANDPERSISTFLAG_PERSISTVIEW and DBCOMMANDPERSISTFLAG_PERSISTPROCEDURE were specified. + /// DBCOMMANDPERSISTFLAG_PERSISTVIEW was specified, and the command could not be persisted as a view. + /// DBCOMMANDPERSISTFLAG_PERSISTPROCEDURE was specified, and the command could not be persisted as a procedure. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATEID The specified DBID already exists. If the provider supports the use of persisted commands as a source in a new + /// command definition, DBIDs must be unique across persisted commands, procedures, tables, and views. + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND An invalid command has been set using ICommandText::SetCommandText(). + /// + /// + /// + /// + /// DB_E_NOCOMMAND SaveCommand() called without setting the command text. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG Should never be returned by ICommandPersist::SaveCommand(). See Comments below. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712917(v=vs.85) HRESULT SaveCommand( DBID *pCommandID, DWORD dwFlags); + [PreserveSig] + HRESULT SaveCommand(in DBID pCommandID, DBCOMMANDPERSISTFLAG dwFlags); + } + + /// + /// + /// This optional interface encapsulates command optimization, a separation of compile time and run time, as found in traditional + /// relational database systems. The result of this optimization is a command execution plan. + /// + /// + /// If the provider supports command preparation, by supporting this interface, commands must be in a prepared state prior to calling the + /// following methods: + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713621(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a26-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandPrepare + { + /// Validates and optimizes the current command. + /// + /// [in] Using this parameter, the consumer can indicate how often the command execution plan, which is produced by + /// ICommandPrepare::Prepare, will be used ? that is, how often the command is likely to be executed without renewed optimization. + /// This guides the optimizer in determining trade-offs between search effort and run-time processing effort. A value of zero + /// indicates that the consumer is unable to provide an estimate and leaves it to the optimizer to choose a default value. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The command was prepared but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer calls ICommandProperties::GetProperties to determine which + /// properties were set. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider ran out of memory while preparing the command. + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED Preparation has been aborted because a resource limit has been reached. For example, the preparation timed out. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details + /// about the errors. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The command was not prepared because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED ? were not set. The consumer calls ICommandProperties::GetProperties to determine + /// which properties were not set. + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was currently set on the command object. + /// + /// + /// + /// + /// DB_E_NOTABLE The specific table or view does not exist in the data store. + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset was open on the command. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to prepare the command. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718370(v=vs.85) HRESULT Prepare ( ULONG cExpectedRuns); + [PreserveSig] + HRESULT Prepare(uint cExpectedRuns); + + /// Discards the current command execution plan. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset was open on the command. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719635(v=vs.85) HRESULT Unprepare(); + [PreserveSig] + HRESULT Unprepare(); + } + + /// + /// + /// ICommandProperties specifies to the command the properties from the Rowset property group that must be supported by the + /// rowsets returned by ICommand::Execute. A special case of these properties, and the ones most commonly requested, are the + /// interfaces the rowset must support. In addition to interfaces, the consumer can request properties that modify the behavior of the + /// rowset or interfaces. + /// + /// + /// All rowsets must support IRowset, IAccessor, IColumnsInfo, IRowsetInfo, and IConvertType. + /// Providers may choose to return rowsets supporting other interfaces if doing so is possible and if the support for the returned + /// interfaces does not affect consumer code that is not expecting them. The riid parameter of ICommand::Execute should be one of + /// the interfaces returned by IRowsetInfo::GetProperties. + /// + /// This interface is mandatory on commands. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723044(v=vs.85) + [PInvokeData("")] + [ComImport, Guid("0c733a79-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandProperties + { + /// Returns the list of properties in the Rowset property group that are currently requested for the rowset. + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Rowset property + /// group for which values have been set or defaults exist. It does not return the values of properties in the Rowset property group + /// for which values have not been set and no defaults exist nor does it return the values of properties for which no value has been + /// set, no default exists, and for which a value will be set automatically because a value for another property in the Rowset + /// property group has been set. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the + /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of + /// dwOptions is undefined. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset + /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this + /// parameter is ignored. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix + /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets + /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Rowset + /// property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than + /// DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is + /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs in an element of rgPropertyIDSets is not zero, the DBPROP structures in the corresponding element of + /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column + /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties + /// have the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, + /// one for each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the + /// same property ID and rgProperties will contain more elements than rgPropertyIDs. + /// + /// + /// 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 *pcPropertySets is zero on output or an error other than + /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. ICommandProperties::GetProperties can fail to return + /// properties for a number of reasons, including: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero, or + /// rgPropertyIDs was not a null pointer. + /// + /// cPropertyIDSets was greater than one, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No values were returned for any properties. The provider allocates memory for *prgPropertySets, and the + /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory + /// when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723119(v=vs.85) HRESULT GetProperties ( const ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG * pcPropertySets, DBPROPSET ** prgPropertySets); + [PreserveSig] + HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, + out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); + + /// Sets properties in the Rowset property group. + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method + /// does not do anything. + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, the + /// value is used is provider-specific. If cPropertySets is zero, this parameter is ignored. + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix + /// C.For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the + /// DBPROP structures to determine which properties were not set. ICommandProperties::SetProperties can fail to set properties + /// for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertySets was not equal to zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All property values were invalid and no properties were set. The consumer checks dwStatus in the DBPROP + /// structures to determine why properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN Properties cannot be set while there is an open rowset. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711497(v=vs.85) HRESULT SetProperties ( ULONG cPropertySets, + // DBPROPSET rgPropertySets[]); + [PreserveSig] + HRESULT SetProperties(uint cPropertySets, [In] SafeDBPROPSETListHandle? rgPropertySets); + } + + /// + /// ICommandStream, while similar to ICommandText, passes a command as a stream object rather than as a string. + /// ICommandStream is not a mandatory interface. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724412(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733abf-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandStream + { + /// Returns the currently set interface pointer of a stream object containing a command. + /// + /// [out] + /// A pointer to memory where the provider returns an IID that specifies the type of object referenced by *ppCommandStream. + /// If piid is a null pointer on input, the provider does not return the IID. + /// If this method returns an error, *piid is set to IID_NULL. + /// + /// + /// [in/out] + /// + /// A pointer to memory containing a GUID that specifies the syntax and general rules for parsing the command stream ? that is, the + /// dialect that will be used by the provider to interpret the statement. This is usually the dialect specified in ICommandStream::SetCommandStream. + /// + /// + /// However, if DBGUID_DEFAULT is specified in SetCommandStream, the provider returns the particular dialect that it will use + /// to interpret the statement. If the provider must choose between multiple dialects at execution time for a command that has been + /// set with DBGUID_DEFAULT or if the provider is returning some provider-specific syntax that might be different from the command + /// set in ICommandStream::SetCommandStream, it returns DBGUID_DEFAULT. Providers can define GUIDs for their own dialects. + /// + /// If ICommandStream::GetCommandStream returns an error, *pguidDialect is set to DB_NULLGUID. + /// If pguidDialect is a null pointer on input, the provider does not return the dialect. + /// + /// + /// [out] + /// + /// A pointer to memory where the command stream interface pointer is returned. If ICommandStream::GetCommandStream returns an + /// error, *ppCommandStream is set to a null pointer. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_DIALECTIGNORED The method succeeded, but the input value of pguidDialect was ignored. The text is returned in the dialect + /// specified in ICommandStream::SetCommandStream or in a provider-specific dialect. The value returned in *pguidDialect + /// represents that dialect. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppCommandStream was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory to return the command stream. + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command was currently set on the command object. + /// + /// + /// + /// + /// DB_E_CANTTRANSLATE The last command was set using ICommandText::SetCommandText, not ICommandStream::SetCommandStream. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724347(v=vs.85) HRESULT GetCommandStream ( IID *piid, GUID + // *pguidDialect, IUnknown **ppCommandStream); + [PreserveSig] + HRESULT GetCommandStream(out Guid piid, [In, Out, Optional] GuidPtr pguidDialect, [MarshalAs(UnmanagedType.IUnknown)] out object? ppCommandStream); + + /// Sets the interface pointer of a stream object containing a command. + /// + /// [in] + /// Specifies the type of stream object representing the command. + /// + /// + /// [in] + /// Specifies the dialect of the command. + /// If this parameter is set to DBGUID_DEFAULT, the provider uses its default dialect. + /// + /// + /// [in] + /// Pointer to a stream object of a type specified by riid. + /// + /// If pCommandStream is a null pointer, the specification of the current command stream object is cleared and the command is put in + /// an initial state. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE One of the following occurred: + /// + /// + /// + /// + /// DB_E_DIALECTNOTSUPPORTED The provider did not support the dialect specified in rguidDialect. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The output stream returned by a previous call to ICommand::Execute is still open. Release that stream + /// before calling this method. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722625(v=vs.85) HRESULT SetCommandStream ( REFIID riid, + // REFGUID rguidDialect, IUnknown *pCommandStream); + [PreserveSig] + HRESULT SetCommandStream(in Guid riid, in Guid rguidDialect, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pCommandStream); + } + + /// + /// This interface is mandatory on commands. + /// + /// A command object can have only one text command. When the command text is specified through ICommandText::SetCommandText, it + /// replaces the existing command text. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714914(v=vs.85) + [PInvokeData("")] + [ComImport, Guid("0c733a27-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandText : ICommand + { + /// Cancels the current command execution. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714402(v=vs.85) HRESULT Cancel(); + new void Cancel(); + + /// Executes the command. + /// + /// [in] A pointer to the controlling IUnknown interface if the rowset is being created as part of an aggregate; otherwise, it + /// is null. + /// + /// + /// + /// [in] The requested IID for the rowset returned in *ppRowset. This interface is conceptually added to the list of required + /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting + /// rowset. If the command has any open rowsets, requesting an interface that is not supported on those open rowsets will generally + /// return E_NOINTERFACE as it is not possible to change the properties supported on a command with open rowsets. In addition, + /// specifying the IID of a nonmandatory interface that has not been explicitly requested through rowset properties set on a prepared + /// command might reduce the provider's ability to optimize the command, because the provider might have to rebuild the access plan + /// to satisfy the additional interface. + /// + /// + /// If this is IID_NULL, ppRowset is ignored and no rowset is returned, even if the command would otherwise generate a rowset. + /// Specifying IID_NULL is useful in the case of text commands that do not generate rowsets, such as data definition commands, as a + /// hint to the provider that no rowset properties need to be verified. + /// + /// + /// If riid is IID_IMultipleResults, the provider creates a multiple results object and returns a pointer to it in *ppRowset; + /// it does this even if the command generates a single result. If the provider supports multiple results and the command generates + /// multiple results but riid is not IID_IMultipleResults, the provider returns the first result and discards any remaining + /// results. If riid is IID_IMultipleResults and the provider does not support multiple results, ICommand::Execute + /// returns E_NOINTERFACE. + /// + /// + /// + /// + /// [in/out] A pointer to a DBPARAMS structure that specifies the values for one or more parameters. In text commands that use + /// parameters, if no value is specified for a parameter through pParams, an error occurs. + /// + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// pData + /// + /// Pointer to a buffer from which the provider retrieves input parameter data and to which the provider returns output parameter + /// data, according to the bindings specified by hAccessor. This pointer must be a valid pointer to a contiguous block of + /// consumer-owned memory for the input and output parameter values. For more information, see Getting Data and Setting Data. When + /// output parameter data is available to the consumer depends on the DBPROP_OUTPUTPARAMETERAVAILABILITY property. + /// + /// + /// + /// cParamSets + /// + /// The number of sets of parameters in * pData. If cParamSets is greater than one, the bindings described by + /// hAccessor define the offsets within * pData for each set of parameters and cbRowSize (as specified in + /// IAccessor::CreateAccessor) defines a single fixed offset between each of those values and the corresponding values for the + /// next set of parameters. Sets of multiple parameters ( cParamSets is greater than one) can be specified only if + /// DBPROP_MULTIPLEPARAMSETS is VARIANT_TRUE and the command does not return any rowsets. + /// + /// + /// + /// hAccessor + /// + /// Handle of the accessor to use. If hAccessor is the handle of a null accessor ( cBindings in + /// IAccessor::CreateAccessor was 0), ICommand::Execute does not retrieve or return any parameter values. + /// + /// + /// + /// + /// If the provider is able to determine the number of parameters in the command and the command text does not include parameters, + /// the provider ignores this argument. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the count of rows affected by a command that updates, deletes, or inserts rows. If + /// cParamSets is greater than one, *pcRowsAffected is the total number of rows affected by all of the sets of parameters specified + /// in the execution. If the number of affected rows is not available, *pcRowsAffected is set to DB_COUNTUNAVAILABLE on output. If + /// riid is IID_IMultipleResults, the value returned in *pcRowsAffected is either DB_COUNTUNAVAILABLE or the total number of + /// rows affected by the entire command; to retrieve individual row counts, the consumer calls IMultipleResults::GetResult. If + /// the command does not update, delete, or insert rows, *pcRowsAffected is undefined on output. If pcRowsAffected is a null pointer, + /// no count of rows is returned. + /// + /// + /// pcRowsAffected is undefined if ICommand::Execute returns DB_S_ASYNCHRONOUS. For asynchronously executed commands, the + /// consumer should call IDBAsynchStatus::GetStatus to obtain the number of rows affected in pulProgress. + /// + /// + /// + /// + /// [in/out] A pointer to the memory in which to return the rowset's pointer. If ppRowset is a null pointer, no rowset is created. + /// However, if the DBPROP_OUTPUTSTREAM property is set and the result of ICommand::Execute is a stream object, a null pointer + /// is an acceptable value. + /// + /// + /// If ppRowset is not a null pointer and an interface on a stream object was requested, the provider returns to *ppRowset the + /// interface pointer set in the DBPROP_OUTPUTSTREAM property. The consumer must release the interface pointer in *ppRowset when it + /// is no longer needed. + /// + /// If *ppRowset is a null pointer, the provider did not write any results to the stream specified in DBPROP_OUTPUTSTREAM. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK; the status of all + /// input parameters bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL; and the status of all output parameters + /// bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED ? or is unknown because the parameter + /// value has not been returned yet. + /// + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to + /// poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any + /// other interfaces may fail, and the full set of interfaces may not be available on the object until asynchronous initialization of + /// the rowset has completed. DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED This can be returned for any of the following reasons: + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// DB_S_ERRORSOCCURRED should be returned before DB_S_NOTSINGLETON because the status values can be checked, and providers are not + /// required to return DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// + /// DB_S_NOTSINGLETON The provider supports returning row objects on ICommand::Execute, and the consumer requested a row + /// object but the result was not a singleton. A row object of the first row of the rowset is returned. Returning this result may be + /// expensive, so providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes + /// precedence over DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// + /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been + /// returned. Execution cannot be resumed. + /// + /// + /// Multiple sets of parameters were specified, and one or more (but not all) of the parameters have been processed prior to the + /// command being canceled by ICommand::Cancel or IDBAsynchStatus::Abort. + /// + /// + /// 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 riid was not IID_NULL, and ppRowset was a null pointer. Any streams used to pass input parameters are not released. + /// + /// + /// The parameter information was invalid. Parameter information may be invalid for any of the following reasons. In all cases, any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_IMultipleResults, and the provider did not support multiple results objects. + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED Execution has been aborted because a resource limit has been reached. For example, a query timed out. No + /// results have been returned. + /// + /// + /// + /// + /// + /// + /// DB_E_BADACCESSORHANDLE pParams was not ignored, and hAccessor in the DBPARAMS structure pointed to by pParams was invalid. Any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// + /// DB_E_BADACCESSORTYPE hAccessor in the DBPARAMS structure pointed to by pParams was not the handle of a parameter accessor. Any + /// streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// DB_E_CANCELED The command was canceled by a call to ICommand::Cancel on another thread. No records were affected. + /// + /// + /// + /// + /// + /// DB_E_CANTCONVERTVALUE A literal value in the command text could not be converted to the type of the associated column for reasons + /// other than data overflow. + /// + /// + /// + /// + /// + /// DB_E_DATAOVERFLOW A literal value in the command text overflowed the type specified by the associated column. + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details + /// about the errors. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The method failed due to one or more nonvalid input parameter values. To determine which input parameter + /// values were not valid, 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.) If any streams were used to pass input parameters, only those with the + /// status value equal to DBSTATUS_S_OK on input are released; otherwise, no attempt is made to release the stream. If the consumer + /// provides storage objects for additional bound parameters that are not used by the current command, it is a consumer programming + /// error and the provider does not attempt to release these parameters. + /// + /// + /// The command was not executed, and no rowset was returned because one or more properties ? for which the dwOptions element of the + /// DBPROP structure was DBPROPOPTIONS_REQUIRED ? were not set. + /// + /// Multiple parameter sets were passed with a command that returns a rowset. (Some providers might not return this error.) + /// + /// + /// + /// + /// DB_E_INTEGRITYVIOLATION A literal value in the command text violated the integrity constraints for the column. + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. Any streams used to pass input parameters are not released. + /// + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. Any streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was currently set on the command object. Any streams used to pass input parameters are not released. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specific table or view does not exist in the data store. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider supports row objects, a row was requested via riid or DBPROP_IRow, and no rows satisfied the selection + /// criteria of the command. + /// + /// + /// + /// + /// + /// DB_E_PARAMNOTOPTIONAL A value was not supplied for a required parameter. + /// The command text used parameters and pParams was a null pointer. + /// + /// + /// + /// + /// + /// DB_E_PARAMUNAVAILABLE Provider cannot derive parameter information, and ICommandWithParameters::SetParameterInfo has not + /// been called. + /// + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to execute the command. For example, a rowset-returning + /// command specified a column for which the consumer does not have read permission, or an update command specified a column for + /// which the consumer does not have write permission. + /// + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. Any streams used to pass input parameters are not released. + /// + /// + /// If a session is enlisted in a global transaction and a command requires the creation of an additional connection, the provider + /// should return DB_E_OBJECTOPEN. Providers written prior to OLE DB 2.6 may return E_FAIL. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718095(v=vs.85) HRESULT Execute ( IUnknown *pUnkOuter, + // REFIID riid, DBPARAMS *pParams, DBROWCOUNT *pcRowsAffected, IUnknown **ppRowset); + [PreserveSig] + new HRESULT Execute([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [In, Out, Optional] DBPARAMS? pParams, + out DBROWCOUNT pcRowsAffected, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Returns an interface pointer to the session that created the command. + /// [in] The IID of the interface on which to return a pointer. + /// + /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the + /// command, it sets *ppSession to a null pointer. If ICommand::GetDBSession fails, it must attempt to set *ppSession to a + /// null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// S_FALSE The provider did not have an object that created the command. Therefore, it set *ppSession to a null pointer. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppSession was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The session did not support the interface specified in riid. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719622(v=vs.85) HRESULT GetDBSession ( REFIID riid, IUnknown **ppSession); + [PreserveSig] + new HRESULT GetDBSession(in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppSession); + + /// Returns the text command set by the last call to ICommandText::SetCommandText. + /// + /// + /// [in/out] A pointer to memory containing a GUID that specifies the syntax and general rules for parsing the command text ? that + /// is, the dialect that will be used by the provider to interpret the statement. This is usually the dialect specified in ICommandText::SetCommandText. + /// + /// + /// However, if DBGUID_DEFAULT is specified in SetCommandText, the provider returns the particular dialect that it will use to + /// interpret the statement. If the provider must choose between multiple dialects at execution time for a command that has been set + /// with DBGUID_DEFAULT or if the provider is returning some provider-specific syntax that may be different from the command set in + /// ICommandText::SetCommandText, it returns DBGUID_DEFAULT. Providers can define GUIDs for their own dialects. + /// + /// If pguidDialect is a null pointer on input, the provider does not return the dialect. + /// If ICommandText::GetCommandText returns an error, *pguidDialect is set to DB_NULLGUID. + /// For more information about dialects, see Using Commands. + /// + /// + /// [out] A pointer to memory in which to return the command text. The command object allocates memory for the command text and + /// returns the address to this memory. The consumer releases this memory with IMalloc::Free when it no longer needs the text. + /// If ICommandText::GetCommandText returns an error, *ppwszCommand is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_DIALECTIGNORED The method succeeded, but the input value of pguidDialect was ignored. The text is returned in the dialect + /// specified in ICommandText::SetCommandText or in the dialect that makes the most sense to the provider. The value returned + /// in *pguidDialect represents that dialect. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppwszCommand was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the command text. + /// + /// + /// + /// + /// DB_E_CANTTRANSLATE The last command was set using ICommandStream::SetCommandStream, not ICommandText::SetCommandText. + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was currently set on the command object. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709825(v=vs.85) HRESULT GetCommandText ( GUID *pguidDialect, + // LPOLESTR *ppwszCommand); + [PreserveSig] + HRESULT GetCommandText([In, Out, Optional] ref Guid pguidDialect, out string ppwszCommand); + + /// Sets the command text, replacing the existing command text. + /// + /// [in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. For a complete + /// description of dialects, see GetCommandText. + /// + /// + /// [in] A pointer to the text of the command. + /// + /// If *pwszCommand is an empty string ("") or pwszCommand is a null pointer, the current command text (and command stream object, if + /// it exists) is cleared and the command is put in an initial state. Any properties that have been set on the command are + /// unaffected; that is, they retain their current values. Methods that require a command, such as ICommand::Execute, + /// ICommandPrepare::Prepare, or IColumnsInfo::GetColumnInfo, will return DB_E_NOCOMMAND until a new command text is set. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// DB_E_DIALECTNOTSUPPORTED The provider did not support the dialect specified in rguidDialect. + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset was open on the command. + /// + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and the command text specified a FROM SCOPE= + /// clause with an unsafe URL. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709757(v=vs.85) HRESULT SetCommandText ( REFGUID + // rguidDialect, LPCOLESTR pwszCommand); + [PreserveSig] + HRESULT SetCommandText(in Guid rguidDialect, [In, Optional, MarshalAs(UnmanagedType.LPWStr)] string? pwszCommand); + } + + /// + /// + /// Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) + /// + /// Download OLE DB driver + /// + /// Improvements in the database engine beginning with SQL Server 2012 (11.x) allow ICommandWithParameters::GetParameterInfo to obtain + /// more accurate descriptions of the expected results. These more accurate results may differ from the values returned by + /// CommandWithParameters::GetParameterInfo in previous versions of SQL Server. For more information, see Metadata Discovery. + /// + /// + /// Also beginning in SQL Server 2012 (11.x), when calling ICommandWithParameters::SetParameterInfo, the value passed to the pwszName + /// parameter must be a valid identifier. For more information, see Database Identifiers. + /// + /// + // https://learn.microsoft.com/en-us/sql/connect/oledb/ole-db-interfaces/icommandwithparameters?view=sql-server-ver16 + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a64-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICommandWithParameters + { + /// Gets a list of the parameters for the command, the parameter names, and the parameter types. + /// + /// [out] + /// + /// A pointer to memory in which to return the number of parameters in the command. If an error occurs, *pcParams is set to zero. + /// + /// + /// + /// [out] + /// + /// A pointer to memory in which to return an array of parameter information structures. The command allocates memory for the array, + /// as well as the strings, and returns the address to this memory. The consumer releases the array memory with IMalloc::Free + /// when it no longer needs the parameter information. If *pcParams is zero on output or an error occurs, the provider does not + /// allocate any memory and ensures that *prgParamInfo is a null pointer on output. Parameters are returned in ascending order + /// according to the iOrdinal element of the PARAMINFO structure. + /// + /// Here is the DBPARAMINFO structure: + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// dwFlags + /// A bitmask describing parameter characteristics; these values have the following meaning: + /// + /// + /// iOrdinal + /// + /// The ordinal of the parameter. Parameters are numbered from left to right as they appear in the command, with the first parameter + /// in the command having an iOrdinal value of 1. + /// + /// + /// + /// pwszName + /// + /// The name of the parameter; it is a null pointer if there is no name. Names are normal names. The colon prefix (where used within + /// SQL text) is stripped. + /// + /// + /// + /// pTypeInfo + /// ITypeInfo describes the type, if pTypeInfo is not a null pointer. + /// + /// + /// ulParamSize + /// + /// The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of + /// the data type. For parameters that use a variable-length data type, this is one of the following: For data types that do not have + /// a length, this is set to ~0 (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// wType + /// + /// The indicator of the parameter's data type, or a type from which the data can be converted for the parameter if the provider + /// cannot determine the exact data type of the parameter. + /// + /// + /// + /// bPrecision + /// + /// If wType is a numeric type or DBTYPE_DBTIMESTAMP, bPrecision is the maximum number of digits, expressed in base 10. + /// Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// bScale + /// + /// If wType is a numeric type with a fixed scale or if wType is DBTYPE_DBTIMESTAMP, bScale is the number of + /// digits to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, this + /// is ~0 (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// + /// + /// [out] + /// + /// A pointer to memory in which to store all string values (names used within the *pwszName element of the DBPARAMINFO structures) + /// with a single, globally allocated buffer. Specifying a null pointer for ppNamesBuffer suspends the return of parameter names. The + /// command allocates memory for the buffer and returns the address to this memory. The consumer releases the memory with + /// IMalloc::Free when it no longer needs the parameter information. If *pcParams is zero on output or an error occurs, the + /// provider does not allocate any memory and ensures that *ppNamesBuffer is a null pointer on output. (The following two sentences + /// have been joined to this Definition paragraph to pass conversion) Each of the individual string values stored in this buffer is + /// terminated by a null-termination character. Therefore, the buffer may contain one or more strings, each with its own + /// null-termination character, and may contain embedded null termination characters. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcParams or prgParamInfo was a null pointer. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the parameter data array or parameter names. + /// + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND The provider can derive parameter information. However, no command text was currently set on the command object + /// and no parameter information had been specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The provider can derive parameter information, and it supports command preparation. However, the command was in + /// an unprepared state and no parameter information was specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + /// + /// DB_E_PARAMUNAVAILABLE The provider cannot derive parameter information from the command, and + /// ICommandWithParameters::SetParameterInfo has not been called. + /// + /// + /// + /// + /// Comments + /// This method makes no logical change to the state of the object. + /// + /// If ICommandWithParameters::SetParameterInfo has not been called for any parameters or + /// ICommandWithParameters::SetParameterInfo has been called with cParams equal to zero, + /// ICommandWithParameters::GetParameterInfo returns information about the parameters only if the provider can derive + /// parameter information. If the provider cannot derive parameter information, ICommandWithParameters::GetParameterInfo + /// returns DB_E_PARAMUNAVAILABLE. + /// + /// + /// If ICommandWithParameters::SetParameterInfo has been called for at least one parameter, + /// ICommandWithParameters::GetParameterInfo returns the parameter information only for those parameters for which + /// SetParameterInfo has been called. The provider does not return a warning in this case because it often cannot determine + /// the number of parameters and therefore cannot determine whether it has returned information for all parameters. It is + /// provider-specific whether or not the provider also returns derived information about the parameters for which + /// ICommandWithParameters::SetParameterInfo was not called. For performance reasons, even providers that can derive this + /// additional parameter information will usually return only the information that was specified when + /// ICommandWithParameters::SetParameterInfo was called. + /// + /// + /// Note + /// + /// Providers are permitted to overwrite parameter information set by the consumer with the actual parameter information for the + /// statement or stored procedure. However, they are not encouraged to do so if such validation requires a round-trip to the server. + /// Consumers must not rely on providers to validate parameter information in this manner. + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714917(v=vs.85) HRESULT GetParameterInfo ( DB_UPARAMS + // *pcParams, DBPARAMINFO **prgParamInfo, OLECHAR **ppNamesBuffer); + [PreserveSig] + HRESULT GetParameterInfo(out DB_UPARAMS pcParams, out SafeIMallocHandle prgParamInfo, out SafeIMallocHandle ppNamesBuffer); + + /// Returns an array of parameter ordinals when given named parameters. + /// + /// [in] The number of parameter names to map. If cParamNames is zero, ICommandWithParameters::MapParameterNames does nothing + /// and returns S_OK. + /// + /// + /// [in] An array of parameter names of which to determine the parameter ordinals. If a parameter name is not found, the + /// corresponding element of rgParamOrdinals is set to zero and the method returns DB_S_ERRORSOCCURRED. + /// + /// + /// [out] An array of cParamNames ordinals of the parameters identified by the elements of rgParamNames. 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 parameter ordinals in the array. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. Each element of rgParamOrdinals is set to a nonzero value. + /// + /// cParamNames was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cParamNames was zero and + /// either or both rgParamNames and rgParamOrdinals was a null pointer. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An element of rgParamNames was invalid. The corresponding element of rgParamOrdinals is set to zero. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cParamNames was not zero, and rgParamNames or rgParamOrdinals was a null pointer. + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All elements of rgParamNames were invalid. All elements of rgParamOrdinals are set to zero. + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND No command text was currently set on the command object, and no parameter information had been specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The provider can derive parameter information and supports command preparation. However, the command was in an + /// unprepared state and no parameter information had been specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725394(v=vs.85) HRESULT MapParameterNames ( DB_UPARAMS + // cParamNames, const OLECHAR *rgParamNames[], DB_LPARAMS rgParamOrdinals[]); + [PreserveSig] + HRESULT MapParameterNames(DB_UPARAMS cParamNames, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgParamNames, + [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DB_LPARAMS[] rgParamOrdinals); + + /// Specifies the native data type of each parameter. + /// + /// [in] The number of parameters for which to set type information. If cParams is zero, the type information for all parameters is + /// discarded and rgParamOrdinals and rgParamBindInfo are ignored. + /// + /// + /// [in] An array of cParams ordinals. These are the ordinals of the parameters for which to set type information. Type information + /// for parameters whose ordinals are not specified is not affected. + /// + /// + /// + /// [in] An array of cParams DBPARAMBINDINFO structures. If rgParamBindInfo is a null pointer, the type information for the + /// parameters specified by the ordinals in rgParamOrdinals is discarded. + /// + /// The DBPARAMBINDINFO structure is: + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// pwszDataSourceType + /// + /// A pointer to the provider-specific name of the parameter's data type or a standard data type name. This name is not returned by + /// ICommandWithParameters::GetParameterInfo; instead, the provider maps the data type specified by this name to an OLE DB + /// type indicator and returns that type indicator. For a list of standard data type names, see "Comments" below. If + /// pwszDataSourceType is null, the provider attempts a default conversion from the data type specified in the binding for the + /// parameter or returns E_INVALIDARG if it cannot perform default parameter conversions. + /// + /// + /// + /// pwszName + /// + /// The name of the parameter. This is a null pointer if the parameter does not have a name. The consumer must specify a name for all + /// or none of the parameters set at any time. If the provider does not support named parameters, this argument is ignored and the + /// provider is not required to verify that all or none of the parameters are named. + /// + /// + /// + /// ulParamSize + /// + /// The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of + /// the data type. For parameters that use a variable-length data type, this is one of the following: For data types that do not have + /// a length, this is set to ~0 (bitwise, the value is not 0; all bits are set to 1). This argument is ignored if + /// pwszDataSourceType is null. + /// + /// + /// + /// dwFlags + /// See the dwFlags element of the DBPARAMINFO structure in GetParameterInfo. + /// + /// + /// bPrecision + /// + /// If pwszDataSourceType is DBTYPE_DBTIMESTAMP or a numeric type, bPrecision is the maximum number of digits, + /// expressed in base 10. Otherwise, it is ignored. This argument is ignored if pwszDataSourceType is null. + /// + /// + /// + /// bScale + /// + /// If pwszDataSourceType is a numeric type with a fixed scale or if wType is DBTYPE_DBTIMESTAMP, bScale is the + /// number of digits to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. + /// Otherwise, it is ignored. This argument is ignored if pwszDataSourceType is null. + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_TYPEINFOOVERRIDDEN The provider was capable of deriving the parameter type information, and + /// ICommandWithParameters::SetParameterInfo was called. The parameter type information specified in + /// ICommandWithParameters::SetParameterInfo was used. + /// + /// ICommandWithParameters::SetParameterInfo replaced parameter type information specified in a previous call to SetParameterInfo. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cParams was not zero, and rgParamOrdinals was a null pointer. + /// An element of rgParamOrdinals was zero. + /// + /// In an element of rgParamBindInfo, the pwszDataSourceType element was a null pointer, and the provider does not support default + /// parameter conversions. + /// + /// In an element of rgParamBindInfo, the dwFlags element was invalid. + /// + /// + /// + /// + /// DB_E_BADORDINAL An element of rgParamOrdinals was invalid. + /// + /// + /// + /// + /// + /// DB_E_BADPARAMETERNAME In an element of rgParamBindInfo, the pwszName element specified an invalid parameter name. The provider + /// does not check whether the name was correct for the specified parameter, just whether it was a valid parameter name. + /// + /// In one or more (but not all) elements of rgParamBindInfo, pwszName was null. + /// + /// In one or more elements of rgParamBindInfo, pwszName was null and one or more parameters previously set and not overridden were + /// specified with a non-null pwszName. + /// + /// + /// In one or more elements of rgParamBindInfo, pwszName was non-null and one or more parameters previously set and not overridden + /// were specified with a null pwszName. + /// + /// + /// + /// + /// + /// + /// DB_E_BADTYPENAME In an element of rgParamBindInfo, the pwszDataSourceType element specified an invalid data type name. The + /// provider does not check whether the data type was correct for the specified parameter, just whether it was a data type name + /// supported by the provider. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset was open on the command. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725393(v=vs.85) HRESULT SetParameterInfo ( DB_UPARAMS + // cParams, const DB_UPARAMS rgParamOrdinals[], const DBPARAMBINDINFO rgParamBindInfo[]); + [PreserveSig] + HRESULT SetParameterInfo(DB_UPARAMS cParams, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DB_UPARAMS[]? rgParamOrdinals, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBPARAMBINDINFO[]? rgParamBindInfo); + } + + /// + /// This interface is mandatory on commands, rowsets, index rowsets, and rows. + /// + /// This interface contains a single method that gives information about the availability of type conversions on a command, a rowset, or + /// a row. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715926(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a88-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IConvertType + { + /// Gives information about the availability of type conversions on a command, a rowset, or a row. + /// [in] The source type of the conversion. + /// [in] The target type of the conversion. + /// + /// + /// [in] Whether IConvertType::CanConvert is to determine if the conversion is supported on the rowset or on the command. + /// These flags have the following meaning: + /// + /// + /// + /// Value + /// Description + /// + /// + /// DBCONVERTFLAGS_COLUMN + /// + /// IConvertType::CanConvert is to determine whether the conversion is supported when setting, getting, finding, filtering, or + /// seeking on columns of the rowset or row. This flag is mutually exclusive with DBCONVERTFLAGS_PARAMETER. + /// + /// + /// + /// DBCONVERTFLAGS_ISFIXEDLENGTH + /// + /// IConvertType::CanConvert is to determine whether a fixed-length value of the DBTYPE specified in the dwFromType can + /// be converted to the DBTYPE specified in wToType. This flag can coexist with either DBCONVERTFLAGS_COLUMN or + /// DBCONVERTFLAGS_PARAMETER. This flag is supported only by OLE DB version 2.0 or later providers. + /// + /// + /// + /// DBCONVERTFLAGS_ISLONG + /// + /// IConvertType::CanConvert is to determine whether the long version of the DBTYPE specified in the dwFromType can be + /// converted to the DBTYPE specified in wToType. This flag is valid only when used in conjunction with a variable-length + /// DBTYPE. This flag can coexist with either DBCONVERTFLAGS_COLUMN or DBCONVERTFLAGS_PARAMETER. This flag is supported only by OLE + /// DB version 2.0 or later providers. + /// + /// + /// + /// DBCONVERTFLAGS_PARAMETER + /// + /// IConvertType::CanConvert is to determine whether the conversion is supported on the parameters of the command. + /// + /// + /// + /// DBCONVERTFLAGS_FROMVARIANT + /// + /// The DBTYPE specified in the wFromType represents a type within a VARIANT. IConvertType::CanConvert returns whether + /// the conversion from a VARIANT of that type to the type specified in wToType is allowed. For providers that support + /// PROPVARIANT, this applies to conversions from PROPVARIANT as well. + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The requested conversion is available. + /// + /// + /// + /// + /// S_FALSE The requested conversion is not available. + /// wFromType or wToType was not a valid type for the provider, and the provider was a version 2.0 or later provider. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// + /// E_INVALIDARG The provider was an OLE DB 1.x provider, and wFromType or wToType was not a valid type indicator for OLE DB 1.x. + /// + /// + /// + /// + /// + /// DB_E_BADCONVERTFLAG dwConvert flags was invalid. + /// + /// The method was called on a command, and its flags inquired about a conversion on a rowset but the property + /// DBPROP_ROWSETCONVERSIONSONCOMMAND was VARIANT_FALSE. + /// + /// The DBCONVERTFLAG_PARAMETER bit was set, and IConvertType::CanConvert was called on a rowset or row. + /// + /// The DBCONVERTFLAGS_PARAMETER bit was set, and IConvertType::CanConvert was called on a command (whether from a provider or + /// not) that does not support parameters. + /// + /// DBCONVERTFLAGS_ISLONG was specified, and the DBTYPE specified in dwFromType was not a variable-length DBTYPE. + /// DBCONVERTFLAGS_ISLONG was specified, and the provider was an OLE DB 1.x provider. + /// DBCONVERTFLAGS_ISFIXEDLENGTH was specified, and the provider was an OLE DB 1.x provider. + /// DBCONVERTFLAGS_COLUMN and DBCONVERTFLAGS_PARAMETER were both specified. (These two flags are mutually exclusive.) + /// + /// + /// + /// + /// DB_E_BADTYPE DBCONVERTFLAGS_FROMVARIANT was specified, and the type specified in wFromType was not a VARIANT type. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711224(v=vs.85) HRESULT CanConvert ( DBTYPE wFromType, + // DBTYPE wToType, DBCONVERTFLAGS dwConvertFlags); + [PreserveSig] + HRESULT CanConvert(DBTYPE wFromType, DBTYPE wToType, DBCONVERTFLAGS dwConvertFlags); + } + + /// ICreateRow creates and binds to an object named by a URL. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716832(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733ab2-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ICreateRow + { + /// Creates and binds to an object named by a URL and returns the requested interface pointer. + /// + /// [in] If the returned object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, + /// it is a null pointer. + /// + /// + /// [in] The canonical URL naming the object to be created. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this string defines the + /// path to the new object and the provider will generate the URL suffix. + /// + /// + /// + /// [in] Bitmask of bind flags that control how the object is to be bound. For more information, see the dwBindURLFlags value table + /// in the reference entry for IBindResource::Bind. + /// + /// + /// Note + /// + /// Creating a row requires DBBINDURLFLAG_WRITE be set. This is independent of whether a row, rowset, or stream view of the resource + /// is requested. + /// + /// + /// + /// The flag values listed in the following table are also available on ICreateRow::CreateRow, in addition to the bind flags + /// defined in IBindResource::Bind. + /// + /// + /// + /// Flags + /// Meaning + /// + /// + /// DBBINDURLFLAG_COLLECTION + /// Creates the object as a collection. + /// + /// + /// DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT + /// Creates the object as a structured document. + /// + /// + /// DBBINDURLFLAG_OPENIFEXISTS + /// + /// If the resource exists and is not a collection, it is opened and S_OK is returned. If it exists and is a collection, + /// DB_E_RESOURCEEXISTS is returned. If the resource does not exist, it is created. This flag may not be used with DBBINDURLFLAG_OVERWRITE. + /// + /// + /// + /// DBBINDURLFLAG_OVERWRITE + /// Deletes and re-creates a named object if it exists. This flag may not be used with DBBINDURLFLAG_OPENIFEXISTS. + /// + /// + /// DBBINDURLFLAG_COLLECTION | DBBINDURLFLAG_OPENIFEXISTS + /// + /// If the resource is not a collection, DB_E_NOTCOLLECTION is returned. If the resource exists and is a collection, it is opened and + /// S_OK is returned. If the resource does not exist, it is created. + /// + /// + /// + /// + /// Not all bind flags may be used with all object types (as specified in the rguid parameter). The following table describes the + /// restrictions. If a client does not adhere to these restrictions, the bind will fail with E_INVALIDARG. + /// + /// + /// + /// Object type + /// Restrictions + /// + /// + /// DBGUID_ROW + /// All flags are allowed. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. + /// + /// + /// DBGUID_ROWSET + /// + /// DBBINDURLFLAG_COLLECTION must be specified. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In + /// addition, the following flags are disallowed: + /// + /// + /// + /// DBGUID_STREAM + /// + /// DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In addition, the following flags are disallowed: + /// + /// + /// + /// + /// + /// + /// [in] A pointer to a GUID indicating the type of OLE DB object to be returned. The GUID must be set to one of the following values: + /// + /// + /// + /// + /// DBGUID_ROW + /// + /// + /// + /// + /// DBGUID_ROWSET + /// + /// + /// + /// + /// DBGUID_STREAM + /// + /// + /// + /// + /// Note + /// DBGUID_ROWSET can be requested only if the row represents a collection (that is, dwBindURLFlags set to DBBINDURLFLAG_COLLECTION). + /// + /// + /// [in] Interface ID of the interface pointer to be returned. + /// + /// [in] Optional pointer to the caller's IAuthenticate i nterface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// + /// [in/out] A pointer to a DBIMPLICITSESSION structure used to request and return aggregation information for the implicit session + /// object. The DBIMPLICITSESSION structure is defined in the reference entry for IBindResource::Bind. If + /// ICreateRow::CreateRow fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL. + /// + /// + /// Note + /// + /// ICreateRow::CreateRow uses pImplSession only when implemented on a binder object and binding to a row, rowset, or stream + /// object (rguid is DBGUID_ROW, DBGUID_ROWSET, or DBGUID_STREAM). If implemented on any other object (for example, a session or row + /// object), the provider ignores pImplSession because the existing object already has a session context. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return a bitmask that describes warning status for requested bind flags. If pdwBindStatus + /// is a null pointer, no status is returned. The bind status values are listed in the table for pdwBindStatus for + /// IBindResource::Bind. This parameter should be set to NULL if an error code is returned. + /// + /// + /// [out] A pointer to memory in which to return a string containing a provider-generated canonical URL that names the created row. + /// If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, callers are required to pass this pointer. If DBPROP_GENERATEURL is + /// DBPROPVAL_GU_NOTSUPPORTED and the caller passes a null value, the provider does not return the absolute URL of the created row. + /// If the caller passes this pointer, the provider must return the absolute URL of the created row. The provider allocates the + /// memory for this string. The consumer should free the memory with IMalloc::Free. If ICreateRow::CreateRow fails and + /// ppwszNewURL is not a null pointer, *ppwszNewURL is set to NULL. + /// + /// + /// [out] A pointer to memory in which to return an interface pointer on the requested object. If ICreateRow::CreateRow fails, + /// *ppUnk is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded, the object named by the URL was created and bound, and the requested interface pointer was returned. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL or ppUnk was a null pointer. + /// rguid was DBGUID_ROWSET, but the DBBINDURLFLAG_COLLECTION bit of dwBindURLFlags was not set. + /// pImplSession was not a null pointer, and pImplSession->piid was a null pointer. + /// + /// dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the dwBindURLFlags value table in the reference entry for + /// IBindResource::Bind but did not contain the flag to be modified. + /// + /// dwBindURLFlags contained both DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE. + /// The provider does not support one or more values of dwBindURLFlags. + /// + /// One of more of the bind flags in dwBindURLFlags are either not supported by the provider or disallowed for the object type + /// denoted by rguid. For flags allowed for each object type, see the table in the reference entry for IBindResource::Bind. + /// + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of an object. The consumer can call + /// IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until + /// asynchronous processing is complete, the object is not populated. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The bind succeeded, but some bind flags or properties were not satisfied. The consumer should examine the + /// bind status returned in the parameter pdwBindStatus of IBindResource::Bind. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED IDBProperties::SetProperties is invoked on the root binder object prior to calling + /// ICreateRow::CreateRow method, with unsupported properties that have the dwoptions parameter set to DBPROPOPTIONS_REQUIRED. + /// + /// + /// + /// + /// + /// DB_E_OBJECTMISMATCH The object named by rguid does not represent the resource named by pwszURL. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support this operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCELOCKED One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by + /// this URL. IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the + /// names of the users who have the object locked. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCENOTSUPPORTED The consumer attempted to create a type of row not supported by the provider. For example, + /// DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT was set but the provider does not support structured documents. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCEOUTOFSCOPE ICreateRow is implemented on a session or row object, and the caller tried to bind to an object + /// that is not within the scope of this session or row object, respectively. + /// + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller's authentication context does not permit access to the object. + /// IErrorInfo::GetDescription returns the default error string. + /// + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and pwszURL specified an unsafe URL. + /// + /// + /// + /// + /// DB_E_READONLY The caller requested write access to a read-only object. + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous binding. + /// + /// + /// + /// + /// DB_E_CANNOTCONNECT The provider could not connect to the server for this object. + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the object being created does not support aggregation. + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and pImplSession->piid did not point + /// to IID_IUnknown. + /// + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and the object being created does not + /// support aggregation. + /// + /// + /// + /// + /// + /// + /// DB_E_OUTOFSPACE The provider was unable to create an object at this URL using ICreateRow::CreateRow because the server was + /// out of physical storage. + /// + /// + /// + /// + /// + /// DB_E_NOTCOLLECTION The provider was unable to create an object with the specified URL because the parent URL is not a collection. + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider was unable to create an object with the specified URL because the parent URL does not exist. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid. + /// + /// + /// + /// + /// + /// DB_E_TIMEOUT The attempt to bind to the object timed out. + /// + /// + /// + /// + /// + /// DB_E_RESOURCEEXISTS The provider was unable to create an object at this URL because an object named by this URL already exists + /// and either the caller did not specify OPENIFEXISTS or OVERWRITE or the provider does not support this behavior on object creation. + /// + /// + /// + /// + /// + /// REGDB_E_CLASSNOTREG The root binder was unable to instantiate the provider binder object. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE The object did not support the interface specified in riid, or riid was IID_NULL. + /// The provider does not allow the creation of resources via ICreateRow. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ICreateRow::CreateRow is implemented on a row object, 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/ms723937(v=vs.85) HRESULT CreateRow( IUnknown * pUnkOuter, + // LPCOLESTR pwszURL, DBBINDURLFLAG dwBindURLFlags, REFGUID rguid, REFIID riid, IAuthenticate * pAuthenticate, DBIMPLICITSESSION * + // pImplSession, DBBINDURLSTATUS * pdwBindStatus, LPOLESTR * ppwszNewURL, IUnknown ** ppUnk ); + [PreserveSig] + HRESULT CreateRow([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, MarshalAs(UnmanagedType.LPWStr)] string pwszURL, + DBBINDURLFLAG dwBindURLFlags, in Guid rguid, in Guid riid, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, + [In, Out, Optional] IntPtr pImplSession, out DBBINDURLSTATUS pdwBindStatus, out SafeIMallocHandle ppwszNewURL, + [Optional, MarshalAs(UnmanagedType.IUnknown)] out object? ppUnk); + } + + /// Creates and binds to an object named by a URL and returns the requested interface pointer. + /// The type of interface to return. + /// The instance. + /// + /// [in] The canonical URL naming the object to be created. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this string defines the path to + /// the new object and the provider will generate the URL suffix. + /// + /// + /// + /// [in] Bitmask of bind flags that control how the object is to be bound. For more information, see the dwBindURLFlags value table in + /// the reference entry for IBindResource::Bind. + /// + /// + /// Note + /// + /// Creating a row requires DBBINDURLFLAG_WRITE be set. This is independent of whether a row, rowset, or stream view of the resource is requested. + /// + /// + /// + /// The flag values listed in the following table are also available on ICreateRow::CreateRow, in addition to the bind flags + /// defined in IBindResource::Bind. + /// + /// + /// + /// Flags + /// Meaning + /// + /// + /// DBBINDURLFLAG_COLLECTION + /// Creates the object as a collection. + /// + /// + /// DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT + /// Creates the object as a structured document. + /// + /// + /// DBBINDURLFLAG_OPENIFEXISTS + /// + /// If the resource exists and is not a collection, it is opened and S_OK is returned. If it exists and is a collection, + /// DB_E_RESOURCEEXISTS is returned. If the resource does not exist, it is created. This flag may not be used with DBBINDURLFLAG_OVERWRITE. + /// + /// + /// + /// DBBINDURLFLAG_OVERWRITE + /// Deletes and re-creates a named object if it exists. This flag may not be used with DBBINDURLFLAG_OPENIFEXISTS. + /// + /// + /// DBBINDURLFLAG_COLLECTION | DBBINDURLFLAG_OPENIFEXISTS + /// + /// If the resource is not a collection, DB_E_NOTCOLLECTION is returned. If the resource exists and is a collection, it is opened and + /// S_OK is returned. If the resource does not exist, it is created. + /// + /// + /// + /// + /// Not all bind flags may be used with all object types (as specified in the rguid parameter). The following table describes the + /// restrictions. If a client does not adhere to these restrictions, the bind will fail with E_INVALIDARG. + /// + /// + /// + /// Object type + /// Restrictions + /// + /// + /// DBGUID_ROW + /// All flags are allowed. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. + /// + /// + /// DBGUID_ROWSET + /// + /// DBBINDURLFLAG_COLLECTION must be specified. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In + /// addition, the following flags are disallowed: + /// + /// + /// + /// DBGUID_STREAM + /// + /// DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In addition, the following flags are disallowed: + /// + /// + /// + /// + /// + /// + /// [in] A pointer to a GUID indicating the type of OLE DB object to be returned. The GUID must be set to one of the following values: + /// + /// + /// + /// + /// DBGUID_ROW + /// + /// + /// + /// + /// DBGUID_ROWSET + /// + /// + /// + /// + /// DBGUID_STREAM + /// + /// + /// + /// + /// Note + /// DBGUID_ROWSET can be requested only if the row represents a collection (that is, dwBindURLFlags set to DBBINDURLFLAG_COLLECTION). + /// + /// + /// + /// + /// [in/out] A pointer to a DBIMPLICITSESSION structure used to request and return aggregation information for the implicit session + /// object. The DBIMPLICITSESSION structure is defined in the reference entry for IBindResource::Bind. If ICreateRow::CreateRow + /// fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL. + /// + /// + /// Note + /// + /// ICreateRow::CreateRow uses pImplSession only when implemented on a binder object and binding to a row, rowset, or stream + /// object (rguid is DBGUID_ROW, DBGUID_ROWSET, or DBGUID_STREAM). If implemented on any other object (for example, a session or row + /// object), the provider ignores pImplSession because the existing object already has a session context. + /// + /// + /// + /// + /// [in] If the returned object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, it + /// is a null pointer. + /// + /// + /// [in] Optional pointer to the caller's IAuthenticate i nterface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// [out] A pointer to memory in which to return a bitmask that describes warning status for requested bind flags. If pdwBindStatus is a + /// null pointer, no status is returned. The bind status values are listed in the table for pdwBindStatus for IBindResource::Bind. This + /// parameter should be set to NULL if an error code is returned. + /// + /// + /// [out] A pointer to memory in which to return a string containing a provider-generated canonical URL that names the created row. If + /// DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, callers are required to pass this pointer. If DBPROP_GENERATEURL is + /// DBPROPVAL_GU_NOTSUPPORTED and the caller passes a null value, the provider does not return the absolute URL of the created row. If + /// the caller passes this pointer, the provider must return the absolute URL of the created row. The provider allocates the memory for + /// this string. The consumer should free the memory with IMalloc::Free. If ICreateRow::CreateRow fails and ppwszNewURL is + /// not a null pointer, *ppwszNewURL is set to NULL. + /// + /// + /// [out] A pointer to memory in which to return an interface pointer on the requested object. If ICreateRow::CreateRow fails, + /// *ppUnk is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded, the object named by the URL was created and bound, and the requested interface pointer was returned. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL or ppUnk was a null pointer. + /// rguid was DBGUID_ROWSET, but the DBBINDURLFLAG_COLLECTION bit of dwBindURLFlags was not set. + /// pImplSession was not a null pointer, and pImplSession->piid was a null pointer. + /// + /// dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the dwBindURLFlags value table in the reference entry for + /// IBindResource::Bind but did not contain the flag to be modified. + /// + /// dwBindURLFlags contained both DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE. + /// The provider does not support one or more values of dwBindURLFlags. + /// + /// One of more of the bind flags in dwBindURLFlags are either not supported by the provider or disallowed for the object type denoted by + /// rguid. For flags allowed for each object type, see the table in the reference entry for IBindResource::Bind. + /// + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of an object. The consumer can call + /// IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until asynchronous + /// processing is complete, the object is not populated. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The bind succeeded, but some bind flags or properties were not satisfied. The consumer should examine the bind + /// status returned in the parameter pdwBindStatus of IBindResource::Bind. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED IDBProperties::SetProperties is invoked on the root binder object prior to calling + /// ICreateRow::CreateRow method, with unsupported properties that have the dwoptions parameter set to DBPROPOPTIONS_REQUIRED. + /// + /// + /// + /// + /// + /// DB_E_OBJECTMISMATCH The object named by rguid does not represent the resource named by pwszURL. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support this operation, and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCELOCKED One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by + /// this URL. IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of + /// the users who have the object locked. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCENOTSUPPORTED The consumer attempted to create a type of row not supported by the provider. For example, + /// DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT was set but the provider does not support structured documents. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCEOUTOFSCOPE ICreateRow is implemented on a session or row object, and the caller tried to bind to an object that + /// is not within the scope of this session or row object, respectively. + /// + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller's authentication context does not permit access to the object. IErrorInfo::GetDescription + /// returns the default error string. + /// + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and pwszURL specified an unsafe URL. + /// + /// + /// + /// + /// DB_E_READONLY The caller requested write access to a read-only object. + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous binding. + /// + /// + /// + /// + /// DB_E_CANNOTCONNECT The provider could not connect to the server for this object. + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the object being created does not support aggregation. + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and pImplSession->piid did not point to IID_IUnknown. + /// + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and the object being created does not support aggregation. + /// + /// + /// + /// + /// + /// + /// DB_E_OUTOFSPACE The provider was unable to create an object at this URL using ICreateRow::CreateRow because the server was out + /// of physical storage. + /// + /// + /// + /// + /// + /// DB_E_NOTCOLLECTION The provider was unable to create an object with the specified URL because the parent URL is not a collection. + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider was unable to create an object with the specified URL because the parent URL does not exist. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid. + /// + /// + /// + /// + /// + /// DB_E_TIMEOUT The attempt to bind to the object timed out. + /// + /// + /// + /// + /// + /// DB_E_RESOURCEEXISTS The provider was unable to create an object at this URL because an object named by this URL already exists and + /// either the caller did not specify OPENIFEXISTS or OVERWRITE or the provider does not support this behavior on object creation. + /// + /// + /// + /// + /// + /// REGDB_E_CLASSNOTREG The root binder was unable to instantiate the provider binder object. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE The object did not support the interface specified in riid, or riid was IID_NULL. + /// The provider does not allow the creation of resources via ICreateRow. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ICreateRow::CreateRow is implemented on a row object, 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/ms723937(v=vs.85) HRESULT CreateRow( IUnknown * pUnkOuter, + // LPCOLESTR pwszURL, DBBINDURLFLAG dwBindURLFlags, REFGUID rguid, REFIID riid, IAuthenticate * pAuthenticate, DBIMPLICITSESSION * + // pImplSession, DBBINDURLSTATUS * pdwBindStatus, LPOLESTR * ppwszNewURL, IUnknown ** ppUnk ); + public static HRESULT CreateRow(this ICreateRow cr, [In, MarshalAs(UnmanagedType.LPWStr)] string pwszURL, + DBBINDURLFLAG dwBindURLFlags, in Guid rguid, [In, Out, Optional] DBIMPLICITSESSION? pImplSession, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, + out DBBINDURLSTATUS pdwBindStatus, out string? ppwszNewURL, + out T? ppUnk) where T : class + { + SafeCoTaskMemStruct pis = pImplSession; + var hr = cr.CreateRow(pUnkOuter, pwszURL, dwBindURLFlags, rguid, typeof(T).GUID, pAuthenticate, pis, out pdwBindStatus, out var p, out var pp); +#pragma warning disable IDE0059 // Unnecessary assignment of a value + pImplSession = pis; +#pragma warning restore IDE0059 // Unnecessary assignment of a value + ppwszNewURL = p?.ToString(); + ppUnk = pp as T; + return hr; + } + + /// Returns the bindings in an accessor. + /// The instance. + /// [in] The handle of the accessor for which to return the bindings. + /// + /// [out] A pointer to memory in which to return a bitmask that describes the properties of the accessor and how it is intended to be + /// used. For more information, see dwAccessorFlags in CreateAccessor. If this method fails, *pdwAccessorFlags is set to DBACCESSOR_INVALID. + /// + /// + /// [out] A pointer to memory in which to return an array of DBBINDING structures. One DBBINDING structure is returned for each binding + /// in the accessor. The provider allocates memory for these structures and any structures pointed to by elements of these structures; + /// for example, if pObject in a binding structure is not a null pointer, the provider allocates a DBOBJECT structure for return to the + /// consumer. The provider returns the address to the memory for these structures; the consumer releases the memory for these structures + /// with IMalloc::Free when it no longer needs the bindings. If *pcBindings is zero on output or the method fails, the provider + /// does not allocate any memory and ensures that *prgBindings is a null pointer on output. For information about bindings, see DBBINDING Structures. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721253(v=vs.85) HRESULT GetBindings ( HACCESSOR hAccessor, + // DBACCESSORFLAGS *pdwAccessorFlags, DBCOUNTITEM *pcBindings, DBBINDING **prgBindings); + public static void GetBindings(this IAccessor a, HACCESSOR hAccessor, out DBACCESSORFLAGS pdwAccessorFlags, out DBBINDING[] prgBindings) + { + a.GetBindings(hAccessor, out pdwAccessorFlags, out var c, out var p); + prgBindings = c == 0 ? [] : p.ToArray((int)c); + } + + /// Returns the column metadata needed by most consumers. + /// The instance. + /// + /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in the + /// rowset. 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 column information. If *pcColumns is 0 on output or terminates due to an error, + /// the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more information, see + /// "DBCOLUMNINFO Structures" in the Comments section. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) HRESULT GetColumnInfo ( DBORDINAL + // *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); + public static HRESULT GetColumnInfo(this IColumnsInfo ci, out DBCOLUMNINFO_MGD[] prgInfo) + { + var hr = ci.GetColumnInfo(out var c, out var p, out var pp); + prgInfo = c == 0 || hr.Failed ? [] : Array.ConvertAll(p.ToArray((int)c), u => (DBCOLUMNINFO_MGD)u); + //IMallocMemoryMethods.Instance.FreeMem(p); + //IMallocMemoryMethods.Instance.FreeMem(pp); + return hr; + } + + /// Gets a list of the parameters for the command, the parameter names, and the parameter types. + /// The instance. + /// + /// [out] + /// + /// A pointer to memory in which to return an array of parameter information structures. The command allocates memory for the array, as + /// well as the strings, and returns the address to this memory. The consumer releases the array memory with IMalloc::Free when it + /// no longer needs the parameter information. If *pcParams is zero on output or an error occurs, the provider does not allocate any + /// memory and ensures that *prgParamInfo is a null pointer on output. Parameters are returned in ascending order according to the + /// iOrdinal element of the PARAMINFO structure. + /// + /// Here is the DBPARAMINFO structure: + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// dwFlags + /// A bitmask describing parameter characteristics; these values have the following meaning: + /// + /// + /// iOrdinal + /// + /// The ordinal of the parameter. Parameters are numbered from left to right as they appear in the command, with the first parameter in + /// the command having an iOrdinal value of 1. + /// + /// + /// + /// pwszName + /// + /// The name of the parameter; it is a null pointer if there is no name. Names are normal names. The colon prefix (where used within SQL + /// text) is stripped. + /// + /// + /// + /// pTypeInfo + /// ITypeInfo describes the type, if pTypeInfo is not a null pointer. + /// + /// + /// ulParamSize + /// + /// The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of the + /// data type. For parameters that use a variable-length data type, this is one of the following: For data types that do not have a + /// length, this is set to ~0 (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// wType + /// + /// The indicator of the parameter's data type, or a type from which the data can be converted for the parameter if the provider cannot + /// determine the exact data type of the parameter. + /// + /// + /// + /// bPrecision + /// + /// If wType is a numeric type or DBTYPE_DBTIMESTAMP, bPrecision is the maximum number of digits, expressed in base 10. + /// Otherwise, this is ~0 (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// bScale + /// + /// If wType is a numeric type with a fixed scale or if wType is DBTYPE_DBTIMESTAMP, bScale is the number of digits + /// to the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, this is ~0 + /// (bitwise, the value is not 0; all bits are set to 1). + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcParams or prgParamInfo was a null pointer. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the parameter data array or parameter names. + /// + /// + /// + /// + /// + /// + /// DB_E_NOCOMMAND The provider can derive parameter information. However, no command text was currently set on the command object and no + /// parameter information had been specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTPREPARED The provider can derive parameter information, and it supports command preparation. However, the command was in an + /// unprepared state and no parameter information was specified with ICommandWithParameters::SetParameterInfo. + /// + /// + /// + /// + /// + /// + /// DB_E_PARAMUNAVAILABLE The provider cannot derive parameter information from the command, and + /// ICommandWithParameters::SetParameterInfo has not been called. + /// + /// + /// + /// + /// Comments + /// This method makes no logical change to the state of the object. + /// + /// If ICommandWithParameters::SetParameterInfo has not been called for any parameters or + /// ICommandWithParameters::SetParameterInfo has been called with cParams equal to zero, + /// ICommandWithParameters::GetParameterInfo returns information about the parameters only if the provider can derive parameter + /// information. If the provider cannot derive parameter information, ICommandWithParameters::GetParameterInfo returns DB_E_PARAMUNAVAILABLE. + /// + /// + /// If ICommandWithParameters::SetParameterInfo has been called for at least one parameter, + /// ICommandWithParameters::GetParameterInfo returns the parameter information only for those parameters for which + /// SetParameterInfo has been called. The provider does not return a warning in this case because it often cannot determine the + /// number of parameters and therefore cannot determine whether it has returned information for all parameters. It is provider-specific + /// whether or not the provider also returns derived information about the parameters for which + /// ICommandWithParameters::SetParameterInfo was not called. For performance reasons, even providers that can derive this + /// additional parameter information will usually return only the information that was specified when + /// ICommandWithParameters::SetParameterInfo was called. + /// + /// + /// Note + /// + /// Providers are permitted to overwrite parameter information set by the consumer with the actual parameter information for the + /// statement or stored procedure. However, they are not encouraged to do so if such validation requires a round-trip to the server. + /// Consumers must not rely on providers to validate parameter information in this manner. + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714917(v=vs.85) HRESULT GetParameterInfo ( DB_UPARAMS *pcParams, + // DBPARAMINFO **prgParamInfo, OLECHAR **ppNamesBuffer); + public static HRESULT GetParameterInfo(this ICommandWithParameters cwp, out DBPARAMINFO[] prgParamInfo) + { + var hr = cwp.GetParameterInfo(out var pcParams, out var p, out var names); + prgParamInfo = hr.Succeeded ? p.ToArray((int)pcParams) : []; + return hr; + } + + /// Returns the list of properties in the Rowset property group that are currently requested for the rowset. + /// The instance. + /// + /// + /// [in] An array of DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset property group. The + /// provider returns the values of the properties specified in these structures. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix C. + /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// + /// [out] An array of DBPROPSET structures. If rgPropertyIDSets is zero length, one structure is returned for each property set that + /// contains at least one property belonging to the Rowset property group. If rgPropertyIDSets is not zero length, one structure is + /// returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If rgPropertyIDSets is not zero lenght, the DBPROPSET structures in *prgPropertySets are returned in the same order as the + /// DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the + /// same. If cPropertyIDs in an element of rgPropertyIDSets is not zero, the DBPROP structures in the corresponding element of + /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column + /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties have + /// the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, one for + /// each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the same property + /// ID and rgProperties will contain more elements than rgPropertyIDs. + /// + /// + /// 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 *pcPropertySets is zero on output or an error other than DB_E_ERRORSOCCURRED occurs, + /// the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. ICommandProperties::GetProperties can fail to return properties + /// for a number of reasons, including: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero, or rgPropertyIDs + /// was not a null pointer. + /// + /// cPropertyIDSets was greater than one, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No values were returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer + /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no + /// longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723119(v=vs.85) HRESULT GetProperties ( const ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG * pcPropertySets, DBPROPSET ** prgPropertySets); + public static HRESULT GetProperties(this ICommandProperties icp, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) + { + var hr = icp.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); + mem.Count = (int)c; + prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; + return hr; + } + + /// Structure for . + [PInvokeData("oledb.h")] + [StructLayout(LayoutKind.Sequential)] + public struct DBPARAMBINDINFO + { + /// + /// + /// A pointer to the provider-specific name of the parameter's data type or a standard data type name. This name is not returned by + /// ICommandWithParameters::GetParameterInfo; instead, the provider maps the data type specified by this name to an OLE DB type + /// indicator and returns that type indicator. For a list of standard data type names, see "Comments" below. + /// + /// + /// If pwszDataSourceType is null, the provider attempts a default conversion from the data type specified in the binding for the + /// parameter or returns E_INVALIDARG if it cannot perform default parameter conversions. + /// + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string? pwszDataSourceType; + + /// + /// The name of the parameter. This is a null pointer if the parameter does not have a name. + /// + /// The consumer must specify a name for all or none of the parameters set at any time. If the provider does not support named + /// parameters, this argument is ignored and the provider is not required to verify that all or none of the parameters are named. + /// + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string? pwszName; + + /// + /// + /// The maximum possible length of a value in the parameter. For parameters that use a fixed-length data type, this is the size of + /// the data type. For parameters that use a variable-length data type, this is one of the following: + /// + /// + /// + /// The maximum length of the parameters in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and + /// DBTYPE_VARNUMERIC), if one is defined. For example, a parameter for a CHAR(5) column in an SQL table has a maximum length of 5. + /// + /// + /// The maximum length of the data type in characters (for DBTYPE_STR and DBTYPE_WSTR) or in bytes (for DBTYPE_BYTES and + /// DBTYPE_VARNUMERIC), if the parameter does not have a defined length. + /// + /// + /// ~0 (bitwise, the value is not 0; all bits are set to 1) if neither the parameter nor the data type has a defined maximum length. + /// + /// + /// For data types that do not have a length, this is set to ~0 (bitwise, the value is not 0; all bits are set to 1). + /// This argument is ignored if pwszDataSourceType is null. + /// + public DBLENGTH ulParamSize; + + /// See the dwFlags element of the DBPARAMINFO structure in GetParameterInfo. + public DBPARAMFLAGS dwFlags; + + /// + /// + /// If pwszDataSourceType is DBTYPE_DBTIMESTAMP or a numeric type, bPrecision is the maximum number of digits, expressed in base 10. + /// Otherwise, it is ignored. + /// + /// This argument is ignored if pwszDataSourceType is null. + /// + public byte bPrecision; + + /// + /// + /// If pwszDataSourceType is a numeric type with a fixed scale or if wType is DBTYPE_DBTIMESTAMP, bScale is the number of digits to + /// the right (if bScale is positive) or left (if bScale is negative) of the decimal point. Otherwise, it is ignored. + /// + /// This argument is ignored if pwszDataSourceType is null. + /// + public byte bScale; + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/OleDb.cs b/PInvoke/OleDb/OleDb2.cs similarity index 52% rename from PInvoke/OleDb/OleDb.cs rename to PInvoke/OleDb/OleDb2.cs index a90db0a8..44170d00 100644 --- a/PInvoke/OleDb/OleDb.cs +++ b/PInvoke/OleDb/OleDb2.cs @@ -1,1954 +1,155 @@ -global using static Vanara.PInvoke.Ole32; -global using HWATCHREGION = System.IntPtr; -global using HACCESSOR = System.IntPtr; -global using HROW = System.IntPtr; -global using HCHAPTER = System.IntPtr; -global using DB_DWRESERVE = nuint; -global using DB_LORDINAL = nint; -global using DB_LPARAMS = nint; -global using DB_LRESERVE = nint; -global using DB_UPARAMS = nuint; -global using DB_URESERVE = nuint; -global using DBBKMARK = nuint; -global using DBBYTEOFFSET = nuint; -global using DBCOUNTITEM = nuint; -global using DBKIND = uint; -global using DBHASHVALUE = uint; -global using DBLENGTH = nuint; -global using DBNUMBERIC = Vanara.PInvoke.Odbc32.SQL_NUMERIC_STRUCT; -global using DBDATE = Vanara.PInvoke.Odbc32.DATE_STRUCT; -global using DBTIME = Vanara.PInvoke.Odbc32.TIME_STRUCT; -global using DBTIMESTAMP = Vanara.PInvoke.Odbc32.TIMESTAMP_STRUCT; -global using DBORDINAL = nuint; -global using DBREFCOUNT = uint; -global using DBROWCOUNT = nint; -global using DBROWOFFSET = nint; -global using DISPPARAMS = System.Runtime.InteropServices.ComTypes.DISPPARAMS; -using System.Linq; - namespace Vanara.PInvoke; /// Items from the OleDb.dll. public static partial class OleDb { - /// Undocumented. - public const uint IDENTIFIER_SDK_ERROR = 0x10000000; - /// Undocumented. - public const uint IDENTIFIER_SDK_MASK = 0xF0000000; - private const string Lib_OleDb = "OleDb.dll"; - - /// - /// IAccessor provides methods for accessor management. For information about accessors, see the section about Accessors in Getting and - /// Setting Data. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719672(v=vs.85) + /// The literal described in the structure. For more information, see the following section. [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a8c-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IAccessor + public enum DBLITERAL { - /// Adds a reference count to an existing accessor. - /// [in] The handle of the accessor for which to increment the reference count. - /// - /// [out] A pointer to memory in which to return the reference count of the accessor handle. If pcRefCount is a null pointer, no - /// reference count is returned. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714978(v=vs.85) HRESULT AddRefAccessor ( HACCESSOR - // hAccessor, DBREFCOUNT *pcRefCount); - void AddRefAccessor(HACCESSOR hAccessor, out DBREFCOUNT pcRefCount); + /// An invalid value. + DBLITERAL_INVALID, - /// Creates an accessor from a set of bindings. - /// - /// [in] A bitmask that describes the properties of the accessor and how it is to be used. These flags have the following meanings. - /// - /// - /// Value - /// Description - /// - /// - /// DBACCESSOR_INVALID - /// This flag is used by IAccessor::GetBindings to indicate that the method failed. - /// - /// - /// DBACCESSOR_PASSBYREF - /// - /// The accessor is a reference accessor. The value passed in the consumer buffer is a pointer to the passer's internal buffer. This - /// pointer need not point to the start of the internal buffer as long as the relative offsets of all elements of the buffer align - /// with the offsets specified in the accessor. The passee must know the internal structure of the passer's buffer in order to read - /// information from it. The passee must not free the buffer at the pointer nor may it write to this buffer. For row accessors, this - /// buffer is the rowset's copy of the row. The consumer reads information directly from this copy of the row at a later point in - /// time, so the provider must guarantee that the pointer remains valid. For parameter accessors, this buffer is the consumer's - /// buffer. The provider reads data from this buffer only when ICommand::Execute is called; therefore, the pointer is not - /// required to remain valid after Execute returns. Support for this flag is optional. A consumer determines whether a - /// provider supports this bit by calling IDBProperties::GetProperties for the DBPROP_BYREFACCESSORS property. When this flag - /// is used, the dwMemOwner in the DBBINDING structure is ignored. If the accessor is used for row data, the accessor refers - /// to the provider's memory; the consumer must not write to or free this memory. If the accessor is used for input parameters, the - /// provider copies the row of data without assuming ownership. It is an error to specify an output or input/output parameter in a - /// reference accessor. For more information, see Reference Accessors in Getting and Setting Data (OLE DB). - /// - /// - /// - /// DBACCESSOR_ROWDATA - /// - /// The accessor is a row accessor and describes bindings to columns in the rowset. An accessor may be a row accessor, a parameter - /// accessor, or both. - /// - /// - /// - /// DBACCESSOR_PARAMETERDATA - /// - /// The accessor is a parameter accessor and describes bindings to parameters in the command text. In a parameter accessor, it is an - /// error to bind an input or an input/output parameter more than one time. - /// - /// - /// - /// DBACCESSOR_OPTIMIZED - /// - /// The row accessor is to be optimized. This hint may affect how a provider structures its internal buffers. A particular column can - /// be bound by only one optimized accessor. The column can also be bound by other, nonoptimized accessors, but the types specified - /// in the nonoptimized accessors must be convertible from the type in the optimized accessor. All optimized accessors must be - /// created before the first row is fetched with IRowset::GetNextRows, IRowsetLocate::GetRowsAt, - /// IRowsetLocate::GetRowsByBookmark, or IRowsetScroll::GetRowsAtRatio. This flag is ignored for parameter accessors - /// and may be ignored by providers that do not provide further optimizations or restrictions based on its setting. Providers that - /// enforce restrictions, such as limiting the number or types of columns bound in optimized accessors, must set this flag when - /// IAccessor::GetBindings is called on an optimized accessor. Providers that do not impose any restrictions on optimized - /// accessors or that ignore this flag entirely are not required to return this flag when IAccessor::GetBindings is called. - /// - /// - /// - /// DBACCESSOR_INHERITED - /// - /// Indicates an accessor on a command should be inherited by a rowset when the rowset implementation is in a separate component from - /// the command object. IAccessor::CreateAccessor is then used to pass an existing command accessor to the rowset - /// implementation. When DBACCESSOR_INHERITED is specified, phAccessor is used as an [in] argument and contains a pointer to - /// the value of the existing accessor handle. The rowset component then creates an internal accessor according to the specified - /// bindings for this handle value. - /// - /// - /// - /// - /// - /// [in] The number of bindings in the accessor. - /// - /// If cBindings is zero, IAccessor::CreateAccessor creates a null accessor. Null accessors are used only by - /// IRowsetChange::InsertRow to create a new row in which each column is set to its default value, NULL, or a status of - /// DBSTATUS_E_UNAVAILABLE. Providers that support IRowsetChange::InsertRow must support the creation of null accessors. For - /// more information, see InsertRow. - /// - /// - /// [in] An array of DBBINDING structures. For more information, see DBBINDING Structures. - /// - /// [in] The number of bytes allocated for a single set of parameters or criteria values in the consumer's buffer. - /// - /// cbRowSize is used by ICommand::Execute to process multiple sets of parameters and by IViewFilter::GetFilter and - /// IViewFilter::SetFilter to get and set multiple OR conditions in criteria. In either case, a single accessor may describe - /// multiple sets of values. cbRowSize is generally the size of the structure that contains a single set of parameter or criteria - /// values and is used as the offset to the start of the next set of values within the array of structures. For example, if - /// cParamSets is greater than 1 in the DBPARAMS structure passed to ICommand::Execute, the provider assumes that the pData - /// element of this structure points to an array of structures containing parameter values, each cbRowSize bytes in size. Similarly, - /// if cRows is greater than 1 in IViewFilter::SetFilter, the provider assumes that the pCriteriaData argument points to an - /// array of structures containing criteria values, each cbRowSize bytes in size. - /// - /// - /// cbRowSize must be large enough to contain the structure defined by the bindings in rgBindings. The provider is not required to - /// verify this, although it may. - /// - /// cbRowSize is not used when fetching rowset data. - /// - /// - /// [out] A pointer to memory in which to return the handle of the created accessor. If IAccessor::CreateAccessor fails, it - /// must attempt to set *phAccessor to a null handle. - /// - /// - /// - /// [out] An array of cBindings DBBINDSTATUS values in which IAccessor::CreateAccessor returns the status of each binding ? - /// that is, whether or not it was successfully validated. If rgStatus is a null pointer, no bind status values are returned. The - /// consumer allocates and owns the memory for this array. The bind status values are returned for the reasons described in the - /// following table. - /// - /// - /// - /// Value - /// Description - /// - /// - /// DBBINDSTATUS_OK - /// - /// No errors were found in the binding. Because accessor validation can be deferred, a status of DBBINDSTATUS_OK does not - /// necessarily mean that the binding was successfully validated. - /// - /// - /// - /// DBBINDSTATUS_BADORDINAL - /// - /// A parameter ordinal was zero in a parameter accessor. If the accessor is validated against the metadata when - /// IAccessor::CreateAccessor is called, DBBINDSTATUS_BADORDINAL can be returned for the following reasons: These reasons - /// cause a status value of DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. Some providers may support - /// binding more parameters than the number of parameters in the command text, and such providers do not return - /// DBBINDSTATUS_BADORDINAL in this case. - /// - /// - /// - /// DBBINDSTATUS_UNSUPPORTEDCONVERSION - /// - /// If the accessor is validated against the metadata when IAccessor::CreateAccessor is called, - /// DBBINDSTATUS_UNSUPPORTEDCONVERSION can be returned for the following reasons: These reasons cause a status value of - /// DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. - /// - /// - /// - /// DBBINDSTATUS_BADBINDINFO - /// - /// dwPart in a binding was not a combination of two or more of the following: DBPART_VALUE DBPART_LENGTH DBPART_STATUS - /// eParamIO in a binding in a parameter accessor was not one of the following: DBPARAMIO_INPUT DBPARAMIO_OUTPUT - /// DBPARAMIO_INPUT | DBPARAMIO_OUTPUT A row accessor was optimized, and a column ordinal in a binding was already used in another - /// optimized accessor. In a parameter accessor, two or more bindings contained the same ordinal for an input or input/output - /// parameter. wType in a binding was DBTYPE_EMPTY or DBTYPE_NULL. wType in a binding was one of the following: - /// DBTYPE_BYREF | DBTYPE _EMPTY, DBTYPE_BYREF | DBTYPE_NULL, or DBTYPE_BYREF | DBTYPE_RESERVED. wType in a binding was used - /// with more than one of the following mutually exclusive type indicators: DBTYPE_BYREF, DBTYPE_ARRAY, or DBTYPE_VECTOR. - /// wType in a binding was DBTYPE_IUNKNOWN, pObject in the same binding was a null pointer, and the provider did not - /// assume that the bound interface is IID_IUnknown. Provider-owned memory was specified for a nonpointer type in a - /// nonreference row accessor. Provider-owned memory was specified for a column, and the provider does not support binding to - /// provider-owned memory for this column. Provider-owned memory was specified for a column for which - /// IColumnsInfo::GetColumnInfo returned DBCOLUMNFLAGS_ISLONG, and the provider does not support binding long data to provider - /// owned memory. In a nonreference parameter accessor, a binding specified provider-owned memory. An output or input/output - /// parameter was specified in a parameter reference accessor. dwFlags in a binding was set to DBBINDFLAG_HTML, and - /// wType for the same binding was not a string value. The provider is an OLE DB 2.5 or later provider, and dwFlags was - /// set to an unknown or invalid value. dwMemOwner was invalid. Providers are not required to return DBBINDSTATUS_BADBINDINFO. - /// If they ignore an invalid value of dwMemOwner, they must default to DBMEMOWNER_CLIENTOWNED. If the accessor is validated - /// against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_BADBINDINFO can be returned for the following reasons: - /// - /// - /// - /// DBBINDSTATUS_BADSTORAGEFLAGS - /// - /// dwFlags, in the DBOBJECT structure pointed to by a binding, specified invalid storage flags. If the accessor is validated - /// against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_BADSTORAGEFLAGS can be returned if - /// dwFlags, in the DBOBJECT structure pointed to by a binding, specified a valid storage flag that was not supported by the - /// object. This causes a status value of DBSTATUS_E_BADACCESSOR to be returned if the accessor is validated when used. - /// - /// - /// - /// DBBINDSTATUS_NOINTERFACE - /// - /// If the accessor is validated against the metadata when IAccessor::CreateAccessor is called, DBBINDSTATUS_NOINTERFACE can - /// be returned for the following reasons: These reasons cause a status value of DBSTATUS_E_BADACCESSOR to be returned if the - /// accessor is validated when used. - /// - /// - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. If rgStatus is not a null pointer, each element is set to DBBINDSTATUS_OK. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG phAccessor was a null pointer. - /// cBindings was not zero, and rgBindings was a null pointer. - /// - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This - /// error can be returned only when the method is called on a rowset. - /// - /// - /// - /// - /// - /// DB_E_BADACCESSORFLAGS dwAccessorFlags was invalid. - /// The DBACCESSOR_PARAMETERDATA bit was set in dwAccessorFlags, and the provider does not support parameters. - /// Neither the DBACCESSOR_PARAMETERDATA bit nor the DBACCESSOR_ROWDATA bit was set in dwAccessorFlags. - /// - /// A method that fetches rows ( IRowset::GetNextRows, IRowsetLocate::GetRowsAt, - /// IRowsetLocate::GetRowsByBookmark, or IRowsetScroll::GetRowsAtRatio) had already been called, and the - /// DBACCESSOR_OPTIMIZED bit in dwAccessorFlags was set. - /// - /// The DBACCESSOR_ PARAMETERDATA bit was set, and IAccessor::CreateAccessor was called on a rowset. - /// - /// - /// - /// - /// - /// DB_E_BYREFACCESSORNOTSUPPORTED dwAccessorFlags was DBACCESSOR_PASSBYREF, and the value of the DBPROP_BYREFACCESSORS property is VARIANT_FALSE. - /// - /// - /// Consumers should always check to see whether the provider supports the property DBPROP_BYREFACCESSORS and call - /// IAccessor::CreateAccessor with the DBACCESSOR_PASSBYREF flag only if the provider supports this property. For performance - /// reasons, some service providers might be unable to detect whether the underlying data provider supports DBACCESSOR_PASSBYREF on - /// the CreateAccessor call and might return DB_E_BYREFACCESSORNOTSUPPORTED. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED Accessor validation failed. To determine which bindings failed, the consumer checks the values returned in - /// rgStatus, at least one of which is not DBBINDSTATUS_OK. - /// - /// - /// - /// - /// - /// - /// 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_NULLACCESSORNOTSUPPORTED cBindings was zero, and either the rowset does not expose IRowsetChange::InsertRow or - /// IAccessor::CreateAccessor was called on a command. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720969(v=vs.85) HRESULT CreateAccessor ( DBACCESSORFLAGS - // dwAccessorFlags, DBCOUNTITEM cBindings, const DBBINDING rgBindings[], DBLENGTH cbRowSize, HACCESSOR *phAccessor, DBBINDSTATUS rgStatus[]); - [PreserveSig] - HRESULT CreateAccessor(DBACCESSORFLAGS dwAccessorFlags, DBCOUNTITEM cBindings, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBINDING[] rgBindings, - [Optional] DBLENGTH cbRowSize, out HACCESSOR phAccessor, [In, Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBBINDSTATUS[]? rgStatus); + /// A binary literal in a text command. + DBLITERAL_BINARY_LITERAL, - /// Returns the bindings in an accessor. - /// [in] The handle of the accessor for which to return the bindings. - /// - /// [out] A pointer to memory in which to return a bitmask that describes the properties of the accessor and how it is intended to be - /// used. For more information, see dwAccessorFlags in CreateAccessor. If this method fails, *pdwAccessorFlags is set to DBACCESSOR_INVALID. - /// - /// - /// [out] A pointer to memory in which to return the number of bindings in the accessor. If this method fails, *pcBindings is set to zero. - /// - /// - /// [out] A pointer to memory in which to return an array of DBBINDING structures. One DBBINDING structure is returned for each - /// binding in the accessor. The provider allocates memory for these structures and any structures pointed to by elements of these - /// structures; for example, if pObject in a binding structure is not a null pointer, the provider allocates a DBOBJECT structure for - /// return to the consumer. The provider returns the address to the memory for these structures; the consumer releases the memory for - /// these structures with IMalloc::Free when it no longer needs the bindings. If *pcBindings is zero on output or the method - /// fails, the provider does not allocate any memory and ensures that *prgBindings is a null pointer on output. For information about - /// bindings, see DBBINDING Structures. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721253(v=vs.85) HRESULT GetBindings ( HACCESSOR hAccessor, - // DBACCESSORFLAGS *pdwAccessorFlags, DBCOUNTITEM *pcBindings, DBBINDING **prgBindings); - void GetBindings(HACCESSOR hAccessor, out DBACCESSORFLAGS pdwAccessorFlags, out DBCOUNTITEM pcBindings, - out SafeIMallocHandle prgBindings); + /// A catalog name in a text command. + DBLITERAL_CATALOG_NAME, - /// Releases an accessor. - /// [in] The handle of the accessor to release. - /// - /// [out] A pointer to memory in which to return the remaining reference count of the accessor handle. If pcRefCount is a null - /// pointer, no reference count is returned. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719717(v=vs.85) HRESULT ReleaseAccessor ( HACCESSOR - // hAccessor, DBREFCOUNT *pcRefCount); - void ReleaseAccessor(HACCESSOR hAccessor, out DBREFCOUNT pcRefCount); - } + /// The character that separates the catalog name from the rest of the identifier in a text command. + DBLITERAL_CATALOG_SEPARATOR, - /// - /// IColumnsInfo is the simpler of two interfaces that can be used to expose information about columns of a rowset or prepared - /// command. It provides a limited set of information in an array. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725401(v=vs.85) - [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a11-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IColumnsInfo - { - /// Returns the column metadata needed by most consumers. - /// - /// [out] A pointer to memory in which to return the number of columns in the rowset; this number includes the bookmark column, if - /// there is one. If IColumnsInfo::GetColumnInfo is called on a command that does not return rows, *pcColumns is set to zero. - /// If this method terminates due to an error, *pcColumns is set to zero. - /// - /// - /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in - /// the rowset. 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 column information. If *pcColumns is 0 on output or terminates due - /// to an error, the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more - /// information, see "DBCOLUMNINFO Structures" in the Comments section. - /// - /// - /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used either within columnid or for - /// pwszName) within a single allocation block. If no returned columns have either form of string name or if this method terminates - /// due to error, this parameter returns a null pointer. If there are any string names, this will be a buffer containing all the - /// values of those names. The consumer should free the buffer with IMalloc::Free when finished working with the names. If - /// *pcColumns is zero on output, the provider does not allocate any memory and ensures that *ppStringsBuffer is a null pointer on - /// output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the - /// buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG pcColumns, prgInfo, or ppStringsBuffer was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures. - /// - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This - /// error can be returned only when the method is called on a rowset. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details - /// about the errors. - /// - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This - /// error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// - /// - /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) - // HRESULT GetColumnInfo ( DBORDINAL *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); - [PreserveSig] - HRESULT GetColumnInfo(out DBORDINAL pcColumns, out SafeIMallocHandle prgInfo, out SafeIMallocHandle ppStringsBuffer); + /// A character literal in a text command. + DBLITERAL_CHAR_LITERAL, - /// Returns an array of ordinals of the columns in a rowset that are identified by the specified column IDs. - /// - /// [in] The number of column IDs to map. If cColumnIDs is 0, IColumnsInfo::MapColumnIDs does nothing and returns S_OK. - /// - /// - /// [in] An array of IDs of the columns of which to determine the column ordinals. If rgColumnIDs contains a duplicate column ID, a - /// column ordinal is returned once for each occurrence of the column ID. If the column ID is invalid, the corresponding element of - /// rgColumns is set to DB_INVALIDCOLUMN. - /// - /// - /// [out] An array of cColumnIDs ordinals of the columns identified by the elements of rgColumnIDs. 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 - /// column IDs in the array. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. All elements of rgColumns are set to values other than DB_INVALIDCOLUMN. - /// - /// cColumnIDs was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cColumnIDs was zero and - /// either or both rgColumnIDs and rgColumns was a null pointer. - /// - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED An element of rgColumnIDs was invalid. If the column ID is invalid, the corresponding element of rgColumns is - /// set to DB_INVALIDCOLUMN. - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cColumnIDs was not 0, and rgColumnIDs was a null pointer. - /// rgColumns was a null pointer. - /// - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This - /// error can be returned only when the method is called on a rowset. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED All elements of rgColumnIDs were invalid. All elements of rgColumns are set to DB_INVALIDCOLUMN. - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This - /// error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// - /// - /// 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/ms714200(v=vs.85) HRESULT MapColumnIDs ( DBORDINAL cColumnIDs, - // const DBID rgColumnIDs[], DBORDINAL rgColumns[]); - [PreserveSig] - HRESULT MapColumnIDs(DBORDINAL cColumnIDs, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDs, - [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBORDINAL[]? rgColumns); - } + /// A column alias in a text command. + DBLITERAL_COLUMN_ALIAS, - /// The IColumnsInfo2 interface allows a consumer to obtain column names or metadata for the columns in a row or rowset. - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712953(v=vs.85) - [PInvokeData("oledb.h")] - [ComImport, Guid("0c733ab8-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IColumnsInfo2 : IColumnsInfo - { - /// Returns the column metadata needed by most consumers. - /// - /// [out] A pointer to memory in which to return the number of columns in the rowset; this number includes the bookmark column, if - /// there is one. If IColumnsInfo::GetColumnInfo is called on a command that does not return rows, *pcColumns is set to zero. - /// If this method terminates due to an error, *pcColumns is set to zero. - /// - /// - /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in - /// the rowset. 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 column information. If *pcColumns is 0 on output or terminates due - /// to an error, the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more - /// information, see "DBCOLUMNINFO Structures" in the Comments section. - /// - /// - /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used either within columnid or for - /// pwszName) within a single allocation block. If no returned columns have either form of string name or if this method terminates - /// due to error, this parameter returns a null pointer. If there are any string names, this will be a buffer containing all the - /// values of those names. The consumer should free the buffer with IMalloc::Free when finished working with the names. If - /// *pcColumns is zero on output, the provider does not allocate any memory and ensures that *ppStringsBuffer is a null pointer on - /// output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the - /// buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG pcColumns, prgInfo, or ppStringsBuffer was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures. - /// - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This - /// error can be returned only when the method is called on a rowset. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details - /// about the errors. - /// - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This - /// error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// - /// - /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) - // HRESULT GetColumnInfo ( DBORDINAL *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); - [PreserveSig] - new HRESULT GetColumnInfo(out DBORDINAL pcColumns, out SafeIMallocHandle prgInfo, out SafeIMallocHandle ppStringsBuffer); + /// A column name used in a text command or in a data-definition interface. + DBLITERAL_COLUMN_NAME, - /// Returns an array of ordinals of the columns in a rowset that are identified by the specified column IDs. - /// - /// [in] The number of column IDs to map. If cColumnIDs is 0, IColumnsInfo::MapColumnIDs does nothing and returns S_OK. - /// - /// - /// [in] An array of IDs of the columns of which to determine the column ordinals. If rgColumnIDs contains a duplicate column ID, a - /// column ordinal is returned once for each occurrence of the column ID. If the column ID is invalid, the corresponding element of - /// rgColumns is set to DB_INVALIDCOLUMN. - /// - /// - /// [out] An array of cColumnIDs ordinals of the columns identified by the elements of rgColumnIDs. 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 - /// column IDs in the array. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. All elements of rgColumns are set to values other than DB_INVALIDCOLUMN. - /// - /// cColumnIDs was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cColumnIDs was zero and - /// either or both rgColumnIDs and rgColumns was a null pointer. - /// - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED An element of rgColumnIDs was invalid. If the column ID is invalid, the corresponding element of rgColumns is - /// set to DB_INVALIDCOLUMN. - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cColumnIDs was not 0, and rgColumnIDs was a null pointer. - /// rgColumns was a null pointer. - /// - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This - /// error can be returned only when the method is called on a rowset. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED All elements of rgColumnIDs were invalid. All elements of rgColumns are set to DB_INVALIDCOLUMN. - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was set. This error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// DB_E_NOTABLE ICommandPrepare was not implemented, and the specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTPREPARED The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This - /// error can be returned only when this method is called from the command object. - /// - /// - /// - /// - /// - /// - /// 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/ms714200(v=vs.85) HRESULT MapColumnIDs ( DBORDINAL cColumnIDs, - // const DBID rgColumnIDs[], DBORDINAL rgColumns[]); - [PreserveSig] - new HRESULT MapColumnIDs(DBORDINAL cColumnIDs, [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDs, - [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBORDINAL[]? rgColumns); + /// A correlation name (table alias) in a text command. + DBLITERAL_CORRELATION_NAME, + + /// A cursor name in a text command. + DBLITERAL_CURSOR_NAME, /// - /// - /// Retrieves column names or column metadata for a row or rowset. Column names are returned in an array of column IDs (DBIDs). - /// Column metadata is returned in an array of DBCOLUMNINFO structures. - /// - /// For information about column IDs, see Column IDs. For information about DBCOLUMNINFO structures, see IColumnsInfo::GetColumnInfo. + /// The character used in a LIKE clause to escape the character returned for the DBLITERAL_LIKE_PERCENT literal. For example, if a + /// percent sign (%) is used to match zero or more characters and this is a backslash (\), the characters "abc\%%" match all + /// character values that start with "abc%". + /// Some SQL dialects support a clause (the ESCAPE clause) that can be used to override this value. /// - /// - /// [in] The count of column name masks in rgColumnIDMasks. If cColumnIDMasks is zero, IColumnsInfo2::GetRestrictedColumnInfo - /// enumerates all columns in the row. - /// - /// - /// [in] An array of cColumnIDMasks column name masks used to restrict the set of columns enumerated. All columns whose DBID matches - /// the elements of rgColumnIDMasks or whose names begin with the string contained in the pwszName element of any of the DBIDs in - /// this array will be returned in the enumeration. If cColumnIDMasks is zero, rgColumnIDMasks is ignored. - /// - /// [in] Reserved. Must be zero. - /// - /// [out] A pointer to memory in which to return a count of the column names and DBCOLUMNINFO structures returned in prgColumnIDs and - /// prgColumnInfo, respectively. If no columns are described or if the method terminates with an error, ***pcColumns is set to zero. - /// - /// - /// [out] A pointer to memory in which to return an array of column IDs (DBIDs) containing the requested column names. - /// IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. This argument - /// duplicates the DBIDs provided in the prgColumnInfo argument but is provided for direct use with methods such as - /// IRowSchemaChange::DeleteColumns that require an array of DBIDs. The provider allocates memory for the DBIDs. The consumer is - /// responsible for releasing this memory with IMalloc::Free. If an error code is returned and prgColumnIDs is not a null pointer, - /// ***prgColumnIDs should be set to NULL. - /// - /// - /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures containing the requested column names. - /// IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. The provider - /// allocates memory for the DBCOLUMNINFO structures. The consumer is responsible for releasing this memory with IMalloc::Free. If an - /// error code is returned and prgColumnInfo is not a null pointer, ***prgColumnInfo should be set to NULL. - /// - /// - /// [out] A pointer to memory in which to return a pointer to storage for all string values (names used with either columnid or - /// *pwszName of the DBCOLUMNINFO structure) within a single allocation block. If no columns are returned, ppStringsBuffer should be - /// set to NULL. If there are any string names, ppStringsBuffer points to a buffer containing all the values of those names. The - /// consumer is responsible for releasing this memory with IMalloc::Free. If an error code is returned and ppStringsBuffer is not a - /// null pointer, ***ppStringsBuffer should be set to NULL. - /// - /// - /// - /// - /// - /// S_OK The requested columns were successfully enumerated. - /// - /// - /// - /// - /// DB_E_BADCOLUMNID An element of rgColumnIDMasks was an invalid DBID. - /// - /// - /// - /// - /// DB_E_DELETEDROW The row was deleted or moved. - /// - /// - /// - /// - /// - /// DB_E_NOCOLUMN No columns matched the mask criteria. The provider sets ***pcColumns to zero and other output arguments to NULL. - /// - /// - /// - /// - /// - /// - /// 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the column information. - /// - /// - /// - /// - /// E_INVALIDARG cColumnIDMasks was not zero, and rgColumnIDMasks was a null pointer. - /// pcColumns was a null pointer. - /// ppStringsBuffer was a null pointer. - /// prgColumnIDs and prgColumnInfo are both null pointers. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the column information structures or - /// string buffer. - /// - /// - /// - /// - /// - /// 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/ms712988(v=vs.85) HRESULT GetRestrictedColumnInfo( DBORDINAL - // cColumnIDMasks, const DBID rgColumnIDMasks[ ], DWORD dwFlags, DBORDINAL *pcColumns, DBID **prgColumnIDs, DBCOLUMNINFO - // **prgColumnInfo, OLECHAR **ppStringsBuffer); - void GetRestrictedColumnInfo(DBORDINAL cColumnIDMasks, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBID[]? rgColumnIDMasks, - [Optional] uint dwFlags, out DBORDINAL pcColumns, out SafeIMallocHandle prgColumnIDs, out SafeIMallocHandle prgColumnInfo, out SafeIMallocHandle ppStringsBuffer); + DBLITERAL_ESCAPE_PERCENT_PREFIX, + + /// + /// The character used in a LIKE clause to escape the character returned for the DBLITERAL_LIKE_UNDERSCORE literal. For example, if + /// an underscore (_) is used to match exactly one character and this is a backslash (\), the characters "abc\_ _" match all + /// character values that are five characters long and start with "abc_". + /// Some SQL dialects support a clause (the ESCAPE clause) that can be used to override this value. + /// + DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, + + /// An index name used in a text command or in a data-definition interface. + DBLITERAL_INDEX_NAME, + + /// + /// The character used in a LIKE clause to match zero or more characters. For example, if this is a percent sign (%), the characters + /// "abc%" match all character values that start with "abc". + /// + DBLITERAL_LIKE_PERCENT, + + /// + /// The character used in a LIKE clause to match exactly one character. For example, if this is an underscore (_), the characters + /// "abc_" match all character values that are four characters long and start with "abc". + /// + DBLITERAL_LIKE_UNDERSCORE, + + /// A procedure name in a text command. + DBLITERAL_PROCEDURE_NAME, + + /// The character used in a text command as the opening quote for quoting identifiers that contain special characters. + DBLITERAL_QUOTE_PREFIX, + + /// A schema name in a text command. + DBLITERAL_SCHEMA_NAME, + + /// A table name used in a text command or in a data-definition interface. + DBLITERAL_TABLE_NAME, + + /// A text command, such as an SQL statement. + DBLITERAL_TEXT_COMMAND, + + /// A user name in a text command. + DBLITERAL_USER_NAME, + + /// A view name in a text command. + DBLITERAL_VIEW_NAME, + + /// + DBLITERAL_CUBE_NAME, + + /// + DBLITERAL_DIMENSION_NAME, + + /// + DBLITERAL_HIERARCHY_NAME, + + /// + DBLITERAL_LEVEL_NAME, + + /// + DBLITERAL_MEMBER_NAME, + + /// + DBLITERAL_PROPERTY_NAME, + + /// The character that separates the schema name from the rest of the identifier in a text command. + DBLITERAL_SCHEMA_SEPARATOR, + + /// + /// The character used in a text command as the closing quote for quoting identifiers that contain special characters. 1.x providers + /// that use the same character as the prefix and suffix may not return this literal value and can set the lt member of the DBLITERAL + /// structure to DBLITERAL_INVALID if requested. + /// + DBLITERAL_QUOTE_SUFFIX, + + /// + /// The escape character, if any, used to suffix the character returned for the DBLITERAL_LIKE_PERCENT literal. For example, if a + /// percent sign (%) is used to match zero or more characters and percent signs are escaped by enclosing in open and close square + /// brackets, DBLITERAL_ESCAPE_PERCENT_PREFIX is "[", DBLITERAL_ESCAPE_PERCENT_SUFFIX is "]", and the characters "abc[%]%" match all + /// character values that start with "abc%". Providers that do not use a suffix character to escape the DBLITERAL_ESCAPE_PERCENT + /// character do not return this literal value and can set the lt member of the DBLITERAL structure to DBLITERAL_INVALID if requested. + /// + DBLITERAL_ESCAPE_PERCENT_SUFFIX, + + /// + /// The escape character, if any, used to suffix the character returned for the DBLITERAL_LIKE_UNDERSCORE literal. For example, if an + /// underscore (_) is used to match exactly one character and underscores are escaped by enclosing in open and close square brackets, + /// DBLITERAL_ESCAPE_UNDERSCORE_PREFIX is "[", DBLITERAL_ESCAPE_UNDERSCORE_SUFFIX is "]", and the characters "abc[_]_" match all + /// character values that are five characters long and start with "abc_". Providers that do not use a suffix character to escape the + /// DBLITERAL_ESCAPE_UNDERSCORE character do not return this literal value and can set the lt member of the DBLITERAL structure to + /// DBLITERAL_INVALID if requested. + /// + DBLITERAL_ESCAPE_UNDERSCORE_SUFFIX, } - /// - /// - /// ICommand contains methods to execute commands. A command can be executed many times, and the parameter values can vary. This - /// interface is mandatory on commands. - /// - /// A command object contains a single text command, which is specified through ICommandText - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709737(v=vs.85) - [PInvokeData("")] - [ComImport, Guid("0c733a63-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ICommand + /// Result flags for . + [PInvokeData("oledb.h")] + public enum DBRESULTFLAG { - /// Cancels the current command execution. - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714402(v=vs.85) HRESULT Cancel(); - void Cancel(); + /// + /// The type of the returned object is defined by riid or by properties set on the command object. If this is ambiguous, the provider + /// should return a rowset. Prior to OLE DB 2.6, providers were required to return E_INVALIDARG when lResultFlag was not zero. + /// Consumers should not pass nonzero values unless the provider is a 2.6 or later provider and has added support for lResultFlag. + /// + DBRESULTFLAG_DEFAULT = 0, - /// Executes the command. - /// - /// [in] A pointer to the controlling IUnknown interface if the rowset is being created as part of an aggregate; otherwise, it - /// is null. - /// - /// - /// - /// [in] The requested IID for the rowset returned in *ppRowset. This interface is conceptually added to the list of required - /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting - /// rowset. If the command has any open rowsets, requesting an interface that is not supported on those open rowsets will generally - /// return E_NOINTERFACE as it is not possible to change the properties supported on a command with open rowsets. In addition, - /// specifying the IID of a nonmandatory interface that has not been explicitly requested through rowset properties set on a prepared - /// command might reduce the provider's ability to optimize the command, because the provider might have to rebuild the access plan - /// to satisfy the additional interface. - /// - /// - /// If this is IID_NULL, ppRowset is ignored and no rowset is returned, even if the command would otherwise generate a rowset. - /// Specifying IID_NULL is useful in the case of text commands that do not generate rowsets, such as data definition commands, as a - /// hint to the provider that no rowset properties need to be verified. - /// - /// - /// If riid is IID_IMultipleResults, the provider creates a multiple results object and returns a pointer to it in *ppRowset; - /// it does this even if the command generates a single result. If the provider supports multiple results and the command generates - /// multiple results but riid is not IID_IMultipleResults, the provider returns the first result and discards any remaining - /// results. If riid is IID_IMultipleResults and the provider does not support multiple results, ICommand::Execute - /// returns E_NOINTERFACE. - /// - /// - /// - /// - /// [in/out] A pointer to a DBPARAMS structure that specifies the values for one or more parameters. In text commands that use - /// parameters, if no value is specified for a parameter through pParams, an error occurs. - /// - /// The elements of this structure are used as described in the following table. - /// - /// - /// Element - /// Description - /// - /// - /// pData - /// - /// Pointer to a buffer from which the provider retrieves input parameter data and to which the provider returns output parameter - /// data, according to the bindings specified by hAccessor. This pointer must be a valid pointer to a contiguous block of - /// consumer-owned memory for the input and output parameter values. For more information, see Getting Data and Setting Data. When - /// output parameter data is available to the consumer depends on the DBPROP_OUTPUTPARAMETERAVAILABILITY property. - /// - /// - /// - /// cParamSets - /// - /// The number of sets of parameters in * pData. If cParamSets is greater than one, the bindings described by - /// hAccessor define the offsets within * pData for each set of parameters and cbRowSize (as specified in - /// IAccessor::CreateAccessor) defines a single fixed offset between each of those values and the corresponding values for the - /// next set of parameters. Sets of multiple parameters ( cParamSets is greater than one) can be specified only if - /// DBPROP_MULTIPLEPARAMSETS is VARIANT_TRUE and the command does not return any rowsets. - /// - /// - /// - /// hAccessor - /// - /// Handle of the accessor to use. If hAccessor is the handle of a null accessor ( cBindings in - /// IAccessor::CreateAccessor was 0), ICommand::Execute does not retrieve or return any parameter values. - /// - /// - /// - /// - /// If the provider is able to determine the number of parameters in the command and the command text does not include parameters, - /// the provider ignores this argument. - /// - /// - /// - /// - /// [out] A pointer to memory in which to return the count of rows affected by a command that updates, deletes, or inserts rows. If - /// cParamSets is greater than one, *pcRowsAffected is the total number of rows affected by all of the sets of parameters specified - /// in the execution. If the number of affected rows is not available, *pcRowsAffected is set to DB_COUNTUNAVAILABLE on output. If - /// riid is IID_IMultipleResults, the value returned in *pcRowsAffected is either DB_COUNTUNAVAILABLE or the total number of - /// rows affected by the entire command; to retrieve individual row counts, the consumer calls IMultipleResults::GetResult. If - /// the command does not update, delete, or insert rows, *pcRowsAffected is undefined on output. If pcRowsAffected is a null pointer, - /// no count of rows is returned. - /// - /// - /// pcRowsAffected is undefined if ICommand::Execute returns DB_S_ASYNCHRONOUS. For asynchronously executed commands, the - /// consumer should call IDBAsynchStatus::GetStatus to obtain the number of rows affected in pulProgress. - /// - /// - /// - /// - /// [in/out] A pointer to the memory in which to return the rowset's pointer. If ppRowset is a null pointer, no rowset is created. - /// However, if the DBPROP_OUTPUTSTREAM property is set and the result of ICommand::Execute is a stream object, a null pointer - /// is an acceptable value. - /// - /// - /// If ppRowset is not a null pointer and an interface on a stream object was requested, the provider returns to *ppRowset the - /// interface pointer set in the DBPROP_OUTPUTSTREAM property. The consumer must release the interface pointer in *ppRowset when it - /// is no longer needed. - /// - /// If *ppRowset is a null pointer, the provider did not write any results to the stream specified in DBPROP_OUTPUTSTREAM. - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK; the status of all - /// input parameters bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL; and the status of all output parameters - /// bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED ? or is unknown because the parameter - /// value has not been returned yet. - /// - /// - /// - /// - /// - /// - /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to - /// poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any - /// other interfaces may fail, and the full set of interfaces may not be available on the object until asynchronous initialization of - /// the rowset has completed. DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED This can be returned for any of the following reasons: - /// - /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see - /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. - /// - /// - /// DB_S_ERRORSOCCURRED should be returned before DB_S_NOTSINGLETON because the status values can be checked, and providers are not - /// required to return DB_S_NOTSINGLETON. - /// - /// - /// - /// - /// - /// - /// DB_S_NOTSINGLETON The provider supports returning row objects on ICommand::Execute, and the consumer requested a row - /// object but the result was not a singleton. A row object of the first row of the rowset is returned. Returning this result may be - /// expensive, so providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes - /// precedence over DB_S_NOTSINGLETON. - /// - /// - /// - /// - /// - /// - /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been - /// returned. Execution cannot be resumed. - /// - /// - /// Multiple sets of parameters were specified, and one or more (but not all) of the parameters have been processed prior to the - /// command being canceled by ICommand::Cancel or IDBAsynchStatus::Abort. - /// - /// - /// 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 riid was not IID_NULL, and ppRowset was a null pointer. Any streams used to pass input parameters are not released. - /// - /// - /// The parameter information was invalid. Parameter information may be invalid for any of the following reasons. In all cases, any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// E_NOINTERFACE The rowset did not support the interface specified in riid. - /// riid was IID_IMultipleResults, and the provider did not support multiple results objects. - /// - /// - /// - /// - /// - /// DB_E_ABORTLIMITREACHED Execution has been aborted because a resource limit has been reached. For example, a query timed out. No - /// results have been returned. - /// - /// - /// - /// - /// - /// - /// DB_E_BADACCESSORHANDLE pParams was not ignored, and hAccessor in the DBPARAMS structure pointed to by pParams was invalid. Any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// - /// DB_E_BADACCESSORTYPE hAccessor in the DBPARAMS structure pointed to by pParams was not the handle of a parameter accessor. Any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// DB_E_CANCELED The command was canceled by a call to ICommand::Cancel on another thread. No records were affected. - /// - /// - /// - /// - /// - /// DB_E_CANTCONVERTVALUE A literal value in the command text could not be converted to the type of the associated column for reasons - /// other than data overflow. - /// - /// - /// - /// - /// - /// DB_E_DATAOVERFLOW A literal value in the command text overflowed the type specified by the associated column. - /// - /// - /// - /// - /// - /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details - /// about the errors. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED The method failed due to one or more nonvalid input parameter values. To determine which input parameter - /// values were not valid, 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.) If any streams were used to pass input parameters, only those with the - /// status value equal to DBSTATUS_S_OK on input are released; otherwise, no attempt is made to release the stream. If the consumer - /// provides storage objects for additional bound parameters that are not used by the current command, it is a consumer programming - /// error and the provider does not attempt to release these parameters. - /// - /// - /// The command was not executed, and no rowset was returned because one or more properties ? for which the dwOptions element of the - /// DBPROP structure was DBPROPOPTIONS_REQUIRED ? were not set. - /// - /// Multiple parameter sets were passed with a command that returns a rowset. (Some providers might not return this error.) - /// - /// - /// - /// - /// DB_E_INTEGRITYVIOLATION A literal value in the command text violated the integrity constraints for the column. - /// - /// - /// - /// - /// - /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support - /// aggregation of the rowset object being created. Any streams used to pass input parameters are not released. - /// - /// - /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. Any streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was currently set on the command object. Any streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// DB_E_NOTABLE The specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTFOUND The provider supports row objects, a row was requested via riid or DBPROP_IRow, and no rows satisfied the selection - /// criteria of the command. - /// - /// - /// - /// - /// - /// DB_E_PARAMNOTOPTIONAL A value was not supplied for a required parameter. - /// The command text used parameters and pParams was a null pointer. - /// - /// - /// - /// - /// - /// DB_E_PARAMUNAVAILABLE Provider cannot derive parameter information, and ICommandWithParameters::SetParameterInfo has not - /// been called. - /// - /// - /// - /// - /// - /// - /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to execute the command. For example, a rowset-returning - /// command specified a column for which the consumer does not have read permission, or an update command specified a column for - /// which the consumer does not have write permission. - /// - /// - /// - /// - /// - /// - /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set - /// to VARIANT_FALSE. Any streams used to pass input parameters are not released. - /// - /// - /// If a session is enlisted in a global transaction and a command requires the creation of an additional connection, the provider - /// should return DB_E_OBJECTOPEN. Providers written prior to OLE DB 2.6 may return E_FAIL. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718095(v=vs.85) HRESULT Execute ( IUnknown *pUnkOuter, - // REFIID riid, DBPARAMS *pParams, DBROWCOUNT *pcRowsAffected, IUnknown **ppRowset); - [PreserveSig] - HRESULT Execute([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [In, Out, Optional] DBPARAMS? pParams, - out DBROWCOUNT pcRowsAffected, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + /// The consumer explicitly requests a rowset object. + DBRESULTFLAG_ROWSET = 1, - /// Returns an interface pointer to the session that created the command. - /// [in] The IID of the interface on which to return a pointer. - /// - /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the - /// command, it sets *ppSession to a null pointer. If ICommand::GetDBSession fails, it must attempt to set *ppSession to a - /// null pointer. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// S_FALSE The provider did not have an object that created the command. Therefore, it set *ppSession to a null pointer. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG ppSession was a null pointer. - /// - /// - /// - /// - /// E_NOINTERFACE The session did not support the interface specified in riid. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719622(v=vs.85) HRESULT GetDBSession ( REFIID riid, IUnknown **ppSession); - [PreserveSig] - HRESULT GetDBSession(in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppSession); - } - - /// - /// - /// ICommandProperties specifies to the command the properties from the Rowset property group that must be supported by the - /// rowsets returned by ICommand::Execute. A special case of these properties, and the ones most commonly requested, are the - /// interfaces the rowset must support. In addition to interfaces, the consumer can request properties that modify the behavior of the - /// rowset or interfaces. - /// - /// - /// All rowsets must support IRowset, IAccessor, IColumnsInfo, IRowsetInfo, and IConvertType. - /// Providers may choose to return rowsets supporting other interfaces if doing so is possible and if the support for the returned - /// interfaces does not affect consumer code that is not expecting them. The riid parameter of ICommand::Execute should be one of - /// the interfaces returned by IRowsetInfo::GetProperties. - /// - /// This interface is mandatory on commands. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723044(v=vs.85) - [PInvokeData("")] - [ComImport, Guid("0c733a79-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ICommandProperties - { - /// Returns the list of properties in the Rowset property group that are currently requested for the rowset. - /// - /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. - /// - /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Rowset property - /// group for which values have been set or defaults exist. It does not return the values of properties in the Rowset property group - /// for which values have not been set and no defaults exist nor does it return the values of properties for which no value has been - /// set, no default exists, and for which a value will be set automatically because a value for another property in the Rowset - /// property group has been set. - /// - /// - /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the - /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of - /// dwOptions is undefined. - /// - /// - /// - /// - /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset - /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this - /// parameter is ignored. - /// - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix - /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets - /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Rowset - /// property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than - /// DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. - /// - /// - /// - /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is - /// returned for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is - /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET - /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If - /// cPropertyIDs in an element of rgPropertyIDSets is not zero, the DBPROP structures in the corresponding element of - /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column - /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties - /// have the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, - /// one for each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the - /// same property ID and rgProperties will contain more elements than rgPropertyIDs. - /// - /// - /// 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 *pcPropertySets is zero on output or an error other than - /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. ICommandProperties::GetProperties can fail to return - /// properties for a number of reasons, including: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero, or - /// rgPropertyIDs was not a null pointer. - /// - /// cPropertyIDSets was greater than one, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED No values were returned for any properties. The provider allocates memory for *prgPropertySets, and the - /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory - /// when it no longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723119(v=vs.85) HRESULT GetProperties ( const ULONG - // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG * pcPropertySets, DBPROPSET ** prgPropertySets); - [PreserveSig] - HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, - out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); - - /// Sets properties in the Rowset property group. - /// - /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method - /// does not do anything. - /// - /// - /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these - /// structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, the - /// value is used is provider-specific. If cPropertySets is zero, this parameter is ignored. - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix - /// C.For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the - /// DBPROP structures to determine which properties were not set. ICommandProperties::SetProperties can fail to set properties - /// for a number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertySets was not equal to zero, and rgPropertySets was a null pointer. - /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED All property values were invalid and no properties were set. The consumer checks dwStatus in the DBPROP - /// structures to determine why properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. - /// - /// - /// - /// - /// - /// DB_E_OBJECTOPEN Properties cannot be set while there is an open rowset. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711497(v=vs.85) HRESULT SetProperties ( ULONG cPropertySets, - // DBPROPSET rgPropertySets[]); - [PreserveSig] - HRESULT SetProperties(uint cPropertySets, [In] SafeDBPROPSETListHandle? rgPropertySets); - } - - /// - /// This interface is mandatory on commands. - /// - /// A command object can have only one text command. When the command text is specified through ICommandText::SetCommandText, it - /// replaces the existing command text. - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714914(v=vs.85) - [PInvokeData("")] - [ComImport, Guid("0c733a27-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ICommandText : ICommand - { - /// Cancels the current command execution. - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714402(v=vs.85) HRESULT Cancel(); - new void Cancel(); - - /// Executes the command. - /// - /// [in] A pointer to the controlling IUnknown interface if the rowset is being created as part of an aggregate; otherwise, it - /// is null. - /// - /// - /// - /// [in] The requested IID for the rowset returned in *ppRowset. This interface is conceptually added to the list of required - /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting - /// rowset. If the command has any open rowsets, requesting an interface that is not supported on those open rowsets will generally - /// return E_NOINTERFACE as it is not possible to change the properties supported on a command with open rowsets. In addition, - /// specifying the IID of a nonmandatory interface that has not been explicitly requested through rowset properties set on a prepared - /// command might reduce the provider's ability to optimize the command, because the provider might have to rebuild the access plan - /// to satisfy the additional interface. - /// - /// - /// If this is IID_NULL, ppRowset is ignored and no rowset is returned, even if the command would otherwise generate a rowset. - /// Specifying IID_NULL is useful in the case of text commands that do not generate rowsets, such as data definition commands, as a - /// hint to the provider that no rowset properties need to be verified. - /// - /// - /// If riid is IID_IMultipleResults, the provider creates a multiple results object and returns a pointer to it in *ppRowset; - /// it does this even if the command generates a single result. If the provider supports multiple results and the command generates - /// multiple results but riid is not IID_IMultipleResults, the provider returns the first result and discards any remaining - /// results. If riid is IID_IMultipleResults and the provider does not support multiple results, ICommand::Execute - /// returns E_NOINTERFACE. - /// - /// - /// - /// - /// [in/out] A pointer to a DBPARAMS structure that specifies the values for one or more parameters. In text commands that use - /// parameters, if no value is specified for a parameter through pParams, an error occurs. - /// - /// The elements of this structure are used as described in the following table. - /// - /// - /// Element - /// Description - /// - /// - /// pData - /// - /// Pointer to a buffer from which the provider retrieves input parameter data and to which the provider returns output parameter - /// data, according to the bindings specified by hAccessor. This pointer must be a valid pointer to a contiguous block of - /// consumer-owned memory for the input and output parameter values. For more information, see Getting Data and Setting Data. When - /// output parameter data is available to the consumer depends on the DBPROP_OUTPUTPARAMETERAVAILABILITY property. - /// - /// - /// - /// cParamSets - /// - /// The number of sets of parameters in * pData. If cParamSets is greater than one, the bindings described by - /// hAccessor define the offsets within * pData for each set of parameters and cbRowSize (as specified in - /// IAccessor::CreateAccessor) defines a single fixed offset between each of those values and the corresponding values for the - /// next set of parameters. Sets of multiple parameters ( cParamSets is greater than one) can be specified only if - /// DBPROP_MULTIPLEPARAMSETS is VARIANT_TRUE and the command does not return any rowsets. - /// - /// - /// - /// hAccessor - /// - /// Handle of the accessor to use. If hAccessor is the handle of a null accessor ( cBindings in - /// IAccessor::CreateAccessor was 0), ICommand::Execute does not retrieve or return any parameter values. - /// - /// - /// - /// - /// If the provider is able to determine the number of parameters in the command and the command text does not include parameters, - /// the provider ignores this argument. - /// - /// - /// - /// - /// [out] A pointer to memory in which to return the count of rows affected by a command that updates, deletes, or inserts rows. If - /// cParamSets is greater than one, *pcRowsAffected is the total number of rows affected by all of the sets of parameters specified - /// in the execution. If the number of affected rows is not available, *pcRowsAffected is set to DB_COUNTUNAVAILABLE on output. If - /// riid is IID_IMultipleResults, the value returned in *pcRowsAffected is either DB_COUNTUNAVAILABLE or the total number of - /// rows affected by the entire command; to retrieve individual row counts, the consumer calls IMultipleResults::GetResult. If - /// the command does not update, delete, or insert rows, *pcRowsAffected is undefined on output. If pcRowsAffected is a null pointer, - /// no count of rows is returned. - /// - /// - /// pcRowsAffected is undefined if ICommand::Execute returns DB_S_ASYNCHRONOUS. For asynchronously executed commands, the - /// consumer should call IDBAsynchStatus::GetStatus to obtain the number of rows affected in pulProgress. - /// - /// - /// - /// - /// [in/out] A pointer to the memory in which to return the rowset's pointer. If ppRowset is a null pointer, no rowset is created. - /// However, if the DBPROP_OUTPUTSTREAM property is set and the result of ICommand::Execute is a stream object, a null pointer - /// is an acceptable value. - /// - /// - /// If ppRowset is not a null pointer and an interface on a stream object was requested, the provider returns to *ppRowset the - /// interface pointer set in the DBPROP_OUTPUTSTREAM property. The consumer must release the interface pointer in *ppRowset when it - /// is no longer needed. - /// - /// If *ppRowset is a null pointer, the provider did not write any results to the stream specified in DBPROP_OUTPUTSTREAM. - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK; the status of all - /// input parameters bound by the accessor is set to DBSTATUS_S_OK or DBSTATUS_S_ISNULL; and the status of all output parameters - /// bound by the accessor is set to DBSTATUS_S_OK, DBSTATUS_S_ISNULL, or DBSTATUS_S_TRUNCATED ? or is unknown because the parameter - /// value has not been returned yet. - /// - /// - /// - /// - /// - /// - /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to - /// poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any - /// other interfaces may fail, and the full set of interfaces may not be available on the object until asynchronous initialization of - /// the rowset has completed. DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED This can be returned for any of the following reasons: - /// - /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see - /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. - /// - /// - /// DB_S_ERRORSOCCURRED should be returned before DB_S_NOTSINGLETON because the status values can be checked, and providers are not - /// required to return DB_S_NOTSINGLETON. - /// - /// - /// - /// - /// - /// - /// DB_S_NOTSINGLETON The provider supports returning row objects on ICommand::Execute, and the consumer requested a row - /// object but the result was not a singleton. A row object of the first row of the rowset is returned. Returning this result may be - /// expensive, so providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes - /// precedence over DB_S_NOTSINGLETON. - /// - /// - /// - /// - /// - /// - /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been - /// returned. Execution cannot be resumed. - /// - /// - /// Multiple sets of parameters were specified, and one or more (but not all) of the parameters have been processed prior to the - /// command being canceled by ICommand::Cancel or IDBAsynchStatus::Abort. - /// - /// - /// 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 riid was not IID_NULL, and ppRowset was a null pointer. Any streams used to pass input parameters are not released. - /// - /// - /// The parameter information was invalid. Parameter information may be invalid for any of the following reasons. In all cases, any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// E_NOINTERFACE The rowset did not support the interface specified in riid. - /// riid was IID_IMultipleResults, and the provider did not support multiple results objects. - /// - /// - /// - /// - /// - /// DB_E_ABORTLIMITREACHED Execution has been aborted because a resource limit has been reached. For example, a query timed out. No - /// results have been returned. - /// - /// - /// - /// - /// - /// - /// DB_E_BADACCESSORHANDLE pParams was not ignored, and hAccessor in the DBPARAMS structure pointed to by pParams was invalid. Any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// - /// DB_E_BADACCESSORTYPE hAccessor in the DBPARAMS structure pointed to by pParams was not the handle of a parameter accessor. Any - /// streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// DB_E_CANCELED The command was canceled by a call to ICommand::Cancel on another thread. No records were affected. - /// - /// - /// - /// - /// - /// DB_E_CANTCONVERTVALUE A literal value in the command text could not be converted to the type of the associated column for reasons - /// other than data overflow. - /// - /// - /// - /// - /// - /// DB_E_DATAOVERFLOW A literal value in the command text overflowed the type specified by the associated column. - /// - /// - /// - /// - /// - /// DB_E_ERRORSINCOMMAND The command text contained one or more errors. Providers should use OLE DB error objects to return details - /// about the errors. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED The method failed due to one or more nonvalid input parameter values. To determine which input parameter - /// values were not valid, 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.) If any streams were used to pass input parameters, only those with the - /// status value equal to DBSTATUS_S_OK on input are released; otherwise, no attempt is made to release the stream. If the consumer - /// provides storage objects for additional bound parameters that are not used by the current command, it is a consumer programming - /// error and the provider does not attempt to release these parameters. - /// - /// - /// The command was not executed, and no rowset was returned because one or more properties ? for which the dwOptions element of the - /// DBPROP structure was DBPROPOPTIONS_REQUIRED ? were not set. - /// - /// Multiple parameter sets were passed with a command that returns a rowset. (Some providers might not return this error.) - /// - /// - /// - /// - /// DB_E_INTEGRITYVIOLATION A literal value in the command text violated the integrity constraints for the column. - /// - /// - /// - /// - /// - /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support - /// aggregation of the rowset object being created. Any streams used to pass input parameters are not released. - /// - /// - /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. Any streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was currently set on the command object. Any streams used to pass input parameters are not released. - /// - /// - /// - /// - /// - /// DB_E_NOTABLE The specific table or view does not exist in the data store. - /// - /// - /// - /// - /// - /// DB_E_NOTFOUND The provider supports row objects, a row was requested via riid or DBPROP_IRow, and no rows satisfied the selection - /// criteria of the command. - /// - /// - /// - /// - /// - /// DB_E_PARAMNOTOPTIONAL A value was not supplied for a required parameter. - /// The command text used parameters and pParams was a null pointer. - /// - /// - /// - /// - /// - /// DB_E_PARAMUNAVAILABLE Provider cannot derive parameter information, and ICommandWithParameters::SetParameterInfo has not - /// been called. - /// - /// - /// - /// - /// - /// - /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to execute the command. For example, a rowset-returning - /// command specified a column for which the consumer does not have read permission, or an update command specified a column for - /// which the consumer does not have write permission. - /// - /// - /// - /// - /// - /// - /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set - /// to VARIANT_FALSE. Any streams used to pass input parameters are not released. - /// - /// - /// If a session is enlisted in a global transaction and a command requires the creation of an additional connection, the provider - /// should return DB_E_OBJECTOPEN. Providers written prior to OLE DB 2.6 may return E_FAIL. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718095(v=vs.85) HRESULT Execute ( IUnknown *pUnkOuter, - // REFIID riid, DBPARAMS *pParams, DBROWCOUNT *pcRowsAffected, IUnknown **ppRowset); - [PreserveSig] - new HRESULT Execute([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [In, Out, Optional] DBPARAMS? pParams, - out DBROWCOUNT pcRowsAffected, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); - - /// Returns an interface pointer to the session that created the command. - /// [in] The IID of the interface on which to return a pointer. - /// - /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the - /// command, it sets *ppSession to a null pointer. If ICommand::GetDBSession fails, it must attempt to set *ppSession to a - /// null pointer. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// S_FALSE The provider did not have an object that created the command. Therefore, it set *ppSession to a null pointer. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG ppSession was a null pointer. - /// - /// - /// - /// - /// E_NOINTERFACE The session did not support the interface specified in riid. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719622(v=vs.85) HRESULT GetDBSession ( REFIID riid, IUnknown **ppSession); - [PreserveSig] - new HRESULT GetDBSession(in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppSession); - - /// Returns the text command set by the last call to ICommandText::SetCommandText. - /// - /// - /// [in/out] A pointer to memory containing a GUID that specifies the syntax and general rules for parsing the command text ? that - /// is, the dialect that will be used by the provider to interpret the statement. This is usually the dialect specified in ICommandText::SetCommandText. - /// - /// - /// However, if DBGUID_DEFAULT is specified in SetCommandText, the provider returns the particular dialect that it will use to - /// interpret the statement. If the provider must choose between multiple dialects at execution time for a command that has been set - /// with DBGUID_DEFAULT or if the provider is returning some provider-specific syntax that may be different from the command set in - /// ICommandText::SetCommandText, it returns DBGUID_DEFAULT. Providers can define GUIDs for their own dialects. - /// - /// If pguidDialect is a null pointer on input, the provider does not return the dialect. - /// If ICommandText::GetCommandText returns an error, *pguidDialect is set to DB_NULLGUID. - /// For more information about dialects, see Using Commands. - /// - /// - /// [out] A pointer to memory in which to return the command text. The command object allocates memory for the command text and - /// returns the address to this memory. The consumer releases this memory with IMalloc::Free when it no longer needs the text. - /// If ICommandText::GetCommandText returns an error, *ppwszCommand is set to a null pointer. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// - /// DB_S_DIALECTIGNORED The method succeeded, but the input value of pguidDialect was ignored. The text is returned in the dialect - /// specified in ICommandText::SetCommandText or in the dialect that makes the most sense to the provider. The value returned - /// in *pguidDialect represents that dialect. - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG ppwszCommand was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the command text. - /// - /// - /// - /// - /// DB_E_CANTTRANSLATE The last command was set using ICommandStream::SetCommandStream, not ICommandText::SetCommandText. - /// - /// - /// - /// - /// DB_E_NOCOMMAND No command text was currently set on the command object. - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709825(v=vs.85) HRESULT GetCommandText ( GUID *pguidDialect, - // LPOLESTR *ppwszCommand); - [PreserveSig] - HRESULT GetCommandText([In, Out, Optional] ref Guid pguidDialect, out string ppwszCommand); - - /// Sets the command text, replacing the existing command text. - /// - /// [in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. For a complete - /// description of dialects, see GetCommandText. - /// - /// - /// [in] A pointer to the text of the command. - /// - /// If *pwszCommand is an empty string ("") or pwszCommand is a null pointer, the current command text (and command stream object, if - /// it exists) is cleared and the command is put in an initial state. Any properties that have been set on the command are - /// unaffected; that is, they retain their current values. Methods that require a command, such as ICommand::Execute, - /// ICommandPrepare::Prepare, or IColumnsInfo::GetColumnInfo, will return DB_E_NOCOMMAND until a new command text is set. - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// DB_E_DIALECTNOTSUPPORTED The provider did not support the dialect specified in rguidDialect. - /// - /// - /// - /// - /// DB_E_OBJECTOPEN A rowset was open on the command. - /// - /// - /// - /// - /// - /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and the command text specified a FROM SCOPE= - /// clause with an unsafe URL. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709757(v=vs.85) HRESULT SetCommandText ( REFGUID - // rguidDialect, LPCOLESTR pwszCommand); - [PreserveSig] - HRESULT SetCommandText(in Guid rguidDialect, [In, Optional, MarshalAs(UnmanagedType.LPWStr)] string? pwszCommand); + /// The consumer explicitly requests a row object. + DBRESULTFLAG_ROW = 2 } /// @@ -2395,6 +596,410 @@ public static partial class OleDb out DBASYNCHPHASE peAsynchPhase, [In, Out, Optional, MarshalAs(UnmanagedType.LPWStr)] ref StringBuilder? ppwszStatusText); } + /// IDBBinderProperties allows a consumer to get, set, and reset direct binding properties. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720917(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733ab3-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDBBinderProperties : IDBProperties + { + /// + /// Returns the values of properties in the Data Source, Data Source Information, and Initialization property groups that are + /// currently set on the data source object, or returns the values of properties in the Initialization property group that are + /// currently set on the enumerator. + /// + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets. If the data source object or enumerator is in an uninitialized + /// state, the provider returns the values of all properties in the Initialization property group for which values have been set or + /// defaults exist. This should include any provider-specific properties belonging to this group. If the data source object or + /// enumerator is in an initialized state, the provider returns the values of all properties in the Data Source, Data Source + /// Information, and Initialization property groups (for data source objects) or just in the Initialization property group (for + /// enumerators), for which values have been set or defaults exist. The provider does not return the values of properties in any of + /// these property groups for which values have not been set and no defaults exist. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported or if + /// the data source object or enumerator is not initialized and the value of a property in a group other than the Initialization + /// property group is requested, the returned value of dwStatus in the returned DBPROP structure for that property is + /// DBPROPSTATUS_NOTSUPPORTED and the value of dwOptions is undefined. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. If the data source object or enumerator has not been initialized, the + /// properties specified in these structures must belong to the Initialization property group. If the data source object or + /// enumerator has been initialized, the properties specified in these structures must belong to the Data Source, Data Source + /// Information, or Initialization property group, for data source objects, or to the Initialization property group, for enumerators. + /// The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this argument is ignored. + /// + /// + /// For information about the properties in the Data Source, Data Source Information, and Initialization property groups that are + /// defined by OLE DB, see Data Source Property Group, Data Source Information Property Group, and Initialization Properties in + /// Appendix C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets + /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Data + /// Source, Data Source Information, or Initialization property group, for data source objects, or in the Initialization property + /// group, for enumerators. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other + /// than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property belonging to the Initialization property group (if the data + /// source object or enumerator is not initialized), the Data Source, Data Source Information, or Initialization property group (if + /// the data source object is initialized), or to the Initialization property group (if the enumerator is initialized). If + /// cPropertyIDSets is not zero, one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// In the case of properties in the Initialization property group and for a previously persisted data source object, those + /// properties related to sensitive authentication information such as password will be returned in an encrypted form if + /// DBPROP_AUTH_PERSIST_ENCRYPTED is VARIANT_TRUE. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of + /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of + /// each array, the property IDs are the same. + /// + /// + /// 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 *pcPropertySets is zero on output or an error other than + /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. For property sets other than DBPROPSET_PROPERTIESINERROR, dwStatus is set to DBPROPSTATUS_OK in all + /// DBPROP structures returned. If the requested property set is DBPROPSET_PROPERTIESINERROR, dwStatus reflects the individual error + /// for each DBPROP structure returned from the method. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. IDBProperties::GetProperties can fail to return properties for a + /// number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero or rgPropertyIDs + /// was not a null pointer. + /// + /// cPropertyIDSets was greater than 1, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the + /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory + /// when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714344(v=vs.85) HRESULT GetProperties ( ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); + [PreserveSig] + new HRESULT GetProperties(uint cPropertyIDSets, [In, Optional] SafeDBPROPIDSETListHandle rgPropertyIDSets, + out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); + + /// Returns information about all properties supported by the provider. + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets. When called on the enumerator, the provider returns + /// information about all properties in the Initialization property group. When called on the data source object, if the data source + /// object is in an uninitialized state, the provider returns information about all properties in the Initialization property group. + /// This should include any provider-specific properties belonging to this group. If the data source object is in an initialized + /// state, the provider returns information about all of the properties in all of the property sets it supports. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns information about the requested properties. If a property is not supported + /// or if the method is called on an enumerator or an uninitialized data source object and the value of a property in a group other + /// than the Initialization property group is requested, the returned value of dwStatus in the returned DBPROPINFO structure for that + /// property is DBPROPFLAGS_NOTSUPPORTED and the values of the pwszDescription, vtType, and vValues elements are undefined. For + /// information about the DBPROPINFO structure, see DBPROPINFO Structure. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. When called on the enumerator, the properties specified in these + /// structures must belong to the Initialization property group. When called on the data source object, if the data source object has + /// not been initialized, the properties must belong to the Initialization property group. If the data source object has been + /// initialized, the properties can belong to any property group. The provider returns information about the properties specified in + /// these structures. If cPropertyIDSets is zero, this parameter is ignored. For information about the DBPROPIDSET structure, see + /// DBPROPIDSET Structure. + /// + /// + /// The following special GUIDs are defined for use with IDBProperties::GetPropertyInfo. All of these GUIDs can be used on + /// data source objects; only the DBPROPSET_DBINITALL GUID can be used on enumerators. If any of these GUIDs are specified in the + /// guidPropertySet element of a DBPROPIDSET structure, the cPropertyIDs and rgPropertyIDs elements of that structure are ignored. + /// However, the consumer should set these to zero and a null pointer, respectively, because the provider might attempt to verify + /// that they are valid values. Consumers cannot pass special GUIDs and the GUIDs of other property sets in the same call to + /// IDBProperties::GetPropertyInfo. That is, if one element of rgPropertyIDSets contains a special GUID, all elements of + /// rgPropertyIDSets must contain special GUIDs. These GUIDs are not returned in the guidPropertySet element of the DBPROPINFOSET + /// structures returned in prgPropertyInfoSets. Instead, the GUID of the property set to which the property belongs is returned. + /// + /// + /// + /// Property set GUID + /// Description + /// + /// + /// DBPROPSET_COLUMNALL + /// Returns all properties in the Column property group, including provider-specific properties. + /// + /// + /// DBPROPSET_CONSTRAINTALL + /// Returns all properties in the Constraint property group, including provider-specific properties. + /// + /// + /// DBPROPSET_DATASOURCEALL + /// Returns all properties in the Data Source property group, including provider-specific properties. + /// + /// + /// DBPROPSET_DATASOURCEINFOALL + /// Returns all properties in the Data Source Information property group, including provider-specific properties. + /// + /// + /// DBPROPSET_DBINITALL + /// Returns all properties in the Initialization property group, including provider-specific properties. + /// + /// + /// DBPROPSET_INDEXALL + /// Returns all properties in the Index property group, including provider-specific properties. + /// + /// + /// DBPROPSET_ROWSETALL + /// Returns all properties in the Rowset property group, including provider-specific properties. + /// + /// + /// DBPROPSET_SESSIONALL + /// Returns all properties in the Session property group, including provider-specific properties. + /// + /// + /// DBPROPSET_STREAMALL + /// Returns all properties of the Stream property group, including provider-specific properties. + /// + /// + /// DBPROPSET_TABLEALL + /// Returns all properties in the Table property group, including provider-specific properties. + /// + /// + /// DBPROPSET_TRUSTEEALL + /// Returns all properties in the Trustee property group, including provider-specific properties. + /// + /// + /// DBPROPSET_VIEWALL + /// Returns all properties in the View property group, including provider-specific properties. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPINFOSET structures returned in *prgPropertyInfoSets. If + /// cPropertyIDSets is zero, *pcPropertyInfoSets is the total number of property sets for which the provider supports at least one + /// property. If *pcPropertyInfoSets is not zero and one of the special GUIDs listed in rgPropertyIDSets was used, + /// *pcPropertyInfoSets may differ from cPropertyIDSets. If an error other than DB_E_ERRORSOCCURRED occurs, *pcPropertyInfoSets is + /// set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPINFOSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property supported by the provider. If cPropertyIDSets is not zero, one + /// structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPINFOSET structures in *prgPropertyInfoSets are returned in the same order as the + /// DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are + /// the same. If cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROPINFO structures in the corresponding element + /// of *prgPropertyInfoSets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding + /// elements of each array, the property IDs are the same. The only exception to these rules is when one of the special GUIDs listed + /// in rgPropertyIDSets was used. In this case, the order of the property information returned may differ from the order specified in rgPropertyIDSets. + /// + /// + /// 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 *prgPropertyInfoSets, the + /// consumer should call IMalloc::Free for the rgPropertyInfos element within each element of *prgPropertyInfoSets. 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 *pcPropertyInfoSets is zero on output or if an error other + /// than DB_E_ERRORSOCCURRED occurs, *prgPropertyInfoSets must be a null pointer on output. + /// + /// For information about the DBPROPINFOSET and DBPROPINFO structures, see DBPROPINFOSET Structure and DBPROPINFO Structure. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values returned in the pwszDescription element + /// of the DBPROPINFO structure. The provider allocates this memory with IMalloc, and the consumer frees it with + /// IMalloc::Free when it no longer needs the property descriptions. If ppDescBuffer is a null pointer on input, + /// IDBProperties::GetPropertyInfo does not return the property descriptions. If *pcPropertyInfoSets is zero on output or if + /// an error occurs, the provider does not allocate any memory and ensures that *ppDescBuffer is a null pointer on output. Each of + /// the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer may + /// contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROPINFO structures returned by the method, dwFlags is set to a value other than DBPROPFLAGS_NOTSUPPORTED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED Information was successfully returned for at least one property. However, one of the following errors occurred: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcPropertyInfoSets or prgPropertyInfoSets was a null pointer. + /// cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// In one element of rgPropertyIDSets, guidPropertySet specified one of the special GUIDs listed in the description of + /// rgPropertyIDSets. In a different element of rgPropertyIDSets, guidPropertySet specified the GUID of a normal property set. + /// + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPINFOSET or DBPROPINFO structures + /// or the property descriptions. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Errors occurred while attempting to return information about all properties. No property information was + /// returned. The provider allocates memory for *prgPropertyInfoSets, and the consumer checks dwFlags in the DBPROPINFO structures to + /// determine why information about each property was not returned. The consumer frees this memory when it no longer needs the + /// information. The method can fail to return information about properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718175(v=vs.85) HRESULT GetPropertyInfo( ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertyInfoSets, DBPROPINFOSET **prgPropertyInfoSets, OLECHAR **ppDescBuffer); + [PreserveSig] + new HRESULT GetPropertyInfo(uint cPropertyIDSets, [In, Optional] SafeDBPROPIDSETListHandle rgPropertyIDSets, + out uint pcPropertyInfoSets, out SafeIMallocHandle prgPropertyInfoSets, out SafeIMallocHandle ppDescBuffer); + + /// + /// Sets properties in the Data Source and Initialization property groups, for data source objects, or in the Initialization property + /// group, for enumerators. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method + /// does not do anything except return S_OK. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. If the data source object or enumerator is + /// uninitialized, the properties specified in these structures must belong to the Initialization property group. If the data source + /// object is initialized, the properties must belong to the Data Source property group. If the enumerator is initialized, it is an + /// error to call this method. If the same property is specified more than once in rgPropertySets, the value used is + /// provider-specific. If cPropertySets is zero, this parameter is ignored. + /// + /// + /// For information about the properties in the Data Source and Initialization property groups that are defined by OLE DB, see Data + /// Source Property Group and Initialization Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, + /// see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the + /// DBPROP structures to determine which properties were not set. IDBProperties::SetProperties can fail to set properties for + /// a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertySets was not equal to zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_ALREADYINITIALIZED The method was called on the enumerator, and the enumerator was already initialized. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All property values were invalid and no properties were set. The consumer checks dwStatus in the DBPROP + /// structures to determine why properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723049(v=vs.85) HRESULT SetProperties ( ULONG cPropertySets, + // DBPROPSET rgPropertySets[]); + [PreserveSig] + new HRESULT SetProperties(uint cPropertySets, [In, Out] SafeDBPROPSETListHandle? rgPropertySets); + + /// + /// Clears any properties set on a binder object. If the binder object has any properties with defaults, Reset returns them to + /// their default values. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723076(v=vs.85) HRESULT Reset(); + void Reset(); + } + /// Consumers call IDBCreateCommand::CreateCommand on a session to obtain a new command. // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711625(v=vs.85) [PInvokeData("oledb.h")] @@ -2545,6 +1150,895 @@ public static partial class OleDb HRESULT CreateSession([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppDBSession); } + /// + /// IDBDataSourceAdmin is an optional interface for creating, destroying, and modifying data stores. + /// + /// It is important to distinguish between the data store and the data source object. The data store is the actual source of data, such + /// as a server database, a file in a directory, or an e-mail system. The data source object is the object that represents, and is used + /// by the consumer code to interact with, the data store. + /// + /// + /// The methods in this interface are intended to affect a data store, although OLE DB objects, such as the data source object, may + /// incidentally be affected as well. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722667(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a7a-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDBDataSourceAdmin + { + /// Creates and initializes a new data store. + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method + /// does not do anything. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Data Source Creation or Initialization property groups; Initialization properties must be supported + /// by the provider for use in data store creation. If the same property is specified more than once in rgPropertySets, the value + /// used is provider-specific. If a provider cannot support a property, the property is ignored. If cPropertySets is zero, this + /// argument is ignored. + /// + /// + /// The properties specified in these structures must belong to the Data Source Creation, Initialization property or Session Property + /// group. If one of these groups is specified and ppSession is not specified, the session properties are ignored + /// + /// + /// For information about the properties in the Data Source Creation and Initialization property groups that are defined by OLE DB, + /// see Data Source Creation Property Group, Initialization Property Group, and Session Property Group in Appendix C. For information + /// about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [in] A pointer to the controlling IUnknown interface if a session is desired and is to be created as part of an aggregate. + /// Otherwise, it is a null pointer. + /// + /// [in] The requested interface for the session returned in *ppSession. Ignored if ppSession is a null pointer. + /// + /// [in/out] A pointer to memory in which to return the pointer to the session. If ppSession is a null pointer, no session is created. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The new data store was created, but one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which + /// properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The session did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory to create the new data store. + /// + /// + /// + /// + /// + /// DB_E_ALREADYINITIALIZED IDBInitialize::Initialize had already been called for the data source object, and an intervening + /// call to IDBInitialize::Uninitialize had not been made. + /// + /// + /// + /// + /// + /// + /// DB_E_CANCELED The provider prompted the user for additional information, and the user selected Cancel. A data store was not + /// created and the data source was not initialized. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATEDATASOURCE A data store with the same name already exists. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The data store was not created because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties + /// for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the data source object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_SEC_E_AUTH_FAILED The provider required initialization, but an authentication failed. The data store was not created. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have permission to create a new data store. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725438(v=vs.85) HRESULT CreateDataSource( ULONG + // cPropertySets, DBPROPSET rgPropertySets[], IUnknown *pUnkOuter, REFIID riid, IUnknown **ppSession); + [PreserveSig] + HRESULT CreateDataSource(uint cPropertySets, [In, Out] SafeDBPROPSETListHandle rgPropertySets, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, + in Guid riid, [Optional, MarshalAs(UnmanagedType.IUnknown)] out object? ppDBSession); + + /// Destroys the current data store. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_UNEXPECTED The data source object was in an uninitialized state. + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support this method. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have permission to destroy the current data store. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725446(v=vs.85) HRESULT DestroyDataSource (); + [PreserveSig] + HRESULT DestroyDataSource(); + + /// Returns information about the data store creation properties that are supported by the data provider. + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns information about all of the properties in the Data + /// Source Creation property group it supports and about all of the properties in the Initialization property group it supports for + /// use in creating data stores. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns information about the requested properties. If a property is not supported + /// or if a property in the Initialization property group cannot be used to create data stores, the returned value of dwStatus in the + /// returned DBPROPINFO structure for that property is DBPROPFLAGS_NOTSUPPORTED and the values of the pwszDescription, vtType, and + /// vValues elements are undefined. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Data + /// Source Creation property group or belong to the Initialization property group and be supported for use in creating data stores. + /// The provider returns information about the properties specified in these structures. If cPropertyIDSets is zero, this parameter + /// is ignored. + /// + /// + /// For information about the properties in the Data Source Creation and Initialization property groups that are defined by OLE DB, + /// see Data Source Creation Property Group, Initialization Property Group, and Session Property Group in Appendix C. For information + /// about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPINFOSET structures returned in *prgPropertyInfoSets. If + /// cPropertyIDSets is zero, *pcPropertyInfoSets is the total number of property sets for which the provider supports at least one + /// property in the Data Source Creation or Initialization property group. If cPropertyIDSets is greater than zero, + /// *pcPropertyInfoSets is set to cPropertyIDSets. If an error occurs, *pcPropertyInfoSets is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPINFOSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property belonging to the Data Source Creation or Initialization + /// property group. If cPropertyIDSets is not zero, one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPINFOSET structures in *prgPropertyInfoSets are returned in the same order as the + /// DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are + /// the same. If cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROPINFO structures in the corresponding element + /// of *prgPropertyInfoSets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding + /// elements of each array, the property IDs are the same. + /// + /// + /// 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 *prgPropertyInfoSets, the + /// consumer should call IMalloc::Free for the rgPropertyInfos element in each element of *prgPropertyInfoSets. If + /// *pcPropertyInfoSets is zero on output or an error occurs, *prgPropertyInfoSets must be a null pointer on output. + /// + /// For information about the DBPROPINFOSET and DBPROPINFO structures, see DBPROPINFOSET Structure and DBPROPINFO Structure. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values returned in the pwszDescription element + /// of the DBPROPINFO structure. The provider allocates this memory with IMalloc, and the consumer frees it with + /// IMalloc::Free when it no longer needs the property descriptions. If ppDescBuffer is a null pointer on input, + /// IDBDataSourceAdmin::GetCreationProperties does not return the property descriptions. If *pcPropertyInfoSets is zero on + /// output or an error occurs, the provider does not allocate any memory and ensures that *ppDescBuffer is a null pointer on output. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROPINFO structures returned by the method, dwFlags is set to a value other than DBPROPFLAGS_NOTSUPPORTED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED One or more properties specified in rgPropertyIDSets were not supported by the provider. The dwFlags element + /// of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED. + /// + /// + /// One or more properties specified in rgPropertyIDSets were not in the Data Source Creation or Initialization property group. The + /// dwFlags element of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED. + /// + /// + /// One or more properties specified in rgPropertyIDSets were in the Initialization property group but could not be used to create + /// data stores. The dwFlags element of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED. + /// + /// + /// One or more property sets specified in rgPropertyIDSets were not supported by the provider. The dwFlags element of the DBPROPINFO + /// structure for all specified properties in these sets is set to DBPROPFLAGS_NOTSUPPORTED. If cPropertyIDs in the DBPROPIDSET + /// structure for the property set was zero, the provider cannot set dwStatus in the DBPROP structure because it does not know the + /// IDs of any properties in the property set. Instead, it sets cProperties to zero in the DBPROPSET structure returned for the + /// property set. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcPropertyInfoSets or prgPropertyInfoSets was a null pointer. + /// cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPINFOSET or DBPROPINFO structures + /// or the property descriptions. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the + /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory + /// when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712991(v=vs.85) HRESULT GetCreationProperties ( ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertyInfoSets, DBPROPINFOSET **prgPropertyInfoSets, OLECHAR **ppDescBuffer); + HRESULT GetCreationProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, out uint pcPropertyInfoSets, + out SafeDBPROPINFOSETListHandle prgPropertyInfoSets, out SafeIMallocHandle ppDescBuffer); + + /// Modifies the current data store. + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The data store was modified, but one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which + /// properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED The data source object was in an uninitialized state. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The data store was not modified because one or more properties ? for which the dwOptions element of the + /// DBPROP structure was DBPROPOPTIONS_REQUIRED ? were not set. The consumer checks dwStatus in the DBPROP structures to determine + /// which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for a + /// number of reasons, including the following: + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support this method. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have permission to modify the current data store. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712958(v=vs.85) HRESULT ModifyDataSource ( ULONG + // cPropertySets, DBPROPSET rgPropertySets[]); + HRESULT ModifyDataSource(uint cPropertySets, [In, Out] SafeDBPROPSETListHandle rgPropertySets); + } + + /// + /// + /// IDBInfo returns information about the keywords and literals a provider supports. It is an optional interface on the data + /// source objects. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713663(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a89-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IDBInfo + { + /// Returns a list of provider-specific keywords. + /// + /// + /// [out] A pointer to memory in which to return the address of a string. The string contains a comma-separated list of all keywords + /// unique to this provider ? that is, a comma-separated list of keywords that are not in the list in the Comments section. If there + /// are no keywords unique to this provider or if an error occurs, the provider sets *ppwszKeywords to a null pointer. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppwszKeywords was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the keywords. + /// + /// + /// + /// + /// E_UNEXPECTED The data source object was in an uninitialized state. + /// + /// + /// + /// Comments + /// The following is a list of the keywords from OLE DB: + /// + /// + /// ABSOLUTE + /// ESCAPE + /// OUTPUT + /// + /// + /// ACTION + /// EXCEPT + /// OVERLAPS + /// + /// + /// ADD + /// EXCEPTION + /// PARTIAL + /// + /// + /// ALL + /// EXEC + /// POSITION + /// + /// + /// ALLOCATE + /// EXECUTE + /// PRECISION + /// + /// + /// ALTER + /// EXISTS + /// PREPARE + /// + /// + /// AND + /// EXTERNAL + /// PRESERVE + /// + /// + /// ANY + /// EXTRACT + /// PRIMARY + /// + /// + /// ARE + /// FALSE + /// PRIOR + /// + /// + /// AS + /// FETCH + /// PRIVILEGES + /// + /// + /// ASC + /// FIRST + /// PROCEDURE + /// + /// + /// ASSERTION + /// FLOAT + /// PUBLIC + /// + /// + /// AT + /// FOR + /// READ + /// + /// + /// AUTHORIZATION + /// FOREIGN + /// REAL + /// + /// + /// AVG + /// FOUND + /// REFERENCES + /// + /// + /// BEGIN + /// FROM + /// RELATIVE + /// + /// + /// BETWEEN + /// FULL + /// RESTRICT + /// + /// + /// BIT + /// GET + /// REVOKE + /// + /// + /// BIT_LENGTH + /// GLOBAL + /// RIGHT + /// + /// + /// BOTH + /// GO + /// ROLLBACK + /// + /// + /// BY + /// GOTO + /// ROWS + /// + /// + /// CASCADE + /// GRANT + /// SCHEMA + /// + /// + /// CASCADED + /// GROUP + /// SCROLL + /// + /// + /// CASE + /// HAVING + /// SECOND + /// + /// + /// CAST + /// HOUR + /// SECTION + /// + /// + /// CATALOG + /// IDENTITY + /// SELECT + /// + /// + /// CHAR + /// IMMEDIATE + /// SESSION + /// + /// + /// CHAR_LENGTH + /// IN + /// SESSION_USER + /// + /// + /// CHARACTER + /// INDICATOR + /// SET + /// + /// + /// CHARACTER_LENGTH + /// INITIALLY + /// SIZE + /// + /// + /// CHECK + /// INNER + /// SMALLINT + /// + /// + /// CLOSE + /// INPUT + /// SOME + /// + /// + /// COALESCE + /// INSENSITIVE + /// SQL + /// + /// + /// COLLATE + /// INSERT + /// SQLCODE + /// + /// + /// COLLATION + /// INT + /// SQLERROR + /// + /// + /// COLUMN + /// INTEGER + /// SQLSTATE + /// + /// + /// COMMIT + /// INTERSECT + /// SUBSTRING + /// + /// + /// CONNECT + /// INTERVAL + /// SUM + /// + /// + /// CONNECTION + /// INTO + /// SYSTEM_USER + /// + /// + /// CONSTRAINT + /// IS + /// TABLE + /// + /// + /// CONSTRAINTS + /// ISOLATION + /// TEMPORARY + /// + /// + /// CONTINUE + /// JOIN + /// THEN + /// + /// + /// CONVERT + /// KEY + /// TIME + /// + /// + /// CORRESPONDING + /// LANGUAGE + /// TIMESTAMP + /// + /// + /// COUNT + /// LAST + /// TIMEZONE_HOUR + /// + /// + /// CREATE + /// LEADING + /// TIMEZONE_MINUTE + /// + /// + /// CROSS + /// LEFT + /// TO + /// + /// + /// CURRENT + /// LEVEL + /// TRAILING + /// + /// + /// CURRENT_DATE + /// LIKE + /// TRANSACTION + /// + /// + /// CURRENT_TIME + /// LOCAL + /// TRANSLATE + /// + /// + /// CURRENT_TIMESTAMP + /// LOWER + /// TRANSLATION + /// + /// + /// CURRENT_USER + /// MATCH + /// TRIGGER + /// + /// + /// CURSOR + /// MAX + /// TRIM + /// + /// + /// DATE + /// MIN + /// TRUE + /// + /// + /// DAY + /// MINUTE + /// UNION + /// + /// + /// DEALLOCATE + /// MODULE + /// UNIQUE + /// + /// + /// DEC + /// MONTH + /// UNKNOWN + /// + /// + /// DECIMAL + /// NAMES + /// UPDATE + /// + /// + /// DECLARE + /// NATIONAL + /// UPPER + /// + /// + /// DEFAULT + /// NATURAL + /// USAGE + /// + /// + /// DEFERRABLE + /// NCHAR + /// USER + /// + /// + /// DEFERRED + /// NEXT + /// USING + /// + /// + /// DELETE + /// NO + /// VALUE + /// + /// + /// DESC + /// NOT + /// VALUES + /// + /// + /// DESCRIBE + /// NULL + /// VARCHAR + /// + /// + /// DESCRIPTOR + /// NULLIF + /// VARYING + /// + /// + /// DIAGNOSTICS + /// NUMERIC + /// VIEW + /// + /// + /// DISCONNECT + /// OCTET_LENGTH + /// WHEN + /// + /// + /// DISTINCT + /// OF + /// WHENEVER + /// + /// + /// DISTINCTROW + /// ON + /// WHERE + /// + /// + /// DOMAIN + /// ONLY + /// WITH + /// + /// + /// DOUBLE + /// OPEN + /// WORK + /// + /// + /// DROP + /// OPTION + /// WRITE + /// + /// + /// ELSE + /// OR + /// YEAR + /// + /// + /// END + /// ORDER + /// ZONE + /// + /// + /// END-EXEC + /// OUTER + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712923(v=vs.85) HRESULT GetKeywords( LPOLESTR *ppwszKeywords); + [return: MarshalAs(UnmanagedType.LPWStr)] + string GetKeywords(); + + /// + /// Returns information about literals used in text commands, ITableDefinition, IIndexDefinition, and + /// IOpenRowset, or any interface that takes DBIDs as arguments. + /// + /// + /// [in] The number of literals being asked about. If this is 0, the provider ignores rgLiterals and returns information about all + /// the literals it supports. + /// + /// + /// + /// [in] An array of cLiterals literals about which to return information. If the consumer specifies an invalid DBLITERAL value in + /// this array, IDBInfo::GetLiteralInfo returns FALSE in fSupported in the corresponding element of the *prgLiteralInfo array. + /// + /// If cLiterals is 0, this parameter is ignored. + /// + /// + /// [out] A pointer to memory in which to return the number of literals for which information was returned. If cLiterals is 0, this + /// is the total number of literals supported by the provider. If an error other than DB_E_ERRORSOCCURRED occurs, *pcLiteralInfo is + /// set to 0. + /// + /// + /// [out] A pointer to memory in which to return a pointer to an array of DBLITERALINFO structures. One structure is returned for + /// each literal. 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 *pcLiteralInfo is 0 on output or if an error other + /// than DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgLiteralInfo is a null pointer on + /// output. For information about DBLITERALINFO structures, see the Comments section. + /// + /// + /// [out] A pointer to memory in which to return a pointer for all string values (pwszLiteralValue, pwszInvalidChars, and + /// pwszInvalidStartingChars) within a single allocation block. The provider allocates this memory, and the consumer releases it with + /// IMalloc::Free when it no longer needs it. If *pcLiteralInfo is 0 on output or an error occurs, + /// the provider does not allocate any memory and ensures that *ppCharBuffer is a null pointer on output. + /// Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer + /// may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In each structure returned in *prgLiteralInfo, the fSupported element is set to TRUE. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED rgLiterals contained at least one unsupported or invalid literal. In the structures returned in + /// *prgLiteralInfo for unsupported or invalid literals, the fSupported element is set to FALSE. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cLiterals was not equal to zero, and rgLiterals was a null pointer. + /// pcLiteralInfo, prgLiteralInfo, or ppCharBuffer was a null pointer. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBLITERALINFO structures or the + /// strings containing the valid and starting characters. + /// + /// + /// + /// + /// + /// E_UNEXPECTED The data source object was in an uninitialized state. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All literals were either invalid or unsupported. The provider allocates memory for *prgLiteralInfo and sets + /// the value of the fSupported element in all of the structures to FALSE. The consumer frees this memory when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712896(v=vs.85) HRESULT GetLiteralInfo( ULONG cLiterals, + // const DBLITERAL rgLiterals[], ULONG *pcLiteralInfo, DBLITERALINFO **prgLiteralInfo, OLECHAR **ppCharBuffer); + HRESULT GetLiteralInfo(uint cLiterals, [In, MarshalAs(UnmanagedType.LPArray)] DBLITERAL[] rgLiterals, out uint pcLiteralInfo, + out SafeIMallocHandle prgLiteralInfo, out SafeIMallocHandle ppCharBuffer); + } + /// /// IDBInitialize is used to initialize and uninitialize data source objects and enumerators. It is a mandatory interface on data source /// objects and an optional interface on enumerators. @@ -3626,6 +3120,26 @@ public static partial class OleDb uint GetRecordCount(); } + /// + /// This is a mandatory interface on the session for obtaining an interface pointer to the data source object. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709721(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a75-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IGetDataSource + { + /// Returns an interface pointer on the data source object that created the session. + /// [in] The IID of the interface on which to return a pointer. + /// + /// A pointer to memory in which to return the interface pointer. If IGetDataSource::GetDataSource fails, it must attempt to + /// set *ppDataSource to a null pointer. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725443(v=vs.85) HRESULT GetDataSource ( REFIID riid, + // IUnknown **ppDataSource); + [return: MarshalAs(UnmanagedType.IUnknown)] + object? GetDataSource(in Guid riid); + } + /// Consumers use the IGetRow interface to get a row object or URL for a row in a rowset. // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718047(v=vs.85) [PInvokeData("oledb.h")] @@ -3745,6 +3259,492 @@ public static partial class OleDb string? GetURLFromHROW(HROW hRow); } + /// + /// + /// The IGetSession interface returns an interface pointer on the session object within whose context the row object was created. + /// + /// + /// Every row object is created within the context of a session object. When a consumer creates a row object from a rowset by calling + /// IGetRow::GetRowFromHROW, the row object exists within the context of the session associated with that rowset. When the + /// consumer instantiates a row directly by calling a method such as IBindResource::Bind, the provider creates an implicit session + /// object first and then instantiates the row object in the context of that session. + /// + /// + /// For many operations, such as creating a containing rowset, creating views, and transacting scoped operations, the consumer needs an + /// interface on the session object within whose context the row exists. The IGetSession interface has a single method that + /// returns the desired interface on the session object associated with a row. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711603(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aba-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IGetSession + { + /// Returns an interface pointer on the session object associated with the row object. + /// [in] The interface ID (IID) of the requested interface to return in ppSession. + /// + /// A pointer to memory in which to return the interface pointer on the session. If the provider does not have a session object as + /// the context for the row, it sets *ppSession to a null pointer. If IGetSession::GetSession fails and ppSession is not a + /// null pointer, the provider must attempt to set *ppSession to a null pointer. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720926(v=vs.85) HRESULT GetSession( REFIID riid, IUnknown + // **ppSession ); + [return: MarshalAs(UnmanagedType.IUnknown)] + object? GetSession(in Guid riid); + } + + /// The IGetSourceRow interface returns an interface on the row object within whose context a stream object was created. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719690(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733abb-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IGetSourceRow + { + /// Returns an interface pointer on the row object associated with the stream object. + /// [in] The IID of the interface on which to return a pointer. + /// + /// A pointer to memory in which to return the interface pointer. If the provider does not have a row object as the context for the + /// stream object, it sets *ppRow to a null pointer. If IGetSourceRow::GetSourceRow fails, the provider must attempt to set + /// *ppRow to a null pointer. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716759(v=vs.85) HRESULT GetSourceRow( REFIID riid, IUnknown + // ** ppRow ); + [return: MarshalAs(UnmanagedType.IUnknown)] + object? GetSourceRow(in Guid riid); + } + + /// IIndexDefinition exposes simple methods to create and drop indexes from the data store. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711593(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a68-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IIndexDefinition + { + /// Adds a new index to a base table. + /// [in] A pointer to the DBID of the table for which to create an index. + /// + /// [in] A pointer to the ID of the new index to create. If this is a null pointer, the provider assigns an ID to the index. The ID + /// must be unique. + /// + /// [in] The count of DBINDEXCOLUMNSDESC structures in rgIndexColumnDescs. + /// + /// [in] An array of DBINDEXCOLUMNDESC structures that describe how to construct the index. The order of the DBINDEXCOLUMNDESC + /// structures in rgIndexColumnDescs determines the order of the columns in the index key. That is, the column identified by the + /// first element of this array is the most significant column in the index key and the column identified by the last element is the + /// least significant column. When the index is opened as a rowset, the key columns occur in order of most significant column to + /// least significant column. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Index property group. If the same property is specified more than once in rgPropertySets, it is + /// provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// For information about the properties in the Index property group that are defined by OLE DB, see Index Property Group in Appendix + /// C.For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return a pointer to the DBID of a newly created index. If ppIndexID is a null pointer, no + /// DBID is returned. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded, and the new index has been created. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The index was created, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not create the index with the table open. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// pIndexID and ppIndexID were both null pointers. + /// cIndexColumnDescs was zero. + /// rgIndexColumnDescs was a null pointer. + /// eIndexColOrder in an element of rgIndexColumnDescs was not a valid value. + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_BADINDEXID *pIndexID was an invalid index ID. + /// + /// + /// + /// + /// DB_E_DUPLICATEINDEXID The specified index already exists in the data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No index was created because one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to determine + /// which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for any + /// of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOCOLUMN A column specified by *pColumnIDin an element of rgIndexColumnDescs does not exist in the specified table. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the data store. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the index. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712936(v=vs.85) HRESULT CreateIndex( DBID *pTableID, DBID + // *pIndexID, DBORDINAL cIndexColumnDescs, const DBINDEXCOLUMNDESC rgIndexColumnDescs[], ULONG cPropertySets, DBPROPSET + // rgPropertySets[], DBID **ppIndexID); + [PreserveSig] + HRESULT CreateIndex(in DBID pTableID, [In, Optional] IntPtr pIndexID, DBORDINAL cIndexColumnDescs, + [In, MarshalAs(UnmanagedType.LPArray)] DBINDEXCOLUMNDESC[] rgIndexColumnDescs, uint cPropertySets, + [In, Out] SafeDBPROPSETListHandle rgPropertySets, out SafeIMallocHandle ppIndexID); + + /// Drops an index from the base table. + /// [in] A pointer to the DBID of the base table. + /// + /// [in] A pointer to the DBID of the index to drop. This must be an index on the table specified with pTableID. If pIndexId is a + /// null pointer, all indexes for the table specified with pTableID are dropped. + /// + /// + /// + /// + /// + /// S_OK The method succeeded, and the index has been dropped from the base table. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED pIndexID was a null pointer, at least one index was successfully dropped, but one or more indexes for the + /// specified table could not be dropped. The consumer can determine the set of indexes not dropped through the INDEXES schema rowset. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED pIndexID was a null pointer, but none of the indexes for the specified table could be dropped. + /// + /// + /// + /// + /// DB_E_INDEXINUSE The specified index was in use. + /// + /// + /// + /// + /// DB_E_NOINDEX The specified index does not exist in the current data store or did not apply to the specified table. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not drop the index with the table open. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the index. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722733(v=vs.85) HRESULT DropIndex( DBID *pTableID, DBID *pIndexID); + [PreserveSig] + HRESULT DropIndex(in DBID pTableID, [In, Optional] IntPtr pIndexID); + } + + /// + /// IMultipleResults is used to retrieve multiple results (row counts, rowset objects, or row objects) created by a command. For + /// more information, see Multiple Results. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721289(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a90-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IMultipleResults + { + /// Returns the next in a series of multiple results from the provider. + /// + /// [in] A pointer to the controlling IUnknown interface if the object is being created as part of an aggregate; otherwise, it + /// is a null pointer. + /// + /// + /// + /// [in] This flag is ignored when returning row counts. When returning result objects (for example, rowset or row objects), the + /// values described in the following table apply. + /// + /// + /// + /// Enum + /// Description + /// + /// + /// DBRESULTFLAG_DEFAULT + /// + /// The type of the returned object is defined by riid or by properties set on the command object. If this is ambiguous, the + /// provider should return a rowset. Prior to OLE DB 2.6, providers were required to return E_INVALIDARG when lResultFlag was + /// not zero. Consumers should not pass nonzero values unless the provider is a 2.6 or later provider and has added support for lResultFlag. + /// + /// + /// + /// DBRESULTFLAG_ROWSET + /// The consumer explicitly requests a rowset object. + /// + /// + /// DBRESULTFLAG_ROW + /// The consumer explicitly requests a row object. + /// + /// + /// + /// Providers that support the return of row objects from ICommand::Execute and also support multiple results should support + /// returning row objects from calls to IMultipleResults::GetResult, as described by the flag values in the preceding table. + /// + /// + /// As in ICommand::Execute, when returning a row object from IMultipleResults::GetResult, if the statement would have + /// returned multiple rows, the provider is encouraged, but not required, to return DB_S_NOTSINGLETON. + /// + /// If lResultFlag is not zero and the riid does not match the requested object type, the provider should return E_NOINTERFACE. + /// + /// If lResultFlag is not zero and a command property (for example, DBPROP_IRow or DBPROP_IRowset) conflicts with the requested + /// object type, the provider should return DB_S_ERRORSOCCURRED with a suitable DBPROPSTATUS value, such as DBPROPSTATUS_CONFLICTING + /// if the property is optional, or DB_E_ERRORSOCCURRED if the property is required. + /// + /// + /// + /// + /// [in] The requested interface to return in *ppRowset. This interface is conceptually added to the list of required interfaces on + /// the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. + /// + /// If this is IID_NULL, ppRowset is ignored and no rowset is returned, even if one exists. + /// + /// + /// + /// [out] A pointer to memory in which to return the count of rows affected by an update, delete, or insert. If the value of + /// cParamSets passed into ICommand::Execute was greater than 1, *pcRowsAffected is the total number of rows affected by all + /// of the sets of parameters represented by the current result. If the count of affected rows is not available, *pcRowsAffected is + /// set to DB_COUNTUNAVAILABLE on output. If the result is not a count of rows affected by an update, delete, or insert, + /// *pcRowsAffected is undefined on output. If an error occurs, *pcRowsAffected is set to DB_COUNTUNAVAILABLE. If pcRowsAffected is a + /// null pointer, no count of affected rows is returned. + /// + /// + /// Some providers do not support returning individual counts of rows but instead return an overall count of the total rows affected + /// by the call to ICommand::Execute, or they do not return row counts at all. Such providers set *pcRowsAffected to + /// DB_COUNTUNAVAILABLE when the count of affected rows is not available. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the interface for the next result. If the next result is not a rowset (for example, + /// if it is the count of the rows affected by an update, delete, or insert), this is set to a null pointer. If an error occurs, + /// *ppRowset is set to a null pointer. + /// + /// If ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED This can be returned for either of the following reasons: + /// + /// + /// + /// + /// + /// DB_S_NOTSINGLETON The provider supports returning row objects on IMultipleResults::GetResult, and the consumer requested a + /// row object but the result was not a singleton. A row object of the first row of the rowset is returned if the provider supports + /// returning the row object. Because returning this result may be expensive, providers are not required to do so. If + /// DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes precedence over DB_S_NOTSINGLETON. + /// + /// + /// + /// + /// + /// DB_S_NORESULT There are no more results. *ppRowset is set to a null pointer, and *pcRowsAffected is set to ?1. + /// + /// + /// + /// + /// + /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been + /// returned. Calling IMultipleResults::GetResult again returns information for the next result or returns DB_S_NORESULT if no + /// more results can be obtained, either because they do not exist or because the resource limit applies across multiple results. + /// + /// + /// This return code takes precedence over DB_S_ERRORSOCCURRED. That is, if the conditions described here and 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 The value passed in for lResultFlag was invalid or not supported. + /// + /// + /// + /// + /// E_NOINTERFACE The interface specified in riid was not supported on the rowset. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to create the rowset. + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED Execution has been aborted because a resource limit has been reached. No results have been returned. + /// Calling IMultipleResults::GetResult again returns information for the next result or returns DB_S_NORESULT if no more + /// results can be obtained, either because they do not exist or because the resource limit applies across multiple results. + /// + /// + /// + /// + /// + /// + /// DB_E_CANTCONVERTVALUE A literal value in the command text associated with the next result could not be converted to the type of + /// the associated column for reasons other than data overflow. + /// + /// + /// + /// + /// + /// + /// DB_E_DATAOVERFLOW A literal value in the command text associated with the next result overflowed the type specified by the + /// associated column. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSINCOMMAND The command text associated with the next result contained one or more errors. Providers should use OLE DB + /// error objects to return details about the errors. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The method failed due to one or more invalid input parameter values associated with the next result. To + /// determine which input parameter 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. + /// + /// + /// The rowset was not returned because one or more properties ? for which the dwOptions element of the DBPROP structure was + /// DBPROPOPTIONS_REQUIRED or an invalid value ? could not be satisfied. + /// + /// + /// + /// + /// + /// + /// DB_E_INTEGRITYVIOLATION A literal value in the command text associated with the next result violated the integrity constraints + /// for the column. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was + /// requested via riid or DBPROP_IRow, and no rows existed in the rowset. + /// + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The previous rowset is still open, and the provider does not support multiple open results simultaneously. + /// (DBPROP_MULTIPLERESULTS is DBPROPVAL_MR_SUPPORTED.) + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to get the next result. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723081(v=vs.85) HRESULT GetResult( IUnknown *pUnkOuter, + // DBRESULTFLAG lResultFlag, REFIID riid, DBROWCOUNT *pcRowsAffected, IUnknown **ppRowset); + [PreserveSig] + HRESULT GetResult([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, DBRESULTFLAG lResultFlag, in Guid riid, + out DBROWCOUNT pcRowsAffected, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + } + /// /// /// IOpenRowset is a required interface on the session. It can be supported by providers that do not support creating rowsets @@ -3952,1006 +3952,48 @@ public static partial class OleDb } /// - /// - /// 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. + /// IParentRowset is used to retrieve child rowsets from a hierarchical rowset. For more information, see Hierarchical Rowsets. /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720986(v=vs.85) + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723109(v=vs.85) [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a7c-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IRowset + [ComImport, Guid("0c733aaa-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IParentRowset { - /// 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); - } - - /// IRowsetInfo provides information about a rowset. - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724541(v=vs.85) - [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a55-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IRowsetInfo - { - /// Returns the current settings of all properties supported by the rowset. - /// - /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. - /// - /// If cPropertySets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Rowset property - /// group for which values exist, including properties for which values were not set but for which defaults exist, and also including - /// properties for which values were set automatically because values were set for other properties. - /// - /// - /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the - /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of - /// dwOptions is undefined. - /// - /// - /// - /// - /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset - /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this - /// parameter is ignored. - /// - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix - /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets - /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Rowset - /// property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than - /// DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. - /// - /// - /// - /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is - /// returned for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is - /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET - /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If - /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of - /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column - /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties - /// have the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, - /// one for each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the - /// same property ID and rgProperties will contain more elements than rgPropertyIDs. - /// - /// - /// 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 *pcPropertySets is zero on output or if an error other than - /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. IRowsetInfo::GetProperties can fail to return properties for - /// a number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the - /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory - /// when it no longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719611(v=vs.85) HRESULT GetProperties ( const ULONG - // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); - [PreserveSig] - HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, - out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); - - /// Returns an interface pointer to the rowset to which a bookmark or chapter applies. - /// [in] The bookmark or chapter column for which to get the related rowset. - /// - /// [in] The IID of the interface pointer to return in *ppReferencedRowset. This interface is conceptually added to the list of - /// required interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the - /// resulting rowset. - /// - /// - /// [out] A pointer to memory in which to return an IUnknown interface pointer on the rowset that interprets values from this - /// column. If this is not a reference column, *ppReferencedRowset is set to a null pointer. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721145(v=vs.85) HRESULT GetReferencedRowset ( DBORDINAL - // iOrdinal, REFIID riid, IUnknown **ppReferencedRowset); - void GetReferencedRowset(DBORDINAL iOrdinal, in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)] out object? ppReferencedRowset); - - /// Returns an interface pointer on the object (command or session) that created this rowset. - /// [in] The IID of the interface on which to return a pointer. - /// - /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the - /// rowset, it sets *ppSpecification to a null pointer and returns S_FALSE. If IRowsetInfo::GetSpecification fails, it must - /// attempt to set *ppSpecification to a null pointer. - /// - /// - /// - /// - /// - /// S_OK The method succeeded. - /// - /// - /// - /// - /// S_FALSE The provider does not have an object that created the rowset. - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG ppSpecification was a null pointer. - /// - /// - /// - /// - /// E_NOINTERFACE The object that created this 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. - /// - /// - /// - /// - /// - /// 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/ms716746(v=vs.85) HRESULT GetSpecification ( REFIID riid, - // IUnknown **ppSpecification); - [PreserveSig] - HRESULT GetSpecification(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object? ppSpecification); - } - - /// - /// - /// ISessionProperties returns information about the properties a session supports and the current settings of those properties. - /// It is a mandatory interface on sessions. - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713721(v=vs.85) - [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a85-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ISessionProperties - { - /// Returns the list of properties in the Session property group that are currently set on the session. - /// - /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. - /// - /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Session - /// property group for which values have been set or defaults exist. It does not return the values of properties in the Session - /// property group for which values have not been set and no defaults exist. - /// - /// - /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the - /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of - /// dwOptions is undefined. - /// - /// - /// - /// - /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Session - /// property group. The provider returns the values of information about the properties specified in these structures. If - /// cPropertyIDSets is zero, this parameter is ignored. - /// - /// - /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix - /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets - /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the - /// Session property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other - /// than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. - /// - /// - /// - /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is - /// returned for each property set that contains at least one property belonging to the Session property group. If cPropertyIDSets is - /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET - /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If - /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of - /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of - /// each array, the property IDs are the same. - /// - /// - /// 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 *pcPropertySets is zero on output or if an error other than - /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. ISessionProperties::GetProperties can fail to return - /// properties for a number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the - /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory - /// when it no longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723643(v=vs.85) HRESULT GetProperties ( ULONG - // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); - [PreserveSig] - HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, - out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); - - /// Sets properties in the Session property group. - /// - /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method - /// does not do anything. - /// - /// - /// - /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these - /// structures must belong to the Session property group. If the same property is specified more than once in rgPropertySets, the - /// value used is provider-specific. If cPropertySets is zero, this parameter is ignored. - /// - /// - /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix - /// C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. - /// - /// - /// - /// - /// - /// - /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the - /// DBPROP structures to determine which properties were not set. ISessionProperties::SetProperties can fail to set properties - /// for a number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertySets was not equal to zero, and rgPropertySets was a null pointer. - /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED All property values were invalid, and no properties were set. The consumer checks dwStatus in the DBPROP - /// structures to determine why properties were not set. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714405(v=vs.85) HRESULT SetProperties ( ULONG cPropertySets, - // DBPROPSET rgPropertySets[]); - [PreserveSig] - HRESULT SetProperties(uint cPropertySets, [In, Out] SafeDBPROPSETListHandle? rgPropertySets); - } - - /// - /// - /// ISourcesRowset returns a rowset of data source objects and enumerators visible from the current enumerator. For more - /// information about enumerators, see Enumerators. - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715969(v=vs.85) - [PInvokeData("")] - [ComImport, Guid("0c733a1e-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ISourcesRowset - { - /// Returns a rowset of the data source objects and enumerators visible from the current enumerator. + /// Returns the child rowset corresponding to a chapter-valued column in the parent rowset. /// - /// [in] A pointer to the controlling IUnknown interface if the sources rowset is being created as part of an aggregate. If - /// the rowset is not part of an aggregate, this must be set to a null pointer. + /// [in] A pointer to the controlling IUnknown interface if the object is being created as part of an aggregate; otherwise, it + /// is a null pointer. /// - /// - /// [in] The IID of the interface on which to return a pointer. This interface is conceptually added to the list of required - /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. - /// - /// - /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. - /// - /// - /// - /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these - /// structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, it is - /// provider-specific which value is used. If cPropertySets is 0, this argument is ignored. - /// - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix - /// C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. - /// - /// - /// - /// [in] A pointer to memory in which to return the requested interface pointer on the rowset. If an error occurs, the returned - /// pointer is null. + /// [in] The ordinal of the chapter-valued column in the parent rowset. + /// [in] The requested interface to return in *ppRowset. + /// + /// [out] A pointer to memory in which to return the interface for the child rowset. If an error occurs, *ppRowset is set to a null pointer. /// /// /// /// /// - /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// S_OK The method succeeded. /// /// /// /// - /// - /// DB_S_ERRORSOCCURRED The rowset was opened, but one or more properties ? for which the dwOptions element of the DBPROP structure - /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties - /// were not set. The method can fail to set properties for a number of reasons, including the following: - /// + /// E_INVALIDARG ppRowset was a null pointer. /// /// /// /// - /// E_FAIL A provider-specific error occurred. + /// E_NOINTERFACE The interface specified in riid was not supported on the rowset. /// /// /// /// - /// E_INVALIDARG ppSourcesRowset was a null pointer. - /// cPropertySets was not 0, and rgPropertySets was a null pointer. - /// In an element of rgPropertySets, cProperties was not 0 and rgProperties was a null pointer. + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to create the rowset. /// /// /// /// - /// E_NOINTERFACE The rowset did not support the interface specified in riid, or riid is IID_NULL. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider did not have enough memory to create the rowset object. - /// - /// - /// - /// - /// E_UNEXPECTED The enumerator object was in an uninitialized state. - /// - /// - /// - /// - /// - /// DB_E_ABORTLIMITREACHED The method failed because a resource limit has been reached. For example, a query used to implement the - /// method timed out. No rowset is returned. - /// - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED No rowset was returned because one or more properties ? for which the dwOptions element of the DBPROP - /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to - /// determine which properties were not set. None of the properties are remembered. The method can fail to set properties for any of - /// the reasons specified in DB_S_ERRORSOCCURRED. - /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. /// /// /// @@ -4965,42 +4007,153 @@ public static partial class OleDb /// /// /// - /// - /// DB_E_NOTFOUND The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was - /// requested via riid or DBPROP_IRow, and no rows existed in the rowset. - /// + /// DB_E_OBJECTOPEN The referenced rowset has already been opened. + /// The provider is single-chaptered, and a child rowset is still open. + /// + /// + /// + /// + /// DB_E_BADORDINAL The column specified by iOrdinal was not a chapter-valued column or did not exist. /// /// /// /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711200(v=vs.85) HRESULT GetSourcesRowset( IUnknown - // *pUnkOuter, REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[], IUnknown **ppSourcesRowset); + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711213(v=vs.85) HRESULT GetChildRowset( IUnknown *pUnkOuter, + // DBORDINAL iOrdinal, REFIID riid, IUnknown **ppRowset); [PreserveSig] - HRESULT GetSourcesRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, uint cPropertySets, - [In, Out] SafeDBPROPSETListHandle? rgPropertySets, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)] out object? ppSourcesRowset); + HRESULT GetChildRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, DBORDINAL iOrdinal, in Guid riid, + [Optional, MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); } - /// ISQLErrorInfo is used to return the SQLSTATE and native error code. - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711569(v=vs.85) + /// The root binder's IRegisterProvider interface manages the mapping of URL schemes and prefixes to OLE DB providers. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716923(v=vs.85) [PInvokeData("oledb.h")] - [ComImport, Guid("0c733a74-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface ISQLErrorInfo + [ComImport, Guid("0c733ab9-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRegisterProvider { - /// Returns the SQLSTATE and native error code associated with an error. - /// - /// [out] A pointer to memory in which to return a pointer to a string that contains the SQLSTATE. An SQLSTATE is a 5-character - /// string defined by the ANSI SQL standard. The memory for this string is allocated by the provider and must be freed by the - /// consumer with a call to SysFreeString. If an error occurs, *pbstrSQLState is set to a null pointer. + /// Returns the CLSID of the provider binder object that is mapped to a URL scheme or scheme and prefix. + /// [in] The canonical URL scheme or scheme and prefix whose mapping is to be returned. + /// [in] Reserved for future use; caller should set this to zero. + /// + /// [out] A pointer to the CLSID of the provider binder object that is mapped to this URL scheme or scheme and prefix. + /// *pclsidProvider is set to DB_NULLGUID if an error code is returned. /// - /// - /// [out] A pointer to memory in which to return a provider-specific, native error code. *plNativeError is not necessarily the same - /// as the dwMinor element in the ERRORINFO structure returned by IErrorRecords::GetErrorInfo. The combination of the hrError - /// and dwMinor elements of the ERRORINFO structure is used to identify an error to the error lookup service, whereas *plNativeError - /// has no such restrictions. + /// + /// + /// + /// + /// S_OK The method succeeded. pclsidProvider points to the CLSID of the provider binder object. + /// + /// + /// + /// + /// S_FALSE No provider binder object was mapped to this URL scheme or scheme and prefix. *pclsidProvider is set to DB_NULLGUID. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL or pclsidProvider was a null pointer. + /// dwReserved was not 0. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718099(v=vs.85) HRESULT GetURLMapping( LPCOLESTR pwszURL, + // DB_DWRESERVE dwReserved, CLSID *pclsidProvider ); + [PreserveSig] + HRESULT GetURLMapping([In, MarshalAs(UnmanagedType.LPWStr)] string pwszURL, [In, Optional] DB_DWRESERVE dwReserved, out Guid pclsidProvider); + + /// Registers the ability of a provider binder object to process a particular URL scheme or scheme and prefix. + /// [in] The canonical URL scheme or scheme and prefix to be mapped. + /// [in] Reserved for future use; providers should set this to zero. + /// + /// [in] A reference to the CLSID of the provider binder object, which is to be mapped to this URL scheme or scheme and prefix. /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718195(v=vs.85) HRESULT GetSQLInfo ( BSTR *pbstrSQLState, - // LONG *plNativeError); - void GetSQLInfo([MarshalAs(UnmanagedType.BStr)] out string pbstrSQLState, out int plNativeError); + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// DB_E_RESOURCEEXISTS The URL scheme or scheme and prefix combination was already mapped to a different provider binder object. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller did not have permission to register this URL mapping. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL was a null pointer or pointed to an invalid URL. + /// dwReserved was not 0. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719610(v=vs.85) HRESULT SetURLMapping( LPCOLESTR pwszURL, + // DB_DWRESERVE dwReserved, REFCLSID rclsidProvider ); + [PreserveSig] + HRESULT SetURLMapping([In, Optional] string? pwszURL, [In, Optional] DB_DWRESERVE dwReserved, [In, Optional] GuidPtr rclsidProvider); + + /// Unregisters one or more URL mappings for a provider binder object. + /// + /// [in] The canonical URL scheme or scheme and prefix to be unmapped for the provider designated by rclsidProvider. If pwszURL is a + /// null pointer, all URL scheme or scheme and prefix combinations are unmapped for this provider. + /// + /// [in] Reserved for future use; providers should set this to zero. + /// + /// [in] A reference to the CLSID of the provider binder object for which the root binder will unregister the named URL mapping. This + /// CLSID must be provided and is never ignored. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// S_FALSE *pwszURL is a null pointer, and no scheme/prefix combinations were mapped to rclsidProvider. + /// *pwszURL was specified, and no matching scheme/prefix combinations were found or were mapped to rclsidProvider. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller did not have permission to unregister URL mappings. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL was not a well-formed or canonical URL. + /// dwReserved was not 0. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712849(v=vs.85) HRESULT UnregisterProvider( LPCOLESTR + // pwszURL, DB_DWRESERVE dwReserved, REFCLSID rclsidProvider ); + [PreserveSig] + HRESULT UnregisterProvider([In, Optional] string? pwszURL, [In, Optional] DB_DWRESERVE dwReserved, [In, Optional] GuidPtr rclsidProvider); } /// Creates a new command. @@ -5031,146 +4184,6 @@ public static partial class OleDb return (T)obj!; } - /// Returns the bindings in an accessor. - /// The instance. - /// [in] The handle of the accessor for which to return the bindings. - /// - /// [out] A pointer to memory in which to return a bitmask that describes the properties of the accessor and how it is intended to be - /// used. For more information, see dwAccessorFlags in CreateAccessor. If this method fails, *pdwAccessorFlags is set to DBACCESSOR_INVALID. - /// - /// - /// [out] A pointer to memory in which to return an array of DBBINDING structures. One DBBINDING structure is returned for each binding - /// in the accessor. The provider allocates memory for these structures and any structures pointed to by elements of these structures; - /// for example, if pObject in a binding structure is not a null pointer, the provider allocates a DBOBJECT structure for return to the - /// consumer. The provider returns the address to the memory for these structures; the consumer releases the memory for these structures - /// with IMalloc::Free when it no longer needs the bindings. If *pcBindings is zero on output or the method fails, the provider - /// does not allocate any memory and ensures that *prgBindings is a null pointer on output. For information about bindings, see DBBINDING Structures. - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721253(v=vs.85) HRESULT GetBindings ( HACCESSOR hAccessor, - // DBACCESSORFLAGS *pdwAccessorFlags, DBCOUNTITEM *pcBindings, DBBINDING **prgBindings); - public static void GetBindings(this IAccessor a, HACCESSOR hAccessor, out DBACCESSORFLAGS pdwAccessorFlags, out DBBINDING[] prgBindings) - { - a.GetBindings(hAccessor, out pdwAccessorFlags, out var c, out var p); - prgBindings = c == 0 ? [] : p.ToArray((int)c); - } - - /// Returns the column metadata needed by most consumers. - /// The instance. - /// [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures. One structure is returned for each column in - /// the rowset. 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 column information. If *pcColumns is 0 on output or terminates due - /// to an error, the provider does not allocate any memory and ensures that *prgInfo is a null pointer on output. For more - /// information, see "DBCOLUMNINFO Structures" in the Comments section. - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722704(v=vs.85) HRESULT GetColumnInfo ( DBORDINAL - // *pcColumns, DBCOLUMNINFO **prgInfo, OLECHAR **ppStringsBuffer); - public static HRESULT GetColumnInfo(this IColumnsInfo ci, out DBCOLUMNINFO_MGD[] prgInfo) - { - var hr = ci.GetColumnInfo(out var c, out var p, out var pp); - prgInfo = c == 0 || hr.Failed ? [] : Array.ConvertAll(p.ToArray((int)c), u => (DBCOLUMNINFO_MGD)u); - //IMallocMemoryMethods.Instance.FreeMem(p); - //IMallocMemoryMethods.Instance.FreeMem(pp); - return hr; - } - - /// Returns the list of properties in the Rowset property group that are currently requested for the rowset. - /// The instance. - /// - /// - /// [in] An array of DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset property group. The - /// provider returns the values of the properties specified in these structures. - /// - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix C. - /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// - /// [out] An array of DBPROPSET structures. If rgPropertyIDSets is zero length, one structure is returned for each property set that - /// contains at least one property belonging to the Rowset property group. If rgPropertyIDSets is not zero length, one structure is - /// returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If rgPropertyIDSets is not zero lenght, the DBPROPSET structures in *prgPropertySets are returned in the same order as the - /// DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the - /// same. If cPropertyIDs in an element of rgPropertyIDSets is not zero, the DBPROP structures in the corresponding element of - /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column - /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties have - /// the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, one for - /// each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the same property - /// ID and rgProperties will contain more elements than rgPropertyIDs. - /// - /// - /// 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 *pcPropertySets is zero on output or an error other than DB_E_ERRORSOCCURRED occurs, - /// the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. ICommandProperties::GetProperties can fail to return properties - /// for a number of reasons, including: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// In an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR and cPropertyIDs was not zero, or rgPropertyIDs - /// was not a null pointer. - /// - /// cPropertyIDSets was greater than one, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED No values were returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer - /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no - /// longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723119(v=vs.85) HRESULT GetProperties ( const ULONG - // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG * pcPropertySets, DBPROPSET ** prgPropertySets); - public static HRESULT GetProperties(this ICommandProperties icp, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) - { - var hr = icp.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); - mem.Count = (int)c; - prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; - return hr; - } - /// /// Returns the values of properties in the Data Source, Data Source Information, and Initialization property groups that are currently /// set on the data source object, or returns the values of properties in the Initialization property group that are currently set on the enumerator. @@ -5281,194 +4294,6 @@ public static partial class OleDb return hr; } - /// Returns the current settings of all properties supported by the rowset. - /// The instance. - /// - /// - /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset - /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this - /// parameter is ignored. - /// - /// - /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix C. - /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// - /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned - /// for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is not zero, one - /// structure is returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET - /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If - /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets - /// are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column properties are - /// specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties have the same property - /// ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, one for each column, in - /// rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the same property ID and - /// rgProperties will contain more elements than rgPropertyIDs. - /// - /// - /// 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 *pcPropertySets is zero on output or if an error other than DB_E_ERRORSOCCURRED - /// occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. IRowsetInfo::GetProperties can fail to return properties for a - /// number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer - /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no - /// longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719611(v=vs.85) HRESULT GetProperties ( const ULONG - // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); - public static HRESULT GetProperties(this IRowsetInfo i, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) - { - var hr = i.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); - mem.Count = (int)c; - prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; - return hr; - } - - /// Returns the list of properties in the Session property group that are currently set on the session. - /// The instance. - /// - /// - /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Session - /// property group. The provider returns the values of information about the properties specified in these structures. If cPropertyIDSets - /// is zero, this parameter is ignored. - /// - /// - /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix C. - /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. - /// - /// - /// - /// - /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned - /// for each property set that contains at least one property belonging to the Session property group. If cPropertyIDSets is not zero, - /// one structure is returned for each property set specified in rgPropertyIDSets. - /// - /// - /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET - /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If - /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets - /// are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of each array, the - /// property IDs are the same. - /// - /// - /// 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 *pcPropertySets is zero on output or if an error other than DB_E_ERRORSOCCURRED - /// occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. - /// - /// - /// - /// - /// - /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to - /// determine the properties for which values were not returned. ISessionProperties::GetProperties can fail to return properties - /// for a number of reasons, including the following: - /// - /// - /// - /// - /// - /// E_FAIL A provider-specific error occurred. - /// - /// - /// - /// - /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. - /// pcPropertySets or prgPropertySets was a null pointer. - /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. - /// - /// - /// - /// - /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. - /// - /// - /// - /// - /// - /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer - /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no - /// longer needs the information. - /// - /// - /// - /// - /// - // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723643(v=vs.85) HRESULT GetProperties ( ULONG cPropertyIDSets, - // const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); - public static HRESULT GetProperties(this ISessionProperties sp, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) - { - var hr = sp.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); - mem.Count = (int)c; - prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; - return hr; - } - /// Opens and returns a rowset that includes all rows from a single base table or index. /// The type of to return. /// The instance. @@ -5655,85 +4480,73 @@ public static partial class OleDb return hr; } - /// Basic information about the error, such as the return code and provider-specific error number. + /// Information about literals is returned in the DBLITERALINFO structure. [PInvokeData("oledb.h")] [StructLayout(LayoutKind.Sequential)] - public struct ERRORINFO + public struct DBLITERALINFO { - /// Undocumented. - public HRESULT hrError; - /// Undocumented. - public uint dwMinor; - /// Undocumented. - public Guid clsid; - /// Undocumented. - public Guid iid; - /// Undocumented. - public int dispid; - } + /// + /// A pointer to a string in the *ppCharBuffer buffer containing the actual literal value. + /// + /// For example, if lt is DBLITERAL_LIKE_PERCENT and the percent character (%) is used to match zero or more characters in a LIKE + /// clause, this would be "%". This is used for DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, + /// DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and + /// DBLITERAL_SCHEMA_SEPARATOR. For all other DBLITERAL values, pwszLiteralValue is not used and is set to a null pointer. + /// + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string pwszLiteralValue; - /*IADOConnectionConstruction - IADOSecurity - IAlterIndex - IAlterTable - IBindResource - IChapteredRowset - IColumnsInfo - IColumnsInfo2 - IColumnsRowset - ICommandPersist - ICommandPrepare - ICommandStream - ICommandWithParameters - IConvertType - IcreateRow - IDataSourceLocator - IDBAsynchNotify - IDBAsynchStatus - IDBBinderProperties - IDBDataSourceAdmin - IDBInfo - IDBSchemaRowset - IGetDataSource - IGetSession - IGetSourceRow - IIndexDefinition - IMultipleResults - IOpenRowset - IParentRowset - IRegisterProvider - IRow - IRowChange - IRowSchemaChange - IRowsetBookmark - IRowsetChange - IRowsetChapterMember - IRowsetCurrentIndex - IRowsetExactScroll - IRowsetFind - IRowsetIdentity - IRowsetIndex - IRowsetLocate - IRowsetNotify - IRowsetRefresh - IRowsetResynch - IRowsetScroll - IRowsetUpdate - IRowsetView - IScopedOperations - ISourcesRowset - ISQLXMLHelper - ITableCreation - ITableDefinition - ITableDefinitionWithConstraints - ITransaction - ITransactionJoin - ITransactionLocal - ITransactionObject - ITransactionOptions - IViewChapter - IViewFilter - IViewRowset - IViewSort - */ + /// + /// A pointer to a string in the *ppCharBuffer buffer containing the characters that are not valid in the literal. + /// + /// For example, if table names can contain anything other than a numeric character, this would be "0123456789" when lt is + /// DBLITERAL_TABLE_NAME. If the literal can contain any valid character, this is a null pointer. This is not used for + /// DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, + /// DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and DBLITERAL_SCHEMA_SEPARATOR; pwszInvalidChars is set to a null pointer for + /// these DBLITERAL values. + /// + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string pwszInvalidChars; + + /// + /// + /// A pointer to a string in the *ppCharBuffer buffer containing the characters that are not valid as the first character of the + /// literal. If the literal can start with any valid character, this is a null pointer. + /// + /// + /// For example, if table names can begin with anything other than a numeric character, this would be "0123456789" when lt is + /// DBLITERAL_TABLE_NAME. This is not used for DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, + /// DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and + /// DBLITERAL_SCHEMA_SEPARATOR; pwszInvalidStartingChars is set to a null pointer for these DBLITERAL values. + /// + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string pwszInvalidStartingChars; + + /// The literal described in the structure. For more information, see the following section. + public DBLITERAL lt; + + /// + /// + /// TRUE if the provider supports the literal specified by lt. If cLiterals is 0, this is always TRUE because IDBInfo::GetLiteralInfo + /// returns information only about literals it supports in this case. + /// + /// + /// FALSE if the provider does not support the literal, or the value of the corresponding element of the rgLiterals array was not a + /// valid value in the DBLITERAL enumerated type. + /// + /// + [MarshalAs(UnmanagedType.Bool)] + public bool fSupported; + + /// + /// The maximum number of characters in the literal. If there is no maximum or the maximum is unknown, cchMaxLen is set to ~0 + /// (bitwise, the value is not 0; all bits are set to 1). For DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, + /// DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and + /// DBLITERAL_SCHEMA_SEPARATOR, this is the actual number of characters in the literal. + /// + public uint cchMaxLen; + } } \ No newline at end of file diff --git a/PInvoke/OleDb/OleDb3.cs b/PInvoke/OleDb/OleDb3.cs new file mode 100644 index 00000000..4491bd9a --- /dev/null +++ b/PInvoke/OleDb/OleDb3.cs @@ -0,0 +1,4039 @@ +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); + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/OleDb4.cs b/PInvoke/OleDb/OleDb4.cs new file mode 100644 index 00000000..565cf174 --- /dev/null +++ b/PInvoke/OleDb/OleDb4.cs @@ -0,0 +1,4169 @@ +namespace Vanara.PInvoke; + +/// Items from the OleDb.dll. +public static partial class OleDb +{ + /// IRowsetFind is the interface that allows consumers to find a row within the rowset matching a specified value. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724221(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a9d-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetFind + { + /// Begins at the specified bookmark and finds the next row matching the specified value. + /// + /// [in] The chapter handle designating the rows to find. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER. + /// For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset. + /// + /// + /// + /// [in] Accessor describing the value to be matched. This accessor must describe only a single column. If it describes more than one + /// column, IRowsetFind::FindNextRow returns DB_E_BADBINDINFO. + /// + /// Valid coercions for IRowsetFind::FindNextRow are the same as those for IRowsetChange::SetData. + /// + /// + /// [in] Pointer to the value to be matched. If this indicates a null value (a variant of type VT_NULL or a status value of + /// DBSTATUS_ISNULL), it is compared equal to null values and not equal to non-null values, within the rowset. It is + /// provider-specific whether null values are compared greater than or less than non-null values. + /// + /// + /// + /// [in] Operation to use in comparing the row values. The consumer should check DBPROP_FINDCOMPAREOPS to determine which comparison + /// operators the provider supports. + /// + /// Only DBCOMPAREOPS_EQ, DBCOMPAREOPS_NE, and DBCOMPAREOPS_IGNORE are valid for the following values of CompareOp: + /// + /// + /// + /// DBTYPE_BOOL + /// + /// + /// + /// + /// DBTYPE_ERROR + /// + /// + /// + /// + /// DBTYPE_GUID + /// + /// + /// + /// + /// DBTYPE_IDISPATCH + /// + /// + /// + /// + /// DBTYPE_IUNKNOWN + /// + /// + /// + /// + /// DBTYPE_BYTES + /// + /// + /// + /// The values in DBCOMPAREOPSENUM have the meanings described in the following table. + /// + /// + /// Value + /// Description + /// + /// + /// DBCOMPAREOPS_LT + /// Match the first value that is less than the search value. + /// + /// + /// DBCOMPAREOPS_LE + /// Match the first value that is less than or equal to the search value. + /// + /// + /// DBCOMPAREOPS_EQ + /// Match the first value that is equal to the search value. + /// + /// + /// DBCOMPAREOPS_GE + /// Match the first value that is greater than or equal to the search value. + /// + /// + /// DBCOMPAREOPS_GT + /// Match the first value that is greater than the search value. + /// + /// + /// DBCOMPAREOPS_BEGINSWITH + /// + /// Match the first value that has the search value as its first characters. This is valid only for values bound as string data types. + /// + /// + /// + /// DBCOMPAREOPS_NOTBEGINSWITH + /// + /// Match the first value that does not have the search value as its first characters. This is valid only for values bound as string + /// data types. + /// + /// + /// + /// DBCOMPAREOPS_CONTAINS + /// + /// Match the first value that contains the search value. This is valid only for values bound as string data types. + /// + /// + /// + /// DBCOMPAREOPS_NOTCONTAINS + /// + /// Match the first value that does not contain the search value. This is valid only for values bound as string data types. + /// + /// + /// + /// DBCOMPAREOPS_NE + /// + /// Match the first value that is not equal to the search value. If the search value is NULL, this matches the first non-NULL value. + /// If the search value is non-NULL, this matches the first non-NULL value that is not equal to the search value. + /// + /// + /// + /// DBCOMPAREOPS_IGNORE + /// + /// Ignore the corresponding value. The provider ignores pFindValue and returns the next cRows rows starting from the + /// row indicated by pBookmark, skipping the number of rows indicated by lRowsOffset. + /// + /// + /// + /// DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE + /// + /// Specify whether the search is case-sensitive or case-insensitive. You can join DBCOMPAREOPS_CASESENSITIVE or + /// DBCOMPAREOPS_CASEINSENSITIVE with any of the other DBCOMPAREOPS values in a bitwise OR operation. If neither is used, the + /// search is handled according to the provider's implementation. Both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE + /// are ignored when searching for nonstring values. + /// + /// + /// + /// + /// + /// [in] Length in bytes of the bookmark, or zero to start from the next fetch location. (See the description of pBookmark.) + /// + /// + /// + /// [in] Pointer to a bookmark that, in combination with lRowsOffset, identifies the row from which to start searching for a match. + /// The consumer is not required to have access rights to this row. However, if this row matches the seek criteria, the provider + /// cannot return it unless the consumer has read permission for it. + /// + /// + /// To request that the find occur starting with the next fetch location, the consumer can specify a cbBookmark value of zero and set + /// pBookmark to null. The next fetch location is the same as the next fetch position used by IRowset::GetNextRows. + /// + /// If cbBookmark equals zero, the provider ignores pBookmark. + /// + /// If the rowset does not support IRowsetLocate, only the special bookmarks DBBMK_FIRST and DBBMK_LAST, and the null value, + /// may be used. + /// + /// If the rowset does not support scrolling backward, only the null bookmark value may be used. + /// If the rowset is chaptered, the identified row must fall within the specified chapter. + /// + /// + /// [in] The signed count of rows from the origin bookmark to the row at which to start searching for a match. The first row checked + /// is determined by the bookmark and this offset. For example, if lRowsOffset is 0, the first row checked is the bookmarked row; if + /// lRowsOffset is 1, the first row checked is the row after the bookmarked row; if lRowsOffset is -1, the first row checked is the + /// row before the bookmarked row. This can be a negative number only if the value of the DBPROP_CANSCROLLBACKWARDS property is VARIANT_TRUE. + /// + /// + /// + /// [in] The number of rows to fetch from the rowset, starting with the first row found. A negative number indicates a backward + /// fetch. The consumer can determine whether the provider supports fetching backward by checking the value of the + /// DBPROP_CANFETCHBACKWARDS property returned by IRowsetInfo::GetProperties. + /// + /// + /// The search direction is the same as the fetch direction, so a negative count searches backward from the starting position and + /// returns successively earlier rows as subsequent obtained rows. If cRows is zero and there are no other errors, no rows are + /// fetched. In this case, if cbBookmark is zero, the next fetch position is moved to the same position as if calling + /// IRowsetFind::FindNextRow with cRows equal to 1 and releasing the retrieved row. In general, consumers should avoid calling + /// IRowsetFind::FindNextRow with cRows equal to zero. + /// + /// + /// Note + /// + /// Calling IRowsetFind::FindNextRow with a cbBookmark value of zero searches for a column value relative to the current + /// IRowset::GetNextRows position. Following the call to IRowsetFind::FindNextRow, the fetch for + /// IRowset::GetNextRows is also moved. Calling IRowsetFind::FindNextRow with a cbBookmark value of zero and a cRows + /// value of zero is defined as setting the next fetch position to the same location as by calling IRowsetFind::FindNextRow + /// with a cbBookmark value of zero and a cRows value of one. + /// + /// + /// In general, it is not useful to call IRowsetFind::FindNextRow with a cRows value of zero. Due to ambiguity in the previous + /// versions of the OLE DB Programmer's Reference, some providers may not implement the next fetch position as defined, and consumers + /// should not rely on the next fetch position following a call to IRowsetFind::FindNextRow with a cbBookmark value of zero + /// and a cRows value of zero. + /// + /// + /// + /// [out] A pointer to memory in which to return the actual number of fetched rows. + /// + /// [out] A pointer to memory in which to return an array of handles of the retrieved 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 0 on output, 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 IRowsetFind::FindNextRow reached the start or the end of the rowset or (in a hierarchical rowset) the + /// start or the end of the chapter 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 returned is returned in *pcRowsObtained; + /// this will be less than cRows. + /// + /// + /// + /// + /// + /// + /// 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 Returning 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. Execution cannot be resumed. + /// + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// The row specified by *pBookmark was deleted, is no longer a member of the rowset, or is a row to which the consumer does not have + /// access rights. IRowsetFind::FindNextRow skipped that row and began searching with the next row in the direction indicated + /// by cRows. + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcRowsObtained or prghRows was a null pointer. + /// cbBookmark was not 0, and pBookmark 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_BADBINDINFO The specified accessor specified binding information for more than one column. + /// + /// + /// + /// + /// DB_E_BADBOOKMARK *pBookmark was invalid; for example, it was incorrectly formed. + /// + /// *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. + /// + /// *pBookmark was not a null value, and the rowset does not support scrolling backward. + /// *pBookmark was not DBBMK_FIRST, DBBMK_LAST, or a null value, and the rowset does not support IRowsetLocate. + /// The rowset was chaptered, and *pBookmark did not apply to the specified chapter. + /// + /// + /// + /// + /// 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_BADCOMPAREOP CompareOp was an invalid value*.* + /// CompareOp was DBCOMPAREOPS_BEGINSWITH or DBCOMPAREOPS_CONTAINS,and pFindValue was not bound as a string value. + /// Both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE were used in the same operation. + /// The specified CompareOp could not be supported on the column, or the column was not searchable. + /// + /// + /// + /// + /// + /// 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 A bookmark value of DBBMK_FIRST or DBBMK_LAST was specified, and the rowset cannot scroll backward. + /// 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 prior HROWs before new ones can be obtained. (See + /// IDBProperties::GetPropertyInfo, DBPROP_CANHOLDROWS.) + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to get the rows. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723091(v=vs.85) HRESULT FindNextRow ( HCHAPTER hChapter, + // HACCESSOR hAccessor, void *pFindValue, DBCOMPAREOP CompareOp, DBBKMARK cbBookmark, const BYTE *pBookmark, DBROWOFFSET lRowsOffset, + // DBROWCOUNT cRows, DBCOUNTITEM *pcRowsObtained, HROW **prghRows); + [PreserveSig] + HRESULT FindNextRow([In] HCHAPTER hChapter, [In] HACCESSOR hAccessor, [In] IntPtr pFindValue, DBCOMPAREOPS CompareOp, DBBKMARK cbBookmark, + [In] IntPtr pBookmark, DBROWOFFSET lRowsOffset, DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); + } + + /// + /// + /// IRowsetIdentity is the interface that indicates row instance identity is implemented on the rowset and enables testing for row + /// identity. If a rowset supports this interface, any two row handles representing the same underlying row will always reflect the same + /// data and state. + /// + /// IRowsetIdentity depends on IRowset. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715913(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a09-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetIdentity + { + /// Compares two row handles to see whether they refer to the same row instance. + /// [in] The handle of an active row. + /// [in] The handle of an active row. + /// + /// + /// + /// + /// S_FALSE The method succeeded, and the row handles do not refer to the same row instance. + /// + /// + /// + /// + /// S_OK The method succeeded, and the row handles do refer to the same row instance. + /// + /// + /// + /// + /// 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 hRowThis or hRowThat was invalid. + /// + /// + /// + /// + /// DB_E_DELETEDROW hRowThis or hRowThat referred to a row for which a deletion had been transmitted to the data store. + /// + /// + /// + /// + /// + /// DB_E_NEWLYINSERTED The provider is unable to determine identity for a row for which an insertion had been transmitted to the data + /// store. This condition can occur when DBPROP_STRONGIDENTITY is set to VARIANT_FALSE. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719629(v=vs.85) HRESULT IsSameRow ( HROW hThisRow, HROW hThatRow); + [PreserveSig] + HRESULT IsSameRow([In] HROW hThisRow, [In] HROW hThatRow); + } + + /// + /// IRowsetIndex is the primary interface for exposing index functionality in OLE DB. For a complete description of indexes, see + /// Index Rowsets, and Integrated Indexes. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719604(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a82-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface 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] + 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] + 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] + HRESULT SetRange([In] HACCESSOR hAccessor, DBORDINAL cStartKeyColumns, [In] IntPtr pStartData, DBORDINAL cEndKeyColumns, [In] IntPtr pEndData, DBRANGE dwRangeOptions); + } + + /// IRowsetInfo provides information about a rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724541(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a55-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetInfo + { + /// Returns the current settings of all properties supported by the rowset. + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertySets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Rowset property + /// group for which values exist, including properties for which values were not set but for which defaults exist, and also including + /// properties for which values were set automatically because values were set for other properties. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the + /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of + /// dwOptions is undefined. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset + /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this + /// parameter is ignored. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix + /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets + /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Rowset + /// property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than + /// DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is + /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of + /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column + /// properties are specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties + /// have the same property ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, + /// one for each column, in rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the + /// same property ID and rgProperties will contain more elements than rgPropertyIDs. + /// + /// + /// 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 *pcPropertySets is zero on output or if an error other than + /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. IRowsetInfo::GetProperties can fail to return properties for + /// a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the + /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory + /// when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719611(v=vs.85) HRESULT GetProperties ( const ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); + [PreserveSig] + HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, + out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); + + /// Returns an interface pointer to the rowset to which a bookmark or chapter applies. + /// [in] The bookmark or chapter column for which to get the related rowset. + /// + /// [in] The IID of the interface pointer to return in *ppReferencedRowset. This interface is conceptually added to the list of + /// required interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the + /// resulting rowset. + /// + /// + /// [out] A pointer to memory in which to return an IUnknown interface pointer on the rowset that interprets values from this + /// column. If this is not a reference column, *ppReferencedRowset is set to a null pointer. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721145(v=vs.85) HRESULT GetReferencedRowset ( DBORDINAL + // iOrdinal, REFIID riid, IUnknown **ppReferencedRowset); + void GetReferencedRowset(DBORDINAL iOrdinal, in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)] out object? ppReferencedRowset); + + /// Returns an interface pointer on the object (command or session) that created this rowset. + /// [in] The IID of the interface on which to return a pointer. + /// + /// [out] A pointer to memory in which to return the interface pointer. If the provider does not have an object that created the + /// rowset, it sets *ppSpecification to a null pointer and returns S_FALSE. If IRowsetInfo::GetSpecification fails, it must + /// attempt to set *ppSpecification to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// S_FALSE The provider does not have an object that created the rowset. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppSpecification was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The object that created this 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. + /// + /// + /// + /// + /// + /// 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/ms716746(v=vs.85) HRESULT GetSpecification ( REFIID riid, + // IUnknown **ppSpecification); + [PreserveSig] + HRESULT GetSpecification(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object? ppSpecification); + } + + /// + /// + /// IRowsetLocate is the interface for fetching arbitrary rows of a rowset. A rowset that does not implement this interface is a + /// sequential rowset. IRowsetLocate is a prerequisite for IRowsetScroll. + /// + /// + /// When IRowsetLocate or one of its direct descendants 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. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms721190(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a7d-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetLocate : 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] + 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] + 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] + 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] + 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] + 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); + } + + /// + /// + /// IRowsetNotify is the callback interface that a consumer must support to connect to local notifications provided by a rowset + /// object. The notifications are intended to synchronize objects that are attached to the same rowset instance. The notifications do not + /// reflect changes in underlying shared tables that occur through other programs or users. + /// + /// + /// The notifications use the standard COM connection point scheme for operations or events on rowset objects. A rowset object supports + /// IConnectionPointContainer, and the consumer calls FindConnectionPoint for IID_IRowsetNotify to obtain the correct + /// IConnectionPoint interface. The consumer then advises that connection point to connect and supplies a pointer to the + /// consumer's IRowsetNotify interface. + /// + /// Providers are required to support all notifications for which they have the underlying functionality. + /// For more information about notifications, see OLE DB Object Notifications. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712959(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a83-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetNotify + { + /// Notifies the consumer of any change to the value of a column. + /// + /// [in] A pointer to the rowset, because the consumer may be receiving notifications from multiple rowsets and this identifies which + /// one is calling. + /// + /// + /// [in] The handle of the row in which the column value was changed. After this method returns, the reference count of this row will + /// be unchanged unless the consumer explicitly changes it. This is different from other methods that return rows to the consumer, in + /// which the provider explicitly increments the reference count. Therefore, if the consumer wants to guarantee that this row handle + /// is valid after this method returns, it must call IRowset::AddRefRows for the row while it is processing this method. + /// + /// [in] The count of columns in rgColumns. + /// [in] An array of columns in the row for which the value was changed. + /// + /// [in] The reason for the change as indicated by the value of DBREASON. If this value is not recognized by the method, the method + /// returns S_OK or DB_S_UNWANTEDREASON. + /// + /// [in] The phase of this notification. + /// + /// [in] When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// S_FALSE The notification, expressed by the value of DBREASON or DBEVENTPHASE or both, is vetoed by reason of logical objection or + /// a failure to be able to implement. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDPHASE The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no + /// further calls with this reason and phase. The phases for other reasons are unaffected. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDREASON The consumer is not interested in receiving any phases for this reason. The provider can optimize by making + /// no further calls with this reason. + /// + /// + /// + /// + /// + /// E_FAIL A consumer-specific error occurred. The provider continues the operation. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715961(v=vs.85) HRESULT OnFieldChange ( IRowset *pRowset, + // HROW hRow, DBORDINAL cColumns, DBORDINAL rgColumns[], DBREASON eReason, DBEVENTPHASE ePhase, BOOL fCantDeny); + [PreserveSig] + HRESULT OnFieldChange([In] IRowset pRowset, [In] HROW hRow, DBORDINAL cColumns, [In, MarshalAs(UnmanagedType.LPArray)] DBORDINAL[] rgColumns, + DBREASON eReason, DBEVENTPHASE ePhase, bool fCantDeny); + + /// Notifies the consumer of the first change to a row or of any change that affects the entire row. + /// + /// [in] A pointer to the rowset, because the consumer may be receiving notifications from multiple rowsets and this identifies which + /// one is calling. + /// + /// [in] The count of row handles in rghRows. + /// + /// + /// [in] An array of handles of rows that are changing. This array belongs to the caller (rowset) and must not be freed or used + /// beyond the duration of the method call. + /// + /// + /// After this method returns, the reference count of these rows will be unchanged unless the consumer explicitly changes them. This + /// is different from other methods that return rows to the consumer, in which the provider explicitly increments the reference + /// counts. Therefore, if the consumer wants to guarantee that these row handles are valid after this method returns, it must call + /// IRowset::AddRefRows for these rows while it is processing this method. + /// + /// + /// + /// [in] The reason for the change as indicated by the value of DBREASON. If this value is not recognized by the method, the method + /// returns S_OK or DB_S_UNWANTEDREASON. + /// + /// [in] The phase of this notification. + /// + /// [in] When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// S_FALSE The notification, expressed by the value of DBREASON or DBEVENTPHASE or both, is vetoed by reason of logical objection or + /// a failure to be able to implement, as permitted for the phase. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDPHASE The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no + /// further calls with this reason and phase. The phases for other reasons are unaffected. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDREASON The consumer is not interested in receiving any phases for this reason. The provider can optimize by making + /// no further calls with this reason. + /// + /// + /// + /// + /// + /// E_FAIL A consumer-specific error occurred. The provider continues the operation. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722694(v=vs.85)?redirectedfrom=MSDN HRESULT OnRowChange ( + // IRowset *pRowset, DBCOUNTITEM cRows, const HROW rghRows[], DBREASON eReason, DBEVENTPHASE ePhase, BOOL fCantDeny); + [PreserveSig] + HRESULT OnRowChange([In] IRowset pRowset, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray)] HROW[] rghRows, DBREASON eReason, + DBEVENTPHASE ePhase, bool fCantDeny); + + /// Notifies the consumer of any change affecting the entire rowset. + /// + /// [in] A pointer to the rowset, because the consumer may be receiving notifications from multiple rowsets and this identifies which + /// one is calling. + /// + /// + /// [in] The reason for the change as indicated by the value of DBREASON. If this value is not recognized by the method, the method + /// returns S_OK or DB_S_UNWANTEDREASON. + /// + /// [in] The phase of this notification. + /// + /// [in] When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// S_FALSE The notification, expressed by the value of DBREASON or DBEVENTPHASE or both, is vetoed by reason of logical objection or + /// a failure to be able to implement. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDPHASE The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no + /// further calls with this reason and phase. The phases for other reasons are unaffected. + /// + /// + /// + /// + /// + /// + /// DB_S_UNWANTEDREASON The consumer is not interested in receiving any phases for this reason. The provider can optimize by making + /// no further calls with this reason. + /// + /// + /// + /// + /// + /// E_FAIL A consumer-specific error occurred. The provider continues the operation. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722669(v=vs.85) HRESULT OnRowsetChange ( IRowset * pRowset, + // DBREASON eReason, DBEVENTPHASE ePhase, BOOL fCantDeny); + [PreserveSig] + HRESULT OnRowsetChange([In] IRowset pRowset, DBREASON eReason, DBEVENTPHASE ePhase, bool fCantDeny); + } + + /// IRowsetRefresh is used to retrieve the values for rows that are currently visible to the transaction. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714892(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aa9-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetRefresh + { + /// Retrieves the data values from the data store that are visible to the transaction for the specified rows. + /// + /// [in] The chapter handle designating the rows to refresh. For nonchaptered rowsets, the caller must set hChapter to + /// DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset. + /// + /// + /// [in] The count of rows to refresh. If cRows is zero, IRowsetRefresh::RefreshVisibleData ignores rghRows and reads in + /// current values for all active rows. + /// + /// [in] An array of cRows row handles to be refreshed. If cRows is zero, this argument is ignored. + /// + /// [in] TRUE if the provider should discard any pending changes to a given row and accept the visible values as the new current + /// values; FALSE otherwise. + /// + /// + /// [out] A pointer to memory in which to return the number of rows the method attempted to refresh. This is still the case if + /// DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED is returned. If any other error occurs, the provider sets *pcRowsRefreshed to zero. If + /// this is a null pointer, no count of rows is returned. + /// + /// + /// + /// [out] A pointer to memory in which to return the array of row handles the method attempted to refresh. If cRows is not zero, the + /// elements of this array are in one-to-one correspondence with those of rghRows. If cRows is zero, the elements of this array are + /// the handles of all rows that have been updated by the operation. In this case, IRowsetRefresh::RefreshVisibleData will add + /// to the reference count of the rows whose handles are returned in prghRowsRefreshed. + /// + /// + /// The rowset allocates memory for the handles and the client should release this memory with IMalloc::Free when no longer + /// needed. This argument is ignored if pcRowsRefreshed is a null pointer and must not be a null pointer otherwise. If + /// *pcRowsRefreshed is zero on output or the method fails, the provider does not allocate any memory and ensures that + /// *prghRowsRefreshed is a null pointer on output. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with + /// the elements of *prghRowsRefreshed. If no errors occur while refreshing a row, the corresponding element of *prgRowStatus is set + /// to DBROWSTATUS_S_OK if the row is successfully resynchronized, or to DBROWSTATUS_S_NOCHANGE if the provider can easily determine + /// that there was no change to the value. If an error occurs while refreshing a row, the corresponding element is set as specified + /// in DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no row status values are returned. + /// + /// + /// The rowset allocates memory for the row status values and returns the address to this memory; the client releases this memory + /// with IMalloc::Free when it is no longer needed. This argument is ignored if pcRowsRefreshed is a null pointer. If + /// *pcRowsRefreshed is zero on output or the method fails, the provider does not allocate any memory and ensures that *prgRowStatus + /// is a null pointer on output. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. All rows were successfully processed. For each row, prgRowStatus contains one of the following: + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An error occurred while refreshing a row, but at least one row was successfully refreshed. Successes can + /// occur for the reason listed under S_OK. The following errors can occur: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows was not zero, and rghRows was a null pointer. + /// pcRowsRefreshed was not a null pointer, and prghRowsRefreshed was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Errors occurred while refreshing 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to refresh the rows. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714369(v=vs.85) HRESULT RefreshVisibleData ( HCHAPTER + // hChapter, DBCOUNTITEM cRows, const HROW rghRows[], BOOL fOverwrite, DBCOUNTITEM *pcRowsRefreshed, HROW **prghRowsRefreshed, + // DBROWSTATUS **prgRowStatus); + [PreserveSig] + HRESULT RefreshVisibleData([In] HCHAPTER hChapter, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray)] HROW[] rghRows, bool fOverwrite, + out DBCOUNTITEM pcRowsRefreshed, out SafeIMallocHandle prghRowsRefreshed, out SafeIMallocHandle prgRowStatus); + + /// + /// Gets the most recent data either from the provider-implemented data cache that is visible to the transaction or from the data store. + /// + /// + /// [in] The handle of the row with pending changes for which to get the latest data. This can be the handle of a row with a pending delete. + /// + /// + /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in + /// IAccessor::CreateAccessor was zero), IRowsetRefresh::GetLastVisibleData does not get any data values. + /// + /// [out] A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer. + /// + /// + /// + /// + /// + /// 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 hAccessor 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. It is possible for a reference accessor or an accessor that has a binding that uses + /// provider-owned memory to be invalid for use with this method, even if the accessor is valid for use with IRowset::GetData + /// or IRowsetChange::SetData. + /// + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// + /// 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_PENDINGINSERT The rowset was in delayed update mode, and hRow referred to a pending insert row. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to retrieve the rows from the data store. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719662(v=vs.85) HRESULT GetLastVisibleData ( HROW hRow, + // HACCESSOR hAccessor, void *pData); + [PreserveSig] + HRESULT GetLastVisibleData([In] HROW hRow, [In] HACCESSOR hAccessor, [Out] IntPtr pData); + } + + /// + /// IRowsetResynch allows consumers to retrieve the current values for rows that may have been changed in the data store since retrieved. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723082(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a84-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetResynch + { + /// Gets the data in the data store that is visible to the transaction for the specified row. + /// + /// [in] The handle of the row for which to get the visible data. This can be the handle of a row with a pending delete. + /// + /// + /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindings in + /// IAccessor::CreateAccessor was zero), IRowsetResynch::GetVisibleData does not get any data values. + /// + /// [out] A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer. + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pData was a null pointer, and hAccessor 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. It is possible for a reference accessor or an accessor that has a binding that uses + /// provider-owned memory to be invalid for use with this method, even if the accessor is valid for use with IRowset::GetData + /// or IRowsetChange::SetData. + /// + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// DB_E_DELETEDROW hRow referred to a row for which a deletion had been transmitted to the data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Errors occurred while returning data for all columns. To determine what errors occurred, the consumer checks + /// the status values. + /// + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED The provider was unable to retrieve the visible data due to reaching a limit on the server, such as a + /// query execution timing out. + /// + /// + /// + /// + /// + /// + /// DB_E_NEWLYINSERTED DBPROP_STRONGIDENTITY was VARIANT_FALSE, and hRow referred to a row for which an insertion had been + /// transmitted to the data store. + /// + /// + /// + /// + /// + /// + /// 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_PENDINGINSERT The rowset was in delayed update mode, and hRow referred to a pending insert row. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725455(v=vs.85) HRESULT GetVisibleData (HROW hRow, HACCESSOR + // hAccessor, void *pData); + [PreserveSig] + HRESULT GetVisibleData([In] HROW hRow, [In] HACCESSOR hAccessor, [Out] IntPtr pData); + + /// + /// Gets the data in the data store that is visible to the transaction for the specified rows and updates the rowset's copies of + /// those rows. + /// + /// + /// [in] The count of rows to resynchronize. If cRows is zero, IRowsetResynch::ResynchRows ignores rghRows and reads the + /// current value of all active rows. + /// + /// [in] An array of cRows row handles to be resynchronized. If cRows is zero, this argument is ignored. + /// + /// [out] A pointer to memory in which to return the number of rows the method attempted to resynchronize. The caller may supply a + /// null pointer if no list is desired. If the method fails with an error other than DB_E_ERRORSOCCURRED, the provider sets + /// *pcRowsResynched to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return the array of row handles the method attempted to resynchronize. If cRows is not + /// zero, the elements of this array are in one-to-one correspondence with those of rghRows. If cRows is zero, the elements of this + /// array are the handles of all active rows in the rowset. When cRows is zero, IRowsetResynch::ResynchRows will add to the + /// reference count of the rows whose handles are returned in prghRowsResynched. + /// + /// + /// The rowset allocates memory for the handles and the client should release this memory with IMalloc::Free when no longer + /// needed. This argument is ignored if pcRowsResynched is a null pointer and must not be a null pointer otherwise. If + /// *pcRowsResynched is zero on output or the method fails, the provider does not allocate any memory and ensures that + /// *prghRowsResynched is a null pointer on output. + /// + /// If pcRowsResynched is a null pointer, prghRowsResynched and prgRowStatus are ignored. + /// + /// If pcRowsResynched is not a null pointer and if *pcRowsResynched is zero on output or the method fails, the provider does not + /// allocate any memory and ensures that *prghRowsResynched and *prgRowStatus are null pointers on output. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with + /// the elements of *prghRowsResynched. If no errors occur while resynchronizing a row, the corresponding element of *prgRowStatus is + /// set to DBROWSTATUS_S_OK. If the method fails while resynchronizing a row, the corresponding element is set as specified in + /// DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no row status values are returned. + /// + /// + /// The rowset allocates memory for the row status values and returns the address to this memory; the client releases this memory + /// with IMalloc::Free when it is no longer needed. This argument is ignored if pcRowsResynched is a null pointer. If + /// *pcRowsResynched is zero on output or if the method fails with an error other than DB_E_ERRORSOCCURRED, the provider does not + /// allocate any memory and ensures that *prgRowStatus is a null pointer on output. + /// + /// If pcRowsResynched is a null pointer, prghRowsResynched and prgRowStatus are ignored. + /// + /// If pcRowsResynched is not a null pointer and if *pcRowsResynched is zero on output or the method fails, the provider does not + /// allocate any memory and ensures that *prghRowsResynched and *prgRowStatus are null pointers on output. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. All rows were successfully resynchronized. The following value can be returned in *prgRowStatus: + /// The row was successfully resynchronized. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An error occurred while resynchronizing a row, but at least one row was successfully resynchronized. + /// Successes can occur for the reason listed under S_OK. The following errors can occur: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// + /// E_INVALIDARG cRows was not zero, and rghRows was a null pointer. pcRowsResynched was not a null pointer, and prghRowsResynched + /// was a null pointer. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Errors occurred while resynchronizing 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_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to resynchronize the rows. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms717937(v=vs.85) HRESULT ResynchRows ( DBCOUNTITEM cRows, + // const HROW rghRows[], DBCOUNTITEM *pcRowsResynched, HROW **prghRowsResynched, DBROWSTATUS **prgRowStatus); + [PreserveSig] + HRESULT ResynchRows(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray)] HROW[] rghRows, + out DBCOUNTITEM pcRowsResynched, out SafeIMallocHandle prghRowsResynched, out SafeIMallocHandle prgRowStatus); + } + + /// IRowsetScroll enables consumers to fetch rows at approximate positions in the rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712984(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a7e-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetScroll : IRowsetLocate + { + /// 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] + 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] + HRESULT GetRowsAtRatio([In, Optional] HWATCHREGION hReserved1, [In] HCHAPTER hChapter, DBCOUNTITEM ulNumerator, DBCOUNTITEM ulDenominator, + DBROWCOUNT cRows, out DBCOUNTITEM pcRowsObtained, out SafeIMallocHandle prghRows); + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/OleDb5.cs b/PInvoke/OleDb/OleDb5.cs new file mode 100644 index 00000000..2b1d3edf --- /dev/null +++ b/PInvoke/OleDb/OleDb5.cs @@ -0,0 +1,6934 @@ +namespace Vanara.PInvoke; + +/// Items from the OleDb.dll. +public static partial class OleDb +{ + /// Flags describing additional semantics for the copy operation + [PInvokeData("oledb.h")] + [Flags] + public enum DBCOPYFLAGS + { + /// + /// The copy operation is performed asynchronously. Progress and notifications are available by using IDBAsynchStatus and + /// IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. + /// + DBCOPY_ASYNC = 0x100, + + /// + /// The copy operation succeeds even if a target object already exists at the destination URL. Otherwise, the copy fails if a target + /// object already exists. + /// + DBCOPY_REPLACE_EXISTING = 0x200, + + /// + /// If this flag is set and the attempt to copy the tree or subtree fails because the destination URL is on a different server or + /// serviced by a different provider than the source, the provider is requested to attempt to simulate the copy using download and + /// upload operations. When moving entities between providers, this may cause increased latency or data loss due to different + /// provider capabilities. + /// + DBCOPY_ALLOW_EMULATION = 0x400, + + /// If this flag is set, only the root node of the tree is copied; no child nodes are copied. + DBCOPY_NON_RECURSIVE = 0x800, + + /// + /// Either all trees or subtrees are copied successfully or none are copied. Whether all parts of an atomic operation are attempted + /// if one part fails is provider-specific. + /// + DBCOPY_ATOMIC = 0x1000 + } + + /// A bitmask of flags that control additional semantics for the delete operation + [PInvokeData("oledb.h")] + [Flags] + public enum DBDELETEFLAGS + { + /// + /// The delete operation is performed asynchronously. Progress and notifications are available via IDBAsynchStatus and + /// IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. If + /// DBDELETE_ASYNC is not specified, the operation is synchronous. A value of 0 is allowed. + /// + DBDELETE_ASYNC = 0x100, + + /// + /// Either all trees and subtrees are deleted or none are deleted. Whether all parts of an atomic operation are attempted if one part + /// fails is provider-specific. If DBDELETE_ATOMIC is not specified, the operation is non-atomic. A value of 0 is allowed. + /// + DBDELETE_ATOMIC = 0x1000 + } + + /// Flags describing additional semantics for the move operation + [PInvokeData("oledb.h")] + [Flags] + public enum DBMOVEFLAGS + { + /// + /// The move operation succeeds, even if a target object exists. Without this value, the move will fail if the target object already exists. + /// + DBMOVE_REPLACE_EXISTING = 0x1, + + /// + /// The move operation is performed asynchronously. Progress and notifications are available via IDBAsynchStatus and IDBAsynchNotify + /// callbacks. Implementations that do not support asynchronous behavior should block and return a warning. + /// + DBMOVE_ASYNC = 0x100, + + /// + /// Request the server not to update links contained in an object on a move. + /// + /// If this flag is not specified, the default behavior is to do what the server specifies. By default, IScopedOperations::Move will + /// update links if the server is capable and if the option is turned on. If the server does not have the ability to fix up links or + /// if the option is turned off, this call will still return S_OK. + /// + /// + DBMOVE_DONT_UPDATE_LINKS = 0x200, + + /// + /// If the attempt to move the row fails because the destination URL is on a different server or serviced by a different provider + /// than the source, the provider is requested to attempt to simulate the move using download, upload, and delete operations. When + /// moving resources between providers, this may cause increased latency or data loss due to different provider capabilities. + /// + DBMOVE_ALLOW_EMULATION = 0x400, + + /// + /// Either all sources are moved successfully or no sources are moved. Whether all parts of an atomic operation are attempted if one + /// part fails is provider-specific. + /// + DBMOVE_ATOMIC = 0x1000 + } + + /// Indicates whether consumers want rows with pending updates, deletes, or inserts. + [PInvokeData("oledb.h")] + [Flags] + public enum DBPENDINGSTATUS : uint + { + /// The row has a pending insert. + DBPENDINGSTATUS_NEW = 0x1, + + /// The row has a deferred change. + DBPENDINGSTATUS_CHANGED = 0x2, + + /// The row has a pending delete. This state is sometimes called soft delete. + DBPENDINGSTATUS_DELETED = 0x4, + + /// No changes have been made to the row, or changes that were made to the row have been transmitted or undone. + DBPENDINGSTATUS_UNCHANGED = 0x8, + + /// + /// The row has been deleted and that deletion has been transmitted to the data store. This status is also used when a row handle + /// passed to IRowsetUpdate::GetRowStatus was invalid. This state is sometimes called hard delete. + /// + DBPENDINGSTATUS_INVALIDROW = 0x10 + } + + /// + /// + /// IRowsetUpdate enables consumers to delay the transmission of changes made with IRowsetChange to the data store. This + /// interface also enables consumers to undo changes before transmission. + /// + /// IRowsetUpdate is optional. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714401(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a6d-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetUpdate : 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] + new 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] + new 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] + new HRESULT InsertRow([In] HCHAPTER hChapter, [In] HACCESSOR hAccessor, [In] IntPtr pData, out HROW phRow); + + /// Gets the data most recently fetched from or transmitted to the data store. Does not get values based on pending changes. + /// + /// [in] The handle of the row for which to get the original data. This can be the handle of a row with a pending change or delete. + /// + /// + /// [in] The handle of the accessor to use. If hAccessor is the handle of a null accessor (cBindingsin + /// IAccessor::CreateAccessor was zero), IRowsetUpdate::GetOriginalData does not get any data values. + /// + /// [out] A pointer to a buffer in which to return the data. The consumer allocates memory for this buffer. + /// + /// + /// + /// + /// + /// 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 A row handle in rghRows referred to a row on which a storage or other object was open. The corresponding + /// element of *prgRowStatus contains DBROWSTATUS_E_OBJECTOPEN. + /// + /// + /// 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 hAccessor 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. It is possible for a reference accessor or an accessor that has a binding that uses + /// provider-owned memory to be invalid for use with this method, even if the accessor is valid for use with IRowset::GetData or IRowsetChange::SetData. + /// + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// DB_E_DELETEDROW hRow referred to a row for which a deletion had been transmitted to the data store. + /// + /// + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// + /// 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/ms709947(v=vs.85) HRESULT GetOriginalData ( HROW hRow, + // HACCESSOR hAccessor, void *pData); + [PreserveSig] + HRESULT GetOriginalData([In] HROW hRow, [In] HACCESSOR hAccessor, [Out] IntPtr pData); + + /// Returns a list of rows with pending changes. + /// [in] Reserved for future use. Must be DB_NULL_HCHAPTER. + /// + /// + /// [in] Indicates whether consumers want rows with pending updates, deletes, or inserts. The following DBPENDINGSTATUS values are + /// valid and can be combined: + /// + /// + /// + /// + /// DBPENDINGSTATUS_NEW + /// + /// + /// + /// + /// DBPENDINGSTATUS_CHANGED + /// + /// + /// + /// + /// DBPENDINGSTATUS_DELETED + /// + /// + /// + /// For information about the DBPENDINGSTATUS type, see Row States in Deferred Update Mode. + /// + /// + /// [out] A pointer to memory in which to return the number of rows with pending changes. If this is a null pointer, prgPendingRows + /// and prgPendingStatus are ignored. This is useful when the consumer wants to check the returned return code to determine whether + /// there are any pending changes. If an error occurs, *pcPendingRows is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of handles of rows with pending changes. If this is a null pointer, no row + /// handles are returned. The rowset allocates memory for the row handles and returns the address to this memory; the consumer + /// releases this memory with IMalloc::Free when it no longer needs the row handles. This argument is ignored if pcPendingRows + /// is a null pointer. If *pcPendingRows is zero on output or an error occurs, the provider does not allocate any memory and ensures + /// that *prgPendingRows is a null pointer on output. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPENDINGSTATUS values. These values are in one-to-one correspondence + /// with the row handles returned in *prgPendingRows and indicate the type of pending change. For information about the + /// DBPENDINGSTATUS type, see Row States in Deferred Update Mode. If this is a null pointer, no status information is returned. + /// + /// + /// The rowset allocates memory for the row statuses and returns the address to this memory; the consumer releases this memory with + /// IMalloc::Free when it no longer needs the row statuses. This argument is ignored if pcPendingRows is a null pointer. If + /// *pcPendingRows is zero on output or an error occurs, the provider does not allocate any memory and ensures that *prgPendingStatus + /// is a null pointer on output. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded, and changes were pending. + /// + /// + /// + /// + /// S_FALSE The method succeeded, and no changes were pending. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG dwRowStatus was DBPENDINGSTATUS_INVALIDROW, DBPENDINGSTATUS_UNCHANGED, or any other invalid value. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the handles of rows with pending changes + /// or the array of DBPENDINGSTATUS values. + /// + /// + /// + /// + /// + /// 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 hReserved 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. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719626(v=vs.85) HRESULT GetPendingRows ( HCHAPTER hReserved, + // DBPENDINGSTATUS dwRowStatus, DBCOUNTITEM *pcPendingRows, HROW **prgPendingRows, DBPENDINGSTATUS **prgPendingStatus); + [PreserveSig] + HRESULT GetPendingRows([In] HCHAPTER hReserved, DBPENDINGSTATUS dwRowStatus, out DBCOUNTITEM pcPendingRows, + out SafeIMallocHandle prgPendingRows, out SafeIMallocHandle prgPendingStatus); + + /// Returns the status of rows. + /// [in] Reserved for future use. Must be DB_NULL_HCHAPTER. + /// + /// [in] The count of elements in rghRows and rgPendingStatus. If this value is zero, IRowsetUpdate::GetRowStatus ignores + /// rghRows and rgPendingStatus and does not return any status. + /// + /// + /// [in] An array of handles of rows for which to return the status. This array is allocated by the consumer and must not be freed by + /// the provider. + /// + /// + /// + /// [out] An array of DBPENDINGSTATUS values. IRowsetUpdate::GetRowStatus returns the DBPENDINGSTATUS values for all rows + /// specified in the rghRows array. The DBPENDINGSTATUS_INVALIDROW value is used to indicate an invalid row handle. For information + /// about the DBPENDINGSTATUS type, see Row States in Deferred Update Mode. + /// + /// The rgPendingStatus array is allocated, but not necessarily initialized, by the caller and must not be freed by the provider. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. Status values were successfully retrieved for all rows, and each element of rgPendingStatus is set to + /// DBPENDINGSTATUS_NEW, DBPENDINGSTATUS_CHANGED, DBPENDINGSTATUS_DELETED, or DBPENDINGSTATUS_UNCHANGED. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An error occurred while getting the status of a row, but the status of at least one row was successfully + /// retrieved. Successes can occur for the reasons listed under S_OK. The following error can occur: + /// + /// A row handle in rghRows was invalid. The corresponding element of rgRowStatus contains DBPENDINGSTATUS_INVALIDROW. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows was greater than zero, and either rghRows was a null pointer or rgPendingStatus 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 hReserved 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 getting the status of all of the rows. Errors can occur for the reason listed under DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724377(v=vs.85) HRESULT GetRowStatus( HCHAPTER hReserved, + // DBCOUNTITEM cRows, const HROW rghRows[], DBPENDINGSTATUS rgPendingStatus[]); + [PreserveSig] + HRESULT GetRowStatus([In] HCHAPTER hReserved, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] HROW[] rghRows, + [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] DBPENDINGSTATUS[] rgPendingStatus); + + /// Undoes any changes made to a row since it was last fetched or IRowsetUpdate::Update was called for it. + /// [in] Reserved for future use. Must be DB_NULL_HCHAPTER. + /// + /// [in] The count of rows to undo. If cRows is nonzero, IRowsetUpdate::Undo undoes all pending changes in the rows specified + /// in rghRows. If cRows is zero, IRowsetUpdate::Undo ignores rghRows and undoes all pending changes to all rows in the rowset. + /// + /// + /// [in] An array of handles of the rows to undo. Elements of this array can refer to rows with pending deletes. + /// + /// If rghRows includes a row that does not have any pending changes, IRowsetUpdate::Undo does not return an error. Instead, + /// the row remains unchanged from its original state ? which is the intention of IRowsetUpdate::Undo ? and its row status is + /// set to DBROWSTATUS_S_OK. + /// + /// + /// If rghRows includes a duplicate row, IRowsetUpdate::Undo treats the occurrences as if the row were passed to the method + /// two times sequentially. Therefore, on the first occurrence, IRowsetUpdate::Undo undoes any pending changes. On the second + /// occurrence, IRowsetUpdate::Undo treats the row as a row with no pending changes and leaves it in its current (now + /// original) state. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of rows IRowsetUpdate::Undo attempted to undo. If this is a null + /// pointer, no count of rows is returned. If the method fails with an error other than DB_E_ERRORSOCCURRED, *pcRows is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array containing the handles of all the rows IRowsetUpdate::Undo attempted + /// to undo. If rghRows is not a null pointer, the elements of this array are in one-to-one correspondence with those in rghRows. For + /// example, if a row appears twice in rghRows, it appears twice in *prgRows. When rghRows is not a null pointer, + /// IRowsetUpdate::Undo does not add to the reference count of the rows it returns in *prgRows, because the consumer already + /// has these row handles. + /// + /// + /// If rghRows is a null pointer, the elements of this array are the handles of all the rows that had pending changes, whether or not + /// IRowsetUpdate::Undo was successful at undoing those changes. The consumer checks *prgRowStatus to determine which rows + /// were undone. When rghRows is a null pointer, IRowsetUpdate::Undo adds to the reference count of the rows it returns in + /// *prgRows, because the consumer is not guaranteed to already have these row handles. A side effect of this is that rows with a + /// reference count of zero, but with pending changes at the time IRowsetUpdate::Undo is called, are brought back into + /// existence; that is, their reference count is increased to 1 and they must be rereleased. + /// + /// + /// The rowset allocates memory for the array of handles and returns the address to this memory; the consumer releases this memory + /// with IMalloc::Free when it no longer needs the handles. This argument is ignored if pcRows is a null pointer and must not + /// be a null pointer otherwise. If *pcRows is zero on output or the method fails with an error other than DB_E_ERRORSOCCURRED, the + /// provider does not allocate any memory and ensures that *prgRows is a null pointer on output. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with + /// the elements of rghRows (if rghRows is not a null pointer) or *prgRows (if rghRows is a null pointer). If no errors occur while + /// undoing a row, the corresponding element of *prgRowStatus is set to DBROWSTATUS_S_OK. If an error occurs while undoing a row, the + /// corresponding element is set as specified in DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no row status values are returned. + /// + /// + /// The rowset allocates memory for the row status values and returns the address to this memory; the consumer releases this memory + /// with IMalloc::Free when it no longer needs the row status values. This argument is ignored if cRows is zero and pcRows is + /// a null pointer. If IRowsetUpdate::Undo does not attempt to undo any rows or the method fails with an error other than + /// DB_E_ERRORSOCCURRED, the provider does not allocate any memory and ensures that *prgRowStatus is a null pointer on output. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. The changes in all rows were successfully undone. The following value can be returned in *prgRowStatus: + /// The changes in the row were successfully undone. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An error occurred while undoing the changes in a row, but the changes in at least one row were successfully + /// undone. Successes can occur for the reasons listed under S_OK. The following errors can occur: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows was not 0, and rghRows was a null pointer. + /// pcRows was not a null pointer, and prgRows was a null pointer. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return either the handles of the rows + /// IRowsetUpdate::Undo attempted to undo or the array of row status values. + /// + /// + /// + /// + /// + /// 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 hReserved 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 undoing all of the rows. The provider allocates memory for *prgRows and *prgRowStatus, + /// and the consumer checks the values in *prgRowStatus to determine why the pending changes were not undone. The consumer frees this + /// memory when it no longer needs the information. 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/ms719655(v=vs.85) HRESULT Undo ( HCHAPTER hReserved, + // DBCOUNTITEM cRows, const HROW rghRows[], DBCOUNTITEM *pcRows, HROW **prgRows, DBROWSTATUS **prgRowStatus); + [PreserveSig] + HRESULT Undo([In] HCHAPTER hReserved, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] HROW[] rghRows, + out DBCOUNTITEM pcRowsUndone, out SafeIMallocHandle prgRowsUndone, out SafeIMallocHandle prgRowStatus); + + /// + /// Transmits any changes made to an existing row since it was last fetched or IRowsetUpdate::Update was called for it. + /// Transmits a newly created row that is pending insert. + /// + /// [in] Reserved for future use. Must be DB_NULL_HCHAPTER. + /// + /// [in] The count of rows to update. If cRows is nonzero, IRowsetUpdate::Update updates all pending changes in the rows + /// specified in rghRows. If cRows is zero, IRowsetUpdate::Update ignores rghRows and updates all pending changes to all rows + /// in the rowset. + /// + /// + /// [in] An array of handles of the rows to update. + /// + /// If rghRows includes a row that does not have any pending changes, IRowsetUpdate::Update does not return an error. Instead, + /// the row remains unchanged and hence has no pending changes after Update returns ? which is the intention of Update + /// ? and the row status value associated with that row is DBROWSTATUS_S_OK. Furthermore, IRowsetUpdate::Update guarantees not + /// to transmit any value for the row to the data store. + /// + /// + /// If rghRows includes a duplicate row, IRowsetUpdate::Update behaves as follows. If the row handle is valid, no errors occur + /// and *prgRowStatus contains DBROWSTATUS_S_OK for each occurrence. If the row handle is invalid, *prgRowStatus contains the + /// appropriate error for each occurrence. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of rows IRowsetUpdate::Update attempted to update. If this is a + /// null pointer, no count of rows is returned. If the method fails with an error other than DB_E_ERRORSOCCURRED, *pcRows is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array containing the handles of all the rows IRowsetUpdate::Update + /// attempted to update. If rghRows is not a null pointer, the elements of this array are in one-to-one correspondence with those in + /// rghRows. For example, if a row appears twice in rghRows, it appears twice in *prgRows. When rghRows is not a null pointer, + /// IRowsetUpdate::Update does not add to the reference count of the rows it returns in *prgRows; the reason is that the + /// consumer already has these row handles. + /// + /// + /// If rghRows is a null pointer, the elements of this array are handles of all the rows that had pending changes, whether or not + /// IRowsetUpdate::Update was successful at transmitting those changes to the data store. The consumer checks *prgRowStatus to + /// determine which rows were updated. When rghRows is a null pointer, IRowsetUpdate::Update adds to the reference count of + /// the rows it returns in *prgRows; the reason is that the consumer is not guaranteed to already have these row handles. A side + /// effect of this is that rows with a reference count of zero, but with pending changes at the time IRowsetUpdate::Update is + /// called, are brought back into existence; that is, their reference count is increased to 1 and they must be rereleased. + /// + /// + /// The rowset allocates memory for the array of handles and returns the address to this memory; the consumer releases this memory + /// with IMalloc::Free when it no longer needs the handles. This argument is ignored if pcRows is a null pointer and must not + /// be a null pointer otherwise. If *pcRows is zero on output or the method fails with an error other than DB_E_ERRORSOCCURRED, the + /// provider does not allocate any memory and ensures that *prgRows is a null pointer on output. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with + /// the elements of rghRows (if rghRows is not a null pointer) or *prgRows (if rghRows is a null pointer). If no errors or warnings + /// occur while updating a row, the corresponding element of *prgRowStatus is set to DBROWSTATUS_S_OK. If an error or warning occurs + /// while updating a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no + /// row status values are returned. + /// + /// + /// The rowset allocates memory for the row status values and returns the address to this memory; the consumer releases this memory + /// with IMalloc::Free when it no longer needs the row status values. This argument is ignored if cRows is zero and pcRows is + /// a null pointer. If IRowsetUpdate::Update does not attempt to update any rows or the method fails with an error other than + /// DB_E_ERRORSOCCURRED, the provider does not allocate any memory and ensures that *prgRowStatus is a null pointer on output. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. The changes in all rows were successfully updated. The following values can be returned in *prgRowStatus: + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED An error occurred while updating a row, but at least one row was successfully updated. Successes can occur + /// for the reasons listed under S_OK. The following errors can occur: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows was not zero, and rghRows was a null pointer. + /// pcRows was not a null pointer, and prgRows was a null pointer on input. + /// + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return either the handles of the rows + /// IRowsetUpdate::Update attempted to update or the array of row status values. + /// + /// + /// + /// + /// + /// 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 hReserved 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 updating all of the rows. The provider allocates memory for *prgRows and *prgRowStatus, + /// and the consumer checks the values in *prgRowStatus to determine why the pending changes were not updated. The consumer frees + /// this memory when it no longer needs the information. 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/ms719709(v=vs.85) HRESULT Update ( HCHAPTER hReserved, + // DBCOUNTITEM cRows, const HROW rghRows[], DBCOUNTITEM *pcRows, HROW **prgRows, DBROWSTATUS **prgRowStatus); + [PreserveSig] + HRESULT Update([In] HCHAPTER hReserved, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] HROW[] rghRows, + out DBCOUNTITEM pcRows, out SafeIMallocHandle prgRows, out SafeIMallocHandle prgRowStatus); + } + + /// IRowsetView enables the consumer to create or apply a view to an existing rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709755(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a99-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IRowsetView + { + /// Creates a view. + /// + /// [in] A pointer to the controlling IUnknown interface if the view is being created as part of an aggregate. It is a null + /// pointer if the view is not part of an aggregate. + /// + /// [in] The IID of the interface requested on the view. + /// [out] A pointer to memory in which to return the interface pointer on the newly created view. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppView was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The view did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to create the view. + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the view object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// 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/ms723074(v=vs.85) HRESULT CreateView ( IUnknown *pUnkOuter, + // REFIID riid, IUnknown **ppView); + [PreserveSig] + HRESULT CreateView([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object? ppView); + + /// Returns a new view describing conditions applied to the specified chapter. + /// [in] The chapter from which to return the view conditions. + /// [in] The IID of the interface on which to return a pointer. + /// [out] The chapter handle to which the view was applied to create the new chapter. + /// + /// [out] A pointer to memory in which to return the interface pointer. If IRowsetView::GetView fails, it must attempt to set + /// *ppView to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE The view did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the view information. + /// + /// + /// + /// + /// DB_E_BADCHAPTER hChapter was invalid. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711261(v=vs.85) HRESULT GetView ( HCHAPTER hChapter, REFIID + // riid, HCHAPTER *phChapterSource, IUnknown **ppView); + [PreserveSig] + HRESULT GetView([In] HCHAPTER hChapter, in Guid riid, out HCHAPTER phChapterSource, [MarshalAs(UnmanagedType.IUnknown)] out object? ppView); + } + + /// + /// + /// The IScopedOperations interface supports recursive operations on a tree-structured namespace, such as a file system, that is + /// bound to an OLE DB row object. The scope of the row object is defined by the tree or subtree whose root node is bound to the row + /// object. Each node in the tree can be bound to its own row object. One of the columns in each row object can be a rowset containing a + /// row for each child of the node that is bound to the row object. The entire tree can thus be bound by a structure of row and rowset objects. + /// + /// + /// In tree-structured namespaces such as a file system or an e-mail system, each row object can be associated with a default stream + /// column that stores the contents of a file or an e-mail message. On the row object, the default stream column is identified by a + /// special constant column ID (DBID). The consumer passes this column ID as an argument to IRow::Open to get the default stream. + /// After the application has obtained the default stream from a row, it can return to the containing row by calling IGetSourceRow::GetSourceRow. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715006(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733ab0-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IScopedOperations : IBindResource + { + /// + /// Binds to an object named by a URL. When implemented on a row object, binds to a tree-structured namespace, such as a file system + /// directory, named by the URL. Returns a data source, session, rowset, row, command, or stream object. + /// + /// + /// + /// [in] If the returned object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, + /// it is a null pointer. + /// + /// + /// Note + /// + /// When IBindResource is implemented on an object other than a binder and Bind is requesting a data source or session + /// object, pUnkOuter must be a null pointer because the data source and session objects have already been created. + /// + /// + /// + /// [in] The canonical URL of the object for which an OLE DB object is to be returned. + /// + /// [in] Bitmask of bind flags that control how the OLE DB object is opened. + /// + /// + /// Flag + /// Meaning + /// + /// + /// DBBINDURLFLAG_READ + /// Open object for reading only. + /// + /// + /// DBBINDURLFLAG_WRITE + /// Open object for writing only. See note above for DBBINDURLFLAG_READ. + /// + /// + /// DBBINDURLFLAG_READWRITE + /// Open object for reading and writing. See note above for DBBINDURLFLAG_READ. + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_READ + /// Deny others read access. + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_WRITE + /// + /// Deny others write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not support + /// this type of DENY semantics. + /// + /// + /// + /// DBBINDURLFLAG_SHARE_EXCLUSIVE + /// + /// Deny others read and write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not + /// support this type of DENY semantics. + /// + /// + /// + /// DBBINDURLFLAG_SHARE_DENY_NONE + /// Do not deny others read or write access (equivalent to the omission of SHARE_DENY_READ and SHARE_DENY_WRITE). + /// + /// + /// DBBINDURLFLAG_RECURSIVE + /// + /// Modifies DBBINDURLFLAG_SHARE_*. Propagate sharing restrictions to all objects in the subtree. Has no effect when binding to leaf + /// nodes. Specifying this flag with only DBBINDURLFLAG_SHARE_DENY_NONE (or equivalently, with no SHARE_DENY flags) will result in E_INVALIDARG. + /// + /// + /// + /// DBBINDURLFLAG_OUTPUT + /// + /// Bind to the resource's executed output rather than its source. For example, this will retrieve the HTML generated by an ASP file + /// rather than its source. This flag is ignored on binds to collections. + /// + /// + /// + /// DBBINDURLFLAG_ASYNCHRONOUS + /// + /// Return immediately and perform the binding on a separate thread. If DBBINDURLFLAG_WAITFORINIT is not specified, this flag affects + /// the behavior of the IBindResource::Bind or ICreateRow::CreateRow call. If DBBINDURLFLAG_WAITFORINIT is specified, + /// this flag affects the behavior of the IDBInitialize::Initialize call. For more information, see the "Comments" section below. + /// + /// + /// + /// DBBINDURLFLAG_WAITFORINIT + /// + /// Return an interface supported on an uninitialized object, but do not initiate the bind. Used in the following cases: The consumer + /// may ask only for interfaces supported on uninitialized objects. The provider returns E_NOINTERFACE if any other interface is requested. + /// + /// + /// + /// DBBINDURLFLAG_DELAYFETCHSTREAM + /// + /// On a bind to a row, overrides the consumer's intent to immediately open the default stream. Absence of this flag is a hint to the + /// provider to instantiate the default stream object and prefetch its contents. + /// + /// + /// + /// DBBINDURLFLAG_DELAYFETCHCOLUMNS + /// + /// On a bind to a row, this flag overrides the consumer's intent to immediately access the row's columns. Absence of this flag is a + /// hint to the provider to download or prefetch the row's columns. + /// + /// + /// + /// + /// Most of the options specified by these flags can also be specified by setting DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS + /// initialization properties. (See " IBindResource::Bind Flags and Initialization Property Flags" below.) If any flags are + /// specified in dwBindURLFlags (that is, dwBindURLFlags does not equal zero), this set of flags overrides any flags that are + /// specified in DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS. If dwBindURLFlags is zero, the flags specified in DBPROP_INIT_MODE and + /// DBPROP_INIT_BINDFLAGS are used instead. + /// + /// + /// If dwBindURLFlags is zero and DBPROP_INIT_MODE is not explicitly set on the bind, the provider returns E_INVALIDARG because one + /// of DBBINDURLFLAG_READ or DBBINDURLFLAG_WRITE was not set. If dwBindURLFlags is zero and DBPROP_INIT_BINDFLAGS is not explicitly + /// set, DBPROP_INIT_BINDFLAGS defaults to zero (no options set). + /// + /// + /// Note + /// + /// The sets of flags that can be specified in DBPROP_INIT_MODE and DBPROP_INIT_BINDFLAGS are deliberately disjoint so that flags + /// from both sets can be used in the same call to IBindResource::Bind. Nevertheless, the division of flags between the two + /// properties specified below in " IBindResource::Bind Flags and Initialization Property Flags" must be honored. If the + /// client specifies flags from DBPROP_INIT_MODE in the DBPROP_INIT_BINDFLAGS property, or vice versa, they will be ignored. + /// + /// + /// + /// Not all bind flags may be used with all object types (as specified in the rguid parameter). The following table describes the + /// restrictions. If a client does not adhere to these restrictions, the bind will fail with E_INVALIDARG. + /// + /// + /// + /// Object type + /// Restrictions + /// + /// + /// DBGUID_DSO + /// Only the following flags may be used: + /// + /// + /// DBGUID_SESSION + /// Only the following flag may be used: + /// + /// + /// DBGUID_COMMAND + /// Only the following flags may be used: + /// + /// + /// DBGUID_ROW + /// No restrictions. All flags are allowed. + /// + /// + /// DBGUID_ROWSET + /// The following flags are disallowed: A consumer may bind to a rowset object, but the behavior is provider-specific. + /// + /// + /// DBGUID_STREAM + /// The following flags are disallowed: + /// + /// + /// + /// + /// [in] A pointer to a GUID indicating the type of OLE DB object to be returned. The GUID must be one of the following values: + /// + /// + /// + /// DBGUID_DSO + /// + /// + /// + /// + /// DBGUID_SESSION + /// + /// + /// + /// + /// DBGUID_COMMAND + /// + /// + /// + /// + /// DBGUID_ROW + /// + /// + /// + /// + /// DBGUID_ROWSET + /// + /// + /// + /// + /// DBGUID_STREAM + /// + /// + /// + /// + /// Note + /// When implemented on a row object, the GUID must be set to one of the following values: + /// DBGUID_ROW + /// DBGUID_ROWSET (can be requested only if the row represents a collection) + /// DBGUID_STREAM + /// + /// + /// [in] Interface ID of the interface pointer to be returned. + /// + /// [in] Optional pointer to the caller's IAuthenticate interface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// + /// [in/out] A pointer to a DBIMPLICITSESSION structure used to request and return aggregation information for the implicit session + /// object. If the bind fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL. The + /// DBIMPLICITSESSION structure is defined as follows: + /// + /// + /// + /// Element + /// Description + /// + /// + /// pUnkOuter + /// + /// If the implicit session object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. + /// Otherwise, it is a null pointer. + /// + /// + /// + /// piid + /// + /// A pointer to the IID of the interface (on the implicit session) on which to return a pointer. Cannot be NULL. If pUnkOuter + /// is not a null pointer, this IID must be IID_IUnknown. + /// + /// + /// + /// pSession + /// + /// An interface pointer to the implicit session object returned by the provider. If the session object is aggregated, this is a + /// pointer to the IUnknown interface of the inner object. + /// + /// + /// + /// + /// Note + /// + /// IBindResource::Bind uses pImplSession only when implemented on a binder object and binding to a row, rowset, or stream + /// object (rguid is DBGUID_ROW, DBGUID_ROWSET, or DBGUID_STREAM). When binding to a data source or session object (rguid is + /// DBGUID_DSO or DBGUID_SESSION), the provider ignores pImplSession because no recursive backing session is created. If implemented + /// on any other object (for example, a session or row object), the provider ignores pImplSession because the existing object already + /// has a session context. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return a bitmask containing warning status values for the requested bind flags. If + /// pdwBindStatus is a null pointer, no status values are returned. If IBindResource::Bind returns a result other than + /// DB_S_ERRORSOCCURRED and pdwBindStatus is not a null pointer, the provider returns DBBINDURLSTATUS_S_OK. The values described in + /// the following table may be returned. + /// + /// + /// + /// Status value + /// Description + /// + /// + /// DBBINDURLSTATUS_S_ DENYNOTSUPPORTED + /// + /// The bind succeeded, but the provider does not support any DENY semantics. No lock was obtained. If the consumer requires the + /// lock, it should release the object and report that a lock could not be obtained. + /// + /// + /// + /// DBBINDURLSTATUS_S_ DENYTYPENOTSUPPORTED + /// + /// The bind succeeded, but the provider does not support the requested kind of DENY semantics. For example, the provider may support + /// only DENY_WRITE or DENY_EXCLUSIVE. No lock was obtained. If the consumer requires the lock type, it should release the object and + /// report that the type of lock could not be obtained. + /// + /// + /// + /// DBBINDURLSTATUS_S_REDIRECTED + /// + /// The bind was successful, but the server for the object indicated that its URL has changed. The client should query the + /// RESOURCE_ABSOLUTEPARSENAME column on the returned object to determine the new URL. This column is available on the resource + /// rowset, so this status should be used only by document source providers. (DBPROP_DATASOURCE_TYPE is DBPROPVAL_DST_DOCSOURCE.) + /// + /// + /// + /// DBBINDURLSTATUS_S_OK + /// + /// The bind was successful and the status is reported as OK, because the provider returned a result other than DB_S_ERRORSOCCURRED + /// and pdwBindStatus was not a null pointer. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an interface pointer on the requested object. If IBindResource::Bind fails, + /// *ppUnk is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The bind succeeded. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The call to IBindResource::Bind has initiated asynchronous binding to the data source, rowset, or row. + /// The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous + /// processing. Until asynchronous processing completes, the data source, rowset, row, or stream object remains in an uninitialized state. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The bind succeeded, but some bind flags or properties were not satisfied. The consumer should examine the + /// bind status reported in *pdwBindStatus. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous binding. + /// + /// + /// + /// + /// DB_E_CANNOTCONNECT The provider could not connect to the server for this object. + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the object being created does not support aggregation. + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and pImplSession->piid did not point + /// to IID_IUnknown. + /// + /// + /// pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and the object being created does not + /// support aggregation. + /// + /// + /// IBindResource was implemented on an object other than a binder, rguid was DBGUID_DSO or DBGUID_SESSION, and pUnkOuter was + /// not a null pointer. + /// + /// + /// + /// + /// + /// + /// DB_E_NOTCOLLECTION The client requested an object type that is valid only for a collection (such as a rowset), but the resource + /// at the specified URL is not a collection. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider was unable to locate an object named by the specified URL. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid. + /// + /// + /// + /// + /// + /// DB_E_OBJECTMISMATCH The object named by rguid does not represent the resource named by pwszURL. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support this operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// DB_E_READONLY The caller requested write access to a read-only object. + /// + /// + /// + /// + /// + /// DB_E_RESOURCELOCKED One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by + /// this URL. If a provider supports extended error information, IErrorInfo::GetDescription returns a string consisting of + /// user names separated by semicolons. These are the names of the users who have the object locked. + /// + /// + /// + /// + /// + /// + /// DB_E_RESOURCEOUTOFSCOPE IBindResource is implemented on a session object, and the caller tried to bind to a URL that is + /// not within the scope of this session. + /// + /// + /// + /// + /// + /// DB_E_TIMEOUT The attempt to bind to the object timed out. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The caller's authentication context does not permit access to the object. + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and pwszURL specified an unsafe URL. + /// + /// + /// + /// + /// REGDB_E_CLASSNOTREG The root binder was unable to instantiate the provider binder. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pwszURL or ppUnk was null. + /// pImplSession was not a null pointer, and pImplSession->piid was null. + /// + /// dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the table above but did not contain the flag to be modified. + /// + /// The provider does not support one or more values of dwBindURLFlags. + /// + /// One of more of the bind flags in dwBindURLFlags are either not supported by the provider or disallowed for the object type + /// denoted by rguid. For flags allowed for each object type, see the table in the reference entry for IBindResource::Bind. + /// + /// + /// + /// + /// + /// E_NOINTERFACE The object did not support the interface specified in riid, or riid was IID_NULL. + /// The provider binder did not implement IBindResource. + /// + /// + /// + /// + /// + /// E_UNEXPECTED IBindResource::Bind is implemented on a row object; 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/ms721010(v=vs.85) + [PreserveSig] + new HRESULT Bind([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, MarshalAs(UnmanagedType.LPWStr)] string pwszURL, DBBINDURLFLAG dwBindURLFlags, + in Guid rguid, in Guid riid, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, [In, Out, Optional] IntPtr pImplSession, + out DBBINDURLSTATUS pdwBindStatus, [MarshalAs(UnmanagedType.IUnknown)] out object? ppUnk); + + /// + /// Copies trees or subtrees, designated by an array of source URLs, to the locations designated by a corresponding array of + /// destination URLs. + /// + /// + /// [in] Count of trees and subtrees named by the rgpwszSourceURLs and rgpwszDestURLs arrays. If cRows is zero, all other arguments + /// are ignored and the method returns S_OK. + /// + /// + /// [in] Array of canonical URLs naming the source trees or subtrees to be copied. If cRows is greater than zero and an element of + /// rgpwszSourceURLs is an empty string (L""), the current row object is copied. + /// + /// + /// [in] Array of canonical URLs naming the destination trees or subtrees. The elements of rgpwszDestURLs correspond to the elements + /// of rgpwszSourceURLs. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this array contains URL paths and the provider generates the + /// URL suffixes. + /// + /// + /// [in] Flags describing additional semantics for the copy operation as described in the following table. + /// + /// Note + /// Some of these flags are similar to the flags used in the Microsoft? Windows? CopyFileEx file I/O function. + /// + /// + /// + /// Flag value + /// Description + /// + /// + /// DBCOPY_ALLOW_EMULATION + /// + /// If this flag is set and the attempt to copy the tree or subtree fails because the destination URL is on a different server or + /// serviced by a different provider than the source, the provider is requested to attempt to simulate the copy using download and + /// upload operations. When moving entities between providers, this may cause increased latency or data loss due to different + /// provider capabilities. + /// + /// + /// + /// DBCOPY_ASYNC + /// + /// The copy operation is performed asynchronously. Progress and notifications are available by using IDBAsynchStatus and + /// IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. + /// + /// + /// + /// DBCOPY_ATOMIC + /// + /// Either all trees or subtrees are copied successfully or none are copied. Whether all parts of an atomic operation are attempted + /// if one part fails is provider-specific. + /// + /// + /// + /// DBCOPY_NON_RECURSIVE + /// If this flag is set, only the root node of the tree is copied; no child nodes are copied. + /// + /// + /// DBCOPY_REPLACE_EXISTING + /// + /// The copy operation succeeds even if a target object already exists at the destination URL. Otherwise, the copy fails if a target + /// object already exists. + /// + /// + /// + /// + /// + /// [in] Optional pointer to the caller's IAuthenticate interface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// + /// [out] Array of DBSTATUS status fields indicating whether each element of rgpwszSourceURLs was copied to rgpwszDestURLs. Whether + /// the status fields are set for return codes other than DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED is provider-specific. The status + /// fields described in the following table apply. + /// + /// + /// + /// Status field + /// Description + /// + /// + /// DBSTATUS_S_OK + /// Indicates that the tree or subtree was successfully copied. + /// + /// + /// DBSTATUS_E_CANCELED + /// The operation was canceled, and the provider did not complete the copy operation for this resource. + /// + /// + /// DBSTATUS_E_CANNOTCOMPLETE + /// + /// The server that owns the source URL cannot complete the operation. The provider may return this error for one of the following reasons: + /// + /// + /// + /// DBSTATUS_E_DOESNOTEXIST + /// Indicates that either the source URL or the parent of the destination URL does not exist. + /// + /// + /// DBSTATUS_E_INVALIDURL + /// A source or destination URL string contains invalid characters. + /// + /// + /// DBSTATUS_E_NOTCOLLECTION + /// + /// The destination URL contained in rgpwszDestURLs did not specify a path or collection as required by the operation. + /// + /// + /// + /// DBSTATUS_E_OUTOFSPACE + /// The provider is unable to obtain enough storage space to complete the copy operation. + /// + /// + /// DBSTATUS_E_PERMISSIONDENIED + /// Unable to access a tree or subtree because of a permissions failure. + /// + /// + /// DBSTATUS_E_RESOURCEEXISTS + /// + /// The provider was unable to perform the copy because an object already exists at the destination URL and the + /// DBCOPY_REPLACE_EXISTING flag was not set. + /// + /// + /// + /// DBSTATUS_E_RESOURCELOCKED + /// + /// One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the object named by this URL. If supported, + /// IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of the + /// users who have the object locked. + /// + /// + /// + /// DBSTATUS_E_RESOURCEOUTOFSCOPE + /// A source or destination URL is outside the scope of the current row object. + /// + /// + /// DBSTATUS_E_UNAVAILABLE + /// An atomic operation failed to complete, and status was unavailable for this part of the operation. + /// + /// + /// DBSTATUS_E_VOLUMENOTFOUND + /// The provider is unable to locate the storage volume indicated by a URL. + /// + /// + /// + /// + /// [in/out] Optional consumer-allocated array of cRows pointers to the provider-assigned and allocated canonical destination URLs. + /// The caller may pass a null value to indicate it does not want the provider to return destination URLs. This parameter should be + /// set to NULL if an error code is returned. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all generated URL strings within a single allocation block. + /// When it is finished working with the URLs, the consumer should free this buffer. Each of the individual string values stored in + /// this buffer is terminated by a null character. If cRows is zero or this method terminates due to an error, the provider sets + /// ppStringsBuffer to a null pointer. If rgpwszNewURLs is a null pointer, the consumer must set ppStringsBuffer to NULL as well. + /// + /// + /// + /// + /// + /// S_OK All requested copy operations succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated an asynchronous copy operation. The consumer can call + /// IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// DB_S_BUFFERFULL All copy operations succeeded, but the provider was unable to allocate ppStringsBuffer. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED DBCOPY_ATOMIC was not set, and the provider failed to copy from one or more source URL. The caller should + /// examine rgdwStatus to determine which source URLs were not copied and why. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous copy operations. + /// + /// + /// + /// + /// + /// DB_E_CANCELED The operation was called synchronously and, before it completed, was canceled by a call to + /// IDBAsynchStatus::Abort. The consumer can examine rgdwStatus for a status of DBSTATUS_E_CANCELED to determine whether an + /// individual URL was copied. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED DBCOPY_ATOMIC was set, and the provider failed to copy one or more source URLs. The caller should examine + /// rgdwStatus to determine which URLs were not copied and why. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support the value of dwCopyFlags. + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and one of the URLs specified was unsafe. + /// + /// + /// + /// + /// Note + /// + /// When failing one of multiple operations, the status of the failing operation is DBSTATUS_E_CANNOTCOMPLETE and the status of any + /// remaining uncompleted operations is DBSTATUS_E_UNAVAILABLE. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows is not zero; and rgpwszSourceURLs,rgpwszDestURLs, or rgdwStatus is a null pointer. + /// cRows is not zero, andone of rgpwszNewURLs and ppStringsBuffer, but not both,are null pointers. + /// cRows is not zero, and an element of rgpwszSourceURLs or rgpwszDestURLs is a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to complete the operation. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit, ITransaction::Abort, or IScopedOperations::Delete (on this row) was + /// called, and the object is in a zombie state. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711633(v=vs.85) HRESULT Copy ( DBCOUNTITEM cRows, LPCOLESTR + // rgpwszSourceURLs[ ], LPCOLESTR rgpwszDestURLs[ ], DBCOPYFLAGS dwCopyFlags, IAuthenticate *pAuthenticate, DBSTATUS rgdwStatus[ ], + // LPOLESTR rgpwszNewURLs[ ], OLECHAR **ppStringsBuffer ); + [PreserveSig] + HRESULT Copy(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgpwszSourceURLs, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgpwszDestURLs, DBCOPYFLAGS dwCopyFlags, + [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBSTATUS[] rgdwStatus, + [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] StrPtrUni[]? rgpwszNewURLs, out SafeIMallocHandle ppStringsBuffer); + + /// + /// Moves trees or subtrees that are represented by OLE DB row objects. The trees or subtrees are designated by an array of source + /// URLs and are moved to the locations designated by a corresponding array of destination URLs. + /// + /// + /// [in] Count of rows named by the rgpwszSourceURLs and rgpwszDestURLs arrays. If cRows is zero, all other arguments are ignored and + /// the method returns S_OK. + /// + /// + /// [in] Array of canonical URLs naming the trees or subtrees to be moved from the source location. If cRows is greater than zero and + /// an element of rgpwszSourceURLs is an empty string (L""), the current row object is moved. + /// + /// + /// [in] Array of canonical URLs naming the destination to which the trees or subtrees are to be moved. The elements of + /// rgpwszDestURLs correspond to the elements of rgpwszSourceURLs. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this array contains + /// URL paths and the provider generates the URL suffixes. If DBPROP_GENERATEURL is DBPROPVAL_GU_NOTSUPPORTED and the caller passes a + /// null value, the provider does not return the absolute URLs of the moved URLs. + /// + /// + /// [in] Flags describing additional semantics for the move operation as described in the following table. + /// + /// + /// Flag value + /// Description + /// + /// + /// DBMOVE_ALLOW_EMULATION + /// + /// If the attempt to move the row fails because the destination URL is on a different server or serviced by a different provider + /// than the source, the provider is requested to attempt to simulate the move using download, upload, and delete operations. When + /// moving resources between providers, this may cause increased latency or data loss due to different provider capabilities. + /// + /// + /// + /// DBMOVE_ASYNC + /// + /// The move operation is performed asynchronously. Progress and notifications are available via IDBAsynchStatus and + /// IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. + /// + /// + /// + /// DBMOVE_ATOMIC + /// + /// Either all sources are moved successfully or no sources are moved. Whether all parts of an atomic operation are attempted if one + /// part fails is provider-specific. + /// + /// + /// + /// DBMOVE_DONT_UPDATE_LINKS + /// + /// Request the server not to update links contained in an object on a move. If this flag is not specified, the default behavior is + /// to do what the server specifies. By default, IScopedOperations::Move will update links if the server is capable and if the + /// option is turned on. If the server does not have the ability to fix up links or if the option is turned off, this call will still + /// return S_OK. + /// + /// + /// + /// DBMOVE_REPLACE_EXISTING + /// + /// The move operation succeeds, even if a target object exists. Without this value, the move will fail if the target object already exists. + /// + /// + /// + /// + /// + /// [in] Optional pointer to the IAuthenticate interface. If supplied, it is provider-specific whether the + /// IAuthenticate credentials are used before or after anonymous or default login credentials are used. + /// + /// + /// + /// [out] Array of DBSTATUS status fields indicating whether each element of rgpwszSourceURLs was moved to rgpwszDestURLs. Whether + /// the status fields are set for return codes other than DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED is provider-specific. The status + /// fields described in the following table apply to the move operations. + /// + /// + /// + /// Status field + /// Description + /// + /// + /// DBSTATUS_S_OK + /// Indicates that a tree or subtree was successfully moved. + /// + /// + /// DBSTATUS_E_CANCELED + /// The operation was canceled, and the provider did not complete the move operation for this resource. + /// + /// + /// DBSTATUS_S_CANNOTDELETESOURCE + /// A tree or subtree was moved to a new location, but the source tree or subtree could not be deleted. + /// + /// + /// DBSTATUS_E_CANNOTCOMPLETE + /// + /// The server that owns the source URL cannot complete the operation. The provider may return this error for one of the following reasons: + /// + /// + /// + /// DBSTATUS_E_DOESNOTEXIST + /// Indicates that either the source URL or the parent of the destination URL does not exist. + /// + /// + /// DBSTATUS_E_INVALIDURL + /// A source or destination URL string contains invalid characters. + /// + /// + /// DBSTATUS_E_NOTCOLLECTION + /// + /// The destination URL contained in rgpwszDestURLs did not specify a path or collection as required by the operation. + /// + /// + /// + /// DBSTATUS_E_OUTOFSPACE + /// The provider is unable to obtain enough storage space to complete the move operation. + /// + /// + /// DBSTATUS_E_PERMISSIONDENIED + /// Unable to access a tree or subtree because of a permissions failure. + /// + /// + /// DBSTATUS_E_RESOURCEEXISTS + /// + /// The provider was unable to perform the move because an object already exists at the destination URL and the + /// DBMOVE_REPLACE_EXISTING flag was not set. + /// + /// + /// + /// DBSTATUS_E_RESOURCELOCKED + /// + /// One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the object named by this URL. If supported, + /// IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of the + /// users who have the object locked. + /// + /// + /// + /// DBSTATUS_E_RESOURCEOUTOFSCOPE + /// A source or destination URL is outside the scope of the current row object. + /// + /// + /// DBSTATUS_E_UNAVAILABLE + /// An atomic operation failed to complete, and status was unavailable for this part of the operation. + /// + /// + /// DBSTATUS_E_VOLUMENOTFOUND + /// The provider is unable to locate the storage volume indicated by a URL. + /// + /// + /// + /// + /// [in/out] Optional consumer-allocated array of cRows pointers to the provider-assigned and allocated canonical destination URLs. + /// The caller may pass a null value to indicate it does not want the provider to return destination URLs. This parameter should be + /// set to NULL if an error code is returned. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all generated URL strings within a single allocation block. + /// When it is finished working with the URLs, the consumer should free this buffer. Each of the individual string values stored in + /// this buffer is terminated by a null character. If cRows is zero or this method terminates due to an error, the provider sets + /// ppStringsBuffer to a null pointer. If rgpwszNewURLs is a null pointer, the consumer must set ppStringsBuffer to NULL as well. + /// + /// + /// + /// + /// + /// S_OK All requested move operations succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated an asynchronous move operation. The consumer can call + /// IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// DB_S_BUFFERFULL All move operations succeeded, but the provider was unable to allocate ppStringsBuffer. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED DBMOVE_ATOMIC was not set, and the provider failed to move one or more source URLs. The caller should examine + /// rgdwStatus to determine which source URLs were not copied from and why. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous moves. + /// + /// + /// + /// + /// + /// DB_E_CANCELED The operation was called synchronously and, before it completed, was canceled by a call to + /// IDBAsynchStatus::Abort. The consumer can examine rgdwStatus for a status of DBSTATUS_E_CANCELED to determine whether an + /// individual URL was moved. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED DBMOVE_ATOMIC was set, and the provider failed to move one or more source URLs. The caller should examine + /// rgdwStatus to determine which URLs were not moved and why. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support the value of dwMoveFlags. + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and one of the URLs specified was unsafe. + /// + /// + /// + /// + /// Note + /// + /// When failing one of multiple operations, the status of the failing operation is DBSTATUS_E_CANNOTCOMPLETE and the status of any + /// remaining, uncompleted operations is DBSTATUS_E_UNAVAILABLE. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows is not zero; and rgpwszSourceURLs,rgpwszDestURLs, or rgdwStatus is a null pointer. + /// cRows is not zero, and one of rgpwszNewURLs and ppStringsBuffer, but not both, are null pointers. + /// cRows is not zero, and an element of rgpwszSourceURLs or rgpwszDestURLs is a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to complete the operation. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit, ITransaction::Abort, or IScopedOperations::Delete (on this row) was + /// called, and the object is in a zombie state.. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720893(v=vs.85) HRESULT Move ( DBCOUNTITEM cRows, LPCOLESTR + // rgpwszSourceURLs[ ], LPCOLESTR rgpwszDestURLs[ ], DBMOVEFLAGS dwMoveFlags, IAuthenticate *pAuthenticate, DBSTATUS rgdwStatus[ ], + // LPOLESTR rgpwszNewURLs[ ], OLECHAR **ppStringsBuffer ); + [PreserveSig] + HRESULT Move(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgpwszSourceURLs, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgpwszDestURLs, DBMOVEFLAGS dwMoveFlags, + [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pAuthenticate, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBSTATUS[] rgdwStatus, + [Out, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] StrPtrUni[]? rgpwszNewURLs, out SafeIMallocHandle ppStringsBuffer); + + /// + /// Deletes the trees or subtrees named by an array of URLs. The URLs must all be within the scope of the current row object. + /// + /// + /// [in] Count of trees and subtrees named by the rgpwszURLs array. If cRows is zero, all other arguments are ignored and the method + /// returns S_OK. + /// + /// + /// [in] Array of canonical URLs naming the trees or subtrees to be deleted. If cRows is greater than zero and an element of + /// rgpwszURLs is an empty string (L""), the current row object is deleted. + /// + /// + /// [in] A bitmask of flags that control additional semantics for the delete operation, as described in the following table. + /// + /// + /// Flag value + /// Description + /// + /// + /// DBDELETE_ASYNC + /// + /// The delete operation is performed asynchronously. Progress and notifications are available via IDBAsynchStatus and + /// IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. If + /// DBDELETE_ASYNC is not specified, the operation is synchronous. A value of 0 is allowed. + /// + /// + /// + /// DBDELETE_ATOMIC + /// + /// Either all trees and subtrees are deleted or none are deleted. Whether all parts of an atomic operation are attempted if one part + /// fails is provider-specific. If DBDELETE_ATOMIC is not specified, the operation is non-atomic. A value of 0 is allowed. + /// + /// + /// + /// + /// + /// + /// [out] Array of DBSTATUS status fields indicating, for each element of rgpwszURLs, whether the tree or subtree named by that + /// element was deleted. Whether the status fields are set for return codes other than DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED is + /// provider-specific. The status fields described in the following table apply. + /// + /// + /// + /// Status field + /// Description + /// + /// + /// DBSTATUS_S_OK + /// Indicates that the tree or subtree was deleted. + /// + /// + /// DBSTATUS_E_CANCELED + /// The operation was canceled, and the provider did not complete the delete operation for this resource. + /// + /// + /// DBSTATUS_E_DOESNOTEXIST + /// Indicates that the tree or subtree named by this URL did not exist. + /// + /// + /// DBSTATUS_E_INVALIDURL + /// A URL string contained invalid characters. + /// + /// + /// DBSTATUS_E_PERMISSIONDENIED + /// Unable to access a tree or subtree due to a permissions failure. + /// + /// + /// DBSTATUS_E_RESOURCELOCKED + /// + /// One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the object named by this URL. If supported, + /// IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of the + /// users who have the object locked. + /// + /// + /// + /// DBSTATUS_E_RESOURCEOUTOFSCOPE + /// A URL to be deleted is outside the scope of the current row object. + /// + /// + /// DBSTATUS_E_UNAVAILABLE + /// An atomic operation failed to complete, and status was unavailable for this part of the operation. + /// + /// + /// DBSTATUS_E_VOLUMENOTFOUND + /// The provider is unable to locate the storage volume named by a URL. + /// + /// + /// + /// + /// + /// + /// + /// S_OK All requested deletions succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated an asynchronous delete operation. The consumer can call + /// IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED DBDELETE_ATOMIC was not set, and the provider failed to delete one or more URLs. The caller should examine + /// rgdwStatus to determine which URLs were not deleted and why. + /// + /// + /// DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see + /// DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. + /// + /// + /// + /// + /// + /// DB_E_ASYNCNOTSUPPORTED The provider does not support asynchronous deletions. + /// + /// + /// + /// + /// + /// DB_E_CANCELED The operation was called synchronously and, before it completed, was canceled by a call to + /// IDBAsynchStatus::Abort. The consumer can examine rgdwStatus for a status of DBSTATUS_E_CANCELED to determine whether an + /// individual URL was deleted. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED DBDELETE_ATOMIC was set, and the provider failed to delete one or more URLs. The caller should examine + /// rgdwStatus to determine which URLs were not deleted and why. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support the value of dwDeleteFlags. + /// + /// + /// + /// + /// DB_SEC_E_SAFEMODE_DENIED The provider was called within a safe mode or context, and one of the URLs specified was unsafe. + /// + /// + /// + /// + /// Note + /// + /// When failing one of multiple operations, the status of the failing operation is DBSTATUS_E_CANNOTCOMPLETE and the status of any + /// remaining, uncompleted operations is DBSTATUS_E_UNAVAILABLE. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cRows is not zero, and rgpwszURLs or rgdwStatus is a null pointer. + /// cRows is not zero, and an element of rgpwszURLs is a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to complete the operation. + /// + /// + /// + /// + /// 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/ms724355(v=vs.85) HRESULT Delete ( DBCOUNTITEM cRows, + // LPCOLESTR rgpwszURLs[ ], DBDELETEFLAGS dwDeleteFlags, DBSTATUS rgdwStatus[ ] ); + [PreserveSig] + HRESULT Delete(DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgpwszURLs, + DBDELETEFLAGS dwDeleteFlags, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] DBSTATUS[] rgdwStatus); + + /// + /// Opens and returns a rowset containing the child rows of the current row or of a URL-named row within the scope of the current + /// row. Due to interface and method factoring, IScopedOperations::OpenRowset is not inherited from IOpenRowset. + /// However, it is the very same method, adapted for direct binding within the scope of the current row. + /// + /// + /// [in] If the rowset is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, it is a + /// null pointer. + /// + /// + /// + /// [in] The table ID (DBID) of the table to open. When implemented on row objects, this is an absolute or relative URL within the + /// scope of the current row. If one of the following is true, pTableID designates the current row and the rowset will contain the + /// child rows of this row: + /// + /// + /// + /// + /// pTableID is NULL. + /// + /// + /// + /// + /// pTableID is not NULL, pTableID->eKind is DBKIND_NAME, and pTableID->uName.pwszName is NULL. + /// + /// + /// + /// + /// pTableID is not null, pTableID->eKind is DBKIND_NAME, and pTableID->uName.pwszName is L"". + /// + /// + /// + /// + /// + /// [in] The DBID of the index to open. Not currently used in IScopedOperations. Consumers must set pIndexID to NULL. For more + /// information, see the "Comments" section. + /// + /// + /// [in] The IID of the interface to return in *ppRowset. This interface is conceptually added to the list of required interfaces on + /// the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. This + /// must be an interface that the rowset supports, even when ppRowset is set to a null pointer and no rowset is created. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties in these structures must + /// belong to the rowset property group. If the same property is specified more than once in rgPropertySets, the value used is + /// provider-specific. If cPropertySets is zero, this argument is ignored. + /// + /// + /// For information about the rowset properties, see the rowset property group in Appendix C: OLE DB Properties. For information + /// about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [in/out] A pointer to memory in which to return the interface pointer to the created rowset. If ppRowset is a null pointer, no + /// rowset is created; properties are verified, and if a required property cannot be set, DB_E_ERRORSOCCURRED is returned. If + /// IScopedOperations::OpenRowset fails, *ppRowset is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded, and the rowset was opened. + /// + /// + /// + /// + /// + /// DB_S_ASYNCHRONOUS The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to + /// poll for status or can call IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. + /// Attempting to call any other interfaces might fail, and the full set of interfaces might not be available on the object until + /// asynchronous initialization of the rowset has completed. DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The rowset was opened, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including: + /// + /// + /// + /// + /// + /// + /// DB_S_STOPLIMITREACHED Execution has been stopped because a resource limit has been reached. The results obtained so far have been + /// returned. This return code takes precedence over DB_S_ERRORSOCCURRED; that is, if the conditions described here and 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. + /// + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED The method failed because a resource limit has been reached. For example, a query used to implement the + /// method timed out. No rowset is returned. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No rowset was returned because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties + /// for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_E_NOINDEX The specified index does not exist in the current data store or did not apply to the specified table. + /// The provider does not support opening indexes through IScopedOperations. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified URL does not exist in the data store or does not reside within the scope of the current row. + /// + /// + /// + /// + /// DB_E_NOTCOLLECTION pTableID specified a URL that does not name a collection. + /// pTableID was a null pointer or specified an empty string, and the current row is not a collection. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// DB_E_RESOURCEOUTOFSCOPE pTableID named a URL that is not within the scope of the current row. + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to open the rowset object. For example, the rowset + /// might have included a column for which the consumer does not have read permission. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID is not NULL, and pTableID->eKind is not DBKIND_NAME. + /// ppRowset was a null pointer. + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cPropertieswas not zero and rgProperties was a null pointer. + /// pIndexID was not NULL. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid, or riid was IID_NULL. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to create the rowset. + /// + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit, ITransaction::Abort, or IScopedOperations::Delete (on this row) was + /// called, and the object is in a zombie state. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms717916(v=vs.85) HRESULT OpenRowset ( IUnknown *pUnkOuter, + // DBID *pTableID, DBID *pIndexID, REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[ ], IUnknown **ppRowset ); + [PreserveSig] + HRESULT OpenRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional] IntPtr pTableID, [In, Optional] IntPtr pIndexID, + in Guid riid, uint cPropertySets, [In, Out] SafeDBPROPSETListHandle rgPropertySets, [Out, MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + } + + /// + /// + /// ISessionProperties returns information about the properties a session supports and the current settings of those properties. + /// It is a mandatory interface on sessions. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713721(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a85-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ISessionProperties + { + /// Returns the list of properties in the Session property group that are currently set on the session. + /// + /// [in] The number of DBPROPIDSET structures in rgPropertyIDSets. + /// + /// If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Session + /// property group for which values have been set or defaults exist. It does not return the values of properties in the Session + /// property group for which values have not been set and no defaults exist. + /// + /// + /// If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the + /// returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of + /// dwOptions is undefined. + /// + /// + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Session + /// property group. The provider returns the values of information about the properties specified in these structures. If + /// cPropertyIDSets is zero, this parameter is ignored. + /// + /// + /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix + /// C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets + /// is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the + /// Session property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other + /// than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero. + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is + /// returned for each property set that contains at least one property belonging to the Session property group. If cPropertyIDSets is + /// not zero, one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of + /// *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of + /// each array, the property IDs are the same. + /// + /// + /// 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 *pcPropertySets is zero on output or if an error other than + /// DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. ISessionProperties::GetProperties can fail to return + /// properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the + /// consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory + /// when it no longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723643(v=vs.85) HRESULT GetProperties ( ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); + [PreserveSig] + HRESULT GetProperties(uint cPropertyIDSets, [In] SafeDBPROPIDSETListHandle rgPropertyIDSets, + out uint pcPropertySets, out SafeDBPROPSETListHandle prgPropertySets); + + /// Sets properties in the Session property group. + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method + /// does not do anything. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Session property group. If the same property is specified more than once in rgPropertySets, the + /// value used is provider-specific. If cPropertySets is zero, this parameter is ignored. + /// + /// + /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix + /// C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the + /// DBPROP structures to determine which properties were not set. ISessionProperties::SetProperties can fail to set properties + /// for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertySets was not equal to zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED All property values were invalid, and no properties were set. The consumer checks dwStatus in the DBPROP + /// structures to determine why properties were not set. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714405(v=vs.85) HRESULT SetProperties ( ULONG cPropertySets, + // DBPROPSET rgPropertySets[]); + [PreserveSig] + HRESULT SetProperties(uint cPropertySets, [In, Out] SafeDBPROPSETListHandle? rgPropertySets); + } + + /// + /// + /// ISourcesRowset returns a rowset of data source objects and enumerators visible from the current enumerator. For more + /// information about enumerators, see Enumerators. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715969(v=vs.85) + [PInvokeData("")] + [ComImport, Guid("0c733a1e-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ISourcesRowset + { + /// Returns a rowset of the data source objects and enumerators visible from the current enumerator. + /// + /// [in] A pointer to the controlling IUnknown interface if the sources rowset is being created as part of an aggregate. If + /// the rowset is not part of an aggregate, this must be set to a null pointer. + /// + /// + /// [in] The IID of the interface on which to return a pointer. This interface is conceptually added to the list of required + /// interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, it is + /// provider-specific which value is used. If cPropertySets is 0, this argument is ignored. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix + /// C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [in] A pointer to memory in which to return the requested interface pointer on the rowset. If an error occurs, the returned + /// pointer is null. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The rowset was opened, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppSourcesRowset was a null pointer. + /// cPropertySets was not 0, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not 0 and rgProperties was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid, or riid is IID_NULL. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to create the rowset object. + /// + /// + /// + /// + /// E_UNEXPECTED The enumerator object was in an uninitialized state. + /// + /// + /// + /// + /// + /// DB_E_ABORTLIMITREACHED The method failed because a resource limit has been reached. For example, a query used to implement the + /// method timed out. No rowset is returned. + /// + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED No rowset was returned because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. None of the properties are remembered. The method can fail to set properties for any of + /// the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// + /// DB_E_NOTFOUND The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was + /// requested via riid or DBPROP_IRow, and no rows existed in the rowset. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711200(v=vs.85) HRESULT GetSourcesRowset( IUnknown + // *pUnkOuter, REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[], IUnknown **ppSourcesRowset); + [PreserveSig] + HRESULT GetSourcesRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, uint cPropertySets, + [In, Out] SafeDBPROPSETListHandle? rgPropertySets, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)] out object? ppSourcesRowset); + } + + /// ISQLErrorInfo is used to return the SQLSTATE and native error code. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711569(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a74-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ISQLErrorInfo + { + /// Returns the SQLSTATE and native error code associated with an error. + /// + /// [out] A pointer to memory in which to return a pointer to a string that contains the SQLSTATE. An SQLSTATE is a 5-character + /// string defined by the ANSI SQL standard. The memory for this string is allocated by the provider and must be freed by the + /// consumer with a call to SysFreeString. If an error occurs, *pbstrSQLState is set to a null pointer. + /// + /// + /// [out] A pointer to memory in which to return a provider-specific, native error code. *plNativeError is not necessarily the same + /// as the dwMinor element in the ERRORINFO structure returned by IErrorRecords::GetErrorInfo. The combination of the hrError + /// and dwMinor elements of the ERRORINFO structure is used to identify an error to the error lookup service, whereas *plNativeError + /// has no such restrictions. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718195(v=vs.85) HRESULT GetSQLInfo ( BSTR *pbstrSQLState, + // LONG *plNativeError); + void GetSQLInfo([MarshalAs(UnmanagedType.BStr)] out string pbstrSQLState, out int plNativeError); + } + + /// + /// The ITableCreation extends ITableDefinition to provide a full set of methods to create or describe the complete set of + /// table definition information. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713639(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733abc-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITableCreation : ITableDefinition + { + /// Creates a new base table in the data store. + /// [in] The controlling unknown if the rowset is to be aggregated; otherwise, a null pointer. + /// + /// [in] A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table. + /// + /// + /// [in] The number of DBCOLUMNDESC structures in the rgColumnDescs array. This can be zero if the provider allows the creation of + /// tables with no columns. + /// + /// + /// [in/out] An array of DBCOLUMNDESC structures that describe the columns of the table. + /// + /// The elements of this structure are used as follows. The consumer decides the values to use in the nonproperties elements of this + /// structure based on values from the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// Element + /// Description + /// + /// + /// pwszTypeName + /// + /// The provider-specific name of the data type of the column. This name corresponds to a value in the TYPE_NAME column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for pwszTypeName that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. If pwszTypeName is NULL, the provider determines the + /// type of the column based upon wType and ulColumnSize, as well as any column properties, such as DBPROP_COL_ISLONG + /// and DBPROP_COL_FIXEDLENGTH, passed in rgPropertySets. There may be some types that can only be created by specifying the + /// name in pwszTypeName because they cannot be unambiguously determined based on the wType, ulColumnSize, and + /// property values specified. + /// + /// + /// + /// pTypeInfo + /// + /// If pTypeInfo is not a null pointer, the data type of the column is an abstract data type (ADT) and values in this column + /// are actually instances of the type described by the type library. wType may be either DBTYPE_BYTES, with a length of at + /// least 4, or DBTYPE_IUNKNOWN. The instance values are required to be COM objects derived from IUnknown. + /// + /// + /// + /// rgPropertySets + /// + /// An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must + /// belong to the Column property group. All properties specified in rgPropertySets for this element of rgColumnDescs + /// apply to the column specified by dbcid; the colid element in the DBPROP structure for specified properties is + /// ignored. If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used. + /// If cPropertySets is zero, this argument is ignored. For information about the properties in the Column property group that + /// are defined by OLE DB, see "Column Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see + /// DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// pclsid + /// + /// If the column contains COM objects, a pointer to the class ID of those objects. If more than one class of objects can reside in + /// the column, * pclsid is set to IID_NULL. If the column does not contain COM objects, this is ignored and pclsid + /// should be a null pointer. + /// + /// + /// + /// cPropertySets + /// The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// ulColumnSize + /// + /// The maximum length in characters for values in this column if wType is DBTYPE_STR or DBTYPE_WSTR, or in bytes if + /// wType is DBTYPE_BYTES. If ulColumnSize is zero and a default maximum column length is defined, the provider creates + /// a column of that length. If no default is defined, the length of the created column is provider-specific. For all other values of + /// wType, ulColumnSize is ignored. Providers that do not require a length argument in the specification of the + /// provider type ( pwszTypeName) ignore this element. + /// + /// + /// + /// dbcid + /// The column ID of the column. + /// + /// + /// wType + /// + /// The type indicator for the data type of the column. This name corresponds to a value in the DATA_TYPE column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for wType that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// bPrecision + /// + /// The maximum precision of data values in the column when wType is the indicator for DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; it + /// is ignored for all other data types. This must be within the limits specified for the type in the COLUMN_SIZE column in the + /// PROVIDER_TYPES schema rowset. For information about the precision of numeric data types, see Precision of Numeric Data Types in + /// Appendix A. + /// + /// + /// + /// bScale + /// + /// The scale of data values in the column when wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; it is ignored + /// for all other data types. This must be within the limits specified for the type in the MINIMUM_SCALE and MAXIMUM_SCALE columns in + /// the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// + /// Note + /// + /// The provider does not modify any elements of the DBCOLUMNDESC structures. However, upon a return code of S_OK, + /// DB_S_ERRORSOCCURRED, or DB_E_ERRORSOCCURRED, the dwStatus element in the DBPROP structure for each column property indicates + /// whether or not that column property was set (DBPROPSTATUS_OK). + /// + /// + /// + /// + /// [in] The IID of the interface to be returned for the resulting rowset; this is ignored if ppRowset is a null pointer. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table + /// property group (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, it + /// is provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// Note + /// + /// The colid element of every DBPROP structure passed to the method must be set either to a valid DBID value or to DB_NULLID. For + /// rowset properties, the colid element of the DBPROP structure must be set either to the ID of the rowset column to which the + /// property applies or to DB_NULLID if the property applies to the entire rowset. For table properties, the property applies to the + /// entire table and therefore the colid element of the DBPROP structure must be set to DB_NULLID. + /// + /// + /// For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see Rowset Property + /// Group and Table Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure + /// and DBPROP Structure. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned. + /// + /// + /// Note + /// + /// The contents of *ppTableID might not exactly match the passed pTableID. (For example, it might contain additional version or + /// other information.) The consumer should use *ppTableID to identify the newly created table. If ppTableID is NULL on input and the + /// provider cannot create a table that exactly matches pTableID, ITableDefinition::CreateTable should fail with DB_E_BADTABLEID. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created + /// table. If ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was created and the rowset was opened, but one or more properties ? for which the dwOptions element + /// of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID and ppTableID were both null pointers. + /// + /// cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating + /// tables with no columns. + /// + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_NULL, and ppRowset was not a null pointer. + /// DB_E_BADCOLUMNIDdbcid in an element of rgColumnDescs was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid was the same in two or more elements of rgColumnDescs. + /// + /// + /// + /// + /// DB_E_DUPLICATETABLEID The specified table already exists in the current data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not created, and no rowset was returned because one or more properties ? for which the + /// dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks + /// dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of + /// the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the table. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719598(v=vs.85) HRESULT CreateTable( IUnknown *pUnkOuter, + // DBID *pTableID, DBORDINAL cColumnDescs, const DBCOLUMNDESC rgColumnDescs[], REFIID riid, ULONG cPropertySets, DBPROPSET + // rgPropertySets[], DBID **ppTableID, IUnknown **ppRowset); + [PreserveSig] + new HRESULT CreateTable([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional] IntPtr pTableID, + DBORDINAL cColumnDescs, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] DBCOLUMNDESC[]? rgColumnDescs, + in Guid riid, uint cPropertySets, [In] SafeDBPROPSETListHandle rgPropertySets, + out IntPtr ppTableID, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Drops a base table in the data store. + /// + /// + /// + /// + /// S_OK The method succeeded and the table is dropped. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the table because pTableID was referenced in a view definition. + /// The provider could not drop the table because pTableID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use and could not be dropped. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the table. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713664(v=vs.85) HRESULT DropTable ( DBID *pTableID); + [PreserveSig] + new HRESULT DropTable(in DBID pTableID); + + /// Adds a new column to a base table. + /// [in] A pointer to the DBID of the table to which the column is to be added. + /// + /// [in/out] A pointer to the DBCOLUMNDESC structure that describes the new column. For more information about the DBCOLUMNDESC + /// structure, see ITableDefinition::CreateTable. + /// + /// + /// + /// [out] A pointer to memory in which to return the returned DBID of a newly created column. If this is a null pointer, no DBID is + /// returned. If ppColumnID is non-null, the provider allocates memory for the DBID and overwrites *ppColumnID with a pointer to this + /// new DBID without regard for its current value. + /// + /// + /// Note + /// + /// The contents of *ppColumnID might not exactly match the passed dbcid in *pColumnDesc. The consumer should use *ppColumnID to + /// identify the newly created column. If ppColumnID is NULL on input and the provider cannot create a column that exactly matches + /// dbcid in *pColumnDesc, AddColumn should fail with DB_E_BADCOLUMNID. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The column was added, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnDesc was a null pointer. + /// cPropertySets was not zero, and rgPropertySets was a null pointer in the DBCOLUMNDESC structure. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID dbcid in *pColumnDesc was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid in *pColumnDesc was the same as an existing column ID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The column was not added because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP + /// structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to add a column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712851(v=vs.85) HRESULT AddColumn( DBID *pTableID, + // DBCOLUMNDESC *pColumnDesc, DBID **ppColumnID); + [PreserveSig] + new HRESULT AddColumn(in DBID pTableID, in DBCOLUMNDESC pColumnDesc, [Optional] out IntPtr ppColumnID); + + /// Drops a column from the base table. + /// [in] A pointer to the DBID of the table from which to drop the column. + /// [in] A pointer to the DBID of the column to drop. + /// + /// + /// + /// + /// S_OK The method succeeded, and the column was dropped from the base table. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnID was a null pointer. + /// + /// + /// + /// + /// DB_E_NOCOLUMN The column specified in *pColumnID does not exist in the specified table. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the column because pColumnID was referenced in a view definition. + /// + /// The provider could not drop the column because pColumnID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// The provider could not drop the column because pColumnID was referenced, along with one or more other columns, in a constraint + /// definition on pTableID. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715924(v=vs.85) HRESULT DropColumn( DBID *pTableID, DBID *pColumnID); + [PreserveSig] + new HRESULT DropColumn(in DBID pTableID, in DBID pColumnID); + + /// Returns creation information for a table. + /// [in] A pointer to the ID of the table to describe. + /// + /// [out] A pointer to the number of DBCOLUMNDESC structures in the prgColumnDescs array. If pcColumnDescs is NULL, the provider + /// ignores prgColumnDescs and does not return any column descriptions. + /// + /// + /// [out] A pointer to an array of DBCOLUMNDESC structures that describe the columns of the table, or NULL if the consumer is not + /// interested in getting back column descriptions. For more information on the DBCOLUMNDESC structure, see ITableDefinition::CreateTable. + /// + /// + /// [out] A pointer to the number of DBPROPSET structures in prgPropertySets. If this is NULL, the provider ignores prgPropertySets + /// and does not return any table creation properties. + /// + /// + /// + /// [out] A pointer to an array of DBPROPSET structures containing properties and values used in creation of the table, or NULL if + /// the consumer is not interested in getting back table creation properties. The properties returned in these structures belong to + /// the Table property group. + /// + /// + /// For information about the properties in the Tables property groups that are defined by OLE DB, see Table Property Group in + /// Appendix C: OLE DB Properties. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [out] A pointer to the number of DBCONSTRAINTDESC structures in the prgConstraintDescs array. If this is NULL, the provider + /// ignores the value of prgConstraintDescs and does not return any column descriptions. + /// + /// + /// [out] A pointer to an array of DBCONSTRAINTDESC structures that describe the columns of the table, or NULL if no constraint + /// definitions are to be returned to the consumer. For more information on DBCONSTRAINTDESC structure, see ITableDefinitionWithConstraints::AddConstraint. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values returned in the pwszTypeName element of + /// DBCOLUMNDESC structure or the pwszConstraintText element of the DBCONSTRAINTDESC structure. The provider allocates this memory + /// with IMalloc, and the consumer frees it with IMalloc::Free when it no longer needs the descriptions. If + /// ppwszStringBuffer is a null pointer on input, ITableCreation::GetTableDefinition does not return the string values. If no + /// shared memory is allocated for pwszTypeName or pwszConstraintText for any elements of prgColumnDescs or prgConstraintDescs, + /// respectively, or if an error occurs, the provider does not allocate any memory and ensures that *ppwszStringBuffer is a null + /// pointer on output. Each of the individual string values stored in this buffer is terminated by a null-termination character. + /// Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded + /// null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// pcColumnDescs was not null, and prgColumnDescs was a null pointer. + /// pcPropertySets was not null, and prgPropertySets was a null pointer. + /// pcConstraintDescs was not null, and prgConstraintDescs was a null pointer. + /// pcColumnDescs, pcPropertySets, and pcConstraintDescs were all null pointers. + /// + /// + /// + /// + /// DB_E_NOTABLE The table specified in pTableID does not exist in the current data source. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714993(v=vs.85) HRESULT GetTableDefinition( DBID *pTableID, + // DBORDINAL *pcColumnDescs, DBCOLUMNDESC *prgColumnDescs[], ULONG *pcPropertySets, DBPROPSET *prgPropertySets[], ULONG + // *pcConstraintDescs, DBCONSTRAINTDESC *prgConstraintDescs[], OLECHAR **ppwszStringBuffer); + [PreserveSig] + HRESULT GetTableDefinition(in DBID pTableID, out DBORDINAL pcColumnDescs, out SafeIMallocHandle prgColumnDescs, out uint pcPropertySets, + out SafeDBPROPSETListHandle prgPropertySets, out uint pcConstraintDescs, out SafeIMallocHandle prgConstraintDescs, + out SafeIMallocHandle ppwszStringBuffer); + } + + /// The ITableDefinition interface exposes simple methods to create, drop, and alter tables on the data store. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714277(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a86-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITableDefinition + { + /// Creates a new base table in the data store. + /// [in] The controlling unknown if the rowset is to be aggregated; otherwise, a null pointer. + /// + /// [in] A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table. + /// + /// + /// [in] The number of DBCOLUMNDESC structures in the rgColumnDescs array. This can be zero if the provider allows the creation of + /// tables with no columns. + /// + /// + /// [in/out] An array of DBCOLUMNDESC structures that describe the columns of the table. + /// + /// The elements of this structure are used as follows. The consumer decides the values to use in the nonproperties elements of this + /// structure based on values from the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// Element + /// Description + /// + /// + /// pwszTypeName + /// + /// The provider-specific name of the data type of the column. This name corresponds to a value in the TYPE_NAME column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for pwszTypeName that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. If pwszTypeName is NULL, the provider determines the + /// type of the column based upon wType and ulColumnSize, as well as any column properties, such as DBPROP_COL_ISLONG + /// and DBPROP_COL_FIXEDLENGTH, passed in rgPropertySets. There may be some types that can only be created by specifying the + /// name in pwszTypeName because they cannot be unambiguously determined based on the wType, ulColumnSize, and + /// property values specified. + /// + /// + /// + /// pTypeInfo + /// + /// If pTypeInfo is not a null pointer, the data type of the column is an abstract data type (ADT) and values in this column + /// are actually instances of the type described by the type library. wType may be either DBTYPE_BYTES, with a length of at + /// least 4, or DBTYPE_IUNKNOWN. The instance values are required to be COM objects derived from IUnknown. + /// + /// + /// + /// rgPropertySets + /// + /// An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must + /// belong to the Column property group. All properties specified in rgPropertySets for this element of rgColumnDescs + /// apply to the column specified by dbcid; the colid element in the DBPROP structure for specified properties is + /// ignored. If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used. + /// If cPropertySets is zero, this argument is ignored. For information about the properties in the Column property group that + /// are defined by OLE DB, see "Column Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see + /// DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// pclsid + /// + /// If the column contains COM objects, a pointer to the class ID of those objects. If more than one class of objects can reside in + /// the column, * pclsid is set to IID_NULL. If the column does not contain COM objects, this is ignored and pclsid + /// should be a null pointer. + /// + /// + /// + /// cPropertySets + /// The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// ulColumnSize + /// + /// The maximum length in characters for values in this column if wType is DBTYPE_STR or DBTYPE_WSTR, or in bytes if + /// wType is DBTYPE_BYTES. If ulColumnSize is zero and a default maximum column length is defined, the provider creates + /// a column of that length. If no default is defined, the length of the created column is provider-specific. For all other values of + /// wType, ulColumnSize is ignored. Providers that do not require a length argument in the specification of the + /// provider type ( pwszTypeName) ignore this element. + /// + /// + /// + /// dbcid + /// The column ID of the column. + /// + /// + /// wType + /// + /// The type indicator for the data type of the column. This name corresponds to a value in the DATA_TYPE column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for wType that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// bPrecision + /// + /// The maximum precision of data values in the column when wType is the indicator for DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; it + /// is ignored for all other data types. This must be within the limits specified for the type in the COLUMN_SIZE column in the + /// PROVIDER_TYPES schema rowset. For information about the precision of numeric data types, see Precision of Numeric Data Types in + /// Appendix A. + /// + /// + /// + /// bScale + /// + /// The scale of data values in the column when wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; it is ignored + /// for all other data types. This must be within the limits specified for the type in the MINIMUM_SCALE and MAXIMUM_SCALE columns in + /// the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// + /// Note + /// + /// The provider does not modify any elements of the DBCOLUMNDESC structures. However, upon a return code of S_OK, + /// DB_S_ERRORSOCCURRED, or DB_E_ERRORSOCCURRED, the dwStatus element in the DBPROP structure for each column property indicates + /// whether or not that column property was set (DBPROPSTATUS_OK). + /// + /// + /// + /// + /// [in] The IID of the interface to be returned for the resulting rowset; this is ignored if ppRowset is a null pointer. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table + /// property group (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, it + /// is provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// Note + /// + /// The colid element of every DBPROP structure passed to the method must be set either to a valid DBID value or to DB_NULLID. For + /// rowset properties, the colid element of the DBPROP structure must be set either to the ID of the rowset column to which the + /// property applies or to DB_NULLID if the property applies to the entire rowset. For table properties, the property applies to the + /// entire table and therefore the colid element of the DBPROP structure must be set to DB_NULLID. + /// + /// + /// For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see Rowset Property + /// Group and Table Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure + /// and DBPROP Structure. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned. + /// + /// + /// Note + /// + /// The contents of *ppTableID might not exactly match the passed pTableID. (For example, it might contain additional version or + /// other information.) The consumer should use *ppTableID to identify the newly created table. If ppTableID is NULL on input and the + /// provider cannot create a table that exactly matches pTableID, ITableDefinition::CreateTable should fail with DB_E_BADTABLEID. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created + /// table. If ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was created and the rowset was opened, but one or more properties ? for which the dwOptions element + /// of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID and ppTableID were both null pointers. + /// + /// cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating + /// tables with no columns. + /// + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_NULL, and ppRowset was not a null pointer. + /// DB_E_BADCOLUMNIDdbcid in an element of rgColumnDescs was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid was the same in two or more elements of rgColumnDescs. + /// + /// + /// + /// + /// DB_E_DUPLICATETABLEID The specified table already exists in the current data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not created, and no rowset was returned because one or more properties ? for which the + /// dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks + /// dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of + /// the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the table. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719598(v=vs.85) HRESULT CreateTable( IUnknown *pUnkOuter, + // DBID *pTableID, DBORDINAL cColumnDescs, const DBCOLUMNDESC rgColumnDescs[], REFIID riid, ULONG cPropertySets, DBPROPSET + // rgPropertySets[], DBID **ppTableID, IUnknown **ppRowset); + [PreserveSig] + HRESULT CreateTable([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional] IntPtr pTableID, + DBORDINAL cColumnDescs, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] DBCOLUMNDESC[]? rgColumnDescs, + in Guid riid, uint cPropertySets, [In] SafeDBPROPSETListHandle rgPropertySets, + out IntPtr ppTableID, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Drops a base table in the data store. + /// + /// + /// + /// + /// S_OK The method succeeded and the table is dropped. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the table because pTableID was referenced in a view definition. + /// The provider could not drop the table because pTableID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use and could not be dropped. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the table. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713664(v=vs.85) HRESULT DropTable ( DBID *pTableID); + [PreserveSig] + HRESULT DropTable(in DBID pTableID); + + /// Adds a new column to a base table. + /// [in] A pointer to the DBID of the table to which the column is to be added. + /// + /// [in/out] A pointer to the DBCOLUMNDESC structure that describes the new column. For more information about the DBCOLUMNDESC + /// structure, see ITableDefinition::CreateTable. + /// + /// + /// + /// [out] A pointer to memory in which to return the returned DBID of a newly created column. If this is a null pointer, no DBID is + /// returned. If ppColumnID is non-null, the provider allocates memory for the DBID and overwrites *ppColumnID with a pointer to this + /// new DBID without regard for its current value. + /// + /// + /// Note + /// + /// The contents of *ppColumnID might not exactly match the passed dbcid in *pColumnDesc. The consumer should use *ppColumnID to + /// identify the newly created column. If ppColumnID is NULL on input and the provider cannot create a column that exactly matches + /// dbcid in *pColumnDesc, AddColumn should fail with DB_E_BADCOLUMNID. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The column was added, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnDesc was a null pointer. + /// cPropertySets was not zero, and rgPropertySets was a null pointer in the DBCOLUMNDESC structure. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID dbcid in *pColumnDesc was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid in *pColumnDesc was the same as an existing column ID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The column was not added because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP + /// structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to add a column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712851(v=vs.85) HRESULT AddColumn( DBID *pTableID, + // DBCOLUMNDESC *pColumnDesc, DBID **ppColumnID); + [PreserveSig] + HRESULT AddColumn(in DBID pTableID, in DBCOLUMNDESC pColumnDesc, [Optional] out IntPtr ppColumnID); + + /// Drops a column from the base table. + /// [in] A pointer to the DBID of the table from which to drop the column. + /// [in] A pointer to the DBID of the column to drop. + /// + /// + /// + /// + /// S_OK The method succeeded, and the column was dropped from the base table. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnID was a null pointer. + /// + /// + /// + /// + /// DB_E_NOCOLUMN The column specified in *pColumnID does not exist in the specified table. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the column because pColumnID was referenced in a view definition. + /// + /// The provider could not drop the column because pColumnID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// The provider could not drop the column because pColumnID was referenced, along with one or more other columns, in a constraint + /// definition on pTableID. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715924(v=vs.85) HRESULT DropColumn( DBID *pTableID, DBID *pColumnID); + [PreserveSig] + HRESULT DropColumn(in DBID pTableID, in DBID pColumnID); + } + + /// + /// + /// The ITableDefinitionWithConstraints interface exposes simple methods to create, drop, and alter tables on the data store. It + /// also provides a mechanism to create and delete multitable and multicolumn constraints on tables. + /// + /// + /// ITableDefinitionWithConstraints extends ITableCreation by adding the ability to create and drop constraints from the + /// base table and create base tables with constraints in one, atomic operation. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms720947(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733aab-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITableDefinitionWithConstraints : ITableCreation + { + /// Creates a new base table in the data store. + /// [in] The controlling unknown if the rowset is to be aggregated; otherwise, a null pointer. + /// + /// [in] A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table. + /// + /// + /// [in] The number of DBCOLUMNDESC structures in the rgColumnDescs array. This can be zero if the provider allows the creation of + /// tables with no columns. + /// + /// + /// [in/out] An array of DBCOLUMNDESC structures that describe the columns of the table. + /// + /// The elements of this structure are used as follows. The consumer decides the values to use in the nonproperties elements of this + /// structure based on values from the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// Element + /// Description + /// + /// + /// pwszTypeName + /// + /// The provider-specific name of the data type of the column. This name corresponds to a value in the TYPE_NAME column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for pwszTypeName that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. If pwszTypeName is NULL, the provider determines the + /// type of the column based upon wType and ulColumnSize, as well as any column properties, such as DBPROP_COL_ISLONG + /// and DBPROP_COL_FIXEDLENGTH, passed in rgPropertySets. There may be some types that can only be created by specifying the + /// name in pwszTypeName because they cannot be unambiguously determined based on the wType, ulColumnSize, and + /// property values specified. + /// + /// + /// + /// pTypeInfo + /// + /// If pTypeInfo is not a null pointer, the data type of the column is an abstract data type (ADT) and values in this column + /// are actually instances of the type described by the type library. wType may be either DBTYPE_BYTES, with a length of at + /// least 4, or DBTYPE_IUNKNOWN. The instance values are required to be COM objects derived from IUnknown. + /// + /// + /// + /// rgPropertySets + /// + /// An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must + /// belong to the Column property group. All properties specified in rgPropertySets for this element of rgColumnDescs + /// apply to the column specified by dbcid; the colid element in the DBPROP structure for specified properties is + /// ignored. If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used. + /// If cPropertySets is zero, this argument is ignored. For information about the properties in the Column property group that + /// are defined by OLE DB, see "Column Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see + /// DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// pclsid + /// + /// If the column contains COM objects, a pointer to the class ID of those objects. If more than one class of objects can reside in + /// the column, * pclsid is set to IID_NULL. If the column does not contain COM objects, this is ignored and pclsid + /// should be a null pointer. + /// + /// + /// + /// cPropertySets + /// The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// ulColumnSize + /// + /// The maximum length in characters for values in this column if wType is DBTYPE_STR or DBTYPE_WSTR, or in bytes if + /// wType is DBTYPE_BYTES. If ulColumnSize is zero and a default maximum column length is defined, the provider creates + /// a column of that length. If no default is defined, the length of the created column is provider-specific. For all other values of + /// wType, ulColumnSize is ignored. Providers that do not require a length argument in the specification of the + /// provider type ( pwszTypeName) ignore this element. + /// + /// + /// + /// dbcid + /// The column ID of the column. + /// + /// + /// wType + /// + /// The type indicator for the data type of the column. This name corresponds to a value in the DATA_TYPE column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for wType that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// bPrecision + /// + /// The maximum precision of data values in the column when wType is the indicator for DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; it + /// is ignored for all other data types. This must be within the limits specified for the type in the COLUMN_SIZE column in the + /// PROVIDER_TYPES schema rowset. For information about the precision of numeric data types, see Precision of Numeric Data Types in + /// Appendix A. + /// + /// + /// + /// bScale + /// + /// The scale of data values in the column when wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; it is ignored + /// for all other data types. This must be within the limits specified for the type in the MINIMUM_SCALE and MAXIMUM_SCALE columns in + /// the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// + /// Note + /// + /// The provider does not modify any elements of the DBCOLUMNDESC structures. However, upon a return code of S_OK, + /// DB_S_ERRORSOCCURRED, or DB_E_ERRORSOCCURRED, the dwStatus element in the DBPROP structure for each column property indicates + /// whether or not that column property was set (DBPROPSTATUS_OK). + /// + /// + /// + /// + /// [in] The IID of the interface to be returned for the resulting rowset; this is ignored if ppRowset is a null pointer. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table + /// property group (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, it + /// is provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// Note + /// + /// The colid element of every DBPROP structure passed to the method must be set either to a valid DBID value or to DB_NULLID. For + /// rowset properties, the colid element of the DBPROP structure must be set either to the ID of the rowset column to which the + /// property applies or to DB_NULLID if the property applies to the entire rowset. For table properties, the property applies to the + /// entire table and therefore the colid element of the DBPROP structure must be set to DB_NULLID. + /// + /// + /// For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see Rowset Property + /// Group and Table Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure + /// and DBPROP Structure. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned. + /// + /// + /// Note + /// + /// The contents of *ppTableID might not exactly match the passed pTableID. (For example, it might contain additional version or + /// other information.) The consumer should use *ppTableID to identify the newly created table. If ppTableID is NULL on input and the + /// provider cannot create a table that exactly matches pTableID, ITableDefinition::CreateTable should fail with DB_E_BADTABLEID. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created + /// table. If ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was created and the rowset was opened, but one or more properties ? for which the dwOptions element + /// of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID and ppTableID were both null pointers. + /// + /// cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating + /// tables with no columns. + /// + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_NULL, and ppRowset was not a null pointer. + /// DB_E_BADCOLUMNIDdbcid in an element of rgColumnDescs was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid was the same in two or more elements of rgColumnDescs. + /// + /// + /// + /// + /// DB_E_DUPLICATETABLEID The specified table already exists in the current data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not created, and no rowset was returned because one or more properties ? for which the + /// dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks + /// dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of + /// the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the table. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719598(v=vs.85) HRESULT CreateTable( IUnknown *pUnkOuter, + // DBID *pTableID, DBORDINAL cColumnDescs, const DBCOLUMNDESC rgColumnDescs[], REFIID riid, ULONG cPropertySets, DBPROPSET + // rgPropertySets[], DBID **ppTableID, IUnknown **ppRowset); + [PreserveSig] + new HRESULT CreateTable([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional] IntPtr pTableID, + DBORDINAL cColumnDescs, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] DBCOLUMNDESC[]? rgColumnDescs, + in Guid riid, uint cPropertySets, [In] SafeDBPROPSETListHandle rgPropertySets, + out IntPtr ppTableID, [MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Drops a base table in the data store. + /// + /// + /// + /// + /// S_OK The method succeeded and the table is dropped. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the table because pTableID was referenced in a view definition. + /// The provider could not drop the table because pTableID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use and could not be dropped. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the table. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713664(v=vs.85) HRESULT DropTable ( DBID *pTableID); + [PreserveSig] + new HRESULT DropTable(in DBID pTableID); + + /// Adds a new column to a base table. + /// [in] A pointer to the DBID of the table to which the column is to be added. + /// + /// [in/out] A pointer to the DBCOLUMNDESC structure that describes the new column. For more information about the DBCOLUMNDESC + /// structure, see ITableDefinition::CreateTable. + /// + /// + /// + /// [out] A pointer to memory in which to return the returned DBID of a newly created column. If this is a null pointer, no DBID is + /// returned. If ppColumnID is non-null, the provider allocates memory for the DBID and overwrites *ppColumnID with a pointer to this + /// new DBID without regard for its current value. + /// + /// + /// Note + /// + /// The contents of *ppColumnID might not exactly match the passed dbcid in *pColumnDesc. The consumer should use *ppColumnID to + /// identify the newly created column. If ppColumnID is NULL on input and the provider cannot create a column that exactly matches + /// dbcid in *pColumnDesc, AddColumn should fail with DB_E_BADCOLUMNID. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The column was added, but one or more properties ? for which the dwOptions element of the DBPROP structure + /// was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties + /// were not set. The method can fail to set properties for a number of reasons, including: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnDesc was a null pointer. + /// cPropertySets was not zero, and rgPropertySets was a null pointer in the DBCOLUMNDESC structure. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID dbcid in *pColumnDesc was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in *pColumnDesc was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid in *pColumnDesc was the same as an existing column ID. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The column was not added because one or more properties ? for which the dwOptions element of the DBPROP + /// structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in the DBPROP + /// structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to add a column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712851(v=vs.85) HRESULT AddColumn( DBID *pTableID, + // DBCOLUMNDESC *pColumnDesc, DBID **ppColumnID); + [PreserveSig] + new HRESULT AddColumn(in DBID pTableID, in DBCOLUMNDESC pColumnDesc, [Optional] out IntPtr ppColumnID); + + /// Drops a column from the base table. + /// [in] A pointer to the DBID of the table from which to drop the column. + /// [in] A pointer to the DBID of the column to drop. + /// + /// + /// + /// + /// S_OK The method succeeded, and the column was dropped from the base table. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pColumnID was a null pointer. + /// + /// + /// + /// + /// DB_E_NOCOLUMN The column specified in *pColumnID does not exist in the specified table. + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the column because pColumnID was referenced in a view definition. + /// + /// The provider could not drop the column because pColumnID was referenced in a constraint belonging to a table other than pTableID. + /// + /// + /// The provider could not drop the column because pColumnID was referenced, along with one or more other columns, in a constraint + /// definition on pTableID. + /// + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the current data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the column. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms715924(v=vs.85) HRESULT DropColumn( DBID *pTableID, DBID *pColumnID); + [PreserveSig] + new HRESULT DropColumn(in DBID pTableID, in DBID pColumnID); + + /// Returns creation information for a table. + /// [in] A pointer to the ID of the table to describe. + /// + /// [out] A pointer to the number of DBCOLUMNDESC structures in the prgColumnDescs array. If pcColumnDescs is NULL, the provider + /// ignores prgColumnDescs and does not return any column descriptions. + /// + /// + /// [out] A pointer to an array of DBCOLUMNDESC structures that describe the columns of the table, or NULL if the consumer is not + /// interested in getting back column descriptions. For more information on the DBCOLUMNDESC structure, see ITableDefinition::CreateTable. + /// + /// + /// [out] A pointer to the number of DBPROPSET structures in prgPropertySets. If this is NULL, the provider ignores prgPropertySets + /// and does not return any table creation properties. + /// + /// + /// + /// [out] A pointer to an array of DBPROPSET structures containing properties and values used in creation of the table, or NULL if + /// the consumer is not interested in getting back table creation properties. The properties returned in these structures belong to + /// the Table property group. + /// + /// + /// For information about the properties in the Tables property groups that are defined by OLE DB, see Table Property Group in + /// Appendix C: OLE DB Properties. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// [out] A pointer to the number of DBCONSTRAINTDESC structures in the prgConstraintDescs array. If this is NULL, the provider + /// ignores the value of prgConstraintDescs and does not return any column descriptions. + /// + /// + /// [out] A pointer to an array of DBCONSTRAINTDESC structures that describe the columns of the table, or NULL if no constraint + /// definitions are to be returned to the consumer. For more information on DBCONSTRAINTDESC structure, see ITableDefinitionWithConstraints::AddConstraint. + /// + /// + /// [out] A pointer to memory in which to return a pointer to storage for all string values returned in the pwszTypeName element of + /// DBCOLUMNDESC structure or the pwszConstraintText element of the DBCONSTRAINTDESC structure. The provider allocates this memory + /// with IMalloc, and the consumer frees it with IMalloc::Free when it no longer needs the descriptions. If + /// ppwszStringBuffer is a null pointer on input, ITableCreation::GetTableDefinition does not return the string values. If no + /// shared memory is allocated for pwszTypeName or pwszConstraintText for any elements of prgColumnDescs or prgConstraintDescs, + /// respectively, or if an error occurs, the provider does not allocate any memory and ensures that *ppwszStringBuffer is a null + /// pointer on output. Each of the individual string values stored in this buffer is terminated by a null-termination character. + /// Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded + /// null-termination characters. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID was a null pointer. + /// pcColumnDescs was not null, and prgColumnDescs was a null pointer. + /// pcPropertySets was not null, and prgPropertySets was a null pointer. + /// pcConstraintDescs was not null, and prgConstraintDescs was a null pointer. + /// pcColumnDescs, pcPropertySets, and pcConstraintDescs were all null pointers. + /// + /// + /// + /// + /// DB_E_NOTABLE The table specified in pTableID does not exist in the current data source. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714993(v=vs.85) HRESULT GetTableDefinition( DBID *pTableID, + // DBORDINAL *pcColumnDescs, DBCOLUMNDESC *prgColumnDescs[], ULONG *pcPropertySets, DBPROPSET *prgPropertySets[], ULONG + // *pcConstraintDescs, DBCONSTRAINTDESC *prgConstraintDescs[], OLECHAR **ppwszStringBuffer); + [PreserveSig] + new HRESULT GetTableDefinition(in DBID pTableID, out DBORDINAL pcColumnDescs, out SafeIMallocHandle prgColumnDescs, out uint pcPropertySets, + out SafeDBPROPSETListHandle prgPropertySets, out uint pcConstraintDescs, out SafeIMallocHandle prgConstraintDescs, + out SafeIMallocHandle ppwszStringBuffer); + + /// Adds a new constraint to a base table. + /// [in] A pointer to the DBID of the table to which the constraint is to be added. + /// + /// [in] A pointer to the DBCONSTRAINTDESC structure that describes the new constraint. DBCONSTRAINTDESC is defined as follows: + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// pConstraintID + /// + /// The constraint identifier. If this is null, the provider generates a unique ID for the constraint. This ID is not returned to the + /// consumer through the DBCONSTRAINTDESC structure. Consumers should generally specify a value for the constraint and not set + /// pConstraintID to null, because there is no easy way to get back the ID for the added constraint. + /// + /// + /// + /// ConstraintType + /// The type of the constraint as defined in the DBCONSTRAINTTYPE enum. One of the following values: + /// + /// + /// cColumns + /// + /// The number of elements in the array passed in rgColumnList. For check constraints, this is always zero. If cColumns + /// is zero, rgColumnList is ignored. + /// + /// + /// + /// rgColumnList + /// + /// For unique and primary key constraints, this contains the list of columns that comprise the constraint. For foreign key + /// constraints, this defines the list of column IDs (DBIDs in the referenced table) that make up the referenced key in a + /// relationship. The order of the elements in this array comprise the key columns in descending order of significance. As such, the + /// first element is the most significant key column and the last element in the array is the least significant key column. + /// + /// + /// + /// pReferencedTableID + /// + /// For foreign keys, this contains the referenced table in a relationship. For all other types of constraints, this is null. + /// + /// + /// + /// cForeignKeyColumns + /// + /// The number of elements in the array passed in rgForeignKeyColumnList. If cForeignKeyColumns is zero, + /// rgForeignKeyColumnList is ignored. This field must be zero if pReferencedTableID is a null pointer. + /// + /// + /// + /// rgForeignKeyColumnList + /// + /// The columns (DBIDs in the base table) that comprise the foreign key in a relationship. The order of the elements in this array + /// comprise the key columns in descending order of significance. As such, the first element is the most significant key column and + /// the last element in the array is the least significant key column. This field is ignored if cForeignKeyColumns is zero. + /// + /// + /// + /// pwszConstraintText + /// The constraint clause. If ConstraintType is not DBCONSTRAINTTYPE_CHECK, this must be a null pointer. + /// + /// + /// UpdateRule + /// + /// The update rule (as defined in SQL-92). One of the following values: This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. + /// + /// + /// + /// DeleteRule + /// + /// The delete rule (as defined in SQL-92). One of the following values: This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. + /// + /// + /// + /// MatchType + /// + /// The match type (as defined in SQL-92). This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. One of + /// the following values: + /// + /// + /// + /// Deferrability + /// + /// A bitmask that describes whether application or checking of the constraint is immediate or deferred. Values are as follows: Not + /// specifying DBDEFERRABILITY_DEFERRED implies that the constraint is immediate. Not specifying DBDEFERRABILITY_ DEFERRABLE implies + /// that the constraint is not deferrable. If DBDEFERRABILITY_DEFERRABLE is not specified, the DBDEFERRABILITY_DEFERRED bit is + /// ignored and the constraint is immediate. If the constraint is immediate, the constraint is applied or checked at the end of each + /// SQL statement. If the constraint is deferred, the constraint is applied or checked when the constraint is changed to immediate, + /// either explicitly by command execution or implicitly at the end of the current transaction. + /// + /// + /// + /// cReserved + /// + /// The number of DBPROPSET structures in rgReserved. If this is zero, the provider ignores rgReserved. This parameter + /// applies to constraint properties, and consumers should set this element to 0. + /// + /// + /// + /// rgReserved + /// + /// An array of DBPROPSET structures containing properties and values to be set. If cReserved is zero, this argument is + /// ignored. This parameter applies to constraint properties, and consumers should set this element to NULL. + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pConstraintDesc was a null pointer. + /// cForeignKeyColumns was not zero, and rgForeignKeyColumnList was null. + /// cForeignKeyColumns was not zero and was not equal to cColumns. + /// cColumns was not zero, and rgColumnList was null. + /// cReserved was not zero, or rgReserved was not a null pointer. + /// + /// + /// + /// + /// + /// DB_E_NOCOLUMN The DBCONSTRAINTDESC structure contained a reference to a column ID, either in rgForeignKeyColumnList, when + /// rgForeignKeyColumnList is not ignored, or in rgColumnList, and the column was not found. This error can also be returned when the + /// column referred to by pwszConstraintText does not exist. + /// + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTFORM ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was not zero. + /// ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and pReferencedTableID was not a null pointer. + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and pReferencedTableID was NULL. + /// The type of the constraint was not a check constraint, and pwszConstraintText was not NULL. + /// ConstraintType wasDBCONSTRAINTTYPE_CHECK, and pwszConstraintText was a null pointer. + /// ConstraintType was DBCONSTRAINTTYPE_CHECK, and cColumns was not zero. + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was zero. + /// + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and the column type of a column in rgForeignKeyColumnList does not match the type + /// of the corresponding column in rgColumnList. + /// + /// + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, DBCONSTRAINTTYPE_PRIMARYKEY, or DBCONSTRAINTTYPE_UNIQUE; and cColumns was zero. + /// + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTID pConstraintID was invalid. + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTTYPE ConstraintType was invalid or not supported by the provider. + /// + /// + /// + /// + /// DB_E_BADDEFERRABILITY Deferrability was invalid, or the value was not supported by the provider. + /// + /// + /// + /// + /// DB_E_BADMATCHTYPE MatchType was not ignored and was invalid, or the value was not supported by the provider. + /// + /// + /// + /// + /// + /// DB_E_BADUPDATEDELETERULE UpdateRule or DeleteRule was not ignored and was invalid, or the value was not supported by the provider. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATECONSTRAINTID pConstraintID was the same as an existing constraint. + /// ConstraintType was DBCONSTRAINTTYPE_PRIMARYKEY, and the base table already had a primary key. + /// + /// + /// + /// + /// DB_E_NOTABLE The table specified by *pTableID does not exist in the data store. + /// The table specified by *pReferencedTableID in the DBCONSTRAINTDESC structure does not exist. + /// + /// + /// + /// + /// + /// DB_E_SCHEMAVIOLATION The type of the constraint conflicted with an attribute (for example, column type) of the referenced column. + /// + /// The constraint conflicts with current contents of the table. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not add a constraint as a result. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to add a constraint. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms711562(v=vs.85) HRESULT AddConstraint( DBID *pTableID, + // DBCONSTRAINTDESC *pConstraintDesc); + [PreserveSig] + HRESULT AddConstraint(in DBID pTableID, in DBCONSTRAINTDESC pConstraintDesc); + + /// Creates a new base table in the data store. + /// [in] The controlling unknown if the rowset is to be aggregated; otherwise, a null pointer. + /// + /// [in] A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table. + /// + /// + /// [in] The number of DBCOLUMNDESC structures in the rgColumnDescs array. This can be zero if the provider allows the creation of + /// tables with no columns. + /// + /// + /// [in/out] An array of DBCOLUMNDESC structures that describe the columns of the table. For more information on the DBCOLUMNDESC + /// structure, please refer to ITableDefinition::CreateTable. + /// + /// + /// [in] The number of DBCONSTRAINTDESC structures in the rgConstraintDescs array. If this is zero, rgConstraintDescs is ignored. + /// + /// + /// [in] An array of DBCONSTRAINTDESC structures that describe constraints to be created on the table. For more information on this + /// structure, please refer to ITableDefinitionWithConstraints::AddConstraint. + /// + /// + /// [in] The IID of the interface to be returned for the resulting rowset; this is ignored if ppRowset is a null pointer. + /// + /// + /// [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these + /// structures must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table + /// property group (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, it + /// is provider-specific which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see Rowset Property + /// Group and Table Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure + /// and DBPROP Structure. + /// + /// + /// + /// [out] A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned. + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created + /// table. If ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded, and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was created and the rowset was opened, but one or more properties ? for which the dwOptions element + /// of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to + /// determine which properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID and ppTableID were both null pointers. + /// + /// cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating + /// tables with no columns. + /// + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// cConstraintDescs was not zero, and rgConstraintDescs was a null pointer. + /// In an element of rgConstraintDescs, cForeignKeyColumns was not zero and rgForeignKeyColumnList was null. + /// In an element of rgConstraintDescs, cForeignKeyColumns was not zero and was not equal to cColumns. + /// In an element of rgConstraintDescs, cColumns was not zero and rgColumnList was null. + /// In an element of rgConstraintDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// + /// + /// + /// + /// DB_E_BADCOLUMNID dbcid in an element of rgColumnDescs was an invalid column ID. + /// + /// + /// + /// + /// + /// DB_E_NOCOLUMN The DBCONSTRAINTDESC structure contained a reference to a column ID, either in rgForeignKeyColumnList, when + /// rgForeignKeyColumnList is not ignored, or in rgColumnList, and the column was not found. + /// + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTFORM ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was not zero. + /// ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and pReferencedTableID was not a null pointer. + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and pReferencedTableID was NULL. + /// The type of the constraint was not a check constraint, and pwszConstraintText was not NULL. + /// ConstraintType wasDBCONSTRAINTTYPE_CHECK, and pwszConstraintText was a null pointer. + /// ConstraintType was DBCONSTRAINTTYPE_CHECK, and cColumns was not zero. + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was zero. + /// + /// ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, DBCONSTRAINTTYPE_PRIMARYKEY, or DBCONSTRAINTTYPE_UNIQUE and cColumns was zero. + /// + /// + /// In an element of rgColumnDescs, ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and the column type of a column in + /// rgForeignKeyColumnList does not match the type of the corresponding column in rgColumnList. + /// + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTID In an element of rgConstraintDescs, *pConstraintID was invalid. + /// + /// + /// + /// + /// DB_E_BADCONSTRAINTTYPE In an element of rgConstraintDescs, ConstraintType was invalid or not supported by the provider. + /// + /// + /// + /// + /// + /// DB_E_BADDEFERRABILITY In an element of rgConstraintDescs, Deferrability was invalid or the value was not supported by the provider. + /// + /// + /// + /// + /// + /// + /// DB_E_BADMATCHTYPE In an element of rgConstraintDescs, MatchType was not ignored and was invalid or the value was not supported by + /// the provider. + /// + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADPROPERTYVALUE The value of a property was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_BADTYPE One or more of the wType, pwszTypeName, and pTypeInfo elements in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// + /// DB_E_BADUPDATEDELETERULE In an element of rgConstraintDescs, UpdateRule or DeleteRule was not ignored and was invalid or the + /// value was not supported by the provider. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid was the same in two or more elements of rgColumnDescs. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATECONSTRAINTID In an element of rgConstraintDescs, the constraint was the same as an existing constraint, or the + /// constraint ID was the same in two or more elements. + /// + /// + /// + /// + /// + /// DB_E_DUPLICATETABLEID The specified table already exists in the data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not created and no rowset was returned because one or more properties ? for which the dwOptions + /// element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? were not set. The consumer checks dwStatus in + /// the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method + /// can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not + /// possible to set the property. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_E_NOTABLE In one or more elements of rgConstraintDescs, the table referenced by *pReferencedTableID does not exist. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set + /// to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// DB_E_SCHEMAVIOLATION The type of the constraint conflicted with an attribute (for example, column type) of the referenced column. + /// + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the table. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709819(v=vs.85) HRESULT CreateTableWithConstraints( IUnknown + // *pUnkOuter, DBID *pTableID, DBORDINAL cColumnDescs, const DBCOLUMNDESC rgColumnDescs[], ULONG cConstraintDescs, DBCONSTRAINTDESC + // rgConstraintDescs[], REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[], DBID **ppTableID, IUnknown **ppRowset); + [PreserveSig] + HRESULT CreateTableWithConstraints([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, [In, Optional] IntPtr pTableID, + DBORDINAL cColumnDescs, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] DBCOLUMNDESC[] rgColumnDescs, uint cConstraintDescs, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 4)] DBCONSTRAINTDESC[] rgConstraintDescs, in Guid riid, uint cPropertySets, + [In] SafeDBPROPSETListHandle rgPropertySets, out DBID ppTableID, [Optional, MarshalAs(UnmanagedType.IUnknown)] out object? ppRowset); + + /// Drops a constraint from a base table. + /// + /// Parameters + /// + /// + /// + /// pTableID [in] A pointer to the DBID of the table from which to drop the constraint. + /// + /// + /// + /// + /// pConstraintID [in] A pointer to the DBID of the constraint to drop. + /// + /// + /// + /// Return Code + /// + /// + /// + /// S_OK The method succeeded, and the constraint was dropped from the base table. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID or pConstraintID was a null pointer. + /// + /// + /// + /// + /// DB_E_BADTABLEID The constraint specified in *pConstraintID does not exist in the table specified in *pTableID. + /// + /// + /// + /// + /// + /// DB_E_DROPRESTRICTED The provider could not drop the constraint because there were one or more table constraints dependent on pConstraintID. + /// + /// + /// + /// + /// + /// DB_E_NOCONSTRAINT pConstraintID did not exist in the data store. + /// + /// + /// + /// + /// DB_E_NOTABLE The specified table does not exist in the data store. + /// + /// + /// + /// + /// DB_E_TABLEINUSE The specified table was in use, and the provider could not drop the constraint as a result. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to drop the constraint. + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709695(v=vs.85) HRESULT DropConstraint( DBID *pTableID, DBID *pConstraintID); + [PreserveSig] + HRESULT DropConstraint(in DBID pTableID, in DBID pConstraintID); + } + + /// + /// + /// ITransactionJoin is exposed only by providers that support distributed transactions. The consumer calls QueryInterface + /// for ITransactionJoin to determine whether the provider supports distributed transactions. For more information about + /// transactions, see Transactions (OLE DB). + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms718071(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a5e-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionJoin + { + /// Returns an object that can be used to specify configuration options for a subsequent call to ITransactionJoin::JoinTransaction. + /// + /// [out] A pointer to memory in which to return a pointer to the object that can be used to set extended transaction options. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL An unknown error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppOptions was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY Unable to allocate memory. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714338(v=vs.85) HRESULT GetOptionsObject ( + // ITransactionOptions **ppOptions); + [PreserveSig] + HRESULT GetOptionsObject(out ITransactionOptions ppOptions); + + /// Requests that the session enlist in a coordinated transaction. + /// + /// [in] A pointer to the controlling IUnknown of the transaction coordinator, or NULL to unenlist from the coordinated + /// transaction. If non-null, QueryInterface can be called for ITransaction on the transaction coordinator. If NULL, + /// the remaining arguments to the method are ignored. + /// + /// [in] The isolation level to be used with this transaction. For more information, see ITransactionLocal::StartTransaction. + /// [in] Must be zero. + /// + /// [in] Optionally a null pointer. If this is not a null pointer, it is a pointer to an object previously returned from + /// ITransactionJoin::GetOptionsObject called on this session. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN There were open Commands or Rowsets on the Session object, and the provider requires closing open objects before + /// changing transaction enlistment. + /// + /// + /// + /// + /// + /// E_FAIL An unknown error occurred. + /// + /// + /// + /// + /// E_INVALIDARG punkTransactionCoord was a null pointer, and the provider doesn't support unenlisting from a coordinated transaction. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown provider-specific error occurred. + /// + /// + /// + /// + /// XACT_E_CONNECTION_DOWN The connection to the transaction manager failed. + /// + /// + /// + /// + /// XACT_E_CONNECTION_REQUEST_DENIED The transaction manager did not accept a connection request. + /// + /// + /// + /// + /// + /// XACT_E_ISOLATIONLEVEL Neither the requested isolation level nor a strengthening of it can be supported by this transaction + /// implementation, or isoLevel was not valid. + /// + /// + /// + /// + /// + /// XACT_E_LOGFULL Unable to begin a new transaction because the log file is full. + /// + /// + /// + /// + /// XACT_E_NOENLIST A transaction coordinator was specified, but the new transaction was unable to enlist therein. + /// + /// + /// + /// + /// + /// XACT_E_NOISORETAIN The requested semantics of retention of isolation across retaining commit and abort boundaries cannot be + /// supported by this transaction implementation, or isoFlags was not equal to zero. + /// + /// + /// + /// + /// + /// XACT_E_NOTIMEOUT A time-out was specified, but time-outs are not supported. + /// + /// + /// + /// + /// XACT_E_TMNOTAVAILABLE Unable to connect to the transaction manager, or the transaction manager is unavailable. + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The enlistment request failed for one of the following reasons: + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709749(v=vs.85) HRESULT JoinTransaction ( IUnknown + // *punkTransactionCoord, ISOLEVEL isoLevel, ULONG isoFlags, ITransactionOptions *pOtherOptions); + [PreserveSig] + HRESULT JoinTransaction([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? punkTransactionCoord, ISOLEVEL isoLevel, + [Optional] uint isoFlags, [In, Optional] ITransactionOptions? pOtherOptions); + } + + /// + /// ITransactionLocal is an optional interface on sessions. It is used to start, commit, and abort transactions on the session. + /// For more information, see Simple Transactions. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714893(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a5f-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionLocal : ITransaction + { + /// Commits a transaction. + /// + /// [in] Whether the commit is retaining or nonretaining. + /// + /// Note + /// + /// A retaining commit or abort should not change the characteristics (isolation level, isolation flags, transaction options) of the + /// transaction. The new unit of work retains the same characteristics as the committed work. + /// + /// + /// + /// + /// + /// [in] Values taken from the enumeration XACTTC. Values that may be specified in grfTC are as follows. These values are mutually exclusive. + /// + /// + /// + /// Flag + /// Description + /// + /// + /// XACTTC_ASYNC_PHASEONE + /// When this flag is specified, an asynchronous commit is performed. + /// + /// + /// XACTTC_SYNC_PHASEONE + /// + /// When this flag is specified, the call to ITransaction::Commit returns after phase one of the two-phase commit protocol. + /// + /// + /// + /// XACTTC_SYNC_PHASETWO + /// + /// When this flag is specified, the call to ITransaction::Commit returns after phase two of the two-phase commit protocol. + /// + /// + /// + /// XACTTC_SYNC + /// Synonym for XACTTC_SYNC_PHASETWO. + /// + /// + /// + /// [in] Must be zero. + /// + /// + /// + /// + /// S_OK The transaction was successfully committed. + /// + /// + /// + /// + /// + /// XACT_S_ASYNC An asynchronous commit was specified. The commit operation has begun, but its outcome is not yet known. When the + /// transaction is complete, notification will be sent by ITransactionOutcomeEvents. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. The transaction was aborted. + /// + /// + /// + /// + /// E_UNEXPECTED An unexpected error occurred. The transaction status is unknown. + /// + /// + /// + /// + /// XACT_E_ABORTED The transaction was implicitly aborted before ITransaction::Commit was called. + /// + /// + /// + /// + /// XACT_E_ALREADYINPROGRESS A commit or abort operation was already in progress. This call was ignored. + /// + /// + /// + /// + /// + /// XACT_E_CANTRETAIN Retaining commit is not supported, or a new unit of work could not be created. The commit succeeded and the + /// session is in auto-commit mode. + /// + /// Commit was called on a distributed transaction with fRetaining set to TRUE. + /// + /// + /// + /// + /// XACT_E_COMMITFAILED The transaction failed to commit for an unknown reason. The transaction was aborted. + /// + /// + /// + /// + /// XACT_E_CONNECTION_DOWN The connection to the transaction manager failed. The transaction was aborted. + /// + /// + /// + /// + /// + /// XACT_E_INDOUBT The transaction status is in doubt. A communication failure occurred, or a transaction manager or resource manager + /// has failed. + /// + /// + /// + /// + /// + /// + /// XACT_E_NOTRANSACTION Unable to commit the transaction because it had already been explicitly committed or aborted. This call was ignored. + /// + /// + /// + /// + /// + /// + /// XACT_E_NOTSUPPORTED An invalid combination of commit flags was specified, or grfRM was not equal to zero. This call was ignored. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713008(v=vs.85) HRESULT Commit( BOOL fRetaining, DWORD + // grfTC, DWORD grfRM); + [PreserveSig] + new HRESULT Commit(bool fRetaining, XACTTC grfTC, uint grfRM = 0); + + /// + /// + /// + /// Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, + /// Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista + /// + /// This method aborts the transaction. + /// + /// + /// [in] An optional BOID that indicates why the transaction is being aborted. This argument may be NULL indicating that no abort + /// reason is provided. + /// + /// [in] Must be FALSE. + /// + /// [in] When fAsync is TRUE, an asynchronous abort is performed and the caller must use ITransactionOutcomeEvents to learn + /// the outcome of the transaction. + /// + /// + /// + /// The initiator of the transaction may abort the transaction as may any resource manager enlisted on the transaction. + /// + /// Abort may be invoked on a transaction repeatedly. XACT_S_ABORTING HRESULT will be returned following the first invocation + /// of Abort. + /// + /// If a communication failure occurs during a call to Commit or Abort, the status of the transaction is unknown. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms688267(v=vs.85) HRESULT Abort( BOID * pboidReason, BOOL + // fRetaining, BOOL fAsync); + [PreserveSig] + new HRESULT Abort([In, Optional] IntPtr pboidReason, bool fRetaining, bool fAsync); + + /// Returns information regarding a transaction. + /// + /// + /// [out] A pointer to the caller-allocated XACTTRANSINFO structure in which the method returns information about the transaction. + /// pInfo must not be a null pointer. + /// + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// uow + /// The unit of work associated with this transaction. Cannot be NULL and must be unique per transaction. + /// + /// + /// isoLevel + /// + /// The isolation level associated with this transaction. ISOLATIONLEVEL_UNSPECIFIED indicates that no isolation level was specified. + /// For more information, see ITransactionLocal::StartTransaction. + /// + /// + /// + /// isoFlags + /// Will be zero. + /// + /// + /// grfTCSupported + /// This bitmask indicates the XACTTC flags that this transaction implementation supports. + /// + /// + /// grfRMSupported + /// Will be zero. + /// + /// + /// grfTCSupportedRetaining + /// Will be zero. + /// + /// + /// grfRMSupportedRetaining + /// Will be zero. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pInfo was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred. No information is returned. + /// + /// + /// + /// + /// + /// XACT_E_NOTRANSACTION Unable to retrieve information for the transaction because it was already completed. No information is returned. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714975(v=vs.85) HRESULT GetTransactionInfo( XACTTRANSINFO *pInfo); + [PreserveSig] + new HRESULT GetTransactionInfo(out XACTTRANSINFO pInfo); + + /// Returns an object that can be used to specify configuration options for a subsequent call to ITransactionLocal::StartTransaction. + /// + /// [out] A pointer to memory in which to return a pointer to the object that can be used to set extended transaction options. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_E_NOTSUPPORTED The provider does not support ITransactionOptions. A call to ITransactionLocal::GetOptionsObject should + /// return DB_E_NOTSUPPORTED for 2.6-compliant providers and later. For earlier providers, the return code is unspecified. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppOptions was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY Unable to allocate memory. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred, and the method failed. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713719(v=vs.85) HRESULT GetOptionsObject ( + // ITransactionOptions **ppOptions); + [PreserveSig] + HRESULT GetOptionsObject(out ITransactionOptions ppOptions); + + /// Begins a new transaction. + /// + /// [in] The isolation level to be used with this transaction. For more information, see Isolation Levels in OLE DB. + /// + /// + /// Value + /// Description + /// + /// + /// ISOLATIONLEVEL_UNSPECIFIED + /// + /// Applicable only to ITransactionJoin::JoinTransaction. Invalid for ITransactionLocal or for setting isolation level while + /// in auto-commit mode. + /// + /// + /// + /// ISOLATIONLEVEL_CHAOS + /// Cannot overwrite the dirty data of other transactions at higher isolation levels. + /// + /// + /// ISOLATIONLEVEL_READUNCOMMITTED + /// Read Uncommitted. + /// + /// + /// ISOLATIONLEVEL_BROWSE + /// Synonym for ISOLATIONLEVEL_READUNCOMMITTED. + /// + /// + /// ISOLATIONLEVEL_READCOMMITTED + /// Read Committed. + /// + /// + /// ISOLATIONLEVEL_CURSORSTABILITY + /// Synonym for ISOLATIONLEVEL_READCOMMITTED. + /// + /// + /// ISOLATIONLEVEL_REPEATABLEREAD + /// Repeatable Read. + /// + /// + /// ISOLATIONLEVEL_SERIALIZABLE + /// Serializable. + /// + /// + /// ISOLATIONLEVEL_ISOLATED + /// Synonym for ISOLATIONLEVEL_SERIALIZABLE. + /// + /// + /// + /// [in] Must be zero. + /// + /// [in] Optionally a null pointer. If this is not a null pointer, it is a pointer to an object previously returned from + /// ITransactionLocal::GetOptionsObject called on this session instance. + /// + /// + /// [out] A pointer to memory in which to return the level of the new transaction. The value of the top-level transaction is 1. If + /// pulTransactionLevel is a null pointer, the level is not returned. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN A rowset object was open, and the provider does not support starting a new transaction with existing open rowset objects. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred, and the method failed. + /// + /// + /// + /// + /// + /// XACT_E_CONNECTION_DENIED This session could not create a new transaction at the present time due to unspecified capacity issues. + /// + /// + /// + /// + /// + /// XACT_E_CONNECTION_DOWN This session is having communication difficulties with its internal implementation. + /// + /// + /// + /// + /// + /// XACT_E_ISOLATIONLEVEL Neither the requested isolation level nor a strengthening of it can be supported by this transaction + /// implementation, or isoLevel was not valid. + /// + /// + /// + /// + /// + /// + /// XACT_E_LOGFULL A transaction could not be created because this session specifies logging to a device that lacks available space. + /// + /// + /// + /// + /// + /// + /// XACT_E_NOISORETAIN The requested semantics of retention of isolation across retaining commit and abort boundaries cannot be + /// supported by this transaction implementation, or isoFlags was not equal to zero. + /// + /// + /// + /// + /// + /// XACT_E_NOTIMEOUT A noninfinite time-out value was requested, but time-outs are not supported by this transaction. + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS This session can handle only one extant transaction at a time, and there is presently such a transaction. + /// The session supports a limited number of nested transactions, and that limit has been reached. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709786(v=vs.85) HRESULT StartTransaction ( ISOLEVEL + // isoLevel, ULONG isoFlags, ITransactionOptions *pOtherOptions, ULONG *pulTransactionLevel); + [PreserveSig] + HRESULT StartTransaction(ISOLEVEL isoLevel, [Optional] ISOFLAG isoFlags, [In, Optional] ITransactionOptions? pOtherOptions, out uint pulTransactionLevel); + } + + /// + /// ITransactionObject enables consumers to obtain the transaction object associated with a particular transaction level. For more + /// information, see ITransaction Object. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713659(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a60-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionObject + { + /// Returns an interface pointer on the transaction object. + /// [in] The level of the transaction. + /// [out] A pointer to memory in which to return a pointer to the returned transaction object. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ulTransactionLevel was zero, or ppTransactionObject was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred, and the method failed. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms712995(v=vs.85) HRESULT GetTransactionObject ( ULONG + // ulTransactionLevel, ITransaction **ppTransactionObject); + [PreserveSig] + HRESULT GetTransactionObject(uint ulTransactionLevel, out ITransaction? ppTransactionObject); + } + + /// IViewChapter enables the consumer to create or apply a view to an existing rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms724248(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a98-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewChapter + { + /// Returns the rowset from which the view was created. + /// [in] The IID of the interface on which to return a pointer. + /// + /// [out] A pointer to memory in which to return the interface pointer. If IViewChapter::GetSpecification fails, it must + /// attempt to set *ppRowset to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE The view did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the rowset information. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716976(v=vs.85) HRESULT GetSpecification ( REFIID riid, + // IUnknown **ppRowset); + [PreserveSig] + HRESULT GetSpecification(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object? ppRowset); + + /// Returns a chapter for the rows meeting the specified view conditions. + /// + /// [in] A chapter defining the set of rows on which to apply the view. To apply a view to the root rowset, the consumer must use DB_NULL_HCHAPTER. + /// + /// + /// [out] A chapter reflecting the specified view conditions, or NULL to indicate that the view conditions should be applied to hSource. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// DB_E_BADCHAPTER hSource was invalid. + /// + /// + /// + /// + /// + /// DB_E_CANTFILTER The described filter could not be opened. The provider may have limitations on the columns used in a filter or a + /// limitation on the complexity of the filter. + /// + /// + /// + /// + /// + /// + /// DB_E_CANTORDER The described order could not be opened. The provider may have limitations on the columns used in an order or a + /// limitation on the complexity of the order. + /// + /// + /// + /// + /// + /// DB_E_BADCOMPAREOP A specified comparison operator was invalid. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716852(v=vs.85) HRESULT OpenViewChapter ( HCHAPTER hSource, + // HCHAPTER *phViewChapter); + [PreserveSig] + HRESULT OpenViewChapter([In] HCHAPTER hSource, [Optional] IntPtr phViewChapter); + } + + /// IViewFilter enables consumers to restrict the contents of a rowset to rows matching a set of conditions. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722601(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a9b-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewFilter + { + /// Retrieves the filter applied to a view. + /// + /// [in] A row data accessor describing the data to be written to ppCriteriaData. The same column may appear more than one time in + /// the criteria. + /// + /// + /// [out] A pointer to memory in which to write the number of rows in the criteria table, where the criteria described by each row is + /// joined in a logical OR with the other rows. If pcRows is greater than one, the cbRowSize argument used in the call to + /// IAccessor::CreateAccessor is used to specify the offset between each set of row values. + /// + /// + /// + /// [out] A pointer to memory in which to write a two-dimensional array of comparisons operators. The two-dimensional array contains + /// pcRows by cBindings comparison operators in pcRows-major format, where cBindings is the number of columns represented in + /// hAccessor, and is written in row-major format. Each comparison operator in the cBindings dimension refers to a column in + /// pCriteriaData, and each set of columns in the pcRows dimension refers to a row in pCriteriaData. Columns within a row are joined + /// together in a logical AND, and each row is joined in a logical OR with another row. For information about the + /// DBCOMPAREOP enumerated type, see IRowsetFind::FindNextRow. + /// + /// + /// Note + /// + /// If the consumer set the filter using IViewFilter::SetFilter, it knows the maximum size of the comparison operator array + /// and can allocate memory for it accordingly. If the consumer was passed the view, it needs to allocate sufficiently large buffers + /// to hold these arrays. + /// + /// + /// + /// + /// [out] A pointer to a buffer in which to return the criteria data. + /// + /// Note + /// + /// If the consumer set the filter using IViewFilter::SetFilter, it knows the maximum size of the criteria data array and can + /// allocate memory for it accordingly. If the consumer was passed the view, it needs to allocate sufficiently large buffers to hold + /// these arrays. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// + /// 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_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the filter information. + /// + /// + /// + /// + /// DB_E_BADACCESSORHANDLE hAccessor was invalid. Providers are required to check for this condition in this method. + /// + /// + /// + /// + /// DB_E_BADACCESSORTYPE The specified accessor was not a row accessor. + /// + /// + /// + /// + /// DB_E_BADCOMPAREOP In an element of pCompareOps, both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE were specified. + /// The provider was asked for an option that it does not support. + /// + /// + /// + /// + /// + /// 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/ms709726(v=vs.85) HRESULT GetFilter ( HACCESSOR hAccessor, + // DBCOUNTITEM *pcRows, DBCOMPAREOP *pCompareOps[], void *pCriteriaData); + [PreserveSig] + HRESULT GetFilter(HACCESSOR hAccessor, out DBCOUNTITEM pcRows, [Out, MarshalAs(UnmanagedType.LPArray)] DBCOMPAREOPS[,] pCompareOps, [Out] IntPtr pCriteriaData); + + /// Retrieves the bindings used to describe the filter conditions associated with a view. + /// + /// [out] A pointer to memory in which to return the number of bindings used to describe the filter criteria. If this method fails or + /// if no filter has been applied to the view, *pcBindings is set to zero. + /// + /// + /// [out] A pointer to memory in which to return an array of DBBINDING structures. One structure is returned for each binding used to + /// describe the filter criteria. 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 bindings. If *pcBindings is zero on output or + /// the method fails, the provider does not allocate any memory and ensures that *prgBindings is a null pointer on output. For + /// information about bindings, see DBBINDING Structures. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcBindings or prgBindings was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the binding structures. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723078(v=vs.85) HRESULT GetFilterBindings( DBCOUNTITEM + // *pcBindings, DBBINDING **prgBindings); + [PreserveSig] + HRESULT GetFilterBindings(out DBCOUNTITEM pcBindings, out SafeIMallocHandle prgBindings); + + /// Specifies a filter condition for a view. + /// + /// [in] The handle of the accessor that describes the data in pCriteriaData. The same column may appear more than once in the criteria. + /// + /// + /// [in] The number of rows in the criteria table, where the criteria described by each row is joined in a logical OR with the other + /// rows. Some providers may have limits on the number of rows (OR conditions) that can be expressed in the criteria. + /// + /// + /// + /// [in] A two-dimensional array containing cRows by cBindings comparison operators in cRows-major format, where cBindings is the + /// number of columns represented in hAccessor. Each comparison operator in the cBindings dimension refers to a column in + /// pCriteriaData, and each set of columns in the pcRows dimension refers to a row in pCriteriaData. Columns within a row are joined + /// together in a logical AND, and each row is joined in a logical OR with another row. The consumer should check + /// DBPROP_FINDCOMPAREOPS to determine which comparison operators the provider supports. For information about the DBCOMPAREOP + /// enumerated type, see IRowsetFind::FindNextRow. + /// + /// + /// Note + /// The expression column DBCOMPAREOPS_IGNORE value always resolves to TRUE when used with the IViewFilter::SetFilter. + /// + /// + /// + /// [in] A pointer to memory containing the data values, at offsets that correspond to the bindings in the accessor that, in + /// conjunction with the array of comparison operators, define the criteria. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// DB_E_BADCOMPAREOP In an element of CompareOps, both DBCOMPAREOPS_CASESENSITIVE and DBCOMPAREOPS_CASEINSENSITIVE were specified. + /// The provider was asked for an option that it does not support. + /// + /// + /// + /// + /// + /// DB_E_CANTFILTER The described filter could not be applied. The provider may have limitations on the columns used in a filter or a + /// limitation on the complexity of the filter. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719693(v=vs.85) HRESULT SetFilter ( HACCESSOR hAccessor, + // DBCOUNTITEM cRows, DBCOMPAREOP CompareOps[], void *pCriteriaData); + [PreserveSig] + HRESULT SetFilter([In] HACCESSOR hAccessor, DBCOUNTITEM cRows, [In, MarshalAs(UnmanagedType.LPArray)] DBCOMPAREOPS[] CompareOps, [In] IntPtr pCriteriaData); + } + + /// IViewRowset enables the consumer to create or apply view operations when opening a rowset. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713657(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a97-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewRowset + { + /// Returns the object from which the view was created. + /// + /// [in] The IID of the interface to be returned. This interface is conceptually added to the list of required interfaces on the + /// resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset. + /// + /// + /// [out] A pointer to memory in which to return the interface pointer. If IViewRowset::GetSpecification fails, it must + /// attempt to set *ppObject to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_NOINTERFACE The view did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the object information. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms716967(v=vs.85) HRESULT GetSpecification ( REFIID riid, + // IUnknown **ppObject); + [PreserveSig] + HRESULT GetSpecification(in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 0)] out object? ppObject); + + /// Creates a rowset from a view. + /// + /// [in] A pointer to the controlling IUnknown interface if the new rowset is being created as part of an aggregate. It is a + /// null pointer if the rowset is not part of an aggregate. + /// + /// [in] The IID of the interface requested on the rowset. + /// + /// [out] A pointer to memory in which to return the interface pointer on the newly created rowset. If + /// IViewRowset::OpenViewRowset fails, *ppRowset is set to a null pointer. + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG ppRowset was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider did not have enough memory to create the rowset. + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723079(v=vs.85) HRESULT OpenViewRowset ( IUnknown + // *pUnkOuter, REFIID riid, IUnknown **ppRowset); + [PreserveSig] + HRESULT OpenViewRowset([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pUnkOuter, in Guid riid, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 1)] out object? ppRowset); + } + + /// IViewSort enables the consumer to apply a sort order to a view. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714371(v=vs.85) + [PInvokeData("oledb.h")] + [ComImport, Guid("0c733a9a-2a1c-11ce-ade5-00aa0044773d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IViewSort + { + /// Retrieves the sort order applied to a view. + /// [out] Count of the number of columns in the sort order. + /// + /// [out] The ordinals of the columns used to describe the sort. The order of the columns in the list defines the precedence of the + /// columns in the sort. + /// + /// [out] The sort order for the corresponding column in the prgColumns list. + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pcColumns, prgColumns, or prgOrders was NULL. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the sort information. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722756(v=vs.85) HRESULT GetSortOrder ( DBORDINAL *pcColumns, + // DBORDINAL *prgColumns[], DBSORT *prgOrders[]); + [PreserveSig] + HRESULT GetSortOrder(out DBORDINAL pcColumns, out SafeIMallocHandle prgColumns, out SafeIMallocHandle prgOrders); + + /// Specifies a sort order to be applied to a view. + /// + /// [in] Count of the number of columns to be used in specifying the order, or zero to clear any sort order previously set on the view. + /// + /// + /// [in] The ordinals of the columns used to describe the sort. The order of the columns in the list defines the precedence of the + /// columns in the sort. This argument is ignored if cColumns is zero. + /// + /// + /// [in] The sort order for the corresponding column in the rgColumns list. This argument is ignored if cColumns is zero. + /// The DBSORT structure is as follows: + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG rgColumns was NULL, and cColumns was not equal to zero. + /// rgOrders was NULL, and cColumns was not equal to zero. + /// + /// + /// + /// + /// + /// DB_E_CANTORDER The described order could not be opened. The provider may have limitations on the columns used in an order or a + /// limitation on the complexity of the order. + /// + /// The same column ordinal appeared multiple times in rgColumns. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722623(v=vs.85) HRESULT SetSortOrder ( DBORDINAL cColumns, + // const DBORDINAL rgColumns[], const DBSORT rgOrders[]); + [PreserveSig] + HRESULT SetSortOrder(DBORDINAL cColumns, [In, MarshalAs(UnmanagedType.LPArray)] DBORDINAL[]? rgColumns, [In, MarshalAs(UnmanagedType.LPArray)] DBSORT[]? rgOrders); + } + + /// Creates a new base table in the data store. + /// The type of the rowset interface to return. + /// The instance. + /// [in] The controlling unknown if the rowset is to be aggregated; otherwise, a null pointer. + /// + /// [in] A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table. + /// + /// + /// [in/out] An array of DBCOLUMNDESC structures that describe the columns of the table. + /// + /// The elements of this structure are used as follows. The consumer decides the values to use in the nonproperties elements of this + /// structure based on values from the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// Element + /// Description + /// + /// + /// pwszTypeName + /// + /// The provider-specific name of the data type of the column. This name corresponds to a value in the TYPE_NAME column in the + /// PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for pwszTypeName that is + /// different from the values listed in the PROVIDER_TYPES schema rowset. If pwszTypeName is NULL, the provider determines the + /// type of the column based upon wType and ulColumnSize, as well as any column properties, such as DBPROP_COL_ISLONG and + /// DBPROP_COL_FIXEDLENGTH, passed in rgPropertySets. There may be some types that can only be created by specifying the name in + /// pwszTypeName because they cannot be unambiguously determined based on the wType, ulColumnSize, and property + /// values specified. + /// + /// + /// + /// pTypeInfo + /// + /// If pTypeInfo is not a null pointer, the data type of the column is an abstract data type (ADT) and values in this column are + /// actually instances of the type described by the type library. wType may be either DBTYPE_BYTES, with a length of at least 4, + /// or DBTYPE_IUNKNOWN. The instance values are required to be COM objects derived from IUnknown. + /// + /// + /// + /// rgPropertySets + /// + /// An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong + /// to the Column property group. All properties specified in rgPropertySets for this element of rgColumnDescs apply to the + /// column specified by dbcid; the colid element in the DBPROP structure for specified properties is ignored. If the same + /// property is specified more than once in rgPropertySets, it is provider-specific which value is used. If cPropertySets + /// is zero, this argument is ignored. For information about the properties in the Column property group that are defined by OLE DB, see + /// "Column Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// pclsid + /// + /// If the column contains COM objects, a pointer to the class ID of those objects. If more than one class of objects can reside in the + /// column, * pclsid is set to IID_NULL. If the column does not contain COM objects, this is ignored and pclsid should be a + /// null pointer. + /// + /// + /// + /// cPropertySets + /// The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. + /// + /// + /// ulColumnSize + /// + /// The maximum length in characters for values in this column if wType is DBTYPE_STR or DBTYPE_WSTR, or in bytes if wType + /// is DBTYPE_BYTES. If ulColumnSize is zero and a default maximum column length is defined, the provider creates a column of that + /// length. If no default is defined, the length of the created column is provider-specific. For all other values of wType, + /// ulColumnSize is ignored. Providers that do not require a length argument in the specification of the provider type ( + /// pwszTypeName) ignore this element. + /// + /// + /// + /// dbcid + /// The column ID of the column. + /// + /// + /// wType + /// + /// The type indicator for the data type of the column. This name corresponds to a value in the DATA_TYPE column in the PROVIDER_TYPES + /// schema rowset. In most cases, there is no reason for a consumer to specify a value for wType that is different from the values + /// listed in the PROVIDER_TYPES schema rowset. + /// + /// + /// + /// bPrecision + /// + /// The maximum precision of data values in the column when wType is the indicator for DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; it is + /// ignored for all other data types. This must be within the limits specified for the type in the COLUMN_SIZE column in the + /// PROVIDER_TYPES schema rowset. For information about the precision of numeric data types, see Precision of Numeric Data Types in + /// Appendix A. + /// + /// + /// + /// bScale + /// + /// The scale of data values in the column when wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; it is ignored for + /// all other data types. This must be within the limits specified for the type in the MINIMUM_SCALE and MAXIMUM_SCALE columns in the + /// PROVIDER_TYPES schema rowset. + /// + /// + /// + /// + /// Note + /// + /// The provider does not modify any elements of the DBCOLUMNDESC structures. However, upon a return code of S_OK, DB_S_ERRORSOCCURRED, + /// or DB_E_ERRORSOCCURRED, the dwStatus element in the DBPROP structure for each column property indicates whether or not that column + /// property was set (DBPROPSTATUS_OK). + /// + /// + /// + /// + /// + /// [in/out] An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures + /// must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table property group + /// (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, it is provider-specific + /// which value is used. If cPropertySets is zero, this argument is ignored. + /// + /// + /// Note + /// + /// The colid element of every DBPROP structure passed to the method must be set either to a valid DBID value or to DB_NULLID. For rowset + /// properties, the colid element of the DBPROP structure must be set either to the ID of the rowset column to which the property applies + /// or to DB_NULLID if the property applies to the entire rowset. For table properties, the property applies to the entire table and + /// therefore the colid element of the DBPROP structure must be set to DB_NULLID. + /// + /// + /// For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see Rowset Property Group + /// and Table Property Group in Appendix C. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure. + /// + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned. + /// + /// + /// Note + /// + /// The contents of *ppTableID might not exactly match the passed pTableID. (For example, it might contain additional version or other + /// information.) The consumer should use *ppTableID to identify the newly created table. If ppTableID is NULL on input and the provider + /// cannot create a table that exactly matches pTableID, ITableDefinition::CreateTable should fail with DB_E_BADTABLEID. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created table. If + /// ppRowset is a null pointer, no rowset is created. + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED The table was created and the rowset was opened, but one or more properties ? for which the dwOptions element of + /// the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. The consumer checks dwStatus in the DBPROP structures to determine + /// which properties were not set. The method can fail to set properties for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pTableID and ppTableID were both null pointers. + /// + /// cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating + /// tables with no columns. + /// + /// cPropertySets was not zero, and rgPropertySets was a null pointer. + /// In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer. + /// In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer. + /// + /// + /// + /// + /// E_NOINTERFACE The rowset did not support the interface specified in riid. + /// riid was IID_NULL, and ppRowset was not a null pointer. + /// DB_E_BADCOLUMNIDdbcid in an element of rgColumnDescs was an invalid column ID. + /// + /// + /// + /// + /// DB_E_BADTABLEID *pTableID was an invalid table ID. + /// + /// + /// + /// + /// DB_E_BADPRECISION The precision in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADSCALE The scale in an element of rgColumnDescs was invalid. + /// + /// + /// + /// + /// DB_E_BADTYPE The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid. + /// In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType. + /// + /// + /// + /// + /// DB_E_DUPLICATECOLUMNID dbcid was the same in two or more elements of rgColumnDescs. + /// + /// + /// + /// + /// DB_E_DUPLICATETABLEID The specified table already exists in the current data store. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED The table was not created, and no rowset was returned because one or more properties ? for which the dwOptions + /// element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value ? could not be set. The consumer checks dwStatus in + /// the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of the reasons + /// specified in DB_S_ERRORSOCCURRED. + /// + /// + /// + /// + /// + /// + /// DB_E_NOAGGREGATION pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support + /// aggregation of the rowset object being created. + /// + /// pUnkOuter was not a null pointer, and riid was not IID_IUnknown. + /// + /// + /// + /// + /// DB_SEC_E_PERMISSIONDENIED The consumer did not have sufficient permission to create the table. + /// + /// + /// + /// + /// + /// DB_E_OBJECTOPEN The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE. + /// + /// + /// + /// + /// + /// + /// XACT_E_XTIONEXISTS The provider supports transactional DDL, the session is participating in a transaction, and the value of + /// DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML. + /// + /// + /// + /// + /// + public static HRESULT CreateTable(this ITableDefinition td, [In, Optional] object? pUnkOuter, [In, Optional] DBID? pTableID, + [In, Optional] DBCOLUMNDESC[]? rgColumnDescs, [In, Optional] DBPROPSET[]? rgPropertySets, out DBID? ppTableID, out T? ppRowset) where T : class + { + var hr = td.CreateTable(pUnkOuter, (SafeCoTaskMemStruct)pTableID, (uint)(rgColumnDescs?.Length ?? 0), rgColumnDescs, typeof(T).GUID, + (uint)(rgPropertySets?.Length ?? 0), rgPropertySets, out var ptid, out object? rowset); + ppTableID = ptid.ToNullableStructure(); + ppRowset = (T?)rowset; + return hr; + } + + /// Returns information about the index rowset capabilities. + /// The instance. + /// + /// + /// [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 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) + public static HRESULT GetIndexInfo(this IRowsetIndex ri, out DBINDEXCOLUMNDESC[] prgIndexColumnDesc, out DBPROPSET[] prgIndexPropertySets) + { + HRESULT hr = ri.GetIndexInfo(out var pcKeyColumns, out var pIndexColumnDesc, out var pcIndexPropertySets, out var pIndexPropertySets); + prgIndexColumnDesc = pcKeyColumns == 0 ? [] : pIndexColumnDesc.ToArray((int)pcKeyColumns); + prgIndexPropertySets = pcIndexPropertySets == 0 ? [] : pIndexPropertySets.ToArray((int)pcIndexPropertySets); + return hr; + } + + /// Returns the current settings of all properties supported by the rowset. + /// The instance. + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Rowset + /// property group. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this + /// parameter is ignored. + /// + /// + /// For information about the properties in the Rowset property group that are defined by OLE DB, see Rowset Properties in Appendix C. + /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned + /// for each property set that contains at least one property belonging to the Rowset property group. If cPropertyIDSets is not zero, one + /// structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets + /// are returned in the same order as the DBPROPID values in rgPropertyIDs. Therefore, in the case where no column properties are + /// specified in rgPropertyIDSets, corresponding elements of the input rgPropertyIDs and the returned rgProperties have the same property + /// ID. However, if a column property is requested in rgPropertyIDSets, multiple properties may be returned, one for each column, in + /// rgProperties. In this case, corresponding elements of rgPropertyIDs and rgProperties will not have the same property ID and + /// rgProperties will contain more elements than rgPropertyIDs. + /// + /// + /// 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 *pcPropertySets is zero on output or if an error other than DB_E_ERRORSOCCURRED + /// occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. IRowsetInfo::GetProperties can fail to return properties for a + /// number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// E_UNEXPECTED ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer + /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no + /// longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms719611(v=vs.85) HRESULT GetProperties ( const ULONG + // cPropertyIDSets, const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); + public static HRESULT GetProperties(this IRowsetInfo i, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) + { + var hr = i.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); + mem.Count = (int)c; + prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; + return hr; + } + + /// Returns the list of properties in the Session property group that are currently set on the session. + /// The instance. + /// + /// + /// [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Session + /// property group. The provider returns the values of information about the properties specified in these structures. If cPropertyIDSets + /// is zero, this parameter is ignored. + /// + /// + /// For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix C. + /// For information about the DBPROPIDSET structure, see DBPROPIDSET Structure. + /// + /// + /// + /// + /// [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned + /// for each property set that contains at least one property belonging to the Session property group. If cPropertyIDSets is not zero, + /// one structure is returned for each property set specified in rgPropertyIDSets. + /// + /// + /// If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET + /// structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If + /// cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets + /// are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of each array, the + /// property IDs are the same. + /// + /// + /// 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 *pcPropertySets is zero on output or if an error other than DB_E_ERRORSOCCURRED + /// occurs, the provider does not allocate any memory and ensures that *prgPropertySets 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. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK. + /// + /// + /// + /// + /// + /// DB_S_ERRORSOCCURRED No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to + /// determine the properties for which values were not returned. ISessionProperties::GetProperties can fail to return properties + /// for a number of reasons, including the following: + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer. + /// pcPropertySets or prgPropertySets was a null pointer. + /// In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer. + /// + /// + /// + /// + /// E_OUTOFMEMORY The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures. + /// + /// + /// + /// + /// + /// DB_E_ERRORSOCCURRED Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer + /// checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no + /// longer needs the information. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms723643(v=vs.85) HRESULT GetProperties ( ULONG cPropertyIDSets, + // const DBPROPIDSET rgPropertyIDSets[], ULONG *pcPropertySets, DBPROPSET **prgPropertySets); + public static HRESULT GetProperties(this ISessionProperties sp, DBPROPIDSET[] rgPropertyIDSets, out DBPROPSET[] prgPropertySets) + { + var hr = sp.GetProperties((uint)rgPropertyIDSets.Length, rgPropertyIDSets, out var c, out var mem); + mem.Count = (int)c; + prgPropertySets = c > 0 && !mem.IsInvalid ? mem : []; + return hr; + } + + /// Basic information about the error, such as the return code and provider-specific error number. + [PInvokeData("oledb.h")] + [StructLayout(LayoutKind.Sequential)] + public struct ERRORINFO + { + /// Undocumented. + public HRESULT hrError; + + /// Undocumented. + public uint dwMinor; + + /// Undocumented. + public Guid clsid; + + /// Undocumented. + public Guid iid; + + /// Undocumented. + public int dispid; + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/Transact.cs b/PInvoke/OleDb/Transact.cs new file mode 100644 index 00000000..cd235a73 --- /dev/null +++ b/PInvoke/OleDb/Transact.cs @@ -0,0 +1,861 @@ +#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member + +using System.Runtime.CompilerServices; + +namespace Vanara.PInvoke; + +public static partial class OleDb +{ + /// infinite time-out value + public const uint XACTCONST_TIMEOUTINFINITE = 0; + + /// The ISOFLAG enumeration values specify certain flags for a transaction. + [PInvokeData("transact.h")] + [Flags] + public enum ISOFLAG + { + /// Use just one of ISOFLAG_RETAIN_COMMIT values. + ISOFLAG_RETAIN_COMMIT_DC = 1, + + /// + ISOFLAG_RETAIN_COMMIT = 2, + + /// + ISOFLAG_RETAIN_COMMIT_NO = 3, + + /// Use just one of ISOFLAG_RETAIN_ABORT values. + ISOFLAG_RETAIN_ABORT_DC = 4, + + /// + ISOFLAG_RETAIN_ABORT = 8, + + /// + ISOFLAG_RETAIN_ABORT_NO = 12, + + /// + ISOFLAG_RETAIN_DONTCARE = ISOFLAG_RETAIN_COMMIT_DC | ISOFLAG_RETAIN_ABORT_DC, + + /// + ISOFLAG_RETAIN_BOTH = ISOFLAG_RETAIN_COMMIT | ISOFLAG_RETAIN_ABORT, + + /// + ISOFLAG_RETAIN_NONE = ISOFLAG_RETAIN_COMMIT_NO | ISOFLAG_RETAIN_ABORT_NO, + + /// + ISOFLAG_OPTIMISTIC = 16, + + /// + ISOFLAG_READONLY = 32 + } + + /// The ISOLATIONLEVEL enumeration values specify the isolation levels of a transaction. + [PInvokeData("transact.h")] + public enum ISOLEVEL : uint + { + /// + /// No isolation level was specified. Any isolation level is supported. A downstream component that has this isolation level always + /// uses the same isolation level that its immediate upstream component uses. If the root object in a transaction has its isolation + /// level configured to ISOLATIONLEVEL_UNSPECIFIED, its isolation level becomes ISOLATIONLEVEL_SERIALIZABLE. + /// + ISOLATIONLEVEL_UNSPECIFIED = 0xffffffff, + + /// No isolation level is used. It is not safe to use this level of isolation. + ISOLATIONLEVEL_CHAOS = 0x10, + + /// + /// A transaction can read any data, even if it is being modified by another transaction. Any type of new data can be inserted during + /// a transaction. This is the least safe isolation level but allows the highest concurrency. + /// + ISOLATIONLEVEL_READUNCOMMITTED = 0x100, + + /// Same as ISOLATIONLEVEL_READUNCOMMITTED. + ISOLATIONLEVEL_BROWSE = 0x100, + + /// Same as ISOLATIONLEVEL_READCOMMITTED. + ISOLATIONLEVEL_CURSORSTABILITY = 0x1000, + + /// + /// A transaction cannot read data that is being modified by another transaction that has not committed. Any type of new data can be + /// inserted during a transaction. This is the default isolation level in Microsoft SQL Server. + /// + ISOLATIONLEVEL_READCOMMITTED = 0x1000, + + /// + /// Data read by a current transaction cannot be changed by another transaction until the current transaction finishes. Any type of + /// new data can be inserted during a transaction. + /// + ISOLATIONLEVEL_REPEATABLEREAD = 0x10000, + + /// + /// Data read by a current transaction cannot be changed by another transaction until the current transaction finishes. No new data + /// can be inserted that would affect the current transaction. This is the safest isolation level and is the default, but allows the + /// lowest level of concurrency. + /// + ISOLATIONLEVEL_SERIALIZABLE = 0x100000, + + /// Same as ISOLATIONLEVEL_SERIALIZABLE. + ISOLATIONLEVEL_ISOLATED = 0x100000 + } + + /// Specifies any configuration or startup options for the transaction manager object. + [PInvokeData("xolehlp.h")] + [Flags] + public enum OLE_TM : uint + { + /// + /// External callers should use this flag if they want the default behavior (which is to demand start DTC). This approach provides + /// meaningful text and is preferable to directly using the value 0 for i_grfOptions. + /// + OLE_TM_FLAG_NONE = 0x00000000, + + /// Callers can specify this option if they do not want demand start of DTC. + OLE_TM_FLAG_NODEMANDSTART = 0x00000001, + + /// + /// If this flag is set, the application specifies that it does not wish to take advantage of any features that need agile recovery + /// support. As a consequence, the application will be restricted to using the default transaction manager on a cluster.
+ /// + OLE_TM_FLAG_NOAGILERECOVERY = 0x00000002, + + /// + /// Specifying this flag will cause DTC to query the lock status and fail demand start if someone else is holding SCM lock. This flag + /// should not be used by external callers. + /// + OLE_TM_FLAG_QUERY_SERVICE_LOCKSTATUS = 0x80000000, + + /// + /// Only components internal to the Transaction manager (such as XATM) should use this flag. This flag should not be used by external callers. + /// + OLE_TM_FLAG_INTERNAL_TO_TM = 0x40000000, + } + + [PInvokeData("transact.h")] + public enum XACTHEURISTIC + { + XACTHEURISTIC_ABORT = 1, + XACTHEURISTIC_COMMIT = 2, + XACTHEURISTIC_DAMAGE = 3, + XACTHEURISTIC_DANGER = 4 + } + + [PInvokeData("transact.h")] + public enum XACTRM + { + XACTRM_OPTIMISTICLASTWINS = 1, + XACTRM_NOREADONLYPREPARES = 2 + } + + [PInvokeData("transact.h")] + [Flags] + public enum XACTSTAT + { + XACTSTAT_NONE, + XACTSTAT_OPENNORMAL = 0x1, + XACTSTAT_OPENREFUSED = 0x2, + XACTSTAT_PREPARING = 0x4, + XACTSTAT_PREPARED = 0x8, + XACTSTAT_PREPARERETAINING = 0x10, + XACTSTAT_PREPARERETAINED = 0x20, + XACTSTAT_COMMITTING = 0x40, + XACTSTAT_COMMITRETAINING = 0x80, + XACTSTAT_ABORTING = 0x100, + XACTSTAT_ABORTED = 0x200, + XACTSTAT_COMMITTED = 0x400, + XACTSTAT_HEURISTIC_ABORT = 0x800, + XACTSTAT_HEURISTIC_COMMIT = 0x1000, + XACTSTAT_HEURISTIC_DAMAGE = 0x2000, + XACTSTAT_HEURISTIC_DANGER = 0x4000, + XACTSTAT_FORCED_ABORT = 0x8000, + XACTSTAT_FORCED_COMMIT = 0x10000, + XACTSTAT_INDOUBT = 0x20000, + XACTSTAT_CLOSED = 0x40000, + XACTSTAT_OPEN = 0x3, + XACTSTAT_NOTPREPARED = 0x7ffc3, + XACTSTAT_ALL = 0x7ffff + } + + [PInvokeData("transact.h")] + [Flags] + public enum XACTTC + { + XACTTC_NONE, + XACTTC_SYNC_PHASEONE = 1, + XACTTC_SYNC_PHASETWO = 2, + XACTTC_SYNC = 2, + XACTTC_ASYNC_PHASEONE = 4, + XACTTC_ASYNC = 4 + } + + /// The ITransaction interface is used to commit and abort transactions and to obtain status information about transactions. + /// + /// You obtain a pointer to this interface by calling the ITransactionDispenser::BeginTransaction method or the + /// ITransactionImport::Import method. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms686531(v=vs.85) + [PInvokeData("transact.h")] + [ComImport, Guid("0fb15084-af41-11ce-bd2b-204c4f4f5020"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransaction + { + /// Commits a transaction. + /// + /// [in] Whether the commit is retaining or nonretaining. + /// + /// Note + /// + /// A retaining commit or abort should not change the characteristics (isolation level, isolation flags, transaction options) of the + /// transaction. The new unit of work retains the same characteristics as the committed work. + /// + /// + /// + /// + /// + /// [in] Values taken from the enumeration XACTTC. Values that may be specified in grfTC are as follows. These values are mutually exclusive. + /// + /// + /// + /// Flag + /// Description + /// + /// + /// XACTTC_ASYNC_PHASEONE + /// When this flag is specified, an asynchronous commit is performed. + /// + /// + /// XACTTC_SYNC_PHASEONE + /// + /// When this flag is specified, the call to ITransaction::Commit returns after phase one of the two-phase commit protocol. + /// + /// + /// + /// XACTTC_SYNC_PHASETWO + /// + /// When this flag is specified, the call to ITransaction::Commit returns after phase two of the two-phase commit protocol. + /// + /// + /// + /// XACTTC_SYNC + /// Synonym for XACTTC_SYNC_PHASETWO. + /// + /// + /// + /// [in] Must be zero. + /// + /// + /// + /// + /// S_OK The transaction was successfully committed. + /// + /// + /// + /// + /// + /// XACT_S_ASYNC An asynchronous commit was specified. The commit operation has begun, but its outcome is not yet known. When the + /// transaction is complete, notification will be sent by ITransactionOutcomeEvents. + /// + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. The transaction was aborted. + /// + /// + /// + /// + /// E_UNEXPECTED An unexpected error occurred. The transaction status is unknown. + /// + /// + /// + /// + /// XACT_E_ABORTED The transaction was implicitly aborted before ITransaction::Commit was called. + /// + /// + /// + /// + /// XACT_E_ALREADYINPROGRESS A commit or abort operation was already in progress. This call was ignored. + /// + /// + /// + /// + /// + /// XACT_E_CANTRETAIN Retaining commit is not supported, or a new unit of work could not be created. The commit succeeded and the + /// session is in auto-commit mode. + /// + /// Commit was called on a distributed transaction with fRetaining set to TRUE. + /// + /// + /// + /// + /// XACT_E_COMMITFAILED The transaction failed to commit for an unknown reason. The transaction was aborted. + /// + /// + /// + /// + /// XACT_E_CONNECTION_DOWN The connection to the transaction manager failed. The transaction was aborted. + /// + /// + /// + /// + /// + /// XACT_E_INDOUBT The transaction status is in doubt. A communication failure occurred, or a transaction manager or resource manager + /// has failed. + /// + /// + /// + /// + /// + /// + /// XACT_E_NOTRANSACTION Unable to commit the transaction because it had already been explicitly committed or aborted. This call was ignored. + /// + /// + /// + /// + /// + /// + /// XACT_E_NOTSUPPORTED An invalid combination of commit flags was specified, or grfRM was not equal to zero. This call was ignored. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms713008(v=vs.85) HRESULT Commit( BOOL fRetaining, DWORD + // grfTC, DWORD grfRM); + [PreserveSig] + HRESULT Commit(bool fRetaining, XACTTC grfTC, uint grfRM = 0); + + /// + /// + /// + /// Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, + /// Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista + /// + /// This method aborts the transaction. + /// + /// + /// [in] An optional BOID that indicates why the transaction is being aborted. This argument may be NULL indicating that no abort + /// reason is provided. + /// + /// [in] Must be FALSE. + /// + /// [in] When fAsync is TRUE, an asynchronous abort is performed and the caller must use ITransactionOutcomeEvents to learn + /// the outcome of the transaction. + /// + /// + /// + /// The initiator of the transaction may abort the transaction as may any resource manager enlisted on the transaction. + /// + /// Abort may be invoked on a transaction repeatedly. XACT_S_ABORTING HRESULT will be returned following the first invocation + /// of Abort. + /// + /// If a communication failure occurs during a call to Commit or Abort, the status of the transaction is unknown. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms688267(v=vs.85) HRESULT Abort( BOID * pboidReason, BOOL + // fRetaining, BOOL fAsync); + [PreserveSig] + HRESULT Abort([In, Optional] IntPtr pboidReason, bool fRetaining, bool fAsync); + + /// Returns information regarding a transaction. + /// + /// + /// [out] A pointer to the caller-allocated XACTTRANSINFO structure in which the method returns information about the transaction. + /// pInfo must not be a null pointer. + /// + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// uow + /// The unit of work associated with this transaction. Cannot be NULL and must be unique per transaction. + /// + /// + /// isoLevel + /// + /// The isolation level associated with this transaction. ISOLATIONLEVEL_UNSPECIFIED indicates that no isolation level was specified. + /// For more information, see ITransactionLocal::StartTransaction. + /// + /// + /// + /// isoFlags + /// Will be zero. + /// + /// + /// grfTCSupported + /// This bitmask indicates the XACTTC flags that this transaction implementation supports. + /// + /// + /// grfRMSupported + /// Will be zero. + /// + /// + /// grfTCSupportedRetaining + /// Will be zero. + /// + /// + /// grfRMSupportedRetaining + /// Will be zero. + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pInfo was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred. No information is returned. + /// + /// + /// + /// + /// + /// XACT_E_NOTRANSACTION Unable to retrieve information for the transaction because it was already completed. No information is returned. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714975(v=vs.85) HRESULT GetTransactionInfo( XACTTRANSINFO *pInfo); + [PreserveSig] + HRESULT GetTransactionInfo(out XACTTRANSINFO pInfo); + } + + /// + /// This interface contains two methods. The BeginTransaction method creates new transaction objects. The GetOptionsObject + /// method creates new transaction options objects. + /// + /// + /// Call the DtcGetTransactionManager function with an riid of IID_ITransactionDispenser when initially connecting to DTC. You can also + /// call QueryInterface on any interface on the DTC proxy core object with an riid of IID_ITransactionDispenser. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms687604(v=vs.85) + [PInvokeData("transact.h")] + [ComImport, Guid("3A6AD9E1-23B9-11cf-AD60-00AA00A74CCD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionDispenser + { + /// This method creates a transaction options object. + /// + /// [out] Pointer to the pointer to the ITransactionOptions interface on the transaction options object. Must not be NULL. + /// + /// + /// + /// + /// The transaction options object obtained from the GetOptionsObject call can be assigned transaction attributes by calling + /// the ITransactionOptions::SetOptions method. The transaction options object can then be passed to + /// ITransactionDispenser::BeginTransaction. The transaction attributes from the transaction options object will be inherited by the + /// newly created transaction object. + /// + /// A process may create as many transaction options objects as it wishes. + /// + /// Two or more threads may simultaneously invoke the BeginTransaction method using the same transaction options object. + /// However, the attributes of the transaction options object must not be changed while the object is in use by the + /// BeginTransaction method. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms679525(v=vs.85) HRESULT GetOptionsObject( + // ITransactionOptions ** ppOptions); + [PreserveSig] + HRESULT GetOptionsObject(out ITransactionOptions? ppOptions); + + /// This method initiates a new transaction and returns a new transaction object which represents the transaction. + /// [in] Must be NULL. + /// + /// [in] The isolation level to be used for this transaction, specified by the ISOLATIONLEVEL enumeration. This value is ignored by + /// DTC and passed on to the resource managers. + /// + /// [in] Values from ISOFLAG enumeration. + /// + /// [in] A pointer to a transaction options object. This value may be NULL. If pOptions is NULL the time-out value for the + /// transaction is infinite and the transaction will not have a description. + /// + /// [out] Pointer to the pointer to the ITransaction interface on the new transaction object. + /// + /// + /// A transaction options object which is passed as a parameter to BeginTransaction must not be altered while the + /// BeginTransaction method invocation is outstanding. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms686676(v=vs.85) HRESULT BeginTransaction( IUnknown * + // punkOuter, ISOLEVEL isoLevel, ULONG isoFlags, ITransactionOptions * pOptions, ITransaction ** ppTransaction); + [PreserveSig] + HRESULT BeginTransaction([In, Optional] object? punkOuter, ISOLEVEL isoLevel, ISOFLAG isoFlags, + [In, Optional] ITransactionOptions? pOptions, out ITransaction? ppTransaction); + } + + /// + /// This interface contains methods that control the attributes of new transactions such as their time-out periods and descriptions. + /// + /// This interface is used to get and set attributes within a transaction options object. The transaction options object can be passed as + /// a parameter to the ITransactionDispenser::BeginTransaction method. The attributes of the transaction options object are inherited by + /// the newly initiated transaction. This lets the caller of the BeginTransaction method to control the attributes of a + /// transaction such as its time-out period and transaction description. + /// + /// + /// This interface is also used to get the transaction option attributes of an existing transaction object. It cannot be used to set the + /// attributes, because the transaction has already begun. + /// + /// + /// You obtain a pointer to this interface by calling the ITransactionDispenser::GetOptionsObject method. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms684388(v=vs.85) + [PInvokeData("transact.h")] + [ComImport, Guid("3A6AD9E0-23B9-11cf-AD60-00AA00A74CCD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionOptions + { + /// Sets a suite of options associated with a transaction. + /// + /// [in] A pointer to an XACTOPT structure containing the options to be set in this transaction. This cannot be a null pointer. + /// The elements of this structure are used as described in the following table. + /// + /// + /// Element + /// Description + /// + /// + /// ulTimeout + /// + /// The amount of real time in milliseconds before the transaction is to be aborted automatically. Zero indicates an infinite + /// time-out. If no options have been previously set, ulTimeout is zero. + /// + /// + /// + /// szDescription + /// + /// A pointer to a textual description associated with this transaction. This string is appropriate for display in various end-user + /// administration tools that might monitor or log the transaction. If no options have been previously set, szDescription is + /// an empty string. + /// + /// + /// + /// + /// + /// + /// + /// + /// S_OK The method succeeded. + /// + /// + /// + /// + /// E_FAIL A provider-specific error occurred. + /// + /// + /// + /// + /// E_INVALIDARG pOptions was a null pointer. + /// + /// + /// + /// + /// E_UNEXPECTED An unknown error occurred; the method failed. + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms714204(v=vs.85) HRESULT SetOptions( XACTOPT *pOptions); + [PreserveSig] + HRESULT SetOptions(in XACTOPT pOptions); + + /// The GetOptions method is used to read transaction attributes from a transaction options object. + /// + /// [in, out] Reference to a XACTOPT structure containing attribute information for a transaction options object. The szDescription + /// field must be pre-allocated with the correct length. + /// + /// + /// + /// This method can used to determine the description and the transaction timeout of a transaction that is already in progress, as + /// shown in the following sample code. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms683541(v=vs.85) HRESULT GetOptions( XACTOPT * pOptions); + [PreserveSig] + HRESULT GetOptions(ref XACTOPT pOptions); + } + + /// + /// This interface is used by application programs that require asynchronous notification about transaction outcomes. The application + /// program implements the methods in this interface and registers the interface with the connection point mechanism. DTC calls the + /// appropriate method on this interface to inform the application about the outcome of a transaction. + /// + /// + /// + /// Typically, ITransaction::Commit or Abort calls are performed synchronously. This means that the calling thread is + /// blocked until DTC makes a commit or abort decision (usually at the end of phase one of the two-phase commit protocol). + /// + /// + /// It is possible to avoid blocking the calling thread by using asynchronous Commit or Abort calls. Asynchronous + /// Commit or Abort require the following: + /// + /// + /// The ITransactionOutcomeEvents events are raised when the transaction's outcome is known. On the root transaction manager's + /// system, the transaction outcome event is raised at the end of phase one. On the subordinate transaction managers' systems, the + /// transaction outcome events are raised at the beginning of phase two. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms686465(v=vs.85) + [PInvokeData("transact.h")] + [ComImport, Guid("3A6AD9E2-23B9-11cf-AD60-00AA00A74CCD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface ITransactionOutcomeEvents + { + /// This event is raised when the transaction committed. + /// [in] Indicates whether retaining Commit was specified. Will be FALSE. + /// [in] Always NULL. + /// [in] Always S_OK. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms687677(v=vs.85) HRESULT Committed( BOOL fRetaining, XACTUOW + // * pNewUOW, HRESULT hr); + [PreserveSig] + HRESULT Committed(bool fRetaining, [In, Optional] IntPtr pNewUOW, HRESULT hr); + + /// + /// This event is raised when the transaction aborted, either as a result of a call to Abort or an unsuccessful call to Commit*.* + /// + /// [in] A BOID indicating why the transaction aborted. + /// [in] Indicates whether retaining Commit was specified. Will be FALSE. + /// [in] Always NULL. + /// [in] Always S_OK. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms688494(v=vs.85) HRESULT Aborted( BOID * pboidReason, BOOL + // fRetaining, XACTUOW * pNewUOW, HRESULT hr); + [PreserveSig] + HRESULT Aborted([In, Optional] IntPtr pboidReason, bool fRetaining, [In, Optional] IntPtr pNewUOW, HRESULT hr); + + /// + /// This event is raised when one of the participants in the transaction chooses to heuristically decide the outcome of the transaction. + /// + /// [in] Values from the enumeration XACTHEURISTIC. + /// + /// [in] A BOID indicating why the transaction was heuristically decided. This value is provided by the party making the heuristic decision. + /// + /// [in] Always S_OK. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms678855(v=vs.85) HRESULT HeuristicDecision( DWORD dwDecision, + // BOID * pboidReason, HRESULT hr); + [PreserveSig] + HRESULT HeuristicDecision(XACTHEURISTIC dwDecision, [In, Optional] IntPtr pboidReason, HRESULT hr); + + /// + /// This event is raised when the outcome of the transaction is in-doubt. The outcome of the transaction can be in-doubt if the + /// connection between the MSDTC proxy and the MSDTC TM was broken after the proxy asked the transaction manager to commit or abort a + /// transaction but before the transaction manager's response to the commit or abort was received by the proxy. Note: Receiving this + /// method call is not the same as the state of the transaction being in-doubt. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms687104(v=vs.85) HRESULT Indoubt(void); + [PreserveSig] + HRESULT Indoubt(); + } + + /// + /// + /// The DtcGetTransactionManagerEx function is typically the first DTC call that application programs and resource managers make + /// when using DTC. This helper function establishes the initial connection to DTC. It returns an interface pointer to one of the + /// interfaces on the DTC proxy core object. This function helps reduce the boot time and minimize resource consumption and adds the + /// ability to demand start DTC to compensate for removing boot start. + /// + /// + /// + /// [in] Name of the host system which will serve as the transaction commit coordinator. + /// + /// Note + /// If the host system is not found the HRESULT XACT_E_UNABLE_TO_READ_DTC_CONFIG is returned. + /// + /// + /// + /// [in] String Name of the transaction manager which will serve as the transaction commit coordinator. Must be NULL. + /// + /// [in] IID of the requested interface. + /// + /// [in] Specifies any configuration or startup options for the transaction manager object. Currently the supported flags are: + /// OLE_TM_FLAG_NODEMANDSTART (Value = 0x00000001) + /// Callers can specify this option if they do not want demand start of DTC. + /// OLE_TM_FLAG_NONE (Value = 0x00000000) + /// + /// External callers should use this flag if they want the default behavior (which is to demand start DTC). This approach provides + /// meaningful text and is preferable to directly using the value 0 for i_grfOptions. + /// + /// OLE_TM_FLAG_INTERNAL_TO_TM (Internal only) + /// + /// Only components internal to the Transaction manager (such as XATM) should use this flag. This flag should not be used by external callers. + /// + /// OLE_TM_FLAG_QUERY_SERVICE_LOCKSTATUS (Internal only) + /// + /// Specifying this flag will cause DTC to query the lock status and fail demand start if someone else is holding SCM lock. This flag + /// should not be used by external callers. + /// + /// + /// + /// [in] Pointer to a self-describing structure. You can use the structure to pass various configuration parameters into the TM object. + /// Must be NULL. + /// + /// [out] Pointer to the pointer to the requested interface. + /// + /// + /// Note + /// This API should not be called without the OLE_TM_FLAG_NO_DEMANDSTART during service startup. + /// + /// + /// If the value refers to a remote computer, then you must configure the computers participating in the transaction as follows, + /// otherwise the call will fail: + /// + /// + /// + /// + /// On the computer where the application that makes this call resides, make sure the Remote Registry service is running. + /// + /// + /// + /// + /// + /// On the remote computer referred to by the parameter, make sure the MSDTC service is configured to accept Network Transactions and + /// allows remote clients. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms678898(v=vs.85) EXTERN_C EXPORTAPI __cdecl + // DtcGetTransactionManagerEx( tchar * pszHost, tchar * pszTmName, REFIIDriid, DWORDgrfOptions, void * pvConfigParams, void ** ppvObject); + [PInvokeData("xolehlp.h")] + [DllImport("xolehlp.dll", SetLastError = false, CharSet = CharSet.Auto)] + public static extern HRESULT DtcGetTransactionManagerEx(string? pszHost, string? pszTmName, in Guid riid, + OLE_TM grfOptions, [In, Optional] IntPtr pvConfigParams, [MarshalAs(UnmanagedType.IUnknown, IidParameterIndex = 2)] out object? ppvObject); + + /// + /// The DtcGetTransactionManagerEx function is typically the first DTC call that application programs and resource managers make + /// when using DTC. This helper function establishes the initial connection to DTC. It returns an interface pointer to one of the + /// interfaces on the DTC proxy core object. This function helps reduce the boot time and minimize resource consumption and adds the + /// ability to demand start DTC to compensate for removing boot start. + /// + /// The type of the interface to return. + /// + /// [in] Name of the host system which will serve as the transaction commit coordinator. + /// + /// Note + /// If the host system is not found the HRESULT XACT_E_UNABLE_TO_READ_DTC_CONFIG is returned. + /// + /// + /// + /// [in] Specifies any configuration or startup options for the transaction manager object. Currently the supported flags are: + /// OLE_TM_FLAG_NODEMANDSTART (Value = 0x00000001) + /// Callers can specify this option if they do not want demand start of DTC. + /// OLE_TM_FLAG_NONE (Value = 0x00000000) + /// + /// External callers should use this flag if they want the default behavior (which is to demand start DTC). This approach provides + /// meaningful text and is preferable to directly using the value 0 for i_grfOptions. + /// + /// OLE_TM_FLAG_INTERNAL_TO_TM (Internal only) + /// + /// Only components internal to the Transaction manager (such as XATM) should use this flag. This flag should not be used by external callers. + /// + /// OLE_TM_FLAG_QUERY_SERVICE_LOCKSTATUS (Internal only) + /// + /// Specifying this flag will cause DTC to query the lock status and fail demand start if someone else is holding SCM lock. This flag + /// should not be used by external callers. + /// + /// + /// [out] Pointer to the pointer to the requested interface. + /// + /// + /// Note + /// This API should not be called without the OLE_TM_FLAG_NO_DEMANDSTART during service startup. + /// + /// + /// If the value refers to a remote computer, then you must configure the computers participating in the transaction as follows, + /// otherwise the call will fail: + /// + /// + /// + /// + /// On the computer where the application that makes this call resides, make sure the Remote Registry service is running. + /// + /// + /// + /// + /// + /// On the remote computer referred to by the parameter, make sure the MSDTC service is configured to accept Network Transactions and + /// allows remote clients. + /// + /// + /// + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms678898(v=vs.85) EXTERN_C EXPORTAPI __cdecl + // DtcGetTransactionManagerEx( tchar * pszHost, tchar * pszTmName, REFIIDriid, DWORDgrfOptions, void * pvConfigParams, void ** ppvObject); + [PInvokeData("xolehlp.h")] + public static T DtcGetTransactionManagerEx(string? pszHost = null, OLE_TM grfOptions = 0) where T : class + { + DtcGetTransactionManagerEx(pszHost, null, typeof(T).GUID, grfOptions, IntPtr.Zero, out var ppvObject).ThrowIfFailed(); + return (T)ppvObject!; + } + + /// + [StructLayout(LayoutKind.Sequential, Size = 16)] + [UnsafeValueType] + [NativeCppClass] + [PInvokeData("transact.h")] + public struct BOID + { + } + + /// The XACTOPT structure contains information for a transaction options object. + [PInvokeData("transact.h")] + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)] + public struct XACTOPT + { + /// + /// This parameter limits the duration of the transaction and therefore bounds the amount of time that locks are held on database + /// records and system resources. If the time-out period expires before the transaction commits, the DTC automatically aborts the + /// transaction. The time-out is specified in milliseconds. A time-out value of zero indicates no time-out. + /// + public uint ulTimeout; + + /// + /// A textual description for a transaction. The description is displayed by the DTC administration tool in the DTC Transactions + /// window. The description is meaningful only to the DTC administrator and is not processed or interpreted by the DTC itself. + /// + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 40)] + public string szDescription; + } + + /// The XACTTRANSINFO structure stores information about the transaction. + [PInvokeData("transact.h")] + [StructLayout(LayoutKind.Sequential)] + public struct XACTTRANSINFO + { + /// The unit of work associated with this transaction. + public BOID uow; + + /// + /// The isolation level associated with this transaction object, specified by the ISOLATIONLEVEL enumeration. + /// ISOLATIONLEVEL_UNSPECIFIED indicates that no isolation level was specified. + /// + public ISOLEVEL isoLevel; + + /// Values from ISOFLAG enumeration. + public ISOFLAG isoFlags; + + /// This bit mask indicates which grfTC flags that this transaction implementation supports. + public uint grfTCSupported; + + /// Must be zero. + public uint grfRMSupported; + + /// Must be zero. + public uint grfTCSupportedRetaining; + + /// Must be zero. + public uint grfRMSupportedRetaining; + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/adoint.cs b/PInvoke/OleDb/adoint.cs new file mode 100644 index 00000000..33263f38 --- /dev/null +++ b/PInvoke/OleDb/adoint.cs @@ -0,0 +1,41 @@ +namespace Vanara.PInvoke; + +public static partial class OleDb +{ + /// + /// + /// IADOConnectionConstruction allows you to create an ADO connection from existing OLE DB objects. Using this interface is only + /// feasible from C or C++ code that uses a mix of OLE DB and ADO. To do this, you typically create an empty ADO connection by using + /// CoCreateInstance; query the object for the IADOConnectionConstuction interface; and then call WrapDSOandSession + /// to initialize from an existing OLE DB data source object and session. + /// + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965351(v=vs.85) + [PInvokeData("adoint.h")] + [ComImport, Guid("00000516-0000-0010-8000-00AA006D2EA4"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IADOConnectionConstruction + { + /// Returns the underlying OLEDB Data Source object for this connection. + /// In the header file, this method is called ADOCommandConstruction::DSO. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965468(v=vs.85) HRESULT get_DSO( IUnknown** ppDSO); + [PreserveSig] + HRESULT get_DSO([MarshalAs(UnmanagedType.IUnknown)] out object? ppDSO); + + /// Returns the underlying OLEDB Session for this connection. + /// In the header file, this method is called ADOCommandConstruction::Session. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965359(v=vs.85) HRESULT get_Session( IUnknown** ppSession); + [PreserveSig] + HRESULT get_Session([MarshalAs(UnmanagedType.IUnknown)] out object? ppSession); + + /// Initializes a connection from an existing OLEDB Data Source object and Session. + /// [in] An interface pointer to the Data Source object. It must point to an IDBInitialize interface. + /// + /// [in] An interface pointer to the Session object. It must be queryable for the ISessionProperties, IBindResource, and ICreateRow interfaces. + /// + /// In the header file, this method is called ADOCommandConstruction::WrapDSOandSession. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/aa965326(v=vs.85) HRESULT WrapDSOandSession( IUnknown* pDSO + // IUnknown* pSession); + [PreserveSig] + HRESULT WrapDSOandSession([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pDSO, [In, Optional, MarshalAs(UnmanagedType.IUnknown)] object? pSession); + } +} \ No newline at end of file diff --git a/PInvoke/OleDb/msdasc.cs b/PInvoke/OleDb/msdasc.cs index 445d0ac7..a8edf03c 100644 --- a/PInvoke/OleDb/msdasc.cs +++ b/PInvoke/OleDb/msdasc.cs @@ -374,6 +374,38 @@ public static partial class OleDb void WriteStringToStorage([In, Optional] string? pwszFileName, [In, Optional] string? pwszInitializationString, Kernel32.CreationOption dwCreationDisposition); } + /// + /// Created for reference use in Visual Basic. Provides implementation for the promptNew and promptEdit methods. + /// + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms722628(v=vs.85) + [ComImport, Guid("2206CCB2-19C1-11D1-89E0-00C04FD7A829"), InterfaceType(ComInterfaceType.InterfaceIsIDispatch)] + public interface IDataSourceLocator + { + /// The parent window handle for dialog boxes to be displayed. The dialog box will always be centered within this window. Returns the currently assigned window handle. + /// A HWND value. The handle of the parent window where the dialog will be displayed. + public HWND hWnd { get; set; } + + /// + /// Opens the Data Link Properties window. Allows the user to select the properties for a new connection. The properties are returned in a connection string. + /// + /// An ADO connection object. Contains preset connection properties that will be displayed in the Data Link Properties window. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms725384(v=vs.85) + [return: MarshalAs(UnmanagedType.IDispatch)] + object? PromptNew(); + + /// + /// Opens the Data Link Properties window. Allows the user to change the properties for an existing ADO connection object. The + /// properties for the connection object are changed directly at the connection object. + /// + /// + /// An ADO connection object. Contains preset connection properties that will be displayed in the Data Link Properties window. + /// + /// A Boolean value. True if user pressed OK in the Data Link Properties window; False if Cancel was pressed. + // https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms709747(v=vs.85) + [return: MarshalAs(UnmanagedType.Bool)] + bool PromptEdit([MarshalAs(UnmanagedType.IDispatch)] ref object? ppADOConnection); + } + /// /// /// The IDBPromptInitialize interface allows the display of the data link dialog boxes programmatically. Using the data link user @@ -616,6 +648,18 @@ public static partial class OleDb [In, MarshalAs(UnmanagedType.LPWStr)] string pwszInitialFile, [MarshalAs(UnmanagedType.LPWStr)] out string ppwszSelectedFile); } + /// + [PInvokeData("msdasc.h")] + [ComImport, Guid("06210E88-01F5-11D1-B512-0080C781C384"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IService + { + /// + /// + /// + [PreserveSig] + HRESULT InvokeService([In, MarshalAs(UnmanagedType.IUnknown)] object pUnkInner); + } + /// Creates a data source object; analogous to CoCreateInstance. /// The interface type to create. /// The instance. @@ -809,9 +853,4 @@ public static partial class OleDb /// CLSID_RootBinder [ComImport, Guid("FF151822-B0BF-11D1-A80D-000000000000"), ClassInterface(ClassInterfaceType.None)] public class RootBinder { } - - /* - IService - IDataSourceLocator - */ } \ No newline at end of file