3 * Support code to manage HANDLE tables.
5 * Copyright 1998 Alexandre Julliard
6 * Copyright 2002-2004 Mike McCormack for CodeWeavers
7 * Copyright 2004 Michael Jung
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
31 #include "wine/debug.h"
33 WINE_DEFAULT_DEBUG_CHANNEL(handle
);
35 #define HANDLE2INDEX(h) ((h)-1)
36 #define INDEX2HANDLE(i) ((i)+1)
38 /******************************************************************************
41 * Initializes the HANDLETABLE structure pointed to by lpTable
44 * lpTable [I] Pointer to the HANDLETABLE structure, which is to be initalized.
47 * Note that alloc_handle_table calls init_handle_table on it's own, which
48 * means that you only have to call init_handle_table, if you use a global
49 * variable of type HANDLETABLE for your handle table. However, in this
50 * case you have to call destroy_handle_table when you don't need the table
53 void init_handle_table(HANDLETABLE
*lpTable
)
55 TRACE("(lpTable=%p)\n", lpTable
);
57 lpTable
->paEntries
= NULL
;
58 lpTable
->iEntries
= 0;
59 lpTable
->iFirstFree
= 0;
60 InitializeCriticalSection(&lpTable
->mutex
);
63 /******************************************************************************
64 * destroy_handle_table
66 * Destroys the handle table.
69 * lpTable [I] Pointer to the handle table, which is to be destroyed.
72 * Note that release_handle_table takes care of this.
74 void destroy_handle_table(HANDLETABLE
*lpTable
)
76 TRACE("(lpTable=%p)\n", lpTable
);
78 HeapFree(GetProcessHeap(), 0, lpTable
->paEntries
);
79 DeleteCriticalSection(&lpTable
->mutex
);
82 /******************************************************************************
85 * Tests if handle is valid given the specified handle table
88 * lpTable [I] Pointer to the handle table, with respect to which the handle's
89 * validness is tested.
90 * handle [I] The handle tested for validness.
91 * dwType [I] A magic value that identifies the referenced object's type.
94 * non zero, if handle is valid.
95 * zero, if handle is not valid.
97 int is_valid_handle(HANDLETABLE
*lpTable
, unsigned int handle
, DWORD dwType
)
99 unsigned int index
= HANDLE2INDEX(handle
);
102 TRACE("(lpTable=%p, handle=%d)\n", lpTable
, handle
);
104 EnterCriticalSection(&lpTable
->mutex
);
106 /* We don't use zero handle values */
107 if (!handle
) goto exit
;
109 /* Check for index out of table bounds */
110 if (index
>= lpTable
->iEntries
) goto exit
;
112 /* Check if this handle is currently allocated */
113 if (!lpTable
->paEntries
[index
].pObject
) goto exit
;
115 /* Check if this handle references an object of the correct type. */
116 if (lpTable
->paEntries
[index
].pObject
->dwType
!= dwType
) goto exit
;
120 LeaveCriticalSection(&lpTable
->mutex
);
124 /******************************************************************************
125 * release_all_handles
127 * Releases all valid handles in the given handle table and shrinks the table
131 * lpTable [I] The table of which all valid handles shall be released.
133 static void release_all_handles(HANDLETABLE
*lpTable
)
137 TRACE("(lpTable=%p)\n", lpTable
);
139 EnterCriticalSection(&lpTable
->mutex
);
140 for (i
=0; i
<lpTable
->iEntries
; i
++)
141 if (lpTable
->paEntries
[i
].pObject
)
142 release_handle(lpTable
, lpTable
->paEntries
[i
].pObject
->dwType
, INDEX2HANDLE(i
));
143 LeaveCriticalSection(&lpTable
->mutex
);
146 /******************************************************************************
149 * Allocates a new handle table
152 * lplpTable [O] Pointer to the variable, to which the pointer to the newly
153 * allocated handle table is written.
155 * non zero, if successful
156 * zero, if not successful (out of process heap memory)
159 * If all you need is a single handle table, you may as well declare a global
160 * variable of type HANDLETABLE and call init_handle_table on your own.
162 int alloc_handle_table(HANDLETABLE
**lplpTable
)
164 TRACE("(lplpTable=%p)\n", lplpTable
);
166 *lplpTable
= HeapAlloc(GetProcessHeap(), 0, sizeof(HANDLETABLE
));
169 init_handle_table(*lplpTable
);
176 /******************************************************************************
177 * release_handle_table
179 * Releases a handle table and frees the resources it used.
182 * lpTable [I] Pointer to the handle table, which is to be released.
185 * non zero, if successful
186 * zero, if not successful
189 * All valid handles still in the table are released also.
191 int release_handle_table(HANDLETABLE
*lpTable
)
193 TRACE("(lpTable=%p)\n", lpTable
);
195 release_all_handles(lpTable
);
196 destroy_handle_table(lpTable
);
197 return (int)HeapFree(GetProcessHeap(), 0, lpTable
);
200 /******************************************************************************
201 * grow_handle_table [Internal]
203 * Grows the number of entries in the given table by TABLE_SIZE_INCREMENT
206 * lpTable [I] Pointer to the table, which is to be grown
209 * non zero, if successful
210 * zero, if not successful (out of memory on process heap)
213 * This is a support function for alloc_handle. Do not call!
215 static int grow_handle_table(HANDLETABLE
*lpTable
)
217 HANDLETABLEENTRY
*newEntries
;
218 unsigned int i
, newIEntries
;
220 newIEntries
= lpTable
->iEntries
+ TABLE_SIZE_INCREMENT
;
222 newEntries
= HeapAlloc(GetProcessHeap(), 0, sizeof(HANDLETABLEENTRY
)*newIEntries
);
226 if (lpTable
->paEntries
)
228 memcpy(newEntries
, lpTable
->paEntries
, sizeof(HANDLETABLEENTRY
)*lpTable
->iEntries
);
229 HeapFree(GetProcessHeap(), 0, lpTable
->paEntries
);
232 for (i
=lpTable
->iEntries
; i
<newIEntries
; i
++)
234 newEntries
[i
].pObject
= NULL
;
235 newEntries
[i
].iNextFree
= i
+1;
238 lpTable
->paEntries
= newEntries
;
239 lpTable
->iEntries
= newIEntries
;
244 /******************************************************************************
247 * Allocates a new handle to the specified object in a given handle table.
250 * lpTable [I] Pointer to the handle table, from which the new handle is
252 * lpObject [I] Pointer to the object, for which a handle shall be allocated.
253 * lpHandle [O] Pointer to a handle variable, into which the handle value will
254 * be stored. If not successful, this will be
255 * INVALID_HANDLE_VALUE
257 * non zero, if successful
258 * zero, if not successful (no free handle)
260 static int alloc_handle(HANDLETABLE
*lpTable
, OBJECTHDR
*lpObject
, unsigned int *lpHandle
)
264 TRACE("(lpTable=%p, lpObject=%p, lpHandle=%p)\n", lpTable
, lpObject
, lpHandle
);
266 EnterCriticalSection(&lpTable
->mutex
);
267 if (lpTable
->iFirstFree
>= lpTable
->iEntries
)
268 if (!grow_handle_table(lpTable
))
270 *lpHandle
= (unsigned int)INVALID_HANDLE_VALUE
;
274 *lpHandle
= INDEX2HANDLE(lpTable
->iFirstFree
);
276 lpTable
->paEntries
[lpTable
->iFirstFree
].pObject
= lpObject
;
277 lpTable
->iFirstFree
= lpTable
->paEntries
[lpTable
->iFirstFree
].iNextFree
;
278 InterlockedIncrement(&lpObject
->refcount
);
282 LeaveCriticalSection(&lpTable
->mutex
);
286 /******************************************************************************
289 * Releases resources occupied by the specified handle in the given table.
290 * The reference count of the handled object is decremented. If it becomes
291 * zero and if the 'destructor' function pointer member is non NULL, the
292 * destructor function will be called. Note that release_handle does not
293 * release resources other than the handle itself. If this is wanted, do it
294 * in the destructor function.
297 * lpTable [I] Pointer to the handle table, from which a handle is to be
299 * handle [I] The handle, which is to be released
300 * dwType [I] Identifier for the type of the object, for which a handle is
304 * non zero, if successful
305 * zero, if not successful (invalid handle)
307 int release_handle(HANDLETABLE
*lpTable
, unsigned int handle
, DWORD dwType
)
309 unsigned int index
= HANDLE2INDEX(handle
);
313 TRACE("(lpTable=%p, hande=%d)\n", lpTable
, handle
);
315 EnterCriticalSection(&lpTable
->mutex
);
317 if (!is_valid_handle(lpTable
, handle
, dwType
))
320 pObject
= lpTable
->paEntries
[index
].pObject
;
321 if (InterlockedDecrement(&pObject
->refcount
) == 0)
323 TRACE("destroying handle %d\n", handle
);
324 if (pObject
->destructor
)
325 pObject
->destructor(pObject
);
328 lpTable
->paEntries
[index
].pObject
= NULL
;
329 lpTable
->paEntries
[index
].iNextFree
= lpTable
->iFirstFree
;
330 lpTable
->iFirstFree
= index
;
334 LeaveCriticalSection(&lpTable
->mutex
);
338 /******************************************************************************
341 * Returns the object identified by the handle in the given handle table
344 * lpTable [I] Pointer to the handle table, in which the handle is looked up.
345 * handle [I] The handle, which is to be looked up
346 * lplpObject [O] Pointer to the variable, into which the pointer to the
347 * object looked up is copied.
349 * non zero, if successful
350 * zero, if not successful (invalid handle)
352 int lookup_handle(HANDLETABLE
*lpTable
, unsigned int handle
, DWORD dwType
, OBJECTHDR
**lplpObject
)
356 TRACE("(lpTable=%p, handle=%d, lplpObject=%p)\n", lpTable
, handle
, lplpObject
);
358 EnterCriticalSection(&lpTable
->mutex
);
359 if (!is_valid_handle(lpTable
, handle
, dwType
))
364 *lplpObject
= lpTable
->paEntries
[HANDLE2INDEX(handle
)].pObject
;
368 LeaveCriticalSection(&lpTable
->mutex
);
372 /******************************************************************************
375 * Copies a handle. Increments the reference count of the object referenced
379 * lpTable [I] Pointer to the handle table, which holds the handle to be copied.
380 * handle [I] The handle to be copied.
381 * copy [O] Pointer to a handle variable, where the copied handle is put.
384 * non zero, if successful
385 * zero, if not successful (invalid handle or out of memory)
387 int copy_handle(HANDLETABLE
*lpTable
, unsigned int handle
, DWORD dwType
, unsigned int *copy
)
392 TRACE("(lpTable=%p, handle=%d, copy=%p)\n", lpTable
, handle
, copy
);
394 EnterCriticalSection(&lpTable
->mutex
);
395 if (!lookup_handle(lpTable
, handle
, dwType
, &pObject
))
397 *copy
= (unsigned int)INVALID_HANDLE_VALUE
;
398 LeaveCriticalSection(&lpTable
->mutex
);
402 ret
= alloc_handle(lpTable
, pObject
, copy
);
403 LeaveCriticalSection(&lpTable
->mutex
);
407 /******************************************************************************
410 * Allocates a new object of size cbSize on the current process's heap.
411 * Initializes the object header using the destructor and dwType params.
412 * Allocates a handle to the object in the handle table pointed to by lpTable.
413 * Returns a pointer to the created object in ppObject.
414 * Returns a handle to the created object.
417 * lpTable [I] Pointer to the handle table, from which a handle is to be
419 * cbSize [I] Size of the object to be allocated in bytes.
420 * dwType [I] Object type; will be copied to the object header.
421 * destructor [I] Function pointer to a destructor function. Will be called
422 * once the object's reference count gets zero.
423 * ppObject [O] Pointer to a pointer variable, where a pointer to the newly
424 * created object will be stored. You may set this to NULL.
427 * INVALID_HANDLE_VALUE, if something went wrong.
428 * a handle to the new object, if successful.
430 unsigned int new_object(HANDLETABLE
*lpTable
, size_t cbSize
, DWORD dwType
, DESTRUCTOR destructor
,
431 OBJECTHDR
**ppObject
)
434 unsigned int hObject
;
439 pObject
= HeapAlloc(GetProcessHeap(), 0, cbSize
);
441 return (unsigned int)INVALID_HANDLE_VALUE
;
443 pObject
->dwType
= dwType
;
444 pObject
->refcount
= 0;
445 pObject
->destructor
= destructor
;
447 if (!alloc_handle(lpTable
, pObject
, &hObject
))
448 HeapFree(GetProcessHeap(), 0, pObject
);