VirtualBox

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

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

GuestControlSvc.h: cleanups. bugref:9320
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 43.0 KB
行 
1/* $Id: GuestControlSvc.h 79286 2019-06-22 00:03:47Z vboxsync $ */
2/** @file
3 * Guest control service - Common header for host service and guest clients.
4 */
5
6/*
7 * Copyright (C) 2011-2019 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_INCLUDED_HostServices_GuestControlSvc_h
28#define VBOX_INCLUDED_HostServices_GuestControlSvc_h
29#ifndef RT_WITHOUT_PRAGMA_ONCE
30# pragma once
31#endif
32
33#include <VBox/VMMDevCoreTypes.h>
34#include <VBox/VBoxGuestCoreTypes.h>
35#include <VBox/hgcmsvc.h>
36#include <iprt/assert.h>
37
38/* Everything defined in this file lives in this namespace. */
39namespace guestControl {
40
41/******************************************************************************
42* Typedefs, constants and inlines *
43******************************************************************************/
44
45#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
46
47/** Maximum number of concurrent guest sessions a VM can have. */
48#define VBOX_GUESTCTRL_MAX_SESSIONS 32
49/** Maximum number of concurrent guest objects (processes, files, ...)
50 * a guest session can have. */
51#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
52/** Maximum of callback contexts a guest process can have. */
53#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
54
55/** Base (start) of guest control session IDs. Session
56 * ID 0 is reserved for the root process which
57 * hosts all other guest session processes. */
58#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
59
60/** Builds a context ID out of the session ID, object ID and an
61 * increasing count. */
62#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
63 ( (uint32_t)((uSession) & 0x1f) << 27 \
64 | (uint32_t)((uObject) & 0x7ff) << 16 \
65 | (uint32_t)((uCount) & 0xffff) \
66 )
67/** Creates a context ID out of a session ID. */
68#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
69 ((uint32_t)((uSession) & 0x1f) << 27)
70/** Gets the session ID out of a context ID. */
71#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
72 (((uContextID) >> 27) & 0x1f)
73/** Gets the process ID out of a context ID. */
74#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
75 (((uContextID) >> 16) & 0x7ff)
76/** Gets the context count of a process out of a context ID. */
77#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
78 ((uContextID) & 0xffff)
79/** Filter context IDs by session. Can be used in conjunction
80 * with VbglR3GuestCtrlMsgFilterSet(). */
81#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
82 (VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) | 0xF8000000)
83
84/**
85 * Structure keeping the context of a host callback.
86 */
87typedef struct VBOXGUESTCTRLHOSTCBCTX
88{
89 /** HGCM message number. */
90 uint32_t uMessage;
91 /** The context ID. */
92 uint32_t uContextID;
93 /** Protocol version of this guest session. Might
94 * be 0 if not supported. */
95 uint32_t uProtocol;
96} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
97
98/**
99 * Structure for low level HGCM host callback from
100 * the guest. No deep copy. */
101typedef struct VBOXGUESTCTRLHOSTCALLBACK
102{
103 /** Number of HGCM parameters. */
104 uint32_t mParms;
105 /** Actual HGCM parameters. */
106 PVBOXHGCMSVCPARM mpaParms;
107} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
108
109/** @name Host message destination flags.
110 *
111 * This is ORed into the context ID parameter Main after extending it to 64-bit.
112 *
113 * @internal Host internal.
114 * @{ */
115#define VBOX_GUESTCTRL_DST_ROOT_SVC RT_BIT_64(63)
116#define VBOX_GUESTCTRL_DST_SESSION RT_BIT_64(62)
117#define VBOX_GUESTCTRL_DST_BOTH ( VBOX_GUESTCTRL_DST_ROOT_SVC | VBOX_GUESTCTRL_DST_SESSION )
118/** @} */
119
120
121/**
122 * The service messages which are callable by host.
123 */
124enum eHostMsg
125{
126 /**
127 * The host asks the client to cancel all pending waits and exit.
128 */
129 HOST_MSG_CANCEL_PENDING_WAITS = 0,
130 /**
131 * The host wants to create a guest session.
132 */
133 HOST_MSG_SESSION_CREATE = 20,
134 /**
135 * The host wants to close a guest session.
136 */
137 HOST_MSG_SESSION_CLOSE = 21,
138 /**
139 * The host wants to execute something in the guest. This can be a command
140 * line or starting a program.
141 * @note Legacy (VBox < 4.3) message.
142 */
143 HOST_MSG_EXEC_CMD = 100,
144 /**
145 * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
146 * @note Legacy (VBox < 4.3) message.
147 */
148 HOST_MSG_EXEC_SET_INPUT = 101,
149 /**
150 * Gets the current status of a running process, e.g.
151 * new data on stdout/stderr, process terminated etc.
152 * @note Legacy (VBox < 4.3) message.
153 */
154 HOST_MSG_EXEC_GET_OUTPUT = 102,
155 /**
156 * Terminates a running guest process.
157 */
158 HOST_MSG_EXEC_TERMINATE = 110,
159 /**
160 * Waits for a certain event to happen. This can be an input, output
161 * or status event.
162 */
163 HOST_MSG_EXEC_WAIT_FOR = 120,
164 /**
165 * Opens a guest file.
166 */
167 HOST_MSG_FILE_OPEN = 240,
168 /**
169 * Closes a guest file.
170 */
171 HOST_MSG_FILE_CLOSE,
172 /**
173 * Reads from an opened guest file.
174 */
175 HOST_MSG_FILE_READ = 250,
176 /**
177 * Reads from an opened guest file at a specified offset.
178 */
179 HOST_MSG_FILE_READ_AT,
180 /**
181 * Write to an opened guest file.
182 */
183 HOST_MSG_FILE_WRITE = 260,
184 /**
185 * Write to an opened guest file at a specified offset.
186 */
187 HOST_MSG_FILE_WRITE_AT,
188 /**
189 * Changes the read & write position of an opened guest file.
190 */
191 HOST_MSG_FILE_SEEK = 270,
192 /**
193 * Gets the current file position of an opened guest file.
194 */
195 HOST_MSG_FILE_TELL,
196 /**
197 * Removes a directory on the guest.
198 */
199 HOST_MSG_DIR_REMOVE = 320,
200 /**
201 * Renames a path on the guest.
202 */
203 HOST_MSG_PATH_RENAME = 330,
204 /**
205 * Retrieves the user's documents directory.
206 */
207 HOST_MSG_PATH_USER_DOCUMENTS,
208 /**
209 * Retrieves the user's home directory.
210 */
211 HOST_MSG_PATH_USER_HOME,
212
213 /** Blow the type up to 32-bits. */
214 HOST_MSG_32BIT_HACK = 0x7fffffff
215};
216
217
218/**
219 * Translates a guest control host message enum to a string.
220 *
221 * @returns Enum string name.
222 * @param enmMsg The message to translate.
223 */
224DECLINLINE(const char *) GstCtrlHostMsgtoStr(enum eHostMsg enmMsg)
225{
226 switch (enmMsg)
227 {
228 RT_CASE_RET_STR(HOST_MSG_CANCEL_PENDING_WAITS);
229 RT_CASE_RET_STR(HOST_MSG_SESSION_CREATE);
230 RT_CASE_RET_STR(HOST_MSG_SESSION_CLOSE);
231 RT_CASE_RET_STR(HOST_MSG_EXEC_CMD);
232 RT_CASE_RET_STR(HOST_MSG_EXEC_SET_INPUT);
233 RT_CASE_RET_STR(HOST_MSG_EXEC_GET_OUTPUT);
234 RT_CASE_RET_STR(HOST_MSG_EXEC_TERMINATE);
235 RT_CASE_RET_STR(HOST_MSG_EXEC_WAIT_FOR);
236 RT_CASE_RET_STR(HOST_MSG_FILE_OPEN);
237 RT_CASE_RET_STR(HOST_MSG_FILE_CLOSE);
238 RT_CASE_RET_STR(HOST_MSG_FILE_READ);
239 RT_CASE_RET_STR(HOST_MSG_FILE_READ_AT);
240 RT_CASE_RET_STR(HOST_MSG_FILE_WRITE);
241 RT_CASE_RET_STR(HOST_MSG_FILE_WRITE_AT);
242 RT_CASE_RET_STR(HOST_MSG_FILE_SEEK);
243 RT_CASE_RET_STR(HOST_MSG_FILE_TELL);
244 RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE);
245 RT_CASE_RET_STR(HOST_MSG_PATH_RENAME);
246 RT_CASE_RET_STR(HOST_MSG_PATH_USER_DOCUMENTS);
247 RT_CASE_RET_STR(HOST_MSG_PATH_USER_HOME);
248 RT_CASE_RET_STR(HOST_MSG_32BIT_HACK);
249 }
250 return "Unknown";
251}
252
253
254/**
255 * The service messages which are callable by the guest.
256 *
257 * @note The message numbers cannot be changed. Please use the first non-zero
258 * number that's not in use when adding new messages.
259 *
260 * @note Remember to update service.cpp when adding new messages for Main,
261 * as it validates all incoming messages before passing them on.
262 */
263enum eGuestMsg
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 message 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 message number, host will reject it.
303 */
304 GUEST_MSG_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 message, defaults to
391 * VERR_NOT_SUPPORTED. The second parameter is the 32-bit message ID of the
392 * message 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 messages 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_MSG_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_MSG_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_MSG_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_MSG_SESSION_ACCEPT = 16,
490 /**
491 * Guest reports back a guest session status.
492 * @todo proper docs.
493 */
494 GUEST_MSG_SESSION_NOTIFY = 20,
495 /**
496 * Guest wants to close a specific guest session.
497 * @todo proper docs.
498 */
499 GUEST_MSG_SESSION_CLOSE = 21,
500
501 /**
502 * Guests sends output from an executed process.
503 * @todo proper docs.
504 */
505 GUEST_MSG_EXEC_OUTPUT = 100,
506 /**
507 * Guest sends a status update of an executed process to the host.
508 * @todo proper docs.
509 */
510 GUEST_MSG_EXEC_STATUS = 101,
511 /**
512 * Guests sends an input status notification to the host.
513 * @todo proper docs.
514 */
515 GUEST_MSG_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_MSG_EXEC_IO_NOTIFY = 210,
524 /**
525 * Guest notifies the host about some directory event.
526 * @todo proper docs.
527 */
528 GUEST_MSG_DIR_NOTIFY = 230,
529 /**
530 * Guest notifies the host about some file event.
531 * @todo proper docs.
532 */
533 GUEST_MSG_FILE_NOTIFY = 240
534};
535
536/**
537 * Translates a guest control guest message enum to a string.
538 *
539 * @returns Enum string name.
540 * @param enmMsg The message to translate.
541 */
542DECLINLINE(const char *) GstCtrlGuestMsgToStr(enum eGuestMsg enmMsg)
543{
544 switch (enmMsg)
545 {
546 RT_CASE_RET_STR(GUEST_MSG_WAIT);
547 RT_CASE_RET_STR(GUEST_MSG_CANCEL);
548 RT_CASE_RET_STR(GUEST_MSG_DISCONNECTED);
549 RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
550 RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
551 RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT);
552 RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT);
553 RT_CASE_RET_STR(GUEST_MSG_GET);
554 RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD);
555 RT_CASE_RET_STR(GUEST_MSG_REPLY);
556 RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
557 RT_CASE_RET_STR(GUEST_MSG_SKIP);
558 RT_CASE_RET_STR(GUEST_MSG_MAKE_ME_MASTER);
559 RT_CASE_RET_STR(GUEST_MSG_SESSION_PREPARE);
560 RT_CASE_RET_STR(GUEST_MSG_SESSION_CANCEL_PREPARED);
561 RT_CASE_RET_STR(GUEST_MSG_SESSION_ACCEPT);
562 RT_CASE_RET_STR(GUEST_MSG_SESSION_NOTIFY);
563 RT_CASE_RET_STR(GUEST_MSG_SESSION_CLOSE);
564 RT_CASE_RET_STR(GUEST_MSG_EXEC_OUTPUT);
565 RT_CASE_RET_STR(GUEST_MSG_EXEC_STATUS);
566 RT_CASE_RET_STR(GUEST_MSG_EXEC_INPUT_STATUS);
567 RT_CASE_RET_STR(GUEST_MSG_EXEC_IO_NOTIFY);
568 RT_CASE_RET_STR(GUEST_MSG_DIR_NOTIFY);
569 RT_CASE_RET_STR(GUEST_MSG_FILE_NOTIFY);
570 }
571 return "Unknown";
572}
573
574
575/**
576 * Guest session notification types.
577 * @sa HGCMMsgSessionNotify.
578 */
579enum GUEST_SESSION_NOTIFYTYPE
580{
581 GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
582 /** Something went wrong (see rc). */
583 GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
584 /** Guest session has been started. */
585 GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
586 /** Guest session terminated normally. */
587 GUEST_SESSION_NOTIFYTYPE_TEN = 20,
588 /** Guest session terminated via signal. */
589 GUEST_SESSION_NOTIFYTYPE_TES = 30,
590 /** Guest session terminated abnormally. */
591 GUEST_SESSION_NOTIFYTYPE_TEA = 40,
592 /** Guest session timed out and was killed. */
593 GUEST_SESSION_NOTIFYTYPE_TOK = 50,
594 /** Guest session timed out and was not killed successfully. */
595 GUEST_SESSION_NOTIFYTYPE_TOA = 60,
596 /** Service/OS is stopping, process was killed. */
597 GUEST_SESSION_NOTIFYTYPE_DWN = 150
598};
599
600/**
601 * Guest directory notification types.
602 * @sa HGCMMsgDirNotify.
603 */
604enum GUEST_DIR_NOTIFYTYPE
605{
606 GUEST_DIR_NOTIFYTYPE_UNKNOWN = 0,
607 /** Something went wrong (see rc). */
608 GUEST_DIR_NOTIFYTYPE_ERROR = 1,
609 /** Guest directory opened. */
610 GUEST_DIR_NOTIFYTYPE_OPEN = 10,
611 /** Guest directory closed. */
612 GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
613 /** Information about an open guest directory. */
614 GUEST_DIR_NOTIFYTYPE_INFO = 40,
615 /** Guest directory created. */
616 GUEST_DIR_NOTIFYTYPE_CREATE = 70,
617 /** Guest directory deleted. */
618 GUEST_DIR_NOTIFYTYPE_REMOVE = 80
619};
620
621/**
622 * Guest file notification types.
623 * @sa HGCMMsgFileNotify.
624 */
625enum GUEST_FILE_NOTIFYTYPE
626{
627 GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
628 GUEST_FILE_NOTIFYTYPE_ERROR = 1,
629 GUEST_FILE_NOTIFYTYPE_OPEN = 10,
630 GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
631 GUEST_FILE_NOTIFYTYPE_READ = 30,
632 GUEST_FILE_NOTIFYTYPE_WRITE = 40,
633 GUEST_FILE_NOTIFYTYPE_SEEK = 50,
634 GUEST_FILE_NOTIFYTYPE_TELL = 60
635};
636
637/**
638 * Guest file seeking types. Has to match FileSeekType in Main.
639 *
640 * @note This is not compatible with RTFileSeek, which is an unncessary pain.
641 */
642enum GUEST_FILE_SEEKTYPE
643{
644 GUEST_FILE_SEEKTYPE_BEGIN = 1,
645 GUEST_FILE_SEEKTYPE_CURRENT = 4,
646 GUEST_FILE_SEEKTYPE_END = 8
647};
648
649/*
650 * HGCM parameter structures.
651 */
652#pragma pack (1)
653
654/**
655 * Waits for a host message to arrive. The structure then contains the
656 * actual message type + required number of parameters needed to successfully
657 * retrieve that host message (in a next round).
658 */
659typedef struct HGCMMsgWaitFor
660{
661 VBGLIOCHGCMCALL hdr;
662 /** The returned message the host wants to run on the guest. */
663 HGCMFunctionParameter msg; /* OUT uint32_t */
664 /** Number of parameters the message needs. */
665 HGCMFunctionParameter num_parms; /* OUT uint32_t */
666} HGCMMsgWaitFor;
667
668/**
669 * Asks the guest control host service to set a message
670 * filter for this client. This filter will then only
671 * deliver messages to the client which match the
672 * wanted context ID (ranges).
673 */
674typedef struct HGCMMsgFilterSet
675{
676 VBGLIOCHGCMCALL hdr;
677 /** Value to filter for after filter mask was applied. */
678 HGCMFunctionParameter value; /* IN uint32_t */
679 /** Mask to add to the current set filter. */
680 HGCMFunctionParameter mask_add; /* IN uint32_t */
681 /** Mask to remove from the current set filter. */
682 HGCMFunctionParameter mask_remove; /* IN uint32_t */
683 /** Filter flags; currently unused. */
684 HGCMFunctionParameter flags; /* IN uint32_t */
685} HGCMMsgFilterSet;
686
687/**
688 * Asks the guest control host service to disable
689 * a previously set message filter again.
690 */
691typedef struct HGCMMsgFilterUnset
692{
693 VBGLIOCHGCMCALL hdr;
694 /** Unset flags; currently unused. */
695 HGCMFunctionParameter flags; /* IN uint32_t */
696} HGCMMsgFilterUnset;
697
698/**
699 * Asks the guest control host service to skip the
700 * currently assigned host message returned by
701 * VbglR3GuestCtrlMsgWaitFor().
702 */
703typedef struct HGCMMsgSkip
704{
705 VBGLIOCHGCMCALL hdr;
706 /** Skip flags; currently unused. */
707 HGCMFunctionParameter flags; /* IN uint32_t */
708} HGCMMsgSkip;
709
710/**
711 * Asks the guest control host service to cancel all pending (outstanding)
712 * waits which were not processed yet. This is handy for a graceful shutdown.
713 */
714typedef struct HGCMMsgCancelPendingWaits
715{
716 VBGLIOCHGCMCALL hdr;
717} HGCMMsgCancelPendingWaits;
718
719typedef struct HGCMMsgReply
720{
721 VBGLIOCHGCMCALL hdr;
722 /** Context ID. */
723 HGCMFunctionParameter context;
724 /** Message type. */
725 HGCMFunctionParameter type;
726 /** IPRT result of overall operation. */
727 HGCMFunctionParameter rc;
728 /** Optional payload to this reply. */
729 HGCMFunctionParameter payload;
730} HGCMMsgReply;
731
732/**
733 * Creates a guest session.
734 */
735typedef struct HGCMMsgSessionOpen
736{
737 VBGLIOCHGCMCALL hdr;
738 /** Context ID. */
739 HGCMFunctionParameter context;
740 /** The guest control protocol version this
741 * session is about to use. */
742 HGCMFunctionParameter protocol;
743 /** The user name to run the guest session under. */
744 HGCMFunctionParameter username;
745 /** The user's password. */
746 HGCMFunctionParameter password;
747 /** The domain to run the guest session under. */
748 HGCMFunctionParameter domain;
749 /** Session creation flags. */
750 HGCMFunctionParameter flags;
751} HGCMMsgSessionOpen;
752
753/**
754 * Terminates (closes) a guest session.
755 */
756typedef struct HGCMMsgSessionClose
757{
758 VBGLIOCHGCMCALL hdr;
759 /** Context ID. */
760 HGCMFunctionParameter context;
761 /** Session termination flags. */
762 HGCMFunctionParameter flags;
763} HGCMMsgSessionClose;
764
765/**
766 * Reports back a guest session's status.
767 */
768typedef struct HGCMMsgSessionNotify
769{
770 VBGLIOCHGCMCALL hdr;
771 /** Context ID. */
772 HGCMFunctionParameter context;
773 /** Notification type. */
774 HGCMFunctionParameter type;
775 /** Notification result. */
776 HGCMFunctionParameter result;
777} HGCMMsgSessionNotify;
778
779typedef struct HGCMMsgPathRename
780{
781 VBGLIOCHGCMCALL hdr;
782 /** UInt32: Context ID. */
783 HGCMFunctionParameter context;
784 /** Source to rename. */
785 HGCMFunctionParameter source;
786 /** Destination to rename source to. */
787 HGCMFunctionParameter dest;
788 /** UInt32: Rename flags. */
789 HGCMFunctionParameter flags;
790} HGCMMsgPathRename;
791
792typedef struct HGCMMsgPathUserDocuments
793{
794 VBGLIOCHGCMCALL hdr;
795 /** UInt32: Context ID. */
796 HGCMFunctionParameter context;
797} HGCMMsgPathUserDocuments;
798
799typedef struct HGCMMsgPathUserHome
800{
801 VBGLIOCHGCMCALL hdr;
802 /** UInt32: Context ID. */
803 HGCMFunctionParameter context;
804} HGCMMsgPathUserHome;
805
806/**
807 * Executes a command inside the guest.
808 */
809typedef struct HGCMMsgProcExec
810{
811 VBGLIOCHGCMCALL hdr;
812 /** Context ID. */
813 HGCMFunctionParameter context;
814 /** The command to execute on the guest. */
815 HGCMFunctionParameter cmd;
816 /** Execution flags (see IGuest::ProcessCreateFlag_*). */
817 HGCMFunctionParameter flags;
818 /** Number of arguments. */
819 HGCMFunctionParameter num_args;
820 /** The actual arguments. */
821 HGCMFunctionParameter args;
822 /** Number of environment value pairs. */
823 HGCMFunctionParameter num_env;
824 /** Size (in bytes) of environment block, including terminating zeros. */
825 HGCMFunctionParameter cb_env;
826 /** The actual environment block. */
827 HGCMFunctionParameter env;
828 union
829 {
830 struct
831 {
832 /** The user name to run the executed command under.
833 * Only for VBox < 4.3 hosts. */
834 HGCMFunctionParameter username;
835 /** The user's password.
836 * Only for VBox < 4.3 hosts. */
837 HGCMFunctionParameter password;
838 /** Timeout (in msec) which either specifies the
839 * overall lifetime of the process or how long it
840 * can take to bring the process up and running -
841 * (depends on the IGuest::ProcessCreateFlag_*). */
842 HGCMFunctionParameter timeout;
843 } v1;
844 struct
845 {
846 /** Timeout (in ms) which either specifies the
847 * overall lifetime of the process or how long it
848 * can take to bring the process up and running -
849 * (depends on the IGuest::ProcessCreateFlag_*). */
850 HGCMFunctionParameter timeout;
851 /** Process priority. */
852 HGCMFunctionParameter priority;
853 /** Number of process affinity blocks. */
854 HGCMFunctionParameter num_affinity;
855 /** Pointer to process affinity blocks (uint64_t). */
856 HGCMFunctionParameter affinity;
857 } v2;
858 } u;
859} HGCMMsgProcExec;
860
861/**
862 * Sends input to a guest process via stdin.
863 */
864typedef struct HGCMMsgProcInput
865{
866 VBGLIOCHGCMCALL hdr;
867 /** Context ID. */
868 HGCMFunctionParameter context;
869 /** The process ID (PID) to send the input to. */
870 HGCMFunctionParameter pid;
871 /** Input flags (see IGuest::ProcessInputFlag_*). */
872 HGCMFunctionParameter flags;
873 /** Data buffer. */
874 HGCMFunctionParameter data;
875 /** Actual size of data (in bytes). */
876 HGCMFunctionParameter size;
877} HGCMMsgProcInput;
878
879/**
880 * Retrieves ouptut from a previously executed process
881 * from stdout/stderr.
882 */
883typedef struct HGCMMsgProcOutput
884{
885 VBGLIOCHGCMCALL hdr;
886 /** Context ID. */
887 HGCMFunctionParameter context;
888 /** The process ID (PID). */
889 HGCMFunctionParameter pid;
890 /** The pipe handle ID (stdout/stderr). */
891 HGCMFunctionParameter handle;
892 /** Optional flags. */
893 HGCMFunctionParameter flags;
894 /** Data buffer. */
895 HGCMFunctionParameter data;
896} HGCMMsgProcOutput;
897
898/**
899 * Reports the current status of a guest process.
900 */
901typedef struct HGCMMsgProcStatus
902{
903 VBGLIOCHGCMCALL hdr;
904 /** Context ID. */
905 HGCMFunctionParameter context;
906 /** The process ID (PID). */
907 HGCMFunctionParameter pid;
908 /** The process status. */
909 HGCMFunctionParameter status;
910 /** Optional flags (based on status). */
911 HGCMFunctionParameter flags;
912 /** Optional data buffer (not used atm). */
913 HGCMFunctionParameter data;
914} HGCMMsgProcStatus;
915
916/**
917 * Reports back the status of data written to a process.
918 */
919typedef struct HGCMMsgProcStatusInput
920{
921 VBGLIOCHGCMCALL hdr;
922 /** Context ID. */
923 HGCMFunctionParameter context;
924 /** The process ID (PID). */
925 HGCMFunctionParameter pid;
926 /** Status of the operation. */
927 HGCMFunctionParameter status;
928 /** Optional flags. */
929 HGCMFunctionParameter flags;
930 /** Data written. */
931 HGCMFunctionParameter written;
932} HGCMMsgProcStatusInput;
933
934/*
935 * Guest control 2.0 messages.
936 */
937
938/**
939 * Terminates a guest process.
940 */
941typedef struct HGCMMsgProcTerminate
942{
943 VBGLIOCHGCMCALL hdr;
944 /** Context ID. */
945 HGCMFunctionParameter context;
946 /** The process ID (PID). */
947 HGCMFunctionParameter pid;
948} HGCMMsgProcTerminate;
949
950/**
951 * Waits for certain events to happen.
952 */
953typedef struct HGCMMsgProcWaitFor
954{
955 VBGLIOCHGCMCALL hdr;
956 /** Context ID. */
957 HGCMFunctionParameter context;
958 /** The process ID (PID). */
959 HGCMFunctionParameter pid;
960 /** Wait (event) flags. */
961 HGCMFunctionParameter flags;
962 /** Timeout (in ms). */
963 HGCMFunctionParameter timeout;
964} HGCMMsgProcWaitFor;
965
966typedef struct HGCMMsgDirRemove
967{
968 VBGLIOCHGCMCALL hdr;
969 /** UInt32: Context ID. */
970 HGCMFunctionParameter context;
971 /** Directory to remove. */
972 HGCMFunctionParameter path;
973 /** UInt32: Removement flags. */
974 HGCMFunctionParameter flags;
975} HGCMMsgDirRemove;
976
977/**
978 * Opens a guest file.
979 */
980typedef struct HGCMMsgFileOpen
981{
982 VBGLIOCHGCMCALL hdr;
983 /** UInt32: Context ID. */
984 HGCMFunctionParameter context;
985 /** File to open. */
986 HGCMFunctionParameter filename;
987 /** Open mode. */
988 HGCMFunctionParameter openmode;
989 /** Disposition mode. */
990 HGCMFunctionParameter disposition;
991 /** Sharing mode. */
992 HGCMFunctionParameter sharing;
993 /** UInt32: Creation mode. */
994 HGCMFunctionParameter creationmode;
995 /** UInt64: Initial offset. */
996 HGCMFunctionParameter offset;
997} HGCMMsgFileOpen;
998
999/**
1000 * Closes a guest file.
1001 */
1002typedef struct HGCMMsgFileClose
1003{
1004 VBGLIOCHGCMCALL hdr;
1005 /** Context ID. */
1006 HGCMFunctionParameter context;
1007 /** File handle to close. */
1008 HGCMFunctionParameter handle;
1009} HGCMMsgFileClose;
1010
1011/**
1012 * Reads from a guest file.
1013 */
1014typedef struct HGCMMsgFileRead
1015{
1016 VBGLIOCHGCMCALL hdr;
1017 /** Context ID. */
1018 HGCMFunctionParameter context;
1019 /** File handle to read from. */
1020 HGCMFunctionParameter handle;
1021 /** Size (in bytes) to read. */
1022 HGCMFunctionParameter size;
1023} HGCMMsgFileRead;
1024
1025/**
1026 * Reads at a specified offset from a guest file.
1027 */
1028typedef struct HGCMMsgFileReadAt
1029{
1030 VBGLIOCHGCMCALL hdr;
1031 /** Context ID. */
1032 HGCMFunctionParameter context;
1033 /** File handle to read from. */
1034 HGCMFunctionParameter handle;
1035 /** Offset where to start reading from. */
1036 HGCMFunctionParameter offset;
1037 /** Actual size of data (in bytes). */
1038 HGCMFunctionParameter size;
1039} HGCMMsgFileReadAt;
1040
1041/**
1042 * Writes to a guest file.
1043 */
1044typedef struct HGCMMsgFileWrite
1045{
1046 VBGLIOCHGCMCALL hdr;
1047 /** Context ID. */
1048 HGCMFunctionParameter context;
1049 /** File handle to write to. */
1050 HGCMFunctionParameter handle;
1051 /** Actual size of data (in bytes). */
1052 HGCMFunctionParameter size;
1053 /** Data buffer to write to the file. */
1054 HGCMFunctionParameter data;
1055} HGCMMsgFileWrite;
1056
1057/**
1058 * Writes at a specified offset to a guest file.
1059 */
1060typedef struct HGCMMsgFileWriteAt
1061{
1062 VBGLIOCHGCMCALL hdr;
1063 /** Context ID. */
1064 HGCMFunctionParameter context;
1065 /** File handle to write to. */
1066 HGCMFunctionParameter handle;
1067 /** Offset where to start reading from. */
1068 HGCMFunctionParameter offset;
1069 /** Actual size of data (in bytes). */
1070 HGCMFunctionParameter size;
1071 /** Data buffer to write to the file. */
1072 HGCMFunctionParameter data;
1073} HGCMMsgFileWriteAt;
1074
1075/**
1076 * Seeks the read/write position of a guest file.
1077 */
1078typedef struct HGCMMsgFileSeek
1079{
1080 VBGLIOCHGCMCALL hdr;
1081 /** Context ID. */
1082 HGCMFunctionParameter context;
1083 /** File handle to seek. */
1084 HGCMFunctionParameter handle;
1085 /** The seeking method. */
1086 HGCMFunctionParameter method;
1087 /** The seeking offset. */
1088 HGCMFunctionParameter offset;
1089} HGCMMsgFileSeek;
1090
1091/**
1092 * Tells the current read/write position of a guest file.
1093 */
1094typedef struct HGCMMsgFileTell
1095{
1096 VBGLIOCHGCMCALL hdr;
1097 /** Context ID. */
1098 HGCMFunctionParameter context;
1099 /** File handle to get the current position for. */
1100 HGCMFunctionParameter handle;
1101} HGCMMsgFileTell;
1102
1103/******************************************************************************
1104* HGCM replies from the guest. These are handled in Main's low-level HGCM *
1105* callbacks and dispatched to the appropriate guest object. *
1106******************************************************************************/
1107
1108typedef struct HGCMReplyFileNotify
1109{
1110 VBGLIOCHGCMCALL hdr;
1111 /** Context ID. */
1112 HGCMFunctionParameter context;
1113 /** Notification type. */
1114 HGCMFunctionParameter type;
1115 /** IPRT result of overall operation. */
1116 HGCMFunctionParameter rc;
1117 union
1118 {
1119 struct
1120 {
1121 /** Guest file handle. */
1122 HGCMFunctionParameter handle;
1123 } open;
1124 /** Note: Close does not have any additional data (yet). */
1125 struct
1126 {
1127 /** Actual data read (if any). */
1128 HGCMFunctionParameter data;
1129 } read;
1130 struct
1131 {
1132 /** How much data (in bytes) have been successfully written. */
1133 HGCMFunctionParameter written;
1134 } write;
1135 struct
1136 {
1137 HGCMFunctionParameter offset;
1138 } seek;
1139 struct
1140 {
1141 HGCMFunctionParameter offset;
1142 } tell;
1143 } u;
1144} HGCMReplyFileNotify;
1145
1146typedef struct HGCMReplyDirNotify
1147{
1148 VBGLIOCHGCMCALL hdr;
1149 /** Context ID. */
1150 HGCMFunctionParameter context;
1151 /** Notification type. */
1152 HGCMFunctionParameter type;
1153 /** IPRT result of overall operation. */
1154 HGCMFunctionParameter rc;
1155 union
1156 {
1157 struct
1158 {
1159 /** Directory information. */
1160 HGCMFunctionParameter objInfo;
1161 } info;
1162 struct
1163 {
1164 /** Guest directory handle. */
1165 HGCMFunctionParameter handle;
1166 } open;
1167 struct
1168 {
1169 /** Current read directory entry. */
1170 HGCMFunctionParameter entry;
1171 /** Extended entry object information. Optional. */
1172 HGCMFunctionParameter objInfo;
1173 } read;
1174 } u;
1175} HGCMReplyDirNotify;
1176
1177#pragma pack ()
1178
1179/******************************************************************************
1180* Callback data structures. *
1181******************************************************************************/
1182
1183/**
1184 * The guest control callback data header. Must come first
1185 * on each callback structure defined below this struct.
1186 */
1187typedef struct CALLBACKDATA_HEADER
1188{
1189 /** Context ID to identify callback data. This is
1190 * and *must* be the very first parameter in this
1191 * structure to still be backwards compatible. */
1192 uint32_t uContextID;
1193} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
1194
1195/*
1196 * These structures make up the actual low level HGCM callback data sent from
1197 * the guest back to the host.
1198 */
1199
1200typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
1201{
1202 /** Callback data header. */
1203 CALLBACKDATA_HEADER hdr;
1204} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
1205
1206typedef struct CALLBACKDATA_MSG_REPLY
1207{
1208 /** Callback data header. */
1209 CALLBACKDATA_HEADER hdr;
1210 /** Notification type. */
1211 uint32_t uType;
1212 /** Notification result. Note: int vs. uint32! */
1213 uint32_t rc;
1214 /** Pointer to optional payload. */
1215 void *pvPayload;
1216 /** Payload size (in bytes). */
1217 uint32_t cbPayload;
1218} CALLBACKDATA_MSG_REPLY, *PCALLBACKDATA_MSG_REPLY;
1219
1220typedef struct CALLBACKDATA_SESSION_NOTIFY
1221{
1222 /** Callback data header. */
1223 CALLBACKDATA_HEADER hdr;
1224 /** Notification type. */
1225 uint32_t uType;
1226 /** Notification result. Note: int vs. uint32! */
1227 uint32_t uResult;
1228} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
1229
1230typedef struct CALLBACKDATA_PROC_STATUS
1231{
1232 /** Callback data header. */
1233 CALLBACKDATA_HEADER hdr;
1234 /** The process ID (PID). */
1235 uint32_t uPID;
1236 /** The process status. */
1237 uint32_t uStatus;
1238 /** Optional flags, varies, based on u32Status. */
1239 uint32_t uFlags;
1240 /** Optional data buffer (not used atm). */
1241 void *pvData;
1242 /** Size of optional data buffer (not used atm). */
1243 uint32_t cbData;
1244} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
1245
1246typedef struct CALLBACKDATA_PROC_OUTPUT
1247{
1248 /** Callback data header. */
1249 CALLBACKDATA_HEADER hdr;
1250 /** The process ID (PID). */
1251 uint32_t uPID;
1252 /** The handle ID (stdout/stderr). */
1253 uint32_t uHandle;
1254 /** Optional flags (not used atm). */
1255 uint32_t uFlags;
1256 /** Optional data buffer. */
1257 void *pvData;
1258 /** Size (in bytes) of optional data buffer. */
1259 uint32_t cbData;
1260} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
1261
1262typedef struct CALLBACKDATA_PROC_INPUT
1263{
1264 /** Callback data header. */
1265 CALLBACKDATA_HEADER hdr;
1266 /** The process ID (PID). */
1267 uint32_t uPID;
1268 /** Current input status. */
1269 uint32_t uStatus;
1270 /** Optional flags. */
1271 uint32_t uFlags;
1272 /** Size (in bytes) of processed input data. */
1273 uint32_t uProcessed;
1274} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
1275
1276/**
1277 * General guest directory notification callback.
1278 */
1279typedef struct CALLBACKDATA_DIR_NOTIFY
1280{
1281 /** Callback data header. */
1282 CALLBACKDATA_HEADER hdr;
1283 /** Notification type. */
1284 uint32_t uType;
1285 /** IPRT result of overall operation. */
1286 uint32_t rc;
1287 union
1288 {
1289 struct
1290 {
1291 /** Size (in bytes) of directory information. */
1292 uint32_t cbObjInfo;
1293 /** Pointer to directory information. */
1294 void *pvObjInfo;
1295 } info;
1296 struct
1297 {
1298 /** Guest directory handle. */
1299 uint32_t uHandle;
1300 } open;
1301 /** Note: Close does not have any additional data (yet). */
1302 struct
1303 {
1304 /** Size (in bytes) of directory entry information. */
1305 uint32_t cbEntry;
1306 /** Pointer to directory entry information. */
1307 void *pvEntry;
1308 /** Size (in bytes) of directory entry object information. */
1309 uint32_t cbObjInfo;
1310 /** Pointer to directory entry object information. */
1311 void *pvObjInfo;
1312 } read;
1313 } u;
1314} CALLBACKDATA_DIR_NOTIFY, *PCALLBACKDATA_DIR_NOTIFY;
1315
1316/**
1317 * General guest file notification callback.
1318 */
1319typedef struct CALLBACKDATA_FILE_NOTIFY
1320{
1321 /** Callback data header. */
1322 CALLBACKDATA_HEADER hdr;
1323 /** Notification type. */
1324 uint32_t uType;
1325 /** IPRT result of overall operation. */
1326 uint32_t rc;
1327 union
1328 {
1329 struct
1330 {
1331 /** Guest file handle. */
1332 uint32_t uHandle;
1333 } open;
1334 /** Note: Close does not have any additional data (yet). */
1335 struct
1336 {
1337 /** How much data (in bytes) have been read. */
1338 uint32_t cbData;
1339 /** Actual data read (if any). */
1340 void *pvData;
1341 } read;
1342 struct
1343 {
1344 /** How much data (in bytes) have been successfully written. */
1345 uint32_t cbWritten;
1346 } write;
1347 struct
1348 {
1349 /** New file offset after successful seek. */
1350 uint64_t uOffActual;
1351 } seek;
1352 struct
1353 {
1354 /** New file offset after successful tell. */
1355 uint64_t uOffActual;
1356 } tell;
1357 } u;
1358} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
1359
1360} /* namespace guestControl */
1361
1362#endif /* !VBOX_INCLUDED_HostServices_GuestControlSvc_h */
1363
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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