VirtualBox

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

Last change on this file since 100205 was 100205, checked in by vboxsync, 18 months ago

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