e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * VBoxGuestR3Lib - Ring-3 Support Library for VirtualBox guest additions, Events.
e64031e20c39650a7bc902a3e1aba613b9415deevboxsync * Copyright (C) 2007-2010 Oracle Corporation
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * available from http://www.virtualbox.org. This file is free software;
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * you can redistribute it and/or modify it under the terms of the GNU
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * General Public License (GPL) as published by the Free Software
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * The contents of this file may alternatively be used under the terms
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * of the Common Development and Distribution License Version 1.0
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * VirtualBox OSE distribution, in which case the provisions of the
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * CDDL are applicable instead of those of the GPL.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * You may elect to license modified versions of this file under the
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * terms and conditions of either the GPL or the CDDL or both.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync/*******************************************************************************
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync* Header Files *
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync*******************************************************************************/
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * Wait for the host to signal one or more events and return which.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * The events will only be delivered by the host if they have been enabled
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * previously using @a VbglR3CtlFilterMask. If one or several of the events
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * have already been signalled but not yet waited for, this function will return
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * immediately and return those events.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * @returns IPRT status code.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * @param fMask The events we want to wait for, or-ed together.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * @param cMillies How long to wait before giving up and returning
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * (VERR_TIMEOUT). Use RT_INDEFINITE_WAIT to wait until we
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * are interrupted or one of the events is signalled.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * @param pfEvents Where to store the events signalled. Optional.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsyncVBGLR3DECL(int) VbglR3WaitEvent(uint32_t fMask, uint32_t cMillies, uint32_t *pfEvents)
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync LogFlow(("VbglR3WaitEvent: fMask=0x%x, cMillies=%u, pfEvents=%p\n",
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync AssertReturn((fMask & ~VMMDEV_EVENT_VALID_EVENT_MASK) == 0, VERR_INVALID_PARAMETER);
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync AssertPtrNullReturn(pfEvents, VERR_INVALID_POINTER);
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync int rc = vbglR3DoIOCtl(VBOXGUEST_IOCTL_WAITEVENT, &waitEvent, sizeof(waitEvent));
d8d9fac6bf94c8283c2c558824b669c66f5ae3f7vboxsync * If a guest requests for an event which is not available on the host side
d8d9fac6bf94c8283c2c558824b669c66f5ae3f7vboxsync * (because of an older host version, a disabled feature or older Guest Additions),
d8d9fac6bf94c8283c2c558824b669c66f5ae3f7vboxsync * don't trigger an assertion here even in debug builds - would be annoying.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync AssertMsg(waitEvent.u32Result == VBOXGUEST_WAITEVENT_OK, ("%d rc=%Rrc\n", waitEvent.u32Result, rc));
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync LogFlow(("VbglR3WaitEvent: rc=%Rrc, u32EventFlagsOut=0x%x. u32Result=%d\n",
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync rc, waitEvent.u32EventFlagsOut, waitEvent.u32Result));
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * Cause any pending WaitEvent calls (VBOXGUEST_IOCTL_WAITEVENT) to return
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * with a VERR_INTERRUPTED status.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * Can be used in combination with a termination flag variable for interrupting
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * event loops. Avoiding race conditions is the responsibility of the caller.
e6660f4933111b0649ffa77483102881f4e75c3bvboxsync * @returns IPRT status code.