VirtualBox

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

Last change on this file since 99966 was 99966, checked in by vboxsync, 19 months ago

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