VirtualBox

source: vbox/trunk/src/VBox/Main/include/hgcm/HGCMThread.h@ 28973

Last change on this file since 28973 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

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