VirtualBox

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

Last change on this file since 97782 was 96407, checked in by vboxsync, 2 years ago

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