VirtualBox

source: vbox/trunk/include/VBox/GuestHost/SharedClipboard-uri.h@ 79630

Last change on this file since 79630 was 79630, checked in by vboxsync, 6 years ago

Shared Clipboard/URI: Update.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 51.1 KB
Line 
1/* $Id: SharedClipboard-uri.h 79630 2019-07-09 08:14:01Z vboxsync $ */
2/** @file
3 * Shared Clipboard - Shared URI functions between host and guest.
4 */
5
6/*
7 * Copyright (C) 2019 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h
28#define VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h
29#ifndef RT_WITHOUT_PRAGMA_ONCE
30# pragma once
31#endif
32
33#include <map>
34
35#include <iprt/assert.h>
36#include <iprt/critsect.h>
37#include <iprt/fs.h>
38#include <iprt/list.h>
39
40#include <iprt/cpp/list.h>
41#include <iprt/cpp/ministring.h>
42
43#include <VBox/GuestHost/SharedClipboard.h>
44
45/** @name Shared Clipboard handles.
46 * @{
47 */
48
49/** A Shared Clipboard list handle. */
50typedef uint64_t SHAREDCLIPBOARDLISTHANDLE;
51/** Pointer to a Shared Clipboard list handle. */
52typedef SHAREDCLIPBOARDLISTHANDLE *PSHAREDCLIPBOARDLISTHANDLE;
53
54/** Specifies an invalid Shared Clipboard list handle. */
55#define SHAREDCLIPBOARDLISTHANDLE_INVALID 0
56
57/** A Shared Clipboard object handle. */
58typedef uint64_t SHAREDCLIPBOARDOBJHANDLE;
59/** Pointer to a Shared Clipboard object handle. */
60typedef SHAREDCLIPBOARDOBJHANDLE *PSHAREDCLIPBOARDOBJHANDLE;
61
62/** Specifies an invalid Shared Clipboard object handle. */
63#define SHAREDCLIPBOARDOBJHANDLE_INVALID 0
64
65/** @} */
66
67/** @name Shared Clipboard open/create flags.
68 * @{
69 */
70
71/** No flags. Initialization value. */
72#define SHAREDCLIPBOARD_CF_NONE (0x00000000)
73
74/** Lookup only the object, do not return a handle. All other flags are ignored. */
75#define SHAREDCLIPBOARD_CF_LOOKUP (0x00000001)
76
77/** Create/open a directory. */
78#define SHAREDCLIPBOARD_CF_DIRECTORY (0x00000004)
79
80/** Open/create action to do if object exists
81 * and if the object does not exists.
82 * REPLACE file means atomically DELETE and CREATE.
83 * OVERWRITE file means truncating the file to 0 and
84 * setting new size.
85 * When opening an existing directory REPLACE and OVERWRITE
86 * actions are considered invalid, and cause returning
87 * FILE_EXISTS with NIL handle.
88 */
89#define SHAREDCLIPBOARD_CF_ACT_MASK_IF_EXISTS (0x000000F0)
90#define SHAREDCLIPBOARD_CF_ACT_MASK_IF_NEW (0x00000F00)
91
92/** What to do if object exists. */
93#define SHAREDCLIPBOARD_CF_ACT_OPEN_IF_EXISTS (0x00000000)
94#define SHAREDCLIPBOARD_CF_ACT_FAIL_IF_EXISTS (0x00000010)
95#define SHAREDCLIPBOARD_CF_ACT_REPLACE_IF_EXISTS (0x00000020)
96#define SHAREDCLIPBOARD_CF_ACT_OVERWRITE_IF_EXISTS (0x00000030)
97
98/** What to do if object does not exist. */
99#define SHAREDCLIPBOARD_CF_ACT_CREATE_IF_NEW (0x00000000)
100#define SHAREDCLIPBOARD_CF_ACT_FAIL_IF_NEW (0x00000100)
101
102/** Read/write requested access for the object. */
103#define SHAREDCLIPBOARD_CF_ACCESS_MASK_RW (0x00003000)
104
105/** No access requested. */
106#define SHAREDCLIPBOARD_CF_ACCESS_NONE (0x00000000)
107/** Read access requested. */
108#define SHAREDCLIPBOARD_CF_ACCESS_READ (0x00001000)
109/** Write access requested. */
110#define SHAREDCLIPBOARD_CF_ACCESS_WRITE (0x00002000)
111/** Read/Write access requested. */
112#define SHAREDCLIPBOARD_CF_ACCESS_READWRITE (SHAREDCLIPBOARD_CF_ACCESS_READ | SHAREDCLIPBOARD_CF_ACCESS_WRITE)
113
114/** Requested share access for the object. */
115#define SHAREDCLIPBOARD_CF_ACCESS_MASK_DENY (0x0000C000)
116
117/** Allow any access. */
118#define SHAREDCLIPBOARD_CF_ACCESS_DENYNONE (0x00000000)
119/** Do not allow read. */
120#define SHAREDCLIPBOARD_CF_ACCESS_DENYREAD (0x00004000)
121/** Do not allow write. */
122#define SHAREDCLIPBOARD_CF_ACCESS_DENYWRITE (0x00008000)
123/** Do not allow access. */
124#define SHAREDCLIPBOARD_CF_ACCESS_DENYALL (SHAREDCLIPBOARD_CF_ACCESS_DENYREAD | SHAREDCLIPBOARD_CF_ACCESS_DENYWRITE)
125
126/** Requested access to attributes of the object. */
127#define SHAREDCLIPBOARD_CF_ACCESS_MASK_ATTR (0x00030000)
128
129/** No access requested. */
130#define SHAREDCLIPBOARD_CF_ACCESS_ATTR_NONE (0x00000000)
131/** Read access requested. */
132#define SHAREDCLIPBOARD_CF_ACCESS_ATTR_READ (0x00010000)
133/** Write access requested. */
134#define SHAREDCLIPBOARD_CF_ACCESS_ATTR_WRITE (0x00020000)
135/** Read/Write access requested. */
136#define SHAREDCLIPBOARD_CF_ACCESS_ATTR_READWRITE (SHAREDCLIPBOARD_CF_ACCESS_ATTR_READ | SHAREDCLIPBOARD_CF_ACCESS_ATTR_WRITE)
137
138/** The file is opened in append mode. Ignored if SHAREDCLIPBOARD_CF_ACCESS_WRITE is not set. */
139#define SHAREDCLIPBOARD_CF_ACCESS_APPEND (0x00040000)
140
141/** @} */
142
143/** Result of an open/create request.
144 * Along with handle value the result code
145 * identifies what has happened while
146 * trying to open the object.
147 */
148typedef enum _SHAREDCLIPBOARDCREATERESULT
149{
150 SHAREDCLIPBOARD_CREATERESULT_NONE,
151 /** Specified path does not exist. */
152 SHAREDCLIPBOARD_CREATERESULT_PATH_NOT_FOUND,
153 /** Path to file exists, but the last component does not. */
154 SHAREDCLIPBOARD_CREATERESULT_FILE_NOT_FOUND,
155 /** File already exists and either has been opened or not. */
156 SHAREDCLIPBOARD_CREATERESULT_FILE_EXISTS,
157 /** New file was created. */
158 SHAREDCLIPBOARD_CREATERESULT_FILE_CREATED,
159 /** Existing file was replaced or overwritten. */
160 SHAREDCLIPBOARD_CREATERESULT_FILE_REPLACED,
161 /** Blow the type up to 32-bit. */
162 SHAREDCLIPBOARD_CREATERESULT_32BIT_HACK = 0x7fffffff
163} SHAREDCLIPBOARDCREATERESULT;
164AssertCompile(SHAREDCLIPBOARD_CREATERESULT_NONE == 0);
165AssertCompileSize(SHAREDCLIPBOARDCREATERESULT, 4);
166
167/**
168 * The available additional information in a SHAREDCLIPBOARDFSOBJATTR object.
169 */
170typedef enum _SHAREDCLIPBOARDFSOBJATTRADD
171{
172 /** No additional information is available / requested. */
173 SHAREDCLIPBOARDFSOBJATTRADD_NOTHING = 1,
174 /** The additional unix attributes (SHAREDCLIPBOARDFSOBJATTR::u::Unix) are
175 * available / requested. */
176 SHAREDCLIPBOARDFSOBJATTRADD_UNIX,
177 /** The additional extended attribute size (SHAREDCLIPBOARDFSOBJATTR::u::EASize) is
178 * available / requested. */
179 SHAREDCLIPBOARDFSOBJATTRADD_EASIZE,
180 /** The last valid item (inclusive).
181 * The valid range is SHAREDCLIPBOARDFSOBJATTRADD_NOTHING thru
182 * SHAREDCLIPBOARDFSOBJATTRADD_LAST. */
183 SHAREDCLIPBOARDFSOBJATTRADD_LAST = SHAREDCLIPBOARDFSOBJATTRADD_EASIZE,
184
185 /** The usual 32-bit hack. */
186 SHAREDCLIPBOARDFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
187} SHAREDCLIPBOARDFSOBJATTRADD;
188
189
190/* Assert sizes of the IRPT types we're using below. */
191AssertCompileSize(RTFMODE, 4);
192AssertCompileSize(RTFOFF, 8);
193AssertCompileSize(RTINODE, 8);
194AssertCompileSize(RTTIMESPEC, 8);
195AssertCompileSize(RTDEV, 4);
196AssertCompileSize(RTUID, 4);
197
198/**
199 * Shared Clipboard filesystem object attributes.
200 */
201#pragma pack(1)
202typedef struct _SHAREDCLIPBOARDFSOBJATTR
203{
204 /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*.
205 * @remarks We depend on a number of RTFS_ defines to remain unchanged.
206 * Fortuntately, these are depending on windows, dos and unix
207 * standard values, so this shouldn't be much of a pain. */
208 RTFMODE fMode;
209
210 /** The additional attributes available. */
211 SHAREDCLIPBOARDFSOBJATTRADD enmAdditional;
212
213 /**
214 * Additional attributes.
215 *
216 * Unless explicitly specified to an API, the API can provide additional
217 * data as it is provided by the underlying OS.
218 */
219 union SHAREDCLIPBOARDFSOBJATTRUNION
220 {
221 /** Additional Unix Attributes
222 * These are available when SHAREDCLIPBOARDFSOBJATTRADD is set in fUnix.
223 */
224 struct SHAREDCLIPBOARDFSOBJATTRUNIX
225 {
226 /** The user owning the filesystem object (st_uid).
227 * This field is ~0U if not supported. */
228 RTUID uid;
229
230 /** The group the filesystem object is assigned (st_gid).
231 * This field is ~0U if not supported. */
232 RTGID gid;
233
234 /** Number of hard links to this filesystem object (st_nlink).
235 * This field is 1 if the filesystem doesn't support hardlinking or
236 * the information isn't available.
237 */
238 uint32_t cHardlinks;
239
240 /** The device number of the device which this filesystem object resides on (st_dev).
241 * This field is 0 if this information is not available. */
242 RTDEV INodeIdDevice;
243
244 /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
245 * Together with INodeIdDevice, this field can be used as a OS wide unique id
246 * when both their values are not 0.
247 * This field is 0 if the information is not available. */
248 RTINODE INodeId;
249
250 /** User flags (st_flags).
251 * This field is 0 if this information is not available. */
252 uint32_t fFlags;
253
254 /** The current generation number (st_gen).
255 * This field is 0 if this information is not available. */
256 uint32_t GenerationId;
257
258 /** The device number of a character or block device type object (st_rdev).
259 * This field is 0 if the file isn't of a character or block device type and
260 * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
261 RTDEV Device;
262 } Unix;
263
264 /**
265 * Extended attribute size.
266 */
267 struct SHAREDCLIPBOARDFSOBJATTREASIZE
268 {
269 /** Size of EAs. */
270 RTFOFF cb;
271 } EASize;
272 } u;
273} SHAREDCLIPBOARDFSOBJATTR;
274#pragma pack()
275AssertCompileSize(SHAREDCLIPBOARDFSOBJATTR, 44);
276/** Pointer to a shared folder filesystem object attributes structure. */
277typedef SHAREDCLIPBOARDFSOBJATTR *PSHAREDCLIPBOARDFSOBJATTR;
278/** Pointer to a const shared folder filesystem object attributes structure. */
279typedef const SHAREDCLIPBOARDFSOBJATTR *PCSHAREDCLIPBOARDFSOBJATTR;
280
281/**
282 * Shared Clipboard file system object information structure.
283 */
284#pragma pack(1)
285typedef struct _SHAREDCLIPBOARDFSOBJINFO
286{
287 /** Logical size (st_size).
288 * For normal files this is the size of the file.
289 * For symbolic links, this is the length of the path name contained
290 * in the symbolic link.
291 * For other objects this fields needs to be specified.
292 */
293 RTFOFF cbObject;
294
295 /** Disk allocation size (st_blocks * DEV_BSIZE). */
296 RTFOFF cbAllocated;
297
298 /** Time of last access (st_atime).
299 * @remarks Here (and other places) we depend on the IPRT timespec to
300 * remain unchanged. */
301 RTTIMESPEC AccessTime;
302
303 /** Time of last data modification (st_mtime). */
304 RTTIMESPEC ModificationTime;
305
306 /** Time of last status change (st_ctime).
307 * If not available this is set to ModificationTime.
308 */
309 RTTIMESPEC ChangeTime;
310
311 /** Time of file birth (st_birthtime).
312 * If not available this is set to ChangeTime.
313 */
314 RTTIMESPEC BirthTime;
315
316 /** Attributes. */
317 SHAREDCLIPBOARDFSOBJATTR Attr;
318
319} SHAREDCLIPBOARDFSOBJINFO;
320#pragma pack()
321AssertCompileSize(SHAREDCLIPBOARDFSOBJINFO, 92);
322/** Pointer to a shared folder filesystem object information structure. */
323typedef SHAREDCLIPBOARDFSOBJINFO *PSHAREDCLIPBOARDFSOBJINFO;
324/** Pointer to a const shared folder filesystem object information
325 * structure. */
326typedef const SHAREDCLIPBOARDFSOBJINFO *PCSHAREDCLIPBOARDFSOBJINFO;
327
328#pragma pack(1)
329typedef struct _VBOXCLIPBOARDCREATEPARMS
330{
331 /** Returned SHAREDCLIPBOARDOBJHANDLE of opened object. */
332 SHAREDCLIPBOARDOBJHANDLE uHandle;
333 /** Returned result of the operation. */
334 SHAREDCLIPBOARDCREATERESULT enmResult;
335 /** SHAREDCLIPBOARD_CF_* */
336 uint32_t fCreate;
337 /**
338 * Attributes of object to create and
339 * returned actual attributes of opened/created object.
340 */
341 SHAREDCLIPBOARDFSOBJINFO ObjInfo;
342} VBOXCLIPBOARDCREATEPARMS, *PVBOXCLIPBOARDCREATEPARMS;
343#pragma pack()
344
345/** Clipboard area ID. A valid area is >= 1.
346 * If 0 is specified, the last (most recent) area is meant.
347 * Set to UINT32_MAX if not initialized. */
348typedef uint32_t SHAREDCLIPBOARDAREAID;
349
350/** Defines a non-initialized (nil) clipboard area. */
351#define NIL_SHAREDCLIPBOARDAREAID UINT32_MAX
352
353/** SharedClipboardArea open flags. */
354typedef uint32_t SHAREDCLIPBOARDAREAOPENFLAGS;
355
356/** No clipboard area open flags specified. */
357#define SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE 0
358/** The clipboard area must not exist yet. */
359#define SHAREDCLIPBOARDAREA_OPEN_FLAGS_MUST_NOT_EXIST RT_BIT(0)
360/** Mask of all valid clipboard area open flags. */
361#define SHAREDCLIPBOARDAREA_OPEN_FLAGS_VALID_MASK 0x1
362
363/** SharedClipboardURIObject flags. */
364typedef uint32_t SHAREDCLIPBOARDURIOBJECTFLAGS;
365
366/** No flags specified. */
367#define SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE 0
368
369/** Mask of all valid Shared Clipboard URI object flags. */
370#define SHAREDCLIPBOARDURIOBJECT_FLAGS_VALID_MASK UINT32_C(0x0)
371
372/**
373 * Class for handling Shared Clipboard URI objects.
374 * This class abstracts the access and handling objects when performing Shared Clipboard actions.
375 */
376class SharedClipboardURIObject
377{
378public:
379
380 /**
381 * Enumeration for specifying an URI object type.
382 */
383 enum Type
384 {
385 /** Unknown type, do not use. */
386 Type_Unknown = 0,
387 /** Object is a file. */
388 Type_File,
389 /** Object is a directory. */
390 Type_Directory,
391 /** The usual 32-bit hack. */
392 Type_32Bit_Hack = 0x7fffffff
393 };
394
395 enum Storage
396 {
397 Storage_Unknown = 0,
398 Storage_Local,
399 Storage_Temporary,
400 /** The usual 32-bit hack. */
401 Storage_32Bit_Hack = 0x7fffffff
402 };
403
404 /**
405 * Enumeration for specifying an URI object view
406 * for representing its data accordingly.
407 */
408 enum View
409 {
410 /** Unknown view, do not use. */
411 View_Unknown = 0,
412 /** Handle data from the source point of view. */
413 View_Source,
414 /** Handle data from the destination point of view. */
415 View_Target,
416 /** The usual 32-bit hack. */
417 View_Dest_32Bit_Hack = 0x7fffffff
418 };
419
420 SharedClipboardURIObject(void);
421 SharedClipboardURIObject(Type type, const RTCString &strSrcPathAbs = "", const RTCString &strDstPathAbs = "");
422 virtual ~SharedClipboardURIObject(void);
423
424public:
425
426 /**
427 * Returns the given absolute source path of the object.
428 *
429 * @return Absolute source path of the object.
430 */
431 const RTCString &GetSourcePathAbs(void) const { return m_strSrcPathAbs; }
432
433 /**
434 * Returns the given, absolute destination path of the object.
435 *
436 * @return Absolute destination path of the object.
437 */
438 const RTCString &GetDestPathAbs(void) const { return m_strTgtPathAbs; }
439
440 RTFMODE GetMode(void) const;
441
442 uint64_t GetProcessed(void) const;
443
444 uint64_t GetSize(void) const;
445
446 /**
447 * Returns the object's type.
448 *
449 * @return The object's type.
450 */
451 Type GetType(void) const { return m_enmType; }
452
453 /**
454 * Returns the object's view.
455 *
456 * @return The object's view.
457 */
458 View GetView(void) const { return m_enmView; }
459
460public:
461
462 int SetSize(uint64_t cbSize);
463
464public:
465
466 void Close(void);
467 bool IsComplete(void) const;
468 bool IsOpen(void) const;
469 int OpenDirectory(View enmView, uint32_t fCreate = 0, RTFMODE fMode = 0);
470 int OpenDirectoryEx(const RTCString &strPathAbs, View enmView,
471 uint32_t fCreate = 0, RTFMODE fMode = 0,
472 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
473 int OpenFile(View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0);
474 int OpenFileEx(const RTCString &strPathAbs, View enmView,
475 uint64_t fOpen = 0, RTFMODE fMode = 0,
476 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
477 int QueryInfo(View enmView);
478 int Read(void *pvBuf, size_t cbBuf, uint32_t *pcbRead);
479 void Reset(void);
480 int SetDirectoryData(const RTCString &strPathAbs, View enmView, uint32_t fOpen = 0, RTFMODE fMode = 0,
481 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
482 int SetFileData(const RTCString &strPathAbs, View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0,
483 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
484 int Write(const void *pvBuf, size_t cbBuf, uint32_t *pcbWritten);
485
486public:
487
488 static int RebaseURIPath(RTCString &strPath, const RTCString &strBaseOld = "", const RTCString &strBaseNew = "");
489
490protected:
491
492 void closeInternal(void);
493 int setDirectoryDataInternal(const RTCString &strPathAbs, View enmView, uint32_t fCreate = 0, RTFMODE fMode = 0,
494 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
495 int setFileDataInternal(const RTCString &strPathAbs, View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0,
496 SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
497 int queryInfoInternal(View enmView);
498
499protected:
500
501 /** The object's type. */
502 Type m_enmType;
503 /** The object's view. */
504 View m_enmView;
505 /** Where the object is being stored to. */
506 Storage m_enmStorage;
507 /** Absolute path (base) for the source. */
508 RTCString m_strSrcPathAbs;
509 /** Absolute path (base) for the target. */
510 RTCString m_strTgtPathAbs;
511 /** Saved SHAREDCLIPBOARDURIOBJECT_FLAGS. */
512 uint32_t m_fFlags;
513 /** Requested file mode.
514 * Note: The actual file mode of an opened file will be in objInfo. */
515 RTFMODE m_fModeRequested;
516
517 /** Union containing data depending on the object's type. */
518 union
519 {
520 /** Structure containing members for objects that
521 * are files. */
522 struct
523 {
524 /** File handle. */
525 RTFILE hFile;
526 /** File system object information of this file. */
527 RTFSOBJINFO objInfo;
528 /** Requested file open flags. */
529 uint32_t fOpenRequested;
530 /** Bytes to proces for reading/writing. */
531 uint64_t cbToProcess;
532 /** Bytes processed reading/writing. */
533 uint64_t cbProcessed;
534 } File;
535 struct
536 {
537 /** Directory handle. */
538 RTDIR hDir;
539 /** File system object information of this directory. */
540 RTFSOBJINFO objInfo;
541 /** Requested directory creation flags. */
542 uint32_t fCreateRequested;
543 } Dir;
544 } u;
545};
546
547/**
548 * Structure for keeping a reply message.
549 */
550typedef struct _VBOXCLIPBOARDREPLY
551{
552 /** Message type of type VBOX_SHAREDCLIPBOARD_REPLYMSGTYPE_XXX. */
553 uint32_t uType;
554 /** IPRT result of overall operation. Note: int vs. uint32! */
555 uint32_t rc;
556 union
557 {
558 struct
559 {
560 SHAREDCLIPBOARDLISTHANDLE uHandle;
561 } ListOpen;
562 struct
563 {
564 SHAREDCLIPBOARDOBJHANDLE uHandle;
565 } ObjOpen;
566 } u;
567 /** Pointer to optional payload. */
568 void *pvPayload;
569 /** Payload size (in bytes). */
570 uint32_t cbPayload;
571} VBOXCLIPBOARDREPLY, *PVBOXCLIPBOARDREPLY;
572
573/**
574 * Structure for maintaining Shared Clipboard list open paramters.
575 */
576typedef struct _VBOXCLIPBOARDLISTOPENPARMS
577{
578 /** Listing flags (see VBOX_SHAREDCLIPBOARD_LIST_FLAG_XXX). */
579 uint32_t fList;
580 /** Size (in bytes) of the filter string. */
581 uint32_t cbFilter;
582 /** Filter string. DOS wilcard-style. */
583 char *pszFilter;
584 /** Size (in bytes) of the listing path. */
585 uint32_t cbPath;
586 /** Listing path (absolute). If empty or NULL the listing's root path will be opened. */
587 char *pszPath;
588} VBOXCLIPBOARDLISTOPENPARMS, *PVBOXCLIPBOARDLISTOPENPARMS;
589
590/**
591 * Structure for keeping a Shared Clipboard list header.
592 */
593typedef struct _VBOXCLIPBOARDLISTHDR
594{
595 /** Feature flag(s). Not being used atm. */
596 uint32_t fFeatures;
597 /** Total objects returned. */
598 uint64_t cTotalObjects;
599 /** Total size (in bytes) returned. */
600 uint64_t cbTotalSize;
601 /** Compression being method used. Not implemented yet. */
602 uint32_t enmCompression;
603 /** Checksum type being used. Not implemented yet. */
604 uint32_t enmChecksumType;
605} VBOXCLIPBOARDLISTHDR, *PVBOXCLIPBOARDLISTHDR;
606
607/**
608 * Structure for a Shared Clipboard list entry.
609 */
610typedef struct _VBOXCLIPBOARDLISTENTRY
611{
612 /** Information flag(s). */
613 uint32_t fInfo;
614 /** Size (in bytes) of the actual list entry. */
615 uint32_t cbInfo;
616 /** Data of the actual list entry. */
617 void *pvInfo;
618} VBOXCLIPBOARDLISTENTRY, *PVBOXCLIPBOARDLISTENTRY;
619
620/**
621 * Structure for a Shared Clipboard object header.
622 */
623typedef struct _VBOXCLIPBOARDOBJHDR
624{
625 /** Header type. Currently not being used. */
626 uint32_t enmType;
627} VBOXCLIPBOARDOBJHDR, *PVBOXCLIPBOARDOBJHDR;
628
629/**
630 * Enumeration for specifying a clipboard area object type.
631 */
632typedef enum _SHAREDCLIPBOARDAREAOBJTYPE
633{
634 /** Unknown object type; do not use. */
635 SHAREDCLIPBOARDAREAOBJTYPE_UNKNOWN = 0,
636 /** Object is a directory. */
637 SHAREDCLIPBOARDAREAOBJTYPE_DIR,
638 /** Object is a file. */
639 SHAREDCLIPBOARDAREAOBJTYPE_FILE,
640 /** Object is a symbolic link. */
641 SHAREDCLIPBOARDAREAOBJTYPE_SYMLINK,
642 /** The usual 32-bit hack. */
643 SHAREDCLIPBOARDAREAOBJTYPE_32Bit_Hack = 0x7fffffff
644} SHAREDCLIPBOARDAREAOBJTYPE;
645
646/** Defines a clipboard area object state. */
647typedef uint32_t SHAREDCLIPBOARDAREAOBJSTATE;
648
649/** No object state set. */
650#define SHAREDCLIPBOARDAREAOBJSTATE_NONE 0
651/** The object is considered as being complete (e.g. serialized). */
652#define SHAREDCLIPBOARDAREAOBJSTATE_COMPLETE RT_BIT(0)
653
654/**
655 * Lightweight structure to keep a clipboard area object's state.
656 *
657 * Note: We don't want to use the ClipboardURIObject class here, as this
658 * is too heavy for this purpose.
659 */
660typedef struct _SHAREDCLIPBOARDAREAOBJ
661{
662 SHAREDCLIPBOARDAREAOBJTYPE enmType;
663 SHAREDCLIPBOARDAREAOBJSTATE fState;
664} SHAREDCLIPBOARDAREAOBJ, *PSHAREDCLIPBOARDAREAOBJ;
665
666/**
667 * Class for maintaining a Shared Clipboard area
668 * on the host or guest. This will contain all received files & directories
669 * for a single Shared Clipboard operation.
670 *
671 * In case of a failed Shared Clipboard operation this class can also
672 * perform a gentle rollback if required.
673 */
674class SharedClipboardArea
675{
676public:
677
678 SharedClipboardArea(void);
679 SharedClipboardArea(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
680 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
681 virtual ~SharedClipboardArea(void);
682
683public:
684
685 uint32_t AddRef(void);
686 uint32_t Release(void);
687
688 int Lock(void);
689 int Unlock(void);
690
691 int AddObject(const char *pszPath, const SHAREDCLIPBOARDAREAOBJ &Obj);
692 int GetObject(const char *pszPath, PSHAREDCLIPBOARDAREAOBJ pObj);
693
694 int Close(void);
695 bool IsOpen(void) const;
696 int OpenEx(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
697 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
698 int OpenTemp(SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
699 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
700 SHAREDCLIPBOARDAREAID GetID(void) const;
701 const char *GetDirAbs(void) const;
702 uint32_t GetRefCount(void);
703 int Reopen(void);
704 int Reset(bool fDeleteContent);
705 int Rollback(void);
706
707public:
708
709 static int PathConstruct(const char *pszBase, SHAREDCLIPBOARDAREAID uID, char *pszPath, size_t cbPath);
710
711protected:
712
713 int initInternal(void);
714 int destroyInternal(void);
715 int closeInternal(void);
716
717protected:
718
719 typedef std::map<RTCString, SHAREDCLIPBOARDAREAOBJ> SharedClipboardAreaFsObjMap;
720
721 /** Creation timestamp (in ms). */
722 uint64_t m_tsCreatedMs;
723 /** Number of references to this instance. */
724 volatile uint32_t m_cRefs;
725 /** Critical section for serializing access. */
726 RTCRITSECT m_CritSect;
727 /** Open flags. */
728 uint32_t m_fOpen;
729 /** Directory handle for root clipboard directory. */
730 RTDIR m_hDir;
731 /** Absolute path to root clipboard directory. */
732 RTCString m_strPathAbs;
733 /** List for holding created directories in the case of a rollback. */
734 SharedClipboardAreaFsObjMap m_mapObj;
735 /** Associated clipboard area ID. */
736 SHAREDCLIPBOARDAREAID m_uID;
737};
738
739int SharedClipboardPathSanitizeFilename(char *pszPath, size_t cbPath);
740int SharedClipboardPathSanitize(char *pszPath, size_t cbPath);
741
742/** SharedClipboardURIList flags. */
743typedef uint32_t SHAREDCLIPBOARDURILISTFLAGS;
744
745/** No flags specified. */
746#define SHAREDCLIPBOARDURILIST_FLAGS_NONE 0
747/** Keep the original paths, don't convert paths to relative ones. */
748#define SHAREDCLIPBOARDURILIST_FLAGS_ABSOLUTE_PATHS RT_BIT(0)
749/** Resolve all symlinks. */
750#define SHAREDCLIPBOARDURILIST_FLAGS_RESOLVE_SYMLINKS RT_BIT(1)
751/** Keep the files + directory entries open while
752 * being in this list. */
753#define SHAREDCLIPBOARDURILIST_FLAGS_KEEP_OPEN RT_BIT(2)
754/** Lazy loading: Only enumerate sub directories when needed.
755 ** @todo Implement lazy loading. */
756#define SHAREDCLIPBOARDURILIST_FLAGS_LAZY RT_BIT(3)
757
758/** Mask of all valid Shared Clipboard URI list flags. */
759#define SHAREDCLIPBOARDURILIST_FLAGS_VALID_MASK UINT32_C(0xF)
760
761class SharedClipboardURIList
762{
763public:
764
765 SharedClipboardURIList(void);
766 virtual ~SharedClipboardURIList(void);
767
768public:
769
770 int AppendNativePath(const char *pszPath, SHAREDCLIPBOARDURILISTFLAGS fFlags);
771 int AppendNativePathsFromList(const char *pszNativePaths, size_t cbNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
772 int AppendNativePathsFromList(const RTCList<RTCString> &lstNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
773 int AppendURIObject(SharedClipboardURIObject *pObject);
774 int AppendURIPath(const char *pszURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
775 int AppendURIPathsFromList(const char *pszURIPaths, size_t cbURIPaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
776 int AppendURIPathsFromList(const RTCList<RTCString> &lstURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
777
778 void Clear(void);
779 SharedClipboardURIObject *At(size_t i) const { return m_lstTree.at(i); }
780 SharedClipboardURIObject *First(void) const { return m_lstTree.first(); }
781 bool IsEmpty(void) const { return m_lstTree.isEmpty(); }
782 void RemoveFirst(void);
783 int SetFromURIData(const void *pvData, size_t cbData, SHAREDCLIPBOARDURILISTFLAGS fFlags);
784
785 RTCString GetRootEntries(const RTCString &strPathBase = "", const RTCString &strSeparator = "\r\n") const;
786 uint64_t GetRootCount(void) const { return m_lstRoot.size(); }
787 uint64_t GetTotalCount(void) const { return m_cTotal; }
788 uint64_t GetTotalBytes(void) const { return m_cbTotal; }
789
790protected:
791
792 int appendEntry(const char *pcszSource, const char *pcszTarget, SHAREDCLIPBOARDURILISTFLAGS fFlags);
793 int appendObject(SharedClipboardURIObject *pObject);
794 int appendPathRecursive(const char *pcszSrcPath, const char *pcszDstPath, const char *pcszDstBase, size_t cchDstBase, SHAREDCLIPBOARDURILISTFLAGS fFlags);
795
796protected:
797
798 /** List of all top-level file/directory entries.
799 * Note: All paths are kept internally as UNIX paths for
800 * easier conversion/handling! */
801 RTCList<RTCString> m_lstRoot;
802 /** List of all URI objects added. The list's content
803 * might vary depending on how the objects are being
804 * added (lazy or not). */
805 RTCList<SharedClipboardURIObject *> m_lstTree;
806 /** Total number of all URI objects. */
807 uint64_t m_cTotal;
808 /** Total size of all URI objects, that is, the file
809 * size of all objects (in bytes).
810 * Note: Do *not* size_t here, as we also want to support large files
811 * on 32-bit guests. */
812 uint64_t m_cbTotal;
813};
814
815int SharedClipboardURIListHdrAlloc(PVBOXCLIPBOARDLISTHDR *ppListHdr);
816void SharedClipboardURIListHdrFree(PVBOXCLIPBOARDLISTHDR pListHdr);
817PVBOXCLIPBOARDLISTHDR SharedClipboardURIListHdrDup(PVBOXCLIPBOARDLISTHDR pListHdr);
818int SharedClipboardURIListHdrInit(PVBOXCLIPBOARDLISTHDR pListHdr);
819void SharedClipboardURIListHdrDestroy(PVBOXCLIPBOARDLISTHDR pListHdr);
820void SharedClipboardURIListHdrFree(PVBOXCLIPBOARDLISTHDR pListHdr);
821void SharedClipboardURIListHdrReset(PVBOXCLIPBOARDLISTHDR pListHdr);
822bool SharedClipboardURIListHdrIsValid(PVBOXCLIPBOARDLISTHDR pListHdr);
823
824int SharedClipboardURIListOpenParmsCopy(PVBOXCLIPBOARDLISTOPENPARMS pDst, PVBOXCLIPBOARDLISTOPENPARMS pSrc);
825PVBOXCLIPBOARDLISTOPENPARMS SharedClipboardURIListOpenParmsDup(PVBOXCLIPBOARDLISTOPENPARMS pParms);
826int SharedClipboardURIListOpenParmsInit(PVBOXCLIPBOARDLISTOPENPARMS pParms);
827void SharedClipboardURIListOpenParmsDestroy(PVBOXCLIPBOARDLISTOPENPARMS pParms);
828
829int SharedClipboardURIListEntryAlloc(PVBOXCLIPBOARDLISTENTRY *ppListEntry);
830void SharedClipboardURIListEntryFree(PVBOXCLIPBOARDLISTENTRY pListEntry);
831int SharedClipboardURIListEntryCopy(PVBOXCLIPBOARDLISTENTRY pDst, PVBOXCLIPBOARDLISTENTRY pSrc);
832PVBOXCLIPBOARDLISTENTRY SharedClipboardURIListEntryDup(PVBOXCLIPBOARDLISTENTRY pListEntry);
833int SharedClipboardURIListEntryInit(PVBOXCLIPBOARDLISTENTRY pListEntry);
834void SharedClipboardURIListEntryDestroy(PVBOXCLIPBOARDLISTENTRY pListEntry);
835bool SharedClipboardURIListEntryIsValid(PVBOXCLIPBOARDLISTENTRY pListEntry);
836
837/**
838 * Enumeration specifying an URI transfer direction.
839 */
840typedef enum _SHAREDCLIPBOARDURITRANSFERDIR
841{
842 /** Unknown transfer directory. */
843 SHAREDCLIPBOARDURITRANSFERDIR_UNKNOWN = 0,
844 /** Read transfer (from source). */
845 SHAREDCLIPBOARDURITRANSFERDIR_READ,
846 /** Write transfer (to target). */
847 SHAREDCLIPBOARDURITRANSFERDIR_WRITE,
848 /** The usual 32-bit hack. */
849 SHAREDCLIPBOARDURITRANSFERDIR_32BIT_HACK = 0x7fffffff
850} SHAREDCLIPBOARDURITRANSFERDIR;
851
852struct _SHAREDCLIPBOARDURITRANSFER;
853typedef struct _SHAREDCLIPBOARDURITRANSFER SHAREDCLIPBOARDURITRANSFER;
854
855/**
856 * Structure for handling a single URI object context.
857 */
858typedef struct _SHAREDCLIPBOARDCLIENTURIOBJCTX
859{
860 SHAREDCLIPBOARDURITRANSFER *pTransfer;
861 SHAREDCLIPBOARDOBJHANDLE uHandle;
862} SHAREDCLIPBOARDCLIENTURIOBJCTX, *PSHAREDCLIPBOARDCLIENTURIOBJCTX;
863
864typedef struct _SHAREDCLIPBOARDURITRANSFEROBJSTATE
865{
866 uint64_t cbProcessed;
867} SHAREDCLIPBOARDURITRANSFEROBJSTATE, *PSHAREDCLIPBOARDURITRANSFEROBJSTATE;
868
869typedef struct _SHAREDCLIPBOARDURITRANSFEROBJ
870{
871 SHAREDCLIPBOARDOBJHANDLE uHandle;
872 char *pszPathAbs;
873 SHAREDCLIPBOARDFSOBJINFO objInfo;
874 SHAREDCLIPBOARDSOURCE enmSource;
875 SHAREDCLIPBOARDURITRANSFEROBJSTATE State;
876} SHAREDCLIPBOARDURITRANSFEROBJ, *PSHAREDCLIPBOARDURITRANSFEROBJ;
877
878/** No status set. */
879#define SHAREDCLIPBOARDURITRANSFERSTATUS_NONE 0
880/** The transfer has been announced but is not running yet. */
881#define SHAREDCLIPBOARDURITRANSFERSTATUS_READY 1
882/** The transfer is active and running. */
883#define SHAREDCLIPBOARDURITRANSFERSTATUS_RUNNING 2
884/** The transfer has been completed. */
885#define SHAREDCLIPBOARDURITRANSFERSTATUS_COMPLETED 3
886/** The transfer has been canceled. */
887#define SHAREDCLIPBOARDURITRANSFERSTATUS_CANCELED 4
888/** The transfer ran into an unrecoverable error. */
889#define SHAREDCLIPBOARDURITRANSFERSTATUS_ERROR 5
890
891/** Defines a transfer status. */
892typedef uint32_t SHAREDCLIPBOARDURITRANSFERSTATUS;
893
894/**
895 * Structure for an (optional) URI transfer event payload.
896 */
897typedef struct _SHAREDCLIPBOARDURITRANSFERPAYLOAD
898{
899 /** Payload ID; currently unused. */
900 uint32_t uID;
901 /** Pointer to actual payload data. */
902 void *pvData;
903 /** Size (in bytes) of actual payload data. */
904 uint32_t cbData;
905} SHAREDCLIPBOARDURITRANSFERPAYLOAD, *PSHAREDCLIPBOARDURITRANSFERPAYLOAD;
906
907/**
908 * Structure for maintaining an URI transfer event.
909 */
910typedef struct _SHAREDCLIPBOARDURITRANSFEREVENT
911{
912 /** Event semaphore for signalling the event. */
913 RTSEMEVENT hEventSem;
914 /** Payload to this event. Optional and can be NULL. */
915 PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload;
916} SHAREDCLIPBOARDURITRANSFEREVENT, *PSHAREDCLIPBOARDURITRANSFEREVENT;
917
918/**
919 * Enumeration for an URI transfer event type.
920 */
921typedef enum _SHAREDCLIPBOARDURITRANSFEREVENTTYPE
922{
923 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_UNKNOWN,
924 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_OPEN,
925 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_CLOSE,
926 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_HDR_READ,
927 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_HDR_WRITE,
928 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_ENTRY_READ,
929 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_ENTRY_WRITE,
930 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_FILE_OPEN,
931 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_FILE_CLOSE,
932 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_FILE_READ,
933 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_FILE_WRITE,
934 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_ERROR,
935 /** Marks the end of the event list. */
936 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LAST,
937 /** The usual 32-bit hack. */
938 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_32BIT_HACK = 0x7fffffff
939} SHAREDCLIPBOARDURITRANSFEREVENTTYPE;
940
941/** Map of URI transfer events.
942 * The key specifies the event type of SHAREDCLIPBOARDURITRANSFEREVENTTYPE. */
943typedef std::map<uint32_t, SHAREDCLIPBOARDURITRANSFEREVENT *> SharedClipboardURITransferEventMap;
944
945typedef struct _SHAREDCLIPBOARDURILISTHANDLEINFO
946{
947 VBOXCLIPBOARDLISTOPENPARMS OpenParms;
948 RTFMODE fMode;
949 union
950 {
951 struct
952 {
953 union
954 {
955 RTDIR hDirRoot;
956 RTFILE hFile;
957 };
958 } Local;
959 } u;
960} SHAREDCLIPBOARDURILISTHANDLEINFO, *PSHAREDCLIPBOARDURILISTHANDLEINFO;
961
962typedef struct _SHAREDCLIPBOARDOBJHANDLEINFO
963{
964 union
965 {
966 struct
967 {
968 RTDIR hDirRoot;
969 } Local;
970 } u;
971} SHAREDCLIPBOARDURIOBJHANDLEINFO, *PSHAREDCLIPBOARDURIOBJHANDLEINFO;
972
973/** Map of URI list handles.
974 * The key specifies the list handle. */
975typedef std::map<SHAREDCLIPBOARDLISTHANDLE, SHAREDCLIPBOARDURILISTHANDLEINFO *> SharedClipboardURIListMap;
976
977typedef std::map<SHAREDCLIPBOARDOBJHANDLE, SHAREDCLIPBOARDURILISTHANDLEINFO *> SharedClipboardURIObjMap;
978
979/**
980 * Structure for maintaining an URI transfer state.
981 * Everything in here will be part of a saved state (later).
982 */
983typedef struct _SHAREDCLIPBOARDURITRANSFERSTATE
984{
985 /** The transfer's current status. */
986 SHAREDCLIPBOARDURITRANSFERSTATUS enmStatus;
987 /** The transfer's direction. */
988 SHAREDCLIPBOARDURITRANSFERDIR enmDir;
989 /** The transfer's source. */
990 SHAREDCLIPBOARDSOURCE enmSource;
991} SHAREDCLIPBOARDURITRANSFERSTATE, *PSHAREDCLIPBOARDURITRANSFERSTATE;
992
993struct _SHAREDCLIPBOARDURITRANSFER;
994typedef struct _SHAREDCLIPBOARDURITRANSFER *PSHAREDCLIPBOARDURITRANSFER;
995
996/**
997 * Structure maintaining URI clipboard provider context data.
998 * This is handed in to the provider implementation callbacks.
999 */
1000typedef struct _SHAREDCLIPBOARDPROVIDERCTX
1001{
1002 /** Pointer to the related URI transfer. */
1003 PSHAREDCLIPBOARDURITRANSFER pTransfer;
1004 /** User-defined data pointer. Can be NULL if not needed. */
1005 void *pvUser;
1006} SHAREDCLIPBOARDPROVIDERCTX, *PSHAREDCLIPBOARDPROVIDERCTX;
1007
1008/** Defines an URI clipboard provider function declaration with additional parameters. */
1009#define SHAREDCLIPBOARDPROVIDERFUNCDECL(a_Name, ...) \
1010 typedef DECLCALLBACK(int) RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name)(PSHAREDCLIPBOARDPROVIDERCTX, __VA_ARGS__); \
1011 typedef RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDPROVIDER, a_Name);
1012
1013/** Defines an URI clipboard provider function declaration with additional parameters. */
1014#define SHAREDCLIPBOARDPROVIDERFUNCDECLRET(a_Ret, a_Name, ...) \
1015 typedef DECLCALLBACK(a_Ret) RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name)(PSHAREDCLIPBOARDPROVIDERCTX, __VA_ARGS__); \
1016 typedef RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDPROVIDER, a_Name);
1017
1018/** Defines an URI clipboard provider function declaration (no additional parameters). */
1019#define SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(a_Name) \
1020 typedef DECLCALLBACK(int) RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name)(PSHAREDCLIPBOARDPROVIDERCTX); \
1021 typedef RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDPROVIDER, a_Name);
1022
1023/** Declares a URI clipboard provider function member. */
1024#define SHAREDCLIPBOARDPROVIDERFUNCMEMBER(a_Name, a_Member) \
1025 RT_CONCAT(PFNSHAREDCLIPBOARDPROVIDER, a_Name) a_Member;
1026
1027SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(TRANSFEROPEN)
1028SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(TRANSFERCLOSE)
1029SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTOPEN, PVBOXCLIPBOARDLISTOPENPARMS pOpenParms, PSHAREDCLIPBOARDLISTHANDLE phList)
1030SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTCLOSE, SHAREDCLIPBOARDLISTHANDLE hList);
1031SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTHDRREAD, SHAREDCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTHDR pListHdr)
1032SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTHDRWRITE, SHAREDCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTHDR pListHdr)
1033SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTENTRYREAD, SHAREDCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTENTRY pEntry)
1034SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTENTRYWRITE, SHAREDCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTENTRY pEntry)
1035SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJOPEN, const char *pszPath, PVBOXCLIPBOARDCREATEPARMS pCreateParms, PSHAREDCLIPBOARDOBJHANDLE phObj)
1036SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJCLOSE, SHAREDCLIPBOARDOBJHANDLE hObj)
1037SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJREAD, SHAREDCLIPBOARDOBJHANDLE hObj, void *pvData, uint32_t cbData, uint32_t fFlags, uint32_t *pcbRead)
1038SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJWRITE, SHAREDCLIPBOARDOBJHANDLE hObj, void *pvData, uint32_t cbData, uint32_t fFlags, uint32_t *pcbWritten)
1039SHAREDCLIPBOARDPROVIDERFUNCDECLRET(uint64_t, OBJGETSIZE, SHAREDCLIPBOARDOBJHANDLE hObj)
1040SHAREDCLIPBOARDPROVIDERFUNCDECLRET(uint64_t, OBJGETPROCESSED, SHAREDCLIPBOARDOBJHANDLE hObj)
1041SHAREDCLIPBOARDPROVIDERFUNCDECLRET(const char *, OBJGETPATH, SHAREDCLIPBOARDOBJHANDLE hObj)
1042
1043/**
1044 * Shared Clipboard URI provider interface table.
1045 */
1046typedef struct _SHAREDCLIPBOARDPROVIDERINTERFACE
1047{
1048 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(TRANSFEROPEN, pfnTransferOpen);
1049 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(TRANSFERCLOSE, pfnTransferClose);
1050 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTOPEN, pfnListOpen);
1051 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTCLOSE, pfnListClose);
1052 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTHDRREAD, pfnListHdrRead);
1053 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTHDRWRITE, pfnListHdrWrite);
1054 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTENTRYREAD, pfnListEntryRead);
1055 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTENTRYWRITE, pfnListEntryWrite);
1056 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJOPEN, pfnObjOpen);
1057 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJCLOSE, pfnObjClose);
1058 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJREAD, pfnObjRead);
1059 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJWRITE, pfnObjWrite);
1060 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJGETSIZE, pfnObjGetSize);
1061 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJGETPROCESSED, pfnObjGetProcessed);
1062 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJGETPATH, pfnObjGetPath);
1063} SHAREDCLIPBOARDPROVIDERINTERFACE, *PSHAREDCLIPBOARDPROVIDERINTERFACE;
1064
1065/**
1066 * Structure for the Shared Clipboard provider creation context.
1067 */
1068typedef struct _SHAREDCLIPBOARDPROVIDERCREATIONCTX
1069{
1070 /** Specifies what the source of the provider is. */
1071 SHAREDCLIPBOARDSOURCE enmSource;
1072 /** The provider interface table. */
1073 SHAREDCLIPBOARDPROVIDERINTERFACE Interface;
1074 /** Provider callback data. */
1075 void *pvUser;
1076} SHAREDCLIPBOARDPROVIDERCREATIONCTX, *PSHAREDCLIPBOARDPROVIDERCREATIONCTX;
1077
1078struct _SHAREDCLIPBOARDURITRANSFER;
1079typedef _SHAREDCLIPBOARDURITRANSFER *PSHAREDCLIPBOARDURITRANSFER;
1080
1081/**
1082 * Structure for storing URI transfer callback data.
1083 */
1084typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKDATA
1085{
1086 /** Pointer to related URI transfer. */
1087 PSHAREDCLIPBOARDURITRANSFER pTransfer;
1088 /** Saved user pointer. */
1089 void *pvUser;
1090} SHAREDCLIPBOARDURITRANSFERCALLBACKDATA, *PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA;
1091
1092#define SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(a_Name) \
1093 typedef DECLCALLBACK(void) RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name)(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData); \
1094 typedef RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDCALLBACK, a_Name);
1095
1096#define SHAREDCLIPBOARDTRANSFERCALLBACKDECL(a_Name, ...) \
1097 typedef DECLCALLBACK(void) RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name)(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData, __VA_ARGS__); \
1098 typedef RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDCALLBACK, a_Name);
1099
1100#define SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(a_Name, a_Member) \
1101 RT_CONCAT(PFNSHAREDCLIPBOARDCALLBACK, a_Name) a_Member;
1102
1103SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERPREPARE)
1104SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERSTARTED)
1105SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(LISTHEADERCOMPLETE)
1106SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(LISTENTRYCOMPLETE)
1107SHAREDCLIPBOARDTRANSFERCALLBACKDECL (TRANSFERCOMPLETE, int rc)
1108SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERCANCELED)
1109SHAREDCLIPBOARDTRANSFERCALLBACKDECL (TRANSFERERROR, int rc)
1110
1111/**
1112 * Structure acting as a function callback table for URI transfers.
1113 * All callbacks are optional and therefore can be NULL.
1114 */
1115typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKS
1116{
1117 /** Saved user pointer. */
1118 void *pvUser;
1119 /** Function pointer, called when the transfer is going to be prepared. */
1120 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERPREPARE, pfnTransferPrepare);
1121 /** Function pointer, called when the transfer has been started. */
1122 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERSTARTED, pfnTransferStarted);
1123 /** Function pointer, called when reading / writing the list header is complete. */
1124 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(LISTHEADERCOMPLETE, pfnListHeaderComplete);
1125 /** Function pointer, called when reading / writing a list entry is complete. */
1126 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(LISTENTRYCOMPLETE, pfnListEntryComplete);
1127 /** Function pointer, called when the transfer is complete. */
1128 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERCOMPLETE, pfnTransferComplete);
1129 /** Function pointer, called when the transfer has been canceled. */
1130 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERCANCELED, pfnTransferCanceled);
1131 /** Function pointer, called when transfer resulted in an unrecoverable error. */
1132 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERERROR, pfnTransferError);
1133} SHAREDCLIPBOARDURITRANSFERCALLBACKS, *PSHAREDCLIPBOARDURITRANSFERCALLBACKS;
1134
1135/**
1136 * Structure for thread-related members for a single URI transfer.
1137 */
1138typedef struct _SHAREDCLIPBOARDURITRANSFERTHREAD
1139{
1140 /** Thread handle for the reading / writing thread.
1141 * Can be NIL_RTTHREAD if not being used. */
1142 RTTHREAD hThread;
1143 /** Thread started indicator. */
1144 volatile bool fStarted;
1145 /** Thread stop flag. */
1146 volatile bool fStop;
1147 /** Thread cancelled flag / indicator. */
1148 volatile bool fCancelled;
1149} SHAREDCLIPBOARDURITRANSFERTHREAD, *PSHAREDCLIPBOARDURITRANSFERTHREAD;
1150
1151/**
1152 * Structure for maintaining a single URI transfer.
1153 *
1154 ** @todo Not yet thread safe.
1155 */
1156typedef struct _SHAREDCLIPBOARDURITRANSFER
1157{
1158 /** The node member for using this struct in a RTList. */
1159 RTLISTNODE Node;
1160 /** Critical section for serializing access. */
1161 RTCRITSECT CritSect;
1162 /** The transfer's state (for SSM, later). */
1163 SHAREDCLIPBOARDURITRANSFERSTATE State;
1164 /** Events related to this transfer. */
1165 SharedClipboardURITransferEventMap *pMapEvents;
1166 SharedClipboardURIListMap *pMapLists;
1167 SharedClipboardURIObjMap *pMapObj;
1168 /** The transfer's own (local) area, if any (can be NULL if not needed).
1169 * The area itself has a clipboard area ID assigned.
1170 * On the host this area ID gets shared (maintained / locked) across all VMs via VBoxSVC. */
1171 SharedClipboardArea *pArea;
1172 SHAREDCLIPBOARDPROVIDERCTX ProviderCtx;
1173 /** The transfer's provider interface. */
1174 SHAREDCLIPBOARDPROVIDERINTERFACE ProviderIface;
1175 /** The transfer's (optional) callback table. */
1176 SHAREDCLIPBOARDURITRANSFERCALLBACKS Callbacks;
1177 /** Opaque pointer to implementation-specific parameters. */
1178 void *pvUser;
1179 /** Size (in bytes) of implementation-specific parameters. */
1180 size_t cbUser;
1181 /** Contains thread-related attributes. */
1182 SHAREDCLIPBOARDURITRANSFERTHREAD Thread;
1183} SHAREDCLIPBOARDURITRANSFER, *PSHAREDCLIPBOARDURITRANSFER;
1184
1185/**
1186 * Structure for keeping URI clipboard information around.
1187 */
1188typedef struct _SHAREDCLIPBOARDURICTX
1189{
1190 /** Critical section for serializing access. */
1191 RTCRITSECT CritSect;
1192 /** List of transfers. */
1193 RTLISTANCHOR List;
1194 /** Number of running (concurrent) transfers.
1195 * At the moment we only support only one transfer per client at a time. */
1196 uint32_t cRunning;
1197 /** Maximum Number of running (concurrent) transfers.
1198 * At the moment we only support only one transfer per client at a time. */
1199 uint32_t cMaxRunning;
1200 /** Number of total transfers (in list). */
1201 uint32_t cTransfers;
1202} SHAREDCLIPBOARDURICTX, *PSHAREDCLIPBOARDURICTX;
1203
1204int SharedClipboardURIObjCtxInit(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1205void SharedClipboardURIObjCtxDestroy(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1206bool SharedClipboardURIObjCtxIsValid(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1207
1208int SharedClipboardURITransferCreate(SHAREDCLIPBOARDURITRANSFERDIR enmDir, SHAREDCLIPBOARDSOURCE enmSource,
1209 PSHAREDCLIPBOARDURITRANSFER *ppTransfer);
1210int SharedClipboardURITransferDestroy(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1211
1212int SharedClipboardURITransferOpen(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1213int SharedClipboardURITransferClose(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1214
1215int SharedClipboardURITransferListOpen(PSHAREDCLIPBOARDURITRANSFER pTransfer, PVBOXCLIPBOARDLISTOPENPARMS pOpenParms,
1216 PSHAREDCLIPBOARDLISTHANDLE phList);
1217int SharedClipboardURITransferListClose(PSHAREDCLIPBOARDURITRANSFER pTransfer, SHAREDCLIPBOARDLISTHANDLE hList);
1218int SharedClipboardURITransferListGetHeader(PSHAREDCLIPBOARDURITRANSFER pTransfer, SHAREDCLIPBOARDLISTHANDLE hList,
1219 PVBOXCLIPBOARDLISTHDR pHdr);
1220PSHAREDCLIPBOARDURITRANSFEROBJ SharedClipboardURITransferListGetObj(PSHAREDCLIPBOARDURITRANSFER pTransfer,
1221 SHAREDCLIPBOARDLISTHANDLE hList, uint64_t uIdx);
1222int SharedClipboardURITransferListRead(PSHAREDCLIPBOARDURITRANSFER pTransfer, SHAREDCLIPBOARDLISTHANDLE hList,
1223 PVBOXCLIPBOARDLISTENTRY pEntry);
1224int SharedClipboardURITransferListWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer, SHAREDCLIPBOARDLISTHANDLE hList,
1225 PVBOXCLIPBOARDLISTENTRY pEntry);
1226bool SharedClipboardURITransferListHandleIsValid(PSHAREDCLIPBOARDURITRANSFER pTransfer, SHAREDCLIPBOARDLISTHANDLE hList);
1227
1228int SharedClipboardURITransferPrepare(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1229int SharedClipboardURITransferSetInterface(PSHAREDCLIPBOARDURITRANSFER pTransfer,
1230 PSHAREDCLIPBOARDPROVIDERCREATIONCTX pCreationCtx);
1231void SharedClipboardURITransferReset(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1232SharedClipboardArea *SharedClipboardURITransferGetArea(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1233SHAREDCLIPBOARDSOURCE SharedClipboardURITransferGetSource(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1234SHAREDCLIPBOARDURITRANSFERSTATUS SharedClipboardURITransferGetStatus(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1235int SharedClipboardURITransferHandleReply(PSHAREDCLIPBOARDURITRANSFER pTransfer, PVBOXCLIPBOARDREPLY pReply);
1236int SharedClipboardURITransferRun(PSHAREDCLIPBOARDURITRANSFER pTransfer, PFNRTTHREAD pfnThreadFunc, void *pvUser);
1237void SharedClipboardURITransferSetCallbacks(PSHAREDCLIPBOARDURITRANSFER pTransfer,
1238 PSHAREDCLIPBOARDURITRANSFERCALLBACKS pCallbacks);
1239
1240int SharedClipboardURITransferPayloadAlloc(uint32_t uID, const void *pvData, uint32_t cbData,
1241 PSHAREDCLIPBOARDURITRANSFERPAYLOAD *ppPayload);
1242void SharedClipboardURITransferPayloadFree(PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload);
1243
1244int SharedClipboardURITransferEventRegister(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID);
1245int SharedClipboardURITransferEventUnregister(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID);
1246int SharedClipboardURITransferEventWait(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID, RTMSINTERVAL uTimeoutMs,
1247 PSHAREDCLIPBOARDURITRANSFERPAYLOAD *ppPayload);
1248int SharedClipboardURITransferEventSignal(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID, PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload);
1249
1250int SharedClipboardURITransferRead(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1251int SharedClipboardURITransferReadObjects(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1252
1253int SharedClipboardURITransferWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1254int SharedClipboardURITransferWriteObjects(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1255
1256int SharedClipboardURICtxInit(PSHAREDCLIPBOARDURICTX pURI);
1257void SharedClipboardURICtxDestroy(PSHAREDCLIPBOARDURICTX pURI);
1258void SharedClipboardURICtxReset(PSHAREDCLIPBOARDURICTX pURI);
1259PSHAREDCLIPBOARDURITRANSFER SharedClipboardURICtxGetTransfer(PSHAREDCLIPBOARDURICTX pURI, uint32_t uIdx);
1260uint32_t SharedClipboardURICtxGetRunningTransfers(PSHAREDCLIPBOARDURICTX pURI);
1261uint32_t SharedClipboardURICtxGetTotalTransfers(PSHAREDCLIPBOARDURICTX pURI);
1262void SharedClipboardURICtxTransfersCleanup(PSHAREDCLIPBOARDURICTX pURI);
1263bool SharedClipboardURICtxTransfersMaximumReached(PSHAREDCLIPBOARDURICTX pURI);
1264int SharedClipboardURICtxTransferAdd(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
1265int SharedClipboardURICtxTransferRemove(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
1266
1267void SharedClipboardFsObjFromIPRT(PSHAREDCLIPBOARDFSOBJINFO pDst, PCRTFSOBJINFO pSrc);
1268
1269bool SharedClipboardMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
1270bool SharedClipboardMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
1271
1272#endif /* !VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h */
1273
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