SharedClipboard-uri.h@ 79027

Last change on this file since 79027 was 79027, checked in by vboxsync, 6 years ago
Shared Clipboard/URI: Update (more glue code, transfer callbacks).
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 26.1 KB

Line
1	/* $Id: SharedClipboard-uri.h 79027 2019-06-06 14:47:16Z vboxsync $ */
2	/** @file
3	* Shared Clipboard - Shared URI functions between host and guest.
4	*/
5
6	/*
7	* Copyright (C) 2019 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h
28	#define VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h
29	#ifndef RT_WITHOUT_PRAGMA_ONCE
30	# pragma once
31	#endif
32
33	#include <iprt/assert.h>
34	#include <iprt/critsect.h>
35	#include <iprt/fs.h>
36	#include <iprt/list.h>
37
38	#include <iprt/cpp/list.h>
39	#include <iprt/cpp/ministring.h>
40
41	#include <VBox/HostServices/VBoxClipboardSvc.h>
42
43	/** Clipboard area ID. A valid area is >= 1.
44	* If 0 is specified, the last (most recent) area is meant.
45	* Set to UINT32_MAX if not initialized. */
46	typedef uint32_t SHAREDCLIPBOARDAREAID;
47
48	/** Defines a non-initialized (nil) clipboard area. */
49	#define NIL_SHAREDCLIPBOARDAREAID UINT32_MAX
50
51	/** SharedClipboardArea open flags. */
52	typedef uint32_t SHAREDCLIPBOARDAREAOPENFLAGS;
53
54	/** No open flags specified. */
55	#define SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE 0
56	/** The clipboard area must not exist yet. */
57	#define SHAREDCLIPBOARDAREA_OPEN_FLAGS_MUST_NOT_EXIST RT_BIT(0)
58
59	/**
60	* Class for maintaining a Shared Clipboard area
61	* on the host or guest. This will contain all received files & directories
62	* for a single Shared Clipboard operation.
63	*
64	* In case of a failed Shared Clipboard operation this class can also
65	* perform a gentle rollback if required.
66	*/
67	class SharedClipboardArea
68	{
69	public:
70
71	SharedClipboardArea(void);
72	SharedClipboardArea(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
73	SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
74	virtual ~SharedClipboardArea(void);
75
76	public:
77
78	uint32_t AddRef(void);
79	uint32_t Release(void);
80
81	int Lock(void);
82	int Unlock(void);
83
84	int AddFile(const char *pszFile);
85	int AddDir(const char *pszDir);
86	int Close(void);
87	bool IsOpen(void) const;
88	int OpenEx(const char *pszPath, SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
89	SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
90	int OpenTemp(SHAREDCLIPBOARDAREAID uID = NIL_SHAREDCLIPBOARDAREAID,
91	SHAREDCLIPBOARDAREAOPENFLAGS fFlags = SHAREDCLIPBOARDAREA_OPEN_FLAGS_NONE);
92	SHAREDCLIPBOARDAREAID GetID(void) const;
93	const char *GetDirAbs(void) const;
94	uint32_t GetRefCount(void);
95	int Reopen(void);
96	int Reset(bool fDeleteContent);
97	int Rollback(void);
98
99	public:
100
101	static int PathConstruct(const char pszBase, SHAREDCLIPBOARDAREAID uID, char pszPath, size_t cbPath);
102
103	protected:
104
105	int initInternal(void);
106	int destroyInternal(void);
107	int closeInternal(void);
108
109	protected:
110
111	/** Creation timestamp (in ms). */
112	uint64_t m_tsCreatedMs;
113	/** Number of references to this instance. */
114	volatile uint32_t m_cRefs;
115	/** Critical section for serializing access. */
116	RTCRITSECT m_CritSect;
117	/** Open flags. */
118	uint32_t m_fOpen;
119	/** Directory handle for drop directory. */
120	RTDIR m_hDir;
121	/** Absolute path to drop directory. */
122	RTCString m_strPathAbs;
123	/** List for holding created directories in the case of a rollback. */
124	RTCList<RTCString> m_lstDirs;
125	/** List for holding created files in the case of a rollback. */
126	RTCList<RTCString> m_lstFiles;
127	/** Associated clipboard area ID. */
128	SHAREDCLIPBOARDAREAID m_uID;
129	};
130
131	int SharedClipboardPathSanitizeFilename(char *pszPath, size_t cbPath);
132	int SharedClipboardPathSanitize(char *pszPath, size_t cbPath);
133
134	/** SharedClipboardURIObject flags. */
135	typedef uint32_t SHAREDCLIPBOARDURIOBJECTFLAGS;
136
137	/** No flags specified. */
138	#define SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE 0
139
140	/** Mask of all valid Shared Clipboard URI object flags. */
141	#define SHAREDCLIPBOARDURIOBJECT_FLAGS_VALID_MASK UINT32_C(0x0)
142
143	/**
144	* Class for handling Shared Clipboard URI objects.
145	* This class abstracts the access and handling objects when performing Shared Clipboard actions.
146	*/
147	class SharedClipboardURIObject
148	{
149	public:
150
151	/**
152	* Enumeration for specifying an URI object type.
153	*/
154	enum Type
155	{
156	/** Unknown type, do not use. */
157	Type_Unknown = 0,
158	/** Object is a file. */
159	Type_File,
160	/** Object is a directory. */
161	Type_Directory,
162	/** The usual 32-bit hack. */
163	Type_32Bit_Hack = 0x7fffffff
164	};
165
166	/**
167	* Enumeration for specifying an URI object view
168	* for representing its data accordingly.
169	*/
170	enum View
171	{
172	/** Unknown view, do not use. */
173	View_Unknown = 0,
174	/** Handle data from the source point of view. */
175	View_Source,
176	/** Handle data from the destination point of view. */
177	View_Target,
178	/** The usual 32-bit hack. */
179	View_Dest_32Bit_Hack = 0x7fffffff
180	};
181
182	SharedClipboardURIObject(void);
183	SharedClipboardURIObject(Type type, const RTCString &strSrcPathAbs = "", const RTCString &strDstPathAbs = "");
184	virtual ~SharedClipboardURIObject(void);
185
186	public:
187
188	/**
189	* Returns the given absolute source path of the object.
190	*
191	* @return Absolute source path of the object.
192	*/
193	const RTCString &GetSourcePathAbs(void) const { return m_strSrcPathAbs; }
194
195	/**
196	* Returns the given, absolute destination path of the object.
197	*
198	* @return Absolute destination path of the object.
199	*/
200	const RTCString &GetDestPathAbs(void) const { return m_strTgtPathAbs; }
201
202	RTFMODE GetMode(void) const;
203
204	uint64_t GetProcessed(void) const;
205
206	uint64_t GetSize(void) const;
207
208	/**
209	* Returns the object's type.
210	*
211	* @return The object's type.
212	*/
213	Type GetType(void) const { return m_enmType; }
214
215	/**
216	* Returns the object's view.
217	*
218	* @return The object's view.
219	*/
220	View GetView(void) const { return m_enmView; }
221
222	public:
223
224	int SetSize(uint64_t cbSize);
225
226	public:
227
228	void Close(void);
229	bool IsComplete(void) const;
230	bool IsOpen(void) const;
231	int OpenDirectory(View enmView, uint32_t fCreate = 0, RTFMODE fMode = 0);
232	int OpenDirectoryEx(const RTCString &strPathAbs, View enmView,
233	uint32_t fCreate = 0, RTFMODE fMode = 0,
234	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
235	int OpenFile(View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0);
236	int OpenFileEx(const RTCString &strPathAbs, View enmView,
237	uint64_t fOpen = 0, RTFMODE fMode = 0,
238	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
239	int QueryInfo(View enmView);
240	int Read(void pvBuf, size_t cbBuf, uint32_t pcbRead);
241	void Reset(void);
242	int SetDirectoryData(const RTCString &strPathAbs, View enmView, uint32_t fOpen = 0, RTFMODE fMode = 0,
243	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
244	int SetFileData(const RTCString &strPathAbs, View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0,
245	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
246	int Write(const void pvBuf, size_t cbBuf, uint32_t pcbWritten);
247
248	public:
249
250	static int RebaseURIPath(RTCString &strPath, const RTCString &strBaseOld = "", const RTCString &strBaseNew = "");
251
252	protected:
253
254	void closeInternal(void);
255	int setDirectoryDataInternal(const RTCString &strPathAbs, View enmView, uint32_t fCreate = 0, RTFMODE fMode = 0,
256	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
257	int setFileDataInternal(const RTCString &strPathAbs, View enmView, uint64_t fOpen = 0, RTFMODE fMode = 0,
258	SHAREDCLIPBOARDURIOBJECTFLAGS fFlags = SHAREDCLIPBOARDURIOBJECT_FLAGS_NONE);
259	int queryInfoInternal(View enmView);
260
261	protected:
262
263	/** The object's type. */
264	Type m_enmType;
265	/** The object's view. */
266	View m_enmView;
267	/** Absolute path (base) for the source. */
268	RTCString m_strSrcPathAbs;
269	/** Absolute path (base) for the target. */
270	RTCString m_strTgtPathAbs;
271	/** Saved SHAREDCLIPBOARDURIOBJECT_FLAGS. */
272	uint32_t m_fFlags;
273	/** Requested file mode.
274	* Note: The actual file mode of an opened file will be in objInfo. */
275	RTFMODE m_fModeRequested;
276
277	/** Union containing data depending on the object's type. */
278	union
279	{
280	/** Structure containing members for objects that
281	* are files. */
282	struct
283	{
284	/** File handle. */
285	RTFILE hFile;
286	/** File system object information of this file. */
287	RTFSOBJINFO objInfo;
288	/** Requested file open flags. */
289	uint32_t fOpenRequested;
290	/** Bytes to proces for reading/writing. */
291	uint64_t cbToProcess;
292	/** Bytes processed reading/writing. */
293	uint64_t cbProcessed;
294	} File;
295	struct
296	{
297	/** Directory handle. */
298	RTDIR hDir;
299	/** File system object information of this directory. */
300	RTFSOBJINFO objInfo;
301	/** Requested directory creation flags. */
302	uint32_t fCreateRequested;
303	} Dir;
304	} u;
305	};
306
307	/** SharedClipboardURIList flags. */
308	typedef uint32_t SHAREDCLIPBOARDURILISTFLAGS;
309
310	/** No flags specified. */
311	#define SHAREDCLIPBOARDURILIST_FLAGS_NONE 0
312	/** Keep the original paths, don't convert paths to relative ones. */
313	#define SHAREDCLIPBOARDURILIST_FLAGS_ABSOLUTE_PATHS RT_BIT(0)
314	/** Resolve all symlinks. */
315	#define SHAREDCLIPBOARDURILIST_FLAGS_RESOLVE_SYMLINKS RT_BIT(1)
316	/** Keep the files + directory entries open while
317	* being in this list. */
318	#define SHAREDCLIPBOARDURILIST_FLAGS_KEEP_OPEN RT_BIT(2)
319	/** Lazy loading: Only enumerate sub directories when needed.
320	** @todo Implement lazy loading. */
321	#define SHAREDCLIPBOARDURILIST_FLAGS_LAZY RT_BIT(3)
322
323	/** Mask of all valid Shared Clipboard URI list flags. */
324	#define SHAREDCLIPBOARDURILIST_FLAGS_VALID_MASK UINT32_C(0xF)
325
326	class SharedClipboardURIList
327	{
328	public:
329
330	SharedClipboardURIList(void);
331	virtual ~SharedClipboardURIList(void);
332
333	public:
334
335	int AppendNativePath(const char *pszPath, SHAREDCLIPBOARDURILISTFLAGS fFlags);
336	int AppendNativePathsFromList(const char *pszNativePaths, size_t cbNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
337	int AppendNativePathsFromList(const RTCList<RTCString> &lstNativePaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
338	int AppendURIObject(SharedClipboardURIObject *pObject);
339	int AppendURIPath(const char *pszURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
340	int AppendURIPathsFromList(const char *pszURIPaths, size_t cbURIPaths, SHAREDCLIPBOARDURILISTFLAGS fFlags);
341	int AppendURIPathsFromList(const RTCList<RTCString> &lstURI, SHAREDCLIPBOARDURILISTFLAGS fFlags);
342
343	void Clear(void);
344	SharedClipboardURIObject *At(size_t i) const { return m_lstTree.at(i); }
345	SharedClipboardURIObject *First(void) const { return m_lstTree.first(); }
346	bool IsEmpty(void) const { return m_lstTree.isEmpty(); }
347	void RemoveFirst(void);
348	int SetFromURIData(const void *pvData, size_t cbData, SHAREDCLIPBOARDURILISTFLAGS fFlags);
349
350	RTCString GetRootEntries(const RTCString &strPathBase = "", const RTCString &strSeparator = "\r\n") const;
351	uint64_t GetRootCount(void) const { return m_lstRoot.size(); }
352	uint64_t GetTotalCount(void) const { return m_cTotal; }
353	uint64_t GetTotalBytes(void) const { return m_cbTotal; }
354
355	protected:
356
357	int appendEntry(const char pcszSource, const char pcszTarget, SHAREDCLIPBOARDURILISTFLAGS fFlags);
358	int appendObject(SharedClipboardURIObject *pObject);
359	int appendPathRecursive(const char pcszSrcPath, const char pcszDstPath, const char *pcszDstBase, size_t cchDstBase, SHAREDCLIPBOARDURILISTFLAGS fFlags);
360
361	protected:
362
363	/** List of all top-level file/directory entries.
364	* Note: All paths are kept internally as UNIX paths for
365	* easier conversion/handling! */
366	RTCList<RTCString> m_lstRoot;
367	/** List of all URI objects added. The list's content
368	* might vary depending on how the objects are being
369	* added (lazy or not). */
370	RTCList<SharedClipboardURIObject *> m_lstTree;
371	/** Total number of all URI objects. */
372	uint64_t m_cTotal;
373	/** Total size of all URI objects, that is, the file
374	* size of all objects (in bytes).
375	* Note: Do not size_t here, as we also want to support large files
376	* on 32-bit guests. */
377	uint64_t m_cbTotal;
378	};
379
380	/**
381	* Structure for keeping Shared Clipboard meta data.
382	*
383	* For URI transfers this represents a string list with the file object root entries in it.
384	*/
385	typedef struct _SHAREDCLIPBOARDMETADATA
386	{
387	/** Actual meta data block. */
388	void *pvMeta;
389	/** Total size (in bytes) of the allocated meta data block .*/
390	uint32_t cbMeta;
391	/** How many bytes are being used in the meta data block. */
392	uint32_t cbUsed;
393	} SHAREDCLIPBOARDMETADATA, *PSHAREDCLIPBOARDMETADATA;
394
395	int SharedClipboardMetaDataInit(PSHAREDCLIPBOARDMETADATA pMeta);
396	void SharedClipboardMetaDataDestroy(PSHAREDCLIPBOARDMETADATA pMeta);
397	int SharedClipboardMetaDataAdd(PSHAREDCLIPBOARDMETADATA pMeta, const void *pvDataAdd, uint32_t cbDataAdd);
398	int SharedClipboardMetaDataResize(PSHAREDCLIPBOARDMETADATA pMeta, uint32_t cbNewSize);
399	size_t SharedClipboardMetaDataGetFree(PSHAREDCLIPBOARDMETADATA pMeta);
400	size_t SharedClipboardMetaDataGetUsed(PSHAREDCLIPBOARDMETADATA pMeta);
401	size_t SharedClipboardMetaDataGetSize(PSHAREDCLIPBOARDMETADATA pMeta);
402	void *SharedClipboardMetaDataMutableRaw(PSHAREDCLIPBOARDMETADATA pMeta);
403	const void *SharedClipboardMetaDataRaw(PSHAREDCLIPBOARDMETADATA pMeta);
404
405	/**
406	* Enumeration to specify the Shared Clipboard provider source type.
407	*/
408	typedef enum SHAREDCLIPBOARDPROVIDERSOURCE
409	{
410	/** Invalid source type. */
411	SHAREDCLIPBOARDPROVIDERSOURCE_INVALID = 0,
412	/** Source is VbglR3. */
413	SHAREDCLIPBOARDPROVIDERSOURCE_VBGLR3,
414	/** Source is the host service. */
415	SHAREDCLIPBOARDPROVIDERSOURCE_HOSTSERVICE
416	} SHAREDCLIPBOARDPROVIDERSOURCE;
417
418	/**
419	* Structure for the Shared Clipboard provider creation context.
420	*/
421	typedef struct _SHAREDCLIPBOARDPROVIDERCREATIONCTX
422	{
423	SHAREDCLIPBOARDPROVIDERSOURCE enmSource;
424	union
425	{
426	struct
427	{
428	/** HGCM client ID to use. */
429	uint32_t uClientID;
430	} VBGLR3;
431	} u;
432	} SHAREDCLIPBOARDPROVIDERCREATIONCTX, *PSHAREDCLIPBOARDPROVIDERCREATIONCTX;
433
434	/**
435	* Interface class acting as a lightweight proxy for abstracting reading / writing clipboard data.
436	*
437	* This is needed because various implementations can run on the host or on the guest side,
438	* requiring different methods for handling the actual data.
439	*/
440	class SharedClipboardProvider
441	{
442
443	public:
444
445	static SharedClipboardProvider *Create(PSHAREDCLIPBOARDPROVIDERCREATIONCTX pCtx);
446
447	virtual ~SharedClipboardProvider(void);
448
449	public:
450
451	uint32_t AddRef(void);
452	uint32_t Release(void);
453
454	public: /* Interface to be implemented. */
455
456	virtual int ReadDataHdr(PVBOXCLIPBOARDDATAHDR pDataHdr);
457	virtual int WriteDataHdr(const PVBOXCLIPBOARDDATAHDR pDataHdr);
458
459	virtual int ReadMetaData(const PVBOXCLIPBOARDDATAHDR pDataHdr, void pvMeta, uint32_t cbMeta, uint32_t pcbRead, uint32_t fFlags = 0);
460	virtual int WriteMetaData(const PVBOXCLIPBOARDDATAHDR pDataHdr, const void pvMeta, uint32_t cbMeta, uint32_t pcbWritten,
461	uint32_t fFlags = 0);
462
463	virtual int ReadDirectory(PVBOXCLIPBOARDDIRDATA pDirData);
464	virtual int WriteDirectory(const PVBOXCLIPBOARDDIRDATA pDirData);
465
466	virtual int ReadFileHdr(PVBOXCLIPBOARDFILEHDR pFileHdr);
467	virtual int WriteFileHdr(const PVBOXCLIPBOARDFILEHDR pFileHdr);
468
469	virtual int ReadFileData(PVBOXCLIPBOARDFILEDATA pFileData, uint32_t *pcbRead);
470	virtual int WriteFileData(const PVBOXCLIPBOARDFILEDATA pFileData, uint32_t *pcbWritten);
471
472	virtual void Reset(void);
473
474	protected:
475
476	SharedClipboardProvider(void);
477
478	protected:
479
480	/** Number of references to this instance. */
481	volatile uint32_t m_cRefs;
482	};
483
484	/**
485	* Shared Clipboard provider implementation for VbglR3 (guest side).
486	*/
487	class SharedClipboardProviderVbglR3 : protected SharedClipboardProvider
488	{
489	friend class SharedClipboardProvider;
490
491	public:
492
493	virtual ~SharedClipboardProviderVbglR3(void);
494
495	public:
496
497	int ReadDataHdr(PVBOXCLIPBOARDDATAHDR pDataHdr);
498	int WriteDataHdr(const PVBOXCLIPBOARDDATAHDR pDataHdr);
499
500	int ReadMetaData(const PVBOXCLIPBOARDDATAHDR pDataHdr, void pvMeta, uint32_t cbMeta, uint32_t pcbRead, uint32_t fFlags = 0);
501	int WriteMetaData(const PVBOXCLIPBOARDDATAHDR pDataHdr, const void pvMeta, uint32_t cbMeta, uint32_t pcbWritten,
502	uint32_t fFlags = 0);
503
504	int ReadDirectory(PVBOXCLIPBOARDDIRDATA pDirData);
505	int WriteDirectory(const PVBOXCLIPBOARDDIRDATA pDirData);
506
507	int ReadFileHdr(PVBOXCLIPBOARDFILEHDR pFileHdr);
508	int WriteFileHdr(const PVBOXCLIPBOARDFILEHDR pFileHdr);
509
510	int ReadFileData(PVBOXCLIPBOARDFILEDATA pFileData, uint32_t *pcbRead);
511	int WriteFileData(const PVBOXCLIPBOARDFILEDATA pFileData, uint32_t *pcbWritten);
512
513	void Reset(void);
514
515	protected:
516
517	SharedClipboardProviderVbglR3(uint32_t uClientID);
518
519	/** HGCM client ID to use. */
520	uint32_t m_uClientID;
521	};
522
523	/**
524	* Shared Clipboard provider implementation for host service (host side).
525	*/
526	class SharedClipboardProviderHostService : protected SharedClipboardProvider
527	{
528	friend class SharedClipboardProvider;
529
530	public:
531
532	virtual ~SharedClipboardProviderHostService(void);
533
534	protected:
535
536	SharedClipboardProviderHostService(void);
537	};
538
539	struct _SHAREDCLIPBOARDURITRANSFER;
540	typedef _SHAREDCLIPBOARDURITRANSFER *PSHAREDCLIPBOARDURITRANSFER;
541
542	/**
543	* Structure for storing URI transfer callback data.
544	*/
545	typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKDATA
546	{
547	/** Pointer to related URI transfer. */
548	PSHAREDCLIPBOARDURITRANSFER pTransfer;
549	/** Saved user pointer. */
550	void *pvUser;
551	} SHAREDCLIPBOARDURITRANSFERCALLBACKDATA, *PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA;
552
553	typedef DECLCALLBACK(void) FNSHAREDCLIPBOARDURITRANSFERSTARTED(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData);
554	/** Pointer to a FNSHAREDCLIPBOARDURITRANSFERSTARTED function. */
555	typedef FNSHAREDCLIPBOARDURITRANSFERSTARTED *PFNSHAREDCLIPBOARDURITRANSFERSTARTED;
556
557	typedef DECLCALLBACK(void) FNSHAREDCLIPBOARDURITRANSFERCANCELED(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData);
558	/** Pointer to a FNSHAREDCLIPBOARDURITRANSFERCANCELED function. */
559	typedef FNSHAREDCLIPBOARDURITRANSFERCANCELED *PFNSHAREDCLIPBOARDURITRANSFERCANCELED;
560
561	typedef DECLCALLBACK(void) FNSHAREDCLIPBOARDURITRANSFERCOMPLETE(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData, int rc);
562	/** Pointer to a FNSHAREDCLIPBOARDURITRANSFERCOMPLETE function. */
563	typedef FNSHAREDCLIPBOARDURITRANSFERCOMPLETE *PFNSHAREDCLIPBOARDURITRANSFERCOMPLETE;
564
565	typedef DECLCALLBACK(void) FNSHAREDCLIPBOARDURITRANSFERERROR(PSHAREDCLIPBOARDURITRANSFERCALLBACKDATA pData, int rc);
566	/** Pointer to a FNSHAREDCLIPBOARDURITRANSFERERROR function. */
567	typedef FNSHAREDCLIPBOARDURITRANSFERERROR *PFNSHAREDCLIPBOARDURITRANSFERERROR;
568
569	/**
570	* Structure acting as a function callback table for URI transfers.
571	* All callbacks are optional and therefore can be NULL.
572	*/
573	typedef struct _SHAREDCLIPBOARDURITRANSFERCALLBACKS
574	{
575	/** Saved user pointer. */
576	void *pvUser;
577	/** Function pointer, called when the transfer has been started. */
578	PFNSHAREDCLIPBOARDURITRANSFERSTARTED pfnTransferStarted;
579	/** Function pointer, called when the transfer is complete. */
580	PFNSHAREDCLIPBOARDURITRANSFERCOMPLETE pfnTransferComplete;
581	/** Function pointer, called when the transfer has been canceled. */
582	PFNSHAREDCLIPBOARDURITRANSFERCANCELED pfnTransferCanceled;
583	/** Function pointer, called when transfer resulted in an unrecoverable error. */
584	PFNSHAREDCLIPBOARDURITRANSFERERROR pfnTransferError;
585	} SHAREDCLIPBOARDURITRANSFERCALLBACKS, *PSHAREDCLIPBOARDURITRANSFERCALLBACKS;
586
587	/**
588	* Structure for thread-related members for a single URI transfer.
589	*/
590	typedef struct _SHAREDCLIPBOARDURITRANSFERTHREAD
591	{
592	/** Thread handle for the reading / writing thread.
593	* Can be NIL_RTTHREAD if not being used. */
594	RTTHREAD hThread;
595	/** Thread started indicator. */
596	volatile bool fStarted;
597	/** Thread cancelled flag / indicator. */
598	volatile bool fCancelled;
599	} SHAREDCLIPBOARDURITRANSFERTHREAD, *PSHAREDCLIPBOARDURITRANSFERTHREAD;
600
601	/**
602	* Enumeration specifying an URI transfer direction.
603	*/
604	typedef enum _SHAREDCLIPBOARDURITRANSFERDIR
605	{
606	/** Unknown transfer directory. */
607	SHAREDCLIPBOARDURITRANSFERDIR_UNKNOWN = 0,
608	/** Read transfer (from source). */
609	SHAREDCLIPBOARDURITRANSFERDIR_READ,
610	/** Write transfer (to target). */
611	SHAREDCLIPBOARDURITRANSFERDIR_WRITE,
612	/** The usual 32-bit hack. */
613	SHAREDCLIPBOARDURITRANSFERDIR__32BIT_HACK = 0x7fffffff
614	} SHAREDCLIPBOARDURITRANSFERDIR;
615
616	/**
617	* Structure for maintaining a single URI transfer.
618	*
619	** @todo Not yet thread safe.
620	*/
621	typedef struct _SHAREDCLIPBOARDURITRANSFER
622	{
623	/** The node member for using this struct in a RTList. */
624	RTLISTNODE Node;
625	/** Critical section for serializing access. */
626	RTCRITSECT CritSect;
627	/** The transfer's direction. */
628	SHAREDCLIPBOARDURITRANSFERDIR enmDir;
629	/** The transfer's meta data cache. */
630	VBOXCLIPBOARDDATAHDR Header;
631	/** The transfer's meta data cache. */
632	SHAREDCLIPBOARDMETADATA Meta;
633	/** The URI list for this transfer. */
634	SharedClipboardURIList URIList;
635	/** The Shared Clipboard provider in charge for this transfer. */
636	SharedClipboardProvider *pProvider;
637	/** Opaque pointer to implementation-specific parameters. */
638	void *pvUser;
639	/** Size (in bytes) of implementation-specific parameters. */
640	size_t cbUser;
641	/** Contains thread-related attributes. */
642	SHAREDCLIPBOARDURITRANSFERTHREAD Thread;
643	/** (Optional) callbacks related to this transfer. */
644	SHAREDCLIPBOARDURITRANSFERCALLBACKS Callbacks;
645	} SHAREDCLIPBOARDURITRANSFER, *PSHAREDCLIPBOARDURITRANSFER;
646
647	/**
648	* Structure for keeping URI clipboard information around.
649	*/
650	typedef struct _SHAREDCLIPBOARDURICTX
651	{
652	/** Critical section for serializing access. */
653	RTCRITSECT CritSect;
654	/** List of active transfers.
655	* Use a list or something lateron. */
656	RTLISTANCHOR List;
657	/** Number of concurrent transfers.
658	* At the moment we only support only one transfer at a time. */
659	uint32_t cTransfers;
660	} SHAREDCLIPBOARDURICTX, *PSHAREDCLIPBOARDURICTX;
661
662	int SharedClipboardURITransferCreate(SHAREDCLIPBOARDURITRANSFERDIR enmDir, PSHAREDCLIPBOARDPROVIDERCREATIONCTX pCtx,
663	PSHAREDCLIPBOARDURITRANSFER *ppTransfer);
664	int SharedClipboardURITransferDestroy(PSHAREDCLIPBOARDURITRANSFER pTransfer);
665	void SharedClipboardURITransferReset(PSHAREDCLIPBOARDURITRANSFER pTransfer);
666	const SharedClipboardURIObject *SharedClipboardURITransferGetCurrentObject(PSHAREDCLIPBOARDURITRANSFER pTransfer);
667	SharedClipboardProvider *SharedClipboardURITransferGetProvider(PSHAREDCLIPBOARDURITRANSFER pTransfer);
668	const SharedClipboardURIList *SharedClipboardURITransferGetList(PSHAREDCLIPBOARDURITRANSFER pTransfer);
669	const SharedClipboardURIObject *SharedClipboardURITransferGetObject(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint64_t uIdx);
670	void SharedClipboardURITransferSetCallbacks(PSHAREDCLIPBOARDURITRANSFER pTransfer, PSHAREDCLIPBOARDURITRANSFERCALLBACKS pCallbacks);
671	int SharedClipboardURITransferThreadCreate(PSHAREDCLIPBOARDURITRANSFER pTransfer);
672	int SharedClipboardURITransferThreadDestroy(PSHAREDCLIPBOARDURITRANSFER pTransfer, RTMSINTERVAL uTimeoutMs);
673
674	int SharedClipboardURITransferMetaDataAdd(PSHAREDCLIPBOARDURITRANSFER pTransfer, const void *pvMeta, uint32_t cbMeta);
675	int SharedClipboardURITransferMetaGet(PSHAREDCLIPBOARDURITRANSFER pTransfer, const void *pvMeta, uint32_t cbMeta);
676	int SharedClipboardURITransferMetaDataRead(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t *pcbRead);
677	int SharedClipboardURITransferMetaDataWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer, uint32_t *pcbWritten);
678
679	int SharedClipboardURITransferWrite(PSHAREDCLIPBOARDURITRANSFER pTransfer);
680	int SharedClipboardURITransferWriteObjects(PSHAREDCLIPBOARDURITRANSFER pTransfer);
681
682	int SharedClipboardURICtxInit(PSHAREDCLIPBOARDURICTX pURI);
683	void SharedClipboardURICtxDestroy(PSHAREDCLIPBOARDURICTX pURI);
684	void SharedClipboardURICtxReset(PSHAREDCLIPBOARDURICTX pURI);
685	PSHAREDCLIPBOARDURITRANSFER SharedClipboardURICtxGetTransfer(PSHAREDCLIPBOARDURICTX pURI, uint32_t uIdx);
686	uint32_t SharedClipboardURICtxGetActiveTransfers(PSHAREDCLIPBOARDURICTX pURI);
687	int SharedClipboardURICtxTransferAdd(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
688	int SharedClipboardURICtxTransferRemove(PSHAREDCLIPBOARDURICTX pURI, PSHAREDCLIPBOARDURITRANSFER pTransfer);
689
690	bool SharedClipboardMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
691	bool SharedClipboardMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
692
693	#endif /* !VBOX_INCLUDED_GuestHost_SharedClipboard_uri_h */
694

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

source: vbox/trunk/include/VBox/GuestHost/SharedClipboard-uri.h@ 79027

Download in other formats: