include/hgcm/HGCMThread.h

	HGCMThread.h revision 571c90a734400801da973f986190fac9fc5efd0d
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync/** @file
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync * HGCMThread - Host-Guest Communication Manager worker threads header.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/*
c29fe1f686f1a78237986fbb030e3020cdbbfb77vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
7f8c3a19fc6774798746c0782be09b88e54bf960vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
7f8c3a19fc6774798746c0782be09b88e54bf960vboxsync * available from http://www.virtualbox.org. This file is free software;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * you can redistribute it and/or modify it under the terms of the GNU
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * General Public License (GPL) as published by the Free Software
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * additional information or have any questions.
7d9e0d289e799c0ee5b9307fe7358ddc53bd34ddvboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync#ifndef __HGCMThread_h__
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync#define __HGCMThread_h__
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync#include <VBox/types.h>
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync#include <hgcm/HGCMObjects.h>
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
af1bd0025dd5d8be5f1468689d0d77d4839a3be5vboxsync/** A handle for HGCM message. */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsynctypedef uint32_t HGCMMSGHANDLE;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** A handle for HGCM worker threads. */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsynctypedef uint32_t HGCMTHREADHANDLE;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync/* Forward declaration of message core class. */
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsyncclass HGCMMsgCore;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync/** @todo comment */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsynctypedef HGCMMsgCore *FNHGCMNEWMSGALLOC(uint32_t u32MsgId);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsynctypedef FNHGCMNEWMSGALLOC *PFNHGCMNEWMSGALLOC;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** Function that is called after message processing by worker thread,
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *  or if an error occurred during message handling after successfully
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *  posting (hgcmMsgPost) the message to worker thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param result    Return code either from the service which actually processed the message
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *                  or from HGCM.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pMsgCore  Pointer to just processed message.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsynctypedef DECLCALLBACK(void) HGCMMSGCALLBACK (int32_t result, HGCMMsgCore *pMsgCore);
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsynctypedef HGCMMSGCALLBACK *PHGCMMSGCALLBACK;
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync/* Forward declaration of the worker thread class. */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsyncclass HGCMThread;
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** HGCM core message. */
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsyncclass HGCMMsgCore: public HGCMObject
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync{
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync    private:
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        friend class HGCMThread;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync        /** Version of message header. */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync        uint32_t m_u32Version;
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync        /** Thread the message belongs to, referenced by the message. */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync        HGCMThread *m_pThread;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
be641d8f2dc377d6a4403f3822d8bed08f51e28avboxsync        /** Message number/identifier. */
be641d8f2dc377d6a4403f3822d8bed08f51e28avboxsync        uint32_t m_u32Msg;
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync        /** Callback function pointer. */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync        PHGCMMSGCALLBACK m_pfnCallback;
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        /** Next element in a message queue. */
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync        HGCMMsgCore *m_pNext;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        /** @todo seems not necessary. Previous element in a message queue. */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        HGCMMsgCore *m_pPrev;
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        /** Various internal flags. */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        uint32_t m_fu32Flags;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync        /** Result code for a Send */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        int32_t m_rcSend;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
be641d8f2dc377d6a4403f3822d8bed08f51e28avboxsync        void InitializeCore (uint32_t u32MsgId, HGCMTHREADHANDLE hThread);
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync    protected:
be641d8f2dc377d6a4403f3822d8bed08f51e28avboxsync        virtual ~HGCMMsgCore ();
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync    public:
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        HGCMMsgCore () : HGCMObject(HGCMOBJ_MSG) {};
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        uint32_t MsgId (void) { return m_u32Msg; };
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        HGCMThread *Thread (void) { return m_pThread; };
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsync        /** Initialize message after it was allocated. */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        virtual void Initialize (void) {};
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync        /** Uninitialize message. */
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync        virtual void Uninitialize (void) {};
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync};
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** HGCM worker thread function.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *  @param ThreadHandle  Handle of the thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *  @param pvUser        User specified thread parameter.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsynctypedef DECLCALLBACK(void) FNHGCMTHREAD (HGCMTHREADHANDLE ThreadHandle, void *pvUser);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsynctypedef FNHGCMTHREAD *PFNHGCMTHREAD;
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync/**
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * Thread API.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * Based on thread handles. Internals of a thread are not exposed to users.
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync/** Initialize threads.
e6317c5fa1f3ac24b7d86f42d2b11bcb0733609evboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @return VBox error code
e6317c5fa1f3ac24b7d86f42d2b11bcb0733609evboxsync */
e6317c5fa1f3ac24b7d86f42d2b11bcb0733609evboxsyncint hgcmThreadInit (void);
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsyncvoid hgcmThreadUninit (void);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** Create a HGCM worker thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @param pHandle       Where to store the returned worker thread handle.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pszThreadName Name of the thread, needed by runtime.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pfnThread     The worker thread function.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pvUser        A pointer passed to worker thread.
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync *
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync * @return VBox error code
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync */
295a2ae5a4db2c930f7096c6cf55b5fa4ee5b018vboxsyncint hgcmThreadCreate (HGCMTHREADHANDLE *pHandle, const char *pszThreadName, PFNHGCMTHREAD pfnThread, void *pvUser);
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync/** Wait for termination of a HGCM worker thread.
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync *
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync * @param handle The HGCM thread handle.
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync *
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync * @return VBox error code
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync */
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsyncint hgcmThreadWait (HGCMTHREADHANDLE handle);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** Allocate a message to be posted to HGCM worker thread.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param hThread       Worker thread handle.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pHandle       Where to store the returned message handle.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param u32MsgId      Message identifier.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pfnNewMessage New message allocation callback.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @return VBox error code
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsyncint hgcmMsgAlloc (HGCMTHREADHANDLE hThread, HGCMMSGHANDLE *pHandle, uint32_t u32MsgId, PFNHGCMNEWMSGALLOC pfnNewMessage);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/** Post a message to HGCM worker thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param hMsg          Message handle.
9148e7ca5f9ee1d467112d347bfb2de2b97254d2vboxsync * @param pfnCallback   Message completion callback.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @return VBox error code
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsyncint hgcmMsgPost (HGCMMSGHANDLE hMsg, PHGCMMSGCALLBACK pfnCallback);
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync/** Send a message to HGCM worker thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *  The function will return after message is processed by thread.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync * @param hMsg          Message handle.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @return VBox error code
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsyncint hgcmMsgSend (HGCMMSGHANDLE hMsg);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync/* Wait for and get a message.
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @param hThread       The thread handle.
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param ppMsg         Where to store returned message pointer.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @return VBox error code
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync * @thread worker thread
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsyncint hgcmMsgGet (HGCMTHREADHANDLE hThread, HGCMMsgCore **ppMsg);
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync/** Worker thread has processed a message previuosly obtained with hgcmMsgGet.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @param pMsg          Processed message pointer.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @param result        Result code, VBox erro code.
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync *
1731b00e118d691438a0c8b1f1b4c6e29a0d5bb6vboxsync * @return VBox error code
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync *
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync * @thread worker thread
32ded45b3caba42c8a2315a20bbfabb513fa54c1vboxsync */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsyncvoid hgcmMsgComplete (HGCMMsgCore *pMsg, int32_t result);
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync#endif /* __HGCMThread_h__ */
dc23707aec4dc2ce2c6b6f51af21eef72bb8bf2evboxsync