VirtualBox

source: vbox/trunk/src/VBox/Frontends/VBoxBFE/HGCMThread.h@ 13272

Last change on this file since 13272 was 8155, checked in by vboxsync, 17 years ago

The Big Sun Rebranding Header Change

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.6 KB
Line 
1/** @file
2 *
3 * HGCMThread - Host-Guest Communication Manager worker threads header.
4 */
5
6/*
7 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
18 * Clara, CA 95054 USA or visit http://www.sun.com if you need
19 * additional information or have any questions.
20 */
21
22#ifndef __HGCMThread_h__
23#define __HGCMThread_h__
24
25#include <VBox/types.h>
26
27#include "HGCMObjects.h"
28
29/** A handle for HGCM message. */
30typedef uint32_t HGCMMSGHANDLE;
31
32/** A handle for HGCM worker threads. */
33typedef uint32_t HGCMTHREADHANDLE;
34
35/* Forward declaration of message core class. */
36class HGCMMsgCore;
37
38/** @todo comment */
39
40typedef HGCMMsgCore *FNHGCMNEWMSGALLOC(uint32_t u32MsgId);
41typedef FNHGCMNEWMSGALLOC *PFNHGCMNEWMSGALLOC;
42
43/** Function that is called after message processing by worker thread,
44 * or if an error occured during message handling after successfully
45 * posting (hgcmMsgPost) the message to worker thread.
46 *
47 * @param result Return code either from the service which actually processed the message
48 * or from HGCM.
49 * @param pMsgCore Pointer to just processed message.
50 */
51typedef DECLCALLBACK(void) HGCMMSGCALLBACK (int32_t result, HGCMMsgCore *pMsgCore);
52typedef HGCMMSGCALLBACK *PHGCMMSGCALLBACK;
53
54/* Forward declaration of the worker thread class. */
55class HGCMThread;
56
57/** HGCM core message. */
58class HGCMMsgCore: public HGCMObject
59{
60 private:
61 friend class HGCMThread;
62
63 /** Version of message header. */
64 uint32_t m_u32Version;
65
66 /** Thread the message belongs to, referenced by the message. */
67 HGCMThread *m_pThread;
68
69 /** Message number/identifier. */
70 uint32_t m_u32Msg;
71
72 /** Callback function pointer. */
73 PHGCMMSGCALLBACK m_pfnCallback;
74
75 /** Next element in a message queue. */
76 HGCMMsgCore *m_pNext;
77 /** @todo seems not necessary. Previous element in a message queue. */
78 HGCMMsgCore *m_pPrev;
79
80 /** Various internal flags. */
81 uint32_t m_fu32Flags;
82
83 /** Result code for a Send */
84 int32_t m_rcSend;
85
86 void InitializeCore (uint32_t u32MsgId, HGCMTHREADHANDLE hThread);
87
88 protected:
89 virtual ~HGCMMsgCore ();
90
91 public:
92 HGCMMsgCore () : HGCMObject(HGCMOBJ_MSG) {};
93
94 uint32_t MsgId (void) { return m_u32Msg; };
95
96 HGCMThread *Thread (void) { return m_pThread; };
97
98 /** Initialize message after it was allocated. */
99 virtual void Initialize (void) {};
100
101 /** Uninitialize message. */
102 virtual void Uninitialize (void) {};
103
104};
105
106
107/** HGCM worker thread function.
108 *
109 * @param ThreadHandle Handle of the thread.
110 * @param pvUser User specified thread parameter.
111 */
112typedef DECLCALLBACK(void) FNHGCMTHREAD (HGCMTHREADHANDLE ThreadHandle, void *pvUser);
113typedef FNHGCMTHREAD *PFNHGCMTHREAD;
114
115
116/**
117 * Thread API.
118 * Based on thread handles. Internals of a thread are not exposed to users.
119 */
120
121/** Initialize threads.
122 *
123 * @return VBox error code
124 */
125int hgcmThreadInit (void);
126void hgcmThreadUninit (void);
127
128
129/** Create a HGCM worker thread.
130 *
131 * @param pHandle Where to store the returned worker thread handle.
132 * @param pszThreadName Name of the thread, needed by runtime.
133 * @param pfnThread The worker thread function.
134 * @param pvUser A pointer passed to worker thread.
135 *
136 * @return VBox error code
137 */
138int hgcmThreadCreate (HGCMTHREADHANDLE *pHandle, const char *pszThreadName, PFNHGCMTHREAD pfnThread, void *pvUser);
139
140/** Wait for termination of a HGCM worker thread.
141 *
142 * @param handle The HGCM thread handle.
143 *
144 * @return VBox error code
145 */
146int hgcmThreadWait (HGCMTHREADHANDLE handle);
147
148/** Allocate a message to be posted to HGCM worker thread.
149 *
150 * @param hThread Worker thread handle.
151 * @param pHandle Where to store the returned message handle.
152 * @param u32MsgId Message identifier.
153 * @param pfnNewMessage New message allocation callback.
154 *
155 * @return VBox error code
156 */
157int hgcmMsgAlloc (HGCMTHREADHANDLE hThread, HGCMMSGHANDLE *pHandle, uint32_t u32MsgId, PFNHGCMNEWMSGALLOC pfnNewMessage);
158
159/** Post a message to HGCM worker thread.
160 *
161 * @param hMsg Message handle.
162 * @param pfnCallback Message completion callback.
163 *
164 * @return VBox error code
165 */
166int hgcmMsgPost (HGCMMSGHANDLE hMsg, PHGCMMSGCALLBACK pfnCallback);
167
168/** Send a message to HGCM worker thread.
169 * The function will return after message is processed by thread.
170 *
171 * @param hMsg Message handle.
172 *
173 * @return VBox error code
174 */
175int hgcmMsgSend (HGCMMSGHANDLE hMsg);
176
177
178/* Wait for and get a message.
179 *
180 * @param hThread The thread handle.
181 * @param ppMsg Where to store returned message pointer.
182 *
183 * @return VBox error code
184 *
185 * @thread worker thread
186 */
187int hgcmMsgGet (HGCMTHREADHANDLE hThread, HGCMMsgCore **ppMsg);
188
189
190/** Worker thread has processed a message previuosly obtained with hgcmMsgGet.
191 *
192 * @param pMsg Processed message pointer.
193 * @param result Result code, VBox erro code.
194 *
195 * @return VBox error code
196 *
197 * @thread worker thread
198 */
199void hgcmMsgComplete (HGCMMsgCore *pMsg, int32_t result);
200
201
202#endif /* __HGCMThread_h__ */
Note: See TracBrowser for help on using the repository browser.

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