VBoxGuestR3LibGuestCtrl.cpp revision 9eea21d61089fe62b80ef3f4549600091c2b1967
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * VBoxGuestR3Lib - Ring-3 Support Library for VirtualBox guest additions, guest control.
e64031e20c39650a7bc902a3e1aba613b9415deevboxsync * Copyright (C) 2010 Oracle Corporation
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * available from http://www.virtualbox.org. This file is free software;
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * you can redistribute it and/or modify it under the terms of the GNU
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * General Public License (GPL) as published by the Free Software
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * The contents of this file may alternatively be used under the terms
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * of the Common Development and Distribution License Version 1.0
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * VirtualBox OSE distribution, in which case the provisions of the
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * CDDL are applicable instead of those of the GPL.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * You may elect to license modified versions of this file under the
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * terms and conditions of either the GPL or the CDDL or both.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync/*******************************************************************************
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync* Header Files *
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync*******************************************************************************/
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync/*******************************************************************************
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync* Structures and Typedefs *
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync*******************************************************************************/
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsyncusing namespace guestControl;
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * Connects to the guest control service.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @returns VBox status code
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param pu32ClientId Where to put the client id on success. The client id
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * must be passed to all the other calls to the service.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlConnect(uint32_t *pu32ClientId)
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync strcpy(Info.Loc.u.host.achName, "VBoxGuestControlSvc");
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync Info.u32ClientID = UINT32_MAX; /* try make valgrid shut up. */
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CONNECT, &Info, sizeof(Info));
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * Disconnect from the guest control service.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @returns VBox status code.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlDisconnect(uint32_t u32ClientId)
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_DISCONNECT, &Info, sizeof(Info));
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * Gets a host message.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * This will block until a message becomes available.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @returns VBox status code.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param puMsg Where to store the message id.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param puNumParms Where to store the number of parameters which will be received
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * in a second call to the host.
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsyncVBGLR3DECL(int) VbglR3GuestCtrlGetHostMsg(uint32_t u32ClientId, uint32_t *puMsg, uint32_t *puNumParms)
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puNumParms, VERR_INVALID_PARAMETER);
ed24120b1d8a2eddf4291a9654cf45b2372135abvboxsync Msg.hdr.u32Function = GUEST_GET_HOST_MSG; /* Tell the host we want our next command. */
ed24120b1d8a2eddf4291a9654cf45b2372135abvboxsync Msg.hdr.cParms = 2; /* Just peek for the next message! */
ed24120b1d8a2eddf4291a9654cf45b2372135abvboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
5d69af51557e9e9db029ecd243e820383af49b18vboxsync rc = VbglHGCMParmUInt32Get(&Msg.num_parms, puNumParms);
5d69af51557e9e9db029ecd243e820383af49b18vboxsync /* Ok, so now we know what message type and how much parameters there are. */
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsync * Asks the host to cancel (release) all pending waits which were deferred.
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsync * @returns VBox status code.
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsyncVBGLR3DECL(int) VbglR3GuestCtrlCancelPendingWaits(uint32_t u32ClientId)
4d8251400411b4dcf2c86b5b0376a326ff45938cvboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * Allocates and gets host data, based on the message id.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * This will block until data becomes available.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @returns VBox status code.
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
468c2bcb36eb9a032f5dd0fcb34db10bd58e9996vboxsync * @param uNumParms
de210ca38246009981a22de928a52566c8c53970vboxsync ** @todo Docs!
68e97031354932600728a42c3d454abf04f8c8d1vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecGetHostCmd(uint32_t u32ClientId, uint32_t uNumParms,
68e97031354932600728a42c3d454abf04f8c8d1vboxsync char *pszArgs, uint32_t cbArgs, uint32_t *puNumArgs,
68e97031354932600728a42c3d454abf04f8c8d1vboxsync char *pszEnv, uint32_t *pcbEnv, uint32_t *puNumEnvVars,
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puContext, VERR_INVALID_PARAMETER);
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puNumArgs, VERR_INVALID_PARAMETER);
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puNumEnvVars, VERR_INVALID_PARAMETER);
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(pszPassword, VERR_INVALID_PARAMETER);
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puTimeLimit, VERR_INVALID_PARAMETER);
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync VbglHGCMParmPtrSet(&Msg.username, pszUser, cbUser);
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync VbglHGCMParmPtrSet(&Msg.password, pszPassword, cbPassword);
ba8183e1a0c699f5b5131a03e157fc7e39ed3009vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * Allocates and gets host data, based on the message id.
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * This will block until data becomes available.
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * @returns VBox status code.
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * @param uNumParms
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync ** @todo Docs!
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecGetHostCmdOutput(uint32_t u32ClientId, uint32_t uNumParms,
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puContext, VERR_INVALID_PARAMETER);
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * Retrieves the input data from host which then gets sent to the
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * started process.
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * This will block until data becomes available.
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * @returns VBox status code.
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * @param u32ClientId The client id returned by VbglR3GuestCtrlConnect().
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * @param uNumParms
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync ** @todo Docs!
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecGetHostCmdInput(uint32_t u32ClientId, uint32_t uNumParms,
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync AssertPtrReturn(puContext, VERR_INVALID_PARAMETER);
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
de210ca38246009981a22de928a52566c8c53970vboxsync * Reports the process status (along with some other stuff) to the host.
de210ca38246009981a22de928a52566c8c53970vboxsync * @returns VBox status code.
de210ca38246009981a22de928a52566c8c53970vboxsync ** @todo Docs!
f8df398d066204e2bf0ba209ea3554fc113fb484vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecReportStatus(uint32_t u32ClientId,
de210ca38246009981a22de928a52566c8c53970vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * Sends output (from stdout/stderr) from a running process.
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync * @returns VBox status code.
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync ** @todo Docs!
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecSendOut(uint32_t u32ClientId,
817d003403ed9395143bd4ba88fbd9cb60e5eeebvboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * Reports back the input status to the host.
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync * @returns VBox status code.
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync ** @todo Docs!
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsyncVBGLR3DECL(int) VbglR3GuestCtrlExecReportStatusIn(uint32_t u32ClientId,
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync Msg.hdr.u32Function = GUEST_EXEC_SEND_INPUT_STATUS;
9eea21d61089fe62b80ef3f4549600091c2b1967vboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_HGCM_CALL(sizeof(Msg)), &Msg, sizeof(Msg));