Changeset 107733 in vbox for trunk

Timestamp:

Jan 14, 2025 8:56:10 AM (4 weeks ago)

Author:

vboxsync

Message:

VBoxService/VBoxServicePropCache.cpp: Docs, renaming (to match the rest).

File:

• trunk/src/VBox/Additions/common/VBoxService/VBoxServicePropCache.cpp (modified) (10 diffs)

trunk/src/VBox/Additions/common/VBoxService/VBoxServicePropCache.cpp

@@ -42 +42 @@
 
 
-
-/** @todo Docs */
+/**
+ * Searches a property within a property cache.
+ *
+ * @returns A pointer to the found property cache entry on success, or NULL if not found.
+ * @param   pCache          The property cache.
+ * @param   pszName         Name of property to search for. Case sensitive.
+ * @param   fFlags          Search flags. Currently unused and must be 0.
+ */
 static PVBOXSERVICEVEPROPCACHEENTRY vgsvcPropCacheFindInternal(PVBOXSERVICEVEPROPCACHE pCache, const char *pszName,
                                                                uint32_t fFlags)
@@ -74 +80 @@
 
 
-/** @todo Docs */
+/**
+ * Inserts (appends) a property into a property cache.
+ *
+ * @returns A pointer to the inserted property cache entry on success, or NULL on failure.
+ * @param   pCache          The property cache.
+ * @param   pszName         Name of property to insert. Case sensitive.
+ */
 static PVBOXSERVICEVEPROPCACHEENTRY vgsvcPropCacheInsertEntryInternal(PVBOXSERVICEVEPROPCACHE pCache, const char *pszName)
 {
@@ -106 +118 @@
 
 
-/** @todo Docs */
-static int vgsvcPropCacheWritePropF(uint32_t u32ClientId, const char *pszName, uint32_t fFlags, const char *pszValueFormat, ...)
+/**
+ * Writes a new value to a property.
+ *
+ * @returns VBox status code.
+ * @param   uClientId       The HGCM handle of to the guest property service.
+ * @param   pszName         Name of property to write value for. Case sensitive.
+ * @param   fFlags          Property cache flags of type VGSVCPROPCACHE_FLAGS_XXX.
+ * @param   pszValueFormat  Format string of value to write.
+ */
+static int vgsvcPropCacheWritePropF(uint32_t uClientId, const char *pszName, uint32_t fFlags, const char *pszValueFormat, ...)
 {
     AssertPtrReturn(pszName, VERR_INVALID_POINTER);
@@ -128 +148 @@
                  * guest property using the TRANSRESET flag..
                  */
-                rc = VbglR3GuestPropWrite(u32ClientId, pszName, pszValue, "TRANSRESET");
+                rc = VbglR3GuestPropWrite(uClientId, pszName, pszValue, "TRANSRESET");
                 if (rc == VERR_PARSE_ERROR)
                 {
                     /* Host does not support the "TRANSRESET" flag, so only
                      * use the "TRANSIENT" flag -- better than nothing :-). */
-                    rc = VbglR3GuestPropWrite(u32ClientId, pszName, pszValue, "TRANSIENT");
+                    rc = VbglR3GuestPropWrite(uClientId, pszName, pszValue, "TRANSIENT");
                     /** @todo r=bird: Remember that the host doesn't support
                      * this. */
@@ -139 +159 @@
             }
             else
-                rc = VbglR3GuestPropWriteValue(u32ClientId, pszName, pszValue /* No transient flags set */);
+                rc = VbglR3GuestPropWriteValue(uClientId, pszName, pszValue /* No transient flags set */);
             RTStrFree(pszValue);
         }
@@ -147 +167 @@
     }
     else
-        rc = VbglR3GuestPropWriteValue(u32ClientId, pszName, NULL);
+        rc = VbglR3GuestPropWriteValue(uClientId, pszName, NULL);
     return rc;
 }
@@ -155 +175 @@
  * Creates a property cache.
  *
- * @returns IPRT status code.
+ * @returns VBox status code.
  * @param   pCache          Pointer to the cache.
  * @param   uClientId       The HGCM handle of to the guest property service.
@@ -176 +196 @@
  *
  * @returns VBox status code.
- *
  * @param   pCache          The property cache.
  * @param   pszName         The property name.
@@ -329 +348 @@
  *
  * @returns VBox status code.
- *
  * @param   pCache          The property cache.
  * @param   pszValue        The value to set.  A NULL will delete the value.
@@ -384 +402 @@
  * Flushes the cache by writing every item regardless of its state.
  *
+ * @returns VBox status code.
  * @param   pCache          The property cache.
  */