+some simple sanity checks

CcUnpinRepinnedBcb(): Do not dirty the buffer to be compatible with NT-5.1sp1.
+some comments on 'privbcb->dirty' NT-5.1sp1 compatibility analysis.

diff --git a/src/libcaptive/cc/map.c b/src/libcaptive/cc/map.c
index 0de025c..b9c8595 100644 (file)
--- a/src/libcaptive/cc/map.c
+++ b/src/libcaptive/cc/map.c
@@ -1551,6 +1551,10 @@ static void CcUnpinData_leave_func(struct private_bcb *privbcb)  /* NULL to trave
  * %NULL value is forbidden.
  *
  * Dereferences @Bcb with the possible cleanup operations if you were the last owner.
+ *
+ * This call does not set the buffer as dirty although it will flush the buffers
+ * already set as dirty. Any flushes will be postponed after return from #IRP
+ * handling by the filesystem driver.
  */
 VOID CcUnpinData(IN PVOID Bcb)
 {
@@ -1602,6 +1606,20 @@ struct private_bcb *privbcb;
 }
 
 
+/**
+ * CcRepinBcb:
+ * @Bcb: #PUBLIB_BCB to be repinned.
+ * %NULL value is forbidden.
+ *
+ * Increases usecount on @Bcb. You must call CcUnpinRepinnedBcb() for such @Bcb
+ * afterwards before returning from the #IRP handling.
+ *
+ * libcaptive does not differentiate between CcUnpinData() and CcUnpinRepinnedBcb().
+ * W32 differentiates.
+ *
+ * This call does not set the buffer as dirty - such buffer will not be flushed automatically.
+ *
+ */
 VOID CcRepinBcb(IN PVOID Bcb)
 {
 PUBLIC_BCB *PublicBcb;
@@ -1622,6 +1640,20 @@ struct private_bcb *privbcb;
 }
 
 
+/**
+ * CcUnpinRepinnedBcb:
+ * @Bcb: #PUBLIB_BCB to be unpinned from CcRepinBcb().
+ * %NULL value is forbidden.
+ * @WriteThrough: %TRUE if the buffer should be flushed before finishing this function.
+ * @IoStatus: #PIO_STATUS_BLOCK to return status of this operation.
+ * %NULL value is forbidden. libcaptive always returns %STATUS_SUCCESS here.
+ *
+ * Dereferencing of @Bcb after application of CcRepinBcb().
+ *
+ * This call does not set the buffer as dirty although it will flush the buffers
+ * already set as dirty. Any flushes will be postponed after return from #IRP
+ * handling by the filesystem driver if not requested to be synchronous by @WriteThrough.
+ */
 VOID CcUnpinRepinnedBcb(IN PVOID Bcb,IN BOOLEAN WriteThrough,IN PIO_STATUS_BLOCK IoStatus)
 {
 PUBLIC_BCB *PublicBcb;
@@ -1639,15 +1671,6 @@ struct private_bcb *privbcb;
        g_log(G_LOG_DOMAIN,G_LOG_LEVEL_DEBUG,"%s: Bcb=%p,WriteThrough=%d,IoStatus=%p; privbcb->FileObject=%p",G_STRLOC,
                        Bcb,(gint)WriteThrough,IoStatus,privbcb->FileObject);
 
-       /* FIXME: Should we really mark it as dirty by this function?
-        * Undocumented by W32.
-        */
-       privbcb_set(privbcb,PRIVBCB_ITEM_DIRTY,TRUE);
-
-       /* FIXME: Should we really flush the whole 'Bcb'?
-        * Or maybe just some writes between CcRepinBcb(Bcb) and now? Who knows?
-        * Undocumented by W32.
-        */
        if (WriteThrough)
                captive_privbcb_flush_ordered(privbcb);
 
@@ -1657,8 +1680,17 @@ struct private_bcb *privbcb;
        CcUnpinData(Bcb);
 }
 
-/*
+/**
+ * CcSetDirtyPinnedData:
+ * @Bcb: #PUBLIB_BCB to be unpinned from CcRepinBcb().
+ * %NULL value is forbidden.
+ * @Lsn: Optional LSN (Linear Sequence Number) to assign to @Bcb.
+ * %NULL pointer is permitted.
+ *
  * This call will set the buffer as dirty - such buffer will be flushed automatically.
+ *
+ * You should call it only on CcPin*() buffers - not just CcMapData() buffers
+ * although libcaptive does not differentiate it.
  */
 VOID CcSetDirtyPinnedData(IN PVOID Bcb,IN PLARGE_INTEGER Lsn OPTIONAL)
 {
@@ -1704,7 +1736,7 @@ static void CcSetFileSizes_private_bcb_hash_foreach(
                struct private_bcb *privbcb,    /* value */
                struct CcSetFileSizes_param *CcSetFileSizes_param)      /* user_data */
 {
-       g_return_if_fail(PublicBcb!=NULL);
+       g_return_if_fail(validate_Bcb(PublicBcb));
        g_return_if_fail(privbcb!=NULL);
        g_return_if_fail(CcSetFileSizes_param!=NULL);
 
@@ -2473,7 +2505,7 @@ VOID CcSetAdditionalCacheAttributes(IN PFILE_OBJECT FileObject,IN BOOLEAN Disabl
  */
 VOID CcSetBcbOwnerPointer(IN PVOID Bcb,IN PVOID Owner)
 {
-       g_return_if_fail(Bcb!=NULL);
+       g_return_if_fail(validate_Bcb(Bcb));
        g_return_if_fail(Owner!=NULL);
 
        /* FIXME:thread; NOP if no threads present */
@@ -2496,7 +2528,7 @@ VOID CcSetBcbOwnerPointer(IN PVOID Bcb,IN PVOID Owner)
  */
 VOID CcUnpinDataForThread(IN PVOID Bcb,IN ERESOURCE_THREAD ResourceThreadId)
 {
-       g_return_if_fail(Bcb!=NULL);
+       g_return_if_fail(validate_Bcb(Bcb));
        g_return_if_fail(ResourceThreadId!=0);
 
        /* FIXME:thread */