VirtualBox

Changeset 81559 in vbox


Ignore:
Timestamp:
Oct 28, 2019 10:09:35 AM (5 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
134298
Message:

Shared Clipboard: Got rid of the protocol version in VBOX_SHCL_GUEST_FN_CONNECT and internals; instead use the get / query features bit field.

Location:
trunk
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/HostServices/VBoxClipboardSvc.h

    r81451 r81559  
    3232 * Protocol changelog:
    3333 *
    34  *     Protocol v0 (VBox < 6.1, deprecated):
     34 *     VBox < 6.1, deprecated:
    3535 *         | First, initial implementation since feature was developed.
    3636 *           Has no protocol handshake / versioning support, the client's
    … …  
    3939 *           not have the ability to control / handle parallel transfers.
    4040 *
    41  *     Protocol v1 (VBox >= 6.1):
    42  *         + Adds protocol versioning and context IDs for parallel,
     41 *     VBox >= 6.1:
     42 *         + Adds host/guest feature flags and context IDs for parallel,
    4343 *           asynchronous transfers.
    44  *         | Keeps backwards-compatbility with protocol v0 clients by translating
    45  *           messages to protocol v0, to not break compatibility with older
    46  *           Guest Additions (VBox < 6.1).
     44 *         | Keeps backwards-compatbility with by translating messages to
     45 *           the older protocol (< 6.1), to not break compatibility with older
     46 *           Guest Additions.
    4747 */
    4848
    … …  
    6565 * We're using it as a version field with the high bit set.
    6666 */
    67 /** Older saved states (VBox < 6.1). Includes protocol v0 state. */
     67/** Older saved states (VBox < 6.1). Includes legacy protocol state. */
    6868#define VBOX_SHCL_SSM_VER_0          UINT32_C(0x80000002)
    69 /** Protocol v1 is being used. */
     69/** New saved state (VBox >= 6.1). */
    7070#define VBOX_SHCL_SSM_VER_1          UINT32_C(0x80000003)
    7171
    … …  
    9898#define VBOX_SHCL_HOST_FN_SET_MODE           1
    9999/** Sets the current Shared Clipboard (file) transfers mode.
    100  *  Operates on the VBOX_SHCL_TRANSFERS_ defines. */
     100 *  Operates on the VBOX_SHCL_TRANSFERS_ defines.
     101 *
     102 * @since   6.1
     103 */
    101104#define VBOX_SHCL_HOST_FN_SET_TRANSFER_MODE  2
    102105/** Run headless on the host, i.e. do not touch the host clipboard. */
    103106#define VBOX_SHCL_HOST_FN_SET_HEADLESS       3
    104 /** Reports cancellation of the current operation to the guest. */
     107/** Reports cancellation of the current operation to the guest.
     108 * @since   6.1
     109 */
    105110#define VBOX_SHCL_HOST_FN_CANCEL             4
    106 /** Reports an error to the guest. */
     111/** Reports an error to the guest.
     112 * @since   6.1
     113 */
    107114#define VBOX_SHCL_HOST_FN_ERROR              5
    108 /** Reports that a new clipboard area has been registered. */
     115/** Reports that a new clipboard area has been registered.
     116 * @since   6.1
     117 */
    109118#define VBOX_SHCL_HOST_FN_AREA_REGISTER      6
    110 /** Reports that a clipboard area has been unregistered. */
     119/** Reports that a clipboard area has been unregistered.
     120 * @since   6.1
     121 */
    111122#define VBOX_SHCL_HOST_FN_AREA_UNREGISTER    7
    112 /** Reports that a client (host / guest) has attached to a clipboard area. */
     123/** Reports that a client (host / guest) has attached to a clipboard area.
     124 * @since   6.1
     125 */
    113126#define VBOX_SHCL_HOST_FN_AREA_ATTACH        8
    114 /** Reports that a client (host / guest) has detached from a clipboard area. */
     127/** Reports that a client (host / guest) has detached from a clipboard area.
     128 * @since   6.1
     129 */
    115130#define VBOX_SHCL_HOST_FN_AREA_DETACH        9
    116131
    … …  
    126141#define VBOX_SHCL_HOST_MSG_FORMATS_REPORT                    3
    127142
    128 /** Sends a transfer status to the guest side. */
     143/** Sends a transfer status to the guest side.
     144 *
     145 * @retval  VINF_SUCCESS on success.
     146 * @retval  VERR_INVALID_CLIENT_ID
     147 * @retval  VERR_WRONG_PARAMETER_COUNT
     148 * @retval  VERR_WRONG_PARAMETER_TYPE
     149 * @since   6.1
     150 */
    129151#define VBOX_SHCL_HOST_MSG_TRANSFER_STATUS                   50
    130 /** Reads the root list header from the guest. */
     152/** Reads the root list header from the guest.
     153 *
     154 * @retval  VINF_SUCCESS on success.
     155 * @retval  VERR_INVALID_CLIENT_ID
     156 * @retval  VERR_WRONG_PARAMETER_COUNT
     157 * @retval  VERR_WRONG_PARAMETER_TYPE
     158 * @since   6.1
     159 */
    131160#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_READ       51
    132 /** Writes the root list header to the guest. */
     161/** Writes the root list header to the guest.
     162 *
     163 * @retval  VINF_SUCCESS on success.
     164 * @retval  VERR_INVALID_CLIENT_ID
     165 * @retval  VERR_WRONG_PARAMETER_COUNT
     166 * @retval  VERR_WRONG_PARAMETER_TYPE
     167 * @since   6.1
     168 */
    133169#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_HDR_WRITE      52
    134 /** Reads a root list entry from the guest. */
     170/** Reads a root list entry from the guest.
     171 *
     172 * @retval  VINF_SUCCESS on success.
     173 * @retval  VERR_INVALID_CLIENT_ID
     174 * @retval  VERR_WRONG_PARAMETER_COUNT
     175 * @retval  VERR_WRONG_PARAMETER_TYPE
     176 * @since   6.1
     177 */
    135178#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_READ     53
    136 /** Writes a root list entry to the guest. */
     179/** Writes a root list entry to the guest.
     180 *
     181 * @retval  VINF_SUCCESS on success.
     182 * @retval  VERR_INVALID_CLIENT_ID
     183 * @retval  VERR_WRONG_PARAMETER_COUNT
     184 * @retval  VERR_WRONG_PARAMETER_TYPE
     185 * @since   6.1
     186 */
    137187#define VBOX_SHCL_HOST_MSG_TRANSFER_ROOT_LIST_ENTRY_WRITE    54
    138 /** Open a transfer list on the guest side. */
     188/** Open a transfer list on the guest side.
     189 *
     190 * @retval  VINF_SUCCESS on success.
     191 * @retval  VERR_INVALID_CLIENT_ID
     192 * @retval  VERR_WRONG_PARAMETER_COUNT
     193 * @retval  VERR_WRONG_PARAMETER_TYPE
     194 * @since   6.1
     195 */
    139196#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_OPEN                55
    140 /** Closes a formerly opened transfer list on the guest side. */
     197/** Closes a formerly opened transfer list on the guest side.
     198 *
     199 * @retval  VINF_SUCCESS on success.
     200 * @retval  VERR_INVALID_CLIENT_ID
     201 * @retval  VERR_WRONG_PARAMETER_COUNT
     202 * @retval  VERR_WRONG_PARAMETER_TYPE
     203 * @since   6.1
     204 */
    141205#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_CLOSE               56
    142 /** Reads a list header from the guest. */
     206/** Reads a list header from the guest.
     207 *
     208 * @retval  VINF_SUCCESS on success.
     209 * @retval  VERR_INVALID_CLIENT_ID
     210 * @retval  VERR_WRONG_PARAMETER_COUNT
     211 * @retval  VERR_WRONG_PARAMETER_TYPE
     212 * @since   6.1
     213 */
    143214#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_READ            57
    144 /** Writes a list header to the guest. */
     215/** Writes a list header to the guest.
     216 *
     217 * @retval  VINF_SUCCESS on success.
     218 * @retval  VERR_INVALID_CLIENT_ID
     219 * @retval  VERR_WRONG_PARAMETER_COUNT
     220 * @retval  VERR_WRONG_PARAMETER_TYPE
     221 * @since   6.1
     222 */
    145223#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_HDR_WRITE           58
    146 /** Reads a list entry from the guest. */
     224/** Reads a list entry from the guest.
     225 *
     226 * @retval  VINF_SUCCESS on success.
     227 * @retval  VERR_INVALID_CLIENT_ID
     228 * @retval  VERR_WRONG_PARAMETER_COUNT
     229 * @retval  VERR_WRONG_PARAMETER_TYPE
     230 * @since   6.1
     231 */
    147232#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_READ          59
    148 /** Writes a list entry to the guest. */
     233/** Writes a list entry to the guest.
     234 *
     235 * @retval  VINF_SUCCESS on success.
     236 * @retval  VERR_INVALID_CLIENT_ID
     237 * @retval  VERR_WRONG_PARAMETER_COUNT
     238 * @retval  VERR_WRONG_PARAMETER_TYPE
     239 * @since   6.1
     240 */
    149241#define VBOX_SHCL_HOST_MSG_TRANSFER_LIST_ENTRY_WRITE         60
    150 /** Open a transfer object on the guest side. */
     242/** Open a transfer object on the guest side.
     243 *
     244 * @retval  VINF_SUCCESS on success.
     245 * @retval  VERR_INVALID_CLIENT_ID
     246 * @retval  VERR_WRONG_PARAMETER_COUNT
     247 * @retval  VERR_WRONG_PARAMETER_TYPE
     248 * @since   6.1
     249 */
    151250#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_OPEN                 61
    152 /** Closes a formerly opened transfer object on the guest side. */
     251/** Closes a formerly opened transfer object on the guest side.
     252 *
     253 * @retval  VINF_SUCCESS on success.
     254 * @retval  VERR_INVALID_CLIENT_ID
     255 * @retval  VERR_WRONG_PARAMETER_COUNT
     256 * @retval  VERR_WRONG_PARAMETER_TYPE
     257 * @since   6.1
     258 */
    153259#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_CLOSE                62
    154 /** Reads from an object on the guest side. */
     260/** Reads from an object on the guest side.
     261 *
     262 * @retval  VINF_SUCCESS on success.
     263 * @retval  VERR_INVALID_CLIENT_ID
     264 * @retval  VERR_WRONG_PARAMETER_COUNT
     265 * @retval  VERR_WRONG_PARAMETER_TYPE
     266 * @since   6.1
     267 */
    155268#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_READ                 63
    156 /** Writes to an object on the guest side. */
     269/** Writes to an object on the guest side.
     270 *
     271 * @retval  VINF_SUCCESS on success.
     272 * @retval  VERR_INVALID_CLIENT_ID
     273 * @retval  VERR_WRONG_PARAMETER_COUNT
     274 * @retval  VERR_WRONG_PARAMETER_TYPE
     275 * @since   6.1
     276 */
    157277#define VBOX_SHCL_HOST_MSG_TRANSFER_OBJ_WRITE                64
    158 /** Indicates that the host has canceled a transfer. */
     278/** Indicates that the host has canceled a transfer.
     279 *
     280 * @retval  VINF_SUCCESS on success.
     281 * @retval  VERR_INVALID_CLIENT_ID
     282 * @retval  VERR_WRONG_PARAMETER_COUNT
     283 * @retval  VERR_WRONG_PARAMETER_TYPE
     284 * @since   6.1
     285 */
    159286#define VBOX_SHCL_HOST_MSG_TRANSFER_CANCEL                   65
    160 /** Indicates that the an unrecoverable error on the host occurred . */
     287/** Indicates that the an unrecoverable error on the host occurred.
     288 *
     289 * @retval  VINF_SUCCESS on success.
     290 * @retval  VERR_INVALID_CLIENT_ID
     291 * @retval  VERR_WRONG_PARAMETER_COUNT
     292 * @retval  VERR_WRONG_PARAMETER_TYPE
     293 * @since   6.1
     294 */
    161295#define VBOX_SHCL_HOST_MSG_TRANSFER_ERROR                    66
    162296
    … …  
    165299 */
    166300/** Calls the host and waits (blocking) for an host event VBOX_SHCL_HOST_MSG_*.
    167  *  Note: This is the old message which still is being used for the non-URI Shared Clipboard transfers,
    168  *        to not break compatibility with older Guest Additions / VBox versions. */
     301 *  Deprecated, do not use anymore. Kept to not break compatibility with older
     302 *  Guest Additions / VBox versions. */
    169303#define VBOX_SHCL_GUEST_FN_GET_HOST_MSG_OLD       1
    170304/** Sends a list of available formats to the host.
    … …  
    180314 *  with the legacy protocol (v0).
    181315 *
    182  *  New since protocol v1. */
     316 * @retval  VINF_SUCCESS on success.
     317 * @retval  VERR_INVALID_CLIENT_ID
     318 * @retval  VERR_WRONG_PARAMETER_COUNT
     319 * @retval  VERR_WRONG_PARAMETER_TYPE
     320 * @since   6.1
     321 */
    183322#define VBOX_SHCL_GUEST_FN_CONNECT                5
    184323/** Report guest side feature flags and retrieve the host ones.
    … …  
    192331 *
    193332 * @retval  VINF_SUCCESS on success.
    194  * @retval  VERR_ACCESS_DENIED it not master.
    195333 * @retval  VERR_INVALID_CLIENT_ID
    196334 * @retval  VERR_WRONG_PARAMETER_COUNT
    … …  
    214352#define VBOX_SHCL_GUEST_FN_QUERY_FEATURES         7
    215353/** Peeks at the next message, returning immediately.
    216  *  New since protocol v1. */
     354 *
     355 * @retval  VINF_SUCCESS on success.
     356 * @retval  VERR_INVALID_CLIENT_ID
     357 * @retval  VERR_WRONG_PARAMETER_COUNT
     358 * @retval  VERR_WRONG_PARAMETER_TYPE
     359 * @since   6.1
     360 */
    217361#define VBOX_SHCL_GUEST_FN_MSG_PEEK_NOWAIT        8
    218362/** Peeks at the next message, waiting for one to arrive.
    219  *  New since protocol v1. */
     363 *
     364 * @retval  VINF_SUCCESS on success.
     365 * @retval  VERR_INVALID_CLIENT_ID
     366 * @retval  VERR_WRONG_PARAMETER_COUNT
     367 * @retval  VERR_WRONG_PARAMETER_TYPE
     368 * @since   6.1
     369 */
    220370#define VBOX_SHCL_GUEST_FN_MSG_PEEK_WAIT          9
    221371/** Gets the next message, returning immediately.
    222  *  New since protocol v1. */
     372 *
     373 * @retval  VINF_SUCCESS on success.
     374 * @retval  VERR_INVALID_CLIENT_ID
     375 * @retval  VERR_WRONG_PARAMETER_COUNT
     376 * @retval  VERR_WRONG_PARAMETER_TYPE
     377 * @since   6.1
     378 */
    223379#define VBOX_SHCL_GUEST_FN_MSG_GET                10
    224380/** Replies to a function from the host.
    225  *  New since protocol v1. */
     381 *
     382 * @retval  VINF_SUCCESS on success.
     383 * @retval  VERR_INVALID_CLIENT_ID
     384 * @retval  VERR_WRONG_PARAMETER_COUNT
     385 * @retval  VERR_WRONG_PARAMETER_TYPE
     386 * @since   6.1
     387 */
    226388#define VBOX_SHCL_GUEST_FN_REPLY                  11
    227 /** Reports the available root entries of a transfer.
    228  *  New since protocol v1. */
     389/** Gets the root list header from the host.
     390 *
     391 * @retval  VINF_SUCCESS on success.
     392 * @retval  VERR_INVALID_CLIENT_ID
     393 * @retval  VERR_WRONG_PARAMETER_COUNT
     394 * @retval  VERR_WRONG_PARAMETER_TYPE
     395 * @since   6.1
     396 */
    229397#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_READ     12
    230 /** Reports the available root entries of a transfer.
    231  *  New since protocol v1. */
     398/** Sends the root list header to the host.
     399 *
     400 * @retval  VINF_SUCCESS on success.
     401 * @retval  VERR_INVALID_CLIENT_ID
     402 * @retval  VERR_WRONG_PARAMETER_COUNT
     403 * @retval  VERR_WRONG_PARAMETER_TYPE
     404 * @since   6.1
     405 */
    232406#define VBOX_SHCL_GUEST_FN_ROOT_LIST_HDR_WRITE    13
    233 /** Reports the available root entries of a transfer.
    234  *  New since protocol v1. */
     407/** Gets a root list root entry from the host.
     408 *
     409 * @retval  VINF_SUCCESS on success.
     410 * @retval  VERR_INVALID_CLIENT_ID
     411 * @retval  VERR_WRONG_PARAMETER_COUNT
     412 * @retval  VERR_WRONG_PARAMETER_TYPE
     413 * @since   6.1
     414 */
    235415#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_READ   14
    236 /** Reports the available root entries of a transfer.
    237  *  New since protocol v1. */
     416/** Sends a root list root entry to the host.
     417 *
     418 * @retval  VINF_SUCCESS on success.
     419 * @retval  VERR_INVALID_CLIENT_ID
     420 * @retval  VERR_WRONG_PARAMETER_COUNT
     421 * @retval  VERR_WRONG_PARAMETER_TYPE
     422 * @since   6.1
     423 */
    238424#define VBOX_SHCL_GUEST_FN_ROOT_LIST_ENTRY_WRITE  15
    239425/** Opens / gets a list handle from the host.
    240  *  New since protocol v1. */
     426 *
     427 * @retval  VINF_SUCCESS on success.
     428 * @retval  VERR_INVALID_CLIENT_ID
     429 * @retval  VERR_WRONG_PARAMETER_COUNT
     430 * @retval  VERR_WRONG_PARAMETER_TYPE
     431 * @since   6.1
     432 */
    241433#define VBOX_SHCL_GUEST_FN_LIST_OPEN              16
    242434/** Closes a list handle from the host.
    243  *  New since protocol v1. */
     435 *
     436 * @retval  VINF_SUCCESS on success.
     437 * @retval  VERR_INVALID_CLIENT_ID
     438 * @retval  VERR_WRONG_PARAMETER_COUNT
     439 * @retval  VERR_WRONG_PARAMETER_TYPE
     440 * @since   6.1
     441 */
    244442#define VBOX_SHCL_GUEST_FN_LIST_CLOSE             17
    245443/** Reads a list header from the host.
    246  *  New since protocol v1. */
     444 *
     445 * @retval  VINF_SUCCESS on success.
     446 * @retval  VERR_INVALID_CLIENT_ID
     447 * @retval  VERR_WRONG_PARAMETER_COUNT
     448 * @retval  VERR_WRONG_PARAMETER_TYPE
     449 * @since   6.1
     450 */
    247451#define VBOX_SHCL_GUEST_FN_LIST_HDR_READ          18
    248452/** Writes a list header to the host.
    249  *  New since protocol v1. */
     453 *
     454 * @retval  VINF_SUCCESS on success.
     455 * @retval  VERR_INVALID_CLIENT_ID
     456 * @retval  VERR_WRONG_PARAMETER_COUNT
     457 * @retval  VERR_WRONG_PARAMETER_TYPE
     458 * @since   6.1
     459 */
    250460#define VBOX_SHCL_GUEST_FN_LIST_HDR_WRITE         19
    251 /** New since protocol v1. */
     461/** Reads a list entry from the host.
     462 *
     463 * @retval  VINF_SUCCESS on success.
     464 * @retval  VERR_INVALID_CLIENT_ID
     465 * @retval  VERR_WRONG_PARAMETER_COUNT
     466 * @retval  VERR_WRONG_PARAMETER_TYPE
     467 * @since   6.1
     468 */
    252469#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_READ        20
    253 /** New since protocol v1. */
     470/** Sends a list entry to the host.
     471 *
     472 * @retval  VINF_SUCCESS on success.
     473 * @retval  VERR_INVALID_CLIENT_ID
     474 * @retval  VERR_WRONG_PARAMETER_COUNT
     475 * @retval  VERR_WRONG_PARAMETER_TYPE
     476 * @since   6.1
     477 */
    254478#define VBOX_SHCL_GUEST_FN_LIST_ENTRY_WRITE       21
    255 /** New since protocol v1. */
     479/** Opens an object on the host.
     480 *
     481 * @retval  VINF_SUCCESS on success.
     482 * @retval  VERR_INVALID_CLIENT_ID
     483 * @retval  VERR_WRONG_PARAMETER_COUNT
     484 * @retval  VERR_WRONG_PARAMETER_TYPE
     485 * @since   6.1
     486 */
    256487#define VBOX_SHCL_GUEST_FN_OBJ_OPEN               22
    257 /** New since protocol v1. */
     488/** Closes an object on the host.
     489 *
     490 * @retval  VINF_SUCCESS on success.
     491 * @retval  VERR_INVALID_CLIENT_ID
     492 * @retval  VERR_WRONG_PARAMETER_COUNT
     493 * @retval  VERR_WRONG_PARAMETER_TYPE
     494 * @since   6.1
     495 */
    258496#define VBOX_SHCL_GUEST_FN_OBJ_CLOSE              23
    259 /** New since protocol v1. */
     497/** Reads from an object on the host.
     498 *
     499 * @retval  VINF_SUCCESS on success.
     500 * @retval  VERR_INVALID_CLIENT_ID
     501 * @retval  VERR_WRONG_PARAMETER_COUNT
     502 * @retval  VERR_WRONG_PARAMETER_TYPE
     503 * @since   6.1
     504 */
    260505#define VBOX_SHCL_GUEST_FN_OBJ_READ               24
    261 /** New since protocol v1. */
     506/** Writes to an object on the host.
     507 *
     508 * @retval  VINF_SUCCESS on success.
     509 * @retval  VERR_INVALID_CLIENT_ID
     510 * @retval  VERR_WRONG_PARAMETER_COUNT
     511 * @retval  VERR_WRONG_PARAMETER_TYPE
     512 * @since   6.1
     513 */
    262514#define VBOX_SHCL_GUEST_FN_OBJ_WRITE              25
    263515/** Reports cancellation of the current operation to the host.
    264  *  New since protocol v1. */
     516 *
     517 * @retval  VINF_SUCCESS on success.
     518 * @retval  VERR_INVALID_CLIENT_ID
     519 * @retval  VERR_WRONG_PARAMETER_COUNT
     520 * @retval  VERR_WRONG_PARAMETER_TYPE
     521 * @since   6.1
     522 */
    265523#define VBOX_SHCL_GUEST_FN_CANCEL                 26
    266524/** Reports an error to the host.
    267  *  New since protocol v1. */
     525 *
     526 * @retval  VINF_SUCCESS on success.
     527 * @retval  VERR_INVALID_CLIENT_ID
     528 * @retval  VERR_WRONG_PARAMETER_COUNT
     529 * @retval  VERR_WRONG_PARAMETER_TYPE
     530 * @since   6.1
     531 */
    268532#define VBOX_SHCL_GUEST_FN_ERROR                  27
    269533
    … …  
    276540/** No flags set. */
    277541#define VBOX_SHCL_GF_NONE                         0
     542/** Guest can handle context IDs (uint64_t, in paParam[0]). */
     543#define VBOX_SHCL_GF_0_CONTEXT_ID                 RT_BIT_64(0)
    278544/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
    279545 * correctly (old hosts might not). */
    … …  
    313579 * Message for doing the protocol negotiation between the host
    314580 * and the guest. Not available on older (VBox <= 6.0) hosts.
     581 *
     582 * This message acts as a beacon between the old protocol (VBox <= 6.0) and
     583 * the new protocol (>= VBox 6.1). Newer features are getting introduced soley via
     584 * the guest / host feature flags then.
    315585 */
    316586typedef struct _VBoxShClConnect
    … …  
    318588    VBGLIOCHGCMCALL hdr;
    319589
    320     /** uint32_t, out: Protocol version. */
    321     HGCMFunctionParameter uProtocolVer;
    322     /** uint32_t, out: Protocol flags, unused at the moment. */
    323     HGCMFunctionParameter uProtocolFlags;
    324590    /** uint32_t, out: Maximum chunk size for data transfers. */
    325591    HGCMFunctionParameter cbChunkSize;
    … …  
    330596} VBoxShClConnect;
    331597
    332 #define VBOX_SHCL_CPARMS_CONNECT 5
     598#define VBOX_SHCL_CPARMS_CONNECT 3
    333599
    334600/**
    … …  
    349615        struct
    350616        {
    351             /** uint64_t, in: Context ID. */
     617            /** uint64_t, out: Context ID. */
    352618            HGCMFunctionParameter uContext;
    353             /** uint32_t, out:  VBOX_SHCL_FMT_*. */
     619            /** uint32_t, out: VBOX_SHCL_FMT_*. */
    354620            HGCMFunctionParameter uFormats;
    355             /** uint32_t, in: Format flags. */
     621            /** uint32_t, out: Format flags. */
    356622            HGCMFunctionParameter fFlags;
    357623        } v1;

  • trunk/include/VBox/VBoxGuestLib.h

    r81352 r81559  
    605605    /** IN/OUT: Context ID to retrieve or to use. */
    606606    uint64_t                  uContextID;
    607     /** IN: Protocol version to use. */
    608     uint32_t                  uProtocolVer;
    609     /** IN: Protocol flags. Currently unused. */
    610     uint32_t                  uProtocolFlags;
    611607    /** IN: Maximum chunk size (in bytes). */
    612608    uint32_t                  cbChunkSize;
     609    /** Flag indicating whether to use the legacy protocol (<= VBox 6.1) or not.
     610     *  This is determined in VbglR3ClipboardConnectEx(). */
     611    bool                      fUseLegacyProtocol;
     612    /** IN: Host feature flags (of type VBOX_SHCL_HF_XXX). */
     613    uint64_t                  fHostFeatures;
    613614    /** OUT: Number of parameters retrieved. */
    614615    uint32_t                  uNumParms;

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxClipboard.cpp

    r81369 r81559  
    960960    const PSHCLWINCTX pWinCtx = &pCtx->Win;
    961961
    962     LogRel2(("Shared Clipboard: Worker loop running, using protocol v%RU32\n", pCtx->CmdCtx.uProtocolVer));
     962    LogRel2(("Shared Clipboard: Worker loop running\n"));
    963963
    964964#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
    … …  
    975975    int rc;
    976976
    977     LogFlowFunc(("uProtocolVer=%RU32\n", pCtx->CmdCtx.uProtocolVer));
    978 
    979977    uint32_t uMsg;
    980978    uint32_t uFormats;
    … …  
    985983        PVBGLR3CLIPBOARDEVENT pEvent = NULL;
    986984
    987         LogFlowFunc(("Waiting for host message (protocol v%RU32) ...\n", pCtx->CmdCtx.uProtocolVer));
    988 
    989         if (pCtx->CmdCtx.uProtocolVer == 0) /* Legacy protocol */
     985        LogFlowFunc(("Waiting for host message (fHostFeatures=%#RX64) ...\n", pCtx->CmdCtx.fHostFeatures));
     986
     987        if (pCtx->CmdCtx.fUseLegacyProtocol)
    990988        {
    991989            rc = VbglR3ClipboardGetHostMsgOld(pCtx->CmdCtx.uClientID, &uMsg, &uFormats);
    … …  
    10301028            }
    10311029        }
    1032         else /* Protocol >= v1. */
     1030        else /* Host service has peeking for messages support. */
    10331031        {
    10341032            pEvent = (PVBGLR3CLIPBOARDEVENT)RTMemAllocZ(sizeof(VBGLR3CLIPBOARDEVENT));

  • trunk/src/VBox/Additions/common/VBoxGuest/lib/VBoxGuestR3LibClipboard.cpp

    r81460 r81559  
    9494                           VBOX_SHCL_GUEST_FN_CONNECT, VBOX_SHCL_CPARMS_CONNECT);
    9595
    96         VbglHGCMParmUInt32Set(&Msg.uProtocolVer, 0);
    97         VbglHGCMParmUInt32Set(&Msg.uProtocolFlags, 0);
    9896        VbglHGCMParmUInt32Set(&Msg.cbChunkSize, 0);
    9997        VbglHGCMParmUInt32Set(&Msg.enmCompression, 0);
    … …  
    103101        if (RT_SUCCESS(rc))
    104102        {
    105             rc = VbglHGCMParmUInt32Get(&Msg.uProtocolVer, &pCtx->uProtocolVer);
    106             if (RT_SUCCESS(rc))
    107                 rc = VbglHGCMParmUInt32Get(&Msg.uProtocolFlags, &pCtx->uProtocolFlags);
    108             if (RT_SUCCESS(rc))
    109                 rc = VbglHGCMParmUInt32Get(&Msg.cbChunkSize, &pCtx->cbChunkSize);
     103            rc = VbglHGCMParmUInt32Get(&Msg.cbChunkSize, &pCtx->cbChunkSize);
    110104
    111105            /** @todo Add / handle checksum + compression type. */
    … …  
    116110                 * Report features to the host.
    117111                 */
    118                 uint64_t fHostFeatures0Ignored;
    119                 rc = VbglR3ClipboardReportFeatures(pCtx->uClientID, VBOX_SHCL_GF_NONE /* None yet */,
    120                                                    &fHostFeatures0Ignored);
     112                const uint64_t fGuestFeatures = VBOX_SHCL_GF_0_CONTEXT_ID;
     113
     114                rc = VbglR3ClipboardReportFeatures(pCtx->uClientID, fGuestFeatures,
     115                                                   &pCtx->fHostFeatures);
    121116                if (RT_SUCCESS(rc))
    122                     LogRel2(("Shared Clipboard: Host features: %#RX64\n", fHostFeatures0Ignored));
     117                    LogRel2(("Shared Clipboard: Host features: %#RX64\n", pCtx->fHostFeatures));
    123118                else
    124119                    LogRel(("Shared Clipboard: Warning! Feature reporing failed: %Rrc\n", rc));
     120
     121                pCtx->fUseLegacyProtocol = false;
    125122            }
    126123        }
    … …  
    128125        {
    129126            /* If the above call fails, make sure to use some sane defaults for
    130              * the old (legacy) protocol. */
    131             pCtx->uProtocolVer   = 0;
    132             pCtx->uProtocolFlags = 0;
    133             pCtx->cbChunkSize    = _64K;
     127             * the old (legacy, VBox <= 6.1) protocol. */
     128            pCtx->fUseLegacyProtocol = true;
     129            pCtx->cbChunkSize        = _64K; /* Use 64KB as chunk size by default. */
    134130
    135131            rc = VINF_SUCCESS; /* Failing above is not fatal. */
    136132        }
    137133
    138         LogFlowFunc(("uProtocolVer=%RU32, cbChunkSize=%RU32\n", pCtx->uProtocolVer, pCtx->cbChunkSize));
    139 
    140         LogRel2(("Shared Clipboard: Client %RU32 connected, using protocol v%RU32 (cbChunkSize=%RU32)\n",
    141                  pCtx->uClientID, pCtx->uProtocolVer, pCtx->cbChunkSize));
    142 
     134        LogFlowFunc(("fHostFeatures=%#RX64, cbChunkSize=%RU32\n", pCtx->fHostFeatures, pCtx->cbChunkSize));
     135
     136        LogRel2(("Shared Clipboard: Client %RU32 connected (cbChunkSize=%RU32, fUseLegacyProtocol=%RTbool)\n",
     137                 pCtx->uClientID, pCtx->cbChunkSize, pCtx->fUseLegacyProtocol));
    143138    }
    144139
    … …  
    194189    RT_ZERO(Msg);
    195190
    196     if (pCtx->uProtocolVer >= 1)
    197     {
    198         VBGL_HGCM_HDR_INIT(&Msg.hdr, pCtx->uClientID,
    199                            VBOX_SHCL_GUEST_FN_MSG_GET, 3);
    200 
    201         Msg.u.v1.uContext.SetUInt64(VBOX_SHCL_HOST_MSG_FORMATS_REPORT);
    202         Msg.u.v1.uFormats.SetUInt32(0);
    203         Msg.u.v1.fFlags.SetUInt32(0);
    204     }
     191    VBGL_HGCM_HDR_INIT(&Msg.hdr, pCtx->uClientID, VBOX_SHCL_GUEST_FN_MSG_GET, 3);
     192
     193    Msg.u.v1.uContext.SetUInt64(VBOX_SHCL_HOST_MSG_FORMATS_REPORT);
     194    Msg.u.v1.uFormats.SetUInt32(0);
     195    Msg.u.v1.fFlags.SetUInt32(0);
    205196
    206197    int rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
    … …  
    256247
    257248/**
    258  * Get a host message, legacy version (protocol v0). Do not use anymore.
     249 * Get a host message, legacy version (which does not have VBOX_SHCL_GUEST_FN_MSG_GET). Do not use anymore.
    259250 *
    260251 * Note: This is the old message which still is being used for the non-URI Shared Clipboard transfers,
    … …  
    22182209
    22192210#ifdef LOG_ENABLED
    2220     LogFunc(("Handling idMsg=%RU32 (%s), protocol v%RU32\n", idMsg, ShClHostMsgToStr(idMsg), pCtx->uProtocolVer));
     2211    LogFunc(("Handling idMsg=%RU32 (%s)\n", idMsg, ShClHostMsgToStr(idMsg)));
    22212212#endif
    22222213    switch (idMsg)
    … …  
    23082299    LogFlowFunc(("uFormats=0x%x\n", pFormats->uFormats));
    23092300
    2310     if (pCtx->uProtocolVer == 0)
     2301    if (pCtx->fUseLegacyProtocol)
    23112302    {
    23122303        VBGL_HGCM_HDR_INIT(&Msg.hdr, pCtx->uClientID, VBOX_SHCL_GUEST_FN_FORMATS_REPORT, 1);
    … …  
    24022393    int rc;
    24032394
    2404     if (pCtx->uProtocolVer == 0)
     2395    if (pCtx->fUseLegacyProtocol)
    24052396    {
    24062397        rc = VbglR3ClipboardWriteData(pCtx->uClientID, pData->uFormat, pData->pvData, pData->cbData);

  • trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc-internal.h

    r81451 r81559  
    8888    /** The client's session ID. */
    8989    SHCLSESSIONID           uSessionID;
    90     /** Optional protocol version the client uses. Set to 0 by default. */
    91     uint32_t                uProtocolVer;
    9290    /** Guest feature flags, VBOX_SHCL_GF_0_XXX. */
    9391    uint64_t                fGuestFeatures0;
    … …  
    9694    /** Maximum chunk size to use for data transfers. Set to _64K by default. */
    9795    uint32_t                cbChunkSize;
     96    /** Where the transfer sources its data from. */
    9897    SHCLSOURCE              enmSource;
    9998    /** The client's transfers state. */

  • trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc.cpp

    r81460 r81559  
    422422 * Sets the VBOX_SHCL_GUEST_FN_GET_HOST_MSG_OLD return parameters.
    423423 *
    424  * This function does the necessary translation between the legacy protocol (v0) and the new protocols (>= v1),
     424 * This function does the necessary translation between the legacy protocol (<= VBox 6.0) and the new protocols (>= VBox 6.1),
    425425 * as messages are always stored as >= v1 messages in the message queue.
    426426 *
    … …  
    11131113
    11141114    SHCLEVENTID uEvent;
    1115     if (pClient->State.uProtocolVer == 0)
    1116     {
    1117         /* Protocol v0 did not have any context ID handling, so we ASSUME that the last event registered
     1115    if (!(pClient->State.fGuestFeatures0 & VBOX_SHCL_GF_0_CONTEXT_ID)) /* Legacy */
     1116    {
     1117        /* Older Guest Additions (<= VBox 6.0) did not have any context ID handling, so we ASSUME that the last event registered
    11181118         * is the one we want to handle (as this all was a synchronous protocol anyway). */
    11191119        uEvent = ShClEventGetLast(&pClient->Events);
    … …  
    12041204    RT_ZERO(cmdCtx);
    12051205
    1206     if (pClient->State.uProtocolVer == 0) /* Legacy protocol */
     1206    if (!(pClient->State.fGuestFeatures0 & VBOX_SHCL_GF_0_CONTEXT_ID)) /* Legacy */
    12071207    {
    12081208        if (cParms < 2)
    … …  
    14311431    AssertPtr(pClient);
    14321432
    1433     LogFunc(("u32ClientID=%RU32 (proto %RU32), fn=%RU32 (%s), cParms=%RU32, paParms=%p\n",
    1434              u32ClientID, pClient->State.uProtocolVer, u32Function, ShClGuestMsgToStr(u32Function), cParms, paParms));
     1433    LogFunc(("u32ClientID=%RU32, fn=%RU32 (%s), cParms=%RU32, paParms=%p\n",
     1434             u32ClientID, u32Function, ShClGuestMsgToStr(u32Function), cParms, paParms));
    14351435
    14361436#ifdef DEBUG
    … …  
    14581458                rc = VERR_INVALID_PARAMETER;
    14591459            }
    1460             else if (   paParms[0].type != VBOX_HGCM_SVC_PARM_32BIT  /* uProtocolVer */
    1461                      || paParms[1].type != VBOX_HGCM_SVC_PARM_32BIT  /* uProtocolFlags */
    1462                      || paParms[2].type != VBOX_HGCM_SVC_PARM_32BIT  /* cbChunkSize */
    1463                      || paParms[3].type != VBOX_HGCM_SVC_PARM_32BIT  /* enmCompression */
    1464                      || paParms[4].type != VBOX_HGCM_SVC_PARM_32BIT) /* enmChecksumType */
     1460            else if (   paParms[0].type != VBOX_HGCM_SVC_PARM_32BIT  /* cbChunkSize */
     1461                     || paParms[1].type != VBOX_HGCM_SVC_PARM_32BIT  /* enmCompression */
     1462                     || paParms[2].type != VBOX_HGCM_SVC_PARM_32BIT) /* enmChecksumType */
    14651463            {
    14661464                rc = VERR_INVALID_PARAMETER;
    … …  
    14721470            else
    14731471            {
    1474                 /* Update the protocol version and tell the guest. */
    1475                 pClient->State.uProtocolVer = 1;
    1476 
    1477                 LogFlowFunc(("Now using protocol v%RU32\n", pClient->State.uProtocolVer));
    1478 
    1479                 HGCMSvcSetU32(&paParms[0], pClient->State.uProtocolVer);
    1480                 HGCMSvcSetU32(&paParms[1], 0 /* Procotol flags, not used yet */);
    1481                 HGCMSvcSetU32(&paParms[2], pClient->State.cbChunkSize);
    1482                 HGCMSvcSetU32(&paParms[3], 0 /* Compression type, not used yet */);
    1483                 HGCMSvcSetU32(&paParms[4], 0 /* Checksum type, not used yet */);
     1472                /* Report back supported chunk size to the guest. */
     1473                HGCMSvcSetU32(&paParms[0], _64K); /* Chunk size */ /** @todo Make chunk size dynamic. */
    14841474
    14851475                rc = VINF_SUCCESS;
    … …  
    15231513            uint32_t uFormats = 0;
    15241514
    1525             if (pClient->State.uProtocolVer == 0)
     1515            if (!(pClient->State.fGuestFeatures0 & VBOX_SHCL_GF_0_CONTEXT_ID)) /* Legacy */
    15261516            {
    15271517                if (cParms != 1)
    … …  
    17991789    LogFlowFuncEnter();
    18001790
    1801     pClientState->uProtocolVer    = 0;
    18021791    pClientState->fGuestFeatures0 = VBOX_SHCL_GF_NONE;
    18031792    pClientState->fGuestFeatures1 = VBOX_SHCL_GF_NONE;
    … …  
    19001889static SSMFIELD const s_aShClSSMClientState[] =
    19011890{
    1902     SSMFIELD_ENTRY(SHCLCLIENTSTATE, uProtocolVer),
    1903     SSMFIELD_ENTRY(SHCLCLIENTSTATE, cbChunkSize),
    1904     SSMFIELD_ENTRY(SHCLCLIENTSTATE, enmSource),
     1891    /** Note: Saving the session ID not necessary, as they're not persistent across state save/restore. */
     1892    SSMFIELD_ENTRY    (SHCLCLIENTSTATE, fGuestFeatures0),
     1893    SSMFIELD_ENTRY    (SHCLCLIENTSTATE, fGuestFeatures1),
     1894    SSMFIELD_ENTRY    (SHCLCLIENTSTATE, cbChunkSize),
     1895    SSMFIELD_ENTRY    (SHCLCLIENTSTATE, enmSource),
    19051896    SSMFIELD_ENTRY_TERM()
    19061897};
    … …  
    19091900 * SSM descriptor table for the SHCLCLIENTURISTATE structure.
    19101901 */
    1911 static SSMFIELD const s_aShClSSMClientURIState[] =
     1902static SSMFIELD const s_aShClSSMClientTransferState[] =
    19121903{
    19131904    SSMFIELD_ENTRY(SHCLCLIENTTRANSFERSTATE, enmTransferDir),
    … …  
    19381929static DECLCALLBACK(int) svcSaveState(void *, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM)
    19391930{
    1940     RT_NOREF(u32ClientID);
     1931    LogFlowFuncEnter();
    19411932
    19421933#ifndef UNIT_TEST
    … …  
    19471938     * Pending requests, if any, will be completed in svcDisconnect.
    19481939     */
     1940    RT_NOREF(u32ClientID);
    19491941    LogFunc(("u32ClientID=%RU32\n", u32ClientID));
    19501942
    … …  
    19581950    AssertRCReturn(rc, rc);
    19591951
    1960     rc = SSMR3PutStructEx(pSSM, &pClient->State.Transfers, sizeof(pClient->State.Transfers), 0 /*fFlags*/, &s_aShClSSMClientURIState[0], NULL);
     1952    rc = SSMR3PutStructEx(pSSM, &pClient->State.Transfers, sizeof(pClient->State.Transfers), 0 /*fFlags*/, &s_aShClSSMClientTransferState[0], NULL);
    19611953    AssertRCReturn(rc, rc);
    19621954
    … …  
    20262018static DECLCALLBACK(int) svcLoadState(void *, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM, uint32_t uVersion)
    20272019{
     2020    LogFlowFuncEnter();
     2021
    20282022#ifndef UNIT_TEST
     2023
    20292024    RT_NOREF(u32ClientID, uVersion);
    2030 
    2031     LogFunc(("u32ClientID=%RU32\n", u32ClientID));
    20322025
    20332026    PSHCLCLIENT pClient = (PSHCLCLIENT)pvClient;
    … …  
    20382031    int rc = SSMR3GetU32(pSSM, &lenOrVer);
    20392032    AssertRCReturn(rc, rc);
     2033
     2034    LogFunc(("u32ClientID=%RU32, lenOrVer=%#RX64\n", u32ClientID, lenOrVer));
     2035
    20402036    if (lenOrVer == VBOX_SHCL_SSM_VER_0)
    20412037    {
    … …  
    20442040    else if (lenOrVer == VBOX_SHCL_SSM_VER_1)
    20452041    {
    2046         rc = SSMR3GetStructEx(pSSM, &pClient->State, sizeof(pClient->State), 0 /*fFlags*/, &s_aShClSSMClientState[0], NULL);
     2042        rc = SSMR3GetStructEx(pSSM, &pClient->State, sizeof(pClient->State), 0 /* fFlags */,
     2043                              &s_aShClSSMClientState[0], NULL);
    20472044        AssertRCReturn(rc, rc);
    20482045
    2049         rc = SSMR3GetStructEx(pSSM, &pClient->State.Transfers, sizeof(pClient->State.Transfers), 0 /*fFlags*/, &s_aShClSSMClientURIState[0], NULL);
     2046        rc = SSMR3GetStructEx(pSSM, &pClient->State.Transfers, sizeof(pClient->State.Transfers), 0 /* fFlags */,
     2047                              &s_aShClSSMClientTransferState[0], NULL);
    20502048        AssertRCReturn(rc, rc);
    20512049
    … …  
    21922190    int rc = VINF_SUCCESS;
    21932191
    2194     LogFlowFunc(("ptable=%p\n", pTable));
    2195 
    2196     if (!pTable)
     2192    LogFlowFunc(("pTable=%p\n", pTable));
     2193
     2194    if (!VALID_PTR(pTable))
    21972195    {
    21982196        rc = VERR_INVALID_PARAMETER;
    … …  
    22002198    else
    22012199    {
    2202         LogFunc(("ptable->cbSize = %d, ptable->u32Version = 0x%08X\n", pTable->cbSize, pTable->u32Version));
     2200        LogFunc(("pTable->cbSize = %d, ptable->u32Version = 0x%08X\n", pTable->cbSize, pTable->u32Version));
    22032201
    22042202        if (   pTable->cbSize     != sizeof (VBOXHGCMSVCFNTABLE)
    22052203            || pTable->u32Version != VBOX_HGCM_SVC_VERSION)
    22062204        {
    2207             rc = VERR_INVALID_PARAMETER;
     2205            rc = VERR_VERSION_MISMATCH;
    22082206        }
    22092207        else
    … …  
    22132211            pTable->cbClient = sizeof(SHCLCLIENT);
    22142212
    2215             pTable->pfnUnload     = svcUnload;
    2216             pTable->pfnConnect    = svcConnect;
    2217             pTable->pfnDisconnect = svcDisconnect;
    2218             pTable->pfnCall       = svcCall;
    2219             pTable->pfnHostCall   = svcHostCall;
    2220             pTable->pfnSaveState  = svcSaveState;
    2221             pTable->pfnLoadState  = svcLoadState;
    2222             pTable->pfnRegisterExtension  = svcRegisterExtension;
    2223             pTable->pfnNotify     = NULL;
    2224             pTable->pvService     = NULL;
     2213            pTable->pfnUnload            = svcUnload;
     2214            pTable->pfnConnect           = svcConnect;
     2215            pTable->pfnDisconnect        = svcDisconnect;
     2216            pTable->pfnCall              = svcCall;
     2217            pTable->pfnHostCall          = svcHostCall;
     2218            pTable->pfnSaveState         = svcSaveState;
     2219            pTable->pfnLoadState         = svcLoadState;
     2220            pTable->pfnRegisterExtension = svcRegisterExtension;
     2221            pTable->pfnNotify            = NULL;
     2222            pTable->pvService            = NULL;
    22252223
    22262224            /* Service specific initialization. */
    … …  
    22292227    }
    22302228
     2229    LogFlowFunc(("Returning %Rrc\n", rc));
    22312230    return rc;
    22322231}
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette