System.Data.SQLite
Check-in [47a190338f]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Yet more work on doc comments.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sessions
Files: files | file ages | folders
SHA1: 47a190338fe5c72e8e12d944bd965f8f3a000bd2
User & Date: mistachkin 2017-10-14 02:24:09
Context
2017-10-14
03:25
Fill in doc comments for the SQLiteSession class. check-in: afe96a0b10 user: mistachkin tags: sessions
02:24
Yet more work on doc comments. check-in: 47a190338f user: mistachkin tags: sessions
2017-10-13
21:01
More work on doc comments. check-in: 3bf2ed2311 user: mistachkin tags: sessions
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to System.Data.SQLite/SQLiteSession.cs.

   742    742               return new SQLiteChangeSetIterator(iterator, false);
   743    743           }
   744    744           #endregion
   745    745   
   746    746           ///////////////////////////////////////////////////////////////////////
   747    747   
   748    748           #region IDisposable Members
          749  +        /// <summary>
          750  +        /// Disposes of this object instance.
          751  +        /// </summary>
   749    752           public void Dispose()
   750    753           {
   751    754               Dispose(true);
   752    755               GC.SuppressFinalize(this);
   753    756           }
   754    757           #endregion
   755    758   
   756    759           ///////////////////////////////////////////////////////////////////////
   757    760   
   758    761           #region IDisposable "Pattern" Members
          762  +        /// <summary>
          763  +        /// Non-zero if this object instance has been disposed.
          764  +        /// </summary>
   759    765           private bool disposed;
          766  +
          767  +        /// <summary>
          768  +        /// Throws an exception if this object instance has been disposed.
          769  +        /// </summary>
   760    770           private void CheckDisposed() /* throw */
   761    771           {
   762    772   #if THROW_ON_DISPOSED
   763    773               if (disposed)
   764    774               {
   765    775                   throw new ObjectDisposedException(
   766    776                       typeof(SQLiteChangeSetIterator).Name);
   767    777               }
   768    778   #endif
   769    779           }
   770    780   
   771    781           ///////////////////////////////////////////////////////////////////////
   772    782   
          783  +        /// <summary>
          784  +        /// Disposes or finalizes this object instance.
          785  +        /// </summary>
          786  +        /// <param name="disposing">
          787  +        /// Non-zero if this object is being disposed; otherwise, this object
          788  +        /// is being finalized.
          789  +        /// </param>
   773    790           protected virtual void Dispose(bool disposing)
   774    791           {
   775    792               try
   776    793               {
   777    794                   if (!disposed)
   778    795                   {
   779    796                       //if (disposing)
................................................................................
   808    825               }
   809    826           }
   810    827           #endregion
   811    828   
   812    829           ///////////////////////////////////////////////////////////////////////
   813    830   
   814    831           #region Destructor
          832  +        /// <summary>
          833  +        /// Finalizes this object instance.
          834  +        /// </summary>
   815    835           ~SQLiteChangeSetIterator()
   816    836           {
   817    837               Dispose(false);
   818    838           }
   819    839           #endregion
   820    840       }
   821    841       #endregion
