VirtualBox

Changeset 44863 in vbox for trunk/include/VBox/HostServices


Ignore:
Timestamp:
Feb 28, 2013 12:18:17 PM (12 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
84015
Message:

GuestCtrl: Infrastructure changes for handling and executing dedicated guest sessions and protocol versioning (untested, work in progress).

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/HostServices/GuestControlSvc.h

    r42846 r44863  
    44
    55/*
    6  * Copyright (C) 2011-2012 Oracle Corporation
     6 * Copyright (C) 2011-2013 Oracle Corporation
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    4141* Typedefs, constants and inlines                                             *
    4242******************************************************************************/
     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/** Builds a context ID out of the session ID, object ID and an
     55 *  increasing count. */
     56#define VBOX_GUESTCTRL_CONTEXTID_MAKE(uSession, uObject, uCount) \
     57    (  (uint32_t)((uSession) &   0x1f) << 27 \
     58     | (uint32_t)((uObject)  &  0x7ff) << 16 \
     59     | (uint32_t)((uCount)   & 0xffff)       \
     60    )
     61#define VBOX_GUESTCTRL_CONTEXTID_MAKE_SESSION(uSession) \
     62    ((uint32_t)((uSession) & 0x1f) << 27)
     63/** Gets the session ID out of a context ID. */
     64#define VBOX_GUESTCTRL_CONTEXTID_GET_SESSION(uContextID) \
     65    ((uContextID) >> 27)
     66/** Gets the process ID out of a context ID. */
     67#define VBOX_GUESTCTRL_CONTEXTID_GET_OBJECT(uContextID) \
     68    (((uContextID) >> 16) & 0x7ff)
     69/** Gets the context count of a process out of a context ID. */
     70#define VBOX_GUESTCTRL_CONTEXTID_GET_COUNT(uContextID) \
     71    ((uContextID) & 0xffff)
    4372
    4473/**
    … …  
    104133#define GUESTPROCESS_MAX_USER_LEN           128
    105134#define GUESTPROCESS_MAX_PASSWORD_LEN       128
     135#define GUESTPROCESS_MAX_DOMAIN_LEN         256
    106136
    107137/** @name Internal tools built into VBoxService which are used in order to
    … …  
    135165
    136166/**
    137  * The guest control callback data header. Must come first
    138  * on each callback structure defined below this struct.
    139  */
    140 typedef struct VBoxGuestCtrlCallbackHeader
    141 {
    142     /** Magic number to identify the structure. */
    143     uint32_t u32Magic;
    144     /** Context ID to identify callback data. */
    145     uint32_t u32ContextID;
    146 } CALLBACKHEADER;
    147 typedef CALLBACKHEADER *PCALLBACKHEADER;
    148 
    149 typedef struct VBoxGuestCtrlCallbackDataClientDisconnected
    150 {
    151     /** Callback data header. */
    152     CALLBACKHEADER hdr;
    153 } CALLBACKDATACLIENTDISCONNECTED;
    154 typedef CALLBACKDATACLIENTDISCONNECTED *PCALLBACKDATACLIENTDISCONNECTED;
    155 
    156 /**
    157  * Data structure to pass to the service extension callback.  We use this to
    158  * notify the host of changes to properties.
    159  */
    160 typedef struct VBoxGuestCtrlCallbackDataExecStatus
    161 {
    162     /** Callback data header. */
    163     CALLBACKHEADER hdr;
    164     /** The process ID (PID). */
    165     uint32_t u32PID;
    166     /** The process status. */
    167     uint32_t u32Status;
    168     /** Optional flags, varies, based on u32Status. */
    169     uint32_t u32Flags;
    170     /** Optional data buffer (not used atm). */
    171     void *pvData;
    172     /** Size of optional data buffer (not used atm). */
    173     uint32_t cbData;
    174 } CALLBACKDATAEXECSTATUS;
    175 typedef CALLBACKDATAEXECSTATUS *PCALLBACKDATAEXECSTATUS;
    176 
    177 typedef struct VBoxGuestCtrlCallbackDataExecOut
    178 {
    179     /** Callback data header. */
    180     CALLBACKHEADER hdr;
    181     /** The process ID (PID). */
    182     uint32_t u32PID;
    183     /** The handle ID (stdout/stderr). */
    184     uint32_t u32HandleId;
    185     /** Optional flags (not used atm). */
    186     uint32_t u32Flags;
    187     /** Optional data buffer. */
    188     void *pvData;
    189     /** Size (in bytes) of optional data buffer. */
    190     uint32_t cbData;
    191 } CALLBACKDATAEXECOUT;
    192 typedef CALLBACKDATAEXECOUT *PCALLBACKDATAEXECOUT;
    193 
    194 typedef struct VBoxGuestCtrlCallbackDataExecInStatus
    195 {
    196     /** Callback data header. */
    197     CALLBACKHEADER hdr;
    198     /** The process ID (PID). */
    199     uint32_t u32PID;
    200     /** Current input status. */
    201     uint32_t u32Status;
    202     /** Optional flags. */
    203     uint32_t u32Flags;
    204     /** Size (in bytes) of processed input data. */
    205     uint32_t cbProcessed;
    206 } CALLBACKDATAEXECINSTATUS;
    207 typedef CALLBACKDATAEXECINSTATUS *PCALLBACKDATAEXECINSTATUS;
    208 
    209 enum eVBoxGuestCtrlCallbackDataMagic
    210 {
    211     CALLBACKDATAMAGIC_CLIENT_DISCONNECTED = 0x08041984,
    212 
    213     CALLBACKDATAMAGIC_EXEC_STATUS = 0x26011982,
    214     CALLBACKDATAMAGIC_EXEC_OUT = 0x11061949,
    215     CALLBACKDATAMAGIC_EXEC_IN_STATUS = 0x19091951
    216 };
    217 
    218 enum eVBoxGuestCtrlCallbackType
    219 {
    220     VBOXGUESTCTRLCALLBACKTYPE_UNKNOWN = 0,
    221 
    222     VBOXGUESTCTRLCALLBACKTYPE_EXEC_START = 1,
    223     VBOXGUESTCTRLCALLBACKTYPE_EXEC_OUTPUT = 2,
    224     VBOXGUESTCTRLCALLBACKTYPE_EXEC_INPUT_STATUS = 3
    225 };
     167 * Structure keeping the context of a host callback.
     168 */
     169typedef struct VBoxGuestCtrlHostCbCtx
     170{
     171    /** HGCM Function number. */
     172    uint32_t uFunction;
     173    /** The context ID. */
     174    uint32_t uContextID;
     175    /** Protocol version of this guest session. Might
     176     *  be 0 if not supported. */
     177    uint32_t uProtocol;
     178
     179} VBOXGUESTCTRLHOSTCBCTX, *PVBOXGUESTCTRLHOSTCBCTX;
     180
     181/**
     182 * Structure for low level HGCM host callback from
     183 * the guest. No deep copy. */
     184typedef struct VBoxGuestCtrlHostCallback
     185{
     186    VBoxGuestCtrlHostCallback(uint32_t cParms, VBOXHGCMSVCPARM paParms[])
     187                                : mParms(cParms), mpaParms(paParms) { }
     188
     189    uint32_t mParms;
     190    PVBOXHGCMSVCPARM mpaParms;
     191
     192} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
    226193
    227194/**
    … …  
    234201     */
    235202    HOST_CANCEL_PENDING_WAITS = 0,
    236 
    237     /*
    238      * Execution handling.
    239      */
    240 
     203    /**
     204     * The host wants to create a guest session.
     205     */
     206    HOST_SESSION_CREATE = 20,
     207    /**
     208     * The host wants to close a guest session.
     209     */
     210    HOST_SESSION_CLOSE = 21,
    241211    /**
    242212     * The host wants to execute something in the guest. This can be a command line
    243213     * or starting a program.
     214     ** Note: Legacy (VBox < 4.3) command.
    244215     */
    245216    HOST_EXEC_CMD = 100,
    246217    /**
    247218     * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
     219     ** Note: Legacy (VBox < 4.3) command.
    248220     */
    249221    HOST_EXEC_SET_INPUT = 101,
    … …  
    251223     * Gets the current status of a running process, e.g.
    252224     * new data on stdout/stderr, process terminated etc.
     225     ** Note: Legacy (VBox < 4.3) command.
    253226     */
    254227    HOST_EXEC_GET_OUTPUT = 102,
    255 
    256     /*
    257      * Guest control 2.0 commands start in the 2xx number space.
    258      */
    259 
     228    /**
     229     * Terminates a running guest process.
     230     */
     231    HOST_EXEC_TERMINATE = 110,
    260232    /**
    261233     * Waits for a certain event to happen. This can be an input, output
    262234     * or status event.
    263235     */
    264     HOST_EXEC_WAIT_FOR = 210,
     236    HOST_EXEC_WAIT_FOR = 120,
    265237    /**
    266238     * Opens a guest file.
    … …  
    274246     * Reads from an opened guest file.
    275247     */
    276     HOST_FILE_READ = 242,
     248    HOST_FILE_READ = 250,
     249    /**
     250     * Reads from an opened guest file at
     251     * a specified offset.
     252     */
     253    HOST_FILE_READ_AT = 251,
    277254    /**
    278255     * Write to an opened guest file.
    279256     */
    280     HOST_FILE_WRITE = 243,
     257    HOST_FILE_WRITE = 260,
     258    /**
     259     * Write to an opened guest file at
     260     * a specified offset.
     261     */
     262    HOST_FILE_WRITE_AT = 261,
    281263    /**
    282264     * Changes the read & write position of an opened guest file.
    283265     */
    284     HOST_FILE_SEEK = 244,
     266    HOST_FILE_SEEK = 270,
    285267    /**
    286268     * Gets the current file position of an opened guest file.
    287269     */
    288     HOST_FILE_TELL = 245
     270    HOST_FILE_TELL = 271
    289271};
    290272
    291273/**
    292  * The service functions which are called by guest.  The numbers may not change,
     274 * The service functions which are called by guest. The numbers may not change,
    293275 * so we hardcode them.
     276 *
     277 * Note: Callbacks start at 100. See CALLBACKTYPE enum.
    294278 */
    295279enum eGuestFn
    … …  
    299283     * This is a blocking call and can be deferred.
    300284     */
    301     GUEST_GET_HOST_MSG = 1,
     285    GUEST_MSG_WAIT = 1,
    302286    /**
    303287     * Guest asks the host to cancel all pending waits the guest itself waits on.
    … …  
    311295     */
    312296    GUEST_DISCONNECTED = 3,
    313 
    314     /*
    315      * Process execution.
    316      * The 1xx commands are legacy guest control commands and
    317      * will be replaced by newer commands in the future.
    318      */
    319 
     297    /**
     298     * Sets a message filter to only get messages which have a certain
     299     * context ID scheme (that is, a specific session, object etc).
     300     * Since VBox 4.3+.
     301     */
     302    GUEST_MSG_FILTER = 4,
     303    /**
     304     * Guest reports back a guest session status.
     305     */
     306    GUEST_SESSION_NOTIFY = 20,
    320307    /**
    321308     * Guests sends output from an executed process.
    322309     */
    323     GUEST_EXEC_SEND_OUTPUT = 100,
     310    GUEST_EXEC_OUTPUT = 100,
    324311    /**
    325312     * Guest sends a status update of an executed process to the host.
    326313     */
    327     GUEST_EXEC_SEND_STATUS = 101,
     314    GUEST_EXEC_STATUS = 101,
    328315    /**
    329316     * Guests sends an input status notification to the host.
    330317     */
    331     GUEST_EXEC_SEND_INPUT_STATUS = 102,
    332 
    333     /*
    334      * Guest control 2.0 commands start in the 2xx number space.
    335      */
    336 
     318    GUEST_EXEC_INPUT_STATUS = 102,
    337319    /**
    338320     * Guest notifies the host about some I/O event. This can be
    … …  
    349331
    350332/**
     333 * Guest session notification types.
     334 * @sa HGCMMsgSessionNotify.
     335 */
     336enum GUEST_SESSION_NOTIFYTYPE
     337{
     338    GUEST_SESSION_NOTIFYTYPE_UNKNOWN = 0,
     339    GUEST_SESSION_NOTIFYTYPE_ERROR = 1,
     340    GUEST_SESSION_NOTIFYTYPE_OPEN = 10,
     341    GUEST_SESSION_NOTIFYTYPE_CLOSE = 20
     342};
     343
     344/**
    351345 * Guest file notification types.
    352346 */
    353 enum eGuestFileNotifyType
    354 {
    355     GUESTFILENOTIFYTYPE_ERROR = 0,
    356     GUESTFILENOTIFYTYPE_OPEN = 10,
    357     GUESTFILENOTIFYTYPE_CLOSE = 20,
    358     GUESTFILENOTIFYTYPE_READ = 30,
    359     GUESTFILENOTIFYTYPE_WRITE = 40,
    360     GUESTFILENOTIFYTYPE_SEEK = 50,
    361     GUESTFILENOTIFYTYPE_TELL = 60
     347enum GUEST_FILE_NOTIFYTYPE
     348{
     349    GUEST_FILE_NOTIFYTYPE_UNKNOWN = 0,
     350    GUEST_FILE_NOTIFYTYPE_ERROR = 1,
     351    GUEST_FILE_NOTIFYTYPE_OPEN = 10,
     352    GUEST_FILE_NOTIFYTYPE_CLOSE = 20,
     353    GUEST_FILE_NOTIFYTYPE_READ = 30,
     354    GUEST_FILE_NOTIFYTYPE_WRITE = 40,
     355    GUEST_FILE_NOTIFYTYPE_SEEK = 50,
     356    GUEST_FILE_NOTIFYTYPE_TELL = 60
     357};
     358
     359/**
     360 * Guest file seeking types.
     361 */
     362enum GUEST_FILE_SEEKTYPE
     363{
     364    GUEST_FILE_SEEKTYPE_BEGIN = 1,
     365    GUEST_FILE_SEEKTYPE_CURRENT = 4,
     366    GUEST_FILE_SEEKTYPE_END = 8
    362367};
    363368
    … …  
    367372#pragma pack (1)
    368373
    369 typedef struct VBoxGuestCtrlHGCMMsgType
     374/**
     375 * Waits for a host command to arrive. The structure then contains the
     376 * actual message type + required number of parameters needed to successfully
     377 * retrieve that host command (in a next round).
     378 */
     379typedef struct HGCMMsgCmdWaitFor
    370380{
    371381    VBoxGuestHGCMCallInfo hdr;
    … …  
    379389    HGCMFunctionParameter num_parms; /* OUT uint32_t */
    380390
    381 } VBoxGuestCtrlHGCMMsgType;
     391} HGCMMsgCmdWaitFor;
     392
     393/**
     394 * Asks the guest control host service to set a command
     395 * filter for this client. The filter itself will affect
     396 * the context ID bound to a command.
     397 */
     398typedef struct HGCMMsgCmdSetFilter
     399{
     400    VBoxGuestHGCMCallInfo hdr;
     401
     402    /* Mask of context IDs to be filtered. */
     403    HGCMFunctionParameter add;      /* IN uint32_t */
     404    /* Exclude masked; unused. */
     405    HGCMFunctionParameter remove;   /* IN uint32_t */
     406
     407} HGCMMsgCmdSetFilter;
    382408
    383409/**
    … …  
    385411 * waits which were not processed yet.  This is handy for a graceful shutdown.
    386412 */
    387 typedef struct VBoxGuestCtrlHGCMMsgCancelPendingWaits
    388 {
    389     VBoxGuestHGCMCallInfo hdr;
    390 } VBoxGuestCtrlHGCMMsgCancelPendingWaits;
     413typedef struct HGCMMsgCancelPendingWaits
     414{
     415    VBoxGuestHGCMCallInfo hdr;
     416} HGCMMsgCancelPendingWaits;
     417
     418/**
     419 * Creates a guest session.
     420 */
     421typedef struct HGCMMsgSessionOpen
     422{
     423    VBoxGuestHGCMCallInfo hdr;
     424    /** Context ID. */
     425    HGCMFunctionParameter context;
     426    /** The guest control protocol version this
     427     *  session is about to use. */
     428    HGCMFunctionParameter protocol;
     429    /** The user name to run the guest session under. */
     430    HGCMFunctionParameter username;
     431    /** The user's password. */
     432    HGCMFunctionParameter password;
     433    /** The domain to run the guest session under. */
     434    HGCMFunctionParameter domain;
     435    /** Session creation flags. */
     436    HGCMFunctionParameter flags;
     437} HGCMMsgSessionOpen;
     438
     439/**
     440 * Terminates (closes) a guest session.
     441 */
     442typedef struct HGCMMsgSessionClose
     443{
     444    VBoxGuestHGCMCallInfo hdr;
     445    /** Context ID. */
     446    HGCMFunctionParameter context;
     447    /** Session termination flags. */
     448    HGCMFunctionParameter flags;
     449} HGCMMsgSessionClose;
     450
     451/**
     452 * Reports back a guest session's status.
     453 */
     454typedef struct HGCMMsgSessionNotify
     455{
     456    VBoxGuestHGCMCallInfo hdr;
     457    /** Context ID. */
     458    HGCMFunctionParameter context;
     459    /** Notification type. */
     460    HGCMFunctionParameter type;
     461    /** Notification result. */
     462    HGCMFunctionParameter result;
     463} HGCMMsgSessionNotify;
    391464
    392465/**
    393466 * Executes a command inside the guest.
    394467 */
    395 typedef struct VBoxGuestCtrlHGCMMsgExecCmd
     468typedef struct HGCMMsgProcExec
    396469{
    397470    VBoxGuestHGCMCallInfo hdr;
    … …  
    412485    /** The actual environment block. */
    413486    HGCMFunctionParameter env;
    414     /** The user name to run the executed command under. */
    415     HGCMFunctionParameter username;
    416     /** The user's password. */
    417     HGCMFunctionParameter password;
    418     /** Timeout (in msec) which either specifies the
    419      *  overall lifetime of the process or how long it
    420      *  can take to bring the process up and running -
    421      *  (depends on the IGuest::ProcessCreateFlag_*). */
    422     HGCMFunctionParameter timeout;
    423 
    424 } VBoxGuestCtrlHGCMMsgExecCmd;
    425 
    426 /**
    427  * Injects input to a previously executed process via stdin.
    428  */
    429 typedef struct VBoxGuestCtrlHGCMMsgExecIn
     487    union
     488    {
     489        struct
     490        {
     491            /** The user name to run the executed command under.
     492             *  Only for VBox < 4.3 hosts. */
     493            HGCMFunctionParameter username;
     494            /** The user's password.
     495             *  Only for VBox < 4.3 hosts. */
     496            HGCMFunctionParameter password;
     497            /** Timeout (in msec) which either specifies the
     498             *  overall lifetime of the process or how long it
     499             *  can take to bring the process up and running -
     500             *  (depends on the IGuest::ProcessCreateFlag_*). */
     501            HGCMFunctionParameter timeout;
     502        } v1;
     503        struct
     504        {
     505            /** Timeout (in msec) which either specifies the
     506             *  overall lifetime of the process or how long it
     507             *  can take to bring the process up and running -
     508             *  (depends on the IGuest::ProcessCreateFlag_*). */
     509            HGCMFunctionParameter timeout;
     510            /** Process priority. */
     511            HGCMFunctionParameter priority;
     512            /** Number of process affinity blocks. */
     513            HGCMFunctionParameter num_affinity;
     514            /** Pointer to process affinity blocks (uint64_t). */
     515            HGCMFunctionParameter affinity;
     516        } v2;
     517    } u;
     518
     519} HGCMMsgProcExec;
     520
     521/**
     522 * Sends input to a guest process via stdin.
     523 */
     524typedef struct HGCMMsgProcInput
    430525{
    431526    VBoxGuestHGCMCallInfo hdr;
    … …  
    441536    HGCMFunctionParameter size;
    442537
    443 } VBoxGuestCtrlHGCMMsgExecIn;
     538} HGCMMsgProcInput;
    444539
    445540/**
    … …  
    447542 * from stdout/stderr.
    448543 */
    449 typedef struct VBoxGuestCtrlHGCMMsgExecOut
     544typedef struct HGCMMsgProcOutput
    450545{
    451546    VBoxGuestHGCMCallInfo hdr;
    … …  
    461556    HGCMFunctionParameter data;
    462557
    463 } VBoxGuestCtrlHGCMMsgExecOut;
    464 
    465 /**
    466  * Reports the current status of a (just) started
    467  * or terminated process.
    468  */
    469 typedef struct VBoxGuestCtrlHGCMMsgExecStatus
     558} HGCMMsgProcOutput;
     559
     560/**
     561 * Reports the current status of a guest process.
     562 */
     563typedef struct HGCMMsgProcStatus
    470564{
    471565    VBoxGuestHGCMCallInfo hdr;
    … …  
    481575    HGCMFunctionParameter data;
    482576
    483 } VBoxGuestCtrlHGCMMsgExecStatus;
     577} HGCMMsgProcStatus;
    484578
    485579/**
    486580 * Reports back the status of data written to a process.
    487581 */
    488 typedef struct VBoxGuestCtrlHGCMMsgExecStatusIn
     582typedef struct HGCMMsgProcStatusInput
    489583{
    490584    VBoxGuestHGCMCallInfo hdr;
    … …  
    500594    HGCMFunctionParameter written;
    501595
    502 } VBoxGuestCtrlHGCMMsgExecStatusIn;
     596} HGCMMsgProcStatusInput;
    503597
    504598/*
    … …  
    507601
    508602/**
    509  * Reports back the currente I/O status of a guest process.
    510  */
    511 typedef struct VBoxGuestCtrlHGCMMsgExecIONotify
    512 {
    513     VBoxGuestHGCMCallInfo hdr;
    514     /** Context ID. */
    515     HGCMFunctionParameter context;
    516     /** Data written. */
    517     HGCMFunctionParameter written;
    518 
    519 } VBoxGuestCtrlHGCMMsgExecIONotify;
     603 * Terminates a guest process.
     604 */
     605typedef struct HGCMMsgProcTerminate
     606{
     607    VBoxGuestHGCMCallInfo hdr;
     608    /** Context ID. */
     609    HGCMFunctionParameter context;
     610    /** The process ID (PID). */
     611    HGCMFunctionParameter pid;
     612
     613} HGCMMsgProcTerminate;
     614
     615/**
     616 * Waits for certain events to happen.
     617 */
     618typedef struct HGCMMsgProcWaitFor
     619{
     620    VBoxGuestHGCMCallInfo hdr;
     621    /** Context ID. */
     622    HGCMFunctionParameter context;
     623    /** The process ID (PID). */
     624    HGCMFunctionParameter pid;
     625    /** Wait (event) flags. */
     626    HGCMFunctionParameter flags;
     627    /** Timeout (in ms). */
     628    HGCMFunctionParameter timeout;
     629
     630} HGCMMsgProcWaitFor;
    520631
    521632/**
    522633 * Opens a guest file.
    523634 */
    524 typedef struct VBoxGuestCtrlHGCMMsgFileOpen
    525 {
    526     VBoxGuestHGCMCallInfo hdr;
    527     /** Context ID. */
    528     HGCMFunctionParameter context;
    529     /** File to open. */
     635typedef struct HGCMMsgFileOpen
     636{
     637    VBoxGuestHGCMCallInfo hdr;
     638    /** UInt32: Context ID. */
     639    HGCMFunctionParameter context;
     640    /** String: File to open. */
    530641    HGCMFunctionParameter filename;
    531     /** Open mode. */
     642    /** String: Open mode. */
    532643    HGCMFunctionParameter openmode;
    533     /** Disposition. */
     644    /** String: Disposition. */
    534645    HGCMFunctionParameter disposition;
    535     /** Creation mode. */
     646    /** UInt32: Creation mode. */
    536647    HGCMFunctionParameter creationmode;
    537     /** Offset. */
     648    /** UInt64: Initial offset. */
    538649    HGCMFunctionParameter offset;
    539650
    540 } VBoxGuestCtrlHGCMMsgFileOpen;
     651} HGCMMsgFileOpen;
    541652
    542653/**
    543654 * Closes a guest file.
    544655 */
    545 typedef struct VBoxGuestCtrlHGCMMsgFileClose
     656typedef struct HGCMMsgFileClose
    546657{
    547658    VBoxGuestHGCMCallInfo hdr;
    … …  
    551662    HGCMFunctionParameter handle;
    552663
    553 } VBoxGuestCtrlHGCMMsgFileClose;
     664} HGCMMsgFileClose;
    554665
    555666/**
    556667 * Reads from a guest file.
    557668 */
    558 typedef struct VBoxGuestCtrlHGCMMsgFileRead
     669typedef struct HGCMMsgFileRead
    559670{
    560671    VBoxGuestHGCMCallInfo hdr;
    … …  
    568679    HGCMFunctionParameter data;
    569680
    570 } VBoxGuestCtrlHGCMMsgFileRead;
     681} HGCMMsgFileRead;
     682
     683/**
     684 * Reads at a specified offset from a guest file.
     685 */
     686typedef struct HGCMMsgFileReadAt
     687{
     688    VBoxGuestHGCMCallInfo hdr;
     689    /** Context ID. */
     690    HGCMFunctionParameter context;
     691    /** File handle to read from. */
     692    HGCMFunctionParameter handle;
     693    /** Offset where to start reading from. */
     694    HGCMFunctionParameter offset;
     695    /** Actual size of data (in bytes). */
     696    HGCMFunctionParameter size;
     697    /** Where to put the read data into. */
     698    HGCMFunctionParameter data;
     699
     700} HGCMMsgFileReadAt;
    571701
    572702/**
    573703 * Writes to a guest file.
    574704 */
    575 typedef struct VBoxGuestCtrlHGCMMsgFileWrite
     705typedef struct HGCMMsgFileWrite
    576706{
    577707    VBoxGuestHGCMCallInfo hdr;
    … …  
    585715    HGCMFunctionParameter data;
    586716
    587 } VBoxGuestCtrlHGCMMsgFileWrite;
     717} HGCMMsgFileWrite;
     718
     719/**
     720 * Writes at a specified offset to a guest file.
     721 */
     722typedef struct HGCMMsgFileWriteAt
     723{
     724    VBoxGuestHGCMCallInfo hdr;
     725    /** Context ID. */
     726    HGCMFunctionParameter context;
     727    /** File handle to write to. */
     728    HGCMFunctionParameter handle;
     729    /** Offset where to start reading from. */
     730    HGCMFunctionParameter offset;
     731    /** Actual size of data (in bytes). */
     732    HGCMFunctionParameter size;
     733    /** Data buffer to write to the file. */
     734    HGCMFunctionParameter data;
     735
     736} HGCMMsgFileWriteAt;
    588737
    589738/**
    590739 * Seeks the read/write position of a guest file.
    591740 */
    592 typedef struct VBoxGuestCtrlHGCMMsgFileSeek
     741typedef struct HGCMMsgFileSeek
    593742{
    594743    VBoxGuestHGCMCallInfo hdr;
    … …  
    602751    HGCMFunctionParameter offset;
    603752
    604 } VBoxGuestCtrlHGCMMsgFileSeek;
     753} HGCMMsgFileSeek;
    605754
    606755/**
    607756 * Tells the current read/write position of a guest file.
    608757 */
    609 typedef struct VBoxGuestCtrlHGCMMsgFileTell
     758typedef struct HGCMMsgFileTell
    610759{
    611760    VBoxGuestHGCMCallInfo hdr;
    … …  
    615764    HGCMFunctionParameter handle;
    616765
    617 } VBoxGuestCtrlHGCMMsgFileTell;
    618 
    619 typedef struct VBoxGuestCtrlHGCMMsgFileNotify
    620 {
    621     VBoxGuestHGCMCallInfo hdr;
    622     /** Context ID. */
    623     HGCMFunctionParameter context;
    624     /** The file handle. */
    625     HGCMFunctionParameter handle;
     766} HGCMMsgFileTell;
     767
     768typedef struct HGCMMsgFileNotify
     769{
     770    VBoxGuestHGCMCallInfo hdr;
     771    /** Context ID. */
     772    HGCMFunctionParameter context;
    626773    /** Notification type. */
    627774    HGCMFunctionParameter type;
    … …  
    629776    HGCMFunctionParameter payload;
    630777
    631 } VBoxGuestCtrlHGCMMsgFileNotify;
     778} HGCMMsgFileNotify;
    632779
    633780#pragma pack ()
    634781
    635 /**
    636  * Structure for buffering execution requests in the host service.
    637  */
    638 typedef struct VBoxGuestCtrlParamBuffer
    639 {
    640     uint32_t uMsg;
    641     uint32_t uParmCount;
    642     PVBOXHGCMSVCPARM pParms;
    643 } VBOXGUESTCTRPARAMBUFFER;
    644 typedef VBOXGUESTCTRPARAMBUFFER *PVBOXGUESTCTRPARAMBUFFER;
     782/******************************************************************************
     783* Callback data structures.                                                   *
     784******************************************************************************/
     785
     786/**
     787 * The guest control callback data header. Must come first
     788 * on each callback structure defined below this struct.
     789 */
     790typedef struct CALLBACKDATA_HEADER
     791{
     792    /** Context ID to identify callback data. This is
     793     *  and *must* be the very first parameter in this
     794     *  structure to still be backwards compatible. */
     795    uint32_t uContextID;
     796} CALLBACKDATA_HEADER, *PCALLBACKDATA_HEADER;
     797
     798/*
     799 * These structures make up the actual low level HGCM callback data sent from
     800 * the guest back to the host.
     801 */
     802
     803typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
     804{
     805    /** Callback data header. */
     806    CALLBACKDATA_HEADER hdr;
     807} CALLBACKDATA_CLIENT_DISCONNECTED, *PCALLBACKDATA_CLIENT_DISCONNECTED;
     808
     809typedef struct CALLBACKDATA_SESSION_NOTIFY
     810{
     811    /** Callback data header. */
     812    CALLBACKDATA_HEADER hdr;
     813    /** Notification type. */
     814    uint32_t uType;
     815    /** Notification result. */
     816    uint32_t uResult;
     817} CALLBACKDATA_SESSION_NOTIFY, *PCALLBACKDATA_SESSION_NOTIFY;
     818
     819typedef struct CALLBACKDATA_PROC_STATUS
     820{
     821    /** Callback data header. */
     822    CALLBACKDATA_HEADER hdr;
     823    /** The process ID (PID). */
     824    uint32_t uPID;
     825    /** The process status. */
     826    uint32_t uStatus;
     827    /** Optional flags, varies, based on u32Status. */
     828    uint32_t uFlags;
     829    /** Optional data buffer (not used atm). */
     830    void *pvData;
     831    /** Size of optional data buffer (not used atm). */
     832    uint32_t cbData;
     833} CALLBACKDATA_PROC_STATUS, *PCALLBACKDATA_PROC_STATUS;
     834
     835typedef struct CALLBACKDATA_PROC_OUTPUT
     836{
     837    /** Callback data header. */
     838    CALLBACKDATA_HEADER hdr;
     839    /** The process ID (PID). */
     840    uint32_t uPID;
     841    /** The handle ID (stdout/stderr). */
     842    uint32_t uHandle;
     843    /** Optional flags (not used atm). */
     844    uint32_t uFlags;
     845    /** Optional data buffer. */
     846    void *pvData;
     847    /** Size (in bytes) of optional data buffer. */
     848    uint32_t cbData;
     849} CALLBACKDATA_PROC_OUTPUT, *PCALLBACKDATA_PROC_OUTPUT;
     850
     851typedef struct CALLBACKDATA_PROC_INPUT
     852{
     853    /** Callback data header. */
     854    CALLBACKDATA_HEADER hdr;
     855    /** The process ID (PID). */
     856    uint32_t uPID;
     857    /** Current input status. */
     858    uint32_t uStatus;
     859    /** Optional flags. */
     860    uint32_t uFlags;
     861    /** Size (in bytes) of processed input data. */
     862    uint32_t uProcessed;
     863} CALLBACKDATA_PROC_INPUT, *PCALLBACKDATA_PROC_INPUT;
     864
     865typedef struct CALLBACKDATA_FILE_NOTIFY
     866{
     867    /** Callback data header. */
     868    CALLBACKDATA_HEADER hdr;
     869    /** The file handle. */
     870    uint32_t uHandle;
     871} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
     872
     873/******************************************************************************
     874* Callback payload structures.                                                *
     875******************************************************************************/
     876
     877/*
     878 * These structures contain the actual payload, based of the given payload
     879 * type the HGCM message includes.
     880 */
     881
     882typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_OPEN
     883{
     884    /** IPRT result of overall operation. */
     885    int32_t rc;
     886    /** File handle on successful opening. */
     887    uint32_t uHandle;
     888} CALLBACKPAYLOAD_FILE_NOTFIY_OPEN, *PCALLBACKPAYLOAD_FILE_NOTFIY_OPEN;
     889
     890typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_CLOSE
     891{
     892    /** IPRT result of overall operation. */
     893    int32_t rc;
     894} CALLBACKPAYLOAD_FILE_NOTFIY_CLOSE, *PCALLBACKPAYLOAD_FILE_NOTFIY_CLOSE;
     895
     896typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_READ
     897{
     898    /** IPRT result of overall operation. */
     899    int32_t rc;
     900    /** How much data (in bytes) have been read. */
     901    uint32_t cbData;
     902    /** Actual data read (if any). */
     903    void *pvData;
     904} CALLBACKPAYLOAD_FILE_NOTFIY_READ, *PCALLBACKPAYLOAD_FILE_NOTFIY_READ;
     905
     906typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_WRITE
     907{
     908    /** IPRT result of overall operation. */
     909    int32_t rc;
     910    /** How much data (in bytes) have been successfully written. */
     911    uint32_t cbWritten;
     912} CALLBACKPAYLOAD_FILE_NOTFIY_WRITE, *PCALLBACKPAYLOAD_FILE_NOTFIY_WRITE;
     913
     914typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_SEEK
     915{
     916    /** IPRT result of overall operation. */
     917    int32_t rc;
     918    /** New file offset after successful seek. */
     919    uint64_t uOffActual;
     920} CALLBACKPAYLOAD_FILE_NOTFIY_SEEK, *PCALLBACKPAYLOAD_FILE_NOTFIY_SEEK;
     921
     922typedef struct CALLBACKPAYLOAD_FILE_NOTFIY_TELL
     923{
     924    /** IPRT result of overall operation. */
     925    int32_t rc;
     926    /** Current file offset after successful tell. */
     927    uint64_t uOffActual;
     928} CALLBACKPAYLOAD_FILE_NOTFIY_TELL, *PCALLBACKPAYLOAD_FILE_NOTFIY_TELL;
    645929
    646930} /* namespace guestControl */
Note: See TracChangeset for help on using the changeset viewer.

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