VirtualBox

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

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

Forgot some files, build fix.

  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 28.5 KB
 
1/** @file
2 * Guest control service - Common header for host service and guest clients.
3 */
4
5/*
6 * Copyright (C) 2011-2013 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.alldomusa.eu.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___VBox_HostService_GuestControlService_h
27#define ___VBox_HostService_GuestControlService_h
28
29#include <VBox/types.h>
30#include <VBox/VMMDev.h>
31#include <VBox/VBoxGuest2.h>
32#include <VBox/hgcmsvc.h>
33#include <VBox/log.h>
34#include <iprt/assert.h>
35#include <iprt/string.h>
36
37/* Everything defined in this file lives in this namespace. */
38namespace guestControl {
39
40/******************************************************************************
41* Typedefs, constants and inlines *
42******************************************************************************/
43
44#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
45
46/** Maximum number of concurrent guest sessions a VM can have. */
47#define VBOX_GUESTCTRL_MAX_SESSIONS 32
48/** Maximum number of concurrent guest objects (processes, files, ...)
49 * a guest session can have. */
50#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
51/** Maximum of callback contexts a guest process can have. */
52#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
53
54/** Base (start) of guest control session IDs. Session
55 * ID 0 is reserved for the root process which
56 * hosts all other guest session processes. */
57#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
58
59/** Builds a context ID out of the session ID, object ID and an
60 * increasing count. */
61#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
62 ( (uint32_t)((uSession) & 0x1f) << 27 \
63 | (uint32_t)((uObject) & 0x7ff) << 16 \
64 | (uint32_t)((uCount) & 0xffff) \
65 )
66/** Creates a context ID out of a session ID. */
67#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
68 ((uint32_t)((uSession) & 0x1f) << 27)
69/** Gets the session ID out of a context ID. */
70#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
71 (((uContextID) >> 27) & 0x1f)
72/** Gets the process ID out of a context ID. */
73#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
74 (((uContextID) >> 16) & 0x7ff)
75/** Gets the context count of a process out of a context ID. */
76#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
77 ((uContextID) & 0xffff)
78/** Filter context IDs by session. Can be used in conjunction
79 * with VbglR3GuestCtrlMsgFilterSet(). */
80#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
81 (VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) | 0xF8000000)
82
83/**
84 * Process status when executed in the guest.
85 */
86enum eProcessStatus
87{
88 /** Process is in an undefined state. */
89 PROC_STS_UNDEFINED = 0,
90 /** Process has been started. */
91 PROC_STS_STARTED = 1,
92 /** Process terminated normally. */
93 PROC_STS_TEN = 2,
94 /** Process terminated via signal. */
95 PROC_STS_TES = 3,
96 /** Process terminated abnormally. */
97 PROC_STS_TEA = 4,
98 /** Process timed out and was killed. */
99 PROC_STS_TOK = 5,
100 /** Process timed out and was not killed successfully. */
101 PROC_STS_TOA = 6,
102 /** Service/OS is stopping, process was killed. */
103 PROC_STS_DWN = 7,
104 /** Something went wrong (error code in flags). */
105 PROC_STS_ERROR = 8
106};
107
108/**
109 * Input flags, set by the host. This is needed for
110 * handling flags on the guest side.
111 * Note: Has to match Main's ProcessInputFlag_* flags!
112 */
113#define INPUT_FLAG_NONE 0x0
114#define INPUT_FLAG_EOF RT_BIT(0)
115
116/**
117 * Guest session creation flags.
118 * Only handled internally at the moment.
119 */
120#define SESSIONCREATIONFLAG_NONE 0x0
121
122/**
123 * Guest process creation flags.
124 * Note: Has to match Main's ProcessCreateFlag_* flags!
125 */
126#define EXECUTEPROCESSFLAG_NONE 0x0
127#define EXECUTEPROCESSFLAG_WAIT_START RT_BIT(0)
128#define EXECUTEPROCESSFLAG_IGNORE_ORPHANED RT_BIT(1)
129#define EXECUTEPROCESSFLAG_HIDDEN RT_BIT(2)
130#define EXECUTEPROCESSFLAG_NO_PROFILE RT_BIT(3)
131#define EXECUTEPROCESSFLAG_WAIT_STDOUT RT_BIT(4)
132#define EXECUTEPROCESSFLAG_WAIT_STDERR RT_BIT(5)
133#define EXECUTEPROCESSFLAG_EXPAND_ARGUMENTS RT_BIT(6)
134
135/**
136 * Pipe handle IDs used internally for referencing to
137 * a certain pipe buffer.
138 */
139#define OUTPUT_HANDLE_ID_STDOUT_DEPRECATED 0 /* Needed for VBox hosts < 4.1.0. */
140#define OUTPUT_HANDLE_ID_STDOUT 1
141#define OUTPUT_HANDLE_ID_STDERR 2
142
143/**
144 * Defines for guest process array lengths.
145 */
146#define GUESTPROCESS_MAX_CMD_LEN _1K
147#define GUESTPROCESS_MAX_ARGS_LEN _1K
148#define GUESTPROCESS_MAX_ENV_LEN _64K
149#define GUESTPROCESS_MAX_USER_LEN 128
150#define GUESTPROCESS_MAX_PASSWORD_LEN 128
151#define GUESTPROCESS_MAX_DOMAIN_LEN 256
152
153/** @name Internal tools built into VBoxService which are used in order to
154 * accomplish tasks host<->guest.
155 * @{
156 */
157#define VBOXSERVICE_TOOL_CAT "vbox_cat"
158#define VBOXSERVICE_TOOL_LS "vbox_ls"
159#define VBOXSERVICE_TOOL_RM "vbox_rm"
160#define VBOXSERVICE_TOOL_MKDIR "vbox_mkdir"
161#define VBOXSERVICE_TOOL_MKTEMP "vbox_mktemp"
162#define VBOXSERVICE_TOOL_STAT "vbox_stat"
163/** @} */
164
165/**
166 * Input status, reported by the client.
167 */
168enum eInputStatus
169{
170 /** Input is in an undefined state. */
171 INPUT_STS_UNDEFINED = 0,
172 /** Input was written (partially, see cbProcessed). */
173 INPUT_STS_WRITTEN = 1,
174 /** Input failed with an error (see flags for rc). */
175 INPUT_STS_ERROR = 20,
176 /** Process has abandoned / terminated input handling. */
177 INPUT_STS_TERMINATED = 21,
178 /** Too much input data. */
179 INPUT_STS_OVERFLOW = 30
180};
181
182/**
183 * Structure keeping the context of a host callback.
184 */
185typedef struct VBoxGuestCtrlHostCbCtx
186{
187 /** HGCM Function number. */
188 uint32_t uFunction;
189 /** The context ID. */
190 uint32_t uContextID;
191 /** Protocol version of this guest session. Might
192 * be 0 if not supported. */
193 uint32_t uProtocol;
194
195} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
196
197/**
198 * Structure for low level HGCM host callback from
199 * the guest. No deep copy. */
200typedef struct VBoxGuestCtrlHostCallback
201{
202 VBoxGuestCtrlHostCallback(uint32_t cParms, VBOXHGCMSVCPARM paParms[])
203 : mParms(cParms), mpaParms(paParms) { }
204
205 uint32_t mParms;
206 PVBOXHGCMSVCPARM mpaParms;
207
208} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
209
210/**
211 * The service functions which are callable by host.
212 */
213enum eHostFn
214{
215 /**
216 * The host asks the client to cancel all pending waits and exit.
217 */
218 HOST_CANCEL_PENDING_WAITS = 0,
219 /**
220 * The host wants to create a guest session.
221 */
222 HOST_SESSION_CREATE = 20,
223 /**
224 * The host wants to close a guest session.
225 */
226 HOST_SESSION_CLOSE = 21,
227 /**
228 * The host wants to execute something in the guest. This can be a command line
229 * or starting a program.
230 ** Note: Legacy (VBox < 4.3) command.
231 */
232 HOST_EXEC_CMD = 100,
233 /**
234 * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
235 ** Note: Legacy (VBox < 4.3) command.
236 */
237 HOST_EXEC_SET_INPUT = 101,
238 /**
239 * Gets the current status of a running process, e.g.
240 * new data on stdout/stderr, process terminated etc.
241 ** Note: Legacy (VBox < 4.3) command.
242 */
243 HOST_EXEC_GET_OUTPUT = 102,
244 /**
245 * Terminates a running guest process.
246 */
247 HOST_EXEC_TERMINATE = 110,
248 /**
249 * Waits for a certain event to happen. This can be an input, output
250 * or status event.
251 */
252 HOST_EXEC_WAIT_FOR = 120,
253 /**
254 * Opens a guest file.
255 */
256 HOST_FILE_OPEN = 240,
257 /**
258 * Closes a guest file.
259 */
260 HOST_FILE_CLOSE = 241,
261 /**
262 * Reads from an opened guest file.
263 */
264 HOST_FILE_READ = 250,
265 /**
266 * Reads from an opened guest file at
267 * a specified offset.
268 */
269 HOST_FILE_READ_AT = 251,
270 /**
271 * Write to an opened guest file.
272 */
273 HOST_FILE_WRITE = 260,
274 /**
275 * Write to an opened guest file at
276 * a specified offset.
277 */
278 HOST_FILE_WRITE_AT = 261,
279 /**
280 * Changes the read & write position of an opened guest file.
281 */
282 HOST_FILE_SEEK = 270,
283 /**
284 * Gets the current file position of an opened guest file.
285 */
286 HOST_FILE_TELL = 271
287};
288
289/**
290 * The service functions which are called by guest. The numbers may not change,
291 * so we hardcode them.
292 *
293 * Note: Callbacks start at 100. See CALLBACKTYPE enum.
294 */
295enum eGuestFn
296{
297 /**
298 * Guest waits for a new message the host wants to process on the guest side.
299 * This is a blocking call and can be deferred.
300 */
301 GUEST_MSG_WAIT = 1,
302 /**
303 * Guest asks the host to cancel all pending waits the guest itself waits on.
304 * This becomes necessary when the guest wants to quit but still waits for
305 * commands from the host.
306 */
307 GUEST_CANCEL_PENDING_WAITS = 2,
308 /**
309 * Guest disconnected (terminated normally or due to a crash HGCM
310 * detected when calling service::clientDisconnect().
311 */
312 GUEST_DISCONNECTED = 3,
313 /**
314 * Sets a message filter to only get messages which have a certain
315 * context ID scheme (that is, a specific session, object etc).
316 * Since VBox 4.3+.
317 */
318 GUEST_MSG_FILTER_SET = 4,
319 /**
320 * Unsets (and resets) a previously set message filter.
321 */
322 GUEST_MSG_FILTER_UNSET = 5,
323 /**
324 * Skips the current assigned message returned by GUEST_MSG_WAIT.
325 * Needed for telling the host service to not keep stale
326 * host commands in the queue.
327 */
328 GUEST_MSG_SKIP = 10,
329 /**
330 * Guest reports back a guest session status.
331 */
332 GUEST_SESSION_NOTIFY = 20,
333 /**
334 * Guests sends output from an executed process.
335 */
336 GUEST_EXEC_OUTPUT = 100,
337 /**
338 * Guest sends a status update of an executed process to the host.
339 */
340 GUEST_EXEC_STATUS = 101,
341 /**
342 * Guests sends an input status notification to the host.
343 */
344 GUEST_EXEC_INPUT_STATUS = 102,
345 /**
346 * Guest notifies the host about some I/O event. This can be
347 * a stdout, stderr or a stdin event. The actual event only tells
348 * how many data is available / can be sent without actually
349 * transmitting the data.
350 */
351 GUEST_EXEC_IO_NOTIFY = 210,
352 /**
353 * Guest notifies the host about some file event.
354 */
355 GUEST_FILE_NOTIFY = 240
356};
357
358/**
359 * Guest session notification types.
360 * @sa HGCMMsgSessionNotify.
361 */
362enum GUEST_SESSION_NOTIFYTYPE
363{
364 GUEST_SESSION_NOTIFYTYPE_UNDEFINED = 0,
365 /** Something went wrong (see rc). */
366 GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
367 /** Guest session has been started. */
368 GUEST_SESSION_NOTIFYTYPE_STARTED = 11,
369 /** Guest session terminated normally. */
370 GUEST_SESSION_NOTIFYTYPE_TEN = 20,
371 /** Guest session terminated via signal. */
372 GUEST_SESSION_NOTIFYTYPE_TES = 30,
373 /** Guest session terminated abnormally. */
374 GUEST_SESSION_NOTIFYTYPE_TEA = 40,
375 /** Guest session timed out and was killed. */
376 GUEST_SESSION_NOTIFYTYPE_TOK = 50,
377 /** Guest session timed out and was not killed successfully. */
378 GUEST_SESSION_NOTIFYTYPE_TOA = 60,
379 /** Service/OS is stopping, process was killed. */
380 GUEST_SESSION_NOTIFYTYPE_DWN = 150
381};
382
383/**
384 * Guest file notification types.
385 * @sa HGCMMsgFileNotify.
386 */
387enum GUEST_FILE_NOTIFYTYPE
388{
389 GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
390 GUEST_FILE_NOTIFYTYPE_ERROR = 1,
391 GUEST_FILE_NOTIFYTYPE_OPEN = 10,
392 GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
393 GUEST_FILE_NOTIFYTYPE_READ = 30,
394 GUEST_FILE_NOTIFYTYPE_WRITE = 40,
395 GUEST_FILE_NOTIFYTYPE_SEEK = 50,
396 GUEST_FILE_NOTIFYTYPE_TELL = 60
397};
398
399/**
400 * Guest file seeking types. Has to
401 * match FileSeekType in Main.
402 */
403enum GUEST_FILE_SEEKTYPE
404{
405 GUEST_FILE_SEEKTYPE_BEGIN = 1,
406 GUEST_FILE_SEEKTYPE_CURRENT = 4,
407 GUEST_FILE_SEEKTYPE_END = 8
408};
409
410/*
411 * HGCM parameter structures.
412 */
413#pragma pack (1)
414
415/**
416 * Waits for a host command to arrive. The structure then contains the
417 * actual message type + required number of parameters needed to successfully
418 * retrieve that host command (in a next round).
419 */
420typedef struct HGCMMsgCmdWaitFor
421{
422 VBoxGuestHGCMCallInfo hdr;
423
424 /**
425 * The returned command the host wants to
426 * run on the guest.
427 */
428 HGCMFunctionParameter msg; /* OUT uint32_t */
429 /** Number of parameters the message needs. */
430 HGCMFunctionParameter num_parms; /* OUT uint32_t */
431
432} HGCMMsgCmdWaitFor;
433
434/**
435 * Asks the guest control host service to set a command
436 * filter for this client. This filter will then only
437 * deliver messages to the client which match the
438 * wanted context ID (ranges).
439 */
440typedef struct HGCMMsgCmdFilterSet
441{
442 VBoxGuestHGCMCallInfo hdr;
443
444 /** Value to filter for after filter mask
445 * was applied. */
446 HGCMFunctionParameter value; /* IN uint32_t */
447 /** Mask to add to the current set filter. */
448 HGCMFunctionParameter mask_add; /* IN uint32_t */
449 /** Mask to remove from the current set filter. */
450 HGCMFunctionParameter mask_remove; /* IN uint32_t */
451 /** Filter flags; currently unused. */
452 HGCMFunctionParameter flags; /* IN uint32_t */
453
454} HGCMMsgCmdFilterSet;
455
456/**
457 * Asks the guest control host service to disable
458 * a previously set message filter again.
459 */
460typedef struct HGCMMsgCmdFilterUnset
461{
462 VBoxGuestHGCMCallInfo hdr;
463
464 /** Unset flags; currently unused. */
465 HGCMFunctionParameter flags; /* IN uint32_t */
466} HGCMMsgCmdFilterUnset;
467
468/**
469 * Asks the guest control host service to skip the
470 * currently assigned host command returned by
471 * VbglR3GuestCtrlMsgWaitFor().
472 */
473typedef struct HGCMMsgCmdSkip
474{
475 VBoxGuestHGCMCallInfo hdr;
476
477 /** Skip flags; currently unused. */
478 HGCMFunctionParameter flags; /* IN uint32_t */
479} HGCMMsgCmdSkip;
480
481/**
482 * Asks the guest control host service to cancel all pending (outstanding)
483 * waits which were not processed yet. This is handy for a graceful shutdown.
484 */
485typedef struct HGCMMsgCancelPendingWaits
486{
487 VBoxGuestHGCMCallInfo hdr;
488} HGCMMsgCancelPendingWaits;
489
490/**
491 * Creates a guest session.
492 */
493typedef struct HGCMMsgSessionOpen
494{
495 VBoxGuestHGCMCallInfo hdr;
496 /** Context ID. */
497 HGCMFunctionParameter context;
498 /** The guest control protocol version this
499 * session is about to use. */
500 HGCMFunctionParameter protocol;
501 /** The user name to run the guest session under. */
502 HGCMFunctionParameter username;
503 /** The user's password. */
504 HGCMFunctionParameter password;
505 /** The domain to run the guest session under. */
506 HGCMFunctionParameter domain;
507 /** Session creation flags. */
508 HGCMFunctionParameter flags;
509} HGCMMsgSessionOpen;
510
511/**
512 * Terminates (closes) a guest session.
513 */
514typedef struct HGCMMsgSessionClose
515{
516 VBoxGuestHGCMCallInfo hdr;
517 /** Context ID. */
518 HGCMFunctionParameter context;
519 /** Session termination flags. */
520 HGCMFunctionParameter flags;
521} HGCMMsgSessionClose;
522
523/**
524 * Reports back a guest session's status.
525 */
526typedef struct HGCMMsgSessionNotify
527{
528 VBoxGuestHGCMCallInfo hdr;
529 /** Context ID. */
530 HGCMFunctionParameter context;
531 /** Notification type. */
532 HGCMFunctionParameter type;
533 /** Notification result. */
534 HGCMFunctionParameter result;
535} HGCMMsgSessionNotify;
536
537/**
538 * Executes a command inside the guest.
539 */
540typedef struct HGCMMsgProcExec
541{
542 VBoxGuestHGCMCallInfo hdr;
543 /** Context ID. */
544 HGCMFunctionParameter context;
545 /** The command to execute on the guest. */
546 HGCMFunctionParameter cmd;
547 /** Execution flags (see IGuest::ProcessCreateFlag_*). */
548 HGCMFunctionParameter flags;
549 /** Number of arguments. */
550 HGCMFunctionParameter num_args;
551 /** The actual arguments. */
552 HGCMFunctionParameter args;
553 /** Number of environment value pairs. */
554 HGCMFunctionParameter num_env;
555 /** Size (in bytes) of environment block, including terminating zeros. */
556 HGCMFunctionParameter cb_env;
557 /** The actual environment block. */
558 HGCMFunctionParameter env;
559 union
560 {
561 struct
562 {
563 /** The user name to run the executed command under.
564 * Only for VBox < 4.3 hosts. */
565 HGCMFunctionParameter username;
566 /** The user's password.
567 * Only for VBox < 4.3 hosts. */
568 HGCMFunctionParameter password;
569 /** Timeout (in msec) which either specifies the
570 * overall lifetime of the process or how long it
571 * can take to bring the process up and running -
572 * (depends on the IGuest::ProcessCreateFlag_*). */
573 HGCMFunctionParameter timeout;
574 } v1;
575 struct
576 {
577 /** Timeout (in msec) which either specifies the
578 * overall lifetime of the process or how long it
579 * can take to bring the process up and running -
580 * (depends on the IGuest::ProcessCreateFlag_*). */
581 HGCMFunctionParameter timeout;
582 /** Process priority. */
583 HGCMFunctionParameter priority;
584 /** Number of process affinity blocks. */
585 HGCMFunctionParameter num_affinity;
586 /** Pointer to process affinity blocks (uint64_t). */
587 HGCMFunctionParameter affinity;
588 } v2;
589 } u;
590
591} HGCMMsgProcExec;
592
593/**
594 * Sends input to a guest process via stdin.
595 */
596typedef struct HGCMMsgProcInput
597{
598 VBoxGuestHGCMCallInfo hdr;
599 /** Context ID. */
600 HGCMFunctionParameter context;
601 /** The process ID (PID) to send the input to. */
602 HGCMFunctionParameter pid;
603 /** Input flags (see IGuest::ProcessInputFlag_*). */
604 HGCMFunctionParameter flags;
605 /** Data buffer. */
606 HGCMFunctionParameter data;
607 /** Actual size of data (in bytes). */
608 HGCMFunctionParameter size;
609
610} HGCMMsgProcInput;
611
612/**
613 * Retrieves ouptut from a previously executed process
614 * from stdout/stderr.
615 */
616typedef struct HGCMMsgProcOutput
617{
618 VBoxGuestHGCMCallInfo hdr;
619 /** Context ID. */
620 HGCMFunctionParameter context;
621 /** The process ID (PID). */
622 HGCMFunctionParameter pid;
623 /** The pipe handle ID (stdout/stderr). */
624 HGCMFunctionParameter handle;
625 /** Optional flags. */
626 HGCMFunctionParameter flags;
627 /** Data buffer. */
628 HGCMFunctionParameter data;
629
630} HGCMMsgProcOutput;
631
632/**
633 * Reports the current status of a guest process.
634 */
635typedef struct HGCMMsgProcStatus
636{
637 VBoxGuestHGCMCallInfo hdr;
638 /** Context ID. */
639 HGCMFunctionParameter context;
640 /** The process ID (PID). */
641 HGCMFunctionParameter pid;
642 /** The process status. */
643 HGCMFunctionParameter status;
644 /** Optional flags (based on status). */
645 HGCMFunctionParameter flags;
646 /** Optional data buffer (not used atm). */
647 HGCMFunctionParameter data;
648
649} HGCMMsgProcStatus;
650
651/**
652 * Reports back the status of data written to a process.
653 */
654typedef struct HGCMMsgProcStatusInput
655{
656 VBoxGuestHGCMCallInfo hdr;
657 /** Context ID. */
658 HGCMFunctionParameter context;
659 /** The process ID (PID). */
660 HGCMFunctionParameter pid;
661 /** Status of the operation. */
662 HGCMFunctionParameter status;
663 /** Optional flags. */
664 HGCMFunctionParameter flags;
665 /** Data written. */
666 HGCMFunctionParameter written;
667
668} HGCMMsgProcStatusInput;
669
670/*
671 * Guest control 2.0 messages.
672 */
673
674/**
675 * Terminates a guest process.
676 */
677typedef struct HGCMMsgProcTerminate
678{
679 VBoxGuestHGCMCallInfo hdr;
680 /** Context ID. */
681 HGCMFunctionParameter context;
682 /** The process ID (PID). */
683 HGCMFunctionParameter pid;
684
685} HGCMMsgProcTerminate;
686
687/**
688 * Waits for certain events to happen.
689 */
690typedef struct HGCMMsgProcWaitFor
691{
692 VBoxGuestHGCMCallInfo hdr;
693 /** Context ID. */
694 HGCMFunctionParameter context;
695 /** The process ID (PID). */
696 HGCMFunctionParameter pid;
697 /** Wait (event) flags. */
698 HGCMFunctionParameter flags;
699 /** Timeout (in ms). */
700 HGCMFunctionParameter timeout;
701
702} HGCMMsgProcWaitFor;
703
704/**
705 * Opens a guest file.
706 */
707typedef struct HGCMMsgFileOpen
708{
709 VBoxGuestHGCMCallInfo hdr;
710 /** UInt32: Context ID. */
711 HGCMFunctionParameter context;
712 /** String: File to open. */
713 HGCMFunctionParameter filename;
714 /** String: Open mode. */
715 HGCMFunctionParameter openmode;
716 /** String: Disposition. */
717 HGCMFunctionParameter disposition;
718 /** UInt32: Creation mode. */
719 HGCMFunctionParameter creationmode;
720 /** UInt64: Initial offset. */
721 HGCMFunctionParameter offset;
722
723} HGCMMsgFileOpen;
724
725/**
726 * Closes a guest file.
727 */
728typedef struct HGCMMsgFileClose
729{
730 VBoxGuestHGCMCallInfo hdr;
731 /** Context ID. */
732 HGCMFunctionParameter context;
733 /** File handle to close. */
734 HGCMFunctionParameter handle;
735
736} HGCMMsgFileClose;
737
738/**
739 * Reads from a guest file.
740 */
741typedef struct HGCMMsgFileRead
742{
743 VBoxGuestHGCMCallInfo hdr;
744 /** Context ID. */
745 HGCMFunctionParameter context;
746 /** File handle to read from. */
747 HGCMFunctionParameter handle;
748 /** Size (in bytes) to read. */
749 HGCMFunctionParameter size;
750
751} HGCMMsgFileRead;
752
753/**
754 * Reads at a specified offset from a guest file.
755 */
756typedef struct HGCMMsgFileReadAt
757{
758 VBoxGuestHGCMCallInfo hdr;
759 /** Context ID. */
760 HGCMFunctionParameter context;
761 /** File handle to read from. */
762 HGCMFunctionParameter handle;
763 /** Offset where to start reading from. */
764 HGCMFunctionParameter offset;
765 /** Actual size of data (in bytes). */
766 HGCMFunctionParameter size;
767
768} HGCMMsgFileReadAt;
769
770/**
771 * Writes to a guest file.
772 */
773typedef struct HGCMMsgFileWrite
774{
775 VBoxGuestHGCMCallInfo hdr;
776 /** Context ID. */
777 HGCMFunctionParameter context;
778 /** File handle to write to. */
779 HGCMFunctionParameter handle;
780 /** Actual size of data (in bytes). */
781 HGCMFunctionParameter size;
782 /** Data buffer to write to the file. */
783 HGCMFunctionParameter data;
784
785} HGCMMsgFileWrite;
786
787/**
788 * Writes at a specified offset to a guest file.
789 */
790typedef struct HGCMMsgFileWriteAt
791{
792 VBoxGuestHGCMCallInfo hdr;
793 /** Context ID. */
794 HGCMFunctionParameter context;
795 /** File handle to write to. */
796 HGCMFunctionParameter handle;
797 /** Offset where to start reading from. */
798 HGCMFunctionParameter offset;
799 /** Actual size of data (in bytes). */
800 HGCMFunctionParameter size;
801 /** Data buffer to write to the file. */
802 HGCMFunctionParameter data;
803
804} HGCMMsgFileWriteAt;
805
806/**
807 * Seeks the read/write position of a guest file.
808 */
809typedef struct HGCMMsgFileSeek
810{
811 VBoxGuestHGCMCallInfo hdr;
812 /** Context ID. */
813 HGCMFunctionParameter context;
814 /** File handle to seek. */
815 HGCMFunctionParameter handle;
816 /** The seeking method. */
817 HGCMFunctionParameter method;
818 /** The seeking offset. */
819 HGCMFunctionParameter offset;
820
821} HGCMMsgFileSeek;
822
823/**
824 * Tells the current read/write position of a guest file.
825 */
826typedef struct HGCMMsgFileTell
827{
828 VBoxGuestHGCMCallInfo hdr;
829 /** Context ID. */
830 HGCMFunctionParameter context;
831 /** File handle to get the current position for. */
832 HGCMFunctionParameter handle;
833
834} HGCMMsgFileTell;
835
836/******************************************************************************
837* HGCM replies from the guest. These are handled in Main's low-level HGCM *
838* callbacks and dispatched to the appropriate guest object. *
839******************************************************************************/
840
841typedef struct HGCMReplyFileNotify
842{
843 VBoxGuestHGCMCallInfo hdr;
844 /** Context ID. */
845 HGCMFunctionParameter context;
846 /** Notification type. */
847 HGCMFunctionParameter type;
848 /** IPRT result of overall operation. */
849 HGCMFunctionParameter rc;
850 union
851 {
852 struct
853 {
854 /** Guest file handle. */
855 HGCMFunctionParameter handle;
856 } open;
857 /** Note: Close does not have any additional data (yet). */
858 struct
859 {
860 /** Actual data read (if any). */
861 HGCMFunctionParameter data;
862 } read;
863 struct
864 {
865 /** How much data (in bytes) have been successfully written. */
866 HGCMFunctionParameter written;
867 } write;
868 struct
869 {
870 HGCMFunctionParameter offset;
871 } seek;
872 struct
873 {
874 HGCMFunctionParameter offset;
875 } tell;
876 } u;
877
878} HGCMReplyFileNotify;
879
880#pragma pack ()
881
882/******************************************************************************
883* Callback data structures. *
884******************************************************************************/
885
886/**
887 * The guest control callback data header. Must come first
888 * on each callback structure defined below this struct.
889 */
890typedef struct CALLBACKDATA_HEADER
891{
892 /** Context ID to identify callback data. This is
893 * and *must* be the very first parameter in this
894 * structure to still be backwards compatible. */
895 uint32_t uContextID;
896} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
897
898/*
899 * These structures make up the actual low level HGCM callback data sent from
900 * the guest back to the host.
901 */
902
903typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
904{
905 /** Callback data header. */
906 CALLBACKDATA_HEADER hdr;
907} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
908
909typedef struct CALLBACKDATA_SESSION_NOTIFY
910{
911 /** Callback data header. */
912 CALLBACKDATA_HEADER hdr;
913 /** Notification type. */
914 uint32_t uType;
915 /** Notification result. Note: int vs. uint32! */
916 uint32_t uResult;
917} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
918
919typedef struct CALLBACKDATA_PROC_STATUS
920{
921 /** Callback data header. */
922 CALLBACKDATA_HEADER hdr;
923 /** The process ID (PID). */
924 uint32_t uPID;
925 /** The process status. */
926 uint32_t uStatus;
927 /** Optional flags, varies, based on u32Status. */
928 uint32_t uFlags;
929 /** Optional data buffer (not used atm). */
930 void *pvData;
931 /** Size of optional data buffer (not used atm). */
932 uint32_t cbData;
933} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
934
935typedef struct CALLBACKDATA_PROC_OUTPUT
936{
937 /** Callback data header. */
938 CALLBACKDATA_HEADER hdr;
939 /** The process ID (PID). */
940 uint32_t uPID;
941 /** The handle ID (stdout/stderr). */
942 uint32_t uHandle;
943 /** Optional flags (not used atm). */
944 uint32_t uFlags;
945 /** Optional data buffer. */
946 void *pvData;
947 /** Size (in bytes) of optional data buffer. */
948 uint32_t cbData;
949} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
950
951typedef struct CALLBACKDATA_PROC_INPUT
952{
953 /** Callback data header. */
954 CALLBACKDATA_HEADER hdr;
955 /** The process ID (PID). */
956 uint32_t uPID;
957 /** Current input status. */
958 uint32_t uStatus;
959 /** Optional flags. */
960 uint32_t uFlags;
961 /** Size (in bytes) of processed input data. */
962 uint32_t uProcessed;
963} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
964
965/**
966 * General guest file notification callback.
967 */
968typedef struct CALLBACKDATA_FILE_NOTIFY
969{
970 /** Callback data header. */
971 CALLBACKDATA_HEADER hdr;
972 /** Notification type. */
973 uint32_t uType;
974 /** IPRT result of overall operation. */
975 uint32_t rc;
976 union
977 {
978 struct
979 {
980 /** Guest file handle. */
981 uint32_t uHandle;
982 } open;
983 /** Note: Close does not have any additional data (yet). */
984 struct
985 {
986 /** How much data (in bytes) have been read. */
987 uint32_t cbData;
988 /** Actual data read (if any). */
989 void *pvData;
990 } read;
991 struct
992 {
993 /** How much data (in bytes) have been successfully written. */
994 uint32_t cbWritten;
995 } write;
996 struct
997 {
998 /** New file offset after successful seek. */
999 uint64_t uOffActual;
1000 } seek;
1001 struct
1002 {
1003 /** New file offset after successful tell. */
1004 uint64_t uOffActual;
1005 } tell;
1006 } u;
1007} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
1008
1009} /* namespace guestControl */
1010
1011#endif /* !___VBox_HostService_GuestControlService_h */
1012
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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