................................................................................
   898    918               return result;
   899    919           }
   900    920           #endregion
   901    921   
   902    922           ///////////////////////////////////////////////////////////////////////
   903    923   
   904    924           #region IDisposable "Pattern" Members
          925  +        /// <summary>
          926  +        /// Non-zero if this object instance has been disposed.
          927  +        /// </summary>
   905    928           private bool disposed;
          929  +
          930  +        /// <summary>
          931  +        /// Throws an exception if this object instance has been disposed.
          932  +        /// </summary>
   906    933           private void CheckDisposed() /* throw */
   907    934           {
   908    935   #if THROW_ON_DISPOSED
   909    936               if (disposed)
   910    937               {
   911    938                   throw new ObjectDisposedException(
   912    939                       typeof(SQLiteMemoryChangeSetIterator).Name);
   913    940               }
   914    941   #endif
   915    942           }
   916    943   
   917    944           ///////////////////////////////////////////////////////////////////////
   918    945   
          946  +        /// <summary>
          947  +        /// Disposes or finalizes this object instance.
          948  +        /// </summary>
          949  +        /// <param name="disposing">
          950  +        /// Non-zero if this object is being disposed; otherwise, this object
          951  +        /// is being finalized.
          952  +        /// </param>
   919    953           protected override void Dispose(bool disposing)
   920    954           {
   921    955               //
   922    956               // NOTE: Must dispose of the base class first (leaky abstraction)
   923    957               //       because it contains the iterator handle, which must be
   924    958               //       closed *prior* to freeing the underlying memory.
   925    959               //
................................................................................
  1037   1071               return result;
  1038   1072           }
  1039   1073           #endregion
  1040   1074   
  1041   1075           ///////////////////////////////////////////////////////////////////////
  1042   1076   
  1043   1077           #region IDisposable "Pattern" Members
         1078  +        /// <summary>
         1079  +        /// Non-zero if this object instance has been disposed.
         1080  +        /// </summary>
  1044   1081           private bool disposed;
         1082  +
         1083  +        /// <summary>
         1084  +        /// Throws an exception if this object instance has been disposed.
         1085  +        /// </summary>
  1045   1086           private void CheckDisposed() /* throw */
  1046   1087           {
  1047   1088   #if THROW_ON_DISPOSED
  1048   1089               if (disposed)
  1049   1090               {
  1050   1091                   throw new ObjectDisposedException(
  1051   1092                       typeof(SQLiteStreamChangeSetIterator).Name);
  1052   1093               }
  1053   1094   #endif
  1054   1095           }
  1055   1096   
  1056   1097           ///////////////////////////////////////////////////////////////////////
  1057   1098   
         1099  +        /// <summary>
         1100  +        /// Disposes or finalizes this object instance.
         1101  +        /// </summary>
         1102  +        /// <param name="disposing">
         1103  +        /// Non-zero if this object is being disposed; otherwise, this object
         1104  +        /// is being finalized.
         1105  +        /// </param>
  1058   1106           protected override void Dispose(bool disposing)
  1059   1107           {
  1060   1108               try
  1061   1109               {
  1062   1110                   if (!disposed)
  1063   1111                   {
  1064   1112                       //if (disposing)
................................................................................
  1086   1134           #endregion
  1087   1135       }
  1088   1136       #endregion
  1089   1137   
  1090   1138       ///////////////////////////////////////////////////////////////////////////
  1091   1139   
  1092   1140       #region SQLiteStreamAdapter Class
         1141  +    /// <summary>
         1142  +    /// This class is used to act as a bridge between a <see cref="Stream" />
         1143  +    /// instance and the delegates used with the native streaming API.
         1144  +    /// </summary>
  1093   1145       internal sealed class SQLiteStreamAdapter : IDisposable
  1094   1146       {
  1095   1147           #region Private Data
  1096         -        private Stream stream; /* EXEMPT: NOT OWNED */
         1148  +        /// <summary>
         1149  +        /// The managed stream instance used to in order to service the native
         1150  +        /// delegates for both input and output.
         1151  +        /// </summary>
         1152  +        private Stream stream;
         1153  +
         1154  +        /// <summary>
         1155  +        /// The flags associated with the connection.
         1156  +        /// </summary>
  1097   1157           private SQLiteConnectionFlags flags;
  1098   1158   
  1099   1159           ///////////////////////////////////////////////////////////////////////
  1100   1160   
         1161  +        /// <summary>
         1162  +        /// The delegate used to provide input to the native streaming API.
         1163  +        /// It will be null -OR- point to the <see cref="Input" /> method.
         1164  +        /// method.
         1165  +        /// </summary>
  1101   1166           private UnsafeNativeMethods.xSessionInput xInput;
         1167  +
         1168  +        /// <summary>
         1169  +        /// The delegate used to provide output to the native streaming API.
         1170  +        /// It will be null -OR- point to the <see cref="Output" /> method.
         1171  +        /// </summary>
  1102   1172           private UnsafeNativeMethods.xSessionOutput xOutput;
  1103   1173           #endregion
  1104   1174   
  1105   1175           ///////////////////////////////////////////////////////////////////////
  1106   1176   
  1107   1177           #region Public Constructors
         1178  +        /// <summary>
         1179  +        /// Constructs a new instance of this class using the specified managed
         1180  +        /// stream and connection flags.
         1181  +        /// </summary>
         1182  +        /// <param name="stream">
         1183  +        /// The managed stream instance to be used in order to service the
         1184  +        /// native delegates for both input and output.
         1185  +        /// </param>
         1186  +        /// <param name="flags">
         1187  +        /// The flags associated with the parent connection.
         1188  +        /// </param>
  1108   1189           public SQLiteStreamAdapter(
  1109   1190               Stream stream,
  1110   1191               SQLiteConnectionFlags flags
  1111   1192               )
  1112   1193           {
  1113   1194               this.stream = stream;
  1114   1195               this.flags = flags;
  1115   1196           }
  1116   1197           #endregion
  1117   1198   
  1118   1199           ///////////////////////////////////////////////////////////////////////
  1119   1200   
  1120   1201           #region Private Methods
         1202  +        /// <summary>
         1203  +        /// Queries and returns the flags associated with the connection for
         1204  +        /// this instance.
         1205  +        /// </summary>
         1206  +        /// <returns>
         1207  +        /// The <see cref="SQLiteConnectionFlags" /> value.  There is no return
         1208  +        /// value reserved to indicate an error.
         1209  +        /// </returns>
  1121   1210           private SQLiteConnectionFlags GetFlags()
  1122   1211           {
  1123   1212               return flags;
  1124   1213           }
  1125   1214           #endregion
  1126   1215   
  1127   1216           ///////////////////////////////////////////////////////////////////////
  1128   1217   
  1129   1218           #region Public Methods
         1219  +        /// <summary>
         1220  +        /// Returns a delegate that wraps the <see cref="Input" /> method,
         1221  +        /// creating it first if necessary.
         1222  +        /// </summary>
         1223  +        /// <returns>
         1224  +        /// A delegate that refers to the <see cref="Input" /> method.
         1225  +        /// </returns>
  1130   1226           public UnsafeNativeMethods.xSessionInput GetInputDelegate()
  1131   1227           {
  1132   1228               CheckDisposed();
  1133   1229   
  1134   1230               if (xInput == null)
  1135   1231                   xInput = new UnsafeNativeMethods.xSessionInput(Input);
  1136   1232   
  1137   1233               return xInput;
  1138   1234           }
  1139   1235   
  1140   1236           ///////////////////////////////////////////////////////////////////////
  1141   1237   
         1238  +        /// <summary>
         1239  +        /// Returns a delegate that wraps the <see cref="Output" /> method,
         1240  +        /// creating it first if necessary.
         1241  +        /// </summary>
         1242  +        /// <returns>
         1243  +        /// A delegate that refers to the <see cref="Output" /> method.
         1244  +        /// </returns>
  1142   1245           public UnsafeNativeMethods.xSessionOutput GetOutputDelegate()
  1143   1246           {
  1144   1247               CheckDisposed();
  1145   1248   
  1146   1249               if (xOutput == null)
  1147   1250                   xOutput = new UnsafeNativeMethods.xSessionOutput(Output);
  1148   1251   
................................................................................
  1149   1252               return xOutput;
  1150   1253           }
  1151   1254           #endregion
  1152   1255   
  1153   1256           ///////////////////////////////////////////////////////////////////////
  1154   1257   
  1155   1258           #region Native Callback Methods
         1259  +        /// <summary>
         1260  +        /// This method attempts to read <paramref name="nData" /> bytes from
         1261  +        /// the managed stream, writing them to the <paramref name="pData"/>
         1262  +        /// buffer.
         1263  +        /// </summary>
         1264  +        /// <param name="context">
         1265  +        /// Optional extra context information.  Currently, this will always
         1266  +        /// have a value of <see cref="IntPtr.Zero" />.
         1267  +        /// </param>
         1268  +        /// <param name="pData">
         1269  +        /// A preallocated native buffer to receive the requested input bytes.
         1270  +        /// It must be at least <see cref="nData" /> bytes in size.
         1271  +        /// </param>
         1272  +        /// <param name="nData">
         1273  +        /// Upon entry, the number of bytes to read.  Upon exit, the number of
         1274  +        /// bytes actually read.  This value may be zero upon exit.
         1275  +        /// </param>
         1276  +        /// <returns>
         1277  +        /// The value <see cref="SQLiteErrorCode.Ok" /> upon success -OR- an
         1278  +        /// appropriate error code upon failure.
         1279  +        /// </returns>
  1156   1280           private SQLiteErrorCode Input(
  1157   1281               IntPtr context,
  1158   1282               IntPtr pData,
  1159   1283               ref int nData
  1160   1284               )
  1161   1285           {
  1162   1286               try
................................................................................
  1200   1324               }
  1201   1325   
  1202   1326               return SQLiteErrorCode.IoErr_Read;
  1203   1327           }
  1204   1328   
  1205   1329           ///////////////////////////////////////////////////////////////////////
  1206   1330   
         1331  +        /// <summary>
         1332  +        /// This method attempts to write <paramref name="nData" /> bytes to
         1333  +        /// the managed stream, reading them from the <paramref name="pData"/>
         1334  +        /// buffer.
         1335  +        /// </summary>
         1336  +        /// <param name="context">
         1337  +        /// Optional extra context information.  Currently, this will always
         1338  +        /// have a value of <see cref="IntPtr.Zero" />.
         1339  +        /// </param>
         1340  +        /// <param name="pData">
         1341  +        /// A preallocated native buffer containing the requested output
         1342  +        /// bytes.  It must be at least <see cref="nData" /> bytes in size.
         1343  +        /// </param>
         1344  +        /// <param name="nData">
         1345  +        /// The number of bytes to write.
         1346  +        /// </param>
         1347  +        /// <returns>
         1348  +        /// The value <see cref="SQLiteErrorCode.Ok" /> upon success -OR- an
         1349  +        /// appropriate error code upon failure.
         1350  +        /// </returns>
  1207   1351           private SQLiteErrorCode Output(
  1208   1352               IntPtr context,
  1209   1353               IntPtr pData,
  1210   1354               int nData
  1211   1355               )
  1212   1356           {
  1213   1357               try
................................................................................
  1254   1398               return SQLiteErrorCode.IoErr_Write;
  1255   1399           }
  1256   1400           #endregion
  1257   1401   
  1258   1402           ///////////////////////////////////////////////////////////////////////
  1259   1403   
  1260   1404           #region IDisposable Members
         1405  +        /// <summary>
         1406  +        /// Disposes of this object instance.
         1407  +        /// </summary>
  1261   1408           public void Dispose()
  1262   1409           {
  1263   1410               Dispose(true);
  1264   1411               GC.SuppressFinalize(this);
  1265   1412           }
  1266   1413           #endregion
  1267   1414   
  1268   1415           ///////////////////////////////////////////////////////////////////////
  1269   1416   
  1270   1417           #region IDisposable "Pattern" Members
         1418  +        /// <summary>
         1419  +        /// Non-zero if this object instance has been disposed.
         1420  +        /// </summary>
  1271   1421           private bool disposed;
         1422  +
         1423  +        /// <summary>
         1424  +        /// Throws an exception if this object instance has been disposed.
         1425  +        /// </summary>
  1272   1426           private void CheckDisposed() /* throw */
  1273   1427           {
  1274   1428   #if THROW_ON_DISPOSED
  1275   1429               if (disposed)
  1276   1430               {
  1277   1431                   throw new ObjectDisposedException(
  1278   1432                       typeof(SQLiteStreamAdapter).Name);
  1279   1433               }
  1280   1434   #endif
  1281   1435           }
  1282   1436   
  1283   1437           ///////////////////////////////////////////////////////////////////////
  1284   1438   
         1439  +        /// <summary>
         1440  +        /// Disposes or finalizes this object instance.
         1441  +        /// </summary>
         1442  +        /// <param name="disposing">
         1443  +        /// Non-zero if this object is being disposed; otherwise, this object
         1444  +        /// is being finalized.
         1445  +        /// </param>
  1285   1446           private /* protected virtual */ void Dispose(bool disposing)
  1286   1447           {
  1287   1448               try
  1288   1449               {
  1289   1450                   if (!disposed)
  1290   1451                   {
  1291   1452                       if (disposing)
................................................................................
  1318   1479               }
  1319   1480           }
  1320   1481           #endregion
  1321   1482   
  1322   1483           ///////////////////////////////////////////////////////////////////////
  1323   1484   
  1324   1485           #region Destructor
         1486  +        /// <summary>
         1487  +        /// Finalizes this object instance.
         1488  +        /// </summary>
  1325   1489           ~SQLiteStreamAdapter()
  1326   1490           {
  1327   1491               Dispose(false);
  1328   1492           }
  1329   1493           #endregion
  1330   1494       }
  1331   1495       #endregion
  1332   1496   
  1333   1497       ///////////////////////////////////////////////////////////////////////////
  1334   1498   
  1335   1499       #region SQLiteSessionStreamManager Class
         1500  +    /// <summary>
         1501  +    /// This class manages a collection of <see cref="SQLiteStreamAdapter"/>
         1502  +    /// instances. When used, it takes responsibility for creating, returning,
         1503  +    /// and disposing of its <see cref="SQLiteStreamAdapter"/> instances.
         1504  +    /// </summary>
  1336   1505       internal sealed class SQLiteSessionStreamManager : IDisposable
  1337   1506       {
  1338   1507           #region Private Data
         1508  +        /// <summary>
         1509  +        /// The managed collection of <see cref="SQLiteStreamAdapter" />
         1510  +        /// instances, keyed by their associated <see cref="Stream" />
         1511  +        /// instance.
         1512  +        /// </summary>
  1339   1513           private Dictionary<Stream, SQLiteStreamAdapter> streamAdapters;
         1514  +
         1515  +        /// <summary>
         1516  +        /// The flags associated with the connection.
         1517  +        /// </summary>
  1340   1518           private SQLiteConnectionFlags flags;
  1341   1519           #endregion
  1342   1520   
  1343   1521           ///////////////////////////////////////////////////////////////////////
  1344   1522   
  1345   1523           #region Public Constructors
         1524  +        /// <summary>
         1525  +        /// Constructs a new instance of this class using the specified
         1526  +        /// connection flags.
         1527  +        /// </summary>
         1528  +        /// <param name="flags">
         1529  +        /// The flags associated with the parent connection.
         1530  +        /// </param>
  1346   1531           public SQLiteSessionStreamManager(
  1347   1532               SQLiteConnectionFlags flags
  1348   1533               )
  1349   1534           {
  1350   1535               this.flags = flags;
  1351   1536   
  1352   1537               InitializeStreamAdapters();
  1353   1538           }
  1354   1539           #endregion
  1355   1540   
  1356   1541           ///////////////////////////////////////////////////////////////////////
  1357   1542   
  1358   1543           #region Private Methods
         1544  +        /// <summary>
         1545  +        /// Makes sure the collection of <see cref="SQLiteStreamAdapter" />
         1546  +        /// is created.
         1547  +        /// </summary>
  1359   1548           private void InitializeStreamAdapters()
  1360   1549           {
  1361   1550               if (streamAdapters != null)
  1362   1551                   return;
  1363   1552   
  1364   1553               streamAdapters = new Dictionary<Stream, SQLiteStreamAdapter>();
  1365   1554           }
  1366   1555   
  1367   1556           ///////////////////////////////////////////////////////////////////////
  1368   1557   
         1558  +        /// <summary>
         1559  +        /// Makes sure the collection of <see cref="SQLiteStreamAdapter" />
         1560  +        /// is disposed.
         1561  +        /// </summary>
  1369   1562           private void DisposeStreamAdapters()
  1370   1563           {
  1371   1564               if (streamAdapters == null)
  1372   1565                   return;
  1373   1566   
  1374   1567               foreach (KeyValuePair<Stream, SQLiteStreamAdapter> pair
  1375   1568                       in streamAdapters)
................................................................................
  1386   1579               streamAdapters = null;
  1387   1580           }
  1388   1581           #endregion
  1389   1582   
  1390   1583           ///////////////////////////////////////////////////////////////////////
  1391   1584   
  1392   1585           #region Public Methods
         1586  +        /// <summary>
         1587  +        /// Attempts to return a <see cref="SQLiteStreamAdapter" /> instance
         1588  +        /// suitable for the specified <see cref="Stream" />.
         1589  +        /// </summary>
         1590  +        /// <param name="stream">
         1591  +        /// The <see cref="Stream" /> instance.  If this value is null, a null
         1592  +        /// value will be returned.
         1593  +        /// </param>
         1594  +        /// <returns>
         1595  +        /// A <see cref="SQLiteStreamAdapter" /> instance.  Typically, these
         1596  +        /// are always freshly created; however, this method is designed to
         1597  +        /// return the existing <see cref="SQLiteStreamAdapter" /> instance
         1598  +        /// associated with the specified stream, should one exist.
         1599  +        /// </returns>
  1393   1600           public SQLiteStreamAdapter GetAdapter(
  1394   1601               Stream stream
  1395   1602               )
  1396   1603           {
  1397   1604               CheckDisposed();
  1398   1605   
  1399   1606               if (stream == null)
................................................................................
  1410   1617               return streamAdapter;
  1411   1618           }
  1412   1619           #endregion
  1413   1620   
  1414   1621           ///////////////////////////////////////////////////////////////////////
  1415   1622   
  1416   1623           #region IDisposable Members
         1624  +        /// <summary>
         1625  +        /// Disposes of this object instance.
         1626  +        /// </summary>
  1417   1627           public void Dispose()
  1418   1628           {
  1419   1629               Dispose(true);
  1420   1630               GC.SuppressFinalize(this);
  1421   1631           }
  1422   1632           #endregion
  1423   1633   
  1424   1634           ///////////////////////////////////////////////////////////////////////
  1425   1635   
  1426   1636           #region IDisposable "Pattern" Members
         1637  +        /// <summary>
         1638  +        /// Non-zero if this object instance has been disposed.
         1639  +        /// </summary>
  1427   1640           private bool disposed;
         1641  +
         1642  +        /// <summary>
         1643  +        /// Throws an exception if this object instance has been disposed.
         1644  +        /// </summary>
  1428   1645           private void CheckDisposed() /* throw */
  1429   1646           {
  1430   1647   #if THROW_ON_DISPOSED
  1431   1648               if (disposed)
  1432   1649               {
  1433   1650                   throw new ObjectDisposedException(
  1434   1651                       typeof(SQLiteSessionStreamManager).Name);
  1435   1652               }
  1436   1653   #endif
  1437   1654           }
  1438   1655   
  1439   1656           ///////////////////////////////////////////////////////////////////////
  1440   1657   
         1658  +        /// <summary>
         1659  +        /// Disposes or finalizes this object instance.
         1660  +        /// </summary>
         1661  +        /// <param name="disposing">
         1662  +        /// Non-zero if this object is being disposed; otherwise, this object
         1663  +        /// is being finalized.
         1664  +        /// </param>
  1441   1665           private /* protected virtual */ void Dispose(bool disposing)
  1442   1666           {
  1443   1667               try
  1444   1668               {
  1445   1669                   if (!disposed)
  1446   1670                   {
  1447   1671                       if (disposing)
................................................................................
  1467   1691               }
  1468   1692           }
  1469   1693           #endregion
  1470   1694   
  1471   1695           ///////////////////////////////////////////////////////////////////////
  1472   1696   
  1473   1697           #region Destructor
         1698  +        /// <summary>
         1699  +        /// Finalizes this object instance.
         1700  +        /// </summary>
  1474   1701           ~SQLiteSessionStreamManager()
  1475   1702           {
  1476   1703               Dispose(false);
  1477   1704           }
  1478   1705           #endregion
  1479   1706       }
  1480   1707       #endregion
  1481   1708   
  1482   1709       ///////////////////////////////////////////////////////////////////////////
  1483   1710   
  1484   1711       #region SQLiteChangeGroup Class
         1712  +    /// <summary>
         1713  +    /// This class represents a group of change sets (or patch sets).
         1714  +    /// </summary>
  1485   1715       internal sealed class SQLiteChangeGroup : ISQLiteChangeGroup
  1486   1716       {
  1487   1717           #region Private Data
         1718  +        /// <summary>
         1719  +        /// The <see cref="SQLiteSessionStreamManager" /> instance associated
         1720  +        /// with this change group.
         1721  +        /// </summary>
  1488   1722           private SQLiteSessionStreamManager streamManager;
         1723  +
         1724  +        /// <summary>
         1725  +        /// The flags associated with the connection.
         1726  +        /// </summary>
  1489   1727           private SQLiteConnectionFlags flags;
  1490   1728   
  1491   1729           ///////////////////////////////////////////////////////////////////////
  1492   1730   
         1731  +        /// <summary>
         1732  +        /// The native handle for this change group.  This will be deleted when
         1733  +        /// this instance is disposed or finalized.
         1734  +        /// </summary>
  1493   1735           private IntPtr changeGroup;
  1494   1736           #endregion
  1495   1737   
  1496   1738           ///////////////////////////////////////////////////////////////////////
  1497   1739   
  1498   1740           #region Public Constructors
         1741  +        /// <summary>
         1742  +        /// Constructs a new instance of this class using the specified
         1743  +        /// connection flags.
         1744  +        /// </summary>
         1745  +        /// <param name="flags">
         1746  +        /// The flags associated with the parent connection.
         1747  +        /// </param>
  1499   1748           public SQLiteChangeGroup(
  1500   1749               SQLiteConnectionFlags flags
  1501   1750               )
  1502   1751           {
  1503   1752               this.flags = flags;
  1504   1753   
  1505   1754               InitializeHandle();
  1506   1755           }
  1507   1756           #endregion
  1508   1757   
  1509   1758           ///////////////////////////////////////////////////////////////////////
  1510   1759   
  1511   1760           #region Private Methods
         1761  +        /// <summary>
         1762  +        /// Throws an exception if the native change group handle is invalid.
         1763  +        /// </summary>
  1512   1764           private void CheckHandle()
  1513   1765           {
  1514   1766               if (changeGroup == IntPtr.Zero)
  1515   1767                   throw new InvalidOperationException("change group not open");
  1516   1768           }
  1517   1769   
  1518   1770           ///////////////////////////////////////////////////////////////////////
  1519   1771   
         1772  +        /// <summary>
         1773  +        /// Makes sure the native change group handle is valid, creating it if
         1774  +        /// necessary.
         1775  +        /// </summary>
  1520   1776           private void InitializeHandle()
  1521   1777           {
  1522   1778               if (changeGroup != IntPtr.Zero)
  1523   1779                   return;
  1524   1780   
  1525   1781               SQLiteErrorCode rc = UnsafeNativeMethods.sqlite3changegroup_new(
  1526   1782                   ref changeGroup);
................................................................................
  1527   1783   
  1528   1784               if (rc != SQLiteErrorCode.Ok)
  1529   1785                   throw new SQLiteException(rc, "sqlite3changegroup_new");
  1530   1786           }
  1531   1787   
  1532   1788           ///////////////////////////////////////////////////////////////////////
  1533   1789   
         1790  +        /// <summary>
         1791  +        /// Makes sure the <see cref="SQLiteSessionStreamManager" /> instance
         1792  +        /// is available, creating it if necessary.
         1793  +        /// </summary>
  1534   1794           private void InitializeStreamManager()
  1535   1795           {
  1536   1796               if (streamManager != null)
  1537   1797                   return;
  1538   1798   
  1539   1799               streamManager = new SQLiteSessionStreamManager(flags);
  1540   1800           }
  1541   1801   
  1542   1802           ///////////////////////////////////////////////////////////////////////
  1543   1803   
         1804  +        /// <summary>
         1805  +        /// Attempts to return a <see cref="SQLiteStreamAdapter" /> instance
         1806  +        /// suitable for the specified <see cref="Stream" />.
         1807  +        /// </summary>
         1808  +        /// <param name="stream">
         1809  +        /// The <see cref="Stream" /> instance.  If this value is null, a null
         1810  +        /// value will be returned.
         1811  +        /// </param>
         1812  +        /// <returns>
         1813  +        /// A <see cref="SQLiteStreamAdapter" /> instance.  Typically, these
         1814  +        /// are always freshly created; however, this method is designed to
         1815  +        /// return the existing <see cref="SQLiteStreamAdapter" /> instance
         1816  +        /// associated with the specified stream, should one exist.
         1817  +        /// </returns>
  1544   1818           private SQLiteStreamAdapter GetStreamAdapter(
  1545   1819               Stream stream
  1546   1820               )
  1547   1821           {
  1548   1822               InitializeStreamManager();
  1549   1823   
  1550   1824               return streamManager.GetAdapter(stream);
  1551   1825           }
  1552   1826           #endregion
  1553   1827   
  1554   1828           ///////////////////////////////////////////////////////////////////////
  1555   1829   
  1556   1830           #region ISQLiteChangeGroup Members
         1831  +        /// <summary>
         1832  +        /// Attempts to add a change set (or patch set) to this change group
         1833  +        /// instance.  The underlying data must be contained entirely within
         1834  +        /// the <paramref name="rawData" /> byte array.
         1835  +        /// </summary>
         1836  +        /// <param name="rawData">
         1837  +        /// The raw byte data for the specified change set (or patch set).
         1838  +        /// </param>
  1557   1839           public void AddChangeSet(
  1558   1840               byte[] rawData
  1559   1841               )
  1560   1842           {
  1561   1843               CheckDisposed();
  1562   1844               CheckHandle();
  1563   1845   
................................................................................
  1585   1867                       pData = IntPtr.Zero;
  1586   1868                   }
  1587   1869               }
  1588   1870           }
  1589   1871   
  1590   1872           ///////////////////////////////////////////////////////////////////////
  1591   1873   
         1874  +        /// <summary>
         1875  +        /// Attempts to add a change set (or patch set) to this change group
         1876  +        /// instance.  The underlying data will be read from the specified
         1877  +        /// <see cref="Stream" />.
         1878  +        /// </summary>
         1879  +        /// <param name="stream">
         1880  +        /// The <see cref="Stream" /> instance containing the raw change set
         1881  +        /// (or patch set) data to read.
         1882  +        /// </param>
  1592   1883           public void AddChangeSet(
  1593   1884               Stream stream
  1594   1885               )
  1595   1886           {
  1596   1887               CheckDisposed();
  1597   1888               CheckHandle();
  1598   1889   
................................................................................
  1612   1903   
  1613   1904               if (rc != SQLiteErrorCode.Ok)
  1614   1905                   throw new SQLiteException(rc, "sqlite3changegroup_add_strm");
  1615   1906           }
  1616   1907   
  1617   1908           ///////////////////////////////////////////////////////////////////////
  1618   1909   
         1910  +        /// <summary>
         1911  +        /// Attempts to create and return, via <paramref name="rawData" />, the
         1912  +        /// combined set of changes represented by this change group instance.
         1913  +        /// </summary>
         1914  +        /// <param name="rawData">
         1915  +        /// Upon success, this will contain the raw byte data for all the
         1916  +        /// changes in this change group instance.
         1917  +        /// </param>
  1619   1918           public void CreateChangeSet(
  1620   1919               ref byte[] rawData
  1621   1920               )
  1622   1921           {
  1623   1922               CheckDisposed();
  1624   1923               CheckHandle();
  1625   1924   
................................................................................
  1647   1946                       pData = IntPtr.Zero;
  1648   1947                   }
  1649   1948               }
  1650   1949           }
  1651   1950   
  1652   1951           ///////////////////////////////////////////////////////////////////////
  1653   1952   
         1953  +        /// <summary>
         1954  +        /// Attempts to create and write, via <paramref name="stream" />, the
         1955  +        /// combined set of changes represented by this change group instance.
         1956  +        /// </summary>
         1957  +        /// <param name="stream">
         1958  +        /// Upon success, the raw byte data for all the changes in this change
         1959  +        /// group instance will be written to this <see cref="Stream" />.
         1960  +        /// </param>
  1654   1961           public void CreateChangeSet(
  1655   1962               Stream stream
  1656   1963               )
  1657   1964           {
  1658   1965               CheckDisposed();
  1659   1966               CheckHandle();
  1660   1967   
................................................................................
  1676   1983                   throw new SQLiteException(rc, "sqlite3changegroup_output_strm");
  1677   1984           }
  1678   1985           #endregion
  1679   1986   
  1680   1987           ///////////////////////////////////////////////////////////////////////
  1681   1988   
  1682   1989           #region IDisposable Members
         1990  +        /// <summary>
         1991  +        /// Disposes of this object instance.
         1992  +        /// </summary>
  1683   1993           public void Dispose()
  1684   1994           {
  1685   1995               Dispose(true);
  1686   1996               GC.SuppressFinalize(this);
  1687   1997           }
  1688   1998           #endregion
  1689   1999   
  1690   2000           ///////////////////////////////////////////////////////////////////////
  1691   2001   
  1692   2002           #region IDisposable "Pattern" Members
         2003  +        /// <summary>
         2004  +        /// Non-zero if this object instance has been disposed.
         2005  +        /// </summary>
  1693   2006           private bool disposed;
         2007  +
         2008  +        /// <summary>
         2009  +        /// Throws an exception if this object instance has been disposed.
         2010  +        /// </summary>
  1694   2011           private void CheckDisposed() /* throw */
  1695   2012           {
  1696   2013   #if THROW_ON_DISPOSED
  1697   2014               if (disposed)
  1698   2015               {
  1699   2016                   throw new ObjectDisposedException(
  1700   2017                       typeof(SQLiteChangeGroup).Name);
  1701   2018               }
  1702   2019   #endif
  1703   2020           }
  1704   2021   
  1705   2022           ///////////////////////////////////////////////////////////////////////
  1706   2023   
         2024  +        /// <summary>
         2025  +        /// Disposes or finalizes this object instance.
         2026  +        /// </summary>
         2027  +        /// <param name="disposing">
         2028  +        /// Non-zero if this object is being disposed; otherwise, this object
         2029  +        /// is being finalized.
         2030  +        /// </param>
  1707   2031           private /* protected virtual */ void Dispose(bool disposing)
  1708   2032           {
  1709   2033               try
  1710   2034               {
  1711   2035                   if (!disposed)
  1712   2036                   {
  1713   2037                       if (disposing)
................................................................................
  1745   2069               }
  1746   2070           }
  1747   2071           #endregion
  1748   2072   
  1749   2073           ///////////////////////////////////////////////////////////////////////
  1750   2074   
  1751   2075           #region Destructor
         2076  +        /// <summary>
         2077  +        /// Finalizes this object instance.
         2078  +        /// </summary>
  1752   2079           ~SQLiteChangeGroup()
  1753   2080           {
  1754   2081               Dispose(false);
  1755   2082           }
  1756   2083           #endregion
  1757   2084       }
  1758   2085       #endregion
