GuestControlSvc.h revision 3fb3de312d1ff675e0f7cc62a7d46cbb1d5d9353
/** @file
* Guest control service - Common header for host service and guest clients.
*/
/*
* Copyright (C) 2011-2013 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#include <VBox/VBoxGuest2.h>
/* Everything defined in this file lives in this namespace. */
/******************************************************************************
* Typedefs, constants and inlines *
******************************************************************************/
#define HGCMSERVICE_NAME "VBoxGuestControlSvc"
/** Maximum number of concurrent guest sessions a VM can have. */
#define VBOX_GUESTCTRL_MAX_SESSIONS 32
/** Maximum number of concurrent guest objects (processes, files, ...)
* a guest session can have. */
#define VBOX_GUESTCTRL_MAX_OBJECTS _2K
/** Maximum of callback contexts a guest process can have. */
#define VBOX_GUESTCTRL_MAX_CONTEXTS _64K
/** Builds a context ID out of the session ID, object ID and an
* increasing count. */
)
#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
/** Gets the session ID out of a context ID. */
#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
((uContextID) >> 27)
/** Gets the process ID out of a context ID. */
#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
/** Gets the context count of a process out of a context ID. */
#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
((uContextID) & 0xffff)
/**
* Process status when executed in the guest.
*/
enum eProcessStatus
{
/** Process is in an undefined state. */
PROC_STS_UNDEFINED = 0,
/** Process has been started. */
PROC_STS_STARTED = 1,
/** Process terminated normally. */
PROC_STS_TEN = 2,
/** Process terminated via signal. */
PROC_STS_TES = 3,
/** Process terminated abnormally. */
PROC_STS_TEA = 4,
/** Process timed out and was killed. */
PROC_STS_TOK = 5,
/** Process timed out and was not killed successfully. */
PROC_STS_TOA = 6,
PROC_STS_DWN = 7,
/** Something went wrong (error code in flags). */
PROC_STS_ERROR = 8
};
/**
* Input flags, set by the host. This is needed for
* handling flags on the guest side.
* Note: Has to match Main's ProcessInputFlag_* flags!
*/
#define INPUT_FLAG_NONE 0x0
#define INPUT_FLAG_EOF RT_BIT(0)
/**
* Guest session creation flags.
* Only handled internally at the moment.
*/
#define SESSIONCREATIONFLAG_NONE 0x0
/**
* Guest process creation flags.
* Note: Has to match Main's ProcessCreateFlag_* flags!
*/
#define EXECUTEPROCESSFLAG_NONE 0x0
#define EXECUTEPROCESSFLAG_WAIT_START RT_BIT(0)
/**
* Pipe handle IDs used internally for referencing to
* a certain pipe buffer.
*/
#define OUTPUT_HANDLE_ID_STDOUT_DEPRECATED 0 /* Needed for VBox hosts < 4.1.0. */
#define OUTPUT_HANDLE_ID_STDOUT 1
#define OUTPUT_HANDLE_ID_STDERR 2
/**
* Defines for guest process array lengths.
*/
#define GUESTPROCESS_MAX_CMD_LEN _1K
#define GUESTPROCESS_MAX_ARGS_LEN _1K
#define GUESTPROCESS_MAX_ENV_LEN _64K
#define GUESTPROCESS_MAX_USER_LEN 128
#define GUESTPROCESS_MAX_PASSWORD_LEN 128
#define GUESTPROCESS_MAX_DOMAIN_LEN 256
/** @name Internal tools built into VBoxService which are used in order to
* accomplish tasks host<->guest.
* @{
*/
#define VBOXSERVICE_TOOL_CAT "vbox_cat"
#define VBOXSERVICE_TOOL_LS "vbox_ls"
#define VBOXSERVICE_TOOL_RM "vbox_rm"
#define VBOXSERVICE_TOOL_MKDIR "vbox_mkdir"
#define VBOXSERVICE_TOOL_MKTEMP "vbox_mktemp"
#define VBOXSERVICE_TOOL_STAT "vbox_stat"
/** @} */
/**
* Input status, reported by the client.
*/
enum eInputStatus
{
/** Input is in an undefined state. */
INPUT_STS_UNDEFINED = 0,
/** Input was written (partially, see cbProcessed). */
INPUT_STS_WRITTEN = 1,
/** Input failed with an error (see flags for rc). */
INPUT_STS_ERROR = 20,
/** Process has abandoned / terminated input handling. */
INPUT_STS_TERMINATED = 21,
/** Too much input data. */
INPUT_STS_OVERFLOW = 30
};
/**
* Structure keeping the context of a host callback.
*/
typedef struct VBoxGuestCtrlHostCbCtx
{
/** HGCM Function number. */
/** The context ID. */
/** Protocol version of this guest session. Might
* be 0 if not supported. */
/**
* Structure for low level HGCM host callback from
* the guest. No deep copy. */
typedef struct VBoxGuestCtrlHostCallback
{
/**
* The service functions which are callable by host.
*/
enum eHostFn
{
/**
* The host asks the client to cancel all pending waits and exit.
*/
/**
* The host wants to create a guest session.
*/
HOST_SESSION_CREATE = 20,
/**
* The host wants to close a guest session.
*/
HOST_SESSION_CLOSE = 21,
/**
* The host wants to execute something in the guest. This can be a command line
* or starting a program.
** Note: Legacy (VBox < 4.3) command.
*/
HOST_EXEC_CMD = 100,
/**
* Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
** Note: Legacy (VBox < 4.3) command.
*/
HOST_EXEC_SET_INPUT = 101,
/**
* Gets the current status of a running process, e.g.
** Note: Legacy (VBox < 4.3) command.
*/
HOST_EXEC_GET_OUTPUT = 102,
/**
* Terminates a running guest process.
*/
HOST_EXEC_TERMINATE = 110,
/**
* Waits for a certain event to happen. This can be an input, output
* or status event.
*/
HOST_EXEC_WAIT_FOR = 120,
/**
* Opens a guest file.
*/
HOST_FILE_OPEN = 240,
/**
* Closes a guest file.
*/
HOST_FILE_CLOSE = 241,
/**
* Reads from an opened guest file.
*/
HOST_FILE_READ = 250,
/**
* Reads from an opened guest file at
* a specified offset.
*/
HOST_FILE_READ_AT = 251,
/**
* Write to an opened guest file.
*/
HOST_FILE_WRITE = 260,
/**
* Write to an opened guest file at
* a specified offset.
*/
HOST_FILE_WRITE_AT = 261,
/**
* Changes the read & write position of an opened guest file.
*/
HOST_FILE_SEEK = 270,
/**
* Gets the current file position of an opened guest file.
*/
HOST_FILE_TELL = 271
};
/**
* The service functions which are called by guest. The numbers may not change,
* so we hardcode them.
*
* Note: Callbacks start at 100. See CALLBACKTYPE enum.
*/
enum eGuestFn
{
/**
* Guest waits for a new message the host wants to process on the guest side.
* This is a blocking call and can be deferred.
*/
GUEST_MSG_WAIT = 1,
/**
* Guest asks the host to cancel all pending waits the guest itself waits on.
* This becomes necessary when the guest wants to quit but still waits for
* commands from the host.
*/
/**
* Guest disconnected (terminated normally or due to a crash HGCM
* detected when calling service::clientDisconnect().
*/
GUEST_DISCONNECTED = 3,
/**
* Sets a message filter to only get messages which have a certain
* context ID scheme (that is, a specific session, object etc).
* Since VBox 4.3+.
*/
GUEST_MSG_FILTER = 4,
/**
* Guest reports back a guest session status.
*/
GUEST_SESSION_NOTIFY = 20,
/**
* Guests sends output from an executed process.
*/
GUEST_EXEC_OUTPUT = 100,
/**
* Guest sends a status update of an executed process to the host.
*/
GUEST_EXEC_STATUS = 101,
/**
* Guests sends an input status notification to the host.
*/
GUEST_EXEC_INPUT_STATUS = 102,
/**
* Guest notifies the host about some I/O event. This can be
* a stdout, stderr or a stdin event. The actual event only tells
* how many data is available / can be sent without actually
* transmitting the data.
*/
GUEST_EXEC_IO_NOTIFY = 210,
/** Guest notifies the host about a file event, like opening,
* closing, seeking etc.
*/
GUEST_FILE_NOTIFY = 240
};
/**
* Guest session notification types.
* @sa HGCMMsgSessionNotify.
*/
{
};
/**
* Guest file notification types.
*/
{
};
/**
* Guest file seeking types.
*/
enum GUEST_FILE_SEEKTYPE
{
};
/*
* HGCM parameter structures.
*/
#pragma pack (1)
/**
* Waits for a host command to arrive. The structure then contains the
* actual message type + required number of parameters needed to successfully
* retrieve that host command (in a next round).
*/
typedef struct HGCMMsgCmdWaitFor
{
/**
* The returned command the host wants to
* run on the guest.
*/
/** Number of parameters the message needs. */
/**
* Asks the guest control host service to set a command
* filter for this client. The filter itself will affect
* the context ID bound to a command.
*/
typedef struct HGCMMsgCmdSetFilter
{
/* Mask of context IDs to be filtered. */
/* Exclude masked; unused. */
/**
* Asks the guest control host service to cancel all pending (outstanding)
* waits which were not processed yet. This is handy for a graceful shutdown.
*/
typedef struct HGCMMsgCancelPendingWaits
{
/**
* Creates a guest session.
*/
typedef struct HGCMMsgSessionOpen
{
/** Context ID. */
/** The guest control protocol version this
* session is about to use. */
/** The user name to run the guest session under. */
/** The user's password. */
/** The domain to run the guest session under. */
/** Session creation flags. */
/**
* Terminates (closes) a guest session.
*/
typedef struct HGCMMsgSessionClose
{
/** Context ID. */
/** Session termination flags. */
/**
* Reports back a guest session's status.
*/
typedef struct HGCMMsgSessionNotify
{
/** Context ID. */
/** Notification type. */
/** Notification result. */
/**
* Executes a command inside the guest.
*/
typedef struct HGCMMsgProcExec
{
/** Context ID. */
/** The command to execute on the guest. */
/** Execution flags (see IGuest::ProcessCreateFlag_*). */
/** Number of arguments. */
/** The actual arguments. */
/** Number of environment value pairs. */
/** Size (in bytes) of environment block, including terminating zeros. */
/** The actual environment block. */
union
{
struct
{
/** The user name to run the executed command under.
* Only for VBox < 4.3 hosts. */
/** The user's password.
* Only for VBox < 4.3 hosts. */
/** Timeout (in msec) which either specifies the
* overall lifetime of the process or how long it
* can take to bring the process up and running -
* (depends on the IGuest::ProcessCreateFlag_*). */
} v1;
struct
{
/** Timeout (in msec) which either specifies the
* overall lifetime of the process or how long it
* can take to bring the process up and running -
* (depends on the IGuest::ProcessCreateFlag_*). */
/** Process priority. */
/** Number of process affinity blocks. */
/** Pointer to process affinity blocks (uint64_t). */
} v2;
} u;
/**
* Sends input to a guest process via stdin.
*/
typedef struct HGCMMsgProcInput
{
/** Context ID. */
/** The process ID (PID) to send the input to. */
/** Input flags (see IGuest::ProcessInputFlag_*). */
/** Data buffer. */
/** Actual size of data (in bytes). */
/**
* Retrieves ouptut from a previously executed process
*/
typedef struct HGCMMsgProcOutput
{
/** Context ID. */
/** The process ID (PID). */
/** Optional flags. */
/** Data buffer. */
/**
* Reports the current status of a guest process.
*/
typedef struct HGCMMsgProcStatus
{
/** Context ID. */
/** The process ID (PID). */
/** The process status. */
/** Optional flags (based on status). */
/** Optional data buffer (not used atm). */
/**
* Reports back the status of data written to a process.
*/
typedef struct HGCMMsgProcStatusInput
{
/** Context ID. */
/** The process ID (PID). */
/** Status of the operation. */
/** Optional flags. */
/** Data written. */
/*
* Guest control 2.0 messages.
*/
/**
* Terminates a guest process.
*/
typedef struct HGCMMsgProcTerminate
{
/** Context ID. */
/** The process ID (PID). */
/**
* Waits for certain events to happen.
*/
typedef struct HGCMMsgProcWaitFor
{
/** Context ID. */
/** The process ID (PID). */
/** Wait (event) flags. */
/** Timeout (in ms). */
/**
* Opens a guest file.
*/
typedef struct HGCMMsgFileOpen
{
/** UInt32: Context ID. */
/** String: File to open. */
/** String: Open mode. */
/** String: Disposition. */
/** UInt32: Creation mode. */
/** UInt64: Initial offset. */
/**
* Closes a guest file.
*/
typedef struct HGCMMsgFileClose
{
/** Context ID. */
/** File handle to close. */
/**
* Reads from a guest file.
*/
typedef struct HGCMMsgFileRead
{
/** Context ID. */
/** File handle to read from. */
/** Actual size of data (in bytes). */
/** Where to put the read data into. */
/**
* Reads at a specified offset from a guest file.
*/
typedef struct HGCMMsgFileReadAt
{
/** Context ID. */
/** File handle to read from. */
/** Offset where to start reading from. */
/** Actual size of data (in bytes). */
/** Where to put the read data into. */
/**
* Writes to a guest file.
*/
typedef struct HGCMMsgFileWrite
{
/** Context ID. */
/** File handle to write to. */
/** Actual size of data (in bytes). */
/** Data buffer to write to the file. */
/**
* Writes at a specified offset to a guest file.
*/
typedef struct HGCMMsgFileWriteAt
{
/** Context ID. */
/** File handle to write to. */
/** Offset where to start reading from. */
/** Actual size of data (in bytes). */
/** Data buffer to write to the file. */
/**
*/
typedef struct HGCMMsgFileSeek
{
/** Context ID. */
/** File handle to seek. */
/** The seeking method. */
/** The seeking offset. */
/**
*/
typedef struct HGCMMsgFileTell
{
/** Context ID. */
/** File handle to get the current position for. */
typedef struct HGCMMsgFileNotify
{
/** Context ID. */
/** Notification type. */
/** Notification payload. */
#pragma pack ()
/******************************************************************************
* Callback data structures. *
******************************************************************************/
/**
* The guest control callback data header. Must come first
* on each callback structure defined below this struct.
*/
typedef struct CALLBACKDATA_HEADER
{
/** Context ID to identify callback data. This is
* and *must* be the very first parameter in this
* structure to still be backwards compatible. */
/*
* These structures make up the actual low level HGCM callback data sent from
* the guest back to the host.
*/
typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
{
/** Callback data header. */
typedef struct CALLBACKDATA_SESSION_NOTIFY
{
/** Callback data header. */
/** Notification type. */
/** Notification result. */
typedef struct CALLBACKDATA_PROC_STATUS
{
/** Callback data header. */
/** The process ID (PID). */
/** The process status. */
/** Optional flags, varies, based on u32Status. */
/** Optional data buffer (not used atm). */
void *pvData;
/** Size of optional data buffer (not used atm). */
typedef struct CALLBACKDATA_PROC_OUTPUT
{
/** Callback data header. */
/** The process ID (PID). */
/** Optional flags (not used atm). */
/** Optional data buffer. */
void *pvData;
/** Size (in bytes) of optional data buffer. */
typedef struct CALLBACKDATA_PROC_INPUT
{
/** Callback data header. */
/** The process ID (PID). */
/** Current input status. */
/** Optional flags. */
/** Size (in bytes) of processed input data. */
typedef struct CALLBACKDATA_FILE_NOTIFY
{
/** Callback data header. */
/** The file handle. */
/******************************************************************************
* Callback payload structures. *
******************************************************************************/
/*
* These structures contain the actual payload, based of the given payload
* type the HGCM message includes.
*/
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_OPEN
{
/** IPRT result of overall operation. */
/** File handle on successful opening. */
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_CLOSE
{
/** IPRT result of overall operation. */
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_READ
{
/** IPRT result of overall operation. */
/** How much data (in bytes) have been read. */
/** Actual data read (if any). */
void *pvData;
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_WRITE
{
/** IPRT result of overall operation. */
/** How much data (in bytes) have been successfully written. */
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_SEEK
{
/** IPRT result of overall operation. */
/** New file offset after successful seek. */
typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_TELL
{
/** IPRT result of overall operation. */
/** Current file offset after successful tell. */
} /* namespace guestControl */
#endif /* !___VBox_HostService_GuestControlService_h */