VirtualBox

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

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

Shared Clipboard: Renaming (SHCLTRANSFERSTATUS_STOPPED -> SHCLTRANSFERSTATUS_COMPLETED). bugref:9437
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 48.0 KB
Line 
1/* $Id: SharedClipboard-transfers.h 100547 2023-07-12 12:05:33Z 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 <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 char *pszPath;
349 /** Size (in bytes) of path to to object. */
350 uint32_t cbPath;
351 /** SHCL_OBJ_CF_* */
352 uint32_t fCreate;
353 /**
354 * Attributes of object to open/create and
355 * returned actual attributes of opened/created object.
356 */
357 SHCLFSOBJINFO ObjInfo;
358} SHCLOBJOPENCREATEPARMS;
359/** Pointer to Shared Clipboard object open/create parameters. */
360typedef SHCLOBJOPENCREATEPARMS *PSHCLOBJOPENCREATEPARMS;
361
362/**
363 * Structure for keeping a reply message.
364 */
365typedef struct _SHCLREPLY
366{
367 /** Message type (of type VBOX_SHCL_TX_REPLYMSGTYPE_TRANSFER_XXX). */
368 uint32_t uType;
369 /** IPRT result of overall operation. Note: int vs. uint32! */
370 uint32_t rc;
371 union
372 {
373 /** For VBOX_SHCL_TX_REPLYMSGTYPE_TRANSFER_STATUS. */
374 struct
375 {
376 SHCLTRANSFERSTATUS uStatus;
377 } TransferStatus;
378 /** For VBOX_SHCL_TX_REPLYMSGTYPE_LIST_OPEN. */
379 struct
380 {
381 SHCLLISTHANDLE uHandle;
382 } ListOpen;
383 /** For VBOX_SHCL_TX_REPLYMSGTYPE_LIST_CLOSE. */
384 struct
385 {
386 SHCLLISTHANDLE uHandle;
387 } ListClose;
388 /** For VBOX_SHCL_TX_REPLYMSGTYPE_OBJ_OPEN. */
389 struct
390 {
391 SHCLOBJHANDLE uHandle;
392 } ObjOpen;
393 /** For VBOX_SHCL_TX_REPLYMSGTYPE_OBJ_CLOSE. */
394 struct
395 {
396 SHCLOBJHANDLE uHandle;
397 } ObjClose;
398 } u;
399 /** Pointer to optional payload. */
400 void *pvPayload;
401 /** Payload size (in bytes). */
402 uint32_t cbPayload;
403} SHCLREPLY;
404/** Pointer to a Shared Clipboard reply. */
405typedef SHCLREPLY *PSHCLREPLY;
406
407struct _SHCLLISTENTRY;
408typedef _SHCLLISTENTRY SHCLLISTENTRY;
409
410/**
411 * Structure for maintaining Shared Clipboard list open parameters.
412 */
413typedef struct _SHCLLISTOPENPARMS
414{
415 /** Listing flags (see VBOX_SHCL_LIST_FLAG_XXX). */
416 uint32_t fList;
417 /** Size (in bytes) of the filter string. */
418 uint32_t cbFilter;
419 /** Filter string. DOS wilcard-style. */
420 char *pszFilter;
421 /** Size (in bytes) of the listing path. */
422 uint32_t cbPath;
423 /** Listing path (absolute). If empty or NULL the listing's root path will be opened. */
424 char *pszPath;
425} SHCLLISTOPENPARMS;
426/** Pointer to Shared Clipboard list open parameters. */
427typedef SHCLLISTOPENPARMS *PSHCLLISTOPENPARMS;
428
429/**
430 * Structure for keeping a Shared Clipboard list header.
431 */
432typedef struct _SHCLLISTHDR
433{
434 /** Feature flag(s) of type SHCL_TRANSFER_LIST_FEATURE_F_XXX. */
435 uint32_t fFeatures;
436 /** Total entries of the list. */
437 uint64_t cEntries;
438 /** Total size (in bytes) returned. */
439 uint64_t cbTotalSize;
440} SHCLLISTHDR;
441/** Pointer to a Shared Clipboard list header. */
442typedef SHCLLISTHDR *PSHCLLISTHDR;
443
444/**
445 * Structure for a generic Shared Clipboard list entry.
446 */
447typedef struct _SHCLLISTENTRY
448{
449 /** List node. */
450 RTLISTNODE Node;
451 /** Entry name. */
452 char *pszName;
453 /** Size (in bytes) of entry name.
454 * Includes terminator. */
455 uint32_t cbName;
456 /** Information flag(s). Of type VBOX_SHCL_INFO_F_XXX. */
457 uint32_t fInfo;
458 /** Size (in bytes) of the actual list entry. */
459 uint32_t cbInfo;
460 /** Data of the actual list entry. */
461 void *pvInfo;
462} SHCLLISTENTRY;
463/** Pointer to a Shared Clipboard list entry. */
464typedef SHCLLISTENTRY *PSHCLLISTENTRY;
465/** Pointer to a const Shared Clipboard list entry. */
466typedef SHCLLISTENTRY *PCSHCLLISTENTRY;
467
468/** Maximum length (in UTF-8 characters) of a list entry name. Includes terminator. */
469#define SHCLLISTENTRY_MAX_NAME 1024
470
471/**
472 * Structure for a generic Shared Clipboard list.
473 */
474typedef struct _SHCLLIST
475{
476 /** List header. */
477 SHCLLISTHDR Hdr;
478 /** List entries of type PSHCLLISTENTRY. */
479 RTLISTANCHOR lstEntries;
480} SHCLLIST;
481/** Pointer to a generic Shared Clipboard transfer transfer list. */
482typedef SHCLLIST *PSHCLLIST;
483
484/**
485 * Structure for keeping a Shared Clipboard object data chunk.
486 */
487typedef struct _SHCLOBJDATACHUNK
488{
489 /** Handle of object this data chunk is related to. */
490 uint64_t uHandle;
491 /** Pointer to actual data chunk. */
492 void *pvData;
493 /** Size (in bytes) of data chunk. */
494 uint32_t cbData;
495} SHCLOBJDATACHUNK;
496/** Pointer to a Shared Clipboard transfer object data chunk. */
497typedef SHCLOBJDATACHUNK *PSHCLOBJDATACHUNK;
498
499/**
500 * Structure for handling a single transfer object context.
501 */
502typedef struct _SHCLCLIENTTRANSFEROBJCTX
503{
504 /** Pointer to the actual transfer object of this context. */
505 SHCLTRANSFER *pTransfer;
506 /** Object handle of this transfer context. */
507 SHCLOBJHANDLE uHandle;
508} SHCLCLIENTTRANSFEROBJCTX;
509/** Pointer to a Shared Clipboard transfer object context. */
510typedef SHCLCLIENTTRANSFEROBJCTX *PSHCLCLIENTTRANSFEROBJCTX;
511
512typedef struct _SHCLTRANSFEROBJSTATE
513{
514 /** How many bytes were processed (read / write) so far. */
515 uint64_t cbProcessed;
516} SHCLTRANSFEROBJSTATE;
517/** Pointer to a Shared Clipboard transfer object state. */
518typedef SHCLTRANSFEROBJSTATE *PSHCLTRANSFEROBJSTATE;
519
520/**
521 * Enumeration for specifying a Shared Clipboard object type.
522 */
523typedef enum _SHCLOBJTYPE
524{
525 /** Invalid object type. */
526 SHCLOBJTYPE_INVALID = 0,
527 /** Object is a directory. */
528 SHCLOBJTYPE_DIRECTORY,
529 /** Object is a file. */
530 SHCLOBJTYPE_FILE,
531 /** Object is a symbolic link. */
532 SHCLOBJTYPE_SYMLINK,
533 /** The usual 32-bit hack. */
534 SHCLOBJTYPE_32BIT_SIZE_HACK = 0x7fffffff
535} SHCLOBJTYPE;
536
537/**
538 * Structure for a single Shared Clipboard transfer object.
539 */
540typedef struct _SHCLTRANSFEROBJ
541{
542 /** The list node. */
543 RTLISTNODE Node;
544 /** Handle of the object. */
545 SHCLOBJHANDLE hObj;
546 /** Absolute (local) path of the object. Source-style path. */
547 char *pszPathLocalAbs;
548 /** Object file system information. */
549 SHCLFSOBJINFO objInfo;
550 /** Source the object originates from. */
551 SHCLSOURCE enmSource;
552 /** Current state. */
553 SHCLTRANSFEROBJSTATE State;
554 /** Type of object handle. */
555 SHCLOBJTYPE enmType;
556 /** Data union, based on \a enmType. */
557 union
558 {
559 /** Local data. */
560 struct
561 {
562 union
563 {
564 RTDIR hDir;
565 RTFILE hFile;
566 };
567 } Local;
568 } u;
569} SHCLTRANSFEROBJ;
570/** Pointer to a Shared Clipboard transfer object. */
571typedef SHCLTRANSFEROBJ *PSHCLTRANSFEROBJ;
572
573/**
574 * Structure for keeping transfer list handle information.
575 *
576 * This is using to map own (local) handles to the underlying file system.
577 */
578typedef struct _SHCLLISTHANDLEINFO
579{
580 /** The list node. */
581 RTLISTNODE Node;
582 /** The list's handle. */
583 SHCLLISTHANDLE hList;
584 /** Type of list handle. */
585 SHCLOBJTYPE enmType;
586 /** Absolute local path of the list object. */
587 char *pszPathLocalAbs;
588 union
589 {
590 /** Local data, based on enmType. */
591 struct
592 {
593 union
594 {
595 RTDIR hDir;
596 RTFILE hFile;
597 };
598 } Local;
599 } u;
600} SHCLLISTHANDLEINFO;
601/** Pointer to a Shared Clipboard transfer list handle info. */
602typedef SHCLLISTHANDLEINFO *PSHCLLISTHANDLEINFO;
603
604/**
605 * Structure for maintaining an Shared Clipboard transfer state.
606 * Everything in here will be part of a saved state (later).
607 */
608typedef struct _SHCLTRANSFERSTATE
609{
610 /** The transfer's (local) ID. */
611 SHCLTRANSFERID uID;
612 /** The transfer's current status. */
613 SHCLTRANSFERSTATUS enmStatus;
614 /** The transfer's direction, seen from the perspective who created the transfer. */
615 SHCLTRANSFERDIR enmDir;
616 /** The transfer's source, seen from the perspective who created the transfer. */
617 SHCLSOURCE enmSource;
618} SHCLTRANSFERSTATE;
619/** Pointer to a Shared Clipboard transfer state. */
620typedef SHCLTRANSFERSTATE *PSHCLTRANSFERSTATE;
621
622/**
623 * Structure maintaining clipboard transfer provider context data.
624 *
625 * This is handed-in to the provider interface implementations.
626 */
627typedef struct _SHCLTXPROVIDERCTX
628{
629 /** Pointer to the related Shared Clipboard transfer. */
630 PSHCLTRANSFER pTransfer;
631 /** User-defined data pointer. Can be NULL if not needed. */
632 void *pvUser;
633 /** Size (in bytes) of data at user pointer. */
634 size_t cbUser;
635} SHCLTXPROVIDERCTX;
636/** Pointer to Shared Clipboard transfer provider context data. */
637typedef SHCLTXPROVIDERCTX *PSHCLTXPROVIDERCTX;
638
639struct _SHCLTRANSFERCTX;
640typedef struct _SHCLTRANSFERCTX *PSHCLTRANSFERCTX;
641
642/**
643 * Shared Clipboard transfer provider interface table.
644 *
645 * A transfer provider inteface implementation realizes all low level functions
646 * needed for making a Shared Clipboard transfer happen.
647 */
648typedef struct _SHCLTXPROVIDERIFACE
649{
650 /**
651 * Reads the clipboard transfer root list.
652 *
653 * Depending on the provider, this queries information for the root entries.
654 *
655 * @returns VBox status code.
656 * @param pCtx Provider context to use.
657 */
658 DECLCALLBACKMEMBER(int, pfnRootListRead,(PSHCLTXPROVIDERCTX pCtx));
659 /**
660 * Opens a transfer list.
661 *
662 * @returns VBox status code.
663 * @param pCtx Provider context to use.
664 * @param pOpenParms List open parameters to use for opening.
665 * @param phList Where to store the List handle of opened list on success.
666 */
667 DECLCALLBACKMEMBER(int, pfnListOpen,(PSHCLTXPROVIDERCTX pCtx, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList));
668 /**
669 * Closes a transfer list.
670 *
671 * @returns VBox status code.
672 * @param pCtx Provider context to use.
673 * @param hList Handle of list to close.
674 */
675 DECLCALLBACKMEMBER(int, pfnListClose,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList));
676 /**
677 * Reads the list header.
678 *
679 * @returns VBox status code.
680 * @param pCtx Provider context to use.
681 * @param hList List handle of list to read header for.
682 * @param pListHdr Where to store the list header read.
683 */
684 DECLCALLBACKMEMBER(int, pfnListHdrRead,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
685 /**
686 * Writes the list header.
687 *
688 * @returns VBox status code.
689 * @param pCtx Provider context to use.
690 * @param hList List handle of list to write header for.
691 * @param pListHdr List header to write.
692 */
693 DECLCALLBACKMEMBER(int, pfnListHdrWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
694 /**
695 * Reads a single transfer list entry.
696 *
697 * @returns VBox status code or VERR_NO_MORE_FILES if the end of the list has been reached.
698 * @param pCtx Provider context to use.
699 * @param hList List handle of list to read from.
700 * @param pListEntry Where to store the read information.
701 */
702 DECLCALLBACKMEMBER(int, pfnListEntryRead,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pListEntry));
703 /**
704 * Writes a single transfer list entry.
705 *
706 * @returns VBox status code.
707 * @param pCtx Provider context to use.
708 * @param hList List handle of list to write to.
709 * @param pListEntry Entry information to write.
710 */
711 DECLCALLBACKMEMBER(int, pfnListEntryWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pListEntry));
712 /**
713 * Opens a transfer object.
714 *
715 * @returns VBox status code.
716 * @param pCtx Provider context to use.
717 * @param pCreateParms Open / create parameters of transfer object to open / create.
718 * @param phObj Where to store the handle of transfer object opened on success.
719 */
720 DECLCALLBACKMEMBER(int, pfnObjOpen,(PSHCLTXPROVIDERCTX pCtx, PSHCLOBJOPENCREATEPARMS pCreateParms, PSHCLOBJHANDLE phObj));
721 /**
722 * Closes a transfer object.
723 *
724 * @returns VBox status code.
725 * @param pCtx Provider context to use.
726 * @param hObj Handle of transfer object to close.
727 */
728 DECLCALLBACKMEMBER(int, pfnObjClose,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj));
729 /**
730 * Reads from a transfer object.
731 *
732 * @returns VBox status code.
733 * @param pCtx Provider context to use.
734 * @param hObj Handle of transfer object to read from.
735 * @param pvData Buffer for where to store the read data.
736 * @param cbData Size (in bytes) of buffer.
737 * @param fFlags Read flags. Optional.
738 * @param pcbRead Where to return how much bytes were read on success. Optional.
739 */
740 DECLCALLBACKMEMBER(int, pfnObjRead,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
741 uint32_t fFlags, uint32_t *pcbRead));
742 /**
743 * Writes to a transfer object.
744 *
745 * @returns VBox status code.
746 * @param pCtx Provider context to use.
747 * @param hObj Handle of transfer object to write to.
748 * @param pvData Buffer of data to write.
749 * @param cbData Size (in bytes) of buffer to write.
750 * @param fFlags Write flags. Optional.
751 * @param pcbWritten How much bytes were writtenon success. Optional.
752 */
753 DECLCALLBACKMEMBER(int, pfnObjWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
754 uint32_t fFlags, uint32_t *pcbWritten));
755} SHCLTXPROVIDERIFACE;
756/** Pointer to a Shared Clipboard transfer provider interface table. */
757typedef SHCLTXPROVIDERIFACE *PSHCLTXPROVIDERIFACE;
758
759/** Queries (assigns) a Shared Clipboard provider interface. */
760#define SHCLTXPROVIDERIFACE_QUERY(a_Iface, a_Name) \
761 a_Iface->pfnRootListRead = a_Name ## RootListRead; \
762 a_Iface->pfnListOpen = a_Name ## ListOpen; \
763 a_Iface->pfnListClose = a_Name ## ListClose; \
764 a_Iface->pfnListHdrRead = a_Name ## ListHdrRead; \
765 a_Iface->pfnListHdrWrite = a_Name ## ListHdrWrite; \
766 a_Iface->pfnListEntryRead = a_Name ## ListEntryRead; \
767 a_Iface->pfnListEntryWrite = a_Name ## ListEntryWrite; \
768 a_Iface->pfnObjOpen = a_Name ## ObjOpen; \
769 a_Iface->pfnObjClose = a_Name ## ObjClose; \
770 a_Iface->pfnObjRead = a_Name ## ObjRead; \
771 a_Iface->pfnObjWrite = a_Name ## ObjWrite;
772
773/** Queries (assigns) a Shared Clipboard provider interface + returns the interface pointer. */
774#define SHCLTXPROVIDERIFACE_QUERY_RET(a_Iface, a_Name) \
775 SHCLTXPROVIDERIFACE_QUERY(a_Iface, a_Name); return a_Iface;
776
777/**
778 * Structure for Shared Clipboard transfer provider.
779 */
780typedef struct _SHCLTXPROVIDER
781{
782 /** Specifies what the source of the provider is. */
783 SHCLSOURCE enmSource;
784 /** The provider interface table to use. */
785 SHCLTXPROVIDERIFACE Interface;
786 /** User-provided callback data. */
787 void *pvUser;
788 /** Size (in bytes) of data at user pointer. */
789 size_t cbUser;
790} SHCLTXPROVIDER;
791/** Pointer to Shared Clipboard transfer provider. */
792typedef SHCLTXPROVIDER *PSHCLTXPROVIDER;
793
794/**
795 * Structure maintaining clipboard transfer callback context data.
796 */
797typedef struct _SHCLTRANSFERCALLBACKCTX
798{
799 /** Pointer to the related Shared Clipboard transfer. */
800 PSHCLTRANSFER pTransfer;
801 /** User-defined data pointer. Can be NULL if not needed. */
802 void *pvUser;
803 /** Size (in bytes) of data at user pointer. */
804 size_t cbUser;
805} SHCLTRANSFERCALLBACKCTX;
806/** Pointer to a Shared Clipboard transfer callback context. */
807typedef SHCLTRANSFERCALLBACKCTX *PSHCLTRANSFERCALLBACKCTX;
808
809/**
810 * Shared Clipboard transfer callback table.
811 *
812 * All callbacks are optional (hence all returning void).
813 */
814typedef struct _SHCLTRANSFERCALLBACKS
815{
816 /**
817 * Called after the transfer got created.
818 *
819 * @param pCbCtx Pointer to callback context to use.
820 */
821 DECLCALLBACKMEMBER(void, pfnOnCreated,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
822 /**
823 * Called after the transfer got initialized.
824 *
825 * @param pCbCtx Pointer to callback context to use.
826 */
827 DECLCALLBACKMEMBER(void, pfnOnInitialized,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
828 /**
829 * Called before the transfer gets destroyed.
830 *
831 * @param pCbCtx Pointer to callback context to use.
832 */
833 DECLCALLBACKMEMBER(void, pfnOnDestroy,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
834 /**
835 * Called after the transfer entered the started state.
836 *
837 * @param pCbCtx Pointer to callback context to use.
838 */
839 DECLCALLBACKMEMBER(void, pfnOnStarted,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
840 /**
841 * Called when the transfer has been completed.
842 *
843 * @param pCbCtx Pointer to callback context to use.
844 * @param rcCompletion Completion result.
845 * VERR_CANCELED if transfer has been canceled.
846 */
847 DECLCALLBACKMEMBER(void, pfnOnCompleted,(PSHCLTRANSFERCALLBACKCTX pCbCtx, int rcCompletion));
848 /**
849 * Called when transfer resulted in an unrecoverable error.
850 *
851 * @param pCbCtx Pointer to callback context to use.
852 * @param rcError Error reason, IPRT-style.
853 */
854 DECLCALLBACKMEMBER(void, pfnOnError,(PSHCLTRANSFERCALLBACKCTX pCbCtx, int rcError));
855 /**
856 * Called after a transfer got registered to a transfer context.
857 *
858 * @param pCbCtx Pointer to callback context to use.
859 * @param pTransferCtx Transfer context transfer was registered to.
860 */
861 DECLCALLBACKMEMBER(void, pfnOnRegistered,(PSHCLTRANSFERCALLBACKCTX pCbCtx, PSHCLTRANSFERCTX pTransferCtx));
862 /**
863 * Called after a transfer got unregistered from a transfer context.
864 *
865 * @param pCbCtx Pointer to callback context to use.
866 * @param pTransferCtx Transfer context transfer was unregistered from.
867 */
868 DECLCALLBACKMEMBER(void, pfnOnUnregistered,(PSHCLTRANSFERCALLBACKCTX pCbCtx, PSHCLTRANSFERCTX pTransferCtx));
869
870 /** User-provided callback data. Can be NULL if not used. */
871 void *pvUser;
872 /** Size (in bytes) of data pointer at \a pvUser. */
873 size_t cbUser;
874} SHCLTRANSFERCALLBACKS;
875/** Pointer to a Shared Clipboard transfer callback table. */
876typedef SHCLTRANSFERCALLBACKS *PSHCLTRANSFERCALLBACKS;
877
878/** Function pointer for a transfer thread function. */
879typedef DECLCALLBACKPTR(int, PFNSHCLTRANSFERTHREAD,(PSHCLTRANSFER pTransfer, void *pvUser));
880
881/**
882 * Structure for thread-related members for a single Shared Clipboard transfer.
883 */
884typedef struct _SHCLTRANSFERTHREAD
885{
886 /** Thread handle for the reading / writing thread.
887 * Can be NIL_RTTHREAD if not being used. */
888 RTTHREAD hThread;
889 /** Thread started indicator. */
890 volatile bool fStarted;
891 /** Thread stop flag. */
892 volatile bool fStop;
893 /** Thread cancelled flag / indicator. */
894 volatile bool fCancelled;
895} SHCLTRANSFERTHREAD;
896/** Pointer to a Shared Clipboard transfer thread. */
897typedef SHCLTRANSFERTHREAD *PSHCLTRANSFERTHREAD;
898
899/**
900 * A single Shared Clipboard transfer.
901 *
902 ** @todo Not yet thread safe.
903 */
904typedef struct SHCLTRANSFER
905{
906 /** The node member for using this struct in a RTList. */
907 RTLISTNODE Node;
908 /** Critical section for serializing access. */
909 RTCRITSECT CritSect;
910 /** Number of references to this transfer. */
911 uint32_t cRefs;
912 /** The transfer's state (for SSM, later). */
913 SHCLTRANSFERSTATE State;
914 /** Absolute path to root entries. */
915 char *pszPathRootAbs;
916 /** Timeout (in ms) for waiting of events. */
917 RTMSINTERVAL uTimeoutMs;
918 /** Maximum data chunk size (in bytes) to transfer. Default is 64K. */
919 uint32_t cbMaxChunkSize;
920 /** Status change event. */
921 RTSEMEVENT StatusChangeEvent;
922 /** The transfer's own event source. */
923 SHCLEVENTSOURCE Events;
924 /** Current number of concurrent list handles in \a lstHandles. */
925 uint32_t cListHandles;
926 /** Maximum number of concurrent list handles allowed. */
927 uint32_t cMaxListHandles;
928 /** Next upcoming list handle. For book keeping. */
929 SHCLLISTHANDLE uListHandleNext;
930 /** List of all list handles related to this transfer. */
931 RTLISTANCHOR lstHandles;
932 /** List of root entries of this transfer. */
933 SHCLLIST lstRoots;
934 /** Current number of concurrent object handles. in \a lstObj. */
935 uint32_t cObjHandles;
936 /** Maximum number of concurrent object handles. */
937 uint32_t cMaxObjHandles;
938 /** Next upcoming object handle. For book keeping. */
939 SHCLOBJHANDLE uObjHandleNext;
940 /** Map of all objects handles related to this transfer. */
941 RTLISTANCHOR lstObj;
942 /** The transfer's own provider context. */
943 SHCLTXPROVIDERCTX ProviderCtx;
944 /** The transfer's provider interface. */
945 SHCLTXPROVIDERIFACE ProviderIface;
946 /** The transfer's callback context. */
947 SHCLTRANSFERCALLBACKCTX CallbackCtx;
948 /** The transfer's callback table. */
949 SHCLTRANSFERCALLBACKS Callbacks;
950 /** Opaque pointer to implementation-specific parameters. */
951 void *pvUser;
952 /** Size (in bytes) of implementation-specific parameters. */
953 size_t cbUser;
954 /** Contains thread-related attributes. */
955 SHCLTRANSFERTHREAD Thread;
956} SHCLTRANSFER;
957/** Pointer to a Shared Clipboard transfer. */
958typedef SHCLTRANSFER *PSHCLTRANSFER;
959
960/**
961 * Structure for keeping an Shared Clipboard transfer status report.
962 */
963typedef struct _SHCLTRANSFERREPORT
964{
965 /** Actual status to report. */
966 SHCLTRANSFERSTATUS uStatus;
967 /** Result code (rc) to report; might be unused / invalid, based on enmStatus. */
968 int rc;
969 /** Reporting flags. Currently unused and must be 0. */
970 uint32_t fFlags;
971} SHCLTRANSFERREPORT;
972/** Pointer to Shared Clipboard transfer status. */
973typedef SHCLTRANSFERREPORT *PSHCLTRANSFERREPORT;
974
975#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
976/**
977 * Enumeration for HTTP server status changes.
978 *
979 * Keep those as flags, so that we can wait for multiple statuses, if ever needed.
980 */
981typedef enum _SHCLHTTPSERVERSTATUS
982{
983 /** No status set yet. */
984 SHCLHTTPSERVERSTATUS_NONE = 0x0,
985 /** A new transfer got registered. */
986 SHCLHTTPSERVERSTATUS_STARTED = 0x1,
987 /** A new transfer got registered. */
988 SHCLHTTPSERVERSTATUS_STOPPED = 0x2,
989 /** A new transfer got registered. */
990 SHCLHTTPSERVERSTATUS_TRANSFER_REGISTERED = 0x4,
991 /** A transfer got unregistered. */
992 SHCLHTTPSERVERSTATUS_TRANSFER_UNREGISTERED = 0x8
993} SHCLHTTPSERVERSTATUS;
994
995/**
996 * Structure for keeping a Shared Clipboard HTTP server instance.
997 */
998typedef struct _SHCLHTTPSERVER
999{
1000 /** Critical section for serializing access. */
1001 RTCRITSECT CritSect;
1002 /** Status event for callers to wait for.
1003 * Updates \a enmStatus. */
1004 RTSEMEVENT StatusEvent;
1005 /** Initialized indicator. */
1006 bool fInitialized;
1007 /** Running indicator. */
1008 bool fRunning;
1009 /** Current status. */
1010 SHCLHTTPSERVERSTATUS enmStatus;
1011 /** Handle of the HTTP server instance. */
1012 RTHTTPSERVER hHTTPServer;
1013 /** Port number the HTTP server is running on. 0 if not running. */
1014 uint16_t uPort;
1015 /** List of registered HTTP transfers. */
1016 RTLISTANCHOR lstTransfers;
1017 /** Number of registered HTTP transfers. */
1018 uint32_t cTransfers;
1019 /** Number of files served (via GET) so far.
1020 * Only complete downloads count (i.e. no aborted). */
1021 uint32_t cDownloaded;
1022 /** Cached response data. */
1023 RTHTTPSERVERRESP Resp;
1024} SHCLHTTPSERVER;
1025/** Pointer to Shared Clipboard HTTP server. */
1026typedef SHCLHTTPSERVER *PSHCLHTTPSERVER;
1027
1028/**
1029 * Structure for keeping a Shared Clipboard HTTP context around.
1030 *
1031 * This contains the HTTP server instance, among other things.
1032 */
1033typedef struct _SHCLHTTPCONTEXT
1034{
1035 /** HTTP server instance data. */
1036 SHCLHTTPSERVER HttpServer;
1037} SHCLHTTPCONTEXT;
1038/** Pointer to Shared Clipboard HTTP transfer context. */
1039typedef SHCLHTTPCONTEXT *PSHCLHTTPCONTEXT;
1040
1041#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP */
1042
1043/**
1044 * Structure for keeping a single transfer context event.
1045 */
1046typedef struct _SHCLTRANSFERCTXEVENT
1047{
1048 /** Transfer bound to this event.
1049 * Can be NULL if not being used. */
1050 PSHCLTRANSFER pTransfer;
1051 /** Whether a transfer was registered or not. */
1052 bool fRegistered;
1053} SHCLTRANSFERCTXEVENT;
1054/** Pointer to Shared Clipboard transfer context event. */
1055typedef SHCLTRANSFERCTXEVENT *PSHCLTRANSFERCTXEVENT;
1056
1057/**
1058 * Structure for keeping Shared Clipboard transfer context around.
1059 *
1060 * A transfer context contains a list of (grouped) transfers for book keeping.
1061 */
1062typedef struct _SHCLTRANSFERCTX
1063{
1064 /** Critical section for serializing access. */
1065 RTCRITSECT CritSect;
1066 /** Event used for waiting. for transfer context changes. */
1067 RTSEMEVENT ChangedEvent;
1068 /** Event data for \a ChangedEvent. */
1069 SHCLTRANSFERCTXEVENT ChangedEventData;
1070 /** List of transfers. */
1071 RTLISTANCHOR List;
1072 /** Transfer ID allocation bitmap; clear bits are free, set bits are busy. */
1073 uint64_t bmTransferIds[VBOX_SHCL_MAX_TRANSFERS / sizeof(uint64_t) / 8];
1074 /** Number of running (concurrent) transfers. */
1075 uint16_t cRunning;
1076 /** Maximum Number of running (concurrent) transfers. */
1077 uint16_t cMaxRunning;
1078 /** Number of total transfers (in list). */
1079 uint16_t cTransfers;
1080} SHCLTRANSFERCTX;
1081/** Pointer to Shared Clipboard transfer context. */
1082typedef SHCLTRANSFERCTX *PSHCLTRANSFERCTX;
1083
1084/** @name Shared Clipboard transfer interface providers.
1085 * @{
1086 */
1087PSHCLTXPROVIDERIFACE ShClTransferProviderLocalQueryInterface(PSHCLTXPROVIDER pProvider);
1088/** @} */
1089
1090/** @name Shared Clipboard transfer object API.
1091 * @{
1092 */
1093int ShClTransferObjCtxInit(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
1094void ShClTransferObjCtxDestroy(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
1095bool ShClTransferObjCtxIsValid(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
1096
1097int ShClTransferObjInit(PSHCLTRANSFEROBJ pObj);
1098void ShClTransferObjDestroy(PSHCLTRANSFEROBJ pObj);
1099
1100int ShClTransferObjOpenParmsInit(PSHCLOBJOPENCREATEPARMS pParms);
1101int ShClTransferObjOpenParmsCopy(PSHCLOBJOPENCREATEPARMS pParmsDst, PSHCLOBJOPENCREATEPARMS pParmsSrc);
1102void ShClTransferObjOpenParmsDestroy(PSHCLOBJOPENCREATEPARMS pParms);
1103
1104int ShClTransferObjOpen(PSHCLTRANSFER pTransfer, PSHCLOBJOPENCREATEPARMS pOpenCreateParms, PSHCLOBJHANDLE phObj);
1105int ShClTransferObjClose(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj);
1106bool ShClTransferObjIsComplete(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj);
1107int ShClTransferObjRead(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t fFlags, uint32_t *pcbRead);
1108int ShClTransferObjWrite(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t fFlags, uint32_t *pcbWritten);
1109PSHCLTRANSFEROBJ ShClTransferObjGet(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj);
1110
1111PSHCLOBJDATACHUNK ShClTransferObjDataChunkDup(PSHCLOBJDATACHUNK pDataChunk);
1112void ShClTransferObjDataChunkDestroy(PSHCLOBJDATACHUNK pDataChunk);
1113void ShClTransferObjDataChunkFree(PSHCLOBJDATACHUNK pDataChunk);
1114/** @} */
1115
1116/** @name Shared Clipboard transfer API.
1117 * @{
1118 */
1119int ShClTransferCreateEx(SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource, uint32_t cbMaxChunkSize, uint32_t cMaxListHandles, uint32_t cMaxObjHandles, PSHCLTRANSFER *ppTransfer);
1120int ShClTransferCreate(SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource, PSHCLTRANSFERCALLBACKS pCallbacks, PSHCLTRANSFER *ppTransfer);
1121int ShClTransferInit(PSHCLTRANSFER pTransfer);
1122int ShClTransferDestroy(PSHCLTRANSFER pTransfer);
1123void ShClTransferReset(PSHCLTRANSFER pTransfer);
1124
1125int ShClTransferRun(PSHCLTRANSFER pTransfer, PFNSHCLTRANSFERTHREAD pfnThreadFunc, void *pvUser);
1126int ShClTransferStart(PSHCLTRANSFER pTransfer);
1127int ShClTransferComplete(PSHCLTRANSFER pTransfer);
1128int ShClTransferCancel(PSHCLTRANSFER pTransfer);
1129int ShClTransferError(PSHCLTRANSFER pTransfer, int rc);
1130
1131uint32_t ShClTransferAcquire(PSHCLTRANSFER pTransfer);
1132uint32_t ShClTransferRelease(PSHCLTRANSFER pTransfer);
1133
1134SHCLTRANSFERID ShClTransferGetID(PSHCLTRANSFER pTransfer);
1135SHCLTRANSFERDIR ShClTransferGetDir(PSHCLTRANSFER pTransfer);
1136int ShClTransferGetRootPathAbs(PSHCLTRANSFER pTransfer, char *pszPath, size_t cbPath);
1137SHCLSOURCE ShClTransferGetSource(PSHCLTRANSFER pTransfer);
1138SHCLTRANSFERSTATUS ShClTransferGetStatus(PSHCLTRANSFER pTransfer);
1139int ShClTransferWaitForStatus(PSHCLTRANSFER pTransfer, RTMSINTERVAL msTimeout, SHCLTRANSFERSTATUS enmStatus);
1140int ShClTransferWaitForStatusChange(PSHCLTRANSFER pTransfer, RTMSINTERVAL msTimeout, SHCLTRANSFERSTATUS *penmStatus);
1141
1142int ShClTransferListOpen(PSHCLTRANSFER pTransfer, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList);
1143int ShClTransferListClose(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
1144int ShClTransferListGetHeader(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTHDR pHdr);
1145PSHCLLISTHANDLEINFO ShClTransferListGetByHandle(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
1146PSHCLTRANSFEROBJ ShClTransferListGetObj(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, uint64_t uIdx);
1147int ShClTransferListRead(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
1148int ShClTransferListWrite(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
1149bool ShClTransferListHandleIsValid(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
1150
1151PSHCLLIST ShClTransferListAlloc(void);
1152void ShClTransferListFree(PSHCLLIST pList);
1153void ShClTransferListInit(PSHCLLIST pList);
1154void ShClTransferListDestroy(PSHCLLIST pList);
1155int ShClTransferListAddEntry(PSHCLLIST pList, PSHCLLISTENTRY pEntry, bool fAppend);
1156
1157int ShClTransferListHandleInfoInit(PSHCLLISTHANDLEINFO pInfo);
1158void ShClTransferListHandleInfoDestroy(PSHCLLISTHANDLEINFO pInfo);
1159
1160int ShClTransferListHdrAlloc(PSHCLLISTHDR *ppListHdr);
1161void ShClTransferListHdrFree(PSHCLLISTHDR pListHdr);
1162PSHCLLISTHDR ShClTransferListHdrDup(PSHCLLISTHDR pListHdr);
1163int ShClTransferListHdrInit(PSHCLLISTHDR pListHdr);
1164void ShClTransferListHdrDestroy(PSHCLLISTHDR pListHdr);
1165void ShClTransferListHdrReset(PSHCLLISTHDR pListHdr);
1166bool ShClTransferListHdrIsValid(PSHCLLISTHDR pListHdr);
1167
1168int ShClTransferListOpenParmsCopy(PSHCLLISTOPENPARMS pDst, PSHCLLISTOPENPARMS pSrc);
1169PSHCLLISTOPENPARMS ShClTransferListOpenParmsDup(PSHCLLISTOPENPARMS pParms);
1170int ShClTransferListOpenParmsInit(PSHCLLISTOPENPARMS pParms);
1171void ShClTransferListOpenParmsDestroy(PSHCLLISTOPENPARMS pParms);
1172
1173int ShClTransferListEntryAlloc(PSHCLLISTENTRY *ppListEntry);
1174void ShClTransferListEntryFree(PSHCLLISTENTRY pListEntry);
1175int ShClTransferListEntryInitEx(PSHCLLISTENTRY pListEntry, uint32_t fInfo, const char *pszName, void *pvInfo, uint32_t cbInfo);
1176int ShClTransferListEntryInit(PSHCLLISTENTRY pListEntry);
1177void ShClTransferListEntryDestroy(PSHCLLISTENTRY pListEntry);
1178bool ShClTransferListEntryIsValid(PSHCLLISTENTRY pListEntry);
1179int ShClTransferListEntryCopy(PSHCLLISTENTRY pDst, PSHCLLISTENTRY pSrc);
1180PSHCLLISTENTRY ShClTransferListEntryDup(PSHCLLISTENTRY pListEntry);
1181
1182int ShClTransferSetProvider(PSHCLTRANSFER pTransfer, PSHCLTXPROVIDER pProvider);
1183
1184int ShClTransferRootsInitFromStringList(PSHCLTRANSFER pTransfer, const char *pszRoots, size_t cbRoots);
1185int ShClTransferRootsInitFromStringListUnicode(PSHCLTRANSFER pTransfer, PRTUTF16 pwszRoots, size_t cbRoots);
1186int ShClTransferRootsInitFromFile(PSHCLTRANSFER pTransfer, const char *pszFile);
1187uint64_t ShClTransferRootsCount(PSHCLTRANSFER pTransfer);
1188PCSHCLLISTENTRY ShClTransferRootsEntryGet(PSHCLTRANSFER pTransfer, uint64_t uIndex);
1189int ShClTransferRootListRead(PSHCLTRANSFER pTransfer);
1190/** @} */
1191
1192/** @name Shared Clipboard transfer context API.
1193 * @{
1194 */
1195int ShClTransferCtxInit(PSHCLTRANSFERCTX pTransferCtx);
1196void ShClTransferCtxDestroy(PSHCLTRANSFERCTX pTransferCtx);
1197void ShClTransferCtxReset(PSHCLTRANSFERCTX pTransferCtx);
1198PSHCLTRANSFER ShClTransferCtxGetTransferById(PSHCLTRANSFERCTX pTransferCtx, uint32_t uID);
1199PSHCLTRANSFER ShClTransferCtxGetTransferByIndex(PSHCLTRANSFERCTX pTransferCtx, uint32_t uIdx);
1200PSHCLTRANSFER ShClTransferCtxGetTransferLast(PSHCLTRANSFERCTX pTransferCtx);
1201uint32_t ShClTransferCtxGetRunningTransfers(PSHCLTRANSFERCTX pTransferCtx);
1202uint32_t ShClTransferCtxGetTotalTransfers(PSHCLTRANSFERCTX pTransferCtx);
1203void ShClTransferCtxCleanup(PSHCLTRANSFERCTX pTransferCtx);
1204bool ShClTransferCtxIsMaximumReached(PSHCLTRANSFERCTX pTransferCtx);
1205int ShClTransferCtxCreateId(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFERID pidTransfer);
1206int ShClTransferCtxRegister(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, PSHCLTRANSFERID pidTransfer);
1207int ShClTransferCtxRegisterById(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERID idTransfer);
1208int ShClTransferCtxUnregisterById(PSHCLTRANSFERCTX pTransferCtx, SHCLTRANSFERID idTransfer);
1209int ShClTransferCtxWait(PSHCLTRANSFERCTX pTransferCtx, RTMSINTERVAL msTimeout, bool fRegister, SHCLTRANSFERID idTransfer, PSHCLTRANSFER *ppTransfer);
1210/** @} */
1211
1212#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
1213/** Namespace used as a prefix for HTTP(S) transfer URLs. */
1214#define SHCL_HTTPT_URL_NAMESPACE "vbcl"
1215
1216/** @name Shared Clipboard HTTP context API.
1217 * @{
1218 */
1219int ShClTransferHttpServerMaybeStart(PSHCLHTTPCONTEXT pCtx);
1220int ShClTransferHttpServerMaybeStop(PSHCLHTTPCONTEXT pCtx);
1221/** @} */
1222
1223/** @name Shared Clipboard HTTP server API.
1224 * @{
1225 */
1226int ShClTransferHttpServerInit(PSHCLHTTPSERVER pSrv);
1227int ShClTransferHttpServerDestroy(PSHCLHTTPSERVER pSrv);
1228int ShClTransferHttpServerStart(PSHCLHTTPSERVER pSrv, unsigned cMaxAttempts, uint16_t *puPort);
1229int ShClTransferHttpServerStartEx(PSHCLHTTPSERVER pSrv, uint16_t uPort);
1230int ShClTransferHttpServerStop(PSHCLHTTPSERVER pSrv);
1231int ShClTransferHttpServerRegisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer);
1232int ShClTransferHttpServerUnregisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer);
1233PSHCLTRANSFER ShClTransferHttpServerGetTransferFirst(PSHCLHTTPSERVER pSrv);
1234PSHCLTRANSFER ShClTransferHttpServerGetTransferLast(PSHCLHTTPSERVER pSrv);
1235bool ShClTransferHttpServerGetTransfer(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer);
1236uint16_t ShClTransferHttpServerGetPort(PSHCLHTTPSERVER pSrv);
1237uint32_t ShClTransferHttpServerGetTransferCount(PSHCLHTTPSERVER pSrv);
1238char *ShClTransferHttpServerGetAddressA(PSHCLHTTPSERVER pSrv);
1239char *ShClTransferHttpServerGetUrlA(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer);
1240bool ShClTransferHttpServerIsInitialized(PSHCLHTTPSERVER pSrv);
1241bool ShClTransferHttpServerIsRunning(PSHCLHTTPSERVER pSrv);
1242int ShClTransferHttpServerWaitForStatusChange(PSHCLHTTPSERVER pSrv, SHCLHTTPSERVERSTATUS fStatus, RTMSINTERVAL msTimeout);
1243/** @} */
1244#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP */
1245
1246/** @name Shared Clipboard transfers utility functions.
1247 * @{
1248 */
1249int ShClPathSanitizeFilename(char *pszPath, size_t cbPath);
1250int ShClPathSanitize(char *pszPath, size_t cbPath);
1251const char *ShClTransferStatusToStr(SHCLTRANSFERSTATUS enmStatus);
1252int ShClTransferValidatePath(const char *pcszPath, bool fMustExist);
1253int ShClTransferResolvePathAbs(PSHCLTRANSFER pTransfer, const char *pszPath, uint32_t fFlags, char **ppszResolved);
1254int ShClTransferConvertFileCreateFlags(uint32_t fShClFlags, uint64_t *pfOpen);
1255int ShClFsObjInfoQueryLocal(const char *pszPath, PSHCLFSOBJINFO pObjInfo);
1256int ShClFsObjInfoFromIPRT(PSHCLFSOBJINFO pDst, PCRTFSOBJINFO pSrc);
1257/** @} */
1258
1259/** @name Shared Clipboard MIME functions.
1260 * @{
1261 */
1262bool ShClMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
1263bool ShClMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
1264/** @} */
1265
1266#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