................................................................................
  2175   2502               }
  2176   2503           }
  2177   2504           #endregion
  2178   2505   
  2179   2506           ///////////////////////////////////////////////////////////////////////
  2180   2507   
  2181   2508           #region IDisposable "Pattern" Members
         2509  +        /// <summary>
         2510  +        /// Non-zero if this object instance has been disposed.
         2511  +        /// </summary>
  2182   2512           private bool disposed;
         2513  +
         2514  +        /// <summary>
         2515  +        /// Throws an exception if this object instance has been disposed.
         2516  +        /// </summary>
  2183   2517           private void CheckDisposed() /* throw */
  2184   2518           {
  2185   2519   #if THROW_ON_DISPOSED
  2186   2520               if (disposed)
  2187   2521                   throw new ObjectDisposedException(typeof(SQLiteSession).Name);
  2188   2522   #endif
  2189   2523           }
  2190   2524   
  2191   2525           ///////////////////////////////////////////////////////////////////////
  2192   2526   
         2527  +        /// <summary>
         2528  +        /// Disposes or finalizes this object instance.
         2529  +        /// </summary>
         2530  +        /// <param name="disposing">
         2531  +        /// Non-zero if this object is being disposed; otherwise, this object
         2532  +        /// is being finalized.
         2533  +        /// </param>
  2193   2534           protected override void Dispose(bool disposing)
  2194   2535           {
  2195   2536               try
  2196   2537               {
  2197   2538                   if (!disposed)
  2198   2539                   {
  2199   2540                       if (disposing)
................................................................................
  2372   2713               return xConflict;
  2373   2714           }
  2374   2715           #endregion
  2375   2716   
  2376   2717           ///////////////////////////////////////////////////////////////////////
  2377   2718   
  2378   2719           #region IDisposable "Pattern" Members
         2720  +        /// <summary>
         2721  +        /// Non-zero if this object instance has been disposed.
         2722  +        /// </summary>
  2379   2723           private bool disposed;
         2724  +
         2725  +        /// <summary>
         2726  +        /// Throws an exception if this object instance has been disposed.
         2727  +        /// </summary>
  2380   2728           private void CheckDisposed() /* throw */
  2381   2729           {
  2382   2730   #if THROW_ON_DISPOSED
  2383   2731               if (disposed)
  2384   2732               {
  2385   2733                   throw new ObjectDisposedException(
  2386   2734                       typeof(SQLiteChangeSetBase).Name);
  2387   2735               }
  2388   2736   #endif
  2389   2737           }
  2390   2738   
  2391   2739           ///////////////////////////////////////////////////////////////////////
  2392   2740   
         2741  +        /// <summary>
         2742  +        /// Disposes or finalizes this object instance.
         2743  +        /// </summary>
         2744  +        /// <param name="disposing">
         2745  +        /// Non-zero if this object is being disposed; otherwise, this object
         2746  +        /// is being finalized.
         2747  +        /// </param>
  2393   2748           protected override void Dispose(bool disposing)
  2394   2749           {
  2395   2750               try
  2396   2751               {
  2397   2752                   if (!disposed)
  2398   2753                   {
  2399   2754                       if (disposing)
................................................................................
  2642   2997               return GetEnumerator();
  2643   2998           }
  2644   2999           #endregion
  2645   3000   
  2646   3001           ///////////////////////////////////////////////////////////////////////
  2647   3002   
  2648   3003           #region IDisposable "Pattern" Members
         3004  +        /// <summary>
         3005  +        /// Non-zero if this object instance has been disposed.
         3006  +        /// </summary>
  2649   3007           private bool disposed;
         3008  +
         3009  +        /// <summary>
         3010  +        /// Throws an exception if this object instance has been disposed.
         3011  +        /// </summary>
  2650   3012           private void CheckDisposed() /* throw */
  2651   3013           {
  2652   3014   #if THROW_ON_DISPOSED
  2653   3015               if (disposed)
  2654   3016               {
  2655   3017                   throw new ObjectDisposedException(
  2656   3018                       typeof(SQLiteMemoryChangeSet).Name);
  2657   3019               }
  2658   3020   #endif
  2659   3021           }
  2660   3022   
  2661   3023           ///////////////////////////////////////////////////////////////////////
  2662   3024   
         3025  +        /// <summary>
         3026  +        /// Disposes or finalizes this object instance.
         3027  +        /// </summary>
         3028  +        /// <param name="disposing">
         3029  +        /// Non-zero if this object is being disposed; otherwise, this object
         3030  +        /// is being finalized.
         3031  +        /// </param>
  2663   3032           protected override void Dispose(bool disposing)
  2664   3033           {
  2665   3034               try
  2666   3035               {
  2667   3036                   if (!disposed)
  2668   3037                   {
  2669   3038                       if (disposing)
................................................................................
  2873   3242               return GetEnumerator();
  2874   3243           }
  2875   3244           #endregion
  2876   3245   
  2877   3246           ///////////////////////////////////////////////////////////////////////
  2878   3247   
  2879   3248           #region IDisposable "Pattern" Members
         3249  +        /// <summary>
         3250  +        /// Non-zero if this object instance has been disposed.
         3251  +        /// </summary>
  2880   3252           private bool disposed;
         3253  +
         3254  +        /// <summary>
         3255  +        /// Throws an exception if this object instance has been disposed.
         3256  +        /// </summary>
  2881   3257           private void CheckDisposed() /* throw */
  2882   3258           {
  2883   3259   #if THROW_ON_DISPOSED
  2884   3260               if (disposed)
  2885   3261               {
  2886   3262                   throw new ObjectDisposedException(
  2887   3263                       typeof(SQLiteStreamChangeSet).Name);
  2888   3264               }
  2889   3265   #endif
  2890   3266           }
  2891   3267   
  2892   3268           ///////////////////////////////////////////////////////////////////////
  2893   3269   
         3270  +        /// <summary>
         3271  +        /// Disposes or finalizes this object instance.
         3272  +        /// </summary>
         3273  +        /// <param name="disposing">
         3274  +        /// Non-zero if this object is being disposed; otherwise, this object
         3275  +        /// is being finalized.
         3276  +        /// </param>
  2894   3277           protected override void Dispose(bool disposing)
  2895   3278           {
  2896   3279               try
  2897   3280               {
  2898   3281                   if (!disposed)
  2899   3282                   {
  2900   3283                       if (disposing)
................................................................................
  3042   3425               throw new NotImplementedException();
  3043   3426           }
  3044   3427           #endregion
  3045   3428   
  3046   3429           ///////////////////////////////////////////////////////////////////////
  3047   3430   
  3048   3431           #region IDisposable Members
         3432  +        /// <summary>
         3433  +        /// Disposes of this object instance.
         3434  +        /// </summary>
  3049   3435           public void Dispose()
  3050   3436           {
  3051   3437               Dispose(true);
  3052   3438               GC.SuppressFinalize(this);
  3053   3439           }
  3054   3440           #endregion
  3055   3441   
  3056   3442           ///////////////////////////////////////////////////////////////////////
  3057   3443   
  3058   3444           #region IDisposable "Pattern" Members
         3445  +        /// <summary>
         3446  +        /// Non-zero if this object instance has been disposed.
         3447  +        /// </summary>
  3059   3448           private bool disposed;
         3449  +
         3450  +        /// <summary>
         3451  +        /// Throws an exception if this object instance has been disposed.
         3452  +        /// </summary>
  3060   3453           private void CheckDisposed() /* throw */
  3061   3454           {
  3062   3455   #if THROW_ON_DISPOSED
  3063   3456               if (disposed)
  3064   3457               {
  3065   3458                   throw new ObjectDisposedException(
  3066   3459                       typeof(SQLiteChangeSetEnumerator).Name);
  3067   3460               }
  3068   3461   #endif
  3069   3462           }
  3070   3463   
  3071   3464           ///////////////////////////////////////////////////////////////////////
  3072   3465   
         3466  +        /// <summary>
         3467  +        /// Disposes or finalizes this object instance.
         3468  +        /// </summary>
         3469  +        /// <param name="disposing">
         3470  +        /// Non-zero if this object is being disposed; otherwise, this object
         3471  +        /// is being finalized.
         3472  +        /// </param>
  3073   3473           protected virtual void Dispose(bool disposing)
  3074   3474           {
  3075   3475               try
  3076   3476               {
  3077   3477                   if (!disposed)
  3078   3478                   {
  3079   3479                       if (disposing)
................................................................................
  3099   3499               }
  3100   3500           }
  3101   3501           #endregion
  3102   3502   
  3103   3503           ///////////////////////////////////////////////////////////////////////
  3104   3504   
  3105   3505           #region Destructor
         3506  +        /// <summary>
         3507  +        /// Finalizes this object instance.
         3508  +        /// </summary>
  3106   3509           ~SQLiteChangeSetEnumerator()
  3107   3510           {
  3108   3511               Dispose(false);
  3109   3512           }
  3110   3513           #endregion
  3111   3514       }
  3112   3515       #endregion
................................................................................
  3143   3546               ResetIterator(SQLiteMemoryChangeSetIterator.Create(rawData));
  3144   3547           }
  3145   3548           #endregion
  3146   3549   
  3147   3550           ///////////////////////////////////////////////////////////////////////
  3148   3551   
  3149   3552           #region IDisposable "Pattern" Members
         3553  +        /// <summary>
         3554  +        /// Non-zero if this object instance has been disposed.
         3555  +        /// </summary>
  3150   3556           private bool disposed;
         3557  +
         3558  +        /// <summary>
         3559  +        /// Throws an exception if this object instance has been disposed.
         3560  +        /// </summary>
  3151   3561           private void CheckDisposed() /* throw */
  3152   3562           {
  3153   3563   #if THROW_ON_DISPOSED
  3154   3564               if (disposed)
  3155   3565               {
  3156   3566                   throw new ObjectDisposedException(
  3157   3567                       typeof(SQLiteMemoryChangeSetEnumerator).Name);
  3158   3568               }
  3159   3569   #endif
  3160   3570           }
  3161   3571   
  3162   3572           ///////////////////////////////////////////////////////////////////////
  3163   3573   
         3574  +        /// <summary>
         3575  +        /// Disposes or finalizes this object instance.
         3576  +        /// </summary>
         3577  +        /// <param name="disposing">
         3578  +        /// Non-zero if this object is being disposed; otherwise, this object
         3579  +        /// is being finalized.
         3580  +        /// </param>
  3164   3581           protected override void Dispose(bool disposing)
  3165   3582           {
  3166   3583               try
  3167   3584               {
  3168   3585                   if (!disposed)
  3169   3586                   {
  3170   3587                       if (disposing)
................................................................................
  3209   3626               // do nothing.
  3210   3627           }
  3211   3628           #endregion
  3212   3629   
  3213   3630           ///////////////////////////////////////////////////////////////////////
  3214   3631   
  3215   3632           #region IDisposable "Pattern" Members
         3633  +        /// <summary>
         3634  +        /// Non-zero if this object instance has been disposed.
         3635  +        /// </summary>
  3216   3636           private bool disposed;
         3637  +
         3638  +        /// <summary>
         3639  +        /// Throws an exception if this object instance has been disposed.
         3640  +        /// </summary>
  3217   3641           private void CheckDisposed() /* throw */
  3218   3642           {
  3219   3643   #if THROW_ON_DISPOSED
  3220   3644               if (disposed)
  3221   3645               {
  3222   3646                   throw new ObjectDisposedException(
  3223   3647                       typeof(SQLiteStreamChangeSetEnumerator).Name);
  3224   3648               }
  3225   3649   #endif
  3226   3650           }
  3227   3651   
  3228   3652           ///////////////////////////////////////////////////////////////////////
  3229   3653   
         3654  +        /// <summary>
         3655  +        /// Disposes or finalizes this object instance.
         3656  +        /// </summary>
         3657  +        /// <param name="disposing">
         3658  +        /// Non-zero if this object is being disposed; otherwise, this object
         3659  +        /// is being finalized.
         3660  +        /// </param>
  3230   3661           protected override void Dispose(bool disposing)
  3231   3662           {
  3232   3663               try
  3233   3664               {
  3234   3665                   //if (!disposed)
  3235   3666                   //{
  3236   3667                   //    if (disposing)
................................................................................
  3509   3940               return SQLiteValue.FromIntPtr(pValue);
  3510   3941           }
  3511   3942           #endregion
  3512   3943   
  3513   3944           ///////////////////////////////////////////////////////////////////////
  3514   3945   
  3515   3946           #region IDisposable Members
         3947  +        /// <summary>
         3948  +        /// Disposes of this object instance.
         3949  +        /// </summary>
  3516   3950           public void Dispose()
  3517   3951           {
  3518   3952               Dispose(true);
  3519   3953               GC.SuppressFinalize(this);
  3520   3954           }
  3521   3955           #endregion
  3522   3956   
  3523   3957           ///////////////////////////////////////////////////////////////////////
  3524   3958   
  3525   3959           #region IDisposable "Pattern" Members
         3960  +        /// <summary>
         3961  +        /// Non-zero if this object instance has been disposed.
         3962  +        /// </summary>
  3526   3963           private bool disposed;
         3964  +
         3965  +        /// <summary>
         3966  +        /// Throws an exception if this object instance has been disposed.
         3967  +        /// </summary>
  3527   3968           private void CheckDisposed() /* throw */
  3528   3969           {
  3529   3970   #if THROW_ON_DISPOSED
  3530   3971               if (disposed)
  3531   3972               {
  3532   3973                   throw new ObjectDisposedException(
  3533   3974                       typeof(SQLiteChangeSetMetadataItem).Name);
  3534   3975               }
  3535   3976   #endif
  3536   3977           }
  3537   3978   
  3538   3979           ///////////////////////////////////////////////////////////////////////
  3539   3980   
         3981  +        /// <summary>
         3982  +        /// Disposes or finalizes this object instance.
         3983  +        /// </summary>
         3984  +        /// <param name="disposing">
         3985  +        /// Non-zero if this object is being disposed; otherwise, this object
         3986  +        /// is being finalized.
         3987  +        /// </param>
  3540   3988           private /* protected virtual */ void Dispose(bool disposing)
  3541   3989           {
  3542   3990               try
  3543   3991               {
  3544   3992                   if (!disposed)
  3545   3993                   {
  3546   3994                       if (disposing)
................................................................................
  3567   4015               }
  3568   4016           }
  3569   4017           #endregion
  3570   4018   
  3571   4019           ///////////////////////////////////////////////////////////////////////
  3572   4020   
  3573   4021           #region Destructor
         4022  +        /// <summary>
         4023  +        /// Finalizes this object instance.
         4024  +        /// </summary>
  3574   4025           ~SQLiteChangeSetMetadataItem()
  3575   4026           {
  3576   4027               Dispose(false);
  3577   4028           }
  3578   4029           #endregion
  3579   4030       }
  3580   4031       #endregion
  3581   4032   }