GuestControlSvc.h revision 4171ffb38eb8720b2ae9a8d13e95103ab26cfd12
/** @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
/** Base (start) of guest control session IDs. Session
* ID 0 is reserved for the root process which
* hosts all other guest session processes. */
#define VBOX_GUESTCTRL_SESSION_ID_BASE 1
/** Builds a context ID out of the session ID, object ID and an
* increasing count. */
)
/** Creates a context ID out of a session ID. */
#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
/** Gets the session ID out of a context ID. */
#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
/** 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)
/** Filter context IDs by session. Can be used in conjunction
* with VbglR3GuestCtrlMsgFilterSet(). */
#define VBOX_GUESTCTRL_FILTER_BY_SESSION(uSession) \
/**
* 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 directory removement flags.
* Essentially using what IPRT's RTDIRRMREC_F_
* defines have to offer.
*/
#define DIRREMOVE_FLAG_RECURSIVE RT_BIT(0)
/** Delete the content of the directory and the directory itself. */
/** Only delete the content of the directory, omit the directory it self. */
/** Mask of valid flags. */
/**
* 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
/**
* Guest path rename flags.
* Essentially using what IPRT's RTPATHRENAME_FLAGS_
* defines have to offer.
*/
/** Do not replace anything. */
#define PATHRENAME_FLAG_NO_REPLACE UINT32_C(0)
/** This will replace attempt any target which isn't a directory. */
#define PATHRENAME_FLAG_REPLACE RT_BIT(0)
/** Don't allow symbolic links as part of the path. */
/** Mask of valid flags. */
/**
* 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
{
/** Number of HGCM parameters. */
/** Actual HGCM parameters. */
/**
* 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,
/**
* Removes a directory on the guest.
*/
HOST_DIR_REMOVE = 320,
/**
* Renames a path on the guest.
*/
HOST_PATH_RENAME = 330
};
/**
* The service functions which are called by guest. The numbers may not change,
* so we hardcode them.
*/
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_SET = 4,
/**
* Unsets (and resets) a previously set message filter.
*/
/**
* Skips the current assigned message returned by GUEST_MSG_WAIT.
* Needed for telling the host service to not keep stale
* host commands in the queue.
*/
GUEST_MSG_SKIP = 10,
/**
* General reply to a host message. Only contains basic data
* along with a simple payload.
*/
GUEST_MSG_REPLY = 11,
/**
* General message for updating a pending progress for
* a long task.
*/
/**
* Guest reports back a guest session status.
*/
GUEST_SESSION_NOTIFY = 20,
/**
* Guest wants to close a specific guest session.
*/
GUEST_SESSION_CLOSE = 21,
/**
* 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 some directory event.
*/
GUEST_DIR_NOTIFY = 230,
/**
* Guest notifies the host about some file event.
*/
GUEST_FILE_NOTIFY = 240
};
/**
* Guest session notification types.
* @sa HGCMMsgSessionNotify.
*/
{
/** Something went wrong (see rc). */
/** Guest session has been started. */
/** Guest session terminated normally. */
/** Guest session terminated via signal. */
/** Guest session terminated abnormally. */
/** Guest session timed out and was killed. */
/** Guest session timed out and was not killed successfully. */
};
/**
* Guest directory notification types.
* @sa HGCMMsgDirNotify.
*/
enum GUEST_DIR_NOTIFYTYPE
{
/** Something went wrong (see rc). */
/** Guest directory opened. */
/** Guest directory closed. */
/** Information about an open guest directory. */
/** Guest directory created. */
/** Guest directory deleted. */
};
/**
* Guest file notification types.
* @sa HGCMMsgFileNotify.
*/
{
};
/**
* Guest file seeking types. Has to
* match FileSeekType in Main.
*/
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. This filter will then only
* deliver messages to the client which match the
* wanted context ID (ranges).
*/
typedef struct HGCMMsgCmdFilterSet
{
/** Value to filter for after filter mask
* was applied. */
/** Mask to add to the current set filter. */
/** Mask to remove from the current set filter. */
/** Filter flags; currently unused. */
/**
* Asks the guest control host service to disable
* a previously set message filter again.
*/
typedef struct HGCMMsgCmdFilterUnset
{
/** Unset flags; currently unused. */
/**
* Asks the guest control host service to skip the
* currently assigned host command returned by
* VbglR3GuestCtrlMsgWaitFor().
*/
typedef struct HGCMMsgCmdSkip
{
/** Skip flags; currently 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
{
typedef struct HGCMMsgCmdReply
{
/** Context ID. */
/** Message type. */
/** IPRT result of overall operation. */
/** Optional payload to this reply. */
/**
* 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. */
typedef struct HGCMMsgPathRename
{
/** UInt32: Context ID. */
/** Source to rename. */
/** Destination to rename source to. */
/** UInt32: Rename flags. */
/**
* 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 ms) 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). */
typedef struct HGCMMsgDirRemove
{
/** UInt32: Context ID. */
/** Directory to remove. */
/** UInt32: Removement flags. */
/**
* Opens a guest file.
*/
typedef struct HGCMMsgFileOpen
{
/** UInt32: Context ID. */
/** File to open. */
/** Open mode. */
/** Disposition mode. */
/** Sharing mode. */
/** 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. */
/** Size (in bytes) to read. */
/**
* 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). */
/**
* 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. */
/******************************************************************************
* HGCM replies from the guest. These are handled in Main's low-level HGCM *
* callbacks and dispatched to the appropriate guest object. *
******************************************************************************/
typedef struct HGCMReplyFileNotify
{
/** Context ID. */
/** Notification type. */
/** IPRT result of overall operation. */
union
{
struct
{
/** Guest file handle. */
} open;
/** Note: Close does not have any additional data (yet). */
struct
{
/** Actual data read (if any). */
} read;
struct
{
/** How much data (in bytes) have been successfully written. */
} write;
struct
{
} seek;
struct
{
} tell;
} u;
typedef struct HGCMReplyDirNotify
{
/** Context ID. */
/** Notification type. */
/** IPRT result of overall operation. */
union
{
struct
{
/** Directory information. */
} info;
struct
{
/** Guest directory handle. */
} open;
struct
{
/** Current read directory entry. */
/** Extended entry object information. Optional. */
} read;
} u;
#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_MSG_REPLY
{
/** Callback data header. */
/** Notification type. */
/** Notification result. Note: int vs. uint32! */
/** Pointer to optional payload. */
void *pvPayload;
/** Payload size (in bytes). */
typedef struct CALLBACKDATA_SESSION_NOTIFY
{
/** Callback data header. */
/** Notification type. */
/** Notification result. Note: int vs. uint32! */
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. */
/**
* General guest directory notification callback.
*/
typedef struct CALLBACKDATA_DIR_NOTIFY
{
/** Callback data header. */
/** Notification type. */
/** IPRT result of overall operation. */
union
{
struct
{
/** Size (in bytes) of directory information. */
/** Pointer to directory information. */
void *pvObjInfo;
} info;
struct
{
/** Guest directory handle. */
} open;
/** Note: Close does not have any additional data (yet). */
struct
{
/** Size (in bytes) of directory entry information. */
/** Pointer to directory entry information. */
void *pvEntry;
/** Size (in bytes) of directory entry object information. */
/** Pointer to directory entry object information. */
void *pvObjInfo;
} read;
} u;
/**
* General guest file notification callback.
*/
typedef struct CALLBACKDATA_FILE_NOTIFY
{
/** Callback data header. */
/** Notification type. */
/** IPRT result of overall operation. */
union
{
struct
{
/** Guest file handle. */
} open;
/** Note: Close does not have any additional data (yet). */
struct
{
/** How much data (in bytes) have been read. */
/** Actual data read (if any). */
void *pvData;
} read;
struct
{
/** How much data (in bytes) have been successfully written. */
} write;
struct
{
/** New file offset after successful seek. */
} seek;
struct
{
/** New file offset after successful tell. */
} tell;
} u;
} /* namespace guestControl */
#endif /* !___VBox_HostService_GuestControlService_h */