VirtualBox

source: vbox/trunk/include/VBox/GuestHost/SharedClipboard-transfers.h@ 86949

Last change on this file since 86949 was 86949, checked in by vboxsync, 4 years ago

Shared Clipboard/Transfers: Transfer IDs are 32-bit and of type SHCLTRANSFERID. bugref:9437
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 32.0 KB
Line 
1/* $Id: SharedClipboard-transfers.h 86949 2020-11-20 18:47:46Z vboxsync $ */
2/** @file
3 * Shared Clipboard - Shared transfer functions between host and guest.
4 */
5
6/*
7 * Copyright (C) 2019-2020 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_transfers_h
28#define VBOX_INCLUDED_GuestHost_SharedClipboard_transfers_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#include <VBox/HostServices/VBoxClipboardSvc.h>
45
46
47struct SHCLTRANSFER;
48/** Pointer to a single shared clipboard transfer */
49typedef struct SHCLTRANSFER *PSHCLTRANSFER;
50
51
52/** @name Shared Clipboard transfer definitions.
53 * @{
54 */
55
56/**
57 * Defines the transfer status codes.
58 */
59typedef enum
60{
61 /** No status set. */
62 SHCLTRANSFERSTATUS_NONE = 0,
63 /** The transfer has been initialized but is not running yet. */
64 SHCLTRANSFERSTATUS_INITIALIZED,
65 /** The transfer is active and running. */
66 SHCLTRANSFERSTATUS_STARTED,
67 /** The transfer has been stopped. */
68 SHCLTRANSFERSTATUS_STOPPED,
69 /** The transfer has been canceled. */
70 SHCLTRANSFERSTATUS_CANCELED,
71 /** The transfer has been killed. */
72 SHCLTRANSFERSTATUS_KILLED,
73 /** The transfer ran into an unrecoverable error. */
74 SHCLTRANSFERSTATUS_ERROR,
75 /** The usual 32-bit hack. */
76 SHCLTRANSFERSTATUS_32BIT_SIZE_HACK = 0x7fffffff
77} SHCLTRANSFERSTATUSENUM;
78
79/** Defines a transfer status. */
80typedef uint32_t SHCLTRANSFERSTATUS;
81
82/** @} */
83
84/** @name Shared Clipboard handles.
85 * @{
86 */
87
88/** A Shared Clipboard list handle. */
89typedef uint64_t SHCLLISTHANDLE;
90/** Pointer to a Shared Clipboard list handle. */
91typedef SHCLLISTHANDLE *PSHCLLISTHANDLE;
92/** Specifies an invalid Shared Clipboard list handle.
93 * @todo r=bird: The convention is NIL_SHCLLISTHANDLE. */
94#define SHCLLISTHANDLE_INVALID ((SHCLLISTHANDLE)UINT64_MAX)
95
96/** A Shared Clipboard object handle. */
97typedef uint64_t SHCLOBJHANDLE;
98/** Pointer to a Shared Clipboard object handle. */
99typedef SHCLOBJHANDLE *PSHCLOBJHANDLE;
100/** Specifies an invalid Shared Clipboard object handle.
101 * @todo r=bird: The convention is NIL_SHCLOBJHANDLE. */
102#define SHCLOBJHANDLE_INVALID ((SHCLOBJHANDLE)UINT64_MAX)
103
104/** @} */
105
106/** @name Shared Clipboard open/create flags.
107 * @{
108 */
109/** No flags. Initialization value. */
110#define SHCL_OBJ_CF_NONE UINT32_C(0x00000000)
111
112#if 0 /* These probably won't be needed either */
113/** Lookup only the object, do not return a handle. All other flags are ignored. */
114#define SHCL_OBJ_CF_LOOKUP UINT32_C(0x00000001)
115/** Create/open a directory. */
116#define SHCL_OBJ_CF_DIRECTORY UINT32_C(0x00000004)
117#endif
118
119/** Read/write requested access for the object. */
120#define SHCL_OBJ_CF_ACCESS_MASK_RW UINT32_C(0x00001000)
121/** No access requested. */
122#define SHCL_OBJ_CF_ACCESS_NONE UINT32_C(0x00000000)
123/** Read access requested. */
124#define SHCL_OBJ_CF_ACCESS_READ UINT32_C(0x00001000)
125
126/** Requested share access for the object. */
127#define SHCL_OBJ_CF_ACCESS_MASK_DENY UINT32_C(0x00008000)
128/** Allow any access. */
129#define SHCL_OBJ_CF_ACCESS_DENYNONE UINT32_C(0x00000000)
130/** Do not allow write. */
131#define SHCL_OBJ_CF_ACCESS_DENYWRITE UINT32_C(0x00008000)
132
133/** Requested access to attributes of the object. */
134#define SHCL_OBJ_CF_ACCESS_MASK_ATTR UINT32_C(0x00010000)
135/** No access requested. */
136#define SHCL_OBJ_CF_ACCESS_ATTR_NONE UINT32_C(0x00000000)
137/** Read access requested. */
138#define SHCL_OBJ_CF_ACCESS_ATTR_READ UINT32_C(0x00010000)
139
140/** Valid bits. */
141#define SHCL_OBJ_CF_VALID_MASK UINT32_C(0x00018000)
142/** @} */
143
144/**
145 * The available additional information in a SHCLFSOBJATTR object.
146 * @sa RTFSOBJATTRADD
147 */
148typedef enum _SHCLFSOBJATTRADD
149{
150 /** No additional information is available / requested. */
151 SHCLFSOBJATTRADD_NOTHING = 1,
152 /** The additional unix attributes (SHCLFSOBJATTR::u::Unix) are
153 * available / requested. */
154 SHCLFSOBJATTRADD_UNIX,
155 /** The additional extended attribute size (SHCLFSOBJATTR::u::EASize) is
156 * available / requested. */
157 SHCLFSOBJATTRADD_EASIZE,
158 /** The last valid item (inclusive).
159 * The valid range is SHCLFSOBJATTRADD_NOTHING thru
160 * SHCLFSOBJATTRADD_LAST. */
161 SHCLFSOBJATTRADD_LAST = SHCLFSOBJATTRADD_EASIZE,
162 /** The usual 32-bit hack. */
163 SHCLFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
164} SHCLFSOBJATTRADD;
165
166
167/* Assert sizes of the IRPT types we're using below. */
168AssertCompileSize(RTFMODE, 4);
169AssertCompileSize(RTFOFF, 8);
170AssertCompileSize(RTINODE, 8);
171AssertCompileSize(RTTIMESPEC, 8);
172AssertCompileSize(RTDEV, 4);
173AssertCompileSize(RTUID, 4);
174
175/**
176 * Shared Clipboard filesystem object attributes.
177 *
178 * @sa RTFSOBJATTR
179 */
180typedef struct _SHCLFSOBJATTR
181{
182 /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*.
183 * @remarks We depend on a number of RTFS_ defines to remain unchanged.
184 * Fortuntately, these are depending on windows, dos and unix
185 * standard values, so this shouldn't be much of a pain. */
186 RTFMODE fMode;
187
188 /** The additional attributes available. */
189 SHCLFSOBJATTRADD enmAdditional;
190
191 /**
192 * Additional attributes.
193 *
194 * Unless explicitly specified to an API, the API can provide additional
195 * data as it is provided by the underlying OS.
196 */
197 union SHCLFSOBJATTRUNION
198 {
199 /** Additional Unix Attributes
200 * These are available when SHCLFSOBJATTRADD is set in fUnix.
201 */
202 struct SHCLFSOBJATTRUNIX
203 {
204 /** The user owning the filesystem object (st_uid).
205 * This field is ~0U if not supported. */
206 RTUID uid;
207
208 /** The group the filesystem object is assigned (st_gid).
209 * This field is ~0U if not supported. */
210 RTGID gid;
211
212 /** Number of hard links to this filesystem object (st_nlink).
213 * This field is 1 if the filesystem doesn't support hardlinking or
214 * the information isn't available.
215 */
216 uint32_t cHardlinks;
217
218 /** The device number of the device which this filesystem object resides on (st_dev).
219 * This field is 0 if this information is not available. */
220 RTDEV INodeIdDevice;
221
222 /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
223 * Together with INodeIdDevice, this field can be used as a OS wide unique id
224 * when both their values are not 0.
225 * This field is 0 if the information is not available. */
226 RTINODE INodeId;
227
228 /** User flags (st_flags).
229 * This field is 0 if this information is not available. */
230 uint32_t fFlags;
231
232 /** The current generation number (st_gen).
233 * This field is 0 if this information is not available. */
234 uint32_t GenerationId;
235
236 /** The device number of a character or block device type object (st_rdev).
237 * This field is 0 if the file isn't of a character or block device type and
238 * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
239 RTDEV Device;
240 } Unix;
241
242 /**
243 * Extended attribute size.
244 */
245 struct SHCLFSOBJATTREASIZE
246 {
247 /** Size of EAs. */
248 RTFOFF cb;
249 } EASize;
250
251 /** Padding the structure to a multiple of 8 bytes. */
252 uint64_t au64Padding[5];
253 } u;
254} SHCLFSOBJATTR;
255AssertCompileSize(SHCLFSOBJATTR, 48);
256/** Pointer to a Shared Clipboard filesystem object attributes structure. */
257typedef SHCLFSOBJATTR *PSHCLFSOBJATTR;
258/** Pointer to a const Shared Clipboard filesystem object attributes structure. */
259typedef const SHCLFSOBJATTR *PCSHCLFSOBJATTR;
260
261/**
262 * Shared Clipboard file system object information structure.
263 *
264 * @sa RTFSOBJINFO
265 */
266typedef struct _SHCLFSOBJINFO
267{
268 /** Logical size (st_size).
269 * For normal files this is the size of the file.
270 * For symbolic links, this is the length of the path name contained
271 * in the symbolic link.
272 * For other objects this fields needs to be specified.
273 */
274 RTFOFF cbObject;
275
276 /** Disk allocation size (st_blocks * DEV_BSIZE). */
277 RTFOFF cbAllocated;
278
279 /** Time of last access (st_atime).
280 * @remarks Here (and other places) we depend on the IPRT timespec to
281 * remain unchanged. */
282 RTTIMESPEC AccessTime;
283
284 /** Time of last data modification (st_mtime). */
285 RTTIMESPEC ModificationTime;
286
287 /** Time of last status change (st_ctime).
288 * If not available this is set to ModificationTime.
289 */
290 RTTIMESPEC ChangeTime;
291
292 /** Time of file birth (st_birthtime).
293 * If not available this is set to ChangeTime.
294 */
295 RTTIMESPEC BirthTime;
296
297 /** Attributes. */
298 SHCLFSOBJATTR Attr;
299
300} SHCLFSOBJINFO;
301AssertCompileSize(SHCLFSOBJINFO, 96);
302/** Pointer to a Shared Clipboard filesystem object information structure. */
303typedef SHCLFSOBJINFO *PSHCLFSOBJINFO;
304/** Pointer to a const Shared Clipboard filesystem object information
305 * structure. */
306typedef const SHCLFSOBJINFO *PCSHCLFSOBJINFO;
307
308/**
309 * Structure for keeping object open/create parameters.
310 */
311typedef struct _SHCLOBJOPENCREATEPARMS
312{
313 /** Path to object to open / create. */
314 char *pszPath;
315 /** Size (in bytes) of path to to object. */
316 uint32_t cbPath;
317 /** SHCL_OBJ_CF_* */
318 uint32_t fCreate;
319 /**
320 * Attributes of object to open/create and
321 * returned actual attributes of opened/created object.
322 */
323 SHCLFSOBJINFO ObjInfo;
324} SHCLOBJOPENCREATEPARMS, *PSHCLOBJOPENCREATEPARMS;
325
326/**
327 * Structure for keeping a reply message.
328 */
329typedef struct _SHCLREPLY
330{
331 /** Message type of type VBOX_SHCL_REPLYMSGTYPE_XXX. */
332 uint32_t uType;
333 /** IPRT result of overall operation. Note: int vs. uint32! */
334 uint32_t rc;
335 union
336 {
337 struct
338 {
339 SHCLTRANSFERSTATUS uStatus;
340 } TransferStatus;
341 struct
342 {
343 SHCLLISTHANDLE uHandle;
344 } ListOpen;
345 struct
346 {
347 SHCLLISTHANDLE uHandle;
348 } ListClose;
349 struct
350 {
351 SHCLOBJHANDLE uHandle;
352 } ObjOpen;
353 struct
354 {
355 SHCLOBJHANDLE uHandle;
356 } ObjClose;
357 } u;
358 /** Pointer to optional payload. */
359 void *pvPayload;
360 /** Payload size (in bytes). */
361 uint32_t cbPayload;
362} SHCLREPLY, *PSHCLREPLY;
363
364struct _SHCLLISTENTRY;
365typedef _SHCLLISTENTRY SHCLLISTENTRY;
366
367/** Defines a single root list entry. Currently the same as a regular list entry. */
368typedef SHCLLISTENTRY SHCLROOTLISTENTRY;
369/** Defines a pointer to a single root list entry. Currently the same as a regular list entry pointer. */
370typedef SHCLROOTLISTENTRY *PSHCLROOTLISTENTRY;
371
372/**
373 * Structure for keeping Shared Clipboard root list headers.
374 */
375typedef struct _SHCLROOTLISTHDR
376{
377 /** Roots listing flags; unused at the moment. */
378 uint32_t fRoots;
379 /** Number of root list entries. */
380 uint32_t cRoots;
381} SHCLROOTLISTHDR, *PSHCLROOTLISTHDR;
382
383/**
384 * Structure for maintaining a Shared Clipboard root list.
385 */
386typedef struct _SHCLROOTLIST
387{
388 /** Root list header. */
389 SHCLROOTLISTHDR Hdr;
390 /** Root list entries. */
391 SHCLROOTLISTENTRY *paEntries;
392} SHCLROOTLIST, *PSHCLROOTLIST;
393
394/**
395 * Structure for maintaining Shared Clipboard list open paramters.
396 */
397typedef struct _SHCLLISTOPENPARMS
398{
399 /** Listing flags (see VBOX_SHCL_LIST_FLAG_XXX). */
400 uint32_t fList;
401 /** Size (in bytes) of the filter string. */
402 uint32_t cbFilter;
403 /** Filter string. DOS wilcard-style. */
404 char *pszFilter;
405 /** Size (in bytes) of the listing path. */
406 uint32_t cbPath;
407 /** Listing path (absolute). If empty or NULL the listing's root path will be opened. */
408 char *pszPath;
409} SHCLLISTOPENPARMS, *PSHCLLISTOPENPARMS;
410
411/**
412 * Structure for keeping a Shared Clipboard list header.
413 */
414typedef struct _SHCLLISTHDR
415{
416 /** Feature flag(s). Not being used atm. */
417 uint32_t fFeatures;
418 /** Total objects returned. */
419 uint64_t cTotalObjects;
420 /** Total size (in bytes) returned. */
421 uint64_t cbTotalSize;
422} SHCLLISTHDR, *PSHCLLISTHDR;
423
424/**
425 * Structure for a Shared Clipboard list entry.
426 */
427typedef struct _SHCLLISTENTRY
428{
429 /** Entry name. */
430 char *pszName;
431 /** Size (in bytes) of entry name. */
432 uint32_t cbName;
433 /** Information flag(s). */
434 uint32_t fInfo;
435 /** Size (in bytes) of the actual list entry. */
436 uint32_t cbInfo;
437 /** Data of the actual list entry. */
438 void *pvInfo;
439} SHCLLISTENTRY, *PSHCLLISTENTRY;
440
441/** Maximum length (in UTF-8 characters) of a list entry name. */
442#define SHCLLISTENTRY_MAX_NAME RTPATH_MAX /** @todo Improve this to be more dynamic. */
443
444/**
445 * Structure for maintaining a Shared Clipboard list.
446 */
447typedef struct _SHCLLIST
448{
449 /** List header. */
450 SHCLLISTHDR Hdr;
451 /** List entries. */
452 SHCLROOTLISTENTRY *paEntries;
453} SHCLLIST, *PSHCLLIST;
454
455/**
456 * Structure for keeping a Shared Clipboard object data chunk.
457 */
458typedef struct _SHCLOBJDATACHUNK
459{
460 /** Handle of object this data chunk is related to. */
461 uint64_t uHandle;
462 /** Pointer to actual data chunk. */
463 void *pvData;
464 /** Size (in bytes) of data chunk. */
465 uint32_t cbData;
466} SHCLOBJDATACHUNK, *PSHCLOBJDATACHUNK;
467
468/**
469 * Structure for handling a single transfer object context.
470 */
471typedef struct _SHCLCLIENTTRANSFEROBJCTX
472{
473 SHCLTRANSFER *pTransfer;
474 SHCLOBJHANDLE uHandle;
475} SHCLCLIENTTRANSFEROBJCTX, *PSHCLCLIENTTRANSFEROBJCTX;
476
477typedef struct _SHCLTRANSFEROBJSTATE
478{
479 /** How many bytes were processed (read / write) so far. */
480 uint64_t cbProcessed;
481} SHCLTRANSFEROBJSTATE, *PSHCLTRANSFEROBJSTATE;
482
483typedef struct _SHCLTRANSFEROBJ
484{
485 SHCLOBJHANDLE uHandle;
486 char *pszPathAbs;
487 SHCLFSOBJINFO objInfo;
488 SHCLSOURCE enmSource;
489 SHCLTRANSFEROBJSTATE State;
490} SHCLTRANSFEROBJ, *PSHCLTRANSFEROBJ;
491
492/**
493 * Enumeration for specifying a Shared Clipboard object type.
494 */
495typedef enum _SHCLOBJTYPE
496{
497 /** Invalid object type. */
498 SHCLOBJTYPE_INVALID = 0,
499 /** Object is a directory. */
500 SHCLOBJTYPE_DIRECTORY,
501 /** Object is a file. */
502 SHCLOBJTYPE_FILE,
503 /** Object is a symbolic link. */
504 SHCLOBJTYPE_SYMLINK,
505 /** The usual 32-bit hack. */
506 SHCLOBJTYPE_32BIT_SIZE_HACK = 0x7fffffff
507} SHCLOBJTYPE;
508
509/**
510 * Structure for keeping transfer list handle information.
511 * This is using to map own (local) handles to the underlying file system.
512 */
513typedef struct _SHCLLISTHANDLEINFO
514{
515 /** The list node. */
516 RTLISTNODE Node;
517 /** The list's handle. */
518 SHCLLISTHANDLE hList;
519 /** Type of list handle. */
520 SHCLOBJTYPE enmType;
521 /** Absolute local path of the list object. */
522 char *pszPathLocalAbs;
523 union
524 {
525 /** Local data, based on enmType. */
526 struct
527 {
528 union
529 {
530 RTDIR hDir;
531 RTFILE hFile;
532 };
533 } Local;
534 } u;
535} SHCLLISTHANDLEINFO, *PSHCLLISTHANDLEINFO;
536
537/**
538 * Structure for keeping transfer object handle information.
539 * This is using to map own (local) handles to the underlying file system.
540 */
541typedef struct _SHCLOBJHANDLEINFO
542{
543 /** The list node. */
544 RTLISTNODE Node;
545 /** The object's handle. */
546 SHCLOBJHANDLE hObj;
547 /** Type of object handle. */
548 SHCLOBJTYPE enmType;
549 /** Absolute local path of the object. */
550 char *pszPathLocalAbs;
551 union
552 {
553 /** Local data, based on enmType. */
554 struct
555 {
556 union
557 {
558 RTDIR hDir;
559 RTFILE hFile;
560 };
561 } Local;
562 } u;
563} SHCLOBJHANDLEINFO, *PSHCLOBJHANDLEINFO;
564
565/**
566 * Structure for keeping a single root list entry.
567 */
568typedef struct _SHCLLISTROOT
569{
570 /** The list node. */
571 RTLISTNODE Node;
572 /** Absolute path of entry. */
573 char *pszPathAbs;
574} SHCLLISTROOT, *PSHCLLISTROOT;
575
576/**
577 * Structure for maintaining an Shared Clipboard transfer state.
578 * Everything in here will be part of a saved state (later).
579 */
580typedef struct _SHCLTRANSFERSTATE
581{
582 /** The transfer's (local) ID. */
583 SHCLTRANSFERID uID;
584 /** The transfer's current status. */
585 SHCLTRANSFERSTATUS enmStatus;
586 /** The transfer's direction, seen from the perspective who created the transfer. */
587 SHCLTRANSFERDIR enmDir;
588 /** The transfer's source, seen from the perspective who created the transfer. */
589 SHCLSOURCE enmSource;
590} SHCLTRANSFERSTATE, *PSHCLTRANSFERSTATE;
591
592/**
593 * Structure maintaining clipboard transfer provider context data.
594 * This is handed in to the provider implementation callbacks.
595 */
596typedef struct SHCLPROVIDERCTX
597{
598 /** Pointer to the related Shared Clipboard transfer. */
599 PSHCLTRANSFER pTransfer;
600 /** User-defined data pointer. Can be NULL if not needed. */
601 void *pvUser;
602} SHCLPROVIDERCTX, *PSHCLPROVIDERCTX;
603
604/**
605 * Shared Clipboard transfer provider interface table.
606 */
607typedef struct SHCLPROVIDERINTERFACE
608{
609 DECLCALLBACKMEMBER(int, pfnTransferOpen,(PSHCLPROVIDERCTX pCtx));
610 DECLCALLBACKMEMBER(int, pfnTransferClose,(PSHCLPROVIDERCTX pCtx));
611 DECLCALLBACKMEMBER(int, pfnRootsGet,(PSHCLPROVIDERCTX pCtx, PSHCLROOTLIST *ppRootList));
612 DECLCALLBACKMEMBER(int, pfnListOpen,(PSHCLPROVIDERCTX pCtx, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList));
613 DECLCALLBACKMEMBER(int, pfnListClose,(PSHCLPROVIDERCTX pCtx, SHCLLISTHANDLE hList));
614 DECLCALLBACKMEMBER(int, pfnListHdrRead,(PSHCLPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
615 DECLCALLBACKMEMBER(int, pfnListHdrWrite,(PSHCLPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
616 DECLCALLBACKMEMBER(int, pfnListEntryRead,(PSHCLPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry));
617 DECLCALLBACKMEMBER(int, pfnListEntryWrite,(PSHCLPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry));
618 DECLCALLBACKMEMBER(int, pfnObjOpen,(PSHCLPROVIDERCTX pCtx, PSHCLOBJOPENCREATEPARMS pCreateParms, PSHCLOBJHANDLE phObj));
619 DECLCALLBACKMEMBER(int, pfnObjClose,(PSHCLPROVIDERCTX pCtx, SHCLOBJHANDLE hObj));
620 DECLCALLBACKMEMBER(int, pfnObjRead,(PSHCLPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
621 uint32_t fFlags, uint32_t *pcbRead));
622 DECLCALLBACKMEMBER(int, pfnObjWrite,(PSHCLPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
623 uint32_t fFlags, uint32_t *pcbWritten));
624} SHCLPROVIDERINTERFACE, *PSHCLPROVIDERINTERFACE;
625
626/**
627 * Structure for the Shared Clipboard provider creation context.
628 */
629typedef struct _SHCLPROVIDERCREATIONCTX
630{
631 /** Specifies what the source of the provider is. */
632 SHCLSOURCE enmSource;
633 /** The provider interface table. */
634 SHCLPROVIDERINTERFACE Interface;
635 /** Provider callback data. */
636 void *pvUser;
637} SHCLPROVIDERCREATIONCTX, *PSHCLPROVIDERCREATIONCTX;
638
639
640/**
641 * Structure for storing Shared Clipboard transfer callback data.
642 */
643typedef struct _SHCLTRANSFERCALLBACKDATA
644{
645 /** Pointer to related Shared Clipboard transfer. */
646 PSHCLTRANSFER pTransfer;
647 /** Saved user pointer. */
648 void *pvUser;
649 /** Size (in bytes) of data at user pointer. */
650 size_t cbUser;
651} SHCLTRANSFERCALLBACKDATA, *PSHCLTRANSFERCALLBACKDATA;
652
653/**
654 * Function callback table for Shared Clipboard transfers.
655 *
656 * All callbacks are optional and therefore can be NULL.
657 */
658typedef struct SHCLTRANSFERCALLBACKS
659{
660 /** User pointer to data. Optional and can be NULL. */
661 void *pvUser;
662 /** Size (in bytes) of user data pointing at. Optional and can be 0. */
663 size_t cbUser;
664 /** Called after the transfer has been initialized. */
665 DECLCALLBACKMEMBER(int, pfnTransferInitialize,(PSHCLTRANSFERCALLBACKDATA pData));
666 /** Called before the transfer will be started. */
667 DECLCALLBACKMEMBER(int, pfnTransferStart,(PSHCLTRANSFERCALLBACKDATA pData));
668 /** Called when reading / writing the list header is complete. */
669 DECLCALLBACKMEMBER(void, pfnListHeaderComplete,(PSHCLTRANSFERCALLBACKDATA pData));
670 /** Called when reading / writing a list entry is complete. */
671 DECLCALLBACKMEMBER(void, pfnListEntryComplete,(PSHCLTRANSFERCALLBACKDATA pData));
672 /** Called when the transfer is complete. */
673 DECLCALLBACKMEMBER(void, pfnTransferComplete,(PSHCLTRANSFERCALLBACKDATA pData, int rc));
674 /** Called when the transfer has been canceled. */
675 DECLCALLBACKMEMBER(void, pfnTransferCanceled,(PSHCLTRANSFERCALLBACKDATA pData));
676 /** Called when transfer resulted in an unrecoverable error. */
677 DECLCALLBACKMEMBER(void, pfnTransferError,(PSHCLTRANSFERCALLBACKDATA pData, int rc));
678} SHCLTRANSFERCALLBACKS, *PSHCLTRANSFERCALLBACKS;
679
680/**
681 * Structure for thread-related members for a single Shared Clipboard transfer.
682 */
683typedef struct _SHCLTRANSFERTHREAD
684{
685 /** Thread handle for the reading / writing thread.
686 * Can be NIL_RTTHREAD if not being used. */
687 RTTHREAD hThread;
688 /** Thread started indicator. */
689 volatile bool fStarted;
690 /** Thread stop flag. */
691 volatile bool fStop;
692 /** Thread cancelled flag / indicator. */
693 volatile bool fCancelled;
694} SHCLTRANSFERTHREAD, *PSHCLTRANSFERTHREAD;
695
696/**
697 * A single Shared Clipboard transfer.
698 *
699 ** @todo Not yet thread safe.
700 */
701typedef struct SHCLTRANSFER
702{
703 /** The node member for using this struct in a RTList. */
704 RTLISTNODE Node;
705 /** The transfer's state (for SSM, later). */
706 SHCLTRANSFERSTATE State;
707 /** Absolute path to root entries. */
708 char *pszPathRootAbs;
709 /** Timeout (in ms) for waiting of events. Default is 30s. */
710 RTMSINTERVAL uTimeoutMs;
711 /** Maximum data chunk size (in bytes) to transfer. Default is 64K. */
712 uint32_t cbMaxChunkSize;
713 /** The transfer's own event source. */
714 SHCLEVENTSOURCE Events;
715 /** Current number of concurrent list handles. */
716 uint32_t cListHandles;
717 /** Maximum number of concurrent list handles. */
718 uint32_t cMaxListHandles;
719 /** Next upcoming list handle. */
720 SHCLLISTHANDLE uListHandleNext;
721 /** List of all list handles elated to this transfer. */
722 RTLISTANCHOR lstList;
723 /** Number of root entries in list. */
724 uint64_t cRoots;
725 /** List of root entries of this transfer. */
726 RTLISTANCHOR lstRoots;
727 /** Current number of concurrent object handles. */
728 uint32_t cObjHandles;
729 /** Maximum number of concurrent object handles. */
730 uint32_t cMaxObjHandles;
731 /** Next upcoming object handle. */
732 SHCLOBJHANDLE uObjHandleNext;
733 /** Map of all objects handles related to this transfer. */
734 RTLISTANCHOR lstObj;
735 /** The transfer's own provider context. */
736 SHCLPROVIDERCTX ProviderCtx;
737 /** The transfer's provider interface. */
738 SHCLPROVIDERINTERFACE ProviderIface;
739 /** The transfer's (optional) callback table. */
740 SHCLTRANSFERCALLBACKS Callbacks;
741 /** Opaque pointer to implementation-specific parameters. */
742 void *pvUser;
743 /** Size (in bytes) of implementation-specific parameters. */
744 size_t cbUser;
745 /** Contains thread-related attributes. */
746 SHCLTRANSFERTHREAD Thread;
747 /** Critical section for serializing access. */
748 RTCRITSECT CritSect;
749} SHCLTRANSFER, *PSHCLTRANSFER;
750
751/**
752 * Structure for keeping an Shared Clipboard transfer status report.
753 */
754typedef struct _SHCLTRANSFERREPORT
755{
756 /** Actual status to report. */
757 SHCLTRANSFERSTATUS uStatus;
758 /** Result code (rc) to report; might be unused / invalid, based on enmStatus. */
759 int rc;
760 /** Reporting flags. Currently unused and must be 0. */
761 uint32_t fFlags;
762} SHCLTRANSFERREPORT, *PSHCLTRANSFERREPORT;
763
764/**
765 * Structure for keeping Shared Clipboard transfer context around.
766 */
767typedef struct _SHCLTRANSFERCTX
768{
769 /** Critical section for serializing access. */
770 RTCRITSECT CritSect;
771 /** List of transfers. */
772 RTLISTANCHOR List;
773 /** Transfer ID allocation bitmap; clear bits are free, set bits are busy. */
774 uint64_t bmTransferIds[VBOX_SHCL_MAX_TRANSFERS / sizeof(uint64_t) / 8];
775 /** Number of running (concurrent) transfers. */
776 uint16_t cRunning;
777 /** Maximum Number of running (concurrent) transfers. */
778 uint16_t cMaxRunning;
779 /** Number of total transfers (in list). */
780 uint16_t cTransfers;
781} SHCLTRANSFERCTX, *PSHCLTRANSFERCTX;
782
783int ShClTransferObjCtxInit(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
784void ShClTransferObjCtxDestroy(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
785bool ShClTransferObjCtxIsValid(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
786
787int ShClTransferObjHandleInfoInit(PSHCLOBJHANDLEINFO pInfo);
788void ShClTransferObjHandleInfoDestroy(PSHCLOBJHANDLEINFO pInfo);
789
790int ShClTransferObjOpenParmsInit(PSHCLOBJOPENCREATEPARMS pParms);
791int ShClTransferObjOpenParmsCopy(PSHCLOBJOPENCREATEPARMS pParmsDst, PSHCLOBJOPENCREATEPARMS pParmsSrc);
792void ShClTransferObjOpenParmsDestroy(PSHCLOBJOPENCREATEPARMS pParms);
793
794int ShClTransferObjOpen(PSHCLTRANSFER pTransfer, PSHCLOBJOPENCREATEPARMS pOpenCreateParms, PSHCLOBJHANDLE phObj);
795int ShClTransferObjClose(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj);
796int ShClTransferObjRead(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead, uint32_t fFlags);
797int ShClTransferObjWrite(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten, uint32_t fFlags);
798
799PSHCLOBJDATACHUNK ShClTransferObjDataChunkDup(PSHCLOBJDATACHUNK pDataChunk);
800void ShClTransferObjDataChunkDestroy(PSHCLOBJDATACHUNK pDataChunk);
801void ShClTransferObjDataChunkFree(PSHCLOBJDATACHUNK pDataChunk);
802
803int ShClTransferCreate(PSHCLTRANSFER *ppTransfer);
804int ShClTransferDestroy(PSHCLTRANSFER pTransfer);
805
806int ShClTransferInit(PSHCLTRANSFER pTransfer, SHCLTRANSFERID uID, SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource);
807int ShClTransferOpen(PSHCLTRANSFER pTransfer);
808int ShClTransferClose(PSHCLTRANSFER pTransfer);
809
810int ShClTransferListOpen(PSHCLTRANSFER pTransfer, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList);
811int ShClTransferListClose(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
812int ShClTransferListGetHeader(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTHDR pHdr);
813PSHCLTRANSFEROBJ ShClTransferListGetObj(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, uint64_t uIdx);
814int ShClTransferListRead(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
815int ShClTransferListWrite(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
816bool ShClTransferListHandleIsValid(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
817
818int ShClPathSanitizeFilename(char *pszPath, size_t cbPath);
819int ShClPathSanitize(char *pszPath, size_t cbPath);
820
821PSHCLROOTLIST ShClTransferRootListAlloc(void);
822void ShClTransferRootListFree(PSHCLROOTLIST pRootList);
823
824PSHCLROOTLISTHDR ShClTransferRootListHdrDup(PSHCLROOTLISTHDR pRoots);
825int ShClTransferRootListHdrInit(PSHCLROOTLISTHDR pRoots);
826void ShClTransferRootListHdrDestroy(PSHCLROOTLISTHDR pRoots);
827
828int ShClTransferRootListEntryCopy(PSHCLROOTLISTENTRY pDst, PSHCLROOTLISTENTRY pSrc);
829int ShClTransferRootListEntryInit(PSHCLROOTLISTENTRY pRootListEntry);
830void ShClTransferRootListEntryDestroy(PSHCLROOTLISTENTRY pRootListEntry);
831PSHCLROOTLISTENTRY ShClTransferRootListEntryDup(PSHCLROOTLISTENTRY pRootListEntry);
832
833int ShClTransferListHandleInfoInit(PSHCLLISTHANDLEINFO pInfo);
834void ShClTransferListHandleInfoDestroy(PSHCLLISTHANDLEINFO pInfo);
835
836int ShClTransferListHdrAlloc(PSHCLLISTHDR *ppListHdr);
837void ShClTransferListHdrFree(PSHCLLISTHDR pListHdr);
838PSHCLLISTHDR ShClTransferListHdrDup(PSHCLLISTHDR pListHdr);
839int ShClTransferListHdrInit(PSHCLLISTHDR pListHdr);
840void ShClTransferListHdrDestroy(PSHCLLISTHDR pListHdr);
841void ShClTransferListHdrReset(PSHCLLISTHDR pListHdr);
842bool ShClTransferListHdrIsValid(PSHCLLISTHDR pListHdr);
843
844int ShClTransferListOpenParmsCopy(PSHCLLISTOPENPARMS pDst, PSHCLLISTOPENPARMS pSrc);
845PSHCLLISTOPENPARMS ShClTransferListOpenParmsDup(PSHCLLISTOPENPARMS pParms);
846int ShClTransferListOpenParmsInit(PSHCLLISTOPENPARMS pParms);
847void ShClTransferListOpenParmsDestroy(PSHCLLISTOPENPARMS pParms);
848
849int ShClTransferListEntryAlloc(PSHCLLISTENTRY *ppListEntry);
850void ShClTransferListEntryFree(PSHCLLISTENTRY pListEntry);
851int ShClTransferListEntryCopy(PSHCLLISTENTRY pDst, PSHCLLISTENTRY pSrc);
852PSHCLLISTENTRY ShClTransferListEntryDup(PSHCLLISTENTRY pListEntry);
853int ShClTransferListEntryInit(PSHCLLISTENTRY pListEntry);
854void ShClTransferListEntryDestroy(PSHCLLISTENTRY pListEntry);
855bool ShClTransferListEntryIsValid(PSHCLLISTENTRY pListEntry);
856
857int ShClTransferSetInterface(PSHCLTRANSFER pTransfer, PSHCLPROVIDERCREATIONCTX pCreationCtx);
858int ShClTransferRootsSet(PSHCLTRANSFER pTransfer, const char *pszRoots, size_t cbRoots);
859void ShClTransferReset(PSHCLTRANSFER pTransfer);
860
861uint32_t ShClTransferRootsCount(PSHCLTRANSFER pTransfer);
862int ShClTransferRootsEntry(PSHCLTRANSFER pTransfer, uint64_t uIndex, PSHCLROOTLISTENTRY pEntry);
863int ShClTransferRootsGet(PSHCLTRANSFER pTransfer, PSHCLROOTLIST *ppRootList);
864
865SHCLTRANSFERID ShClTransferGetID(PSHCLTRANSFER pTransfer);
866SHCLTRANSFERDIR ShClTransferGetDir(PSHCLTRANSFER pTransfer);
867SHCLSOURCE ShClTransferGetSource(PSHCLTRANSFER pTransfer);
868SHCLTRANSFERSTATUS ShClTransferGetStatus(PSHCLTRANSFER pTransfer);
869int ShClTransferRun(PSHCLTRANSFER pTransfer, PFNRTTHREAD pfnThreadFunc, void *pvUser);
870int ShClTransferStart(PSHCLTRANSFER pTransfer);
871void ShClTransferSetCallbacks(PSHCLTRANSFER pTransfer, PSHCLTRANSFERCALLBACKS pCallbacks);
872
873int ShClTransferCtxInit(PSHCLTRANSFERCTX pTransferCtx);
874void ShClTransferCtxDestroy(PSHCLTRANSFERCTX pTransferCtx);
875void ShClTransferCtxReset(PSHCLTRANSFERCTX pTransferCtx);
876PSHCLTRANSFER ShClTransferCtxGetTransfer(PSHCLTRANSFERCTX pTransferCtx, uint32_t uIdx);
877uint32_t ShClTransferCtxGetRunningTransfers(PSHCLTRANSFERCTX pTransferCtx);
878uint32_t ShClTransferCtxGetTotalTransfers(PSHCLTRANSFERCTX pTransferCtx);
879void ShClTransferCtxCleanup(PSHCLTRANSFERCTX pTransferCtx);
880bool ShClTransferCtxTransfersMaximumReached(PSHCLTRANSFERCTX pTransferCtx);
881int ShClTransferCtxTransferRegister(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERID *pidTransfer);
882int ShClTransferCtxTransferRegisterByIndex(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERID idTransfer);
883int ShClTransferCtxTransferUnregister(PSHCLTRANSFERCTX pTransferCtx, SHCLTRANSFERID idTransfer);
884
885void ShClFsObjFromIPRT(PSHCLFSOBJINFO pDst, PCRTFSOBJINFO pSrc);
886
887bool ShClMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
888bool ShClMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
889
890const char *ShClTransferStatusToStr(SHCLTRANSFERSTATUS enmStatus);
891
892#endif /* !VBOX_INCLUDED_GuestHost_SharedClipboard_transfers_h */
Note: See TracBrowser for help on using the repository browser.

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