VirtualBox

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

Last change on this file since 106165 was 106061, checked in by vboxsync, 2 months ago

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