VirtualBox

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

最後變更 在這個檔案從75853是 75853,由 vboxsync 提交於 6 年 前

GuestControl,HGCM,VBoxService: Save/restore related optimizations and changes. bugref:9313
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 42.8 KB
行 
1/* $Id: GuestControlSvc.h 75853 2018-11-30 19:26:42Z 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.alldomusa.eu.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 * Does also support the VM restore checking as in GUEST_MSG_PEEK_WAIT (64-bit
325 * param \# 0), see documentation there.
326 *
327 * @retval VINF_SUCCESS if a message was pending and is being returned.
328 * @retval VERR_TRY_AGAIN if no message pending.
329 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
330 * does not match VbglR3GetSessionId() any more. The new value is
331 * returned.
332 * @retval VERR_INVALID_CLIENT_ID
333 * @retval VERR_WRONG_PARAMETER_COUNT
334 * @retval VERR_WRONG_PARAMETER_TYPE
335 * @since 6.0
336 */
337 GUEST_MSG_PEEK_NOWAIT = 6,
338 /** Peeks at the next message, waiting for one to arrive.
339 *
340 * Returns two 32-bit parameters, first is the message ID and the second the
341 * parameter count. May optionally return additional 32-bit parameters with the
342 * sizes of respective message parameters. To distinguish buffer sizes from
343 * integer parameters, the latter gets their sizes inverted (uint32_t is ~4U,
344 * uint64_t is ~8U).
345 *
346 * To facilitate VM restore checking, the first parameter can be a 64-bit
347 * integer holding the VbglR3GetSessionId() value the guest knowns. The
348 * function will then check this before going to sleep and return
349 * VERR_VM_RESTORED if it doesn't match, same thing happens when the VM is
350 * restored.
351 *
352 * @retval VINF_SUCCESS if info about an pending message is being returned.
353 * @retval VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if
354 * cancelled by GUEST_MSG_CANCEL.
355 * @retval VERR_RESOURCE_BUSY if another thread already made a waiting call.
356 * @retval VERR_VM_RESTORED if first parameter is a non-zero 64-bit value that
357 * does not match VbglR3GetSessionId() any more. The new value is
358 * returned.
359 * @retval VERR_INVALID_CLIENT_ID
360 * @retval VERR_WRONG_PARAMETER_COUNT
361 * @retval VERR_WRONG_PARAMETER_TYPE
362 * @note This replaces GUEST_MSG_WAIT.
363 * @since 6.0
364 */
365 GUEST_MSG_PEEK_WAIT = 7,
366 /** Gets the next message, returning immediately.
367 *
368 * All parameters are specific to the message being retrieved, however if the
369 * first one is an integer value it shall be an input parameter holding the
370 * ID of the message being retrieved. While it would be nice to add a separate
371 * parameter for this purpose, this is difficult without breaking GUEST_MSG_WAIT
372 * compatibility.
373 *
374 * @retval VINF_SUCCESS if message retrieved and removed from the pending queue.
375 * @retval VERR_TRY_AGAIN if no message pending.
376 * @retval VERR_MISMATCH if the incoming message ID does not match the pending.
377 * @retval VERR_BUFFER_OVERFLOW if a parmeter buffer is too small. The buffer
378 * size was updated to reflect the required size.
379 * @retval VERR_INVALID_CLIENT_ID
380 * @retval VERR_WRONG_PARAMETER_COUNT
381 * @retval VERR_WRONG_PARAMETER_TYPE
382 * @note This replaces GUEST_MSG_WAIT.
383 * @since 6.0
384 */
385 GUEST_MSG_GET = 8,
386 /** Skip message.
387 *
388 * This skips the current message, replying to the main backend as best it can.
389 * Takes between zero and two parameters. The first parameter is the 32-bit
390 * VBox status code to pass onto Main when skipping the command, defaults to
391 * VERR_NOT_SUPPORTED. The second parameter is the 32-bit message ID of the
392 * command to skip, by default whatever is first in the queue is removed. This
393 * is also the case if UINT32_MAX is specified.
394 *
395 * @retval VINF_SUCCESS on success.
396 * @retval VERR_NOT_FOUND if no message pending.
397 * @retval VERR_MISMATCH if the specified message ID didn't match.
398 * @retval VERR_INVALID_CLIENT_ID
399 * @retval VERR_WRONG_PARAMETER_COUNT
400 * @since 6.0
401 */
402 GUEST_MSG_SKIP = 9,
403 /**
404 * Skips the current assigned message returned by GUEST_MSG_WAIT.
405 * Needed for telling the host service to not keep stale
406 * host commands in the queue.
407 * @deprecated Replaced by GUEST_MSG_SKIP.
408 */
409 GUEST_MSG_SKIP_OLD = 10,
410 /** General reply to a host message.
411 * Only contains basic data along with a simple payload.
412 * @todo proper docs.
413 */
414 GUEST_MSG_REPLY = 11,
415 /** General message for updating a pending progress for a long task.
416 * @todo proper docs.
417 */
418 GUEST_MSG_PROGRESS_UPDATE = 12,
419 /** Sets the caller as the master.
420 *
421 * Called by the root VBoxService to explicitly tell the host that's the master
422 * service. Required to use main VBoxGuest device node. No parameters.
423 *
424 * @retval VINF_SUCCESS on success.
425 * @retval VERR_ACCESS_DENIED if not using main VBoxGuest device not
426 * @retval VERR_RESOURCE_BUSY if there is already a master.
427 * @retval VERR_VERSION_MISMATCH if VBoxGuest didn't supply requestor info.
428 * @retval VERR_INVALID_CLIENT_ID
429 * @retval VERR_WRONG_PARAMETER_COUNT
430 * @since 6.0
431 */
432 GUEST_MAKE_ME_MASTER = 13,
433 /** Prepares the starting of a session.
434 *
435 * VBoxService makes this call before spawning a session process (must be
436 * master). The first parameter is the session ID and the second is a one time
437 * key for identifying the right session process. First parameter is a 32-bit
438 * session ID with a value between 1 and 0xfff0. The second parameter is a byte
439 * buffer containing a key that GUEST_SESSION_ACCEPT checks against, minimum
440 * length is 64 bytes, maximum 16384 bytes.
441 *
442 * @retval VINF_SUCCESS on success.
443 * @retval VERR_OUT_OF_RESOURCES if too many pending sessions hanging around.
444 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
445 * @retval VERR_BUFFER_OVERFLOW if key too large.
446 * @retval VERR_BUFFER_UNDERFLOW if key too small.
447 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
448 * @retval VERR_DUPLICATE if the session ID has been prepared already.
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_PREPARE = 14,
455 /** Cancels a prepared session.
456 *
457 * VBoxService makes this call to clean up after spawning a session process
458 * failed. One parameter, 32-bit session ID. If UINT32_MAX is passed, all
459 * prepared sessions are cancelled.
460 *
461 * @retval VINF_SUCCESS on success.
462 * @retval VWRN_NOT_FOUND if no session with the specified ID.
463 * @retval VERR_ACCESS_DENIED if not master or in legacy mode.
464 * @retval VERR_INVALID_CLIENT_ID
465 * @retval VERR_WRONG_PARAMETER_COUNT
466 * @retval VERR_WRONG_PARAMETER_TYPE
467 * @since 6.0
468 */
469 GUEST_SESSION_CANCEL_PREPARED = 15,
470 /** Accepts a prepared session.
471 *
472 * The session processes makes this call to accept a prepared session. The
473 * session ID is then uniquely associated with the HGCM client ID of the caller.
474 * The parameters must be identical to the matching GUEST_SESSION_PREPARE call.
475 *
476 * @retval VINF_SUCCESS on success.
477 * @retval VERR_NOT_FOUND if the specified session ID wasn't found.
478 * @retval VERR_OUT_OF_RANGE if the session ID outside the allowed range.
479 * @retval VERR_BUFFER_OVERFLOW if key too large.
480 * @retval VERR_BUFFER_UNDERFLOW if key too small.
481 * @retval VERR_ACCESS_DENIED if we're in legacy mode or is master.
482 * @retval VERR_RESOURCE_BUSY if the client is already associated with a session.
483 * @retval VERR_MISMATCH if the key didn't match.
484 * @retval VERR_INVALID_CLIENT_ID
485 * @retval VERR_WRONG_PARAMETER_COUNT
486 * @retval VERR_WRONG_PARAMETER_TYPE
487 * @since 6.0
488 */
489 GUEST_SESSION_ACCEPT = 16,
490 /**
491 * Guest reports back a guest session status.
492 * @todo proper docs.
493 */
494 GUEST_SESSION_NOTIFY = 20,
495 /**
496 * Guest wants to close a specific guest session.
497 * @todo proper docs.
498 */
499 GUEST_SESSION_CLOSE = 21,
500
501 /**
502 * Guests sends output from an executed process.
503 * @todo proper docs.
504 */
505 GUEST_EXEC_OUTPUT = 100,
506 /**
507 * Guest sends a status update of an executed process to the host.
508 * @todo proper docs.
509 */
510 GUEST_EXEC_STATUS = 101,
511 /**
512 * Guests sends an input status notification to the host.
513 * @todo proper docs.
514 */
515 GUEST_EXEC_INPUT_STATUS = 102,
516 /**
517 * Guest notifies the host about some I/O event. This can be
518 * a stdout, stderr or a stdin event. The actual event only tells
519 * how many data is available / can be sent without actually
520 * transmitting the data.
521 * @todo proper docs.
522 */
523 GUEST_EXEC_IO_NOTIFY = 210,
524 /**
525 * Guest notifies the host about some directory event.
526 * @todo proper docs.
527 */
528 GUEST_DIR_NOTIFY = 230,
529 /**
530 * Guest notifies the host about some file event.
531 * @todo proper docs.
532 */
533 GUEST_FILE_NOTIFY = 240
534};
535
536/**
537 * Translates a guest control host function function enum to at string.
538 * @returns Enum string name.
539 * @param enmFunction The function name to translate.
540 */
541DECLINLINE(const char *) GstCtrlGuestFnName(enum eGuestFn enmFunction)
542{
543 switch (enmFunction)
544 {
545 RT_CASE_RET_STR(GUEST_MSG_WAIT);
546 RT_CASE_RET_STR(GUEST_MSG_CANCEL);
547 RT_CASE_RET_STR(GUEST_DISCONNECTED);
548 RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
549 RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
550 RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT);
551 RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT);
552 RT_CASE_RET_STR(GUEST_MSG_GET);
553 RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD);
554 RT_CASE_RET_STR(GUEST_MSG_REPLY);
555 RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
556 RT_CASE_RET_STR(GUEST_MSG_SKIP);
557 RT_CASE_RET_STR(GUEST_MAKE_ME_MASTER);
558 RT_CASE_RET_STR(GUEST_SESSION_PREPARE);
559 RT_CASE_RET_STR(GUEST_SESSION_CANCEL_PREPARED);
560 RT_CASE_RET_STR(GUEST_SESSION_ACCEPT);
561 RT_CASE_RET_STR(GUEST_SESSION_NOTIFY);
562 RT_CASE_RET_STR(GUEST_SESSION_CLOSE);
563 RT_CASE_RET_STR(GUEST_EXEC_OUTPUT);
564 RT_CASE_RET_STR(GUEST_EXEC_STATUS);
565 RT_CASE_RET_STR(GUEST_EXEC_INPUT_STATUS);
566 RT_CASE_RET_STR(GUEST_EXEC_IO_NOTIFY);
567 RT_CASE_RET_STR(GUEST_DIR_NOTIFY);
568 RT_CASE_RET_STR(GUEST_FILE_NOTIFY);
569 }
570 return "Unknown";
571}
572
573
574/**
575 * Guest session notification types.
576 * @sa HGCMMsgSessionNotify.
577 */
578enum GUEST_SESSION_NOTIFYTYPE
579{
580 GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
581 /** Something went wrong (see rc). */
582 GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
583 /** Guest session has been started. */
584 GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
585 /** Guest session terminated normally. */
586 GUEST_SESSION_NOTIFYTYPE_TEN = 20,
587 /** Guest session terminated via signal. */
588 GUEST_SESSION_NOTIFYTYPE_TES = 30,
589 /** Guest session terminated abnormally. */
590 GUEST_SESSION_NOTIFYTYPE_TEA = 40,
591 /** Guest session timed out and was killed. */
592 GUEST_SESSION_NOTIFYTYPE_TOK = 50,
593 /** Guest session timed out and was not killed successfully. */
594 GUEST_SESSION_NOTIFYTYPE_TOA = 60,
595 /** Service/OS is stopping, process was killed. */
596 GUEST_SESSION_NOTIFYTYPE_DWN = 150
597};
598
599/**
600 * Guest directory notification types.
601 * @sa HGCMMsgDirNotify.
602 */
603enum GUEST_DIR_NOTIFYTYPE
604{
605 GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0,
606 /** Something went wrong (see rc). */
607 GUEST_DIR_NOTIFYTYPE_ERROR = 1,
608 /** Guest directory opened. */
609 GUEST_DIR_NOTIFYTYPE_OPEN = 10,
610 /** Guest directory closed. */
611 GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
612 /** Information about an open guest directory. */
613 GUEST_DIR_NOTIFYTYPE_INFO = 40,
614 /** Guest directory created. */
615 GUEST_DIR_NOTIFYTYPE_CREATE = 70,
616 /** Guest directory deleted. */
617 GUEST_DIR_NOTIFYTYPE_REMOVE = 80
618};
619
620/**
621 * Guest file notification types.
622 * @sa HGCMMsgFileNotify.
623 */
624enum GUEST_FILE_NOTIFYTYPE
625{
626 GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
627 GUEST_FILE_NOTIFYTYPE_ERROR = 1,
628 GUEST_FILE_NOTIFYTYPE_OPEN = 10,
629 GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
630 GUEST_FILE_NOTIFYTYPE_READ = 30,
631 GUEST_FILE_NOTIFYTYPE_WRITE = 40,
632 GUEST_FILE_NOTIFYTYPE_SEEK = 50,
633 GUEST_FILE_NOTIFYTYPE_TELL = 60
634};
635
636/**
637 * Guest file seeking types. Has to match FileSeekType in Main.
638 *
639 * @note This is not compatible with RTFileSeek, which is an unncessary pain.
640 */
641enum GUEST_FILE_SEEKTYPE
642{
643 GUEST_FILE_SEEKTYPE_BEGIN = 1,
644 GUEST_FILE_SEEKTYPE_CURRENT = 4,
645 GUEST_FILE_SEEKTYPE_END = 8
646};
647
648/*
649 * HGCM parameter structures.
650 */
651#pragma pack (1)
652
653/**
654 * Waits for a host command to arrive. The structure then contains the
655 * actual message type + required number of parameters needed to successfully
656 * retrieve that host command (in a next round).
657 */
658typedef struct HGCMMsgCmdWaitFor
659{
660 VBGLIOCHGCMCALL hdr;
661 /**
662 * The returned command the host wants to
663 * run on the guest.
664 */
665 HGCMFunctionParameter msg; /* OUT uint32_t */
666 /** Number of parameters the message needs. */
667 HGCMFunctionParameter num_parms; /* OUT uint32_t */
668} HGCMMsgCmdWaitFor;
669
670/**
671 * Asks the guest control host service to set a command
672 * filter for this client. This filter will then only
673 * deliver messages to the client which match the
674 * wanted context ID (ranges).
675 */
676typedef struct HGCMMsgCmdFilterSet
677{
678 VBGLIOCHGCMCALL hdr;
679 /** Value to filter for after filter mask
680 * was applied. */
681 HGCMFunctionParameter value; /* IN uint32_t */
682 /** Mask to add to the current set filter. */
683 HGCMFunctionParameter mask_add; /* IN uint32_t */
684 /** Mask to remove from the current set filter. */
685 HGCMFunctionParameter mask_remove; /* IN uint32_t */
686 /** Filter flags; currently unused. */
687 HGCMFunctionParameter flags; /* IN uint32_t */
688} HGCMMsgCmdFilterSet;
689
690/**
691 * Asks the guest control host service to disable
692 * a previously set message filter again.
693 */
694typedef struct HGCMMsgCmdFilterUnset
695{
696 VBGLIOCHGCMCALL hdr;
697 /** Unset flags; currently unused. */
698 HGCMFunctionParameter flags; /* IN uint32_t */
699} HGCMMsgCmdFilterUnset;
700
701/**
702 * Asks the guest control host service to skip the
703 * currently assigned host command returned by
704 * VbglR3GuestCtrlMsgWaitFor().
705 */
706typedef struct HGCMMsgCmdSkip
707{
708 VBGLIOCHGCMCALL hdr;
709 /** Skip flags; currently unused. */
710 HGCMFunctionParameter flags; /* IN uint32_t */
711} HGCMMsgCmdSkip;
712
713/**
714 * Asks the guest control host service to cancel all pending (outstanding)
715 * waits which were not processed yet. This is handy for a graceful shutdown.
716 */
717typedef struct HGCMMsgCancelPendingWaits
718{
719 VBGLIOCHGCMCALL hdr;
720} HGCMMsgCancelPendingWaits;
721
722typedef struct HGCMMsgCmdReply
723{
724 VBGLIOCHGCMCALL hdr;
725 /** Context ID. */
726 HGCMFunctionParameter context;
727 /** Message type. */
728 HGCMFunctionParameter type;
729 /** IPRT result of overall operation. */
730 HGCMFunctionParameter rc;
731 /** Optional payload to this reply. */
732 HGCMFunctionParameter payload;
733} HGCMMsgCmdReply;
734
735/**
736 * Creates a guest session.
737 */
738typedef struct HGCMMsgSessionOpen
739{
740 VBGLIOCHGCMCALL hdr;
741 /** Context ID. */
742 HGCMFunctionParameter context;
743 /** The guest control protocol version this
744 * session is about to use. */
745 HGCMFunctionParameter protocol;
746 /** The user name to run the guest session under. */
747 HGCMFunctionParameter username;
748 /** The user's password. */
749 HGCMFunctionParameter password;
750 /** The domain to run the guest session under. */
751 HGCMFunctionParameter domain;
752 /** Session creation flags. */
753 HGCMFunctionParameter flags;
754} HGCMMsgSessionOpen;
755
756/**
757 * Terminates (closes) a guest session.
758 */
759typedef struct HGCMMsgSessionClose
760{
761 VBGLIOCHGCMCALL hdr;
762 /** Context ID. */
763 HGCMFunctionParameter context;
764 /** Session termination flags. */
765 HGCMFunctionParameter flags;
766} HGCMMsgSessionClose;
767
768/**
769 * Reports back a guest session's status.
770 */
771typedef struct HGCMMsgSessionNotify
772{
773 VBGLIOCHGCMCALL hdr;
774 /** Context ID. */
775 HGCMFunctionParameter context;
776 /** Notification type. */
777 HGCMFunctionParameter type;
778 /** Notification result. */
779 HGCMFunctionParameter result;
780} HGCMMsgSessionNotify;
781
782typedef struct HGCMMsgPathRename
783{
784 VBGLIOCHGCMCALL hdr;
785 /** UInt32: Context ID. */
786 HGCMFunctionParameter context;
787 /** Source to rename. */
788 HGCMFunctionParameter source;
789 /** Destination to rename source to. */
790 HGCMFunctionParameter dest;
791 /** UInt32: Rename flags. */
792 HGCMFunctionParameter flags;
793} HGCMMsgPathRename;
794
795typedef struct HGCMMsgPathUserDocuments
796{
797 VBGLIOCHGCMCALL hdr;
798 /** UInt32: Context ID. */
799 HGCMFunctionParameter context;
800} HGCMMsgPathUserDocuments;
801
802typedef struct HGCMMsgPathUserHome
803{
804 VBGLIOCHGCMCALL hdr;
805 /** UInt32: Context ID. */
806 HGCMFunctionParameter context;
807} HGCMMsgPathUserHome;
808
809/**
810 * Executes a command inside the guest.
811 */
812typedef struct HGCMMsgProcExec
813{
814 VBGLIOCHGCMCALL hdr;
815 /** Context ID. */
816 HGCMFunctionParameter context;
817 /** The command to execute on the guest. */
818 HGCMFunctionParameter cmd;
819 /** Execution flags (see IGuest::ProcessCreateFlag_*). */
820 HGCMFunctionParameter flags;
821 /** Number of arguments. */
822 HGCMFunctionParameter num_args;
823 /** The actual arguments. */
824 HGCMFunctionParameter args;
825 /** Number of environment value pairs. */
826 HGCMFunctionParameter num_env;
827 /** Size (in bytes) of environment block, including terminating zeros. */
828 HGCMFunctionParameter cb_env;
829 /** The actual environment block. */
830 HGCMFunctionParameter env;
831 union
832 {
833 struct
834 {
835 /** The user name to run the executed command under.
836 * Only for VBox < 4.3 hosts. */
837 HGCMFunctionParameter username;
838 /** The user's password.
839 * Only for VBox < 4.3 hosts. */
840 HGCMFunctionParameter password;
841 /** Timeout (in msec) which either specifies the
842 * overall lifetime of the process or how long it
843 * can take to bring the process up and running -
844 * (depends on the IGuest::ProcessCreateFlag_*). */
845 HGCMFunctionParameter timeout;
846 } v1;
847 struct
848 {
849 /** Timeout (in ms) which either specifies the
850 * overall lifetime of the process or how long it
851 * can take to bring the process up and running -
852 * (depends on the IGuest::ProcessCreateFlag_*). */
853 HGCMFunctionParameter timeout;
854 /** Process priority. */
855 HGCMFunctionParameter priority;
856 /** Number of process affinity blocks. */
857 HGCMFunctionParameter num_affinity;
858 /** Pointer to process affinity blocks (uint64_t). */
859 HGCMFunctionParameter affinity;
860 } v2;
861 } u;
862} HGCMMsgProcExec;
863
864/**
865 * Sends input to a guest process via stdin.
866 */
867typedef struct HGCMMsgProcInput
868{
869 VBGLIOCHGCMCALL hdr;
870 /** Context ID. */
871 HGCMFunctionParameter context;
872 /** The process ID (PID) to send the input to. */
873 HGCMFunctionParameter pid;
874 /** Input flags (see IGuest::ProcessInputFlag_*). */
875 HGCMFunctionParameter flags;
876 /** Data buffer. */
877 HGCMFunctionParameter data;
878 /** Actual size of data (in bytes). */
879 HGCMFunctionParameter size;
880} HGCMMsgProcInput;
881
882/**
883 * Retrieves ouptut from a previously executed process
884 * from stdout/stderr.
885 */
886typedef struct HGCMMsgProcOutput
887{
888 VBGLIOCHGCMCALL hdr;
889 /** Context ID. */
890 HGCMFunctionParameter context;
891 /** The process ID (PID). */
892 HGCMFunctionParameter pid;
893 /** The pipe handle ID (stdout/stderr). */
894 HGCMFunctionParameter handle;
895 /** Optional flags. */
896 HGCMFunctionParameter flags;
897 /** Data buffer. */
898 HGCMFunctionParameter data;
899} HGCMMsgProcOutput;
900
901/**
902 * Reports the current status of a guest process.
903 */
904typedef struct HGCMMsgProcStatus
905{
906 VBGLIOCHGCMCALL hdr;
907 /** Context ID. */
908 HGCMFunctionParameter context;
909 /** The process ID (PID). */
910 HGCMFunctionParameter pid;
911 /** The process status. */
912 HGCMFunctionParameter status;
913 /** Optional flags (based on status). */
914 HGCMFunctionParameter flags;
915 /** Optional data buffer (not used atm). */
916 HGCMFunctionParameter data;
917} HGCMMsgProcStatus;
918
919/**
920 * Reports back the status of data written to a process.
921 */
922typedef struct HGCMMsgProcStatusInput
923{
924 VBGLIOCHGCMCALL hdr;
925 /** Context ID. */
926 HGCMFunctionParameter context;
927 /** The process ID (PID). */
928 HGCMFunctionParameter pid;
929 /** Status of the operation. */
930 HGCMFunctionParameter status;
931 /** Optional flags. */
932 HGCMFunctionParameter flags;
933 /** Data written. */
934 HGCMFunctionParameter written;
935} HGCMMsgProcStatusInput;
936
937/*
938 * Guest control 2.0 messages.
939 */
940
941/**
942 * Terminates a guest process.
943 */
944typedef struct HGCMMsgProcTerminate
945{
946 VBGLIOCHGCMCALL hdr;
947 /** Context ID. */
948 HGCMFunctionParameter context;
949 /** The process ID (PID). */
950 HGCMFunctionParameter pid;
951} HGCMMsgProcTerminate;
952
953/**
954 * Waits for certain events to happen.
955 */
956typedef struct HGCMMsgProcWaitFor
957{
958 VBGLIOCHGCMCALL hdr;
959 /** Context ID. */
960 HGCMFunctionParameter context;
961 /** The process ID (PID). */
962 HGCMFunctionParameter pid;
963 /** Wait (event) flags. */
964 HGCMFunctionParameter flags;
965 /** Timeout (in ms). */
966 HGCMFunctionParameter timeout;
967} HGCMMsgProcWaitFor;
968
969typedef struct HGCMMsgDirRemove
970{
971 VBGLIOCHGCMCALL hdr;
972 /** UInt32: Context ID. */
973 HGCMFunctionParameter context;
974 /** Directory to remove. */
975 HGCMFunctionParameter path;
976 /** UInt32: Removement flags. */
977 HGCMFunctionParameter flags;
978} HGCMMsgDirRemove;
979
980/**
981 * Opens a guest file.
982 */
983typedef struct HGCMMsgFileOpen
984{
985 VBGLIOCHGCMCALL hdr;
986 /** UInt32: Context ID. */
987 HGCMFunctionParameter context;
988 /** File to open. */
989 HGCMFunctionParameter filename;
990 /** Open mode. */
991 HGCMFunctionParameter openmode;
992 /** Disposition mode. */
993 HGCMFunctionParameter disposition;
994 /** Sharing mode. */
995 HGCMFunctionParameter sharing;
996 /** UInt32: Creation mode. */
997 HGCMFunctionParameter creationmode;
998 /** UInt64: Initial offset. */
999 HGCMFunctionParameter offset;
1000} HGCMMsgFileOpen;
1001
1002/**
1003 * Closes a guest file.
1004 */
1005typedef struct HGCMMsgFileClose
1006{
1007 VBGLIOCHGCMCALL hdr;
1008 /** Context ID. */
1009 HGCMFunctionParameter context;
1010 /** File handle to close. */
1011 HGCMFunctionParameter handle;
1012} HGCMMsgFileClose;
1013
1014/**
1015 * Reads from a guest file.
1016 */
1017typedef struct HGCMMsgFileRead
1018{
1019 VBGLIOCHGCMCALL hdr;
1020 /** Context ID. */
1021 HGCMFunctionParameter context;
1022 /** File handle to read from. */
1023 HGCMFunctionParameter handle;
1024 /** Size (in bytes) to read. */
1025 HGCMFunctionParameter size;
1026} HGCMMsgFileRead;
1027
1028/**
1029 * Reads at a specified offset from a guest file.
1030 */
1031typedef struct HGCMMsgFileReadAt
1032{
1033 VBGLIOCHGCMCALL hdr;
1034 /** Context ID. */
1035 HGCMFunctionParameter context;
1036 /** File handle to read from. */
1037 HGCMFunctionParameter handle;
1038 /** Offset where to start reading from. */
1039 HGCMFunctionParameter offset;
1040 /** Actual size of data (in bytes). */
1041 HGCMFunctionParameter size;
1042} HGCMMsgFileReadAt;
1043
1044/**
1045 * Writes to a guest file.
1046 */
1047typedef struct HGCMMsgFileWrite
1048{
1049 VBGLIOCHGCMCALL hdr;
1050 /** Context ID. */
1051 HGCMFunctionParameter context;
1052 /** File handle to write to. */
1053 HGCMFunctionParameter handle;
1054 /** Actual size of data (in bytes). */
1055 HGCMFunctionParameter size;
1056 /** Data buffer to write to the file. */
1057 HGCMFunctionParameter data;
1058} HGCMMsgFileWrite;
1059
1060/**
1061 * Writes at a specified offset to a guest file.
1062 */
1063typedef struct HGCMMsgFileWriteAt
1064{
1065 VBGLIOCHGCMCALL hdr;
1066 /** Context ID. */
1067 HGCMFunctionParameter context;
1068 /** File handle to write to. */
1069 HGCMFunctionParameter handle;
1070 /** Offset where to start reading from. */
1071 HGCMFunctionParameter offset;
1072 /** Actual size of data (in bytes). */
1073 HGCMFunctionParameter size;
1074 /** Data buffer to write to the file. */
1075 HGCMFunctionParameter data;
1076} HGCMMsgFileWriteAt;
1077
1078/**
1079 * Seeks the read/write position of a guest file.
1080 */
1081typedef struct HGCMMsgFileSeek
1082{
1083 VBGLIOCHGCMCALL hdr;
1084 /** Context ID. */
1085 HGCMFunctionParameter context;
1086 /** File handle to seek. */
1087 HGCMFunctionParameter handle;
1088 /** The seeking method. */
1089 HGCMFunctionParameter method;
1090 /** The seeking offset. */
1091 HGCMFunctionParameter offset;
1092} HGCMMsgFileSeek;
1093
1094/**
1095 * Tells the current read/write position of a guest file.
1096 */
1097typedef struct HGCMMsgFileTell
1098{
1099 VBGLIOCHGCMCALL hdr;
1100 /** Context ID. */
1101 HGCMFunctionParameter context;
1102 /** File handle to get the current position for. */
1103 HGCMFunctionParameter handle;
1104} HGCMMsgFileTell;
1105
1106/******************************************************************************
1107* HGCM replies from the guest. These are handled in Main's low-level HGCM *
1108* callbacks and dispatched to the appropriate guest object. *
1109******************************************************************************/
1110
1111typedef struct HGCMReplyFileNotify
1112{
1113 VBGLIOCHGCMCALL hdr;
1114 /** Context ID. */
1115 HGCMFunctionParameter context;
1116 /** Notification type. */
1117 HGCMFunctionParameter type;
1118 /** IPRT result of overall operation. */
1119 HGCMFunctionParameter rc;
1120 union
1121 {
1122 struct
1123 {
1124 /** Guest file handle. */
1125 HGCMFunctionParameter handle;
1126 } open;
1127 /** Note: Close does not have any additional data (yet). */
1128 struct
1129 {
1130 /** Actual data read (if any). */
1131 HGCMFunctionParameter data;
1132 } read;
1133 struct
1134 {
1135 /** How much data (in bytes) have been successfully written. */
1136 HGCMFunctionParameter written;
1137 } write;
1138 struct
1139 {
1140 HGCMFunctionParameter offset;
1141 } seek;
1142 struct
1143 {
1144 HGCMFunctionParameter offset;
1145 } tell;
1146 } u;
1147} HGCMReplyFileNotify;
1148
1149typedef struct HGCMReplyDirNotify
1150{
1151 VBGLIOCHGCMCALL hdr;
1152 /** Context ID. */
1153 HGCMFunctionParameter context;
1154 /** Notification type. */
1155 HGCMFunctionParameter type;
1156 /** IPRT result of overall operation. */
1157 HGCMFunctionParameter rc;
1158 union
1159 {
1160 struct
1161 {
1162 /** Directory information. */
1163 HGCMFunctionParameter objInfo;
1164 } info;
1165 struct
1166 {
1167 /** Guest directory handle. */
1168 HGCMFunctionParameter handle;
1169 } open;
1170 struct
1171 {
1172 /** Current read directory entry. */
1173 HGCMFunctionParameter entry;
1174 /** Extended entry object information. Optional. */
1175 HGCMFunctionParameter objInfo;
1176 } read;
1177 } u;
1178} HGCMReplyDirNotify;
1179
1180#pragma pack ()
1181
1182/******************************************************************************
1183* Callback data structures. *
1184******************************************************************************/
1185
1186/**
1187 * The guest control callback data header. Must come first
1188 * on each callback structure defined below this struct.
1189 */
1190typedef struct CALLBACKDATA_HEADER
1191{
1192 /** Context ID to identify callback data. This is
1193 * and *must* be the very first parameter in this
1194 * structure to still be backwards compatible. */
1195 uint32_t uContextID;
1196} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
1197
1198/*
1199 * These structures make up the actual low level HGCM callback data sent from
1200 * the guest back to the host.
1201 */
1202
1203typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
1204{
1205 /** Callback data header. */
1206 CALLBACKDATA_HEADER hdr;
1207} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
1208
1209typedef struct CALLBACKDATA_MSG_REPLY
1210{
1211 /** Callback data header. */
1212 CALLBACKDATA_HEADER hdr;
1213 /** Notification type. */
1214 uint32_t uType;
1215 /** Notification result. Note: int vs. uint32! */
1216 uint32_t rc;
1217 /** Pointer to optional payload. */
1218 void *pvPayload;
1219 /** Payload size (in bytes). */
1220 uint32_t cbPayload;
1221} CALLBACKDATA_MSG_REPLY, *PCALLBACKDATA_MSG_REPLY;
1222
1223typedef struct CALLBACKDATA_SESSION_NOTIFY
1224{
1225 /** Callback data header. */
1226 CALLBACKDATA_HEADER hdr;
1227 /** Notification type. */
1228 uint32_t uType;
1229 /** Notification result. Note: int vs. uint32! */
1230 uint32_t uResult;
1231} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
1232
1233typedef struct CALLBACKDATA_PROC_STATUS
1234{
1235 /** Callback data header. */
1236 CALLBACKDATA_HEADER hdr;
1237 /** The process ID (PID). */
1238 uint32_t uPID;
1239 /** The process status. */
1240 uint32_t uStatus;
1241 /** Optional flags, varies, based on u32Status. */
1242 uint32_t uFlags;
1243 /** Optional data buffer (not used atm). */
1244 void *pvData;
1245 /** Size of optional data buffer (not used atm). */
1246 uint32_t cbData;
1247} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
1248
1249typedef struct CALLBACKDATA_PROC_OUTPUT
1250{
1251 /** Callback data header. */
1252 CALLBACKDATA_HEADER hdr;
1253 /** The process ID (PID). */
1254 uint32_t uPID;
1255 /** The handle ID (stdout/stderr). */
1256 uint32_t uHandle;
1257 /** Optional flags (not used atm). */
1258 uint32_t uFlags;
1259 /** Optional data buffer. */
1260 void *pvData;
1261 /** Size (in bytes) of optional data buffer. */
1262 uint32_t cbData;
1263} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
1264
1265typedef struct CALLBACKDATA_PROC_INPUT
1266{
1267 /** Callback data header. */
1268 CALLBACKDATA_HEADER hdr;
1269 /** The process ID (PID). */
1270 uint32_t uPID;
1271 /** Current input status. */
1272 uint32_t uStatus;
1273 /** Optional flags. */
1274 uint32_t uFlags;
1275 /** Size (in bytes) of processed input data. */
1276 uint32_t uProcessed;
1277} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
1278
1279/**
1280 * General guest directory notification callback.
1281 */
1282typedef struct CALLBACKDATA_DIR_NOTIFY
1283{
1284 /** Callback data header. */
1285 CALLBACKDATA_HEADER hdr;
1286 /** Notification type. */
1287 uint32_t uType;
1288 /** IPRT result of overall operation. */
1289 uint32_t rc;
1290 union
1291 {
1292 struct
1293 {
1294 /** Size (in bytes) of directory information. */
1295 uint32_t cbObjInfo;
1296 /** Pointer to directory information. */
1297 void *pvObjInfo;
1298 } info;
1299 struct
1300 {
1301 /** Guest directory handle. */
1302 uint32_t uHandle;
1303 } open;
1304 /** Note: Close does not have any additional data (yet). */
1305 struct
1306 {
1307 /** Size (in bytes) of directory entry information. */
1308 uint32_t cbEntry;
1309 /** Pointer to directory entry information. */
1310 void *pvEntry;
1311 /** Size (in bytes) of directory entry object information. */
1312 uint32_t cbObjInfo;
1313 /** Pointer to directory entry object information. */
1314 void *pvObjInfo;
1315 } read;
1316 } u;
1317} CALLBACKDATA_DIR_NOTIFY, *PCALLBACKDATA_DIR_NOTIFY;
1318
1319/**
1320 * General guest file notification callback.
1321 */
1322typedef struct CALLBACKDATA_FILE_NOTIFY
1323{
1324 /** Callback data header. */
1325 CALLBACKDATA_HEADER hdr;
1326 /** Notification type. */
1327 uint32_t uType;
1328 /** IPRT result of overall operation. */
1329 uint32_t rc;
1330 union
1331 {
1332 struct
1333 {
1334 /** Guest file handle. */
1335 uint32_t uHandle;
1336 } open;
1337 /** Note: Close does not have any additional data (yet). */
1338 struct
1339 {
1340 /** How much data (in bytes) have been read. */
1341 uint32_t cbData;
1342 /** Actual data read (if any). */
1343 void *pvData;
1344 } read;
1345 struct
1346 {
1347 /** How much data (in bytes) have been successfully written. */
1348 uint32_t cbWritten;
1349 } write;
1350 struct
1351 {
1352 /** New file offset after successful seek. */
1353 uint64_t uOffActual;
1354 } seek;
1355 struct
1356 {
1357 /** New file offset after successful tell. */
1358 uint64_t uOffActual;
1359 } tell;
1360 } u;
1361} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
1362
1363} /* namespace guestControl */
1364
1365#endif /* !___VBox_HostService_GuestControlService_h */
1366
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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