summaryrefslogtreecommitdiffstats
path: root/include/VBox/GuestHost/SharedClipboard-transfers.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/VBox/GuestHost/SharedClipboard-transfers.h')
-rw-r--r--include/VBox/GuestHost/SharedClipboard-transfers.h993
1 files changed, 993 insertions, 0 deletions
diff --git a/include/VBox/GuestHost/SharedClipboard-transfers.h b/include/VBox/GuestHost/SharedClipboard-transfers.h
new file mode 100644
index 00000000..2cf6fadd
--- /dev/null
+++ b/include/VBox/GuestHost/SharedClipboard-transfers.h
@@ -0,0 +1,993 @@
+/* $Id: SharedClipboard-transfers.h $ */
+/** @file
+ * Shared Clipboard - Shared transfer functions between host and guest.
+ */
+
+/*
+ * Copyright (C) 2019-2023 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef VBOX_INCLUDED_GuestHost_SharedClipboard_transfers_h
+#define VBOX_INCLUDED_GuestHost_SharedClipboard_transfers_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <map>
+
+#include <iprt/assert.h>
+#include <iprt/critsect.h>
+#include <iprt/fs.h>
+#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
+# include <iprt/http-server.h>
+#endif
+#include <iprt/list.h>
+
+#include <iprt/cpp/list.h>
+#include <iprt/cpp/ministring.h>
+
+#include <VBox/GuestHost/SharedClipboard.h>
+#include <VBox/HostServices/VBoxClipboardSvc.h>
+
+
+struct SHCLTRANSFER;
+/** Pointer to a single shared clipboard transfer */
+typedef struct SHCLTRANSFER *PSHCLTRANSFER;
+
+
+/** @name Shared Clipboard transfer definitions.
+ * @{
+ */
+
+/** Defines the maximum length (in chars) a Shared Clipboard transfer path can have. */
+#define SHCL_TRANSFER_PATH_MAX RTPATH_MAX
+
+/**
+ * Defines the transfer status codes.
+ */
+typedef enum
+{
+ /** No status set. */
+ SHCLTRANSFERSTATUS_NONE = 0,
+ /** The transfer has been initialized but is not running yet. */
+ SHCLTRANSFERSTATUS_INITIALIZED,
+ /** The transfer is active and running. */
+ SHCLTRANSFERSTATUS_STARTED,
+ /** The transfer has been stopped. */
+ SHCLTRANSFERSTATUS_STOPPED,
+ /** The transfer has been canceled. */
+ SHCLTRANSFERSTATUS_CANCELED,
+ /** The transfer has been killed. */
+ SHCLTRANSFERSTATUS_KILLED,
+ /** The transfer ran into an unrecoverable error. */
+ SHCLTRANSFERSTATUS_ERROR,
+ /** The usual 32-bit hack. */
+ SHCLTRANSFERSTATUS_32BIT_SIZE_HACK = 0x7fffffff
+} SHCLTRANSFERSTATUSENUM;
+
+/** Defines a transfer status. */
+typedef uint32_t SHCLTRANSFERSTATUS;
+
+/** @} */
+
+/** @name Shared Clipboard handles.
+ * @{
+ */
+
+/** A Shared Clipboard list handle. */
+typedef uint64_t SHCLLISTHANDLE;
+/** Pointer to a Shared Clipboard list handle. */
+typedef SHCLLISTHANDLE *PSHCLLISTHANDLE;
+/** Specifies an invalid Shared Clipboard list handle.
+ * @todo r=bird: The convention is NIL_SHCLLISTHANDLE. */
+#define SHCLLISTHANDLE_INVALID ((SHCLLISTHANDLE)UINT64_MAX)
+
+/** A Shared Clipboard object handle. */
+typedef uint64_t SHCLOBJHANDLE;
+/** Pointer to a Shared Clipboard object handle. */
+typedef SHCLOBJHANDLE *PSHCLOBJHANDLE;
+/** Specifies an invalid Shared Clipboard object handle.
+ * @todo r=bird: The convention is NIL_SHCLOBJHANDLE. */
+#define SHCLOBJHANDLE_INVALID ((SHCLOBJHANDLE)UINT64_MAX)
+
+/** @} */
+
+/** @name Shared Clipboard open/create flags.
+ * @{
+ */
+/** No flags. Initialization value. */
+#define SHCL_OBJ_CF_NONE UINT32_C(0x00000000)
+
+#if 0 /* These probably won't be needed either */
+/** Lookup only the object, do not return a handle. All other flags are ignored. */
+#define SHCL_OBJ_CF_LOOKUP UINT32_C(0x00000001)
+/** Create/open a directory. */
+#define SHCL_OBJ_CF_DIRECTORY UINT32_C(0x00000004)
+#endif
+
+/** Read/write requested access for the object. */
+#define SHCL_OBJ_CF_ACCESS_MASK_RW UINT32_C(0x00001000)
+/** No access requested. */
+#define SHCL_OBJ_CF_ACCESS_NONE UINT32_C(0x00000000)
+/** Read access requested. */
+#define SHCL_OBJ_CF_ACCESS_READ UINT32_C(0x00001000)
+
+/** Requested share access for the object. */
+#define SHCL_OBJ_CF_ACCESS_MASK_DENY UINT32_C(0x00008000)
+/** Allow any access. */
+#define SHCL_OBJ_CF_ACCESS_DENYNONE UINT32_C(0x00000000)
+/** Do not allow write. */
+#define SHCL_OBJ_CF_ACCESS_DENYWRITE UINT32_C(0x00008000)
+
+/** Requested access to attributes of the object. */
+#define SHCL_OBJ_CF_ACCESS_MASK_ATTR UINT32_C(0x00010000)
+/** No access requested. */
+#define SHCL_OBJ_CF_ACCESS_ATTR_NONE UINT32_C(0x00000000)
+/** Read access requested. */
+#define SHCL_OBJ_CF_ACCESS_ATTR_READ UINT32_C(0x00010000)
+
+/** Valid bits. */
+#define SHCL_OBJ_CF_VALID_MASK UINT32_C(0x00019000)
+/** @} */
+
+/**
+ * The available additional information in a SHCLFSOBJATTR object.
+ * @sa RTFSOBJATTRADD
+ */
+typedef enum _SHCLFSOBJATTRADD
+{
+ /** No additional information is available / requested. */
+ SHCLFSOBJATTRADD_NOTHING = 1,
+ /** The additional unix attributes (SHCLFSOBJATTR::u::Unix) are
+ * available / requested. */
+ SHCLFSOBJATTRADD_UNIX,
+ /** The additional extended attribute size (SHCLFSOBJATTR::u::EASize) is
+ * available / requested. */
+ SHCLFSOBJATTRADD_EASIZE,
+ /** The last valid item (inclusive).
+ * The valid range is SHCLFSOBJATTRADD_NOTHING thru
+ * SHCLFSOBJATTRADD_LAST. */
+ SHCLFSOBJATTRADD_LAST = SHCLFSOBJATTRADD_EASIZE,
+ /** The usual 32-bit hack. */
+ SHCLFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
+} SHCLFSOBJATTRADD;
+
+
+/* Assert sizes of the IRPT types we're using below. */
+AssertCompileSize(RTFMODE, 4);
+AssertCompileSize(RTFOFF, 8);
+AssertCompileSize(RTINODE, 8);
+AssertCompileSize(RTTIMESPEC, 8);
+AssertCompileSize(RTDEV, 4);
+AssertCompileSize(RTUID, 4);
+
+/**
+ * Shared Clipboard filesystem object attributes.
+ *
+ * @sa RTFSOBJATTR
+ */
+typedef struct _SHCLFSOBJATTR
+{
+ /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*.
+ * @remarks We depend on a number of RTFS_ defines to remain unchanged.
+ * Fortuntately, these are depending on windows, dos and unix
+ * standard values, so this shouldn't be much of a pain. */
+ RTFMODE fMode;
+
+ /** The additional attributes available. */
+ SHCLFSOBJATTRADD enmAdditional;
+
+ /**
+ * Additional attributes.
+ *
+ * Unless explicitly specified to an API, the API can provide additional
+ * data as it is provided by the underlying OS.
+ */
+ union SHCLFSOBJATTRUNION
+ {
+ /** Additional Unix Attributes
+ * These are available when SHCLFSOBJATTRADD is set in fUnix.
+ */
+ struct SHCLFSOBJATTRUNIX
+ {
+ /** The user owning the filesystem object (st_uid).
+ * This field is ~0U if not supported. */
+ RTUID uid;
+
+ /** The group the filesystem object is assigned (st_gid).
+ * This field is ~0U if not supported. */
+ RTGID gid;
+
+ /** Number of hard links to this filesystem object (st_nlink).
+ * This field is 1 if the filesystem doesn't support hardlinking or
+ * the information isn't available.
+ */
+ uint32_t cHardlinks;
+
+ /** The device number of the device which this filesystem object resides on (st_dev).
+ * This field is 0 if this information is not available. */
+ RTDEV INodeIdDevice;
+
+ /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
+ * Together with INodeIdDevice, this field can be used as a OS wide unique id
+ * when both their values are not 0.
+ * This field is 0 if the information is not available. */
+ RTINODE INodeId;
+
+ /** User flags (st_flags).
+ * This field is 0 if this information is not available. */
+ uint32_t fFlags;
+
+ /** The current generation number (st_gen).
+ * This field is 0 if this information is not available. */
+ uint32_t GenerationId;
+
+ /** The device number of a character or block device type object (st_rdev).
+ * This field is 0 if the file isn't of a character or block device type and
+ * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
+ RTDEV Device;
+ } Unix;
+
+ /**
+ * Extended attribute size.
+ */
+ struct SHCLFSOBJATTREASIZE
+ {
+ /** Size of EAs. */
+ RTFOFF cb;
+ } EASize;
+
+ /** Padding the structure to a multiple of 8 bytes. */
+ uint64_t au64Padding[5];
+ } u;
+} SHCLFSOBJATTR;
+AssertCompileSize(SHCLFSOBJATTR, 48);
+/** Pointer to a Shared Clipboard filesystem object attributes structure. */
+typedef SHCLFSOBJATTR *PSHCLFSOBJATTR;
+/** Pointer to a const Shared Clipboard filesystem object attributes structure. */
+typedef const SHCLFSOBJATTR *PCSHCLFSOBJATTR;
+
+/**
+ * Shared Clipboard file system object information structure.
+ *
+ * @sa RTFSOBJINFO
+ */
+typedef struct _SHCLFSOBJINFO
+{
+ /** Logical size (st_size).
+ * For normal files this is the size of the file.
+ * For symbolic links, this is the length of the path name contained
+ * in the symbolic link.
+ * For other objects this fields needs to be specified.
+ */
+ RTFOFF cbObject;
+
+ /** Disk allocation size (st_blocks * DEV_BSIZE). */
+ RTFOFF cbAllocated;
+
+ /** Time of last access (st_atime).
+ * @remarks Here (and other places) we depend on the IPRT timespec to
+ * remain unchanged. */
+ RTTIMESPEC AccessTime;
+
+ /** Time of last data modification (st_mtime). */
+ RTTIMESPEC ModificationTime;
+
+ /** Time of last status change (st_ctime).
+ * If not available this is set to ModificationTime.
+ */
+ RTTIMESPEC ChangeTime;
+
+ /** Time of file birth (st_birthtime).
+ * If not available this is set to ChangeTime.
+ */
+ RTTIMESPEC BirthTime;
+
+ /** Attributes. */
+ SHCLFSOBJATTR Attr;
+
+} SHCLFSOBJINFO;
+AssertCompileSize(SHCLFSOBJINFO, 96);
+/** Pointer to a Shared Clipboard filesystem object information structure. */
+typedef SHCLFSOBJINFO *PSHCLFSOBJINFO;
+/** Pointer to a const Shared Clipboard filesystem object information
+ * structure. */
+typedef const SHCLFSOBJINFO *PCSHCLFSOBJINFO;
+
+/**
+ * Structure for keeping object open/create parameters.
+ */
+typedef struct _SHCLOBJOPENCREATEPARMS
+{
+ /** Path to object to open / create. */
+ char *pszPath;
+ /** Size (in bytes) of path to to object. */
+ uint32_t cbPath;
+ /** SHCL_OBJ_CF_* */
+ uint32_t fCreate;
+ /**
+ * Attributes of object to open/create and
+ * returned actual attributes of opened/created object.
+ */
+ SHCLFSOBJINFO ObjInfo;
+} SHCLOBJOPENCREATEPARMS, *PSHCLOBJOPENCREATEPARMS;
+
+/**
+ * Structure for keeping a reply message.
+ */
+typedef struct _SHCLREPLY
+{
+ /** Message type of type VBOX_SHCL_REPLYMSGTYPE_XXX. */
+ uint32_t uType;
+ /** IPRT result of overall operation. Note: int vs. uint32! */
+ uint32_t rc;
+ union
+ {
+ struct
+ {
+ SHCLTRANSFERSTATUS uStatus;
+ } TransferStatus;
+ struct
+ {
+ SHCLLISTHANDLE uHandle;
+ } ListOpen;
+ struct
+ {
+ SHCLLISTHANDLE uHandle;
+ } ListClose;
+ struct
+ {
+ SHCLOBJHANDLE uHandle;
+ } ObjOpen;
+ struct
+ {
+ SHCLOBJHANDLE uHandle;
+ } ObjClose;
+ } u;
+ /** Pointer to optional payload. */
+ void *pvPayload;
+ /** Payload size (in bytes). */
+ uint32_t cbPayload;
+} SHCLREPLY, *PSHCLREPLY;
+
+struct _SHCLLISTENTRY;
+typedef _SHCLLISTENTRY SHCLLISTENTRY;
+
+/** Defines a single root list entry. Currently the same as a regular list entry. */
+typedef SHCLLISTENTRY SHCLROOTLISTENTRY;
+/** Defines a pointer to a single root list entry. Currently the same as a regular list entry pointer. */
+typedef SHCLROOTLISTENTRY *PSHCLROOTLISTENTRY;
+
+/**
+ * Structure for keeping Shared Clipboard root list headers.
+ */
+typedef struct _SHCLROOTLISTHDR
+{
+ /** Roots listing flags; unused at the moment. */
+ uint32_t fRoots;
+ /** Number of root list entries. */
+ uint32_t cRoots;
+} SHCLROOTLISTHDR, *PSHCLROOTLISTHDR;
+
+/**
+ * Structure for maintaining a Shared Clipboard root list.
+ */
+typedef struct _SHCLROOTLIST
+{
+ /** Root list header. */
+ SHCLROOTLISTHDR Hdr;
+ /** Root list entries. */
+ SHCLROOTLISTENTRY *paEntries;
+} SHCLROOTLIST, *PSHCLROOTLIST;
+
+/**
+ * Structure for maintaining Shared Clipboard list open paramters.
+ */
+typedef struct _SHCLLISTOPENPARMS
+{
+ /** Listing flags (see VBOX_SHCL_LIST_FLAG_XXX). */
+ uint32_t fList;
+ /** Size (in bytes) of the filter string. */
+ uint32_t cbFilter;
+ /** Filter string. DOS wilcard-style. */
+ char *pszFilter;
+ /** Size (in bytes) of the listing path. */
+ uint32_t cbPath;
+ /** Listing path (absolute). If empty or NULL the listing's root path will be opened. */
+ char *pszPath;
+} SHCLLISTOPENPARMS, *PSHCLLISTOPENPARMS;
+
+/**
+ * Structure for keeping a Shared Clipboard list header.
+ */
+typedef struct _SHCLLISTHDR
+{
+ /** Feature flag(s). Not being used atm. */
+ uint32_t fFeatures;
+ /** Total objects returned. */
+ uint64_t cTotalObjects;
+ /** Total size (in bytes) returned. */
+ uint64_t cbTotalSize;
+} SHCLLISTHDR, *PSHCLLISTHDR;
+
+/**
+ * Structure for a Shared Clipboard list entry.
+ */
+typedef struct _SHCLLISTENTRY
+{
+ /** Entry name. */
+ char *pszName;
+ /** Size (in bytes) of entry name. */
+ uint32_t cbName;
+ /** Information flag(s). */
+ uint32_t fInfo;
+ /** Size (in bytes) of the actual list entry. */
+ uint32_t cbInfo;
+ /** Data of the actual list entry. */
+ void *pvInfo;
+} SHCLLISTENTRY, *PSHCLLISTENTRY;
+
+/** Maximum length (in UTF-8 characters) of a list entry name. */
+#define SHCLLISTENTRY_MAX_NAME RTPATH_MAX /** @todo Improve this to be more dynamic. */
+
+/**
+ * Structure for maintaining a Shared Clipboard list.
+ */
+typedef struct _SHCLLIST
+{
+ /** List header. */
+ SHCLLISTHDR Hdr;
+ /** List entries. */
+ SHCLROOTLISTENTRY *paEntries;
+} SHCLLIST, *PSHCLLIST;
+
+/**
+ * Structure for keeping a Shared Clipboard object data chunk.
+ */
+typedef struct _SHCLOBJDATACHUNK
+{
+ /** Handle of object this data chunk is related to. */
+ uint64_t uHandle;
+ /** Pointer to actual data chunk. */
+ void *pvData;
+ /** Size (in bytes) of data chunk. */
+ uint32_t cbData;
+} SHCLOBJDATACHUNK, *PSHCLOBJDATACHUNK;
+
+/**
+ * Structure for handling a single transfer object context.
+ */
+typedef struct _SHCLCLIENTTRANSFEROBJCTX
+{
+ SHCLTRANSFER *pTransfer;
+ SHCLOBJHANDLE uHandle;
+} SHCLCLIENTTRANSFEROBJCTX, *PSHCLCLIENTTRANSFEROBJCTX;
+
+typedef struct _SHCLTRANSFEROBJSTATE
+{
+ /** How many bytes were processed (read / write) so far. */
+ uint64_t cbProcessed;
+} SHCLTRANSFEROBJSTATE, *PSHCLTRANSFEROBJSTATE;
+
+typedef struct _SHCLTRANSFEROBJ
+{
+ SHCLOBJHANDLE uHandle;
+ char *pszPathAbs;
+ SHCLFSOBJINFO objInfo;
+ SHCLSOURCE enmSource;
+ SHCLTRANSFEROBJSTATE State;
+} SHCLTRANSFEROBJ, *PSHCLTRANSFEROBJ;
+
+/**
+ * Enumeration for specifying a Shared Clipboard object type.
+ */
+typedef enum _SHCLOBJTYPE
+{
+ /** Invalid object type. */
+ SHCLOBJTYPE_INVALID = 0,
+ /** Object is a directory. */
+ SHCLOBJTYPE_DIRECTORY,
+ /** Object is a file. */
+ SHCLOBJTYPE_FILE,
+ /** Object is a symbolic link. */
+ SHCLOBJTYPE_SYMLINK,
+ /** The usual 32-bit hack. */
+ SHCLOBJTYPE_32BIT_SIZE_HACK = 0x7fffffff
+} SHCLOBJTYPE;
+
+/**
+ * Structure for keeping transfer list handle information.
+ * This is using to map own (local) handles to the underlying file system.
+ */
+typedef struct _SHCLLISTHANDLEINFO
+{
+ /** The list node. */
+ RTLISTNODE Node;
+ /** The list's handle. */
+ SHCLLISTHANDLE hList;
+ /** Type of list handle. */
+ SHCLOBJTYPE enmType;
+ /** Absolute local path of the list object. */
+ char *pszPathLocalAbs;
+ union
+ {
+ /** Local data, based on enmType. */
+ struct
+ {
+ union
+ {
+ RTDIR hDir;
+ RTFILE hFile;
+ };
+ } Local;
+ } u;
+} SHCLLISTHANDLEINFO, *PSHCLLISTHANDLEINFO;
+
+/**
+ * Structure for keeping transfer object handle information.
+ * This is using to map own (local) handles to the underlying file system.
+ */
+typedef struct _SHCLOBJHANDLEINFO
+{
+ /** The list node. */
+ RTLISTNODE Node;
+ /** The object's handle. */
+ SHCLOBJHANDLE hObj;
+ /** Type of object handle. */
+ SHCLOBJTYPE enmType;
+ /** Absolute local path of the object. */
+ char *pszPathLocalAbs;
+ union
+ {
+ /** Local data, based on enmType. */
+ struct
+ {
+ union
+ {
+ RTDIR hDir;
+ RTFILE hFile;
+ };
+ } Local;
+ } u;
+} SHCLOBJHANDLEINFO, *PSHCLOBJHANDLEINFO;
+
+/**
+ * Structure for keeping a single root list entry.
+ */
+typedef struct _SHCLLISTROOT
+{
+ /** The list node. */
+ RTLISTNODE Node;
+ /** Absolute path of entry. */
+ char *pszPathAbs;
+} SHCLLISTROOT, *PSHCLLISTROOT;
+
+/**
+ * Structure for maintaining an Shared Clipboard transfer state.
+ * Everything in here will be part of a saved state (later).
+ */
+typedef struct _SHCLTRANSFERSTATE
+{
+ /** The transfer's (local) ID. */
+ SHCLTRANSFERID uID;
+ /** The transfer's current status. */
+ SHCLTRANSFERSTATUS enmStatus;
+ /** The transfer's direction, seen from the perspective who created the transfer. */
+ SHCLTRANSFERDIR enmDir;
+ /** The transfer's source, seen from the perspective who created the transfer. */
+ SHCLSOURCE enmSource;
+} SHCLTRANSFERSTATE, *PSHCLTRANSFERSTATE;
+
+/**
+ * Structure maintaining clipboard transfer provider context data.
+ * This is handed in to the provider interface implementations.
+ */
+typedef struct _SHCLTXPROVIDERCTX
+{
+ /** Pointer to the related Shared Clipboard transfer. */
+ PSHCLTRANSFER pTransfer;
+ /** User-defined data pointer. Can be NULL if not needed. */
+ void *pvUser;
+ /** Size (in bytes) of data at user pointer. */
+ size_t cbUser;
+} SHCLTXPROVIDERCTX, *PSHCLTXPROVIDERCTX;
+
+struct SHCLTRANSFERCTX;
+typedef struct SHCLTRANSFERCTX *PSHCLTRANSFERCTX;
+
+/**
+ * Shared Clipboard transfer provider interface table.
+ *
+ * A transfer provider inteface implementation realizes all low level functions
+ * needed for making a Shared Clipboard transfer happen.
+ */
+typedef struct _SHCLTXPROVIDERIFACE
+{
+ DECLCALLBACKMEMBER(int, pfnRootsGet,(PSHCLTXPROVIDERCTX pCtx, PSHCLROOTLIST *ppRootList));
+ DECLCALLBACKMEMBER(int, pfnListOpen,(PSHCLTXPROVIDERCTX pCtx, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList));
+ DECLCALLBACKMEMBER(int, pfnListClose,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList));
+ DECLCALLBACKMEMBER(int, pfnListHdrRead,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
+ DECLCALLBACKMEMBER(int, pfnListHdrWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTHDR pListHdr));
+ DECLCALLBACKMEMBER(int, pfnListEntryRead,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry));
+ DECLCALLBACKMEMBER(int, pfnListEntryWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry));
+ DECLCALLBACKMEMBER(int, pfnObjOpen,(PSHCLTXPROVIDERCTX pCtx, PSHCLOBJOPENCREATEPARMS pCreateParms, PSHCLOBJHANDLE phObj));
+ DECLCALLBACKMEMBER(int, pfnObjClose,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj));
+ DECLCALLBACKMEMBER(int, pfnObjRead,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
+ uint32_t fFlags, uint32_t *pcbRead));
+ DECLCALLBACKMEMBER(int, pfnObjWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
+ uint32_t fFlags, uint32_t *pcbWritten));
+} SHCLTXPROVIDERIFACE, *PSHCLTXPROVIDERIFACE;
+
+/**
+ * Structure for the Shared Clipboard transfer provider creation context.
+ */
+typedef struct _SHCLTXPROVIDERCREATIONCTX
+{
+ /** Specifies what the source of the provider is. */
+ SHCLSOURCE enmSource;
+ /** The provider interface table. */
+ SHCLTXPROVIDERIFACE Interface;
+ /** User-provided callback data. */
+ void *pvUser;
+ /** Size (in bytes) of data at user pointer. */
+ size_t cbUser;
+} SHCLTXPROVIDERCREATIONCTX, *PSHCLTXPROVIDERCREATIONCTX;
+
+/**
+ * Structure maintaining clipboard transfer callback context data.
+ */
+typedef struct _SHCLTRANSFERCALLBACKCTX
+{
+ /** Pointer to the related Shared Clipboard transfer. */
+ PSHCLTRANSFER pTransfer;
+ /** User-defined data pointer. Can be NULL if not needed. */
+ void *pvUser;
+ /** Size (in bytes) of data at user pointer. */
+ size_t cbUser;
+} SHCLTRANSFERCALLBACKCTX, *PSHCLTRANSFERCALLBACKCTX;
+
+/**
+ * Shared Clipboard transfer callback table.
+ *
+ * All callbacks are optional and can provide additional information / feedback to a frontend.
+ */
+typedef struct _SHCLTRANSFERCALLBACKTABLE
+{
+ /**
+ * Called when the transfer gets initialized.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ */
+ DECLCALLBACKMEMBER(int, pfnOnInitialize,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
+ /**
+ * Called before the transfer will be started.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ */
+ DECLCALLBACKMEMBER(int, pfnOnStart,(PSHCLTRANSFERCALLBACKCTX pCbCtx));
+ /**
+ * Called when the transfer has been complete.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ * @param rcCompletion Completion result.
+ * VERR_CANCELED if transfer has been canceled.
+ */
+ DECLCALLBACKMEMBER(void, pfnOnCompleted,(PSHCLTRANSFERCALLBACKCTX pCbCtx, int rcCompletion));
+ /**
+ * Called when transfer resulted in an unrecoverable error.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ * @param rcError Error reason, IPRT-style.
+ */
+ DECLCALLBACKMEMBER(void, pfnOnError,(PSHCLTRANSFERCALLBACKCTX pCbCtx, int rcError));
+ /**
+ * Called when transfer got registered to a transfer context.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ * @param pTransferCtx Transfer context transfer was registered to.
+ */
+ DECLCALLBACKMEMBER(void, pfnOnRegistered,(PSHCLTRANSFERCALLBACKCTX pCbCtx, PSHCLTRANSFERCTX pTransferCtx));
+ /**
+ * Called when transfer got unregistered from a transfer context.
+ *
+ * @param pCbCtx Pointer to callback context to use.
+ * @param pTransferCtx Transfer context transfer was unregistered from.
+ */
+ DECLCALLBACKMEMBER(void, pfnOnUnregistered,(PSHCLTRANSFERCALLBACKCTX pCbCtx, PSHCLTRANSFERCTX pTransferCtx));
+
+ /** User-provided callback data. Can be NULL if not used. */
+ void *pvUser;
+ /** Size (in bytes) of data pointer at \a pvUser. */
+ size_t cbUser;
+} SHCLTRANSFERCALLBACKTABLE, *PSHCLTRANSFERCALLBACKTABLE;
+
+/**
+ * Structure for thread-related members for a single Shared Clipboard transfer.
+ */
+typedef struct _SHCLTRANSFERTHREAD
+{
+ /** Thread handle for the reading / writing thread.
+ * Can be NIL_RTTHREAD if not being used. */
+ RTTHREAD hThread;
+ /** Thread started indicator. */
+ volatile bool fStarted;
+ /** Thread stop flag. */
+ volatile bool fStop;
+ /** Thread cancelled flag / indicator. */
+ volatile bool fCancelled;
+} SHCLTRANSFERTHREAD, *PSHCLTRANSFERTHREAD;
+
+/**
+ * A single Shared Clipboard transfer.
+ *
+ ** @todo Not yet thread safe.
+ */
+typedef struct SHCLTRANSFER
+{
+ /** The node member for using this struct in a RTList. */
+ RTLISTNODE Node;
+ /** The transfer's state (for SSM, later). */
+ SHCLTRANSFERSTATE State;
+ /** Absolute path to root entries. */
+ char *pszPathRootAbs;
+ /** Timeout (in ms) for waiting of events. Default is 30s. */
+ RTMSINTERVAL uTimeoutMs;
+ /** Maximum data chunk size (in bytes) to transfer. Default is 64K. */
+ uint32_t cbMaxChunkSize;
+ /** The transfer's own event source. */
+ SHCLEVENTSOURCE Events;
+ /** Current number of concurrent list handles. */
+ uint32_t cListHandles;
+ /** Maximum number of concurrent list handles. */
+ uint32_t cMaxListHandles;
+ /** Next upcoming list handle. */
+ SHCLLISTHANDLE uListHandleNext;
+ /** List of all list handles elated to this transfer. */
+ RTLISTANCHOR lstList;
+ /** Number of root entries in list. */
+ uint64_t cRoots;
+ /** List of root entries of this transfer. */
+ RTLISTANCHOR lstRoots;
+ /** Current number of concurrent object handles. */
+ uint32_t cObjHandles;
+ /** Maximum number of concurrent object handles. */
+ uint32_t cMaxObjHandles;
+ /** Next upcoming object handle. */
+ SHCLOBJHANDLE uObjHandleNext;
+ /** Map of all objects handles related to this transfer. */
+ RTLISTANCHOR lstObj;
+ /** The transfer's own provider context. */
+ SHCLTXPROVIDERCTX ProviderCtx;
+ /** The transfer's provider interface. */
+ SHCLTXPROVIDERIFACE ProviderIface;
+ /** The transfer's callback context. */
+ SHCLTRANSFERCALLBACKCTX CallbackCtx;
+ /** The transfer's callback table. */
+ SHCLTRANSFERCALLBACKTABLE Callbacks;
+ /** Opaque pointer to implementation-specific parameters. */
+ void *pvUser;
+ /** Size (in bytes) of implementation-specific parameters. */
+ size_t cbUser;
+ /** Contains thread-related attributes. */
+ SHCLTRANSFERTHREAD Thread;
+ /** Critical section for serializing access. */
+ RTCRITSECT CritSect;
+} SHCLTRANSFER, *PSHCLTRANSFER;
+
+/**
+ * Structure for keeping an Shared Clipboard transfer status report.
+ */
+typedef struct _SHCLTRANSFERREPORT
+{
+ /** Actual status to report. */
+ SHCLTRANSFERSTATUS uStatus;
+ /** Result code (rc) to report; might be unused / invalid, based on enmStatus. */
+ int rc;
+ /** Reporting flags. Currently unused and must be 0. */
+ uint32_t fFlags;
+} SHCLTRANSFERREPORT, *PSHCLTRANSFERREPORT;
+
+#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
+typedef struct _SHCLHTTPSERVER
+{
+ /** Critical section for serializing access. */
+ RTCRITSECT CritSect;
+ /** Handle of the HTTP server instance. */
+ RTHTTPSERVER hHTTPServer;
+ /** Port number the HTTP server is running on. 0 if not running. */
+ uint16_t uPort;
+ /** List of registered HTTP transfers. */
+ RTLISTANCHOR lstTransfers;
+ /** Number of registered HTTP transfers. */
+ uint32_t cTransfers;
+ /** Cached response data. */
+ RTHTTPSERVERRESP Resp;
+} SHCLHTTPSERVER;
+typedef SHCLHTTPSERVER *PSHCLHTTPSERVER;
+
+typedef struct _SHCLHTTPCONTEXT
+{
+ /** HTTP server instance data. */
+ SHCLHTTPSERVER HttpServer;
+} SHCLHTTPCONTEXT;
+typedef SHCLHTTPCONTEXT *PSHCLHTTPCONTEXT;
+
+#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP */
+
+/**
+ * Structure for keeping Shared Clipboard transfer context around.
+ */
+struct SHCLTRANSFERCTX
+{
+ /** Critical section for serializing access. */
+ RTCRITSECT CritSect;
+ /** List of transfers. */
+ RTLISTANCHOR List;
+ /** Transfer ID allocation bitmap; clear bits are free, set bits are busy. */
+ uint64_t bmTransferIds[VBOX_SHCL_MAX_TRANSFERS / sizeof(uint64_t) / 8];
+ /** Number of running (concurrent) transfers. */
+ uint16_t cRunning;
+ /** Maximum Number of running (concurrent) transfers. */
+ uint16_t cMaxRunning;
+ /** Number of total transfers (in list). */
+ uint16_t cTransfers;
+#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
+ /** HTTP server instance for this transfer context. */
+ SHCLHTTPSERVER HttpServer;
+#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP */
+};
+
+int ShClTransferObjCtxInit(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
+void ShClTransferObjCtxDestroy(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
+bool ShClTransferObjCtxIsValid(PSHCLCLIENTTRANSFEROBJCTX pObjCtx);
+
+int ShClTransferObjHandleInfoInit(PSHCLOBJHANDLEINFO pInfo);
+void ShClTransferObjHandleInfoDestroy(PSHCLOBJHANDLEINFO pInfo);
+
+int ShClTransferObjOpenParmsInit(PSHCLOBJOPENCREATEPARMS pParms);
+int ShClTransferObjOpenParmsCopy(PSHCLOBJOPENCREATEPARMS pParmsDst, PSHCLOBJOPENCREATEPARMS pParmsSrc);
+void ShClTransferObjOpenParmsDestroy(PSHCLOBJOPENCREATEPARMS pParms);
+
+int ShClTransferObjOpen(PSHCLTRANSFER pTransfer, PSHCLOBJOPENCREATEPARMS pOpenCreateParms, PSHCLOBJHANDLE phObj);
+int ShClTransferObjClose(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj);
+int ShClTransferObjRead(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t fFlags, uint32_t *pcbRead);
+int ShClTransferObjWrite(PSHCLTRANSFER pTransfer, SHCLOBJHANDLE hObj, void *pvBuf, uint32_t cbBuf, uint32_t fFlags, uint32_t *pcbWritten);
+
+PSHCLOBJDATACHUNK ShClTransferObjDataChunkDup(PSHCLOBJDATACHUNK pDataChunk);
+void ShClTransferObjDataChunkDestroy(PSHCLOBJDATACHUNK pDataChunk);
+void ShClTransferObjDataChunkFree(PSHCLOBJDATACHUNK pDataChunk);
+
+int ShClTransferCreate(PSHCLTRANSFER *ppTransfer);
+int ShClTransferInit(PSHCLTRANSFER pTransfer, SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource);
+int ShClTransferDestroy(PSHCLTRANSFER pTransfer);
+
+int ShClTransferListOpen(PSHCLTRANSFER pTransfer, PSHCLLISTOPENPARMS pOpenParms, PSHCLLISTHANDLE phList);
+int ShClTransferListClose(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
+int ShClTransferListGetHeader(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTHDR pHdr);
+PSHCLTRANSFEROBJ ShClTransferListGetObj(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, uint64_t uIdx);
+int ShClTransferListRead(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
+int ShClTransferListWrite(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList, PSHCLLISTENTRY pEntry);
+bool ShClTransferListHandleIsValid(PSHCLTRANSFER pTransfer, SHCLLISTHANDLE hList);
+
+int ShClPathSanitizeFilename(char *pszPath, size_t cbPath);
+int ShClPathSanitize(char *pszPath, size_t cbPath);
+
+PSHCLROOTLIST ShClTransferRootListAlloc(void);
+void ShClTransferRootListFree(PSHCLROOTLIST pRootList);
+
+PSHCLROOTLISTHDR ShClTransferRootListHdrDup(PSHCLROOTLISTHDR pRoots);
+int ShClTransferRootListHdrInit(PSHCLROOTLISTHDR pRoots);
+void ShClTransferRootListHdrDestroy(PSHCLROOTLISTHDR pRoots);
+
+int ShClTransferRootListEntryCopy(PSHCLROOTLISTENTRY pDst, PSHCLROOTLISTENTRY pSrc);
+int ShClTransferRootListEntryInit(PSHCLROOTLISTENTRY pRootListEntry);
+void ShClTransferRootListEntryDestroy(PSHCLROOTLISTENTRY pRootListEntry);
+PSHCLROOTLISTENTRY ShClTransferRootListEntryDup(PSHCLROOTLISTENTRY pRootListEntry);
+
+int ShClTransferListHandleInfoInit(PSHCLLISTHANDLEINFO pInfo);
+void ShClTransferListHandleInfoDestroy(PSHCLLISTHANDLEINFO pInfo);
+
+int ShClTransferListHdrAlloc(PSHCLLISTHDR *ppListHdr);
+void ShClTransferListHdrFree(PSHCLLISTHDR pListHdr);
+PSHCLLISTHDR ShClTransferListHdrDup(PSHCLLISTHDR pListHdr);
+int ShClTransferListHdrInit(PSHCLLISTHDR pListHdr);
+void ShClTransferListHdrDestroy(PSHCLLISTHDR pListHdr);
+void ShClTransferListHdrReset(PSHCLLISTHDR pListHdr);
+bool ShClTransferListHdrIsValid(PSHCLLISTHDR pListHdr);
+
+int ShClTransferListOpenParmsCopy(PSHCLLISTOPENPARMS pDst, PSHCLLISTOPENPARMS pSrc);
+PSHCLLISTOPENPARMS ShClTransferListOpenParmsDup(PSHCLLISTOPENPARMS pParms);
+int ShClTransferListOpenParmsInit(PSHCLLISTOPENPARMS pParms);
+void ShClTransferListOpenParmsDestroy(PSHCLLISTOPENPARMS pParms);
+
+int ShClTransferListEntryAlloc(PSHCLLISTENTRY *ppListEntry);
+void ShClTransferListEntryFree(PSHCLLISTENTRY pListEntry);
+int ShClTransferListEntryCopy(PSHCLLISTENTRY pDst, PSHCLLISTENTRY pSrc);
+PSHCLLISTENTRY ShClTransferListEntryDup(PSHCLLISTENTRY pListEntry);
+int ShClTransferListEntryInit(PSHCLLISTENTRY pListEntry);
+void ShClTransferListEntryDestroy(PSHCLLISTENTRY pListEntry);
+bool ShClTransferListEntryIsValid(PSHCLLISTENTRY pListEntry);
+
+void ShClTransferCopyCallbacks(PSHCLTRANSFERCALLBACKTABLE pCallbacksDst, PSHCLTRANSFERCALLBACKTABLE pCallbacksSrc);
+void ShClTransferSetCallbacks(PSHCLTRANSFER pTransfer, PSHCLTRANSFERCALLBACKTABLE pCallbacks);
+int ShClTransferSetProviderIface(PSHCLTRANSFER pTransfer, PSHCLTXPROVIDERCREATIONCTX pCreationCtx);
+int ShClTransferRootsSet(PSHCLTRANSFER pTransfer, const char *pszRoots, size_t cbRoots);
+void ShClTransferReset(PSHCLTRANSFER pTransfer);
+
+uint32_t ShClTransferRootsCount(PSHCLTRANSFER pTransfer);
+int ShClTransferRootsEntry(PSHCLTRANSFER pTransfer, uint64_t uIndex, PSHCLROOTLISTENTRY pEntry);
+int ShClTransferRootsGet(PSHCLTRANSFER pTransfer, PSHCLROOTLIST *ppRootList);
+
+SHCLTRANSFERID ShClTransferGetID(PSHCLTRANSFER pTransfer);
+SHCLTRANSFERDIR ShClTransferGetDir(PSHCLTRANSFER pTransfer);
+SHCLSOURCE ShClTransferGetSource(PSHCLTRANSFER pTransfer);
+SHCLTRANSFERSTATUS ShClTransferGetStatus(PSHCLTRANSFER pTransfer);
+int ShClTransferRun(PSHCLTRANSFER pTransfer, PFNRTTHREAD pfnThreadFunc, void *pvUser);
+int ShClTransferStart(PSHCLTRANSFER pTransfer);
+
+int ShClTransferCtxInit(PSHCLTRANSFERCTX pTransferCtx);
+void ShClTransferCtxDestroy(PSHCLTRANSFERCTX pTransferCtx);
+void ShClTransferCtxReset(PSHCLTRANSFERCTX pTransferCtx);
+PSHCLTRANSFER ShClTransferCtxGetTransferById(PSHCLTRANSFERCTX pTransferCtx, uint32_t uID);
+PSHCLTRANSFER ShClTransferCtxGetTransferByIndex(PSHCLTRANSFERCTX pTransferCtx, uint32_t uIdx);
+uint32_t ShClTransferCtxGetRunningTransfers(PSHCLTRANSFERCTX pTransferCtx);
+uint32_t ShClTransferCtxGetTotalTransfers(PSHCLTRANSFERCTX pTransferCtx);
+void ShClTransferCtxCleanup(PSHCLTRANSFERCTX pTransferCtx);
+bool ShClTransferCtxTransfersMaximumReached(PSHCLTRANSFERCTX pTransferCtx);
+int ShClTransferCtxTransferRegister(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERID *pidTransfer);
+int ShClTransferCtxTransferRegisterById(PSHCLTRANSFERCTX pTransferCtx, PSHCLTRANSFER pTransfer, SHCLTRANSFERID idTransfer);
+int ShClTransferCtxTransferUnregister(PSHCLTRANSFERCTX pTransferCtx, SHCLTRANSFERID idTransfer);
+
+#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
+int ShClHttpTransferRegister(PSHCLHTTPCONTEXT pCtx, PSHCLTRANSFER pTransfer);
+int ShClHttpTransferUnregister(PSHCLHTTPCONTEXT pCtx, PSHCLTRANSFER pTransfer);
+
+int ShClTransferHttpServerCreate(PSHCLHTTPSERVER pSrv, uint16_t *puPort);
+int ShClTransferHttpServerCreateEx(PSHCLHTTPSERVER pSrv, uint16_t uPort);
+int ShClTransferHttpServerDestroy(PSHCLHTTPSERVER pSrv);
+void ShClTransferHttpServerInit(PSHCLHTTPSERVER pSrv);
+int ShClTransferHttpServerRegisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer);
+int ShClTransferHttpServerUnregisterTransfer(PSHCLHTTPSERVER pSrv, PSHCLTRANSFER pTransfer);
+bool ShClTransferHttpServerHasTransfer(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer);
+uint16_t ShClTransferHttpServerGetPort(PSHCLHTTPSERVER pSrv);
+uint32_t ShClTransferHttpServerGetTransferCount(PSHCLHTTPSERVER pSrv);
+char *ShClTransferHttpServerGetAddressA(PSHCLHTTPSERVER pSrv);
+char *ShClTransferHttpServerGetUrlA(PSHCLHTTPSERVER pSrv, SHCLTRANSFERID idTransfer);
+bool ShClTransferHttpServerIsRunning(PSHCLHTTPSERVER pSrv);
+#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP */
+
+void ShClFsObjFromIPRT(PSHCLFSOBJINFO pDst, PCRTFSOBJINFO pSrc);
+
+bool ShClMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax);
+bool ShClMIMENeedsCache(const char *pcszFormat, size_t cchFormatMax);
+
+const char *ShClTransferStatusToStr(SHCLTRANSFERSTATUS enmStatus);
+
+#endif /* !VBOX_INCLUDED_GuestHost_SharedClipboard_transfers_h */