VirtualBox

source: vbox/trunk/include/VBox/HostServices/VBoxClipboardSvc.h@ 79267

Last change on this file since 79267 was 79267, checked in by vboxsync, 5 years ago

Shared Clipboard/URI: Update.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 17.2 KB
Line 
1/** @file
2 * Shared Clipboard - Common header for host service and guest clients.
3 */
4
5/*
6 * Copyright (C) 2006-2019 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h
27#define VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <VBox/VMMDevCoreTypes.h>
33#include <VBox/VBoxGuestCoreTypes.h>
34#include <VBox/hgcmsvc.h>
35
36/*
37 * The mode of operations.
38 */
39#define VBOX_SHARED_CLIPBOARD_MODE_OFF 0
40#define VBOX_SHARED_CLIPBOARD_MODE_HOST_TO_GUEST 1
41#define VBOX_SHARED_CLIPBOARD_MODE_GUEST_TO_HOST 2
42#define VBOX_SHARED_CLIPBOARD_MODE_BIDIRECTIONAL 3
43
44/*
45 * The service functions which are callable by host.
46 */
47#define VBOX_SHARED_CLIPBOARD_HOST_FN_SET_MODE 1
48/** Run headless on the host, i.e. do not touch the host clipboard. */
49#define VBOX_SHARED_CLIPBOARD_HOST_FN_SET_HEADLESS 2
50/** Reports cancellation of the current operation to the guest. */
51#define VBOX_SHARED_CLIPBOARD_HOST_FN_CANCEL 3
52/** Reports an error to the guest. */
53#define VBOX_SHARED_CLIPBOARD_HOST_FN_ERROR 4
54/** Reports that a new clipboard area has been registered. */
55#define VBOX_SHARED_CLIPBOARD_HOST_FN_AREA_REGISTER 5
56/** Reports that a clipboard area has been unregistered. */
57#define VBOX_SHARED_CLIPBOARD_HOST_FN_AREA_UNREGISTER 6
58/** Reports that a client (host / guest) has attached to a clipboard area. */
59#define VBOX_SHARED_CLIPBOARD_HOST_FN_AREA_ATTACH 7
60/** Reports that a client (host / guest) has detached from a clipboard area. */
61#define VBOX_SHARED_CLIPBOARD_HOST_FN_AREA_DETACH 8
62
63/*
64 * The service functions which are called by guest.
65 */
66/** Calls the host and waits (blocking) for an host event VBOX_SHARED_CLIPBOARD_HOST_MSG_*. */
67#define VBOX_SHARED_CLIPBOARD_GUEST_FN_GET_HOST_MSG 1
68/** Sends a list of available formats to the host. */
69#define VBOX_SHARED_CLIPBOARD_GUEST_FN_REPORT_FORMATS 2
70/** Reads data in specified format from the host. */
71#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_DATA 3
72/** Writes data in requested format to the host. */
73#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA 4
74/** Reads the data header at the beginning of a (new) data transfer from the host.
75 * New since URI handling was implemented. */
76#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_DATA_HDR 5
77/** Writes data in requested format to the host. */
78#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_DATA_CHUNK 6
79/** Writes the data header at the beginning of a (new) data transfer to the host.
80 * New since URI handling was implemented. */
81#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA_HDR 7
82/** Writes data in requested format to the host. */
83#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA_CHUNK 8
84/** Reads a new directory entry from the host.
85 * New since URI handling was implemented. */
86#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_DIR 9
87/** Writes a new directory entry to the host.
88 * New since URI handling was implemented. */
89#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DIR 10
90/** Reads a new file header entry from the host.
91 * New since URI handling was implemented. */
92#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_FILE_HDR 11
93/** Writes a new file header entry to the host.
94 * New since URI handling was implemented. */
95#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_FILE_HDR 12
96/** Reads a new file data chunk entry from the host.
97 * New since URI handling was implemented. */
98#define VBOX_SHARED_CLIPBOARD_GUEST_FN_READ_FILE_DATA 13
99/** Writes a new file data chunk entry to the host.
100 * New since URI handling was implemented. */
101#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_FILE_DATA 14
102/** Reports cancellation of the current operation to the host.
103 * New since URI handling was implemented. */
104#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_CANCEL 15
105/** Reports an error to the host.
106 * New since URI handling was implemented. */
107#define VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_ERROR 16
108
109/** The maximum default chunk size for a single data transfer. */
110#define VBOX_SHARED_CLIPBOARD_MAX_CHUNK_SIZE _64K
111
112/*
113 * HGCM parameter structures.
114 */
115#pragma pack(1)
116typedef struct _VBoxClipboardGetHostMsg
117{
118 VBGLIOCHGCMCALL hdr;
119
120 /* VBOX_SHARED_CLIPBOARD_HOST_MSG_* */
121 HGCMFunctionParameter msg; /* OUT uint32_t */
122
123 /* VBOX_SHARED_CLIPBOARD_FMT_*, depends on the 'msg'. */
124 HGCMFunctionParameter formats; /* OUT uint32_t */
125} VBoxClipboardGetHostMsg;
126
127#define VBOX_SHARED_CLIPBOARD_CPARMS_GET_HOST_MSG 2
128
129typedef struct _VBoxClipboardReportFormatsMsg
130{
131 VBGLIOCHGCMCALL hdr;
132
133 /* VBOX_SHARED_CLIPBOARD_FMT_* */
134 HGCMFunctionParameter formats; /* OUT uint32_t */
135} VBoxClipboardReportFormatsMsg;
136
137#define VBOX_SHARED_CLIPBOARD_CPARMS_REPORT_FORMATS 1
138
139typedef struct _VBoxClipboardReadDataMsg
140{
141 VBGLIOCHGCMCALL hdr;
142
143 /* Requested format. */
144 HGCMFunctionParameter format; /* IN uint32_t */
145
146 /* The data buffer. */
147 HGCMFunctionParameter ptr; /* IN linear pointer. */
148
149 /* Size of returned data, if > ptr->cb, then no data was
150 * actually transferred and the guest must repeat the call.
151 */
152 HGCMFunctionParameter size; /* OUT uint32_t */
153
154} VBoxClipboardReadDataMsg;
155
156#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_DATA 3
157
158typedef struct _VBoxClipboardWriteDataMsg
159{
160 VBGLIOCHGCMCALL hdr;
161
162 /* Returned format as requested in the VBOX_SHARED_CLIPBOARD_HOST_MSG_READ_DATA message. */
163 HGCMFunctionParameter format; /* IN uint32_t */
164
165 /* Data. */
166 HGCMFunctionParameter ptr; /* IN linear pointer. */
167} VBoxClipboardWriteDataMsg;
168
169#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DATA 2
170
171/**
172 * Reads / writes the (meta) data header.
173 *
174 * Used by:
175 * VBOX_SHARED_CLIPBOARD_FN_READ_DATA_HDR
176 * VBOX_SHARED_CLIPBOARD_FN_WRITE_DATA_HDR
177 */
178typedef struct _VBoxClipboardDataHdrMsg
179{
180 VBGLIOCHGCMCALL hdr;
181
182 /** Context ID. Unused at the moment. */
183 HGCMFunctionParameter uContext; /* OUT uint32_t */
184 /** Data transfer flags. Not yet used and must be 0. */
185 HGCMFunctionParameter uFlags; /* OUT uint32_t */
186 /** Screen ID where the data originates from. */
187 HGCMFunctionParameter uScreenId; /* OUT uint32_t */
188 /** Total size (in bytes) to transfer. */
189 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
190 /**
191 * Total meta data size (in bytes) to transfer.
192 * This size also is part of cbTotal already, so:
193 *
194 * cbTotal = cbMeta + additional size for files etc.
195 */
196 HGCMFunctionParameter cbMeta; /* OUT uint64_t */
197 /** Size (in bytes) of meta data format. */
198 HGCMFunctionParameter cbMetaFmt; /* OUT uint32_t */
199 /** Meta data format. */
200 HGCMFunctionParameter pvMetaFmt; /* OUT ptr */
201 /* Number of objects (files/directories) to transfer. */
202 HGCMFunctionParameter cObjects; /* OUT uint64_t */
203 /** Compression type. */
204 HGCMFunctionParameter enmCompression; /* OUT uint32_t */
205 /** Checksum type. */
206 HGCMFunctionParameter enmChecksumType; /* OUT uint32_t */
207 /** Size (in bytes) of checksum. */
208 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
209 /** Checksum buffer for the entire data to be transferred. */
210 HGCMFunctionParameter pvChecksum; /* OUT ptr */
211} VBoxClipboardReadDataHdrMsg, VBoxClipboardWriteDataHdrMsg;
212
213#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_DATA_HDR 12
214#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DATA_HDR 12
215
216/**
217 * Reads / writes a (meta) data block.
218 *
219 * Used by:
220 * VBOX_SHARED_CLIPBOARD_FN_READ_DATA_CHUNK
221 * VBOX_SHARED_CLIPBOARD_FN_WRITE_DATA_CHUNK
222 */
223typedef struct _VBoxClipboardDataChunkMsg
224{
225 VBGLIOCHGCMCALL hdr;
226
227 /** Context ID. Unused at the moment. */
228 HGCMFunctionParameter uContext; /* OUT uint32_t */
229 /** Size (in bytes) of data block to send. */
230 HGCMFunctionParameter cbData; /* OUT uint32_t */
231 /** Data block to send. */
232 HGCMFunctionParameter pvData; /* OUT ptr */
233 /** Size (in bytes) of checksum. */
234 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
235 /** (Rolling) Checksum, based on checksum type in data header. */
236 HGCMFunctionParameter pvChecksum; /* OUT ptr */
237} VBoxClipboardReadDataChunkMsg, VBoxClipboardWriteDataChunkMsg;
238
239#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_DATA_CHUNK 5
240#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DATA_CHUNK 5
241
242/**
243 * Reads / writes a directory entry.
244 *
245 * Used by:
246 * VBOX_SHARED_CLIPBOARD_FN_READ_DIR
247 * VBOX_SHARED_CLIPBOARD_FN_WRITE_DIR
248 */
249typedef struct _VBoxClipboardDirMsg
250{
251 VBGLIOCHGCMCALL hdr;
252
253 /** Context ID. Unused at the moment. */
254 HGCMFunctionParameter uContext; /* OUT uint32_t */
255 /** Size (in bytes) of directory name. */
256 HGCMFunctionParameter cbName; /* OUT uint32_t */
257 /** Directory name. */
258 HGCMFunctionParameter pvName; /* OUT ptr */
259 /** Directory mode. */
260 HGCMFunctionParameter fMode; /* OUT uint32_t */
261} VBoxClipboardReadDirMsg, VBoxClipboardWriteDirMsg;
262
263#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_DIR 4
264#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_DIR 4
265
266/**
267 * File header message, marking the start of transferring a new file.
268 *
269 * Used by:
270 * VBOX_SHARED_CLIPBOARD_FN_READ_FILE_HDR
271 * VBOX_SHARED_CLIPBOARD_FN_WRITE_FILE_HDR
272 */
273typedef struct _VBoxClipboardFileHdrMsg
274{
275 VBGLIOCHGCMCALL hdr;
276
277 /** Context ID. Unused at the moment. */
278 HGCMFunctionParameter uContext; /* OUT uint32_t */
279 /** Size (in bytes) of file path. */
280 HGCMFunctionParameter cbName; /* OUT uint32_t */
281 /** File path. */
282 HGCMFunctionParameter pvName; /* OUT ptr */
283 /** Optional flags; unused at the moment. */
284 HGCMFunctionParameter uFlags; /* OUT uint32_t */
285 /** File creation mode. */
286 HGCMFunctionParameter fMode; /* OUT uint32_t */
287 /** Total size (in bytes). */
288 HGCMFunctionParameter cbTotal; /* OUT uint64_t */
289} VBoxClipboardReadFileHdrMsg, VBoxClipboardWriteFileHdrMsg;
290
291#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_FILE_HDR 6
292#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_FILE_HDR 6
293
294/**
295 * Reads / writes data of a file entry.
296 *
297 * Used by:
298 * VBOX_SHARED_CLIPBOARD_FN_READ_FILE_DATA
299 * VBOX_SHARED_CLIPBOARD_FN_WRITE_FILE_DATA
300 */
301typedef struct _VBoxClipboardFileDataMsg
302{
303 VBGLIOCHGCMCALL hdr;
304
305 /** Context ID. Unused at the moment. */
306 HGCMFunctionParameter uContext; /* OUT uint32_t */
307 /** Size (in bytes) of current data chunk. */
308 HGCMFunctionParameter cbData; /* OUT uint32_t */
309 /** Current data chunk. */
310 HGCMFunctionParameter pvData; /* OUT ptr */
311 /** Size (in bytes) of current data chunk checksum. */
312 HGCMFunctionParameter cbChecksum; /* OUT uint32_t */
313 /** Checksum of data block, based on the checksum
314 * type in the data header. Optional. */
315 HGCMFunctionParameter pvChecksum; /* OUT ptr */
316} VBoxClipboardReadFileDataMsg, VBoxClipboardWriteFileDataMsg;
317
318#define VBOX_SHARED_CLIPBOARD_CPARMS_READ_FILE_DATA 5
319#define VBOX_SHARED_CLIPBOARD_CPARMS_WRITE_FILE_DATA 5
320
321/**
322 * Sends an error event.
323 *
324 * Used by:
325 * VBOX_SHARED_CLIPBOARD_FN_WRITE_ERROR
326 */
327typedef struct _VBoxClipboardErrorMsg
328{
329 VBGLIOCHGCMCALL hdr;
330
331 /** Context ID. Unused at the moment. */
332 HGCMFunctionParameter uContext; /* OUT uint32_t */
333 /** The error code (IPRT-style). */
334 HGCMFunctionParameter rc; /* OUT uint32_t */
335} VBoxClipboardWriteErrorMsg;
336
337#pragma pack()
338
339/** Builds a callback magic out of the function ID and the version
340 * of the callback data. */
341#define VBOX_CLIPBOARD_CB_MAGIC_MAKE(uFn, uVer) \
342 RT_MAKE_U32(uVer, uFn)
343
344/*
345 * Callback magics.
346 */
347enum eVBoxClipboardCallbackMagics
348{
349 CB_MAGIC_CLIPBOARD_WRITE_DATA_HDR = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA_HDR, 0),
350 CB_MAGIC_CLIPBOARD_WRITE_DATA_CHUNK = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DATA_CHUNK, 0),
351 CB_MAGIC_CLIPBOARD_WRITE_DIR = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_DIR, 0),
352 CB_MAGIC_CLIPBOARD_WRITE_FILE_HDR = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_FILE_HDR, 0),
353 CB_MAGIC_CLIPBOARD_WRITE_FILE_DATA = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_FILE_DATA, 0),
354 CB_MAGIC_CLIPBOARD_WRITE_ERROR = VBOX_CLIPBOARD_CB_MAGIC_MAKE(VBOX_SHARED_CLIPBOARD_GUEST_FN_WRITE_ERROR, 0)
355};
356
357/**
358 * Data header.
359 */
360typedef struct _VBOXCLIPBOARDDATAHDR
361{
362 /** Data transfer flags. Not yet used and must be 0. */
363 uint32_t uFlags;
364 /** Screen ID where the data originates from. */
365 uint32_t uScreenId;
366 /** Total size (in bytes) to transfer. */
367 uint64_t cbTotal;
368 /** Meta data size (in bytes) to transfer.
369 * This size also is part of cbTotal already. */
370 uint32_t cbMeta;
371 /** Size (in bytes) of meta format buffer.
372 * Is sizeof(SHAREDCLIPBOARDMETADATAFMT). */
373 uint32_t cbMetaFmt;
374 /** Meta data format.
375 * Is SHAREDCLIPBOARDMETADATAFMT. */
376 void *pvMetaFmt;
377 /** Number of objects (files/directories) to transfer. */
378 uint64_t cObjects;
379 /** Compression type. Currently unused, so specify 0.
380 **@todo Add IPRT compression type enumeration as soon as it's available. */
381 uint32_t enmCompression;
382 /** Checksum type. Currently unused, so specify RTDIGESTTYPE_INVALID. */
383 RTDIGESTTYPE enmChecksumType;
384 /** Size (in bytes) of checksum. */
385 uint32_t cbChecksum;
386 /** The actual checksum buffer for the entire data to be transferred,
387 * based on enmChksumType. If RTDIGESTTYPE_INVALID is specified,
388 * no checksum is being used and pvChecksum will be NULL. */
389 void *pvChecksum;
390} VBOXCLIPBOARDDATAHDR, *PVBOXCLIPBOARDDATAHDR;
391
392typedef struct _VBOXCLIPBOARDDATACHUNK
393{
394 /** Data block buffer. */
395 void *pvData;
396 /** Size (in bytes) of data block. */
397 uint32_t cbData;
398 /** (Rolling) Checksum. Not yet implemented. */
399 void *pvChecksum;
400 /** Size (in bytes) of checksum. Not yet implemented. */
401 uint32_t cbChecksum;
402} VBOXCLIPBOARDDATACHUNK, *PVBOXCLIPBOARDDATACHUNK;
403
404typedef struct _VBOXCLIPBOARDDIRDATA
405{
406 /** Directory path. */
407 char *pszPath;
408 /** Size (in bytes) of path. */
409 uint32_t cbPath;
410 /** Directory creation mode. */
411 uint32_t fMode;
412} VBOXCLIPBOARDDIRDATA, *PVBOXCLIPBOARDDIRDATA;
413
414typedef struct _VBOXCLIPBOARDFILEHDR
415{
416 /** File path (name). */
417 char *pszFilePath;
418 /** Size (in bytes) of file path. */
419 uint32_t cbFilePath;
420 /** Total size (in bytes) of this file. */
421 uint64_t cbSize;
422 /** File (creation) mode. */
423 uint32_t fMode;
424 /** Additional flags. Not used at the moment. */
425 uint32_t fFlags;
426} VBOXCLIPBOARDFILEHDR, *PVBOXCLIPBOARDFILEHDR;
427
428typedef struct _VBOXCLIPBOARDFILEDATA
429{
430 /** Current file data chunk. */
431 void *pvData;
432 /** Size (in bytes) of current data chunk. */
433 uint32_t cbData;
434 /** Checksum for current file data chunk. */
435 void *pvChecksum;
436 /** Size (in bytes) of current data chunk. */
437 uint32_t cbChecksum;
438} VBOXCLIPBOARDFILEDATA, *PVBOXCLIPBOARDFILEDATA;
439
440typedef struct _VBOXCLIPBOARDERRORDATA
441{
442 int32_t rc;
443} VBOXCLIPBOARDERRORDATA, *PVBOXCLIPBOARDERRORDATA;
444
445bool VBoxSvcClipboardGetHeadless(void);
446bool VBoxSvcClipboardLock(void);
447void VBoxSvcClipboardUnlock(void);
448
449#ifdef VBOX_WITH_SHARED_CLIPBOARD_URI_LIST
450int VBoxSvcClipboardURIReadDataHdr(uint32_t cParms, VBOXHGCMSVCPARM paParms[], PVBOXCLIPBOARDDATAHDR pDataHdr);
451int VBoxSvcClipboardURIReadDataChunk(uint32_t cParms, VBOXHGCMSVCPARM paParms[], PVBOXCLIPBOARDDATACHUNK pDataChunk);
452int VBoxSvcClipboardURIReadDir(uint32_t cParms, VBOXHGCMSVCPARM paParms[], PVBOXCLIPBOARDDIRDATA pDirData);
453int VBoxSvcClipboardURIReadFileHdr(uint32_t cParms, VBOXHGCMSVCPARM paParms[], PVBOXCLIPBOARDFILEHDR pFileHdr);
454int VBoxSvcClipboardURIReadFileData(uint32_t cParms, VBOXHGCMSVCPARM paParms[], PVBOXCLIPBOARDFILEDATA pFileData);
455#endif
456
457#endif /* !VBOX_INCLUDED_HostServices_VBoxClipboardSvc_h */
458
Note: See TracBrowser for help on using the repository browser.

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