VirtualBox

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

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

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

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