Intravision/reactos
1
0
Fork 0
mirror of https://github.com/reactos/reactos.git synced 2025-01-01 03:54:02 +00:00
Code Issues Projects Releases Packages Wiki Activity

[AUDIT]

Browse source 
- Add proper function headers, including links to publically-available documentation
- One internal function is subject to further review/audit

svn path=/trunk/; revision=22672
This commit is contained in:
Aleksey Bragin 2006-06-28 13:53:30 +00:00
parent 6ef4e4d9d4
commit 981fde0f9f
1 changed files with 363 additions and 354 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
reactos/ntoskrnl/ex/callback.c
View file

@ -1,9 +1,10 @@
/*
* COPYRIGHT: See COPYING in the top level directory
* PROJECT: ReactOS kernel
* PROJECT: ReactOS Kernel
* LICENSE: GPL - See COPYING in the top level directory
* FILE: ntoskrnl/ex/callback.c
* PURPOSE: Executive callbacks
* PROGRAMMERS: Alex Ionescu (alex@relsoft.net)
* PROGRAMMERS: Filip Navara
* Alex Ionescu (alex@relsoft.net)
*/
/* INCLUDES *****************************************************************/
@ -63,21 +64,20 @@ KEVENT ExpCallbackEvent;
/* FUNCTIONS *****************************************************************/
/*
* ExpInitializeCallbacks
/*++
* @name ExpInitializeCallbacks
*
* FUNCTION:
* Creates the Callback Object as a valid Object Type in the Kernel.
* Internal function, subject to further review
*
* ARGUMENTS:
* None
* @return TRUE if the Callback Object Type was successfully created.
*
* RETURNS:
* TRUE if the Callback Object Type was successfully created.
*/
* @remarks None
*
*--*/
VOID
INIT_FUNCTION
STDCALL
NTAPI
ExpInitializeCallbacks(VOID)
{
OBJECT_ATTRIBUTES ObjectAttributes;
@ -165,34 +165,40 @@ ExpInitializeCallbacks(VOID)
/* Everything successful */
}
/*
* ExCreateCallback
/*++
* @name ExCreateCallback
* @implemented
*
* FUNCTION:
* Opens or creates a Callback Object. Creates only if Create is true.
* Allows multiple Callback Functions to be registred only if AllowMultipleCallbacks
* is true.
* Allows multiple Callback Functions to be registred only if
* AllowMultipleCallbacks is true.
* See: http://www.osronline.com/ddkx/kmarch/k102_967m.htm
* http://www.osronline.com/article.cfm?id=24
*
* ARGUMENTS:
* CallbackObject = Pointer that will receive the Callback Object.
* CallbackName = Name of Callback
* Create = Determines if the object will be created if it doesn't exit
* AllowMultipleCallbacks = Determines if more then one registered callback function
* @param CallbackObject
* Pointer that will receive the Callback Object.
*
* @param CallbackName
* Name of Callback
*
* @param Create
* Determines if the object will be created if it doesn't exit
*
* @param AllowMultipleCallbacks
* Determines if more then one registered callback function
* can be attached to this Callback Object.
*
* RETURNS:
* STATUS_SUCESS if not failed.
* @return STATUS_SUCESS if not failed.
*
* @implemented
*/
* @remarks Must be called at IRQL = PASSIVE_LEVEL
*
*--*/
NTSTATUS
STDCALL
ExCreateCallback(
OUT PCALLBACK_OBJECT *CallbackObject,
NTAPI
ExCreateCallback(OUT PCALLBACK_OBJECT *CallbackObject,
IN POBJECT_ATTRIBUTES ObjectAttributes,
IN BOOLEAN Create,
IN BOOLEAN AllowMultipleCallbacks
)
IN BOOLEAN AllowMultipleCallbacks)
{
PCALLBACK_OBJECT Callback;
NTSTATUS Status;
@ -235,8 +241,8 @@ ExCreateCallback(
KeInitializeSpinLock(&Callback->Lock); /* SpinLock */
InitializeListHead(&Callback->RegisteredCallbacks); /* Callback Entries */
Callback->AllowMultipleCallbacks = AllowMultipleCallbacks; /* Multiple Callbacks */
Status = ObInsertObject ( /* Create the object */
Callback,
/* Create the object */
Status = ObInsertObject(Callback,
NULL,
FILE_READ_DATA,
0,
@ -244,18 +250,16 @@ ExCreateCallback(
&Handle );
}
}
if(NT_SUCCESS(Status))
{
/* Get a pointer to the new object from the handle we just got */
Status = ObReferenceObjectByHandle (
Handle,
Status = ObReferenceObjectByHandle(Handle,
0,
ExCallbackObjectType,
KernelMode,
(PVOID)&Callback,
NULL
);
NULL);
/* Close the Handle, since we now have the pointer */
ZwClose(Handle);
}
@ -268,29 +272,34 @@ ExCreateCallback(
return Status;
}
/*
* ExNotifyCallback
*
* FUNCTION:
* Calls a function pointer (a registered callback)
*
* ARGUMENTS:
* CallbackObject - Which callback to call
* Argument1 - Pointer/data to send to callback function
* Argument2 - Pointer/data to send to callback function
*
* RETURNS:
* Nothing
*
/*++
* @name ExNotifyCallback
* @implemented
*/
*
* Calls a function pointer (a registered callback)
* See: http://www.osronline.com/ddkx/kmarch/k102_2f5e.htm
* http://msdn.microsoft.com/library/en-us/Kernel_d/hh/Kernel_d/Synchro_e954f515-e536-4e12-8419-e7e54c4a963b.xml.asp?frame=true
* http://vmsone.com/~decuslib/vmssig/vmslt99b/nt/wdm-callback.txt
*
* @param CallbackObject
* Which callback to call
*
* @param Argument1
* Pointer/data to send to callback function
*
* @param Argument2
* Pointer/data to send to callback function
*
* @return None
*
* @remarks None
*
*--*/
VOID
STDCALL
ExNotifyCallback(
IN PCALLBACK_OBJECT OpaqueCallbackObject,
NTAPI
ExNotifyCallback(IN PCALLBACK_OBJECT OpaqueCallbackObject,
IN PVOID Argument1,
IN PVOID Argument2
)
IN PVOID Argument2)
{
PCALLBACK_OBJECT CallbackObject = (PCALLBACK_OBJECT)OpaqueCallbackObject;
PLIST_ENTRY RegisteredCallbacks;
@ -305,7 +314,6 @@ ExNotifyCallback(
RegisteredCallbacks != &CallbackObject->RegisteredCallbacks;
RegisteredCallbacks = RegisteredCallbacks->Flink)
{
/* Get a pointer to a Callback Registration from the List Entries */
CallbackRegistration = CONTAINING_RECORD(RegisteredCallbacks,
CALLBACK_REGISTRATION,
@ -314,7 +322,6 @@ ExNotifyCallback(
/* Don't bother doing Callback Notification if it's pending to be deleted */
if (!CallbackRegistration->PendingDeletion)
{
/* Mark the Callback in use, so it won't get deleted while we are calling it */
CallbackRegistration->InUse += 1;
@ -345,31 +352,34 @@ ExNotifyCallback(
KfReleaseSpinLock(&CallbackObject->Lock, OldIrql);
}
/*
* ExRegisterCallback
*
* FUNCTION:
* Allows a function to associate a callback pointer (Function)
* to a created Callback object
*
* ARGUMENTS:
* CallbackObject = The Object Created with ExCreateCallBack
* CallBackFunction = Pointer to the function to be called back
* CallBackContext = Block of memory that can contain user-data
* which will be passed on to the callback
*
* RETURNS:
* A handle to a Callback Registration Structure (MSDN Documentation)
*
/*++
* @name ExRegisterCallback
* @implemented
*/
*
* Allows a function to associate a callback pointer (Function) to
* a created Callback object
* See: DDK, OSR, links in ExNotifyCallback
*
* @param CallbackObject
* The Object Created with ExCreateCallBack
*
* @param CallBackFunction
* Pointer to the function to be called back
*
* @param CallBackContext
* Block of memory that can contain user-data which will be
* passed on to the callback
*
* @return A handle to a Callback Registration Structure (MSDN Documentation)
*
* @remarks None
*
*--*/
PVOID
STDCALL
ExRegisterCallback(
IN PCALLBACK_OBJECT OpaqueCallbackObject,
NTAPI
ExRegisterCallback(IN PCALLBACK_OBJECT OpaqueCallbackObject,
IN PCALLBACK_FUNCTION CallbackFunction,
IN PVOID CallbackContext
)
IN PVOID CallbackContext)
{
PCALLBACK_OBJECT CallbackObject = (PCALLBACK_OBJECT)OpaqueCallbackObject;
PCALLBACK_REGISTRATION CallbackRegistration = NULL;
@ -419,24 +429,24 @@ ExRegisterCallback(
return (PVOID)CallbackRegistration;
}
/*
* ExUnregisterCallback
*
* FUNCTION:
* Deregisters a CallBack
*
* ARGUMENTS:
* CallbackRegistration = Callback Registration Handle
*
* RETURNS:
* Nothing
*
/*++
* @name ExUnregisterCallback
* @implemented
*/
VOID STDCALL
ExUnregisterCallback(
IN PVOID CallbackRegistrationHandle
)
*
* Deregisters a CallBack
* See: DDK, OSR, links in ExNotifyCallback
*
* @param CallbackRegistration
* Callback Registration Handle
*
* @return None
*
* @remarks None
*
*--*/
VOID
NTAPI
ExUnregisterCallback(IN PVOID CallbackRegistrationHandle)
{
PCALLBACK_REGISTRATION CallbackRegistration;
PCALLBACK_OBJECT CallbackObject;
@ -456,7 +466,6 @@ ExUnregisterCallback(
/* We can't Delete the Callback if it's in use, because this would create a call towards a null pointer => crash */
while (CallbackRegistration->InUse)
{
/* Similarly, we also don't want to wait ages for all pending callbacks to be called */
CallbackRegistration->PendingDeletion = TRUE;