[43347] | 1 | /** @file
|
---|
[44528] | 2 | *
|
---|
[43347] | 3 | * Host Channel: the service definition.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[98103] | 7 | * Copyright (C) 2012-2023 Oracle and/or its affiliates.
|
---|
[43347] | 8 | *
|
---|
[96407] | 9 | * This file is part of VirtualBox base platform packages, as
|
---|
| 10 | * available from https://www.virtualbox.org.
|
---|
[43347] | 11 | *
|
---|
[96407] | 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 | *
|
---|
[43347] | 25 | * The contents of this file may alternatively be used under the terms
|
---|
| 26 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 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
|
---|
[43347] | 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.
|
---|
[96407] | 33 | *
|
---|
| 34 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[43347] | 35 | */
|
---|
| 36 |
|
---|
[76558] | 37 | #ifndef VBOX_INCLUDED_HostServices_VBoxHostChannel_h
|
---|
| 38 | #define VBOX_INCLUDED_HostServices_VBoxHostChannel_h
|
---|
[76507] | 39 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 40 | # pragma once
|
---|
| 41 | #endif
|
---|
[43347] | 42 |
|
---|
[68660] | 43 | #include <VBox/VMMDevCoreTypes.h>
|
---|
[68656] | 44 | #include <VBox/VBoxGuestCoreTypes.h>
|
---|
[43347] | 45 | #include <VBox/hgcmsvc.h>
|
---|
| 46 |
|
---|
| 47 | /*
|
---|
| 48 | * Host calls.
|
---|
| 49 | */
|
---|
| 50 | #define VBOX_HOST_CHANNEL_HOST_FN_REGISTER 1
|
---|
| 51 | #define VBOX_HOST_CHANNEL_HOST_FN_UNREGISTER 2
|
---|
| 52 |
|
---|
| 53 | /*
|
---|
| 54 | * Guest calls.
|
---|
| 55 | */
|
---|
| 56 | #define VBOX_HOST_CHANNEL_FN_ATTACH 1 /* Attach to a channel. */
|
---|
| 57 | #define VBOX_HOST_CHANNEL_FN_DETACH 2 /* Detach from the channel. */
|
---|
| 58 | #define VBOX_HOST_CHANNEL_FN_SEND 3 /* Send data to the host. */
|
---|
| 59 | #define VBOX_HOST_CHANNEL_FN_RECV 4 /* Receive data from the host. */
|
---|
[43462] | 60 | #define VBOX_HOST_CHANNEL_FN_CONTROL 5 /* Generic data exchange using a channel instance. */
|
---|
[43347] | 61 | #define VBOX_HOST_CHANNEL_FN_EVENT_WAIT 6 /* Blocking wait for a host event. */
|
---|
| 62 | #define VBOX_HOST_CHANNEL_FN_EVENT_CANCEL 7 /* Cancel the blocking wait. */
|
---|
[43462] | 63 | #define VBOX_HOST_CHANNEL_FN_QUERY 8 /* Generic data exchange using a channel name. */
|
---|
[43347] | 64 |
|
---|
| 65 | /*
|
---|
| 66 | * The host event ids for the guest.
|
---|
| 67 | */
|
---|
| 68 | #define VBOX_HOST_CHANNEL_EVENT_CANCELLED 0 /* Event was cancelled by FN_EVENT_CANCEL. */
|
---|
| 69 | #define VBOX_HOST_CHANNEL_EVENT_UNREGISTERED 1 /* Channel was unregistered on host. */
|
---|
| 70 | #define VBOX_HOST_CHANNEL_EVENT_RECV 2 /* Data is available for receiving. */
|
---|
| 71 | #define VBOX_HOST_CHANNEL_EVENT_USER 1000 /* Base of channel specific events. */
|
---|
| 72 |
|
---|
[43462] | 73 | /*
|
---|
| 74 | * The common control code ids for the VBOX_HOST_CHANNEL_FN_[CONTROL|QUERY]
|
---|
| 75 | */
|
---|
| 76 | #define VBOX_HOST_CHANNEL_CTRL_EXISTS 0 /* Whether the channel instance or provider exists. */
|
---|
| 77 | #define VBOX_HOST_CHANNEL_CTRL_USER 1000 /* Base of channel specific events. */
|
---|
| 78 |
|
---|
[43347] | 79 | #pragma pack(1)
|
---|
| 80 |
|
---|
| 81 | /* Parameter of VBOX_HOST_CHANNEL_EVENT_RECV */
|
---|
| 82 | typedef struct VBOXHOSTCHANNELEVENTRECV
|
---|
| 83 | {
|
---|
| 84 | uint32_t u32SizeAvailable; /* How many bytes can be read from the channel. */
|
---|
| 85 | } VBOXHOSTCHANNELEVENTRECV;
|
---|
| 86 |
|
---|
| 87 | /*
|
---|
| 88 | * Guest calls.
|
---|
| 89 | */
|
---|
| 90 |
|
---|
| 91 | typedef struct VBoxHostChannelAttach
|
---|
| 92 | {
|
---|
[68550] | 93 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 94 | HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */
|
---|
| 95 | HGCMFunctionParameter flags; /* IN uint32_t: Channel specific flags. */
|
---|
| 96 | HGCMFunctionParameter handle; /* OUT uint32_t: The channel handle. */
|
---|
| 97 | } VBoxHostChannelAttach;
|
---|
| 98 |
|
---|
| 99 | typedef struct VBoxHostChannelDetach
|
---|
| 100 | {
|
---|
[68550] | 101 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 102 | HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */
|
---|
| 103 | } VBoxHostChannelDetach;
|
---|
| 104 |
|
---|
| 105 | typedef struct VBoxHostChannelSend
|
---|
| 106 | {
|
---|
[68550] | 107 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 108 | HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */
|
---|
| 109 | HGCMFunctionParameter data; /* IN linear pointer: Data to be sent. */
|
---|
| 110 | } VBoxHostChannelSend;
|
---|
| 111 |
|
---|
| 112 | typedef struct VBoxHostChannelRecv
|
---|
| 113 | {
|
---|
[68550] | 114 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 115 | HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */
|
---|
| 116 | HGCMFunctionParameter data; /* OUT linear pointer: Buffer for data to be received. */
|
---|
| 117 | HGCMFunctionParameter sizeReceived; /* OUT uint32_t: Bytes received. */
|
---|
| 118 | HGCMFunctionParameter sizeRemaining; /* OUT uint32_t: Bytes remaining in the channel. */
|
---|
| 119 | } VBoxHostChannelRecv;
|
---|
| 120 |
|
---|
| 121 | typedef struct VBoxHostChannelControl
|
---|
| 122 | {
|
---|
[68550] | 123 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 124 | HGCMFunctionParameter handle; /* IN uint32_t: The channel handle. */
|
---|
| 125 | HGCMFunctionParameter code; /* IN uint32_t: The channel specific control code. */
|
---|
| 126 | HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */
|
---|
| 127 | HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */
|
---|
| 128 | HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */
|
---|
| 129 | } VBoxHostChannelControl;
|
---|
| 130 |
|
---|
| 131 | typedef struct VBoxHostChannelEventWait
|
---|
| 132 | {
|
---|
[68550] | 133 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 134 | HGCMFunctionParameter handle; /* OUT uint32_t: The channel which generated the event. */
|
---|
| 135 | HGCMFunctionParameter id; /* OUT uint32_t: The event VBOX_HOST_CHANNEL_EVENT_*. */
|
---|
| 136 | HGCMFunctionParameter parm; /* OUT linear pointer: Parameters of the event. */
|
---|
| 137 | HGCMFunctionParameter sizeReturned; /* OUT uint32_t: Size of the parameters. */
|
---|
| 138 | } VBoxHostChannelEventWait;
|
---|
| 139 |
|
---|
| 140 | typedef struct VBoxHostChannelEventCancel
|
---|
| 141 | {
|
---|
[68550] | 142 | VBGLIOCHGCMCALL hdr;
|
---|
[43347] | 143 | } VBoxHostChannelEventCancel;
|
---|
| 144 |
|
---|
[43462] | 145 | typedef struct VBoxHostChannelQuery
|
---|
| 146 | {
|
---|
[68550] | 147 | VBGLIOCHGCMCALL hdr;
|
---|
[43462] | 148 | HGCMFunctionParameter name; /* IN linear ptr: Channel name utf8 nul terminated. */
|
---|
| 149 | HGCMFunctionParameter code; /* IN uint32_t: The control code. */
|
---|
| 150 | HGCMFunctionParameter parm; /* IN linear pointer: Parameters of the function. */
|
---|
| 151 | HGCMFunctionParameter data; /* OUT linear pointer: Buffer for results. */
|
---|
| 152 | HGCMFunctionParameter sizeDataReturned; /* OUT uint32_t: Bytes returned in the 'data' buffer. */
|
---|
| 153 | } VBoxHostChannelQuery;
|
---|
[43347] | 154 |
|
---|
[43462] | 155 |
|
---|
[43347] | 156 | /*
|
---|
| 157 | * Host calls
|
---|
| 158 | */
|
---|
| 159 |
|
---|
| 160 | typedef struct VBoxHostChannelHostRegister
|
---|
| 161 | {
|
---|
| 162 | VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated. */
|
---|
| 163 | VBOXHGCMSVCPARM iface; /* IN ptr: VBOXHOSTCHANNELINTERFACE. */
|
---|
| 164 | } VBoxHostChannelHostRegister;
|
---|
| 165 |
|
---|
| 166 | typedef struct VBoxHostChannelHostUnregister
|
---|
| 167 | {
|
---|
| 168 | VBOXHGCMSVCPARM name; /* IN ptr: Channel name utf8 nul terminated */
|
---|
| 169 | } VBoxHostChannelHostUnregister;
|
---|
| 170 |
|
---|
| 171 | /* The channel provider will invoke this callback to report channel events. */
|
---|
| 172 | typedef struct VBOXHOSTCHANNELCALLBACKS
|
---|
| 173 | {
|
---|
| 174 | /* A channel event occured.
|
---|
| 175 | *
|
---|
| 176 | * @param pvCallbacks The callback context specified in HostChannelAttach.
|
---|
| 177 | * @param pvChannel The channel instance returned by HostChannelAttach.
|
---|
| 178 | * @param u32Id The event id.
|
---|
| 179 | * @param pvEvent The event parameters.
|
---|
| 180 | * @param cbEvent The size of event parameters.
|
---|
| 181 | */
|
---|
| 182 | DECLR3CALLBACKMEMBER(void, HostChannelCallbackEvent, (void *pvCallbacks, void *pvChannel,
|
---|
| 183 | uint32_t u32Id, const void *pvEvent, uint32_t cbEvent));
|
---|
[43786] | 184 |
|
---|
| 185 | /* The channel has been deleted by the provider. pvCallback will not be used anymore.
|
---|
| 186 | *
|
---|
| 187 | * @param pvCallbacks The callback context specified in HostChannelAttach.
|
---|
| 188 | * @param pvChannel The channel instance returned by HostChannelAttach.
|
---|
| 189 | */
|
---|
| 190 | DECLR3CALLBACKMEMBER(void, HostChannelCallbackDeleted, (void *pvCallbacks, void *pvChannel));
|
---|
[43347] | 191 | } VBOXHOSTCHANNELCALLBACKS;
|
---|
| 192 |
|
---|
| 193 | typedef struct VBOXHOSTCHANNELINTERFACE
|
---|
| 194 | {
|
---|
| 195 | /* The channel provider context. */
|
---|
| 196 | void *pvProvider;
|
---|
| 197 |
|
---|
| 198 | /* A new channel is requested.
|
---|
| 199 | *
|
---|
| 200 | * @param pvProvider The provider context VBOXHOSTCHANNELINTERFACE::pvProvider.
|
---|
| 201 | * @param ppvChannel Where to store pointer to the channel instance created by the provider.
|
---|
| 202 | * @param u32Flags Channel specific flags.
|
---|
| 203 | * @param pCallbacks Callbacks to be invoked by the channel provider.
|
---|
| 204 | * @param pvCallbacks The context of callbacks.
|
---|
| 205 | */
|
---|
| 206 | DECLR3CALLBACKMEMBER(int, HostChannelAttach, (void *pvProvider, void **ppvChannel, uint32_t u32Flags,
|
---|
| 207 | VBOXHOSTCHANNELCALLBACKS *pCallbacks, void *pvCallbacks));
|
---|
| 208 |
|
---|
| 209 | /* The channel is closed. */
|
---|
| 210 | DECLR3CALLBACKMEMBER(void, HostChannelDetach, (void *pvChannel));
|
---|
| 211 |
|
---|
| 212 | /* The guest sends data to the channel. */
|
---|
| 213 | DECLR3CALLBACKMEMBER(int, HostChannelSend, (void *pvChannel, const void *pvData, uint32_t cbData));
|
---|
| 214 |
|
---|
| 215 | /* The guest reads data from the channel. */
|
---|
| 216 | DECLR3CALLBACKMEMBER(int, HostChannelRecv, (void *pvChannel, void *pvData, uint32_t cbData,
|
---|
| 217 | uint32_t *pcbReceived, uint32_t *pcbRemaining));
|
---|
| 218 |
|
---|
[43462] | 219 | /* The guest talks to the provider of the channel.
|
---|
| 220 | * @param pvChannel The channel instance. NULL if the target is the provider, rather than a channel.
|
---|
| 221 | */
|
---|
[43347] | 222 | DECLR3CALLBACKMEMBER(int, HostChannelControl, (void *pvChannel, uint32_t u32Code,
|
---|
| 223 | const void *pvParm, uint32_t cbParm,
|
---|
| 224 | const void *pvData, uint32_t cbData, uint32_t *pcbDataReturned));
|
---|
| 225 | } VBOXHOSTCHANNELINTERFACE;
|
---|
| 226 |
|
---|
| 227 | #pragma pack()
|
---|
| 228 |
|
---|
[76585] | 229 | #endif /* !VBOX_INCLUDED_HostServices_VBoxHostChannel_h */
|
---|