Changeset 71335 in vbox for trunk/src/VBox/HostServices

Timestamp:

Mar 14, 2018 3:07:20 PM (7 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

121286

Message:

Guest Control/service: Renaming, documentation (no functional changes).

File:

• trunk/src/VBox/HostServices/GuestControl/service.cpp (modified) (13 diffs)

trunk/src/VBox/HostServices/GuestControl/service.cpp

@@ -605 +605 @@
 
     /**
-     * Set to inidicate that a client call (GUEST_MSG_WAIT) is pending.
+     * Set to indicate that a client call (GUEST_MSG_WAIT) is pending.
      */
     int SetPending(const ClientConnection *pConnection)
@@ -1026 +1026 @@
     int clientConnect(uint32_t u32ClientID, void *pvClient);
     int clientDisconnect(uint32_t u32ClientID, void *pvClient);
-    int clientGetCommand(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
-    int clientSetMsgFilterSet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
-    int clientSetMsgFilterUnset(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
+    int clientMsgGet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
+    int clientMsgFilterSet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
+    int clientMsgFilterUnset(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
     int clientMsgSkip(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
-    int cancelHostCmd(uint32_t u32ContextID);
-    int cancelPendingWaits(uint32_t u32ClientID, int rcPending);
     int hostCallback(uint32_t eFunction, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
     int hostProcessCommand(uint32_t eFunction, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
@@ -1115 +1113 @@
             bool fLast = RTListNodeIsLast(&mHostCmdList, &pCurCmd->Node);
 
-            int rc2 = cancelHostCmd(pCurCmd->mContextID);
+            uint32_t cParms = 0;
+            VBOXHGCMSVCPARM arParms[2];
+            arParms[cParms++].setUInt32(pCurCmd->mContextID);
+
+            int rc2 = hostCallback(GUEST_DISCONNECTED, cParms, arParms);
             if (RT_FAILURE(rc2))
             {
@@ -1141 +1143 @@
 
 /**
- * Either fills in parameters from a pending host command into our guest context or
- * defer the guest call until we have something from the host.
+ * A client asks for the next message to process.
+ *
+ * This either fills in a pending host command into the client's parameter space
+ * or defers the guest call until we have something from the host.
  *
  * @return  IPRT status code.
@@ -1150 +1154 @@
  * @param   paParms                     Array of parameters.
  */
-int Service::clientGetCommand(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
-                              uint32_t cParms, VBOXHGCMSVCPARM paParms[])
+int Service::clientMsgGet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
+                          uint32_t cParms, VBOXHGCMSVCPARM paParms[])
 {
     /*
@@ -1180 +1184 @@
 }
 
-int Service::clientSetMsgFilterSet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
-                                   uint32_t cParms, VBOXHGCMSVCPARM paParms[])
+/**
+ * A client tells this service to set a message filter.
+ * That way a client only will get new messages which matches the filter.
+ *
+ * @return VBox status code.
+ * @param  u32ClientID                  The client's ID.
+ * @param  callHandle                   The client's call handle.
+ * @param  cParms                       Number of parameters.
+ * @param  paParms                      Array of parameters.
+ */
+int Service::clientMsgFilterSet(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
+                                uint32_t cParms, VBOXHGCMSVCPARM paParms[])
 {
     RT_NOREF(callHandle);
@@ -1231 +1245 @@
 }
 
-int Service::clientSetMsgFilterUnset(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
-                                     uint32_t cParms, VBOXHGCMSVCPARM paParms[])
+/**
+ * A client tells this service to unset (clear) its message filter.
+ *
+ * @return VBox status code.
+ * @param  u32ClientID                  The client's ID.
+ * @param  callHandle                   The client's call handle.
+ * @param  cParms                       Number of parameters.
+ * @param  paParms                      Array of parameters.
+ */
+int Service::clientMsgFilterUnset(uint32_t u32ClientID, VBOXHGCMCALLHANDLE callHandle,
+                                  uint32_t cParms, VBOXHGCMSVCPARM paParms[])
 {
     RT_NOREF(callHandle, paParms);
@@ -1313 +1336 @@
 
 /**
- * Cancels a buffered host command to unblock waiting on Main side
- * via callbacks.
- *
- * @return  IPRT status code.
- * @param   u32ContextID                Context ID of host command to cancel.
- */
-int Service::cancelHostCmd(uint32_t u32ContextID)
-{
-    Assert(mpfnHostCallback);
-
-    LogFlowFunc(("Cancelling CID=%u ...\n", u32ContextID));
-
-    uint32_t cParms = 0;
-    VBOXHGCMSVCPARM arParms[2];
-    arParms[cParms++].setUInt32(u32ContextID);
-
-    return hostCallback(GUEST_DISCONNECTED, cParms, arParms);
-}
-
-/**
- * Client asks itself (in another thread) to cancel all pending waits which are blocking the client
- * from shutting down / doing something else.
- *
- * @return  IPRT status code.
- * @param   u32ClientID                 The client's ID.
- * @param   rcPending                   Result code for completing pending operation.
- */
-int Service::cancelPendingWaits(uint32_t u32ClientID, int rcPending)
-{
-    ClientStateMapIter itClientState = mClientStateMap.find(u32ClientID);
-    if (itClientState != mClientStateMap.end())
-        return itClientState->second.CancelWaiting(rcPending);
-
-    return VINF_SUCCESS;
-}
-
-/**
  * Notifies the host (using low-level HGCM callbacks) about an event
  * which was sent from the client.
@@ -1367 +1353 @@
     {
         VBOXGUESTCTRLHOSTCALLBACK data(cParms, paParms);
-        rc = mpfnHostCallback(mpvHostData, eFunction,
-                              (void *)(&data), sizeof(data));
+        rc = mpfnHostCallback(mpvHostData, eFunction, (void *)(&data), sizeof(data));
     }
     else
@@ -1480 +1465 @@
         {
             LogFlowFunc(("[Client %RU32] GUEST_MSG_GET\n", u32ClientID));
-            rc = clientGetCommand(u32ClientID, callHandle, cParms, paParms);
+            rc = clientMsgGet(u32ClientID, callHandle, cParms, paParms);
         }
         else
@@ -1492 +1477 @@
                  */
                 case GUEST_CANCEL_PENDING_WAITS:
+                {
                     LogFlowFunc(("[Client %RU32] GUEST_CANCEL_PENDING_WAITS\n", u32ClientID));
-                    rc = cancelPendingWaits(u32ClientID, VINF_SUCCESS /* Pending result */);
+                    ClientStateMapIter itClientState = mClientStateMap.find(u32ClientID);
+                    if (itClientState != mClientStateMap.end())
+                        rc = itClientState->second.CancelWaiting(VINF_SUCCESS /* Pending result */);
                     break;
+                }
 
                 /*
@@ -1502 +1491 @@
                 case GUEST_MSG_FILTER_SET:
                     LogFlowFunc(("[Client %RU32] GUEST_MSG_FILTER_SET\n", u32ClientID));
-                    rc = clientSetMsgFilterSet(u32ClientID, callHandle, cParms, paParms);
+                    rc = clientMsgFilterSet(u32ClientID, callHandle, cParms, paParms);
                     break;
 
@@ -1510 +1499 @@
                 case GUEST_MSG_FILTER_UNSET:
                     LogFlowFunc(("[Client %RU32] GUEST_MSG_FILTER_UNSET\n", u32ClientID));
-                    rc = clientSetMsgFilterUnset(u32ClientID, callHandle, cParms, paParms);
+                    rc = clientMsgFilterUnset(u32ClientID, callHandle, cParms, paParms);
                     break;