Index: System.Data.SQLite/SQLiteSession.cs ================================================================== --- System.Data.SQLite/SQLiteSession.cs +++ System.Data.SQLite/SQLiteSession.cs @@ -744,10 +744,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -754,11 +757,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -768,10 +778,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected virtual void Dispose(bool disposing) { try { if (!disposed) @@ -810,10 +827,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteChangeSetIterator() { Dispose(false); } #endregion @@ -900,11 +920,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -914,10 +941,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { // // NOTE: Must dispose of the base class first (leaky abstraction) // because it contains the iterator handle, which must be @@ -1039,11 +1073,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -1053,10 +1094,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -1088,25 +1136,58 @@ #endregion /////////////////////////////////////////////////////////////////////////// #region SQLiteStreamAdapter Class + /// + /// This class is used to act as a bridge between a + /// instance and the delegates used with the native streaming API. + /// internal sealed class SQLiteStreamAdapter : IDisposable { #region Private Data - private Stream stream; /* EXEMPT: NOT OWNED */ + /// + /// The managed stream instance used to in order to service the native + /// delegates for both input and output. + /// + private Stream stream; + + /// + /// The flags associated with the connection. + /// private SQLiteConnectionFlags flags; /////////////////////////////////////////////////////////////////////// + /// + /// The delegate used to provide input to the native streaming API. + /// It will be null -OR- point to the method. + /// method. + /// private UnsafeNativeMethods.xSessionInput xInput; + + /// + /// The delegate used to provide output to the native streaming API. + /// It will be null -OR- point to the method. + /// private UnsafeNativeMethods.xSessionOutput xOutput; #endregion /////////////////////////////////////////////////////////////////////// #region Public Constructors + /// + /// Constructs a new instance of this class using the specified managed + /// stream and connection flags. + /// + /// + /// The managed stream instance to be used in order to service the + /// native delegates for both input and output. + /// + /// + /// The flags associated with the parent connection. + /// public SQLiteStreamAdapter( Stream stream, SQLiteConnectionFlags flags ) { @@ -1116,19 +1197,34 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Private Methods + /// + /// Queries and returns the flags associated with the connection for + /// this instance. + /// + /// + /// The value. There is no return + /// value reserved to indicate an error. + /// private SQLiteConnectionFlags GetFlags() { return flags; } #endregion /////////////////////////////////////////////////////////////////////// #region Public Methods + /// + /// Returns a delegate that wraps the method, + /// creating it first if necessary. + /// + /// + /// A delegate that refers to the method. + /// public UnsafeNativeMethods.xSessionInput GetInputDelegate() { CheckDisposed(); if (xInput == null) @@ -1137,10 +1233,17 @@ return xInput; } /////////////////////////////////////////////////////////////////////// + /// + /// Returns a delegate that wraps the method, + /// creating it first if necessary. + /// + /// + /// A delegate that refers to the method. + /// public UnsafeNativeMethods.xSessionOutput GetOutputDelegate() { CheckDisposed(); if (xOutput == null) @@ -1151,10 +1254,31 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Native Callback Methods + /// + /// This method attempts to read bytes from + /// the managed stream, writing them to the + /// buffer. + /// + /// + /// Optional extra context information. Currently, this will always + /// have a value of . + /// + /// + /// A preallocated native buffer to receive the requested input bytes. + /// It must be at least bytes in size. + /// + /// + /// Upon entry, the number of bytes to read. Upon exit, the number of + /// bytes actually read. This value may be zero upon exit. + /// + /// + /// The value upon success -OR- an + /// appropriate error code upon failure. + /// private SQLiteErrorCode Input( IntPtr context, IntPtr pData, ref int nData ) @@ -1202,10 +1326,30 @@ return SQLiteErrorCode.IoErr_Read; } /////////////////////////////////////////////////////////////////////// + /// + /// This method attempts to write bytes to + /// the managed stream, reading them from the + /// buffer. + /// + /// + /// Optional extra context information. Currently, this will always + /// have a value of . + /// + /// + /// A preallocated native buffer containing the requested output + /// bytes. It must be at least bytes in size. + /// + /// + /// The number of bytes to write. + /// + /// + /// The value upon success -OR- an + /// appropriate error code upon failure. + /// private SQLiteErrorCode Output( IntPtr context, IntPtr pData, int nData ) @@ -1256,10 +1400,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -1266,11 +1413,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -1280,10 +1434,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// private /* protected virtual */ void Dispose(bool disposing) { try { if (!disposed) @@ -1320,10 +1481,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteStreamAdapter() { Dispose(false); } #endregion @@ -1331,20 +1495,41 @@ #endregion /////////////////////////////////////////////////////////////////////////// #region SQLiteSessionStreamManager Class + /// + /// This class manages a collection of + /// instances. When used, it takes responsibility for creating, returning, + /// and disposing of its instances. + /// internal sealed class SQLiteSessionStreamManager : IDisposable { #region Private Data + /// + /// The managed collection of + /// instances, keyed by their associated + /// instance. + /// private Dictionary streamAdapters; + + /// + /// The flags associated with the connection. + /// private SQLiteConnectionFlags flags; #endregion /////////////////////////////////////////////////////////////////////// #region Public Constructors + /// + /// Constructs a new instance of this class using the specified + /// connection flags. + /// + /// + /// The flags associated with the parent connection. + /// public SQLiteSessionStreamManager( SQLiteConnectionFlags flags ) { this.flags = flags; @@ -1354,10 +1539,14 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Private Methods + /// + /// Makes sure the collection of + /// is created. + /// private void InitializeStreamAdapters() { if (streamAdapters != null) return; @@ -1364,10 +1553,14 @@ streamAdapters = new Dictionary(); } /////////////////////////////////////////////////////////////////////// + /// + /// Makes sure the collection of + /// is disposed. + /// private void DisposeStreamAdapters() { if (streamAdapters == null) return; @@ -1388,10 +1581,24 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Public Methods + /// + /// Attempts to return a instance + /// suitable for the specified . + /// + /// + /// The instance. If this value is null, a null + /// value will be returned. + /// + /// + /// A instance. Typically, these + /// are always freshly created; however, this method is designed to + /// return the existing instance + /// associated with the specified stream, should one exist. + /// public SQLiteStreamAdapter GetAdapter( Stream stream ) { CheckDisposed(); @@ -1412,10 +1619,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -1422,11 +1632,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -1436,10 +1653,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// private /* protected virtual */ void Dispose(bool disposing) { try { if (!disposed) @@ -1469,10 +1693,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteSessionStreamManager() { Dispose(false); } #endregion @@ -1480,24 +1707,46 @@ #endregion /////////////////////////////////////////////////////////////////////////// #region SQLiteChangeGroup Class + /// + /// This class represents a group of change sets (or patch sets). + /// internal sealed class SQLiteChangeGroup : ISQLiteChangeGroup { #region Private Data + /// + /// The instance associated + /// with this change group. + /// private SQLiteSessionStreamManager streamManager; + + /// + /// The flags associated with the connection. + /// private SQLiteConnectionFlags flags; /////////////////////////////////////////////////////////////////////// + /// + /// The native handle for this change group. This will be deleted when + /// this instance is disposed or finalized. + /// private IntPtr changeGroup; #endregion /////////////////////////////////////////////////////////////////////// #region Public Constructors + /// + /// Constructs a new instance of this class using the specified + /// connection flags. + /// + /// + /// The flags associated with the parent connection. + /// public SQLiteChangeGroup( SQLiteConnectionFlags flags ) { this.flags = flags; @@ -1507,18 +1756,25 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Private Methods + /// + /// Throws an exception if the native change group handle is invalid. + /// private void CheckHandle() { if (changeGroup == IntPtr.Zero) throw new InvalidOperationException("change group not open"); } /////////////////////////////////////////////////////////////////////// + /// + /// Makes sure the native change group handle is valid, creating it if + /// necessary. + /// private void InitializeHandle() { if (changeGroup != IntPtr.Zero) return; @@ -1529,10 +1785,14 @@ throw new SQLiteException(rc, "sqlite3changegroup_new"); } /////////////////////////////////////////////////////////////////////// + /// + /// Makes sure the instance + /// is available, creating it if necessary. + /// private void InitializeStreamManager() { if (streamManager != null) return; @@ -1539,10 +1799,24 @@ streamManager = new SQLiteSessionStreamManager(flags); } /////////////////////////////////////////////////////////////////////// + /// + /// Attempts to return a instance + /// suitable for the specified . + /// + /// + /// The instance. If this value is null, a null + /// value will be returned. + /// + /// + /// A instance. Typically, these + /// are always freshly created; however, this method is designed to + /// return the existing instance + /// associated with the specified stream, should one exist. + /// private SQLiteStreamAdapter GetStreamAdapter( Stream stream ) { InitializeStreamManager(); @@ -1552,10 +1826,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region ISQLiteChangeGroup Members + /// + /// Attempts to add a change set (or patch set) to this change group + /// instance. The underlying data must be contained entirely within + /// the byte array. + /// + /// + /// The raw byte data for the specified change set (or patch set). + /// public void AddChangeSet( byte[] rawData ) { CheckDisposed(); @@ -1587,10 +1869,19 @@ } } /////////////////////////////////////////////////////////////////////// + /// + /// Attempts to add a change set (or patch set) to this change group + /// instance. The underlying data will be read from the specified + /// . + /// + /// + /// The instance containing the raw change set + /// (or patch set) data to read. + /// public void AddChangeSet( Stream stream ) { CheckDisposed(); @@ -1614,10 +1905,18 @@ throw new SQLiteException(rc, "sqlite3changegroup_add_strm"); } /////////////////////////////////////////////////////////////////////// + /// + /// Attempts to create and return, via , the + /// combined set of changes represented by this change group instance. + /// + /// + /// Upon success, this will contain the raw byte data for all the + /// changes in this change group instance. + /// public void CreateChangeSet( ref byte[] rawData ) { CheckDisposed(); @@ -1649,10 +1948,18 @@ } } /////////////////////////////////////////////////////////////////////// + /// + /// Attempts to create and write, via , the + /// combined set of changes represented by this change group instance. + /// + /// + /// Upon success, the raw byte data for all the changes in this change + /// group instance will be written to this . + /// public void CreateChangeSet( Stream stream ) { CheckDisposed(); @@ -1678,10 +1985,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -1688,11 +1998,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -1702,10 +2019,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// private /* protected virtual */ void Dispose(bool disposing) { try { if (!disposed) @@ -1747,10 +2071,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteChangeGroup() { Dispose(false); } #endregion @@ -2177,11 +2504,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) throw new ObjectDisposedException(typeof(SQLiteSession).Name); @@ -2188,10 +2522,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -2374,11 +2715,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -2388,10 +2736,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -2644,11 +2999,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -2658,10 +3020,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -2875,11 +3244,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -2889,10 +3265,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -3044,10 +3427,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -3054,11 +3440,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -3068,10 +3461,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected virtual void Dispose(bool disposing) { try { if (!disposed) @@ -3101,10 +3501,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteChangeSetEnumerator() { Dispose(false); } #endregion @@ -3145,11 +3548,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -3159,10 +3569,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { if (!disposed) @@ -3211,11 +3628,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -3225,10 +3649,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// protected override void Dispose(bool disposing) { try { //if (!disposed) @@ -3511,10 +3942,13 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable Members + /// + /// Disposes of this object instance. + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } @@ -3521,11 +3955,18 @@ #endregion /////////////////////////////////////////////////////////////////////// #region IDisposable "Pattern" Members + /// + /// Non-zero if this object instance has been disposed. + /// private bool disposed; + + /// + /// Throws an exception if this object instance has been disposed. + /// private void CheckDisposed() /* throw */ { #if THROW_ON_DISPOSED if (disposed) { @@ -3535,10 +3976,17 @@ #endif } /////////////////////////////////////////////////////////////////////// + /// + /// Disposes or finalizes this object instance. + /// + /// + /// Non-zero if this object is being disposed; otherwise, this object + /// is being finalized. + /// private /* protected virtual */ void Dispose(bool disposing) { try { if (!disposed) @@ -3569,13 +4017,16 @@ #endregion /////////////////////////////////////////////////////////////////////// #region Destructor + /// + /// Finalizes this object instance. + /// ~SQLiteChangeSetMetadataItem() { Dispose(false); } #endregion } #endregion }