//-----------------------------------------------------------------------
//
// 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 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 string value,
JET_DbInfo infoLevel);
///
/// 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 JET_DBINFOMISC dbinfomisc,
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.
///
/// 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 long 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 JET_DBINFOMISC dbinfomisc,
JET_DbInfo infoLevel);
#endregion
#region Backup/Restore
#if !MANAGEDESENT_ON_WSA
///
/// 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
///
/// 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.
///
/// 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
///
/// 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.
///
/// 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);
///
/// 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.
///
///
/// 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.
///
/// 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_COLUMNBASE columnbase);
///
/// 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_COLUMNBASE columnbase);
///
/// 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.
///
///
/// 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_DBID 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, int[] 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 int result, JET_TblInfo infoLevel);
#endregion
#region JetGetIndexInfo overloads
///
/// 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 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 int result,
JET_IdxInfo infoLevel);
///
/// 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 JET_INDEXID result,
JET_IdxInfo infoLevel);
///
/// 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 JET_INDEXLIST result,
JET_IdxInfo infoLevel);
///
/// 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 string result,
JET_IdxInfo infoLevel);
///
/// 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 JET_INDEXCREATE result,
JET_IdxInfo infoLevel);
#endregion
#region JetGetTableIndexInfo overloads
///
/// 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.
/// 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 int 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 JET_INDEXID 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 JET_INDEXLIST 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 string 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);
///
/// 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 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.
///
/// 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.
///
/// Defragmentation options.
/// An error code or warning.
/// .
int Defragment(
JET_SESID sesid,
JET_DBID dbid,
string tableName,
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
}
}