VirtualBox

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

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

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