VirtualBox

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

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

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