//----------------------------------------------------------------------- // // Copyright (c) Microsoft Corporation. // //----------------------------------------------------------------------- namespace Microsoft.Isam.Esent.Interop.Implementation { using System; using System.Collections.Generic; using Microsoft.Isam.Esent.Interop.Server2003; using Microsoft.Isam.Esent.Interop.Vista; using Microsoft.Isam.Esent.Interop.Windows7; using Microsoft.Isam.Esent.Interop.Windows8; ///

/// This interface describes all the methods which have a P/Invoke implementation. /// Concrete instances of this interface provide methods that call ESENT. ///

internal partial interface IJetApi { ///

/// Gets a description of the capabilities of the current version of ESENT. ///

JetCapabilities Capabilities { get; } #region Init/Term ///

/// Allocates a new instance of the database engine. ///

/// Returns the new instance. /// The name of the instance. Names must be unique. /// An error if the call fails. int JetCreateInstance(out JET_INSTANCE instance, string name); ///

/// Allocate a new instance of the database engine for use in a single /// process, with a display name specified. ///

/// Returns the newly create instance. /// /// Specifies a unique string identifier for the instance to be created. /// This string must be unique within a given process hosting the /// database engine. /// /// /// A display name for the instance to be created. This will be used /// in eventlog entries. /// /// Creation options. /// An error if the call fails. int JetCreateInstance2(out JET_INSTANCE instance, string name, string displayName, CreateInstanceGrbit grbit); ///

/// Initialize the ESENT database engine. ///

/// /// The instance to initialize. If an instance hasn't been /// allocated then a new one is created and the engine /// will operate in single-instance mode. /// /// An error if the call fails. int JetInit(ref JET_INSTANCE instance); ///

/// Initialize the ESENT database engine. ///

/// /// The instance to initialize. If an instance hasn't been /// allocated then a new one is created and the engine /// will operate in single-instance mode. /// /// /// Initialization options. /// /// An error or warning. int JetInit2(ref JET_INSTANCE instance, InitGrbit grbit); ///

/// Initialize the ESENT database engine. ///

/// /// The instance to initialize. If an instance hasn't been /// allocated then a new one is created and the engine /// will operate in single-instance mode. /// /// /// Additional recovery parameters for remapping databases during /// recovery, position where to stop recovery at, or recovery status. /// /// /// Initialization options. /// /// An error code or warning. int JetInit3(ref JET_INSTANCE instance, JET_RSTINFO recoveryOptions, InitGrbit grbit); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Retrieves information about the instances that are running. ///

/// /// Returns the number of instances. /// /// /// Returns an array of instance info objects, one for each running /// instance. /// /// An error code if the call fails. int JetGetInstanceInfo(out int numInstances, out JET_INSTANCE_INFO[] instances); ///

/// Retrieves information about an instance. ///

/// The instance to get information about. /// Retrieved information. /// The type of information to retrieve. /// An error code if the call fails. int JetGetInstanceMiscInfo(JET_INSTANCE instance, out JET_SIGNATURE signature, JET_InstanceMiscInfo infoLevel); ///

/// Prevents streaming backup-related activity from continuing on a /// specific running instance, thus ending the streaming backup in /// a predictable way. ///

/// The instance to use. /// An error code. int JetStopBackupInstance(JET_INSTANCE instance); ///

/// Prepares an instance for termination. ///

/// The (running) instance to use. /// An error code. int JetStopServiceInstance(JET_INSTANCE instance); #endif // !MANAGEDESENT_ON_WSA ///

/// Prepares an instance for termination. Can also be used to resume a previous quiescing. ///

/// The (running) instance to use. /// The options to stop or resume the instance. /// An error code. int JetStopServiceInstance2( JET_INSTANCE instance, StopServiceGrbit grbit); ///

/// Terminate an instance that was created with or /// . ///

/// The instance to terminate. /// An error or warning. int JetTerm(JET_INSTANCE instance); ///

/// Terminate an instance that was created with or /// . ///

/// The instance to terminate. /// Termination options. /// An error or warning. int JetTerm2(JET_INSTANCE instance, TermGrbit grbit); ///

/// Sets database configuration options. ///

/// /// The instance to set the option on or /// to set the option on all instances. /// /// The session to use. /// The parameter to set. /// The value of the parameter to set, if the parameter is an integer type. /// The value of the parameter to set, if the parameter is a string type. /// An error or warning. int JetSetSystemParameter(JET_INSTANCE instance, JET_SESID sesid, JET_param paramid, IntPtr paramValue, string paramString); ///

/// Sets database configuration options. This overload is used when the /// parameter being set is of type JET_CALLBACK. ///

/// /// The instance to set the option on or /// to set the option on all instances. /// /// The session to use. /// The parameter to set. /// The value of the parameter to set. /// The value of the string parameter to set. /// An error or warning. int JetSetSystemParameter(JET_INSTANCE instance, JET_SESID sesid, JET_param paramid, JET_CALLBACK paramValue, string paramString); ///

/// Gets database configuration options. ///

/// The instance to retrieve the options from. /// The session to use. /// The parameter to get. /// Returns the value of the parameter, if the value is an integer. /// Returns the value of the parameter, if the value is a string. /// The maximum size of the parameter string. /// /// passes in the error number in the paramValue, which is why it is /// a ref parameter and not an out parameter. /// /// An error or warning. int JetGetSystemParameter(JET_INSTANCE instance, JET_SESID sesid, JET_param paramid, ref IntPtr paramValue, out string paramString, int maxParam); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Retrieves the version of the database engine. ///

/// The session to use. /// Returns the version number of the database engine. /// An error code if the call fails. int JetGetVersion(JET_SESID sesid, out uint version); #endif // !MANAGEDESENT_ON_WSA #endregion #region Databases ///

/// Creates and attaches a database file. ///

/// The session to use. /// The path to the database file to create. /// The parameter is not used. /// Returns the dbid of the new database. /// Database creation options. /// An error or warning. int JetCreateDatabase(JET_SESID sesid, string database, string connect, out JET_DBID dbid, CreateDatabaseGrbit grbit); ///

/// Creates and attaches a database file with a maximum database size specified. /// . ///

/// The session to use. /// The path to the database file to create. /// /// The maximum size, in database pages, of the database. Passing 0 means there is /// no enforced maximum. /// /// Returns the dbid of the new database. /// Database creation options. /// An error or warning. int JetCreateDatabase2(JET_SESID sesid, string database, int maxPages, out JET_DBID dbid, CreateDatabaseGrbit grbit); ///

/// Attaches a database file for use with a database instance. In order to use the /// database, it will need to be subsequently opened with . ///

/// The session to use. /// The database to attach. /// Attach options. /// An error or warning. int JetAttachDatabase(JET_SESID sesid, string database, AttachDatabaseGrbit grbit); ///

/// Attaches a database file for use with a database instance. In order to use the /// database, it will need to be subsequently opened with . ///

/// The session to use. /// The database to attach. /// /// The maximum size, in database pages, of the database. Passing 0 means there is /// no enforced maximum. /// /// Attach options. /// An error or warning. int JetAttachDatabase2(JET_SESID sesid, string database, int maxPages, AttachDatabaseGrbit grbit); ///

/// Opens a database previously attached with , /// for use with a database session. This function can be called multiple times /// for the same database. ///

/// The session that is opening the database. /// The database to open. /// Reserved for future use. /// Returns the dbid of the attached database. /// Open database options. /// An error or warning. int JetOpenDatabase(JET_SESID sesid, string database, string connect, out JET_DBID dbid, OpenDatabaseGrbit grbit); ///

/// Closes a database file that was previously opened with or /// created with . ///

/// The session to use. /// The database to close. /// Close options. /// An error or warning. int JetCloseDatabase(JET_SESID sesid, JET_DBID dbid, CloseDatabaseGrbit grbit); ///

/// Releases a database file that was previously attached to a database session. ///

/// The database session to use. /// The database to detach. /// An error or warning. int JetDetachDatabase(JET_SESID sesid, string database); ///

/// Releases a database file that was previously attached to a database session. ///

/// The database session to use. /// The database to detach. /// Detach options. /// An error or warning. int JetDetachDatabase2(JET_SESID sesid, string database, DetachDatabaseGrbit grbit); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Makes a copy of an existing database. The copy is compacted to a /// state optimal for usage. Data in the copied data will be packed /// according to the measures chosen for the indexes at index create. /// In this way, compacted data may be stored as densely as possible. /// Alternatively, compacted data may reserve space for subsequent /// record growth or index insertions. ///

/// The session to use for the call. /// The source database that will be compacted. /// The name to use for the compacted database. /// /// A callback function that can be called periodically through the /// database compact operation to report progress. /// /// /// This parameter is ignored and should be null. /// /// Compact options. /// An error code. int JetCompact( JET_SESID sesid, string sourceDatabase, string destinationDatabase, JET_PFNSTATUS statusCallback, object ignored, CompactGrbit grbit); ///

/// Extends the size of a database that is currently open. ///

/// The session to use. /// The database to grow. /// The desired size of the database, in pages. /// /// The size of the database, in pages, after the call. /// /// An error if the call fails. int JetGrowDatabase(JET_SESID sesid, JET_DBID dbid, int desiredPages, out int actualPages); ///

/// Extends the size of a database that is currently open. ///

/// The session to use. /// The name of the database to grow. /// The desired size of the database, in pages. /// /// The size of the database, in pages, after the call. /// /// An error if the call fails. int JetSetDatabaseSize(JET_SESID sesid, string database, int desiredPages, out int actualPages); #endif // !MANAGEDESENT_ON_WSA ///

/// Retrieves certain information about the given database. ///

/// The session to use. /// The database identifier. /// The value to be retrieved. /// The specific data to retrieve. /// An error if the call fails. int JetGetDatabaseInfo( JET_SESID sesid, JET_DBID dbid, out int value, JET_DbInfo infoLevel); ///

/// Retrieves certain information about the given database. ///

/// The file name of the database. /// The value to be retrieved. /// The specific data to retrieve. /// An error if the call fails. int JetGetDatabaseFileInfo( string databaseName, out int value, JET_DbInfo infoLevel); ///

/// Retrieves certain information about the given database. ///

/// Performs a streaming backup of an instance, including all the attached /// databases, to a directory. With multiple backup methods supported by /// the engine, this is the simplest and most encapsulated function. ///

/// The instance to backup. /// /// The directory where the backup is to be stored. If the backup path is /// null to use the function will truncate the logs, if possible. /// /// Backup options. /// /// Optional status notification callback. /// /// An error code. int JetBackupInstance( JET_INSTANCE instance, string destination, BackupGrbit grbit, JET_PFNSTATUS statusCallback); ///

/// Restores and recovers a streaming backup of an instance including all /// the attached databases. It is designed to work with a backup created /// with the function. This is the /// simplest and most encapsulated restore function. ///

/// The instance to use. /// /// Location of the backup. The backup should have been created with /// . /// /// /// Name of the folder where the database files from the backup set will /// be copied and recovered. If this is set to null, the database files /// will be copied and recovered to their original location. /// /// /// Optional status notification callback. /// /// An error code. int JetRestoreInstance(JET_INSTANCE instance, string source, string destination, JET_PFNSTATUS statusCallback); #endif // !MANAGEDESENT_ON_WSA #endregion #region Snapshot Backup #if !MANAGEDESENT_ON_WSA ///

/// Begins the preparations for a snapshot session. A snapshot session /// is a short time interval in which the engine does not issue any /// write IOs to disk, so that the engine can participate in a volume /// snapshot session (when driven by a snapshot writer). ///

/// Returns the ID of the snapshot session. /// Snapshot options. /// An error code if the call fails. int JetOSSnapshotPrepare(out JET_OSSNAPID snapid, SnapshotPrepareGrbit grbit); ///

/// Selects a specific instance to be part of the snapshot session. ///

/// The snapshot identifier. /// The instance to add to the snapshot. /// Options for this call. /// An error code if the call fails. int JetOSSnapshotPrepareInstance(JET_OSSNAPID snapshot, JET_INSTANCE instance, SnapshotPrepareInstanceGrbit grbit); ///

/// Starts a snapshot. While the snapshot is in progress, no /// write-to-disk activity by the engine can take place. ///

/// The snapshot session. /// /// Returns the number of instances that are part of the snapshot session. /// /// /// Returns information about the instances that are part of the snapshot session. /// /// /// Snapshot freeze options. /// /// An error code if the call fails. int JetOSSnapshotFreeze(JET_OSSNAPID snapshot, out int numInstances, out JET_INSTANCE_INFO[] instances, SnapshotFreezeGrbit grbit); ///

/// Retrieves the list of instances and databases that are part of the /// snapshot session at any given moment. ///

/// The identifier of the snapshot session. /// Returns the number of instances. /// Returns information about the instances. /// Options for this call. /// An error code if the call fails. int JetOSSnapshotGetFreezeInfo( JET_OSSNAPID snapshot, out int numInstances, out JET_INSTANCE_INFO[] instances, SnapshotGetFreezeInfoGrbit grbit); ///

/// Notifies the engine that it can resume normal IO operations after a /// freeze period and a successful snapshot. ///

/// The ID of the snapshot. /// Thaw options. /// An error code if the call fails. int JetOSSnapshotThaw(JET_OSSNAPID snapid, SnapshotThawGrbit grbit); ///

/// Enables log truncation for all instances that are part of the snapshot session. ///

/// /// This function should be called only if the snapshot was created with the /// option. Otherwise, the snapshot /// session ends after the call to . /// /// The snapshot identifier. /// Options for this call. /// An error code if the call fails. int JetOSSnapshotTruncateLog(JET_OSSNAPID snapshot, SnapshotTruncateLogGrbit grbit); ///

/// Truncates the log for a specified instance during a snapshot session. ///

/// /// This function should be called only if the snapshot was created with the /// option. Otherwise, the snapshot /// session ends after the call to . /// /// The snapshot identifier. /// The instance to truncat the log for. /// Options for this call. /// An error code if the call fails. int JetOSSnapshotTruncateLogInstance(JET_OSSNAPID snapshot, JET_INSTANCE instance, SnapshotTruncateLogGrbit grbit); ///

/// Notifies the engine that the snapshot session finished. ///

/// The identifier of the snapshot session. /// Snapshot end options. /// An error code if the call fails. int JetOSSnapshotEnd(JET_OSSNAPID snapid, SnapshotEndGrbit grbit); ///

/// Notifies the engine that it can resume normal IO operations after a /// freeze period ended with a failed snapshot. ///

/// Identifier of the snapshot session. /// Options for this call. /// An error code if the call fails. int JetOSSnapshotAbort(JET_OSSNAPID snapid, SnapshotAbortGrbit grbit); #endif // !MANAGEDESENT_ON_WSA #endregion #region Streaming Backup/Restore #if !MANAGEDESENT_ON_WSA ///

/// Initiates an external backup while the engine and database are online and active. ///

/// The instance prepare for backup. /// Backup options. /// An error code if the call fails. int JetBeginExternalBackupInstance(JET_INSTANCE instance, BeginExternalBackupGrbit grbit); ///

/// Closes a file that was opened with JetOpenFileInstance after the /// data from that file has been extracted using JetReadFileInstance. ///

/// The instance to use. /// The handle to close. /// An error code if the call fails. int JetCloseFileInstance(JET_INSTANCE instance, JET_HANDLE handle); ///

/// Ends an external backup session. This API is the last API in a series /// of APIs that must be called to execute a successful online /// (non-VSS based) backup. ///

/// The instance to end the backup for. /// An error code if the call fails. int JetEndExternalBackupInstance(JET_INSTANCE instance); ///

/// Ends an external backup session. This API is the last API in a series /// of APIs that must be called to execute a successful online /// (non-VSS based) backup. ///

/// The instance to end the backup for. /// Options that specify how the backup ended. /// An error code if the call fails. int JetEndExternalBackupInstance2(JET_INSTANCE instance, EndExternalBackupGrbit grbit); ///

/// Used during a backup initiated by /// to query an instance for the names of database files that should become part of /// the backup file set. Only databases that are currently attached to the instance /// using will be considered. These files may /// subsequently be opened using and read /// using . ///

/// /// It is important to note that this API does not return an error or warning if /// the output buffer is too small to accept the full list of files that should be /// part of the backup file set. /// /// The instance to get the information for. /// /// Returns a list of null terminated strings describing the set of database files /// that should be a part of the backup file set. The list of strings returned in /// this buffer is in the same format as a multi-string used by the registry. Each /// null-terminated string is returned in sequence followed by a final null terminator. /// /// /// Maximum number of characters to retrieve. /// /// /// Actual size of the file list. If this is greater than maxChars /// then the list has been truncated. /// /// An error code if the call fails. int JetGetAttachInfoInstance(JET_INSTANCE instance, out string files, int maxChars, out int actualChars); ///

/// Used during a backup initiated by /// to query an instance for the names of database patch files and logfiles that /// should become part of the backup file set. These files may subsequently be /// opened using and read using . ///

/// /// It is important to note that this API does not return an error or warning if /// the output buffer is too small to accept the full list of files that should be /// part of the backup file set. /// /// The instance to get the information for. /// /// Returns a list of null terminated strings describing the set of database patch files /// and log files that should be a part of the backup file set. The list of strings returned in /// this buffer is in the same format as a multi-string used by the registry. Each /// null-terminated string is returned in sequence followed by a final null terminator. /// /// /// Maximum number of characters to retrieve. /// /// /// Actual size of the file list. If this is greater than maxChars /// then the list has been truncated. /// /// An error code if the call fails. int JetGetLogInfoInstance(JET_INSTANCE instance, out string files, int maxChars, out int actualChars); ///

/// Used during a backup initiated by /// to query an instance for the names of the transaction log files that can be safely /// deleted after the backup has successfully completed. ///

/// /// It is important to note that this API does not return an error or warning if /// the output buffer is too small to accept the full list of files that should be /// part of the backup file set. /// /// The instance to get the information for. /// /// Returns a list of null terminated strings describing the set of database log files /// that can be safely deleted after the backup completes. The list of strings returned in /// this buffer is in the same format as a multi-string used by the registry. Each /// null-terminated string is returned in sequence followed by a final null terminator. /// /// /// Maximum number of characters to retrieve. /// /// /// Actual size of the file list. If this is greater than maxChars /// then the list has been truncated. /// /// An error code if the call fails. int JetGetTruncateLogInfoInstance(JET_INSTANCE instance, out string files, int maxChars, out int actualChars); ///

/// Opens an attached database, database patch file, or transaction log /// file of an active instance for the purpose of performing a streaming /// fuzzy backup. The data from these files can subsequently be read /// through the returned handle using JetReadFileInstance. The returned /// handle must be closed using JetCloseFileInstance. An external backup /// of the instance must have been previously initiated using /// JetBeginExternalBackupInstance. ///

/// The instance to use. /// The file to open. /// Returns a handle to the file. /// Returns the least significant 32 bits of the file size. /// Returns the most significant 32 bits of the file size. /// An error code if the call fails. int JetOpenFileInstance(JET_INSTANCE instance, string file, out JET_HANDLE handle, out long fileSizeLow, out long fileSizeHigh); ///

/// Retrieves the contents of a file opened with . ///

/// The instance to use. /// The file to read from. /// The buffer to read into. /// The size of the buffer. /// Returns the amount of data read into the buffer. /// An error code if the call fails. int JetReadFileInstance(JET_INSTANCE instance, JET_HANDLE file, byte[] buffer, int bufferSize, out int bytesRead); ///

/// Used during a backup initiated by JetBeginExternalBackup to delete /// any transaction log files that will no longer be needed once the /// current backup completes successfully. ///

/// The instance to truncate. /// An error code if the call fails. int JetTruncateLogInstance(JET_INSTANCE instance); #endif // !MANAGEDESENT_ON_WSA #endregion #region Sessions ///

/// Initialize a new ESENT session. ///

/// The initialized instance to create the session in. /// Returns the created session. /// The parameter is not used. /// The parameter is not used. /// An error if the call fails. int JetBeginSession(JET_INSTANCE instance, out JET_SESID sesid, string username, string password); ///

/// Associates a session with the current thread using the given context /// handle. This association overrides the default engine requirement /// that a transaction for a given session must occur entirely on the /// same thread. ///

/// The session to set the context on. /// The context to set. /// An error if the call fails. int JetSetSessionContext(JET_SESID sesid, IntPtr context); ///

/// Disassociates a session from the current thread. This should be /// used in conjunction with JetSetSessionContext. ///

/// The session to use. /// An error if the call fails. int JetResetSessionContext(JET_SESID sesid); ///

/// Ends a session. ///

/// The session to end. /// This parameter is not used. /// An error if the call fails. int JetEndSession(JET_SESID sesid, EndSessionGrbit grbit); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Initialize a new ESE session in the same instance as the given sesid. ///

/// The session to duplicate. /// Returns the new session. /// An error if the call fails. int JetDupSession(JET_SESID sesid, out JET_SESID newSesid); #endif // !MANAGEDESENT_ON_WSA ///

/// Retrieves performance information from the database engine for the /// current thread. Multiple calls can be used to collect statistics /// that reflect the activity of the database engine on this thread /// between those calls. ///

/// /// Returns the thread statistics. /// /// An error code if the operation fails. int JetGetThreadStats(out JET_THREADSTATS threadstats); #endregion #region Tables ///

/// Opens a cursor on a previously created table. ///

/// The database session to use. /// The database to open the table in. /// The name of the table to open. /// The parameter is not used. /// The parameter is not used. /// Table open options. /// Returns the opened table. /// An error if the call fails. int JetOpenTable(JET_SESID sesid, JET_DBID dbid, string tablename, byte[] parameters, int parametersLength, OpenTableGrbit grbit, out JET_TABLEID tableid); ///

/// Close an open table. ///

/// The session which opened the table. /// The table to close. /// An error if the call fails. int JetCloseTable(JET_SESID sesid, JET_TABLEID tableid); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Duplicates an open cursor and returns a handle to the duplicated cursor. /// If the cursor that was duplicated was a read-only cursor then the /// duplicated cursor is also a read-only cursor. /// Any state related to constructing a search key or updating a record is /// not copied into the duplicated cursor. In addition, the location of the /// original cursor is not duplicated into the duplicated cursor. The /// duplicated cursor is always opened on the clustered index and its /// location is always on the first row of the table. ///

/// The session to use. /// The cursor to duplicate. /// The duplicated cursor. /// Reserved for future use. /// An error if the call fails. int JetDupCursor(JET_SESID sesid, JET_TABLEID tableid, out JET_TABLEID newTableid, DupCursorGrbit grbit); ///

/// Walks each index of a table to exactly compute the number of entries /// in an index, and the number of distinct keys in an index. This /// information, together with the number of database pages allocated /// for an index and the current time of the computation is stored in /// index metadata in the database. This data can be subsequently retrieved /// with information operations. ///

/// The session to use. /// The table that the statistics will be computed on. /// An error if the call fails. int JetComputeStats(JET_SESID sesid, JET_TABLEID tableid); ///

/// Enables the application to associate a context handle known as /// Local Storage with a cursor or the table associated with that /// cursor. This context handle can be used by the application to /// store auxiliary data that is associated with a cursor or table. /// The application is later notified using a runtime callback when /// the context handle must be released. This makes it possible to /// associate dynamically allocated state with a cursor or table. ///

/// The session to use. /// The cursor to use. /// The context handle to be associated with the session or cursor. /// Set options. /// An error if the call fails. int JetSetLS(JET_SESID sesid, JET_TABLEID tableid, JET_LS ls, LsGrbit grbit); ///

/// Enables the application to retrieve the context handle known /// as Local Storage that is associated with a cursor or the table /// associated with that cursor. This context handle must have been /// previously set using . JetGetLS can also /// be used to simultaneously fetch the current context handle for /// a cursor or table and reset that context handle. ///

/// The session to use. /// The cursor to use. /// Returns the retrieved context handle. /// Retrieve options. /// An error if the call fails. int JetGetLS(JET_SESID sesid, JET_TABLEID tableid, out JET_LS ls, LsGrbit grbit); ///

/// Determine whether an update of the current record of a cursor /// will result in a write conflict, based on the current update /// status of the record. It is possible that a write conflict will /// ultimately be returned even if JetGetCursorInfo returns successfully. /// because another session may update the record before the current /// session is able to update the same record. ///

/// The session to use. /// The cursor to check. /// An error if the call fails. int JetGetCursorInfo(JET_SESID sesid, JET_TABLEID tableid); #endif // !MANAGEDESENT_ON_WSA #endregion #region Transactions ///

/// Causes a session to enter a transaction or create a new save point in an existing /// transaction. ///

/// The session to begin the transaction for. /// An error if the call fails. int JetBeginTransaction(JET_SESID sesid); ///

/// Causes a session to enter a transaction or create a new save point in an existing /// transaction. ///

/// The session to begin the transaction for. /// Transaction options. /// An error if the call fails. int JetBeginTransaction2(JET_SESID sesid, BeginTransactionGrbit grbit); ///

/// Commits the changes made to the state of the database during the current save point /// and migrates them to the previous save point. If the outermost save point is committed /// then the changes made during that save point will be committed to the state of the /// database and the session will exit the transaction. ///

/// The session to commit the transaction for. /// Commit options. /// An error if the call fails. int JetCommitTransaction(JET_SESID sesid, CommitTransactionGrbit grbit); ///

/// Undoes the changes made to the state of the database /// and returns to the last save point. JetRollback will also close any cursors /// opened during the save point. If the outermost save point is undone, the /// session will exit the transaction. ///

/// The session to rollback the transaction for. /// Rollback options. /// An error if the call fails. int JetRollback(JET_SESID sesid, RollbackTransactionGrbit grbit); #endregion #region DDL ///

/// Create an empty table. The newly created table is opened exclusively. ///

/// The session to use. /// The database to create the table in. /// The name of the table to create. /// Initial number of pages in the table. /// /// The default density of the table. This is used when doing sequential inserts. /// /// Returns the tableid of the new table. /// An error if the call fails. int JetCreateTable(JET_SESID sesid, JET_DBID dbid, string table, int pages, int density, out JET_TABLEID tableid); ///

/// Add a new column to an existing table. ///

/// The session to use. /// The table to add the column to. /// The name of the column. /// The definition of the column. /// The default value of the column. /// The size of the default value. /// Returns the columnid of the new column. /// An error if the call fails. int JetAddColumn(JET_SESID sesid, JET_TABLEID tableid, string column, JET_COLUMNDEF columndef, byte[] defaultValue, int defaultValueSize, out JET_COLUMNID columnid); ///

/// Deletes a column from a database table. ///

/// The session to use. /// A cursor on the table to delete the column from. /// The name of the column to be deleted. /// An error if the call fails. int JetDeleteColumn(JET_SESID sesid, JET_TABLEID tableid, string column); ///

/// Deletes a column from a database table. ///

/// The session to use. /// A cursor on the table to delete the column from. /// The name of the column to be deleted. /// Column deletion options. /// An error if the call fails. int JetDeleteColumn2(JET_SESID sesid, JET_TABLEID tableid, string column, DeleteColumnGrbit grbit); ///

/// Deletes an index from a database table. ///

/// The session to use. /// A cursor on the table to delete the index from. /// The name of the index to be deleted. /// An error if the call fails. int JetDeleteIndex(JET_SESID sesid, JET_TABLEID tableid, string index); ///

/// Deletes a table from a database. ///

/// The session to use. /// The database to delete the table from. /// The name of the table to delete. /// An error if the call fails. int JetDeleteTable(JET_SESID sesid, JET_DBID dbid, string table); ///

/// Creates an index over data in an ESE database. An index can be used to locate /// specific data quickly. ///

/// The session to use. /// The table to create the index on. /// /// Pointer to a null-terminated string that specifies the name of the index to create. /// /// Index creation options. /// /// Pointer to a double null-terminated string of null-delimited tokens. /// /// /// The length, in characters, of szKey including the two terminating nulls. /// /// Initial B+ tree density. /// An error if the call fails. int JetCreateIndex( JET_SESID sesid, JET_TABLEID tableid, string indexName, CreateIndexGrbit grbit, string keyDescription, int keyDescriptionLength, int density); ///

/// Creates indexes over data in an ESE database. ///

/// The session to use. /// The table to create the index on. /// Array of objects describing the indexes to be created. /// Number of index description objects. /// An error code. int JetCreateIndex2( JET_SESID sesid, JET_TABLEID tableid, JET_INDEXCREATE[] indexcreates, int numIndexCreates); ///

/// Creates a temporary table with a single index. A temporary table /// stores and retrieves records just like an ordinary table created /// using JetCreateTableColumnIndex. However, temporary tables are /// much faster than ordinary tables due to their volatile nature. /// They can also be used to very quickly sort and perform duplicate /// removal on record sets when accessed in a purely sequential manner. ///

/// The session to use. /// /// Column definitions for the columns created in the temporary table. /// /// Number of column definitions. /// Table creation options. /// /// Returns the tableid of the temporary table. Closing this tableid /// frees the resources associated with the temporary table. /// /// /// The output buffer that receives the array of column IDs generated /// during the creation of the temporary table. The column IDs in this /// array will exactly correspond to the input array of column definitions. /// As a result, the size of this buffer must correspond to the size of the input array. /// /// An error code. int JetOpenTempTable( JET_SESID sesid, JET_COLUMNDEF[] columns, int numColumns, TempTableGrbit grbit, out JET_TABLEID tableid, JET_COLUMNID[] columnids); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// The session to use. /// /// Column definitions for the columns created in the temporary table. /// /// Number of column definitions. /// /// The locale ID to use to compare any Unicode key column data in the temporary table. /// Any locale may be used as long as the appropriate language pack has been installed /// on the machine. /// /// Table creation options. /// /// Returns the tableid of the temporary table. Closing this tableid /// frees the resources associated with the temporary table. /// /// /// The output buffer that receives the array of column IDs generated /// during the creation of the temporary table. The column IDs in this /// array will exactly correspond to the input array of column definitions. /// As a result, the size of this buffer must correspond to the size of the input array. /// /// An error code. int JetOpenTempTable2( JET_SESID sesid, JET_COLUMNDEF[] columns, int numColumns, int lcid, TempTableGrbit grbit, out JET_TABLEID tableid, JET_COLUMNID[] columnids); #endif // !MANAGEDESENT_ON_WSA ///

/// The session to use. /// /// Column definitions for the columns created in the temporary table. /// /// Number of column definitions. /// /// The Locale ID and normalization flags that will be used to compare /// any Unicode key column data in the temporary table. When this /// is not present then the default options are used. /// /// Table creation options. /// /// Returns the tableid of the temporary table. Closing this tableid /// frees the resources associated with the temporary table. /// /// /// The output buffer that receives the array of column IDs generated /// during the creation of the temporary table. The column IDs in this /// array will exactly correspond to the input array of column definitions. /// As a result, the size of this buffer must correspond to the size of the input array. /// /// An error code. int JetOpenTempTable3( JET_SESID sesid, JET_COLUMNDEF[] columns, int numColumns, JET_UNICODEINDEX unicodeindex, TempTableGrbit grbit, out JET_TABLEID tableid, JET_COLUMNID[] columnids); ///

/// /// Introduced in Windows Vista. /// /// The session to use. /// /// Description of the temporary table to create on input. After a /// successful call, the structure contains the handle to the temporary /// table and column identifications. /// /// An error code. int JetOpenTemporaryTable(JET_SESID sesid, JET_OPENTEMPORARYTABLE temporarytable); ///

/// Creates a table, adds columns, and indices on that table. ///

/// The session to use. /// The database to which to add the new table. /// Object describing the table to create. /// An error if the call fails. int JetCreateTableColumnIndex3( JET_SESID sesid, JET_DBID dbid, JET_TABLECREATE tablecreate); #region JetGetTableColumnInfo overloads ///

/// Retrieves information about a table column. ///

/// The session to use. /// The table containing the column. /// The name of the column. /// Filled in with information about the column. /// An error if the call fails. int JetGetTableColumnInfo( JET_SESID sesid, JET_TABLEID tableid, string columnName, out JET_COLUMNDEF columndef); ///

/// Retrieves information about a table column. ///

/// The session to use. /// The table containing the column. /// The columnid of the column. /// Filled in with information about the column. /// An error if the call fails. int JetGetTableColumnInfo( JET_SESID sesid, JET_TABLEID tableid, JET_COLUMNID columnid, out JET_COLUMNDEF columndef); ///

/// Retrieves information about a table column. ///

/// Retrieves information about all columns in the table. ///

/// The session to use. /// The table containing the column. /// The parameter is ignored. /// Additional options for JetGetTableColumnInfo. /// Filled in with information about the columns in the table. /// An error if the call fails. int JetGetTableColumnInfo( JET_SESID sesid, JET_TABLEID tableid, string ignored, ColInfoGrbit grbit, out JET_COLUMNLIST columnlist); #endregion #region JetGetColumnInfo overloads ///

/// Retrieves information about a table column. ///

/// The session to use. /// The database that contains the table. /// The name of the table containing the column. /// The name of the column. /// Filled in with information about the column. /// An error if the call fails. int JetGetColumnInfo( JET_SESID sesid, JET_DBID dbid, string tablename, string columnName, out JET_COLUMNDEF columndef); ///

/// Retrieves information about all columns in a table. ///

/// The session to use. /// The database that contains the table. /// The name of the table containing the column. /// This parameter is ignored. /// Filled in with information about the columns in the table. /// An error if the call fails. int JetGetColumnInfo( JET_SESID sesid, JET_DBID dbid, string tablename, string ignored, out JET_COLUMNLIST columnlist); ///

/// Retrieves information about a column in a table. ///

/// The session to use. /// The database that contains the table. /// The name of the table containing the column. /// The name of the column. /// Filled in with information about the columns in the table. /// An error if the call fails. int JetGetColumnInfo( JET_SESID sesid, JET_DBID dbid, string tablename, string columnName, out JET_COLUMNBASE columnbase); ///

/// Retrieves information about a column in a table. ///

/// The session to use. /// The database that contains the table. /// The name of the column. /// The ID of the column. /// Filled in with information about the columns in the table. /// An error if the call fails. int JetGetColumnInfo( JET_SESID sesid, JET_DBID dbid, string columnName, JET_COLUMNID columnid, out JET_COLUMNBASE columnbase); #endregion #region JetGetObjectInfo overloads ///

/// Retrieves information about database objects. ///

/// The session to use. /// The database to use. /// Filled in with information about the objects in the database. /// An error if the call fails. int JetGetObjectInfo(JET_SESID sesid, JET_DBID dbid, out JET_OBJECTLIST objectlist); ///

/// Retrieves information about database objects. ///

/// The session to use. /// The database to use. /// The type of the object. /// The object name about which to retrieve information. /// Filled in with information about the objects in the database. /// An error if the call fails. int JetGetObjectInfo( JET_SESID sesid, JET_DBID dbid, JET_objtyp objtyp, string objectName, out JET_OBJECTINFO objectinfo); #endregion ///

/// JetGetCurrentIndex function determines the name of the current /// index of a given cursor. This name is also used to later re-select /// that index as the current index using JetSetCurrentIndex. It can /// also be used to discover the properties of that index using /// JetGetTableIndexInfo. ///

/// The session to use. /// The cursor to get the index name for. /// Returns the name of the index. /// /// The maximum length of the index name. Index names are no more than /// Api.MaxNameLength characters. /// /// An error if the call fails. int JetGetCurrentIndex(JET_SESID sesid, JET_TABLEID tableid, out string indexName, int maxNameLength); #region JetGetTableInfo overloads ///

/// Retrieves various pieces of information about a table in a database. ///

/// /// This overload is used with . /// /// The session to use. /// The table to retrieve information about. /// Retrieved information. /// The type of information to retrieve. /// An error if the call fails. int JetGetTableInfo(JET_SESID sesid, JET_TABLEID tableid, out JET_OBJECTINFO result, JET_TblInfo infoLevel); ///

/// Retrieves various pieces of information about a table in a database. ///

/// /// This overload is used with and /// . /// /// The session to use. /// The table to retrieve information about. /// Retrieved information. /// The type of information to retrieve. /// An error if the call fails. int JetGetTableInfo(JET_SESID sesid, JET_TABLEID tableid, out string result, JET_TblInfo infoLevel); ///

/// Retrieves various pieces of information about a table in a database. ///

/// Retrieves information about indexes on a table. ///

/// The session to use. /// The database to use. /// The name of the table to retrieve index information about. /// The name of the index to retrieve information about. /// Filled in with information about indexes on the table. /// The type of information to retrieve. /// An error if the call fails. int JetGetIndexInfo( JET_SESID sesid, JET_DBID dbid, string tablename, string indexname, out ushort result, JET_IdxInfo infoLevel); ///

/// Retrieves information about indexes on a table. ///

/// The session to use. /// The table to retrieve index information about. /// The name of the index. /// Filled in with information about indexes on the table. /// The type of information to retrieve. /// An error if the call fails. int JetGetTableIndexInfo( JET_SESID sesid, JET_TABLEID tableid, string indexname, out ushort result, JET_IdxInfo infoLevel); ///

/// Retrieves information about indexes on a table. ///

/// The session to use. /// The table to retrieve index information about. /// The name of the index to retrieve information about. /// Filled in with information about indexes on the table. /// The type of information to retrieve. /// An error if the call fails. int JetGetTableIndexInfo( JET_SESID sesid, JET_TABLEID tableid, string indexname, out JET_INDEXCREATE result, JET_IdxInfo infoLevel); #endregion ///

/// Changes the name of an existing table. ///

/// The session to use. /// The database containing the table. /// The name of the table. /// The new name of the table. /// An error if the call fails. int JetRenameTable(JET_SESID sesid, JET_DBID dbid, string tableName, string newTableName); ///

/// Changes the name of an existing column. ///

/// The session to use. /// The table containing the column. /// The name of the column. /// The new name of the column. /// Column rename options. /// An error if the call fails. int JetRenameColumn(JET_SESID sesid, JET_TABLEID tableid, string name, string newName, RenameColumnGrbit grbit); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Changes the default value of an existing column. ///

/// The session to use. /// The database containing the column. /// The name of the table containing the column. /// The name of the column. /// The new default value. /// Size of the new default value. /// Column default value options. /// An error if the call fails. int JetSetColumnDefaultValue( JET_SESID sesid, JET_DBID dbid, string tableName, string columnName, byte[] data, int dataSize, SetColumnDefaultValueGrbit grbit); #endif // !MANAGEDESENT_ON_WSA #endregion #region Navigation ///

/// Positions a cursor to an index entry for the record that is associated with /// the specified bookmark. The bookmark can be used with any index defined over /// a table. The bookmark for a record can be retrieved using . ///

/// The session to use. /// The cursor to position. /// The bookmark used to position the cursor. /// The size of the bookmark. /// An error if the call fails. int JetGotoBookmark(JET_SESID sesid, JET_TABLEID tableid, byte[] bookmark, int bookmarkSize); ///

/// Positions a cursor to an index entry that is associated with the /// specified secondary index bookmark. The secondary index bookmark /// must be used with the same index over the same table from which it /// was originally retrieved. The secondary index bookmark for an index /// entry can be retrieved using . ///

/// The session to use. /// The table cursor to position. /// The buffer that contains the secondary key. /// The size of the secondary key. /// The buffer that contains the primary key. /// The size of the primary key. /// Options for positioning the bookmark. /// An error if the call fails. int JetGotoSecondaryIndexBookmark( JET_SESID sesid, JET_TABLEID tableid, byte[] secondaryKey, int secondaryKeySize, byte[] primaryKey, int primaryKeySize, GotoSecondaryIndexBookmarkGrbit grbit); ///

/// Navigate through an index. The cursor can be positioned at the start or /// end of the index and moved backwards and forwards by a specified number /// of index entries. ///

/// The session to use for the call. /// The cursor to position. /// An offset which indicates how far to move the cursor. /// Move options. /// An error if the call fails. int JetMove(JET_SESID sesid, JET_TABLEID tableid, int numRows, MoveGrbit grbit); ///

/// Constructs search keys that may then be used by and . ///

/// /// The MakeKey functions provide datatype-specific make key functionality. /// /// The session to use. /// The cursor to create the key on. /// Column data for the current key column of the current index. /// Size of the data. /// Key options. /// An error if the call fails. int JetMakeKey(JET_SESID sesid, JET_TABLEID tableid, IntPtr data, int dataSize, MakeKeyGrbit grbit); ///

/// Efficiently positions a cursor to an index entry that matches the search /// criteria specified by the search key in that cursor and the specified /// inequality. A search key must have been previously constructed using /// JetMakeKey. ///

/// The session to use. /// The cursor to position. /// Seek options. /// An error or warning.. int JetSeek(JET_SESID sesid, JET_TABLEID tableid, SeekGrbit grbit); ///

/// Temporarily limits the set of index entries that the cursor can walk using /// to those starting /// from the current index entry and ending at the index entry that matches the /// search criteria specified by the search key in that cursor and the specified /// bound criteria. A search key must have been previously constructed using /// JetMakeKey. ///

/// The session to use. /// The cursor to set the index range on. /// Index range options. /// An error if the call fails. int JetSetIndexRange(JET_SESID sesid, JET_TABLEID tableid, SetIndexRangeGrbit grbit); ///

/// Computes the intersection between multiple sets of index entries from different secondary /// indices over the same table. This operation is useful for finding the set of records in a /// table that match two or more criteria that can be expressed using index ranges. ///

/// The session to use. /// /// An the index ranges to intersect. The tableids in the ranges /// must have index ranges set on them. /// /// /// The number of index ranges. /// /// /// Returns information about the temporary table containing the intersection results. /// /// Intersection options. /// An error if the call fails. int JetIntersectIndexes( JET_SESID sesid, JET_INDEXRANGE[] ranges, int numRanges, out JET_RECORDLIST recordlist, IntersectIndexesGrbit grbit); ///

/// Set the current index of a cursor. ///

/// The session to use. /// The cursor to set the index on. /// /// The name of the index to be selected. If this is null or empty the primary /// index will be selected. /// /// An error if the call fails. int JetSetCurrentIndex(JET_SESID sesid, JET_TABLEID tableid, string index); ///

/// Set the current index of a cursor. ///

/// The session to use. /// The cursor to set the index on. /// /// The name of the index to be selected. If this is null or empty the primary /// index will be selected. /// /// /// Set index options. /// /// An error if the call fails. int JetSetCurrentIndex2(JET_SESID sesid, JET_TABLEID tableid, string index, SetCurrentIndexGrbit grbit); ///

/// Set the current index of a cursor. ///

/// The session to use. /// The cursor to set the index on. /// /// The name of the index to be selected. If this is null or empty the primary /// index will be selected. /// /// /// Set index options. /// /// /// Sequence number of the multi-valued column value which will be used /// to position the cursor on the new index. This parameter is only used /// in conjunction with . When /// this parameter is not present or is set to zero, its value is presumed /// to be 1. /// /// An error if the call fails. int JetSetCurrentIndex3(JET_SESID sesid, JET_TABLEID tableid, string index, SetCurrentIndexGrbit grbit, int itagSequence); ///

/// Set the current index of a cursor. ///

/// The session to use. /// The cursor to set the index on. /// /// The name of the index to be selected. If this is null or empty the primary /// index will be selected. /// /// /// The id of the index to select. This id can be obtained using JetGetIndexInfo /// or JetGetTableIndexInfo with the option. /// /// /// Set index options. /// /// /// Sequence number of the multi-valued column value which will be used /// to position the cursor on the new index. This parameter is only used /// in conjunction with . When /// this parameter is not present or is set to zero, its value is presumed /// to be 1. /// /// An error if the call fails. int JetSetCurrentIndex4( JET_SESID sesid, JET_TABLEID tableid, string index, JET_INDEXID indexid, SetCurrentIndexGrbit grbit, int itagSequence); ///

/// Counts the number of entries in the current index from the current position forward. /// The current position is included in the count. The count can be greater than the /// total number of records in the table if the current index is over a multi-valued /// column and instances of the column have multiple-values. If the table is empty, /// then 0 will be returned for the count. ///

/// The session to use. /// The cursor to count the records in. /// Returns the number of records. /// /// The maximum number of records to count. /// /// An error if the call fails. int JetIndexRecordCount(JET_SESID sesid, JET_TABLEID tableid, out int numRecords, int maxRecordsToCount); ///

/// The session to use. /// The cursor to count the records in. /// Returns the number of records. /// /// The maximum number of records to count. /// /// An error if the call fails. int JetIndexRecordCount2(JET_SESID sesid, JET_TABLEID tableid, out long numRecords, long maxRecordsToCount); ///

/// Notifies the database engine that the application is scanning the entire /// index that the cursor is positioned on. Consequently, the methods that /// are used to access the index data will be tuned to make this scenario as /// fast as possible. ///

/// The session to use. /// The cursor that will be accessing the data. /// Reserved for future use. /// An error if the call fails. int JetSetTableSequential(JET_SESID sesid, JET_TABLEID tableid, SetTableSequentialGrbit grbit); ///

/// Notifies the database engine that the application is no longer scanning the /// entire index the cursor is positioned on. This call reverses a notification /// sent by JetSetTableSequential. ///

/// The session to use. /// The cursor that was accessing the data. /// Reserved for future use. /// An error if the call fails. int JetResetTableSequential(JET_SESID sesid, JET_TABLEID tableid, ResetTableSequentialGrbit grbit); ///

/// Returns the fractional position of the current record in the current index /// in the form of a JET_RECPOS structure. ///

/// The session to use. /// The cursor positioned on the record. /// Returns the approximate fractional position of the record. /// An error if the call fails. int JetGetRecordPosition(JET_SESID sesid, JET_TABLEID tableid, out JET_RECPOS recpos); ///

/// Moves a cursor to a new location that is a fraction of the way through /// the current index. ///

/// The session to use. /// The cursor to position. /// The approximate position to move to. /// An error if the call fails. int JetGotoPosition(JET_SESID sesid, JET_TABLEID tableid, JET_RECPOS recpos); ///

/// If the records with the specified keys are not in the buffer cache /// then start asynchronous reads to bring the records into the database /// buffer cache. ///

/// The session to use. /// The table to issue the prereads against. /// /// The keys to preread. The keys must be sorted. /// /// The lengths of the keys to preread. /// /// The index of the first key in the keys array to read. /// /// /// The maximum number of keys to preread. /// /// /// Returns the number of keys to actually preread. /// /// /// Preread options. Used to specify the direction of the preread. /// /// An error or warning. int JetPrereadKeys( JET_SESID sesid, JET_TABLEID tableid, byte[][] keys, int[] keyLengths, int keyIndex, int keyCount, out int keysPreread, PrereadKeysGrbit grbit); #endregion #region Data Retrieval ///

/// Retrieves the bookmark for the record that is associated with the index entry /// at the current position of a cursor. This bookmark can then be used to /// reposition that cursor back to the same record using . /// The bookmark will be no longer than /// bytes. ///

/// The session to use. /// The cursor to retrieve the bookmark from. /// Buffer to contain the bookmark. /// Size of the bookmark buffer. /// Returns the actual size of the bookmark. /// An error if the call fails. int JetGetBookmark(JET_SESID sesid, JET_TABLEID tableid, byte[] bookmark, int bookmarkSize, out int actualBookmarkSize); ///

/// Retrieves a special bookmark for the secondary index entry at the /// current position of a cursor. This bookmark can then be used to /// efficiently reposition that cursor back to the same index entry /// using JetGotoSecondaryIndexBookmark. This is most useful when /// repositioning on a secondary index that contains duplicate keys or /// that contains multiple index entries for the same record. ///

/// The session to use. /// The cursor to retrieve the bookmark from. /// Output buffer for the secondary key. /// Size of the secondary key buffer. /// Returns the size of the secondary key. /// Output buffer for the primary key. /// Size of the primary key buffer. /// Returns the size of the primary key. /// Options for the call. /// An error if the call fails. int JetGetSecondaryIndexBookmark( JET_SESID sesid, JET_TABLEID tableid, byte[] secondaryKey, int secondaryKeySize, out int actualSecondaryKeySize, byte[] primaryKey, int primaryKeySize, out int actualPrimaryKeySize, GetSecondaryIndexBookmarkGrbit grbit); ///

/// Retrieves the key for the index entry at the current position of a cursor. ///

/// The session to use. /// The cursor to retrieve the key from. /// The buffer to retrieve the key into. /// The size of the buffer. /// Returns the actual size of the data. /// Retrieve key options. /// An error if the call fails. int JetRetrieveKey(JET_SESID sesid, JET_TABLEID tableid, byte[] data, int dataSize, out int actualDataSize, RetrieveKeyGrbit grbit); ///

/// Retrieves a single column value from the current record. The record is that /// record associated with the index entry at the current position of the cursor. /// Alternatively, this function can retrieve a column from a record being created /// in the cursor copy buffer. This function can also retrieve column data from an /// index entry that references the current record. In addition to retrieving the /// actual column value, JetRetrieveColumn can also be used to retrieve the size /// of a column, before retrieving the column data itself so that application /// buffers can be sized appropriately. ///

/// /// The RetrieveColumnAs functions provide datatype-specific retrieval functions. /// /// The session to use. /// The cursor to retrieve the column from. /// The columnid to retrieve. /// The data buffer to be retrieved into. /// The size of the data buffer. /// Returns the actual size of the data buffer. /// Retrieve column options. /// /// If pretinfo is give as NULL then the function behaves as though an itagSequence /// of 1 and an ibLongValue of 0 (zero) were given. This causes column retrieval to /// retrieve the first value of a multi-valued column, and to retrieve long data at /// offset 0 (zero). /// /// An error or warning. int JetRetrieveColumn(JET_SESID sesid, JET_TABLEID tableid, JET_COLUMNID columnid, IntPtr data, int dataSize, out int actualDataSize, RetrieveColumnGrbit grbit, JET_RETINFO retinfo); ///

/// The JetRetrieveColumns function retrieves multiple column values /// from the current record in a single operation. An array of /// structures is used to /// describe the set of column values to be retrieved, and to describe /// output buffers for each column value to be retrieved. ///

/// The session to use. /// The cursor to retrieve columns from. /// /// An array of one or more JET_RETRIEVECOLUMN structures. Each /// structure includes descriptions of which column value to retrieve /// and where to store returned data. /// /// /// Number of structures in the array given by retrievecolumns. /// /// /// An error or warning. /// unsafe int JetRetrieveColumns( JET_SESID sesid, JET_TABLEID tableid, NATIVE_RETRIEVECOLUMN* retrievecolumns, int numColumns); ///

/// Efficiently retrieves a set of columns and their values from the /// current record of a cursor or the copy buffer of that cursor. The /// columns and values retrieved can be restricted by a list of /// column IDs, itagSequence numbers, and other characteristics. This /// column retrieval API is unique in that it returns information in /// dynamically allocated memory that is obtained using a /// user-provided realloc compatible callback. This new flexibility /// permits the efficient retrieval of column data with specific /// characteristics (such as size and multiplicity) that are unknown /// to the caller. This eliminates the need for the use of the discovery /// modes of JetRetrieveColumn to determine those /// characteristics in order to setup a final call to /// JetRetrieveColumn that will successfully retrieve /// the desired data. ///

/// The session to use. /// The cursor to retrieve data from. /// The numbers of JET_ENUMCOLUMNIDS. /// /// An optional array of column IDs, each with an optional array of itagSequence /// numbers to enumerate. /// /// /// Returns the number of column values retrieved. /// /// /// Returns the enumerated column values. /// /// /// Callback used to allocate memory. /// /// /// Context for the allocation callback. /// /// /// Sets a cap on the amount of data to return from a long text or long /// binary column. This parameter can be used to prevent the enumeration /// of an extremely large column value. /// /// Retrieve options. /// A warning, error or success. int JetEnumerateColumns( JET_SESID sesid, JET_TABLEID tableid, int numColumnids, JET_ENUMCOLUMNID[] columnids, out int numColumnValues, out JET_ENUMCOLUMN[] columnValues, JET_PFNREALLOC allocator, IntPtr allocatorContext, int maxDataSize, EnumerateColumnsGrbit grbit); ///

/// Efficiently retrieves a set of columns and their values from the /// current record of a cursor or the copy buffer of that cursor. ///

/// The session to use. /// The cursor to retrieve data from. /// Enumerate options. /// The discovered columns and their values. /// A warning or success. int JetEnumerateColumns( JET_SESID sesid, JET_TABLEID tableid, EnumerateColumnsGrbit grbit, out IEnumerable enumeratedColumns); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Retrieves record size information from the desired location. ///

/// The session to use. /// /// The cursor that will be used for the API call. The cursor must be /// positioned on a record, or have an update prepared. /// /// Returns the size of the record. /// Call options. /// A warning, error or success. int JetGetRecordSize(JET_SESID sesid, JET_TABLEID tableid, ref JET_RECSIZE recsize, GetRecordSizeGrbit grbit); #endif // !MANAGEDESENT_ON_WSA #endregion #region DML ///

/// Deletes the current record in a database table. ///

/// The session that opened the cursor. /// The cursor on a database table. The current row will be deleted. /// An error if the call fails. int JetDelete(JET_SESID sesid, JET_TABLEID tableid); ///

/// Prepare a cursor for update. ///

/// The session which is starting the update. /// The cursor to start the update for. /// The type of update to prepare. /// An error if the call fails. int JetPrepareUpdate(JET_SESID sesid, JET_TABLEID tableid, JET_prep prep); ///

/// The JetUpdate function performs an update operation including inserting a new row into /// a table or updating an existing row. Deleting a table row is performed by calling /// . ///

/// The session which started the update. /// The cursor to update. An update should be prepared. /// Returns the bookmark of the updated record. This can be null. /// The size of the bookmark buffer. /// Returns the actual size of the bookmark. /// /// JetUpdate is the final step in performing an insert or an update. The update is begun by /// calling and then by calling /// JetSetColumn one or more times to set the record state. Finally, JetUpdate /// is called to complete the update operation. Indexes are updated only by JetUpdate or and not during JetSetColumn. /// /// An error if the call fails. int JetUpdate(JET_SESID sesid, JET_TABLEID tableid, byte[] bookmark, int bookmarkSize, out int actualBookmarkSize); ///

/// The JetUpdate2 function performs an update operation including inserting a new row into /// a table or updating an existing row. Deleting a table row is performed by calling /// . ///

/// The session which started the update. /// The cursor to update. An update should be prepared. /// Returns the bookmark of the updated record. This can be null. /// The size of the bookmark buffer. /// Returns the actual size of the bookmark. /// Update options. /// /// JetUpdate is the final step in performing an insert or an update. The update is begun by /// calling and then by calling /// JetSetColumn one or more times to set the record state. Finally, JetUpdate /// is called to complete the update operation. Indexes are updated only by JetUpdate or and not during JetSetColumn. /// /// An error if the call fails. int JetUpdate2(JET_SESID sesid, JET_TABLEID tableid, byte[] bookmark, int bookmarkSize, out int actualBookmarkSize, UpdateGrbit grbit); ///

/// The JetSetColumn function modifies a single column value in a modified record to be inserted or to /// update the current record. It can overwrite an existing value, add a new value to a sequence of /// values in a multi-valued column, remove a value from a sequence of values in a multi-valued column, /// or update all or part of a long value (a column of type /// or ). ///

/// /// The SetColumn methods provide datatype-specific overrides which may be more efficient. /// /// The session which is performing the update. /// The cursor to update. An update should be prepared. /// The columnid to set. /// The data to set. /// The size of data to set. /// SetColumn options. /// Used to specify itag or long-value offset. /// An error if the call fails. int JetSetColumn(JET_SESID sesid, JET_TABLEID tableid, JET_COLUMNID columnid, IntPtr data, int dataSize, SetColumnGrbit grbit, JET_SETINFO setinfo); ///

/// Allows an application to set multiple column values in a single /// operation. An array of structures is /// used to describe the set of column values to be set, and to describe /// input buffers for each column value to be set. ///

/// The session to use. /// The cursor to set the columns on. /// /// An array of structures describing the /// data to set. /// /// /// Number of entries in the setcolumns parameter. /// /// An error code or warning. unsafe int JetSetColumns(JET_SESID sesid, JET_TABLEID tableid, NATIVE_SETCOLUMN* setcolumns, int numColumns); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Explicitly reserve the ability to update a row, write lock, or to explicitly prevent a row from /// being updated by any other session, read lock. Normally, row write locks are acquired implicitly as a /// result of updating rows. Read locks are usually not required because of record versioning. However, /// in some cases a transaction may desire to explicitly lock a row to enforce serialization, or to ensure /// that a subsequent operation will succeed. ///

/// The session to use. /// The cursor to use. A lock will be acquired on the current record. /// Lock options, use this to specify which type of lock to obtain. /// An error if the call fails. int JetGetLock(JET_SESID sesid, JET_TABLEID tableid, GetLockGrbit grbit); #endif // !MANAGEDESENT_ON_WSA ///

/// Performs an atomic addition operation on one column. This function allows /// multiple sessions to update the same record concurrently without conflicts. ///

/// The session to use. /// The cursor to update. /// /// The column to update. This must be an escrow updatable column. /// /// The buffer containing the addend. /// The size of the addend. /// /// An output buffer that will recieve the current value of the column. This buffer /// can be null. /// /// The size of the previousValue buffer. /// Returns the actual size of the previousValue. /// Escrow update options. /// An error code if the operation fails. int JetEscrowUpdate( JET_SESID sesid, JET_TABLEID tableid, JET_COLUMNID columnid, byte[] delta, int deltaSize, byte[] previousValue, int previousValueLength, out int actualPreviousValueLength, EscrowUpdateGrbit grbit); #endregion #region Callbacks ///

/// Allows the application to configure the database engine to issue /// notifications to the application for specific events. These /// notifications are associated with a specific table and remain in /// effect only until the instance containing the table is shut down /// using . ///

/// The session to use. /// /// A cursor opened on the table that the callback should be /// registered on. /// /// /// The callback reasons for which the application wishes to receive notifications. /// /// The callback function. /// A context that will be given to the callback. /// /// A handle that can later be used to cancel the registration of the given /// callback function using . /// /// An error if the call fails. int JetRegisterCallback( JET_SESID sesid, JET_TABLEID tableid, JET_cbtyp cbtyp, JET_CALLBACK callback, IntPtr context, out JET_HANDLE callbackId); ///

/// Configures the database engine to stop issuing notifications to the /// application as previously requested through /// . ///

/// The session to use. /// /// A cursor opened on the table that the callback should be /// registered on. /// /// /// The callback reasons for which the application no longer wishes to receive notifications. /// /// /// The handle of the registered callback that was returned by . /// /// An error if the call fails. int JetUnregisterCallback(JET_SESID sesid, JET_TABLEID tableid, JET_cbtyp cbtyp, JET_HANDLE callbackId); #endregion #region Online Maintenance ///

/// Starts and stops database defragmentation tasks that improves data /// organization within a database. ///

/// The session to use for the call. /// The database to be defragmented. /// /// Under some options defragmentation is performed for the entire database described by the given /// database ID, and other options (such as ) require /// the name of the table to defragment. /// /// /// When starting an online defragmentation task, this parameter sets the maximum number of defragmentation /// passes. When stopping an online defragmentation task, this parameter is set to the number of passes /// performed. This is not honored in all modes (such as ). /// /// /// When starting an online defragmentation task, this parameter sets /// the maximum time for defragmentation. When stopping an online /// defragmentation task, this output buffer is set to the length of /// time used for defragmentation. This is not honored in all modes (such as ). /// /// Defragmentation options. /// An error code or warning. /// . int JetDefragment( JET_SESID sesid, JET_DBID dbid, string tableName, ref int passes, ref int seconds, DefragGrbit grbit); ///

/// Starts and stops database defragmentation tasks that improves data /// organization within a database. ///

/// The session to use for the call. /// The database to be defragmented. /// /// Unused parameter. Defragmentation is performed for the entire database described by the given database ID. /// /// /// When starting an online defragmentation task, this parameter sets the maximum number of defragmentation /// passes. When stopping an online defragmentation task, this parameter is set to the number of passes /// performed. /// /// /// When starting an online defragmentation task, this parameter sets /// the maximum time for defragmentation. When stopping an online /// defragmentation task, this output buffer is set to the length of /// time used for defragmentation. /// /// Callback function that defrag uses to report progress. /// Defragmentation options. /// An error code or warning. int JetDefragment2( JET_SESID sesid, JET_DBID dbid, string tableName, ref int passes, ref int seconds, JET_CALLBACK callback, DefragGrbit grbit); #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Performs idle cleanup tasks or checks the version store status in ESE. ///

/// The session to use. /// A combination of JetIdleGrbit flags. /// An error code if the operation fails. int JetIdle(JET_SESID sesid, IdleGrbit grbit); #endif // !MANAGEDESENT_ON_WSA #endregion #region Misc #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK ///

/// Crash dump options for Watson. ///

/// Crash dump options. /// An error code. int JetConfigureProcessForCrashDump(CrashDumpGrbit grbit); ///

/// Frees memory that was allocated by a database engine call. ///

/// /// The buffer allocated by a call to the database engine. /// is acceptable, and will be ignored. /// /// An error code. int JetFreeBuffer(IntPtr buffer); #endif // !MANAGEDESENT_ON_WSA #endregion } }