diff options
Diffstat (limited to 'include/VBox/HostServices/VBoxHostChannel.h')
| -rw-r--r-- | include/VBox/HostServices/VBoxHostChannel.h | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/include/VBox/HostServices/VBoxHostChannel.h b/include/VBox/HostServices/VBoxHostChannel.h new file mode 100644 index 00000000..7ac452de --- /dev/null +++ b/include/VBox/HostServices/VBoxHostChannel.h @@ -0,0 +1,229 @@ +/** @file + * + * Host Channel: the service definition. + */ + +/* + * Copyright (C) 2012-2022 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_HostServices_VBoxHostChannel_h +#define VBOX_INCLUDED_HostServices_VBoxHostChannel_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <VBox/VMMDevCoreTypes.h> +#include <VBox/VBoxGuestCoreTypes.h> +#include <VBox/hgcmsvc.h> + +/* + * Host calls. + */ +#define VBOX_HOST_CHANNEL_HOST_FN_REGISTER 1 +#define VBOX_HOST_CHANNEL_HOST_FN_UNREGISTER 2 + +/* + * Guest calls. + */ +#define VBOX_HOST_CHANNEL_FN_ATTACH 1 /* Attach to a channel. */ +#define VBOX_HOST_CHANNEL_FN_DETACH 2 /* Detach from the channel. */ +#define VBOX_HOST_CHANNEL_FN_SEND 3 /* Send data to the host. */ +#define VBOX_HOST_CHANNEL_FN_RECV 4 /* Receive data from the host. */ +#define VBOX_HOST_CHANNEL_FN_CONTROL 5 /* Generic data exchange using a channel instance. */ +#define VBOX_HOST_CHANNEL_FN_EVENT_WAIT 6 /* Blocking wait for a host event. */ +#define VBOX_HOST_CHANNEL_FN_EVENT_CANCEL 7 /* Cancel the blocking wait. */ +#define VBOX_HOST_CHANNEL_FN_QUERY 8 /* Generic data exchange using a channel name. */ + +/* + * The host event ids for the guest. + */ +#define VBOX_HOST_CHANNEL_EVENT_CANCELLED 0 /* Event was cancelled by FN_EVENT_CANCEL. */ +#define VBOX_HOST_CHANNEL_EVENT_UNREGISTERED 1 /* Channel was unregistered on host. */ +#define VBOX_HOST_CHANNEL_EVENT_RECV 2 /* Data is available for receiving. */ +#define VBOX_HOST_CHANNEL_EVENT_USER 1000 /* Base of channel specific events. */ + +/* + * The common control code ids for the VBOX_HOST_CHANNEL_FN_[CONTROL|QUERY] + */ +#define VBOX_HOST_CHANNEL_CTRL_EXISTS 0 /* Whether the channel instance or provider exists. */ +#define VBOX_HOST_CHANNEL_CTRL_USER 1000 /* Base of channel specific events. */ + +#pragma pack(1) + +/* Parameter of VBOX_HOST_CHANNEL_EVENT_RECV */ +typedef struct VBOXHOSTCHANNELEVENTRECV +{ + uint32_t u32SizeAvailable; /* How many bytes can be read from the channel. */ +} VBOXHOSTCHANNELEVENTRECV; + +/* + * Guest calls. + */ + +typedef struct VBoxHostChannelAttach +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */ + HGCMFunctionParameter flags; /* IN uint32_t: Channel specific flags. */ + HGCMFunctionParameter handle; /* OUT uint32_t: The channel handle. */ +} VBoxHostChannelAttach; + +typedef struct VBoxHostChannelDetach +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ +} VBoxHostChannelDetach; + +typedef struct VBoxHostChannelSend +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter data; /* IN linear pointer: Data to be sent. */ +} VBoxHostChannelSend; + +typedef struct VBoxHostChannelRecv +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for data to be received. */ + HGCMFunctionParameter sizeReceived; /* OUT uint32_t: Bytes received. */ + HGCMFunctionParameter sizeRemaining; /* OUT uint32_t: Bytes remaining in the channel. */ +} VBoxHostChannelRecv; + +typedef struct VBoxHostChannelControl +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */ + HGCMFunctionParameter code; /* IN uint32_t: The channel specific control code. */ + HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */ + HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */ +} VBoxHostChannelControl; + +typedef struct VBoxHostChannelEventWait +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter handle; /* OUT uint32_t: The channel which generated the event. */ + HGCMFunctionParameter id; /* OUT uint32_t: The event VBOX_HOST_CHANNEL_EVENT_*. */ + HGCMFunctionParameter parm; /* OUT linear pointer: Parameters of the event. */ + HGCMFunctionParameter sizeReturned; /* OUT uint32_t: Size of the parameters. */ +} VBoxHostChannelEventWait; + +typedef struct VBoxHostChannelEventCancel +{ + VBGLIOCHGCMCALL hdr; +} VBoxHostChannelEventCancel; + +typedef struct VBoxHostChannelQuery +{ + VBGLIOCHGCMCALL hdr; + HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */ + HGCMFunctionParameter code; /* IN uint32_t: The control code. */ + HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */ + HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */ + HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */ +} VBoxHostChannelQuery; + + +/* + * Host calls + */ + +typedef struct VBoxHostChannelHostRegister +{ + VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated. */ + VBOXHGCMSVCPARM iface; /* IN ptr: VBOXHOSTCHANNELINTERFACE. */ +} VBoxHostChannelHostRegister; + +typedef struct VBoxHostChannelHostUnregister +{ + VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated */ +} VBoxHostChannelHostUnregister; + +/* The channel provider will invoke this callback to report channel events. */ +typedef struct VBOXHOSTCHANNELCALLBACKS +{ + /* A channel event occured. + * + * @param pvCallbacks The callback context specified in HostChannelAttach. + * @param pvChannel The channel instance returned by HostChannelAttach. + * @param u32Id The event id. + * @param pvEvent The event parameters. + * @param cbEvent The size of event parameters. + */ + DECLR3CALLBACKMEMBER(void, HostChannelCallbackEvent, (void *pvCallbacks, void *pvChannel, + uint32_t u32Id, const void *pvEvent, uint32_t cbEvent)); + + /* The channel has been deleted by the provider. pvCallback will not be used anymore. + * + * @param pvCallbacks The callback context specified in HostChannelAttach. + * @param pvChannel The channel instance returned by HostChannelAttach. + */ + DECLR3CALLBACKMEMBER(void, HostChannelCallbackDeleted, (void *pvCallbacks, void *pvChannel)); +} VBOXHOSTCHANNELCALLBACKS; + +typedef struct VBOXHOSTCHANNELINTERFACE +{ + /* The channel provider context. */ + void *pvProvider; + + /* A new channel is requested. + * + * @param pvProvider The provider context VBOXHOSTCHANNELINTERFACE::pvProvider. + * @param ppvChannel Where to store pointer to the channel instance created by the provider. + * @param u32Flags Channel specific flags. + * @param pCallbacks Callbacks to be invoked by the channel provider. + * @param pvCallbacks The context of callbacks. + */ + DECLR3CALLBACKMEMBER(int, HostChannelAttach, (void *pvProvider, void **ppvChannel, uint32_t u32Flags, + VBOXHOSTCHANNELCALLBACKS *pCallbacks, void *pvCallbacks)); + + /* The channel is closed. */ + DECLR3CALLBACKMEMBER(void, HostChannelDetach, (void *pvChannel)); + + /* The guest sends data to the channel. */ + DECLR3CALLBACKMEMBER(int, HostChannelSend, (void *pvChannel, const void *pvData, uint32_t cbData)); + + /* The guest reads data from the channel. */ + DECLR3CALLBACKMEMBER(int, HostChannelRecv, (void *pvChannel, void *pvData, uint32_t cbData, + uint32_t *pcbReceived, uint32_t *pcbRemaining)); + + /* The guest talks to the provider of the channel. + * @param pvChannel The channel instance. NULL if the target is the provider, rather than a channel. + */ + DECLR3CALLBACKMEMBER(int, HostChannelControl, (void *pvChannel, uint32_t u32Code, + const void *pvParm, uint32_t cbParm, + const void *pvData, uint32_t cbData, uint32_t *pcbDataReturned)); +} VBOXHOSTCHANNELINTERFACE; + +#pragma pack() + +#endif /* !VBOX_INCLUDED_HostServices_VBoxHostChannel_h */ |