SharedClipboard-transfers.h@ 104310

Last change on this file since 104310 was 104310, checked in by vboxsync, 8 months ago
Shared Clipboard/Transfers: Renamed ShClTransferRootsInitFromFile() -> ShClTransferRootsInitFromPath(). bugref:9437
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 49.1 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: