VirtualBox

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

Last change on this file since 79617 was 79497, 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: 46.1 KB
Line 
1/* $Id: SharedClipboard-uri.h 79497 2019-07-03 13:28:33Z 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 VBOXCLIPBOARDLISTHANDLE;
51/** Pointer to a Shared Clipboard list handle. */
52typedef VBOXCLIPBOARDLISTHANDLE *PVBOXCLIPBOARDLISTHANDLE;
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 a Shared Clipboard list header.
549 */
550typedef struct _VBOXCLIPBOARDLISTHDR
551{
552 uint32_t fList; /* IN */
553 uint32_t cbFilter; /* IN */
554 char *pszFilter; /* IN */
555 uint32_t fFeatures; /* OUT */
556 uint64_t cTotalObjects; /* OUT */
557 uint64_t cbTotalSize; /* OUT */
558 uint32_t enmCompression; /* IN / OUT */
559 uint32_t enmChecksumType; /* IN / OUT */
560} VBOXCLIPBOARDLISTHDR, *PVBOXCLIPBOARDLISTHDR;
561
562/**
563 * Structure for a Shared Clipboard list entry.
564 */
565typedef struct _VBOXCLIPBOARDLISTENTRY
566{
567 uint32_t fInfo;
568 uint32_t cbInfo;
569 void *pvInfo;
570} VBOXCLIPBOARDLISTENTRY, *PVBOXCLIPBOARDLISTENTRY;
571
572/**
573 * Structure for a Shared Clipboard object header.
574 */
575typedef struct _VBOXCLIPBOARDOBJHDR
576{
577 uint32_t enmType;
578} VBOXCLIPBOARDOBJHDR, *PVBOXCLIPBOARDOBJHDR;
579
580/**
581 * Enumeration for specifying a clipboard area object type.
582 */
583typedef enum _SHAREDCLIPBOARDAREAOBJTYPE
584{
585 /** Unknown object type; do not use. */
586 SHAREDCLIPBOARDAREAOBJTYPE_UNKNOWN = 0,
587 /** Object is a directory. */
588 SHAREDCLIPBOARDAREAOBJTYPE_DIR,
589 /** Object is a file. */
590 SHAREDCLIPBOARDAREAOBJTYPE_FILE,
591 /** The usual 32-bit hack. */
592 SHAREDCLIPBOARDAREAOBJTYPE__32Bit_Hack = 0x7fffffff
593} SHAREDCLIPBOARDAREAOBJTYPE;
594
595/** Defines a clipboard area object state. */
596typedef uint32_t SHAREDCLIPBOARDAREAOBJSTATE;
597
598/** No object state set. */
599#define SHAREDCLIPBOARDAREAOBJSTATE_NONE 0
600/** The object is considered as being complete (e.g. serialized). */
601#define SHAREDCLIPBOARDAREAOBJSTATE_COMPLETE RT_BIT(0)
602
603/**
604 * Lightweight structure to keep a clipboard area object's state.
605 *
606 * Note: We don't want to use the ClipboardURIObject class here, as this
607 * is too heavy for this purpose.
608 */
609typedef struct _SHAREDCLIPBOARDAREAOBJ
610{
611 SHAREDCLIPBOARDAREAOBJTYPE enmType;
612 SHAREDCLIPBOARDAREAOBJSTATE fState;
613} SHAREDCLIPBOARDAREAOBJ, *PSHAREDCLIPBOARDAREAOBJ;
614
615/**
616 * Class for maintaining a Shared Clipboard area
617 * on the host or guest. This will contain all received files & directories
618 * for a single Shared Clipboard operation.
619 *
620 * In case of a failed Shared Clipboard operation this class can also
621 * perform a gentle rollback if required.
622 */
623class SharedClipboardArea
624{
625public:
626
627 SharedClipboardArea(void);
628 SharedClipboardArea(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
629 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
630 virtual ~SharedClipboardArea(void);
631
632public:
633
634 uint32_t AddRef(void);
635 uint32_t Release(void);
636
637 int Lock(void);
638 int Unlock(void);
639
640 int AddObject(const char *pszPath, const SHAREDCLIPBOARDAREAOBJ &Obj);
641 int GetObject(const char *pszPath, PSHAREDCLIPBOARDAREAOBJ pObj);
642
643 int Close(void);
644 bool IsOpen(void) const;
645 int OpenEx(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
646 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
647 int OpenTemp(SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
648 SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
649 SHAREDCLIPBOARDAREAID GetID(void) const;
650 const char *GetDirAbs(void) const;
651 uint32_t GetRefCount(void);
652 int Reopen(void);
653 int Reset(bool fDeleteContent);
654 int Rollback(void);
655
656public:
657
658 static int PathConstruct(const char *pszBase, SHAREDCLIPBOARDAREAID uID, char *pszPath, size_t cbPath);
659
660protected:
661
662 int initInternal(void);
663 int destroyInternal(void);
664 int closeInternal(void);
665
666protected:
667
668 typedef std::map<RTCString, SHAREDCLIPBOARDAREAOBJ> SharedClipboardAreaFsObjMap;
669
670 /** Creation timestamp (in ms). */
671 uint64_t m_tsCreatedMs;
672 /** Number of references to this instance. */
673 volatile uint32_t m_cRefs;
674 /** Critical section for serializing access. */
675 RTCRITSECT m_CritSect;
676 /** Open flags. */
677 uint32_t m_fOpen;
678 /** Directory handle for root clipboard directory. */
679 RTDIR m_hDir;
680 /** Absolute path to root clipboard directory. */
681 RTCString m_strPathAbs;
682 /** List for holding created directories in the case of a rollback. */
683 SharedClipboardAreaFsObjMap m_mapObj;
684 /** Associated clipboard area ID. */
685 SHAREDCLIPBOARDAREAID m_uID;
686};
687
688int SharedClipboardPathSanitizeFilename(char *pszPath, size_t cbPath);
689int SharedClipboardPathSanitize(char *pszPath, size_t cbPath);
690
691/** SharedClipboardURIList flags. */
692typedef uint32_t SHAREDCLIPBOARDURILISTFLAGS;
693
694/** No flags specified. */
695#define SHAREDCLIPBOARDURILIST_FLAGS_NONE 0
696/** Keep the original paths, don't convert paths to relative ones. */
697#define SHAREDCLIPBOARDURILIST_FLAGS_ABSOLUTE_PATHS RT_BIT(0)
698/** Resolve all symlinks. */
699#define SHAREDCLIPBOARDURILIST_FLAGS_RESOLVE_SYMLINKS RT_BIT(1)
700/** Keep the files + directory entries open while
701 * being in this list. */
702#define SHAREDCLIPBOARDURILIST_FLAGS_KEEP_OPEN RT_BIT(2)
703/** Lazy loading: Only enumerate sub directories when needed.
704 ** @todo Implement lazy loading. */
705#define SHAREDCLIPBOARDURILIST_FLAGS_LAZY RT_BIT(3)
706
707/** Mask of all valid Shared Clipboard URI list flags. */
708#define SHAREDCLIPBOARDURILIST_FLAGS_VALID_MASK UINT32_C(0xF)
709
710class SharedClipboardURIList
711{
712public:
713
714 SharedClipboardURIList(void);
715 virtual ~SharedClipboardURIList(void);
716
717public:
718
719 int AppendNativePath(const char *pszPath, SHAREDCLIPBOARDURILISTFLAGS fFlags);
720 int AppendNativePathsFromList(const char *pszNativePaths, size_t cbNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
721 int AppendNativePathsFromList(const RTCList<RTCString> &lstNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
722 int AppendURIObject(SharedClipboardURIObject *pObject);
723 int AppendURIPath(const char *pszURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
724 int AppendURIPathsFromList(const char *pszURIPaths, size_t cbURIPaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
725 int AppendURIPathsFromList(const RTCList<RTCString> &lstURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
726
727 void Clear(void);
728 SharedClipboardURIObject *At(size_t i) const { return m_lstTree.at(i); }
729 SharedClipboardURIObject *First(void) const { return m_lstTree.first(); }
730 bool IsEmpty(void) const { return m_lstTree.isEmpty(); }
731 void RemoveFirst(void);
732 int SetFromURIData(const void *pvData, size_t cbData, SHAREDCLIPBOARDURILISTFLAGS fFlags);
733
734 RTCString GetRootEntries(const RTCString &strPathBase = "", const RTCString &strSeparator = "\r\n") const;
735 uint64_t GetRootCount(void) const { return m_lstRoot.size(); }
736 uint64_t GetTotalCount(void) const { return m_cTotal; }
737 uint64_t GetTotalBytes(void) const { return m_cbTotal; }
738
739protected:
740
741 int appendEntry(const char *pcszSource, const char *pcszTarget, SHAREDCLIPBOARDURILISTFLAGS fFlags);
742 int appendObject(SharedClipboardURIObject *pObject);
743 int appendPathRecursive(const char *pcszSrcPath, const char *pcszDstPath, const char *pcszDstBase, size_t cchDstBase, SHAREDCLIPBOARDURILISTFLAGS fFlags);
744
745protected:
746
747 /** List of all top-level file/directory entries.
748 * Note: All paths are kept internally as UNIX paths for
749 * easier conversion/handling! */
750 RTCList<RTCString> m_lstRoot;
751 /** List of all URI objects added. The list's content
752 * might vary depending on how the objects are being
753 * added (lazy or not). */
754 RTCList<SharedClipboardURIObject *> m_lstTree;
755 /** Total number of all URI objects. */
756 uint64_t m_cTotal;
757 /** Total size of all URI objects, that is, the file
758 * size of all objects (in bytes).
759 * Note: Do *not* size_t here, as we also want to support large files
760 * on 32-bit guests. */
761 uint64_t m_cbTotal;
762};
763
764int SharedClipboardURIListHdrAlloc(PVBOXCLIPBOARDLISTHDR *ppListHdr);
765void SharedClipboardURIListHdrFree(PVBOXCLIPBOARDLISTHDR pListHdr);
766PVBOXCLIPBOARDLISTHDR SharedClipboardURIListHdrDup(PVBOXCLIPBOARDLISTHDR pListHdr);
767int SharedClipboardURIListHdrInit(PVBOXCLIPBOARDLISTHDR pListHdr);
768void SharedClipboardURIListHdrDestroy(PVBOXCLIPBOARDLISTHDR pListHdr);
769void SharedClipboardURIListHdrFree(PVBOXCLIPBOARDLISTHDR pListHdr);
770void SharedClipboardURIListHdrReset(PVBOXCLIPBOARDLISTHDR pListHdr);
771bool SharedClipboardURIListHdrIsValid(PVBOXCLIPBOARDLISTHDR pListHdr);
772
773int SharedClipboardURIListEntryAlloc(PVBOXCLIPBOARDLISTENTRY *ppListEntry);
774void SharedClipboardURIListEntryFree(PVBOXCLIPBOARDLISTENTRY pListEntry);
775PVBOXCLIPBOARDLISTENTRY SharedClipboardURIListEntryDup(PVBOXCLIPBOARDLISTENTRY pListEntry);
776int SharedClipboardURIListEntryInit(PVBOXCLIPBOARDLISTENTRY pListEntry);
777void SharedClipboardURIListEntryDestroy(PVBOXCLIPBOARDLISTENTRY pListEntry);
778bool SharedClipboardURIListEntryIsValid(PVBOXCLIPBOARDLISTENTRY pListEntry);
779
780/**
781 * Enumeration specifying an URI transfer direction.
782 */
783typedef enum _SHAREDCLIPBOARDURITRANSFERDIR
784{
785 /** Unknown transfer directory. */
786 SHAREDCLIPBOARDURITRANSFERDIR_UNKNOWN = 0,
787 /** Read transfer (from source). */
788 SHAREDCLIPBOARDURITRANSFERDIR_READ,
789 /** Write transfer (to target). */
790 SHAREDCLIPBOARDURITRANSFERDIR_WRITE,
791 /** The usual 32-bit hack. */
792 SHAREDCLIPBOARDURITRANSFERDIR_32BIT_HACK = 0x7fffffff
793} SHAREDCLIPBOARDURITRANSFERDIR;
794
795struct _SHAREDCLIPBOARDURITRANSFER;
796typedef struct _SHAREDCLIPBOARDURITRANSFER SHAREDCLIPBOARDURITRANSFER;
797
798/**
799 * Structure for handling a single URI object context.
800 */
801typedef struct _SHAREDCLIPBOARDCLIENTURIOBJCTX
802{
803 SHAREDCLIPBOARDURITRANSFER *pTransfer;
804 SHAREDCLIPBOARDOBJHANDLE uHandle;
805 SHAREDCLIPBOARDFSOBJINFO *pObjInfo;
806 uint64_t cbProcessed;
807} SHAREDCLIPBOARDCLIENTURIOBJCTX, *PSHAREDCLIPBOARDCLIENTURIOBJCTX;
808
809/**
810 * Enumeration specifying an URI transfer status.
811 */
812typedef enum _SHAREDCLIPBOARDURITRANSFERSTATUS
813{
814 /** No status set. */
815 SHAREDCLIPBOARDURITRANSFERSTATUS_NONE = 0,
816 /** The transfer has been announced but is not running yet. */
817 SHAREDCLIPBOARDURITRANSFERSTATUS_READY,
818 /** The transfer is active and running. */
819 SHAREDCLIPBOARDURITRANSFERSTATUS_RUNNING,
820 /** The usual 32-bit hack. */
821 SHAREDCLIPBOARDURITRANSFERSTATUS_32BIT_HACK = 0x7fffffff
822} SHAREDCLIPBOARDURITRANSFERSTATUS;
823
824typedef struct _SHAREDCLIPBOARDURITRANSFERPAYLOAD
825{
826 uint32_t uID;
827 void *pvData;
828 uint32_t cbData;
829} SHAREDCLIPBOARDURITRANSFERPAYLOAD, *PSHAREDCLIPBOARDURITRANSFERPAYLOAD;
830
831typedef struct _SHAREDCLIPBOARDURITRANSFEREVENT
832{
833 RTSEMEVENT hEventSem;
834 PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload;
835} SHAREDCLIPBOARDURITRANSFEREVENT, *PSHAREDCLIPBOARDURITRANSFEREVENT;
836
837typedef enum _SHAREDCLIPBOARDURITRANSFEREVENTTYPE
838{
839 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_UNKNOWN,
840 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_HDR_READ,
841 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LIST_ENTRY_READ,
842 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_FILE_DATA_READ,
843 /** Marks the end of the event list. */
844 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_LAST,
845 /** The usual 32-bit hack. */
846 SHAREDCLIPBOARDURITRANSFEREVENTTYPE_32BIT_HACK = 0x7fffffff
847} SHAREDCLIPBOARDURITRANSFEREVENTTYPE;
848
849typedef std::map<uint32_t, SHAREDCLIPBOARDURITRANSFEREVENT *> SharedClipboardURITransferEventMap;
850
851typedef struct _SHAREDCLIPBOARDURITRANSFEREVENTS
852{
853 SharedClipboardURITransferEventMap *pMap;
854} SHAREDCLIPBOARDURITRANSFEREVENTS, *PSHAREDCLIPBOARDURITRANSFEREVENTS;
855
856/**
857 * Structure for maintaining an URI transfer state.
858 * Everything in here will be part of a saved state (later).
859 */
860typedef struct _SHAREDCLIPBOARDURITRANSFERSTATE
861{
862 /** The transfer's current status. */
863 SHAREDCLIPBOARDURITRANSFERSTATUS enmStatus;
864 /** The transfer's direction. */
865 SHAREDCLIPBOARDURITRANSFERDIR enmDir;
866 /** The transfer's source. */
867 SHAREDCLIPBOARDSOURCE enmSource;
868 /** Context of current object being handled. */
869 SHAREDCLIPBOARDCLIENTURIOBJCTX ObjCtx;
870} SHAREDCLIPBOARDURITRANSFERSTATE, *PSHAREDCLIPBOARDURITRANSFERSTATE;
871
872struct _SHAREDCLIPBOARDURITRANSFER;
873typedef struct _SHAREDCLIPBOARDURITRANSFER *PSHAREDCLIPBOARDURITRANSFER;
874
875/**
876 * Structure maintaining URI clipboard provider context data.
877 * This is handed in to the provider implementation callbacks.
878 */
879typedef struct _SHAREDCLIPBOARDPROVIDERCTX
880{
881 /** Pointer to the related URI transfer. */
882 PSHAREDCLIPBOARDURITRANSFER pTransfer;
883 /** User-defined data pointer. Can be NULL if not needed. */
884 void *pvUser;
885} SHAREDCLIPBOARDPROVIDERCTX, *PSHAREDCLIPBOARDPROVIDERCTX;
886
887/** Defines an URI clipboard provider function declaration with additional parameters. */
888#define SHAREDCLIPBOARDPROVIDERFUNCDECL(a_Name, ...) \
889 typedef DECLCALLBACK(int) RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name)(PSHAREDCLIPBOARDPROVIDERCTX, __VA_ARGS__); \
890 typedef RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDPROVIDER, a_Name);
891
892/** Defines an URI clipboard provider function declaration (no additional parameters). */
893#define SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(a_Name) \
894 typedef DECLCALLBACK(int) RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name)(PSHAREDCLIPBOARDPROVIDERCTX); \
895 typedef RT_CONCAT(FNSHAREDCLIPBOARDPROVIDER, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDPROVIDER, a_Name);
896
897/** Declares a URI clipboard provider function member. */
898#define SHAREDCLIPBOARDPROVIDERFUNCMEMBER(a_Name, a_Member) \
899 RT_CONCAT(PFNSHAREDCLIPBOARDPROVIDER, a_Name) a_Member;
900
901SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(TRANSFEROPEN)
902SHAREDCLIPBOARDPROVIDERFUNCDECLVOID(TRANSFERCLOSE)
903SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTOPEN, PVBOXCLIPBOARDLISTHDR pListHdr, PVBOXCLIPBOARDLISTHANDLE phList)
904SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTCLOSE, VBOXCLIPBOARDLISTHANDLE hList);
905SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTHDRREAD, VBOXCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTHDR pListHdr)
906SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTHDRWRITE, VBOXCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTHDR pListHdr)
907SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTENTRYREAD, VBOXCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTENTRY pEntry)
908SHAREDCLIPBOARDPROVIDERFUNCDECL(LISTENTRYWRITE, VBOXCLIPBOARDLISTHANDLE hList, PVBOXCLIPBOARDLISTENTRY pEntry)
909SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJOPEN, const char *pszPath, PVBOXCLIPBOARDCREATEPARMS pCreateParms, PSHAREDCLIPBOARDOBJHANDLE phObj)
910SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJCLOSE, SHAREDCLIPBOARDOBJHANDLE hObj)
911SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJREAD, SHAREDCLIPBOARDOBJHANDLE hObj, void *pvData, uint32_t cbData, uint32_t fFlags, uint32_t *pcbRead)
912SHAREDCLIPBOARDPROVIDERFUNCDECL(OBJWRITE, SHAREDCLIPBOARDOBJHANDLE hObj, void *pvData, uint32_t cbData, uint32_t fFlags, uint32_t *pcbWritten)
913
914/**
915 * Shared Clipboard URI provider interface table.
916 */
917typedef struct _SHAREDCLIPBOARDPROVIDERINTERFACE
918{
919 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(TRANSFEROPEN, pfnTransferOpen);
920 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(TRANSFERCLOSE, pfnTransferClose);
921 /** Optional. */
922 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTOPEN, pfnListOpen);
923 /** Optional. */
924 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTCLOSE, pfnListClose);
925 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTHDRREAD, pfnListHdrRead);
926 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTHDRWRITE, pfnListHdrWrite);
927 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTENTRYREAD, pfnListEntryRead);
928 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(LISTENTRYWRITE, pfnListEntryWrite);
929 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJOPEN, pfnObjOpen);
930 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJCLOSE, pfnObjClose);
931 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJREAD, pfnObjRead);
932 SHAREDCLIPBOARDPROVIDERFUNCMEMBER(OBJWRITE, pfnObjWrite);
933} SHAREDCLIPBOARDPROVIDERINTERFACE, *PSHAREDCLIPBOARDPROVIDERINTERFACE;
934
935/**
936 * Structure for the Shared Clipboard provider creation context.
937 */
938typedef struct _SHAREDCLIPBOARDPROVIDERCREATIONCTX
939{
940 /** Specifies what the source of the provider is. */
941 SHAREDCLIPBOARDSOURCE enmSource;
942 /** The provider interface table. */
943 SHAREDCLIPBOARDPROVIDERINTERFACE Interface;
944 /** Provider callback data. */
945 void *pvUser;
946} SHAREDCLIPBOARDPROVIDERCREATIONCTX, *PSHAREDCLIPBOARDPROVIDERCREATIONCTX;
947
948struct _SHAREDCLIPBOARDURITRANSFER;
949typedef _SHAREDCLIPBOARDURITRANSFER *PSHAREDCLIPBOARDURITRANSFER;
950
951/**
952 * Structure for storing URI transfer callback data.
953 */
954typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKDATA
955{
956 /** Pointer to related URI transfer. */
957 PSHAREDCLIPBOARDURITRANSFER pTransfer;
958 /** Saved user pointer. */
959 void *pvUser;
960} SHAREDCLIPBOARDURITRANSFERCALLBACKDATA, *PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA;
961
962#define SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(a_Name) \
963 typedef DECLCALLBACK(void) RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name)(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData); \
964 typedef RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDCALLBACK, a_Name);
965
966#define SHAREDCLIPBOARDTRANSFERCALLBACKDECL(a_Name, ...) \
967 typedef DECLCALLBACK(void) RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name)(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData, __VA_ARGS__); \
968 typedef RT_CONCAT(FNSHAREDCLIPBOARDCALLBACK, a_Name) RT_CONCAT(*PFNSHAREDCLIPBOARDCALLBACK, a_Name);
969
970#define SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(a_Name, a_Member) \
971 RT_CONCAT(PFNSHAREDCLIPBOARDCALLBACK, a_Name) a_Member;
972
973SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERPREPARE)
974SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERSTARTED)
975SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(LISTHEADERCOMPLETE)
976SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(LISTENTRYCOMPLETE)
977SHAREDCLIPBOARDTRANSFERCALLBACKDECL (TRANSFERCOMPLETE, int rc)
978SHAREDCLIPBOARDTRANSFERCALLBACKDECLVOID(TRANSFERCANCELED)
979SHAREDCLIPBOARDTRANSFERCALLBACKDECL (TRANSFERERROR, int rc)
980
981/**
982 * Structure acting as a function callback table for URI transfers.
983 * All callbacks are optional and therefore can be NULL.
984 */
985typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKS
986{
987 /** Saved user pointer. */
988 void *pvUser;
989 /** Function pointer, called when the transfer is going to be prepared. */
990 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERPREPARE, pfnTransferPrepare);
991 /** Function pointer, called when the transfer has been started. */
992 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERSTARTED, pfnTransferStarted);
993 /** Function pointer, called when reading / writing the list header is complete. */
994 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(LISTHEADERCOMPLETE, pfnListHeaderComplete);
995 /** Function pointer, called when reading / writing a list entry is complete. */
996 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(LISTENTRYCOMPLETE, pfnListEntryComplete);
997 /** Function pointer, called when the transfer is complete. */
998 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERCOMPLETE, pfnTransferComplete);
999 /** Function pointer, called when the transfer has been canceled. */
1000 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERCANCELED, pfnTransferCanceled);
1001 /** Function pointer, called when transfer resulted in an unrecoverable error. */
1002 SHAREDCLIPBOARDTRANSFERCALLBACKMEMBER(TRANSFERERROR, pfnTransferError);
1003} SHAREDCLIPBOARDURITRANSFERCALLBACKS, *PSHAREDCLIPBOARDURITRANSFERCALLBACKS;
1004
1005/**
1006 * Structure for thread-related members for a single URI transfer.
1007 */
1008typedef struct _SHAREDCLIPBOARDURITRANSFERTHREAD
1009{
1010 /** Thread handle for the reading / writing thread.
1011 * Can be NIL_RTTHREAD if not being used. */
1012 RTTHREAD hThread;
1013 /** Thread started indicator. */
1014 volatile bool fStarted;
1015 /** Thread stop flag. */
1016 volatile bool fStop;
1017 /** Thread cancelled flag / indicator. */
1018 volatile bool fCancelled;
1019} SHAREDCLIPBOARDURITRANSFERTHREAD, *PSHAREDCLIPBOARDURITRANSFERTHREAD;
1020
1021/**
1022 * Structure for maintaining a single URI transfer.
1023 *
1024 ** @todo Not yet thread safe.
1025 */
1026typedef struct _SHAREDCLIPBOARDURITRANSFER
1027{
1028 /** The node member for using this struct in a RTList. */
1029 RTLISTNODE Node;
1030 /** Critical section for serializing access. */
1031 RTCRITSECT CritSect;
1032 /** The transfer's state (for SSM, later). */
1033 SHAREDCLIPBOARDURITRANSFERSTATE State;
1034 SHAREDCLIPBOARDURITRANSFEREVENTS Events;
1035 /** The transfer's own (local) area, if any (can be NULL if not needed).
1036 * The area itself has a clipboard area ID assigned.
1037 * On the host this area ID gets shared (maintained / locked) across all VMs via VBoxSVC. */
1038 SharedClipboardArea *pArea;
1039 /** The URI list for this transfer. */
1040 SharedClipboardURIList *pURIList;
1041 SHAREDCLIPBOARDPROVIDERCTX ProviderCtx;
1042 /** The transfer's provider interface. */
1043 SHAREDCLIPBOARDPROVIDERINTERFACE ProviderIface;
1044 /** The transfer's (optional) callback table. */
1045 SHAREDCLIPBOARDURITRANSFERCALLBACKS Callbacks;
1046 /** Opaque pointer to implementation-specific parameters. */
1047 void *pvUser;
1048 /** Size (in bytes) of implementation-specific parameters. */
1049 size_t cbUser;
1050 /** Contains thread-related attributes. */
1051 SHAREDCLIPBOARDURITRANSFERTHREAD Thread;
1052} SHAREDCLIPBOARDURITRANSFER, *PSHAREDCLIPBOARDURITRANSFER;
1053
1054/**
1055 * Structure for keeping URI clipboard information around.
1056 */
1057typedef struct _SHAREDCLIPBOARDURICTX
1058{
1059 /** Critical section for serializing access. */
1060 RTCRITSECT CritSect;
1061 /** List of transfers. */
1062 RTLISTANCHOR List;
1063 /** Number of running (concurrent) transfers.
1064 * At the moment we only support only one transfer per client at a time. */
1065 uint32_t cRunning;
1066 /** Maximum Number of running (concurrent) transfers.
1067 * At the moment we only support only one transfer per client at a time. */
1068 uint32_t cMaxRunning;
1069 /** Number of total transfers (in list). */
1070 uint32_t cTransfers;
1071} SHAREDCLIPBOARDURICTX, *PSHAREDCLIPBOARDURICTX;
1072
1073int SharedClipboardURIObjCtxInit(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1074void SharedClipboardURIObjCtxDestroy(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1075bool SharedClipboardURIObjCtxIsValid(PSHAREDCLIPBOARDCLIENTURIOBJCTX pObjCtx);
1076
1077int SharedClipboardURITransferCreate(SHAREDCLIPBOARDURITRANSFERDIR enmDir, SHAREDCLIPBOARDSOURCE enmSource,
1078 PSHAREDCLIPBOARDURITRANSFER *ppTransfer);
1079int SharedClipboardURITransferDestroy(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1080
1081int SharedClipboardURITransferOpen(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1082int SharedClipboardURITransferClose(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1083
1084int SharedClipboardURITransferListOpen(PSHAREDCLIPBOARDURITRANSFER pTransfer, PVBOXCLIPBOARDLISTHDR pListHdr,
1085 PVBOXCLIPBOARDLISTHANDLE phList);
1086int SharedClipboardURITransferListClose(PSHAREDCLIPBOARDURITRANSFER pTransfer, VBOXCLIPBOARDLISTHANDLE hList);
1087int SharedClipboardURITransferListRead(PSHAREDCLIPBOARDURITRANSFER pTransfer, VBOXCLIPBOARDLISTHANDLE hList,
1088 PVBOXCLIPBOARDLISTENTRY pEntry);
1089int SharedClipboardURITransferListWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer, VBOXCLIPBOARDLISTHANDLE hList,
1090 PVBOXCLIPBOARDLISTENTRY pEntry);
1091bool SharedClipboardURITransferListHandleIsValid(PSHAREDCLIPBOARDURITRANSFER pTransfer, VBOXCLIPBOARDLISTHANDLE hList);
1092
1093int SharedClipboardURITransferPrepare(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1094int SharedClipboardURITransferProviderCreate(PSHAREDCLIPBOARDURITRANSFER pTransfer,
1095 PSHAREDCLIPBOARDPROVIDERCREATIONCTX pCreationCtx);
1096void SharedClipboardURITransferReset(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1097SharedClipboardArea *SharedClipboardURITransferGetArea(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1098PSHAREDCLIPBOARDCLIENTURIOBJCTX SharedClipboardURITransferGetCurrentObjCtx(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1099const SharedClipboardURIObject *SharedClipboardURITransferGetCurrentObject(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1100SharedClipboardURIList *SharedClipboardURITransferGetList(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1101SharedClipboardURIObject *SharedClipboardURITransferGetObject(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint64_t uIdx);
1102SHAREDCLIPBOARDSOURCE SharedClipboardURITransferGetSource(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1103SHAREDCLIPBOARDURITRANSFERSTATUS SharedClipboardURITransferGetStatus(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1104int SharedClipboardURITransferRun(PSHAREDCLIPBOARDURITRANSFER pTransfer, PFNRTTHREAD pfnThreadFunc, void *pvUser);
1105void SharedClipboardURITransferSetCallbacks(PSHAREDCLIPBOARDURITRANSFER pTransfer,
1106 PSHAREDCLIPBOARDURITRANSFERCALLBACKS pCallbacks);
1107
1108int SharedClipboardURITransferPayloadAlloc(uint32_t uID, const void *pvData, uint32_t cbData,
1109 PSHAREDCLIPBOARDURITRANSFERPAYLOAD *ppPayload);
1110void SharedClipboardURITransferPayloadFree(PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload);
1111
1112int SharedClipboardURITransferEventRegister(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID);
1113int SharedClipboardURITransferEventUnregister(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID);
1114int SharedClipboardURITransferEventWait(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID, RTMSINTERVAL uTimeoutMs,
1115 PSHAREDCLIPBOARDURITRANSFERPAYLOAD *ppPayload);
1116int SharedClipboardURITransferEventSignal(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t uID, PSHAREDCLIPBOARDURITRANSFERPAYLOAD pPayload);
1117
1118int SharedClipboardURITransferRead(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1119int SharedClipboardURITransferReadObjects(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1120
1121int SharedClipboardURITransferWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1122int SharedClipboardURITransferWriteObjects(PSHAREDCLIPBOARDURITRANSFER pTransfer);
1123
1124int SharedClipboardURICtxInit(PSHAREDCLIPBOARDURICTX pURI);
1125void SharedClipboardURICtxDestroy(PSHAREDCLIPBOARDURICTX pURI);
1126void SharedClipboardURICtxReset(PSHAREDCLIPBOARDURICTX pURI);
1127PSHAREDCLIPBOARDURITRANSFER SharedClipboardURICtxGetTransfer(PSHAREDCLIPBOARDURICTX pURI, uint32_t uIdx);
1128uint32_t SharedClipboardURICtxGetRunningTransfers(PSHAREDCLIPBOARDURICTX pURI);
1129uint32_t SharedClipboardURICtxGetTotalTransfers(PSHAREDCLIPBOARDURICTX pURI);
1130void SharedClipboardURICtxTransfersCleanup(PSHAREDCLIPBOARDURICTX pURI);
1131bool SharedClipboardURICtxTransfersMaximumReached(PSHAREDCLIPBOARDURICTX pURI);
1132int SharedClipboardURICtxTransferAdd(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
1133int SharedClipboardURICtxTransferRemove(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
1134
1135void SharedClipboardFsObjFromIPRT(PSHAREDCLIPBOARDFSOBJINFO pDst, PCRTFSOBJINFO pSrc);
1136
1137bool SharedClipboardMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
1138bool SharedClipboardMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
1139
1140#endif /* !VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h */
1141
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