Index: /trunk/include/VBox/RemoteDesktop/VRDE.h
===================================================================
--- /trunk/include/VBox/RemoteDesktop/VRDE.h	(revision 35938)
+++ /trunk/include/VBox/RemoteDesktop/VRDE.h	(revision 35939)
@@ -38,5 +38,8 @@
 RT_C_DECLS_BEGIN
 
-/* Forward declaration of the VRDE server instance handle. */
+/* Forward declaration of the VRDE server instance handle.
+ * This is an opaque pointer for VirtualBox.
+ * The VRDE library uses it as a pointer to some internal data.
+ */
 #ifdef __cplusplus
 class VRDEServer;
@@ -647,7 +650,12 @@
      * Send a update.
      *
+     * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
+     *       If the have to access the bitmap later or from another thread, then
+     *       it must used an intermediate buffer and copy the framebuffer data to the
+     *       intermediate buffer in VRDEUpdate.
+     *
      * @param hServer   Handle of VRDE server instance.
      * @param uScreenId The screen index.
-     * @param pvUpdate  Pointer to VBoxGuest.h::VRDEORDERHDR structure with extra data.
+     * @param pvUpdate  Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
      * @param cbUpdate  Size of the update data.
      */
@@ -814,7 +822,12 @@
      * Send a update.
      *
+     * Note: the server must access the framebuffer bitmap only when VRDEUpdate is called.
+     *       If the have to access the bitmap later or from another thread, then
+     *       it must used an intermediate buffer and copy the framebuffer data to the
+     *       intermediate buffer in VRDEUpdate.
+     *
      * @param hServer   Handle of VRDE server instance.
      * @param uScreenId The screen index.
-     * @param pvUpdate  Pointer to VBoxGuest.h::VRDEORDERHDR structure with extra data.
+     * @param pvUpdate  Pointer to VRDEOrders.h::VRDEORDERHDR structure with extra data.
      * @param cbUpdate  Size of the update data.
      */
@@ -961,5 +974,5 @@
 
     /*
-     * Same as version 2.
+     * Same as version 2. See comment in VRDEENTRYPOINTS_2.
      */
 
@@ -1055,8 +1068,16 @@
 
 
-#define VRDE_QP_NETWORK_PORT      (1)
-#define VRDE_QP_NETWORK_ADDRESS   (2)
-#define VRDE_QP_NUMBER_MONITORS   (3)
-#define VRDE_QP_NETWORK_PORT_RANGE (4)
+/* Indexes for VRDECallbackProperty. 
+ * *_QP_* queries a property.
+ * *_SP_* sets a property.
+ */
+#define VRDE_QP_NETWORK_PORT      (1) /* Obsolete. Use VRDE_QP_NETWORK_PORT_RANGE instead. */
+#define VRDE_QP_NETWORK_ADDRESS   (2) /* UTF8 string. Host network interface IP address to bind to. */
+#define VRDE_QP_NUMBER_MONITORS   (3) /* 32 bit. Number of monitors in the VM. */
+#define VRDE_QP_NETWORK_PORT_RANGE (4) /* UTF8 string. List of ports. The server must bind to one of
+                                        * free ports from the list. Example: "3000,3010-3012,4000",
+                                        * which tells the server to bind to either of ports:
+                                        * 3000, 3010, 3011, 3012, 4000.
+                                        */
 #ifdef VBOX_WITH_VRDP_VIDEO_CHANNEL
 #define VRDE_QP_VIDEO_CHANNEL         (5)
@@ -1064,8 +1085,13 @@
 #define VRDE_QP_VIDEO_CHANNEL_SUNFLSH (7)
 #endif /* VBOX_WITH_VRDP_VIDEO_CHANNEL */
-#define VRDE_QP_FEATURE           (8)
+#define VRDE_QP_FEATURE           (8) /* VRDEFEATURE structure. Generic interface to query named VRDE properties. */
 
 #define VRDE_SP_BASE 0x1000
-#define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1)
+#define VRDE_SP_NETWORK_BIND_PORT (VRDE_SP_BASE + 1) /* 32 bit. The port number actually used by the server.
+                                                      * If VRDECreateServer fails, it should set the port to 0.
+                                                      * If VRDECreateServer succeeds, then the port must be set
+                                                      * in VRDEEnableConnections to the actually used value.
+                                                      * VRDEDestroy must set the port to 0xFFFFFFFF.
+                                                      */
 
 #pragma pack(1)
@@ -1165,5 +1191,6 @@
                                                      const char *pszDomain));
 
-    /* The client has been successfully connected.
+    /* The client has been successfully connected. That is logon was successful and the
+     * remote desktop protocol connection completely established.
      *
      * @param pvCallback      The callback specific pointer.
@@ -1250,5 +1277,7 @@
                                                            VRDEFRAMEBUFFERINFO *pInfo));
 
-    /* The framebuffer is locked.
+    /* Request the exclusive access to the framebuffer bitmap.
+     * Currently not used because VirtualBox makes sure that the framebuffer is available
+     * when VRDEUpdate is called.
      *
      * @param pvCallback      The callback specific pointer.
@@ -1258,5 +1287,7 @@
                                                           unsigned uScreenId));
 
-    /* The framebuffer is unlocked.
+    /* Release the exclusive access to the framebuffer bitmap.
+     * Currently not used because VirtualBox makes sure that the framebuffer is available
+     * when VRDEUpdate is called.
      *
      * @param pvCallback      The callback specific pointer.
@@ -1303,5 +1334,5 @@
 
     /*
-     * Same as in version 2.
+     * Same as in version 1 and 2. See comment in VRDECALLBACKS_1.
      */
     DECLR3CALLBACKMEMBER(int, VRDECallbackProperty,(void *pvCallback,
@@ -1419,4 +1450,13 @@
  * List of names of the VRDE properties, which are recognized by the VRDE.
  *
+ * For example VRDESupportedProperties should return gapszProperties declared as:
+ *
+ * static const char * const gapszProperties[] =
+ * {
+ *   "TCP/Ports",
+ *   "TCP/Address",
+ *   NULL
+ * };
+ *
  * @returns pointer to array of pointers to name strings (UTF8).
  */