/* $Id$ */
/** @file
* VBoxServiceControl.h - Internal guest control definitions.
*/
/*
* Copyright (C) 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.
*/
#ifndef ___VBoxServiceControl_h
#define ___VBoxServiceControl_h
#include <iprt/critsect.h>
#include <VBox/VBoxGuestLib.h>
/**
* Pipe IDs for handling the guest process poll set.
*/
typedef enum VBOXSERVICECTRLPIPEID
{
/** Pipe for reading from guest process' stdout. */
/** Pipe for reading from guest process' stderr. */
/** Notification pipe for waking up the guest process
* control thread. */
/**
* Structure for one (opened) guest file.
*/
typedef struct VBOXSERVICECTRLFILE
{
/** Pointer to list archor of following
* list node.
* @todo Would be nice to have a RTListGetAnchor(). */
/** Node to global guest control file list. */
/** @todo Use a map later? */
/** The file name. */
/** The file handle on the guest. */
/** File handle to identify this file. */
/** Context ID. */
/** Pointer to thread data. */
typedef struct VBOXSERVICECTRLSESSIONSTARTUPINFO
{
/** The session's protocol version to use. */
/** The session's ID. */
/** User name (account) to start the guest session under. */
/** Password of specified user name (account). */
/** Domain of the user account. */
/** Session creation flags.
* @sa VBOXSERVICECTRLSESSIONSTARTUPFLAG_* flags. */
/** Pointer to thread data. */
/**
* Structure for a guest session thread to
* the VBoxService main executable.
*/
typedef struct VBOXSERVICECTRLSESSIONTHREAD
{
/** Node to global guest control session list. */
/** @todo Use a map later? */
/** The sessions's startup info. */
/** The worker thread. */
/** Critical section for thread-safe use. */
/** Process handle for forked child. */
/** Shutdown indicator; will be set when the thread
* needs (or is asked) to shutdown. */
bool volatile fShutdown;
/** Indicator set by the service thread exiting. */
bool volatile fStopped;
/** Whether the thread was started or not. */
bool fStarted;
#if 0 /* Pipe IPC not used yet. */
/** Pollset containing all the pipes. */
struct StdPipe
{
} StdIn,
/** The notification pipe associated with this guest session.
* This is NIL_RTPIPE for output pipes. */
/** The other end of hNotificationPipeW. */
#endif
/** Pointer to thread data. */
/** Flag indicating that this session has been forked from
* the main executable. */
/** Flag indicating that this session is anonymous, that is,
* it will run start guest processes with the same credentials
* as the main executable. */
/** Flag indicating that started guest processes will dump their
* stdout output to a separate file on disk. For debugging. */
/** Flag indicating that started guest processes will dump their
* stderr output to a separate file on disk. For debugging. */
/**
* Structure for maintaining a guest session. This also
* contains all started threads (e.g. for guest processes).
*
* This structure can act in two different ways:
* - For legacy guest control handling (protocol version < 2)
* this acts as a per-guest process structure containing all
* the information needed to get a guest process up and running.
* - For newer guest control protocols (>= 2) this structure is
* part of the forked session child, maintaining all guest
* control objects under it.
*/
typedef struct VBOXSERVICECTRLSESSION
{
/* The session's startup information. */
/** List of active guest process threads
* (VBOXSERVICECTRLPROCESS). */
/** List of guest control files (VBOXSERVICECTRLFILE). */
/** The session's critical section. */
/** Internal session flags, not related
* to StartupInfo stuff.
* @sa VBOXSERVICECTRLSESSION_FLAG_* flags. */
/** How many processes do we allow keeping around at a time? */
/** Pointer to guest session. */
/**
* Structure holding information for starting a guest
* process.
*/
typedef struct VBOXSERVICECTRLPROCSTARTUPINFO
{
/** Full qualified path of process to start (without arguments). */
/** Process execution flags. @sa */
/** Command line arguments. */
/** Number of arguments specified in pszArgs. */
/** String of environment variables ("FOO=BAR") to pass to the process
* to start. */
/** Size (in bytes) of environment variables block. */
/** Number of environment variables specified in pszEnv. */
/** User name (account) to start the process under. */
/** Password of specified user name (account). */
/** Time limit (in ms) of the process' life time. */
/** Process priority. */
/** Process affinity. At the moment we support
* up to 4 * 64 = 256 CPUs. */
/** Number of used process affinity blocks. */
/** Pointer to a guest process block. */
/**
* Structure for holding data for one (started) guest process.
*/
typedef struct VBOXSERVICECTRLPROCESS
{
/** Node. */
/** Process handle. */
/** Number of references using this struct. */
/** The worker thread. */
/** The session this guest process
* is bound to. */
/** Shutdown indicator; will be set when the thread
* needs (or is asked) to shutdown. */
bool volatile fShutdown;
/** Whether the guest process thread was stopped
* or not. */
bool volatile fStopped;
/** Whether the guest process thread was started
* or not. */
bool fStarted;
/** Client ID. */
/** Context ID. */
/** Critical section for thread-safe use. */
/** Process startup information. */
/** The process' PID assigned by the guest OS. */
/** The process' request queue to handle requests
* from the outside, e.g. the session. */
/** Our pollset, used for accessing the process'
* std* pipes + the notification pipe. */
/** StdIn pipe for addressing writes to the
* guest process' stdin.*/
/** StdOut pipe for addressing reads from
* guest process' stdout.*/
/** StdOut pipe for addressing reads from
* guest process' stdout.*/
/** The notification pipe associated with this guest process.
* This is NIL_RTPIPE for output pipes. */
/** The other end of hNotificationPipeW. */
/** Pointer to thread data. */
/**
* Note on naming conventions:
* - VBoxServiceControl* is named everything sub service module related, e.g.
* - GstCntl* is named everything which declared extern and thus can be called
* by different guest control modules as needed.
* - gstcntl (all lowercase) is a purely static function to split up functionality
* inside a module.
*/
/* Guest session thread handling. */
extern int GstCntlSessionThreadCreate(PRTLISTANCHOR pList, const PVBOXSERVICECTRLSESSIONSTARTUPINFO pSessionStartupInfo, PVBOXSERVICECTRLSESSIONTHREAD *ppSessionThread);
/* Per-session functions. */
extern PVBOXSERVICECTRLPROCESS GstCntlSessionRetainProcess(PVBOXSERVICECTRLSESSION pSession, uint32_t uPID);
extern int GstCntlSessionHandler(PVBOXSERVICECTRLSESSION pSession, uint32_t uMsg, PVBGLR3GUESTCTRLCMDCTX pHostCtx, void *pvScratchBuf, size_t cbScratchBuf, volatile bool *pfShutdown);
extern int GstCntlSessionProcessAdd(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
extern int GstCntlSessionProcessRemove(PVBOXSERVICECTRLSESSION pSession, PVBOXSERVICECTRLPROCESS pProcess);
extern int GstCntlSessionProcessStartAllowed(const PVBOXSERVICECTRLSESSION pSession, bool *pbAllowed);
/* Per-guest process functions. */
extern int GstCntlProcessHandleInput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, bool fPendingClose, void *pvBuf, uint32_t cbBuf);
extern int GstCntlProcessHandleOutput(PVBOXSERVICECTRLPROCESS pProcess, PVBGLR3GUESTCTRLCMDCTX pHostCtx, uint32_t uHandle, uint32_t cbToRead, uint32_t uFlags);
extern int GstCntlProcessStart(const PVBOXSERVICECTRLSESSION pSession, const PVBOXSERVICECTRLPROCSTARTUPINFO pStartupInfo, uint32_t uContext);
extern int GstCntlProcessWait(const PVBOXSERVICECTRLPROCESS pProcess, RTMSINTERVAL msTimeout, int *pRc);
#endif /* ___VBoxServiceControl_h */