VirtualBox

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

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

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