VirtualBox

Changeset 80444 in vbox for trunk/include/VBox/HostServices


Ignore:
Timestamp:
Aug 27, 2019 5:47:44 PM (6 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
132934
Message:

Shared Clipboard/URI: Added protocol versioning support plus enhanced versions of existing commands (to also provide context IDs, among other stuff). So far only the host service(s) and the Windows guest is using the new(er) protocol.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r80359 r80444  
    6969 * The host messages for the guest.
    7070 */
    71 #define VBOX_SHARED_CLIPBOARD_HOST_MSG_QUIT                   1
    72 #define VBOX_SHARED_CLIPBOARD_HOST_MSG_READ_DATA              2
    73 #define VBOX_SHARED_CLIPBOARD_HOST_MSG_REPORT_FORMATS         3
     71/** Asks the client to quit / terminate. */
     72#define VBOX_SHARED_CLIPBOARD_HOST_MSG_QUIT                         1
     73/** Reads (simple) data from the guest. */
     74#define VBOX_SHARED_CLIPBOARD_HOST_MSG_READ_DATA                    2
     75/** Reports available clipboard format from host to the guest.
     76 *  Formerly known as VBOX_SHARED_CLIPBOARD_HOST_MSG_REPORT_FORMATS. */
     77#define VBOX_SHARED_CLIPBOARD_HOST_MSG_FORMATS_WRITE                3
     78/** Reports available clipboard format from host to the guest. */
     79#define VBOX_SHARED_CLIPBOARD_HOST_MSG_FORMATS_READ                 4
    7480
    7581/** Initiates a new transfer (read / write) on the guest side. */
    … …  
    114120 *  Note: This is the old message which still is being used for the non-URI Shared Clipboard transfers,
    115121 *        to not break compatibility with older Guest Additions / VBox versions. */
    116 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG_OLD  1
    117 /** Sends a list of available formats to the host. */
    118 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_REPORT_FORMATS    2
     122#define VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG_OLD       1
     123/** Sends a list of available formats to the host.
     124 *  Formely known as VBOX_SHARED_CLIPBOARD_GUEST_FN_REPORT_FORMATS. */
     125#define VBOX_SHARED_CLIPBOARD_GUEST_FN_FORMATS_WRITE         2
    119126/** Reads data in specified format from the host. */
    120 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_DATA         3
     127#define VBOX_SHARED_CLIPBOARD_GUEST_FN_DATA_READ              3
    121128/** Writes data in requested format to the host. */
    122 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA        4
    123 
     129#define VBOX_SHARED_CLIPBOARD_GUEST_FN_DATA_WRITE             4
     130
     131/** */
     132#define VBOX_SHARED_CLIPBOARD_GUEST_FN_CONNECT                5
    124133/** Peeks at the next message, returning immediately.
    125  *  New since URI handling was implemented. */
    126 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_PEEK_NOWAIT        5
     134 *  New since protocol v1. */
     135#define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_PEEK_NOWAIT        6
    127136/** Peeks at the next message, waiting for one to arrive.
    128  *  New since URI handling was implemented. */
    129 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_PEEK_WAIT          6
     137 *  New since protocol v1. */
     138#define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_PEEK_WAIT          7
    130139/** Gets the next message, returning immediately.
    131  *  New since URI handling was implemented. */
    132 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_GET                7
     140 *  New since protocol v1. */
     141#define VBOX_SHARED_CLIPBOARD_GUEST_FN_MSG_GET                8
    133142/** Sends a transfer status to the host.
    134  *  New since URI handling was implemented. */
    135 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_STATUS                 8
     143 *  New since protocol v1. */
     144#define VBOX_SHARED_CLIPBOARD_GUEST_FN_STATUS                 9
    136145/** Replies to a function from the host.
    137  *  New since URI handling was implemented. */
    138 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_REPLY                  9
     146 *  New since protocol v1. */
     147#define VBOX_SHARED_CLIPBOARD_GUEST_FN_REPLY                  10
    139148/** Reports the available root entries of a transfer.
    140  *  New since URI handling was implemented. */
    141 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_HDR_READ     10
     149 *  New since protocol v1. */
     150#define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_HDR_READ     11
    142151/** Reports the available root entries of a transfer.
    143  *  New since URI handling was implemented. */
    144 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_HDR_WRITE    11
     152 *  New since protocol v1. */
     153#define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_HDR_WRITE    12
    145154/** Reports the available root entries of a transfer.
    146  *  New since URI handling was implemented. */
    147 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_ENTRY_READ   12
     155 *  New since protocol v1. */
     156#define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_ENTRY_READ   13
    148157/** Reports the available root entries of a transfer.
    149  *  New since URI handling was implemented. */
    150 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_ENTRY_WRITE  13
     158 *  New since protocol v1. */
     159#define VBOX_SHARED_CLIPBOARD_GUEST_FN_ROOT_LIST_ENTRY_WRITE  14
    151160/** Opens / gets a list handle from the host.
    152  *  New since URI handling was implemented. */
    153 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_OPEN              14
     161 *  New since protocol v1. */
     162#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_OPEN              15
    154163/** Closes a list handle from the host.
    155  *  New since URI handling was implemented. */
    156 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_CLOSE             15
     164 *  New since protocol v1. */
     165#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_CLOSE             16
    157166/** Reads a list header from the host.
    158  *  New since URI handling was implemented. */
    159 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_HDR_READ          16
     167 *  New since protocol v1. */
     168#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_HDR_READ          17
    160169/** Writes a list header to the host.
    161  *  New since URI handling was implemented. */
    162 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_HDR_WRITE         17
    163 /** New since URI handling was implemented. */
    164 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_ENTRY_READ        18
    165 /** New since URI handling was implemented. */
    166 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_ENTRY_WRITE       19
    167 /** New since URI handling was implemented. */
    168 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_OPEN               20
    169 /** New since URI handling was implemented. */
    170 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_CLOSE              21
    171 /** New since URI handling was implemented. */
    172 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_READ               22
    173 /**  New since URI handling was implemented. */
    174 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_WRITE              23
     170 *  New since protocol v1. */
     171#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_HDR_WRITE         18
     172/** New since protocol v1. */
     173#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_ENTRY_READ        19
     174/** New since protocol v1. */
     175#define VBOX_SHARED_CLIPBOARD_GUEST_FN_LIST_ENTRY_WRITE       20
     176/** New since protocol v1. */
     177#define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_OPEN               21
     178/** New since protocol v1. */
     179#define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_CLOSE              22
     180/** New since protocol v1. */
     181#define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_READ               23
     182/** New since protocol v1. */
     183#define VBOX_SHARED_CLIPBOARD_GUEST_FN_OBJ_WRITE              24
    175184/** Reports cancellation of the current operation to the host.
    176  *  New since URI handling was implemented. */
    177 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_CANCEL                 24
     185 *  New since protocol v1. */
     186#define VBOX_SHARED_CLIPBOARD_GUEST_FN_CANCEL                 25
    178187/** Reports an error to the host.
    179  *  New since URI handling was implemented. */
    180 #define VBOX_SHARED_CLIPBOARD_GUEST_FN_ERROR                  25
     188 *  New since protocol v1. */
     189#define VBOX_SHARED_CLIPBOARD_GUEST_FN_ERROR                  26
    181190
    182191/** The maximum default chunk size for a single data transfer. */
    183192#define VBOX_SHARED_CLIPBOARD_MAX_CHUNK_SIZE                  _64K
    184193
    185 /** Maximum number of concurrent Shared Clipboard transfers a VM can have. */
    186 #define VBOX_SHARED_CLIPBOARD_MAX_TRANSFERS                   UINT16_MAX
     194/** Maximum number of concurrent Shared Clipboard transfers a VM can have.
     195 *  Number 0 always is reserved for the client itself. */
     196#define VBOX_SHARED_CLIPBOARD_MAX_TRANSFERS                   UINT16_MAX - 1
    187197/** Maximum number of concurrent events a transfer can have. */
    188198#define VBOX_SHARED_CLIPBOARD_MAX_EVENTS                      UINT16_MAX
    189199
    190 /** Creates a context ID out of a transfer ID. */
    191 #define VBOX_SHARED_CLIPBOARD_CONTEXTID_MAKE(uTransfer, uEvent) \
    192     RT_MAKE_U32(uEvent, uTransfer)
     200/**
     201 * Creates a context ID out of a source ID.
     202 *
     203 * ID 0 *always* is reserved for the client itself, whereas
     204 * IDs > 0 are being used for transfers of this client.
     205 */
     206#define VBOX_SHARED_CLIPBOARD_CONTEXTID_MAKE(uID, uEvent) \
     207    RT_MAKE_U32(uEvent, uID)
    193208/** Gets the transfer ID out of a context ID. */
    194 #define VBOX_SHARED_CLIPBOARD_CONTEXTID_GET_TRANSFER(uContextID) \
     209#define VBOX_SHARED_CLIPBOARD_CONTEXTID_GET_SOURCE(uContextID) \
    195210    RT_HI_U16(uContextID)
    196211/** Gets the event ID out of a context ID. */
    … …  
    202217 */
    203218#pragma pack(1)
     219/**
     220 * Waits (blocking) for a new host message to arrive.
     221 * Deprecated; do not use anymore.
     222 * Kept for maintaining compatibility with older Guest Additions.
     223 */
    204224typedef struct _VBoxClipboardGetHostMsgOld
    205225{
    206226    VBGLIOCHGCMCALL hdr;
    207227
    208     /* VBOX_SHARED_CLIPBOARD_HOST_MSG_* */
    209     HGCMFunctionParameter msg;     /* OUT uint32_t */
    210 
    211     /* VBOX_SHARED_CLIPBOARD_FMT_*, depends on the 'msg'. */
     228    /** uint32_t, out: Host message type. */
     229    HGCMFunctionParameter msg;
     230    /** uint32_t, out: VBOX_SHARED_CLIPBOARD_FMT_*, depends on the 'msg'.
     231     *  r=andy This actual can have *different* meanings, depending on the host message type. */
    212232    HGCMFunctionParameter formats; /* OUT uint32_t */
    213233} VBoxClipboardGetHostMsgOld;
    … …  
    215235#define VBOX_SHARED_CLIPBOARD_CPARMS_GET_HOST_MSG_OLD 2
    216236
    217 typedef struct _VBoxClipboardReportFormatsMsg
    218 {
    219     VBGLIOCHGCMCALL hdr;
    220 
    221     /* VBOX_SHARED_CLIPBOARD_FMT_* */
    222     HGCMFunctionParameter formats; /* OUT uint32_t */
    223 } VBoxClipboardReportFormatsMsg;
    224 
    225 #define VBOX_SHARED_CLIPBOARD_CPARMS_REPORT_FORMATS 1
     237/**
     238 * Message for doing the protocol negotiation between the host
     239 * and the guest. Not available on older (VBox <= 6.0) hosts.
     240 */
     241typedef struct _VBoxClipboardConnect
     242{
     243    VBGLIOCHGCMCALL hdr;
     244
     245    /** uint32_t, out: Protocol version. */
     246    HGCMFunctionParameter uProtocolVer;
     247    /** uint32_t, out: Protocol flags, unused at the moment. */
     248    HGCMFunctionParameter uProtocolFlags;
     249    /** uint32_t, out: Maximum chunk size for data transfers. */
     250    HGCMFunctionParameter cbChunkSize;
     251    /** uint32_t, in/out: Compression type. Currently unused. */
     252    HGCMFunctionParameter enmCompression;
     253    /** uint32_t, in/out: Checksum type used for data transfer. Currently unused. */
     254    HGCMFunctionParameter enmChecksumType;
     255} VBoxClipboardConnect;
     256
     257#define VBOX_SHARED_CLIPBOARD_CPARMS_CONNECT 5
     258
     259typedef struct _VBoxClipboardFormatsMsg
     260{
     261    VBGLIOCHGCMCALL hdr;
     262
     263    /** uint32_t, in: Context ID. */
     264    HGCMFunctionParameter uContext;
     265    /** uint32_t, out:  VBOX_SHARED_CLIPBOARD_FMT_*. */
     266    HGCMFunctionParameter uFormats;
     267    /** uint32_t, in: Format flags. */
     268    HGCMFunctionParameter fFlags;
     269} VBoxClipboardFormatsMsg;
     270
     271typedef struct _VBoxClipboardReadDataReqMsg
     272{
     273    VBGLIOCHGCMCALL hdr;
     274
     275    /** uint32_t, out: Context ID. */
     276    HGCMFunctionParameter uContext;
     277    /** uint32_t, out: Requested format to read data in. */
     278    HGCMFunctionParameter uFormat;
     279    /** uint32_t, out: Maximum size (in bytes) to read. */
     280    HGCMFunctionParameter cbSize;
     281} VBoxClipboardReadDataReqMsg;
     282
     283#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_DATA_REQ 2
    226284
    227285typedef struct _VBoxClipboardReadDataMsg
    … …  
    229287    VBGLIOCHGCMCALL hdr;
    230288
    231     /* Requested format. */
     289    /** uint32_t, out: Requested format. */
    232290    HGCMFunctionParameter format; /* IN uint32_t */
    233 
    234     /* The data buffer. */
     291    /** ptr, out: The data buffer. */
    235292    HGCMFunctionParameter ptr;    /* IN linear pointer. */
    236 
    237     /* Size of returned data, if > ptr->cb, then no data was
    238      * actually transferred and the guest must repeat the call.
     293    /** uint32_t, out: Size of returned data, if > ptr->cb, then no data was
     294     *  actually transferred and the guest must repeat the call.
    239295     */
    240296    HGCMFunctionParameter size;   /* OUT uint32_t */
    … …  
    248304    VBGLIOCHGCMCALL hdr;
    249305
    250     /* Returned format as requested in the VBOX_SHARED_CLIPBOARD_HOST_MSG_READ_DATA message. */
    251     HGCMFunctionParameter format; /* IN uint32_t */
    252 
    253     /* Data.  */
    254     HGCMFunctionParameter ptr;    /* IN linear pointer. */
     306    union
     307    {
     308        struct
     309        {
     310            /** Returned format as requested in the VBOX_SHARED_CLIPBOARD_HOST_MSG_READ_DATA message. */
     311            HGCMFunctionParameter format; /* IN uint32_t */
     312            /** Data.  */
     313            HGCMFunctionParameter ptr;    /* IN linear pointer. */
     314        } v0;
     315        struct
     316        {
     317            /** uint32_t, out: Context ID. */
     318            HGCMFunctionParameter uContext;
     319            /** uint32_t, out: Requested format to read data in. */
     320            HGCMFunctionParameter uFormat;
     321            /** uint32_t, out: Size of data (in bytes). */
     322            HGCMFunctionParameter cbData;
     323            /** ptr, out: Actual data. */
     324            HGCMFunctionParameter pvData;
     325        } v1;
     326    };
    255327} VBoxClipboardWriteDataMsg;
    256328
    257 #define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DATA 2
     329#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DATA 4
    258330
    259331typedef struct _VBoxClipboardTransferReport
    … …  
    394466    /** uint64_t, in/out: Number of total root list entries. */
    395467    HGCMFunctionParameter      cRoots;
    396     /** uint32_t, in/out: Compression type. */
    397     HGCMFunctionParameter      enmCompression;
    398     /** uint32_t, in/out: Checksum type used for data transfer. */
    399     HGCMFunctionParameter      enmChecksumType;
    400468} VBoxClipboardRootListHdrMsg;
    401469
    402 #define VBOX_SHARED_CLIPBOARD_CPARMS_ROOT_LIST_HDR 5
     470#define VBOX_SHARED_CLIPBOARD_CPARMS_ROOT_LIST_HDR 2
    403471
    404472typedef struct _VBoxClipboardRootListEntryParms
    … …  
    521589    /** uint64_t, in/out:  Number of total bytes to transfer. */
    522590    HGCMFunctionParameter        cbTotalSize;
    523     /** uint32_t, in/out: Compression type. */
    524     HGCMFunctionParameter        enmCompression;
    525     /** uint32_t, in/out: Checksum type used for data transfer. */
    526     HGCMFunctionParameter        enmChecksumType;
    527591} VBoxClipboardListHdrMsg;
    528592
    529 #define VBOX_SHARED_CLIPBOARD_CPARMS_LIST_HDR 8
     593#define VBOX_SHARED_CLIPBOARD_CPARMS_LIST_HDR 6
    530594
    531595typedef struct _VBoxClipboardListEntryReqParms
Note: See TracChangeset for help on using the changeset viewer.

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