VirtualBox

source: vbox/trunk/include/VBox/HostServices/GuestControlSvc.h@ 75824

Last change on this file since 75824 was 75824, checked in by vboxsync, 6 years ago

VBoxGuestControl: Optimizing message handling - part 4. bugref:9313
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 42.0 KB
Line 
1/* $Id: GuestControlSvc.h 75824 2018-11-29 22:12:53Z vboxsync $ */
2/** @file
3 * Guest control service - Common header for host service and guest clients.
4 */
5
6/*
7 * Copyright (C) 2011-2018 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_HostService_GuestControlService_h
28#define ___VBox_HostService_GuestControlService_h
29
30#include <VBox/VMMDevCoreTypes.h>
31#include <VBox/VBoxGuestCoreTypes.h>
32#include <VBox/hgcmsvc.h>
33#include <iprt/assert.h>
34
35/* Everything defined in this file lives in this namespace. */
36namespace guestControl {
37
38/******************************************************************************
39* Typedefs, constants and inlines *
40******************************************************************************/
41
42#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
43
44/** Maximum number of concurrent guest sessions a VM can have. */
45#define VBOX_GUESTCTRL_MAX_SESSIONS 32
46/** Maximum number of concurrent guest objects (processes, files, ...)
47 * a guest session can have. */
48#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
49/** Maximum of callback contexts a guest process can have. */
50#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
51
52/** Base (start) of guest control session IDs. Session
53 * ID 0 is reserved for the root process which
54 * hosts all other guest session processes. */
55#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
56
57/** Builds a context ID out of the session ID, object ID and an
58 * increasing count. */
59#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
60 ( (uint32_t)((uSession) & 0x1f) << 27 \
61 | (uint32_t)((uObject) & 0x7ff) << 16 \
62 | (uint32_t)((uCount) & 0xffff) \
63 )
64/** Creates a context ID out of a session ID. */
65#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
66 ((uint32_t)((uSession) & 0x1f) << 27)
67/** Gets the session ID out of a context ID. */
68#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
69 (((uContextID) >> 27) & 0x1f)
70/** Gets the process ID out of a context ID. */
71#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
72 (((uContextID) >> 16) & 0x7ff)
73/** Gets the context count of a process out of a context ID. */
74#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
75 ((uContextID) & 0xffff)
76/** Filter context IDs by session. Can be used in conjunction
77 * with VbglR3GuestCtrlMsgFilterSet(). */
78#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
79 (VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) | 0xF8000000)
80
81/**
82 * Structure keeping the context of a host callback.
83 */
84typedef struct VBoxGuestCtrlHostCbCtx
85{
86 /** HGCM Function number. */
87 uint32_t uFunction;
88 /** The context ID. */
89 uint32_t uContextID;
90 /** Protocol version of this guest session. Might
91 * be 0 if not supported. */
92 uint32_t uProtocol;
93
94} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
95
96/**
97 * Structure for low level HGCM host callback from
98 * the guest. No deep copy. */
99typedef struct VBoxGuestCtrlHostCallback
100{
101 VBoxGuestCtrlHostCallback(uint32_t cParms, VBOXHGCMSVCPARM paParms[])
102 : mParms(cParms), mpaParms(paParms) { }
103
104 /** Number of HGCM parameters. */
105 uint32_t mParms;
106 /** Actual HGCM parameters. */
107 PVBOXHGCMSVCPARM mpaParms;
108
109} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
110
111
112/** @name Host message destiation flags.
113 *
114 * This is ORed into the context ID parameter Main after extending it to 64-bit.
115 *
116 * @internal Host internal.
117 * @{ */
118#define VBOX_GUESTCTRL_DST_ROOT_SVC RT_BIT_64(63)
119#define VBOX_GUESTCTRL_DST_SESSION RT_BIT_64(62)
120#define VBOX_GUESTCTRL_DST_BOTH ( VBOX_GUESTCTRL_DST_ROOT_SVC | VBOX_GUESTCTRL_DST_SESSION )
121/** @} */
122
123
124/**
125 * The service functions which are callable by host.
126 */
127enum eHostFn
128{
129 /**
130 * The host asks the client to cancel all pending waits and exit.
131 */
132 HOST_CANCEL_PENDING_WAITS = 0,
133 /**
134 * The host wants to create a guest session.
135 */
136 HOST_SESSION_CREATE = 20,
137 /**
138 * The host wants to close a guest session.
139 */
140 HOST_SESSION_CLOSE = 21,
141 /**
142 * The host wants to execute something in the guest. This can be a command line
143 * or starting a program.
144 ** Note: Legacy (VBox < 4.3) command.
145 */
146 HOST_EXEC_CMD = 100,
147 /**
148 * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
149 ** Note: Legacy (VBox < 4.3) command.
150 */
151 HOST_EXEC_SET_INPUT = 101,
152 /**
153 * Gets the current status of a running process, e.g.
154 * new data on stdout/stderr, process terminated etc.
155 * @note Legacy (VBox < 4.3) command.
156 */
157 HOST_EXEC_GET_OUTPUT = 102,
158 /**
159 * Terminates a running guest process.
160 */
161 HOST_EXEC_TERMINATE = 110,
162 /**
163 * Waits for a certain event to happen. This can be an input, output
164 * or status event.
165 */
166 HOST_EXEC_WAIT_FOR = 120,
167 /**
168 * Opens a guest file.
169 */
170 HOST_FILE_OPEN = 240,
171 /**
172 * Closes a guest file.
173 */
174 HOST_FILE_CLOSE = 241,
175 /**
176 * Reads from an opened guest file.
177 */
178 HOST_FILE_READ = 250,
179 /**
180 * Reads from an opened guest file at
181 * a specified offset.
182 */
183 HOST_FILE_READ_AT = 251,
184 /**
185 * Write to an opened guest file.
186 */
187 HOST_FILE_WRITE = 260,
188 /**
189 * Write to an opened guest file at
190 * a specified offset.
191 */
192 HOST_FILE_WRITE_AT = 261,
193 /**
194 * Changes the read & write position of an opened guest file.
195 */
196 HOST_FILE_SEEK = 270,
197 /**
198 * Gets the current file position of an opened guest file.
199 */
200 HOST_FILE_TELL = 271,
201 /**
202 * Removes a directory on the guest.
203 */
204 HOST_DIR_REMOVE = 320,
205 /**
206 * Renames a path on the guest.
207 */
208 HOST_PATH_RENAME = 330,
209 /**
210 * Retrieves the user's documents directory.
211 */
212 HOST_PATH_USER_DOCUMENTS = 331,
213 /**
214 * Retrieves the user's home directory.
215 */
216 HOST_PATH_USER_HOME = 332
217};
218
219
220/**
221 * Translates a guest control host function function enum to at string.
222 * @returns Enum string name.
223 * @param enmFunction The function name to translate.
224 */
225DECLINLINE(const char *) GstCtrlHostFnName(enum eHostFn enmFunction)
226{
227 switch (enmFunction)
228 {
229 RT_CASE_RET_STR(HOST_CANCEL_PENDING_WAITS);
230 RT_CASE_RET_STR(HOST_SESSION_CREATE);
231 RT_CASE_RET_STR(HOST_SESSION_CLOSE);
232 RT_CASE_RET_STR(HOST_EXEC_CMD);
233 RT_CASE_RET_STR(HOST_EXEC_SET_INPUT);
234 RT_CASE_RET_STR(HOST_EXEC_GET_OUTPUT);
235 RT_CASE_RET_STR(HOST_EXEC_TERMINATE);
236 RT_CASE_RET_STR(HOST_EXEC_WAIT_FOR);
237 RT_CASE_RET_STR(HOST_FILE_OPEN);
238 RT_CASE_RET_STR(HOST_FILE_CLOSE);
239 RT_CASE_RET_STR(HOST_FILE_READ);
240 RT_CASE_RET_STR(HOST_FILE_READ_AT);
241 RT_CASE_RET_STR(HOST_FILE_WRITE);
242 RT_CASE_RET_STR(HOST_FILE_WRITE_AT);
243 RT_CASE_RET_STR(HOST_FILE_SEEK);
244 RT_CASE_RET_STR(HOST_FILE_TELL);
245 RT_CASE_RET_STR(HOST_DIR_REMOVE);
246 RT_CASE_RET_STR(HOST_PATH_RENAME);
247 RT_CASE_RET_STR(HOST_PATH_USER_DOCUMENTS);
248 RT_CASE_RET_STR(HOST_PATH_USER_HOME);
249 }
250 return "Unknown";
251}
252
253
254/**
255 * The service functions which are called by guest.
256 *
257 * @note The function numbers cannot be changed. Please use the first non-zero
258 * number that's not in use when adding new functions.
259 *
260 * @note Remember to update service.cpp when adding new functions/events for
261 * Main, as it validates all incoming commands before passing them on.
262 */
263enum eGuestFn
264{
265 /** Guest waits for a new message the host wants to process on the guest side.
266 * This is a blocking call and can be deferred.
267 *
268 * @note This command is rather odd. The above description isn't really
269 * correct. Yes, it (1) waits for a new message and will return the
270 * mesage number and parameter count when one is available. However, it
271 * is also (2) used to retrieve the message parameters. For some weird
272 * reasons it was decided that it should always return VERR_TOO_MUCH_DATA
273 * when used in the first capacity.
274 *
275 * @note Has a problem if the guest kernel module cancels the HGCM call, as the
276 * guest cannot resume waiting till the host issues a message for it and
277 * the cancelled call returns. The new message may potentially end up in
278 * /dev/null depending and hang the message conversation between the guest
279 * and the host (SIGCHLD).
280 *
281 * @deprecated Replaced by GUEST_MSG_PEEK_WAIT, GUEST_MSG_GET and
282 * GUEST_MSG_CANCEL.
283 */
284 GUEST_MSG_WAIT = 1,
285 /** Cancels pending calls for this client session.
286 *
287 * This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets
288 * interrupted on the client end, so as to prevent being rebuffed with
289 * VERR_RESOURCE_BUSY when restarting the call.
290 *
291 * @retval VINF_SUCCESS if cancelled any calls.
292 * @retval VWRN_NOT_FOUND if no callers.
293 * @retval VERR_INVALID_CLIENT_ID
294 * @retval VERR_WRONG_PARAMETER_COUNT
295 * @since 6.0
296 */
297 GUEST_MSG_CANCEL = 2,
298 /** Guest disconnected (terminated normally or due to a crash HGCM
299 * detected when calling service::clientDisconnect().
300 *
301 * @note This is a host side notification message that has no business in this
302 * enum. The guest cannot use this function number, host will reject it.
303 */
304 GUEST_DISCONNECTED = 3,
305 /** Sets a message filter to only get messages which have a certain
306 * context ID scheme (that is, a specific session, object etc).
307 * Since VBox 4.3+.
308 * @deprecated Replaced by GUEST_SESSION_ACCEPT.
309 */
310 GUEST_MSG_FILTER_SET = 4,
311 /** Unsets (and resets) a previously set message filter.
312 * @retval VERR_NOT_IMPLEMENTED since 6.0.
313 * @deprecated Never needed or used,
314 */
315 GUEST_MSG_FILTER_UNSET = 5,
316 /** Peeks at the next message, returning immediately.
317 *
318 * Returns two 32-bit parameters, first is the message ID and the second the
319 * parameter count. May optionally return additional 32-bit parameters with the
320 * sizes of respective message parameters. To distinguish buffer sizes from
321 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
322 * uint64_t is ~8U).
323 *
324 * @retval VINF_SUCCESS if a message was pending and is being returned.
325 * @retval VERR_TRY_AGAIN if no message pending.
326 * @retval VERR_INVALID_CLIENT_ID
327 * @retval VERR_WRONG_PARAMETER_COUNT
328 * @retval VERR_WRONG_PARAMETER_TYPE
329 * @since 6.0
330 */
331 GUEST_MSG_PEEK_NOWAIT = 6,
332 /** Peeks at the next message, waiting for one to arrive.
333 *
334 * Returns two 32-bit parameters, first is the message ID and the second the
335 * parameter count. May optionally return additional 32-bit parameters with the
336 * sizes of respective message parameters. To distinguish buffer sizes from
337 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
338 * uint64_t is ~8U).
339 *
340 * @retval VINF_SUCCESS if info about an pending message is being returned.
341 * @retval VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if
342 * cancelled by GUEST_MSG_CANCEL.
343 * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call.
344 * @retval VERR_INVALID_CLIENT_ID
345 * @retval VERR_WRONG_PARAMETER_COUNT
346 * @retval VERR_WRONG_PARAMETER_TYPE
347 * @note This replaces GUEST_MSG_WAIT.
348 * @since 6.0
349 */
350 GUEST_MSG_PEEK_WAIT = 7,
351 /** Gets the next message, returning immediately.
352 *
353 * All parameters are specific to the message being retrieved, however if the
354 * first one is an integer value it shall be an input parameter holding the
355 * ID of the message being retrieved. While it would be nice to add a separate
356 * parameter for this purpose, this is difficult without breaking GUEST_MSG_WAIT
357 * compatibility.
358 *
359 * @retval VINF_SUCCESS if message retrieved and removed from the pending queue.
360 * @retval VERR_TRY_AGAIN if no message pending.
361 * @retval VERR_MISMATCH if the incoming message ID does not match the pending.
362 * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer
363 * size was updated to reflect the required size.
364 * @retval VERR_INVALID_CLIENT_ID
365 * @retval VERR_WRONG_PARAMETER_COUNT
366 * @retval VERR_WRONG_PARAMETER_TYPE
367 * @note This replaces GUEST_MSG_WAIT.
368 * @since 6.0
369 */
370 GUEST_MSG_GET = 8,
371 /** Skip message.
372 *
373 * This skips the current message, replying to the main backend as best it can.
374 * Takes between zero and two parameters. The first parameter is the 32-bit
375 * VBox status code to pass onto Main when skipping the command, defaults to
376 * VERR_NOT_SUPPORTED. The second parameter is the 32-bit message ID of the
377 * command to skip, by default whatever is first in the queue is removed. This
378 * is also the case if UINT32_MAX is specified.
379 *
380 * @retval VINF_SUCCESS on success.
381 * @retval VERR_NOT_FOUND if no message pending.
382 * @retval VERR_MISMATCH if the specified message ID didn't match.
383 * @retval VERR_INVALID_CLIENT_ID
384 * @retval VERR_WRONG_PARAMETER_COUNT
385 * @since 6.0
386 */
387 GUEST_MSG_SKIP = 9,
388 /**
389 * Skips the current assigned message returned by GUEST_MSG_WAIT.
390 * Needed for telling the host service to not keep stale
391 * host commands in the queue.
392 * @deprecated Replaced by GUEST_MSG_SKIP.
393 */
394 GUEST_MSG_SKIP_OLD = 10,
395 /** General reply to a host message.
396 * Only contains basic data along with a simple payload.
397 * @todo proper docs.
398 */
399 GUEST_MSG_REPLY = 11,
400 /** General message for updating a pending progress for a long task.
401 * @todo proper docs.
402 */
403 GUEST_MSG_PROGRESS_UPDATE = 12,
404 /** Sets the caller as the master.
405 *
406 * Called by the root VBoxService to explicitly tell the host that's the master
407 * service. Required to use main VBoxGuest device node. No parameters.
408 *
409 * @retval VINF_SUCCESS on success.
410 * @retval VERR_ACCESS_DENIED if not using main VBoxGuest device not
411 * @retval VERR_RESOURCE_BUSY if there is already a master.
412 * @retval VERR_VERSION_MISMATCH if VBoxGuest didn't supply requestor info.
413 * @retval VERR_INVALID_CLIENT_ID
414 * @retval VERR_WRONG_PARAMETER_COUNT
415 * @since 6.0
416 */
417 GUEST_MAKE_ME_MASTER = 13,
418 /** Prepares the starting of a session.
419 *
420 * VBoxService makes this call before spawning a session process (must be
421 * master). The first parameter is the session ID and the second is a one time
422 * key for identifying the right session process. First parameter is a 32-bit
423 * session ID with a value between 1 and 0xfff0. The second parameter is a byte
424 * buffer containing a key that GUEST_SESSION_ACCEPT checks against, minimum
425 * length is 64 bytes, maximum 16384 bytes.
426 *
427 * @retval VINF_SUCCESS on success.
428 * @retval VERR_OUT_OF_RESOURCES if too many pending sessions hanging around.
429 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
430 * @retval VERR_BUFFER_OVERFLOW if key too large.
431 * @retval VERR_BUFFER_UNDERFLOW if key too small.
432 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
433 * @retval VERR_DUPLICATE if the session ID has been prepared already.
434 * @retval VERR_INVALID_CLIENT_ID
435 * @retval VERR_WRONG_PARAMETER_COUNT
436 * @retval VERR_WRONG_PARAMETER_TYPE
437 * @since 6.0
438 */
439 GUEST_SESSION_PREPARE = 14,
440 /** Cancels a prepared session.
441 *
442 * VBoxService makes this call to clean up after spawning a session process
443 * failed. One parameter, 32-bit session ID. If UINT32_MAX is passed, all
444 * prepared sessions are cancelled.
445 *
446 * @retval VINF_SUCCESS on success.
447 * @retval VWRN_NOT_FOUND if no session with the specified ID.
448 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
449 * @retval VERR_INVALID_CLIENT_ID
450 * @retval VERR_WRONG_PARAMETER_COUNT
451 * @retval VERR_WRONG_PARAMETER_TYPE
452 * @since 6.0
453 */
454 GUEST_SESSION_CANCEL_PREPARED = 15,
455 /** Accepts a prepared session.
456 *
457 * The session processes makes this call to accept a prepared session. The
458 * session ID is then uniquely associated with the HGCM client ID of the caller.
459 * The parameters must be identical to the matching GUEST_SESSION_PREPARE call.
460 *
461 * @retval VINF_SUCCESS on success.
462 * @retval VERR_NOT_FOUND if the specified session ID wasn't found.
463 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
464 * @retval VERR_BUFFER_OVERFLOW if key too large.
465 * @retval VERR_BUFFER_UNDERFLOW if key too small.
466 * @retval VERR_ACCESS_DENIED if we're in legacy mode or is master.
467 * @retval VERR_RESOURCE_BUSY if the client is already associated with a session.
468 * @retval VERR_MISMATCH if the key didn't match.
469 * @retval VERR_INVALID_CLIENT_ID
470 * @retval VERR_WRONG_PARAMETER_COUNT
471 * @retval VERR_WRONG_PARAMETER_TYPE
472 * @since 6.0
473 */
474 GUEST_SESSION_ACCEPT = 16,
475 /**
476 * Guest reports back a guest session status.
477 * @todo proper docs.
478 */
479 GUEST_SESSION_NOTIFY = 20,
480 /**
481 * Guest wants to close a specific guest session.
482 * @todo proper docs.
483 */
484 GUEST_SESSION_CLOSE = 21,
485
486 /**
487 * Guests sends output from an executed process.
488 * @todo proper docs.
489 */
490 GUEST_EXEC_OUTPUT = 100,
491 /**
492 * Guest sends a status update of an executed process to the host.
493 * @todo proper docs.
494 */
495 GUEST_EXEC_STATUS = 101,
496 /**
497 * Guests sends an input status notification to the host.
498 * @todo proper docs.
499 */
500 GUEST_EXEC_INPUT_STATUS = 102,
501 /**
502 * Guest notifies the host about some I/O event. This can be
503 * a stdout, stderr or a stdin event. The actual event only tells
504 * how many data is available / can be sent without actually
505 * transmitting the data.
506 * @todo proper docs.
507 */
508 GUEST_EXEC_IO_NOTIFY = 210,
509 /**
510 * Guest notifies the host about some directory event.
511 * @todo proper docs.
512 */
513 GUEST_DIR_NOTIFY = 230,
514 /**
515 * Guest notifies the host about some file event.
516 * @todo proper docs.
517 */
518 GUEST_FILE_NOTIFY = 240
519};
520
521/**
522 * Translates a guest control host function function enum to at string.
523 * @returns Enum string name.
524 * @param enmFunction The function name to translate.
525 */
526DECLINLINE(const char *) GstCtrlGuestFnName(enum eGuestFn enmFunction)
527{
528 switch (enmFunction)
529 {
530 RT_CASE_RET_STR(GUEST_MSG_WAIT);
531 RT_CASE_RET_STR(GUEST_MSG_CANCEL);
532 RT_CASE_RET_STR(GUEST_DISCONNECTED);
533 RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
534 RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
535 RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT);
536 RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT);
537 RT_CASE_RET_STR(GUEST_MSG_GET);
538 RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD);
539 RT_CASE_RET_STR(GUEST_MSG_REPLY);
540 RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
541 RT_CASE_RET_STR(GUEST_MSG_SKIP);
542 RT_CASE_RET_STR(GUEST_MAKE_ME_MASTER);
543 RT_CASE_RET_STR(GUEST_SESSION_PREPARE);
544 RT_CASE_RET_STR(GUEST_SESSION_CANCEL_PREPARED);
545 RT_CASE_RET_STR(GUEST_SESSION_ACCEPT);
546 RT_CASE_RET_STR(GUEST_SESSION_NOTIFY);
547 RT_CASE_RET_STR(GUEST_SESSION_CLOSE);
548 RT_CASE_RET_STR(GUEST_EXEC_OUTPUT);
549 RT_CASE_RET_STR(GUEST_EXEC_STATUS);
550 RT_CASE_RET_STR(GUEST_EXEC_INPUT_STATUS);
551 RT_CASE_RET_STR(GUEST_EXEC_IO_NOTIFY);
552 RT_CASE_RET_STR(GUEST_DIR_NOTIFY);
553 RT_CASE_RET_STR(GUEST_FILE_NOTIFY);
554 }
555 return "Unknown";
556}
557
558
559/**
560 * Guest session notification types.
561 * @sa HGCMMsgSessionNotify.
562 */
563enum GUEST_SESSION_NOTIFYTYPE
564{
565 GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
566 /** Something went wrong (see rc). */
567 GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
568 /** Guest session has been started. */
569 GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
570 /** Guest session terminated normally. */
571 GUEST_SESSION_NOTIFYTYPE_TEN = 20,
572 /** Guest session terminated via signal. */
573 GUEST_SESSION_NOTIFYTYPE_TES = 30,
574 /** Guest session terminated abnormally. */
575 GUEST_SESSION_NOTIFYTYPE_TEA = 40,
576 /** Guest session timed out and was killed. */
577 GUEST_SESSION_NOTIFYTYPE_TOK = 50,
578 /** Guest session timed out and was not killed successfully. */
579 GUEST_SESSION_NOTIFYTYPE_TOA = 60,
580 /** Service/OS is stopping, process was killed. */
581 GUEST_SESSION_NOTIFYTYPE_DWN = 150
582};
583
584/**
585 * Guest directory notification types.
586 * @sa HGCMMsgDirNotify.
587 */
588enum GUEST_DIR_NOTIFYTYPE
589{
590 GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0,
591 /** Something went wrong (see rc). */
592 GUEST_DIR_NOTIFYTYPE_ERROR = 1,
593 /** Guest directory opened. */
594 GUEST_DIR_NOTIFYTYPE_OPEN = 10,
595 /** Guest directory closed. */
596 GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
597 /** Information about an open guest directory. */
598 GUEST_DIR_NOTIFYTYPE_INFO = 40,
599 /** Guest directory created. */
600 GUEST_DIR_NOTIFYTYPE_CREATE = 70,
601 /** Guest directory deleted. */
602 GUEST_DIR_NOTIFYTYPE_REMOVE = 80
603};
604
605/**
606 * Guest file notification types.
607 * @sa HGCMMsgFileNotify.
608 */
609enum GUEST_FILE_NOTIFYTYPE
610{
611 GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
612 GUEST_FILE_NOTIFYTYPE_ERROR = 1,
613 GUEST_FILE_NOTIFYTYPE_OPEN = 10,
614 GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
615 GUEST_FILE_NOTIFYTYPE_READ = 30,
616 GUEST_FILE_NOTIFYTYPE_WRITE = 40,
617 GUEST_FILE_NOTIFYTYPE_SEEK = 50,
618 GUEST_FILE_NOTIFYTYPE_TELL = 60
619};
620
621/**
622 * Guest file seeking types. Has to match FileSeekType in Main.
623 *
624 * @note This is not compatible with RTFileSeek, which is an unncessary pain.
625 */
626enum GUEST_FILE_SEEKTYPE
627{
628 GUEST_FILE_SEEKTYPE_BEGIN = 1,
629 GUEST_FILE_SEEKTYPE_CURRENT = 4,
630 GUEST_FILE_SEEKTYPE_END = 8
631};
632
633/*
634 * HGCM parameter structures.
635 */
636#pragma pack (1)
637
638/**
639 * Waits for a host command to arrive. The structure then contains the
640 * actual message type + required number of parameters needed to successfully
641 * retrieve that host command (in a next round).
642 */
643typedef struct HGCMMsgCmdWaitFor
644{
645 VBGLIOCHGCMCALL hdr;
646 /**
647 * The returned command the host wants to
648 * run on the guest.
649 */
650 HGCMFunctionParameter msg; /* OUT uint32_t */
651 /** Number of parameters the message needs. */
652 HGCMFunctionParameter num_parms; /* OUT uint32_t */
653} HGCMMsgCmdWaitFor;
654
655/**
656 * Asks the guest control host service to set a command
657 * filter for this client. This filter will then only
658 * deliver messages to the client which match the
659 * wanted context ID (ranges).
660 */
661typedef struct HGCMMsgCmdFilterSet
662{
663 VBGLIOCHGCMCALL hdr;
664 /** Value to filter for after filter mask
665 * was applied. */
666 HGCMFunctionParameter value; /* IN uint32_t */
667 /** Mask to add to the current set filter. */
668 HGCMFunctionParameter mask_add; /* IN uint32_t */
669 /** Mask to remove from the current set filter. */
670 HGCMFunctionParameter mask_remove; /* IN uint32_t */
671 /** Filter flags; currently unused. */
672 HGCMFunctionParameter flags; /* IN uint32_t */
673} HGCMMsgCmdFilterSet;
674
675/**
676 * Asks the guest control host service to disable
677 * a previously set message filter again.
678 */
679typedef struct HGCMMsgCmdFilterUnset
680{
681 VBGLIOCHGCMCALL hdr;
682 /** Unset flags; currently unused. */
683 HGCMFunctionParameter flags; /* IN uint32_t */
684} HGCMMsgCmdFilterUnset;
685
686/**
687 * Asks the guest control host service to skip the
688 * currently assigned host command returned by
689 * VbglR3GuestCtrlMsgWaitFor().
690 */
691typedef struct HGCMMsgCmdSkip
692{
693 VBGLIOCHGCMCALL hdr;
694 /** Skip flags; currently unused. */
695 HGCMFunctionParameter flags; /* IN uint32_t */
696} HGCMMsgCmdSkip;
697
698/**
699 * Asks the guest control host service to cancel all pending (outstanding)
700 * waits which were not processed yet. This is handy for a graceful shutdown.
701 */
702typedef struct HGCMMsgCancelPendingWaits
703{
704 VBGLIOCHGCMCALL hdr;
705} HGCMMsgCancelPendingWaits;
706
707typedef struct HGCMMsgCmdReply
708{
709 VBGLIOCHGCMCALL hdr;
710 /** Context ID. */
711 HGCMFunctionParameter context;
712 /** Message type. */
713 HGCMFunctionParameter type;
714 /** IPRT result of overall operation. */
715 HGCMFunctionParameter rc;
716 /** Optional payload to this reply. */
717 HGCMFunctionParameter payload;
718} HGCMMsgCmdReply;
719
720/**
721 * Creates a guest session.
722 */
723typedef struct HGCMMsgSessionOpen
724{
725 VBGLIOCHGCMCALL hdr;
726 /** Context ID. */
727 HGCMFunctionParameter context;
728 /** The guest control protocol version this
729 * session is about to use. */
730 HGCMFunctionParameter protocol;
731 /** The user name to run the guest session under. */
732 HGCMFunctionParameter username;
733 /** The user's password. */
734 HGCMFunctionParameter password;
735 /** The domain to run the guest session under. */
736 HGCMFunctionParameter domain;
737 /** Session creation flags. */
738 HGCMFunctionParameter flags;
739} HGCMMsgSessionOpen;
740
741/**
742 * Terminates (closes) a guest session.
743 */
744typedef struct HGCMMsgSessionClose
745{
746 VBGLIOCHGCMCALL hdr;
747 /** Context ID. */
748 HGCMFunctionParameter context;
749 /** Session termination flags. */
750 HGCMFunctionParameter flags;
751} HGCMMsgSessionClose;
752
753/**
754 * Reports back a guest session's status.
755 */
756typedef struct HGCMMsgSessionNotify
757{
758 VBGLIOCHGCMCALL hdr;
759 /** Context ID. */
760 HGCMFunctionParameter context;
761 /** Notification type. */
762 HGCMFunctionParameter type;
763 /** Notification result. */
764 HGCMFunctionParameter result;
765} HGCMMsgSessionNotify;
766
767typedef struct HGCMMsgPathRename
768{
769 VBGLIOCHGCMCALL hdr;
770 /** UInt32: Context ID. */
771 HGCMFunctionParameter context;
772 /** Source to rename. */
773 HGCMFunctionParameter source;
774 /** Destination to rename source to. */
775 HGCMFunctionParameter dest;
776 /** UInt32: Rename flags. */
777 HGCMFunctionParameter flags;
778} HGCMMsgPathRename;
779
780typedef struct HGCMMsgPathUserDocuments
781{
782 VBGLIOCHGCMCALL hdr;
783 /** UInt32: Context ID. */
784 HGCMFunctionParameter context;
785} HGCMMsgPathUserDocuments;
786
787typedef struct HGCMMsgPathUserHome
788{
789 VBGLIOCHGCMCALL hdr;
790 /** UInt32: Context ID. */
791 HGCMFunctionParameter context;
792} HGCMMsgPathUserHome;
793
794/**
795 * Executes a command inside the guest.
796 */
797typedef struct HGCMMsgProcExec
798{
799 VBGLIOCHGCMCALL hdr;
800 /** Context ID. */
801 HGCMFunctionParameter context;
802 /** The command to execute on the guest. */
803 HGCMFunctionParameter cmd;
804 /** Execution flags (see IGuest::ProcessCreateFlag_*). */
805 HGCMFunctionParameter flags;
806 /** Number of arguments. */
807 HGCMFunctionParameter num_args;
808 /** The actual arguments. */
809 HGCMFunctionParameter args;
810 /** Number of environment value pairs. */
811 HGCMFunctionParameter num_env;
812 /** Size (in bytes) of environment block, including terminating zeros. */
813 HGCMFunctionParameter cb_env;
814 /** The actual environment block. */
815 HGCMFunctionParameter env;
816 union
817 {
818 struct
819 {
820 /** The user name to run the executed command under.
821 * Only for VBox < 4.3 hosts. */
822 HGCMFunctionParameter username;
823 /** The user's password.
824 * Only for VBox < 4.3 hosts. */
825 HGCMFunctionParameter password;
826 /** Timeout (in msec) which either specifies the
827 * overall lifetime of the process or how long it
828 * can take to bring the process up and running -
829 * (depends on the IGuest::ProcessCreateFlag_*). */
830 HGCMFunctionParameter timeout;
831 } v1;
832 struct
833 {
834 /** Timeout (in ms) which either specifies the
835 * overall lifetime of the process or how long it
836 * can take to bring the process up and running -
837 * (depends on the IGuest::ProcessCreateFlag_*). */
838 HGCMFunctionParameter timeout;
839 /** Process priority. */
840 HGCMFunctionParameter priority;
841 /** Number of process affinity blocks. */
842 HGCMFunctionParameter num_affinity;
843 /** Pointer to process affinity blocks (uint64_t). */
844 HGCMFunctionParameter affinity;
845 } v2;
846 } u;
847} HGCMMsgProcExec;
848
849/**
850 * Sends input to a guest process via stdin.
851 */
852typedef struct HGCMMsgProcInput
853{
854 VBGLIOCHGCMCALL hdr;
855 /** Context ID. */
856 HGCMFunctionParameter context;
857 /** The process ID (PID) to send the input to. */
858 HGCMFunctionParameter pid;
859 /** Input flags (see IGuest::ProcessInputFlag_*). */
860 HGCMFunctionParameter flags;
861 /** Data buffer. */
862 HGCMFunctionParameter data;
863 /** Actual size of data (in bytes). */
864 HGCMFunctionParameter size;
865} HGCMMsgProcInput;
866
867/**
868 * Retrieves ouptut from a previously executed process
869 * from stdout/stderr.
870 */
871typedef struct HGCMMsgProcOutput
872{
873 VBGLIOCHGCMCALL hdr;
874 /** Context ID. */
875 HGCMFunctionParameter context;
876 /** The process ID (PID). */
877 HGCMFunctionParameter pid;
878 /** The pipe handle ID (stdout/stderr). */
879 HGCMFunctionParameter handle;
880 /** Optional flags. */
881 HGCMFunctionParameter flags;
882 /** Data buffer. */
883 HGCMFunctionParameter data;
884} HGCMMsgProcOutput;
885
886/**
887 * Reports the current status of a guest process.
888 */
889typedef struct HGCMMsgProcStatus
890{
891 VBGLIOCHGCMCALL hdr;
892 /** Context ID. */
893 HGCMFunctionParameter context;
894 /** The process ID (PID). */
895 HGCMFunctionParameter pid;
896 /** The process status. */
897 HGCMFunctionParameter status;
898 /** Optional flags (based on status). */
899 HGCMFunctionParameter flags;
900 /** Optional data buffer (not used atm). */
901 HGCMFunctionParameter data;
902} HGCMMsgProcStatus;
903
904/**
905 * Reports back the status of data written to a process.
906 */
907typedef struct HGCMMsgProcStatusInput
908{
909 VBGLIOCHGCMCALL hdr;
910 /** Context ID. */
911 HGCMFunctionParameter context;
912 /** The process ID (PID). */
913 HGCMFunctionParameter pid;
914 /** Status of the operation. */
915 HGCMFunctionParameter status;
916 /** Optional flags. */
917 HGCMFunctionParameter flags;
918 /** Data written. */
919 HGCMFunctionParameter written;
920} HGCMMsgProcStatusInput;
921
922/*
923 * Guest control 2.0 messages.
924 */
925
926/**
927 * Terminates a guest process.
928 */
929typedef struct HGCMMsgProcTerminate
930{
931 VBGLIOCHGCMCALL hdr;
932 /** Context ID. */
933 HGCMFunctionParameter context;
934 /** The process ID (PID). */
935 HGCMFunctionParameter pid;
936} HGCMMsgProcTerminate;
937
938/**
939 * Waits for certain events to happen.
940 */
941typedef struct HGCMMsgProcWaitFor
942{
943 VBGLIOCHGCMCALL hdr;
944 /** Context ID. */
945 HGCMFunctionParameter context;
946 /** The process ID (PID). */
947 HGCMFunctionParameter pid;
948 /** Wait (event) flags. */
949 HGCMFunctionParameter flags;
950 /** Timeout (in ms). */
951 HGCMFunctionParameter timeout;
952} HGCMMsgProcWaitFor;
953
954typedef struct HGCMMsgDirRemove
955{
956 VBGLIOCHGCMCALL hdr;
957 /** UInt32: Context ID. */
958 HGCMFunctionParameter context;
959 /** Directory to remove. */
960 HGCMFunctionParameter path;
961 /** UInt32: Removement flags. */
962 HGCMFunctionParameter flags;
963} HGCMMsgDirRemove;
964
965/**
966 * Opens a guest file.
967 */
968typedef struct HGCMMsgFileOpen
969{
970 VBGLIOCHGCMCALL hdr;
971 /** UInt32: Context ID. */
972 HGCMFunctionParameter context;
973 /** File to open. */
974 HGCMFunctionParameter filename;
975 /** Open mode. */
976 HGCMFunctionParameter openmode;
977 /** Disposition mode. */
978 HGCMFunctionParameter disposition;
979 /** Sharing mode. */
980 HGCMFunctionParameter sharing;
981 /** UInt32: Creation mode. */
982 HGCMFunctionParameter creationmode;
983 /** UInt64: Initial offset. */
984 HGCMFunctionParameter offset;
985} HGCMMsgFileOpen;
986
987/**
988 * Closes a guest file.
989 */
990typedef struct HGCMMsgFileClose
991{
992 VBGLIOCHGCMCALL hdr;
993 /** Context ID. */
994 HGCMFunctionParameter context;
995 /** File handle to close. */
996 HGCMFunctionParameter handle;
997} HGCMMsgFileClose;
998
999/**
1000 * Reads from a guest file.
1001 */
1002typedef struct HGCMMsgFileRead
1003{
1004 VBGLIOCHGCMCALL hdr;
1005 /** Context ID. */
1006 HGCMFunctionParameter context;
1007 /** File handle to read from. */
1008 HGCMFunctionParameter handle;
1009 /** Size (in bytes) to read. */
1010 HGCMFunctionParameter size;
1011} HGCMMsgFileRead;
1012
1013/**
1014 * Reads at a specified offset from a guest file.
1015 */
1016typedef struct HGCMMsgFileReadAt
1017{
1018 VBGLIOCHGCMCALL hdr;
1019 /** Context ID. */
1020 HGCMFunctionParameter context;
1021 /** File handle to read from. */
1022 HGCMFunctionParameter handle;
1023 /** Offset where to start reading from. */
1024 HGCMFunctionParameter offset;
1025 /** Actual size of data (in bytes). */
1026 HGCMFunctionParameter size;
1027} HGCMMsgFileReadAt;
1028
1029/**
1030 * Writes to a guest file.
1031 */
1032typedef struct HGCMMsgFileWrite
1033{
1034 VBGLIOCHGCMCALL hdr;
1035 /** Context ID. */
1036 HGCMFunctionParameter context;
1037 /** File handle to write to. */
1038 HGCMFunctionParameter handle;
1039 /** Actual size of data (in bytes). */
1040 HGCMFunctionParameter size;
1041 /** Data buffer to write to the file. */
1042 HGCMFunctionParameter data;
1043} HGCMMsgFileWrite;
1044
1045/**
1046 * Writes at a specified offset to a guest file.
1047 */
1048typedef struct HGCMMsgFileWriteAt
1049{
1050 VBGLIOCHGCMCALL hdr;
1051 /** Context ID. */
1052 HGCMFunctionParameter context;
1053 /** File handle to write to. */
1054 HGCMFunctionParameter handle;
1055 /** Offset where to start reading from. */
1056 HGCMFunctionParameter offset;
1057 /** Actual size of data (in bytes). */
1058 HGCMFunctionParameter size;
1059 /** Data buffer to write to the file. */
1060 HGCMFunctionParameter data;
1061} HGCMMsgFileWriteAt;
1062
1063/**
1064 * Seeks the read/write position of a guest file.
1065 */
1066typedef struct HGCMMsgFileSeek
1067{
1068 VBGLIOCHGCMCALL hdr;
1069 /** Context ID. */
1070 HGCMFunctionParameter context;
1071 /** File handle to seek. */
1072 HGCMFunctionParameter handle;
1073 /** The seeking method. */
1074 HGCMFunctionParameter method;
1075 /** The seeking offset. */
1076 HGCMFunctionParameter offset;
1077} HGCMMsgFileSeek;
1078
1079/**
1080 * Tells the current read/write position of a guest file.
1081 */
1082typedef struct HGCMMsgFileTell
1083{
1084 VBGLIOCHGCMCALL hdr;
1085 /** Context ID. */
1086 HGCMFunctionParameter context;
1087 /** File handle to get the current position for. */
1088 HGCMFunctionParameter handle;
1089} HGCMMsgFileTell;
1090
1091/******************************************************************************
1092* HGCM replies from the guest. These are handled in Main's low-level HGCM *
1093* callbacks and dispatched to the appropriate guest object. *
1094******************************************************************************/
1095
1096typedef struct HGCMReplyFileNotify
1097{
1098 VBGLIOCHGCMCALL hdr;
1099 /** Context ID. */
1100 HGCMFunctionParameter context;
1101 /** Notification type. */
1102 HGCMFunctionParameter type;
1103 /** IPRT result of overall operation. */
1104 HGCMFunctionParameter rc;
1105 union
1106 {
1107 struct
1108 {
1109 /** Guest file handle. */
1110 HGCMFunctionParameter handle;
1111 } open;
1112 /** Note: Close does not have any additional data (yet). */
1113 struct
1114 {
1115 /** Actual data read (if any). */
1116 HGCMFunctionParameter data;
1117 } read;
1118 struct
1119 {
1120 /** How much data (in bytes) have been successfully written. */
1121 HGCMFunctionParameter written;
1122 } write;
1123 struct
1124 {
1125 HGCMFunctionParameter offset;
1126 } seek;
1127 struct
1128 {
1129 HGCMFunctionParameter offset;
1130 } tell;
1131 } u;
1132} HGCMReplyFileNotify;
1133
1134typedef struct HGCMReplyDirNotify
1135{
1136 VBGLIOCHGCMCALL hdr;
1137 /** Context ID. */
1138 HGCMFunctionParameter context;
1139 /** Notification type. */
1140 HGCMFunctionParameter type;
1141 /** IPRT result of overall operation. */
1142 HGCMFunctionParameter rc;
1143 union
1144 {
1145 struct
1146 {
1147 /** Directory information. */
1148 HGCMFunctionParameter objInfo;
1149 } info;
1150 struct
1151 {
1152 /** Guest directory handle. */
1153 HGCMFunctionParameter handle;
1154 } open;
1155 struct
1156 {
1157 /** Current read directory entry. */
1158 HGCMFunctionParameter entry;
1159 /** Extended entry object information. Optional. */
1160 HGCMFunctionParameter objInfo;
1161 } read;
1162 } u;
1163} HGCMReplyDirNotify;
1164
1165#pragma pack ()
1166
1167/******************************************************************************
1168* Callback data structures. *
1169******************************************************************************/
1170
1171/**
1172 * The guest control callback data header. Must come first
1173 * on each callback structure defined below this struct.
1174 */
1175typedef struct CALLBACKDATA_HEADER
1176{
1177 /** Context ID to identify callback data. This is
1178 * and *must* be the very first parameter in this
1179 * structure to still be backwards compatible. */
1180 uint32_t uContextID;
1181} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
1182
1183/*
1184 * These structures make up the actual low level HGCM callback data sent from
1185 * the guest back to the host.
1186 */
1187
1188typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
1189{
1190 /** Callback data header. */
1191 CALLBACKDATA_HEADER hdr;
1192} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
1193
1194typedef struct CALLBACKDATA_MSG_REPLY
1195{
1196 /** Callback data header. */
1197 CALLBACKDATA_HEADER hdr;
1198 /** Notification type. */
1199 uint32_t uType;
1200 /** Notification result. Note: int vs. uint32! */
1201 uint32_t rc;
1202 /** Pointer to optional payload. */
1203 void *pvPayload;
1204 /** Payload size (in bytes). */
1205 uint32_t cbPayload;
1206} CALLBACKDATA_MSG_REPLY, *PCALLBACKDATA_MSG_REPLY;
1207
1208typedef struct CALLBACKDATA_SESSION_NOTIFY
1209{
1210 /** Callback data header. */
1211 CALLBACKDATA_HEADER hdr;
1212 /** Notification type. */
1213 uint32_t uType;
1214 /** Notification result. Note: int vs. uint32! */
1215 uint32_t uResult;
1216} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
1217
1218typedef struct CALLBACKDATA_PROC_STATUS
1219{
1220 /** Callback data header. */
1221 CALLBACKDATA_HEADER hdr;
1222 /** The process ID (PID). */
1223 uint32_t uPID;
1224 /** The process status. */
1225 uint32_t uStatus;
1226 /** Optional flags, varies, based on u32Status. */
1227 uint32_t uFlags;
1228 /** Optional data buffer (not used atm). */
1229 void *pvData;
1230 /** Size of optional data buffer (not used atm). */
1231 uint32_t cbData;
1232} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
1233
1234typedef struct CALLBACKDATA_PROC_OUTPUT
1235{
1236 /** Callback data header. */
1237 CALLBACKDATA_HEADER hdr;
1238 /** The process ID (PID). */
1239 uint32_t uPID;
1240 /** The handle ID (stdout/stderr). */
1241 uint32_t uHandle;
1242 /** Optional flags (not used atm). */
1243 uint32_t uFlags;
1244 /** Optional data buffer. */
1245 void *pvData;
1246 /** Size (in bytes) of optional data buffer. */
1247 uint32_t cbData;
1248} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
1249
1250typedef struct CALLBACKDATA_PROC_INPUT
1251{
1252 /** Callback data header. */
1253 CALLBACKDATA_HEADER hdr;
1254 /** The process ID (PID). */
1255 uint32_t uPID;
1256 /** Current input status. */
1257 uint32_t uStatus;
1258 /** Optional flags. */
1259 uint32_t uFlags;
1260 /** Size (in bytes) of processed input data. */
1261 uint32_t uProcessed;
1262} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
1263
1264/**
1265 * General guest directory notification callback.
1266 */
1267typedef struct CALLBACKDATA_DIR_NOTIFY
1268{
1269 /** Callback data header. */
1270 CALLBACKDATA_HEADER hdr;
1271 /** Notification type. */
1272 uint32_t uType;
1273 /** IPRT result of overall operation. */
1274 uint32_t rc;
1275 union
1276 {
1277 struct
1278 {
1279 /** Size (in bytes) of directory information. */
1280 uint32_t cbObjInfo;
1281 /** Pointer to directory information. */
1282 void *pvObjInfo;
1283 } info;
1284 struct
1285 {
1286 /** Guest directory handle. */
1287 uint32_t uHandle;
1288 } open;
1289 /** Note: Close does not have any additional data (yet). */
1290 struct
1291 {
1292 /** Size (in bytes) of directory entry information. */
1293 uint32_t cbEntry;
1294 /** Pointer to directory entry information. */
1295 void *pvEntry;
1296 /** Size (in bytes) of directory entry object information. */
1297 uint32_t cbObjInfo;
1298 /** Pointer to directory entry object information. */
1299 void *pvObjInfo;
1300 } read;
1301 } u;
1302} CALLBACKDATA_DIR_NOTIFY, *PCALLBACKDATA_DIR_NOTIFY;
1303
1304/**
1305 * General guest file notification callback.
1306 */
1307typedef struct CALLBACKDATA_FILE_NOTIFY
1308{
1309 /** Callback data header. */
1310 CALLBACKDATA_HEADER hdr;
1311 /** Notification type. */
1312 uint32_t uType;
1313 /** IPRT result of overall operation. */
1314 uint32_t rc;
1315 union
1316 {
1317 struct
1318 {
1319 /** Guest file handle. */
1320 uint32_t uHandle;
1321 } open;
1322 /** Note: Close does not have any additional data (yet). */
1323 struct
1324 {
1325 /** How much data (in bytes) have been read. */
1326 uint32_t cbData;
1327 /** Actual data read (if any). */
1328 void *pvData;
1329 } read;
1330 struct
1331 {
1332 /** How much data (in bytes) have been successfully written. */
1333 uint32_t cbWritten;
1334 } write;
1335 struct
1336 {
1337 /** New file offset after successful seek. */
1338 uint64_t uOffActual;
1339 } seek;
1340 struct
1341 {
1342 /** New file offset after successful tell. */
1343 uint64_t uOffActual;
1344 } tell;
1345 } u;
1346} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
1347
1348} /* namespace guestControl */
1349
1350#endif /* !___VBox_HostService_GuestControlService_h */
1351
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette