GuestControlSvc.h revision f9ce005e61f0fbb51a2cabc53d58c3485151faa9
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest control service - Common header for host service and guest clients.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Copyright (C) 2011-2012 Oracle Corporation
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * available from http://www.virtualbox.org. This file is free software;
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * you can redistribute it and/or modify it under the terms of the GNU
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * The contents of this file may alternatively be used under the terms
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * of the Common Development and Distribution License Version 1.0
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * VirtualBox OSE distribution, in which case the provisions of the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * CDDL are applicable instead of those of the GPL.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * You may elect to license modified versions of this file under the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * terms and conditions of either the GPL or the CDDL or both.
61fa69e2bc9fc9e7490feed1c020273f3ddb238dvboxsync/* Everything defined in this file lives in this namespace. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync/******************************************************************************
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync* Typedefs, constants and inlines *
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync******************************************************************************/
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Process status when executed in the guest.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process is in an undefined state. */
223cf005b18af2c21352a70693ebaf0582f68ebcvboxsync /** Process has been started. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process terminated normally. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process terminated via signal. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process terminated abnormally. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process timed out and was killed. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process timed out and was not killed successfully. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Service/OS is stopping, process was killed. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Something went wrong (error code in flags). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Input flags, set by the host. This is needed for
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * handling flags on the guest side.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Note: Has to match Main's ProcessInputFlag_* flags!
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Execution flags.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Note: Has to match Main's CreateProcessFlag_* flags!
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync#define EXECUTEPROCESSFLAG_IGNORE_ORPHANED RT_BIT(1)
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Pipe handle IDs used internally for referencing to
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * a certain pipe buffer.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync#define OUTPUT_HANDLE_ID_STDOUT_DEPRECATED 0 /* Needed for VBox hosts < 4.1.0. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Defines for guest process array lengths.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync/** @name Internal tools built into VBoxService which are used in order to
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * accomplish tasks host<->guest.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Input status, reported by the client.
fdea543f71872a3ec3909536a4fce37ab7aa3a8bvboxsync /** Input is in an undefined state. */
fdea543f71872a3ec3909536a4fce37ab7aa3a8bvboxsync /** Input was written (partially, see cbProcessed). */
8f7bc6ad2b7bbcb4b3b96248cd2478e45f2e3b88vboxsync /** Input failed with an error (see flags for rc). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Process has abandoned / terminated input handling. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Too much input data. */
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * The guest control callback data header. Must come first
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * on each callback structure defined below this struct.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync /** Magic number to identify the structure. */
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync /** Context ID to identify callback data. */
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsynctypedef struct VBoxGuestCtrlCallbackDataClientDisconnected
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync /** Callback data header. */
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsynctypedef CALLBACKDATACLIENTDISCONNECTED *PCALLBACKDATACLIENTDISCONNECTED;
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * Data structure to pass to the service extension callback. We use this to
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * notify the host of changes to properties.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync /** Callback data header. */
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync /** The process ID (PID). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The process status. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Optional flags, varies, based on u32Status. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Optional data buffer (not used atm). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Size of optional data buffer (not used atm). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsynctypedef CALLBACKDATAEXECSTATUS *PCALLBACKDATAEXECSTATUS;
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Callback data header. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The process ID (PID). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The handle ID (stdout/stderr). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Optional flags (not used atm). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Optional data buffer. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Size (in bytes) of optional data buffer. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsynctypedef struct VBoxGuestCtrlCallbackDataExecInStatus
a11c569636fa6838bd423f4631a9660a5a84204bvboxsync /** Callback data header. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The process ID (PID). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Current input status. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Optional flags. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Size (in bytes) of processed input data. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsynctypedef CALLBACKDATAEXECINSTATUS *PCALLBACKDATAEXECINSTATUS;
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync CALLBACKDATAMAGIC_CLIENT_DISCONNECTED = 0x08041984,
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The service functions which are callable by host.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The host asks the client to cancel all pending waits and exit.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Execution handling.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The host wants to execute something in the guest. This can be a command line
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * or starting a program.
aaeb2e2f6ed5b164f1dec9a16a7adeb84f64cf31vboxsync * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
78a205e3fc6719d59e8c561b3d287d3a4f879852vboxsync * Gets the current status of a running process, e.g.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * new data on stdout/stderr, process terminated etc.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * Guest control 2.0 commands start in the 2xx number space.
6b022885f2cb6a55167609edecd89570cd80001dvboxsync * Waits for a certain event to happen. This can be an input, output
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * or status event.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The service functions which are called by guest. The numbers may not change,
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * so we hardcode them.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest waits for a new message the host wants to process on the guest side.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This is a blocking call and can be deferred.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest asks the host to cancel all pending waits the guest itself waits on.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This becomes necessary when the guest wants to quit but still waits for
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * commands from the host.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest disconnected (terminated normally or due to a crash HGCM
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * detected when calling service::clientDisconnect().
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Process execution.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The 1xx commands are legacy guest control commands and
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * will be replaced by newer commands in the future.
e08de24d4792d31b7f2aac29db5cb8840d940009vboxsync * Guests sends output from an executed process.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest sends a status update of an executed process to the host.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guests sends an input status notification to the host.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest control 2.0 commands start in the 2xx number space.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Guest notifies the host about some I/O event. This can be
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * a stdout, stderr or a stdin event. The actual event only tells
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * how many data is available / can be sent without actually
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * transmitting the data.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * HGCM parameter structures.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The returned command the host wants to
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * run on the guest.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Number of parameters the message needs. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync HGCMFunctionParameter num_parms; /* OUT uint32_t */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Asks the guest control host service to cancel all pending (outstanding)
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * waits which were not processed yet. This is handy for a graceful shutdown.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsynctypedef struct VBoxGuestCtrlHGCMMsgCancelPendingWaits
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Executes a command inside the guest.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Context ID. */
680ca45722ec7123029ced4f88dfad87b397ef52vboxsync /** The command to execute on the guest. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Execution flags (see IGuest::ProcessCreateFlag_*). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Number of arguments. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The actual arguments. */
0e77737b0ba913683e614db11463b31ca67aacbevboxsync /** Number of environment value pairs. */
0e77737b0ba913683e614db11463b31ca67aacbevboxsync /** Size (in bytes) of environment block, including terminating zeros. */
0e77737b0ba913683e614db11463b31ca67aacbevboxsync /** The actual environment block. */
e4ea543752422f1139923e3e506c625b0a1827c5vboxsync /** The user name to run the executed command under. */
2d53f6e472561965d363674e17f48d3bdffc24d3vboxsync /** The user's password. */
e9a217d585085a6a6d129d27ca0d96a1b8e6d0eevboxsync /** Timeout (in msec) which either specifies the
2d53f6e472561965d363674e17f48d3bdffc24d3vboxsync * overall lifetime of the process or how long it
2d53f6e472561965d363674e17f48d3bdffc24d3vboxsync * can take to bring the process up and running -
2d53f6e472561965d363674e17f48d3bdffc24d3vboxsync * (depends on the IGuest::ProcessCreateFlag_*). */
0e77737b0ba913683e614db11463b31ca67aacbevboxsync * Injects input to a previously executed process via stdin.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Context ID. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The process ID (PID) to send the input to. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Input flags (see IGuest::ProcessInputFlag_*). */
6b022885f2cb6a55167609edecd89570cd80001dvboxsync /** Data buffer. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Actual size of data (in bytes). */
e08de24d4792d31b7f2aac29db5cb8840d940009vboxsync * Retrieves ouptut from a previously executed process
6b022885f2cb6a55167609edecd89570cd80001dvboxsync /** Context ID. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The process ID (PID). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** The pipe handle ID (stdout/stderr). */
6b022885f2cb6a55167609edecd89570cd80001dvboxsync /** Optional flags. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Data buffer. */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Reports the current status of a (just) started
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * or terminated process.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Context ID. */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** The process ID (PID). */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** The process status. */
6b022885f2cb6a55167609edecd89570cd80001dvboxsync /** Optional flags (based on status). */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** Optional data buffer (not used atm). */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync * Reports back the status of data written to a process.
6b022885f2cb6a55167609edecd89570cd80001dvboxsync /** Context ID. */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** The process ID (PID). */
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Status of the operation. */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** Optional flags. */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync /** Data written. */
d98e61ba075ed7d0b567a5d884bc85d643fe3de7vboxsync * Reports back the currente I/O status of a guest process.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync /** Context ID. */
79b24ef0ab7cd4a03a3571b3954c52ab8b573137vboxsync /** Data written. */
79b24ef0ab7cd4a03a3571b3954c52ab8b573137vboxsync * Structure for buffering execution requests in the host service.
3dde2f85d4cf477621a3128887a2c08a8bca7c01vboxsynctypedef VBOXGUESTCTRPARAMBUFFER *PVBOXGUESTCTRPARAMBUFFER;
5e797edc29f96c8367de4fbf5874171c24a89ba7vboxsync} /* namespace guestControl */
6b022885f2cb6a55167609edecd89570cd80001dvboxsync#endif /* !___VBox_HostService_GuestControlService_h */