callback.c File Reference

#include "exp.h"

Go to the source code of this file.

Classes
struct	_CALLBACK_OBJECT
struct	_CALLBACK_REGISTRATION
Defines
#define	CALLBACK_MODIFY_STATE   0x0001
#define	CALLBACK_ALL_ACCESS
Typedefs
typedef _CALLBACK_OBJECT	CALLBACK_OBJECT
typedef _CALLBACK_OBJECT *	PCALLBACK_OBJECT
typedef _CALLBACK_REGISTRATION	CALLBACK_REGISTRATION
typedef _CALLBACK_REGISTRATION *	PCALLBACK_REGISTRATION
Functions
VOID	ExpDeleteCallback (IN PCALLBACK_OBJECT CallbackObject)
BOOLEAN	ExpInitializeCallbacks ()
NTSTATUS	ExCreateCallback (OUT PCALLBACK_OBJECT *CallbackObject, IN POBJECT_ATTRIBUTES ObjectAttributes, IN BOOLEAN Create, IN BOOLEAN AllowMultipleCallbacks)
PVOID	ExRegisterCallback (IN PCALLBACK_OBJECT CallbackObject, IN PCALLBACK_FUNCTION CallbackFunction, IN PVOID CallbackContext)
VOID	ExUnregisterCallback (IN PVOID CbRegistration)
VOID	ExNotifyCallback (IN PCALLBACK_OBJECT CallbackObject, IN PVOID Argument1, IN PVOID Argument2)
Variables
POBJECT_TYPE	ExCallbackObjectType
KEVENT	ExpCallbackEvent
GENERIC_MAPPING	ExpCallbackMapping

---

Define Documentation

#define CALLBACK_ALL_ACCESS

Value: (STANDARD_RIGHTS_REQUIRED|SYNCHRONIZE|\ CALLBACK_MODIFY_STATE ) Definition at line 35 of file ex/callback.c. Referenced by ExpInitializeCallbacks().

#define CALLBACK_MODIFY_STATE   0x0001

Definition at line 33 of file ex/callback.c.

---

Typedef Documentation

typedef struct _CALLBACK_OBJECT CALLBACK_OBJECT

typedef struct _CALLBACK_REGISTRATION CALLBACK_REGISTRATION

typedef struct _CALLBACK_OBJECT * PCALLBACK_OBJECT

Referenced by ExCreateCallback(), and ExUnregisterCallback().

typedef struct _CALLBACK_REGISTRATION * PCALLBACK_REGISTRATION

Referenced by ExNotifyCallback(), ExRegisterCallback(), and ExUnregisterCallback().

---

Function Documentation

NTSTATUS ExCreateCallback (  OUT PCALLBACK_OBJECT *  CallbackObject, IN POBJECT_ATTRIBUTES  ObjectAttributes, IN BOOLEAN  Create, IN BOOLEAN  AllowMultipleCallbacks )

Definition at line 222 of file ex/callback.c. References Create(), ExCallbackObjectType, Handle, KeInitializeSpinLock(), KernelMode, NT_SUCCESS, NTSTATUS(), NULL, ObCreateObject(), ObInsertObject(), ObjectAttributes, ObOpenObjectByName(), ObReferenceObjectByHandle(), PAGED_CODE, PCALLBACK_OBJECT, and Status. Referenced by ExpInitializeCallbacks(). : This function opens a callback object with the specified callback object. If the callback object does not exist or it is a NULL then a callback object will be created if create is TRUE. If a callbackobject is created it will only support mulitiple registered callbacks if AllowMulitipleCallbacks is TRUE. Arguments: CallbackObject - Supplies a pointer to a variable that will receive the Callback object. CallbackName - Supplies a pointer to a object name that will receive the Create - Supplies a flag which indicates whether a callback object will be created or not . AllowMultipleCallbacks - Supplies a flag which indicates only support mulitiple registered callbacks. Return Value: Returns STATUS_SUCESS unless fali... --*/ { PCALLBACK_OBJECT cbObject; NTSTATUS Status; HANDLE Handle; PAGED_CODE(); // // If named callback, open handle to it // if (ObjectAttributes->ObjectName) { Status = ObOpenObjectByName(ObjectAttributes, ExCallbackObjectType, KernelMode, NULL, 0, // DesiredAccess, NULL, &Handle); } else { Status = STATUS_UNSUCCESSFUL; } // // If not opened, check if callback should be created // if(!NT_SUCCESS(Status) && Create ) { Status = ObCreateObject(KernelMode, ExCallbackObjectType, ObjectAttributes, KernelMode, NULL, sizeof(CALLBACK_OBJECT), 0, 0, (PVOID *)&cbObject ); if(NT_SUCCESS(Status)){ // // Fill in structure signature // cbObject->Signature = 'llaC'; // // It will support multiple registered callbacks if // AllowMultipleCallbacks is TRUE. // cbObject->AllowMultipleCallbacks = AllowMultipleCallbacks; // // Initialize CallbackObject queue. // InitializeListHead( &cbObject->RegisteredCallbacks ); // // Initialize spinlock // KeInitializeSpinLock (&cbObject->Lock); // // Put the object in the root directory // Status = ObInsertObject ( cbObject, NULL, FILE_READ_DATA, 0, NULL, &Handle ); } } if(NT_SUCCESS(Status)){ // // Add one to callback object reference count // Status = ObReferenceObjectByHandle ( Handle, 0, // DesiredAccess ExCallbackObjectType, KernelMode, &cbObject, NULL ); ZwClose (Handle); } // // If SUCEESS , returns a referenced pointer to the CallbackObject. // if (NT_SUCCESS(Status)) { *CallbackObject = cbObject; } return Status; }

VOID ExNotifyCallback (  IN PCALLBACK_OBJECT  CallbackObject, IN PVOID  Argument1, IN PVOID  Argument2 )

Definition at line 563 of file ex/callback.c. References _CALLBACK_REGISTRATION::Busy, _CALLBACK_REGISTRATION::CallbackContext, _CALLBACK_REGISTRATION::CallbackFunction, DISPATCH_LEVEL, ExpCallbackEvent, FALSE, KeAcquireSpinLock, KeReleaseSpinLock(), KeSetEvent(), NULL, PCALLBACK_REGISTRATION, and _CALLBACK_REGISTRATION::UnregisterWaiting. 00571 : 00572 00573 This function notifies all registered callbacks . 00574 00575 Arguments: 00576 00577 CallbackObject - supplies a pointer to the callback object should be 00578 notified. 00579 00580 SystemArgument1 - supplies a pointer will be passed to callback function. 00581 00582 SystemArgument2 - supplies a pointer will be passed to callback function. 00583 00584 Return Value: 00585 00586 None. 00587 00588 --*/ 00589 00590 { 00591 PLIST_ENTRY Link; 00592 PCALLBACK_REGISTRATION CallbackRegistration; 00593 KIRQL OldIrql; 00594 00595 if (CallbackObject == NULL) { 00596 return ; 00597 } 00598 00599 // 00600 // Synchronize with callback object 00601 // 00602 00603 KeAcquireSpinLock (&CallbackObject->Lock, &OldIrql); 00604 00605 // 00606 // call registered callbacks at callers IRQL level 00607 // ( done if FIFO order of registration ) 00608 // 00609 00610 if (OldIrql == DISPATCH_LEVEL) { 00611 00612 // 00613 // OldIrql is DISPATCH_LEVEL, just invoke all callbacks without 00614 // releasing the lock 00615 // 00616 00617 for (Link = CallbackObject->RegisteredCallbacks.Flink; 00618 Link != &CallbackObject->RegisteredCallbacks; 00619 Link = Link->Flink) { 00620 00621 // 00622 // Get current registration to notify 00623 // 00624 00625 CallbackRegistration = CONTAINING_RECORD (Link, 00626 CALLBACK_REGISTRATION, 00627 Link); 00628 00629 // 00630 // Notify reigstration 00631 // 00632 00633 CallbackRegistration->CallbackFunction( 00634 CallbackRegistration->CallbackContext, 00635 Argument1, 00636 Argument2 00637 ); 00638 00639 } // next registration 00640 00641 } else { 00642 00643 // 00644 // OldIrql is < DISPATCH_LEVEL, the code being called may be pagable 00645 // and the callback object spinlock needs to be released around 00646 // each registration callback. 00647 // 00648 00649 for (Link = CallbackObject->RegisteredCallbacks.Flink; 00650 Link != &CallbackObject->RegisteredCallbacks; 00651 Link = Link->Flink ) { 00652 00653 // 00654 // Get current registration to notify 00655 // 00656 00657 CallbackRegistration = CONTAINING_RECORD (Link, 00658 CALLBACK_REGISTRATION, 00659 Link); 00660 00661 // 00662 // If registration is being removed, don't bothing calling it 00663 // 00664 00665 if (!CallbackRegistration->UnregisterWaiting) { 00666 00667 // 00668 // Set registration busy 00669 // 00670 00671 CallbackRegistration->Busy += 1; 00672 00673 // 00674 // Release SpinLock and notify this callback 00675 // 00676 00677 KeReleaseSpinLock (&CallbackObject->Lock, OldIrql); 00678 00679 CallbackRegistration->CallbackFunction( 00680 CallbackRegistration->CallbackContext, 00681 Argument1, 00682 Argument2 00683 ); 00684 00685 // 00686 // Synchronize with CallbackObject 00687 // 00688 00689 KeAcquireSpinLock (&CallbackObject->Lock, &OldIrql); 00690 00691 // 00692 // Remove our busy count 00693 // 00694 00695 CallbackRegistration->Busy -= 1; 00696 00697 // 00698 // If the registriation removal is pending, kick global 00699 // event let unregister conitnue 00700 // 00701 00702 if (CallbackRegistration->UnregisterWaiting && 00703 CallbackRegistration->Busy == 0) { 00704 KeSetEvent (&ExpCallbackEvent, 0, FALSE); 00705 } 00706 } 00707 } 00708 } 00709 00710 00711 // 00712 // Release callback 00713 // 00714 00715 KeReleaseSpinLock (&CallbackObject->Lock, OldIrql); 00716 } }

VOID ExpDeleteCallback (  IN PCALLBACK_OBJECT  CallbackObject  )

Definition at line 370 of file ex/callback.c. References ASSERT. Referenced by ExpInitializeCallbacks(). { ASSERT (IsListEmpty(&CallbackObject->RegisteredCallbacks)); }

BOOLEAN ExpInitializeCallbacks (   )

Definition at line 101 of file ex/callback.c. References CALLBACK_ALL_ACCESS, EXP_INITIALIZE_GLOBAL_CALLBACKS::CallBackObject, ExCallbackObjectType, ExCreateCallback(), ExpCallbackEvent, ExpCallbackMapping, ExpDeleteCallback(), ExpInitializeCallback, ExpWstrCallback, FALSE, KeInitializeEvent, L, NonPagedPool, NT_SUCCESS, NtClose(), NtCreateDirectoryObject(), NTSTATUS(), NULL, ObCreateObjectType(), OBJECT_TYPE_INITIALIZER, ObjectAttributes, RtlInitUnicodeString(), SePublicDefaultSd, Status, and TRUE. : This function creates the callback object type descriptor at system initialization and stores the address of the object type descriptor in local static storage. Arguments: None. Return Value: A value of TRUE is returned if the timer object type descriptor is successfully initialized. Otherwise a value of FALSE is returned. --*/ { OBJECT_TYPE_INITIALIZER ObjectTypeInitializer; OBJECT_ATTRIBUTES ObjectAttributes; NTSTATUS Status; UNICODE_STRING unicodeString; ULONG i; HANDLE handle; // // Initialize string descriptor. // RtlInitUnicodeString(&unicodeString, L"Callback"); // // Create timer object type descriptor. // RtlZeroMemory(&ObjectTypeInitializer, sizeof(ObjectTypeInitializer)); ObjectTypeInitializer.Length = sizeof(ObjectTypeInitializer); ObjectTypeInitializer.InvalidAttributes = OBJ_OPENLINK; ObjectTypeInitializer.GenericMapping = ExpCallbackMapping; ObjectTypeInitializer.DeleteProcedure = ExpDeleteCallback; ObjectTypeInitializer.PoolType = NonPagedPool; ObjectTypeInitializer.ValidAccessMask = CALLBACK_ALL_ACCESS; Status = ObCreateObjectType(&unicodeString, &ObjectTypeInitializer, (PSECURITY_DESCRIPTOR)NULL, &ExCallbackObjectType); if (!NT_SUCCESS(Status)) { return FALSE; } RtlInitUnicodeString( &unicodeString, ExpWstrCallback ); InitializeObjectAttributes( &ObjectAttributes, &unicodeString, OBJ_CASE_INSENSITIVE | OBJ_PERMANENT, NULL, SePublicDefaultSd ); Status = NtCreateDirectoryObject( &handle, DIRECTORY_ALL_ACCESS, &ObjectAttributes ); if (!NT_SUCCESS(Status)) { return FALSE; } NtClose (handle); // // Initialize event to wait on for Unregisters which occur while // notifications are in progress // KeInitializeEvent (&ExpCallbackEvent, NotificationEvent, 0); // // Initialize NT global callbacks // for (i=0; ExpInitializeCallback[i].CallBackObject; i++) { // // Create named calledback // RtlInitUnicodeString(&unicodeString, ExpInitializeCallback[i].CallbackName); InitializeObjectAttributes( &ObjectAttributes, &unicodeString, OBJ_PERMANENT | OBJ_CASE_INSENSITIVE, NULL, NULL ); Status = ExCreateCallback ( ExpInitializeCallback[i].CallBackObject, &ObjectAttributes, TRUE, TRUE ); if (!NT_SUCCESS(Status)) { return FALSE; } } return TRUE; }

PVOID ExRegisterCallback (  IN PCALLBACK_OBJECT  CallbackObject, IN PCALLBACK_FUNCTION  CallbackFunction, IN PVOID  CallbackContext )

Definition at line 378 of file ex/callback.c. References ASSERT, _CALLBACK_REGISTRATION::Busy, _CALLBACK_REGISTRATION::CallbackContext, _CALLBACK_REGISTRATION::CallbackFunction, _CALLBACK_REGISTRATION::CallbackObject, DISPATCH_LEVEL, ExAllocatePoolWithTag, ExFreePool(), FALSE, KeAcquireSpinLock, KeReleaseSpinLock(), _CALLBACK_REGISTRATION::Link, NonPagedPool, NTSTATUS(), NULL, ObDereferenceObject, ObReferenceObject, PCALLBACK_FUNCTION, PCALLBACK_REGISTRATION, Status, TRUE, and _CALLBACK_REGISTRATION::UnregisterWaiting. : This routine allows a caller to register that it would like to have its callback Function invoked when the callback notification call occurs. Arguments: CallbackObject - Supplies a pointer to a CallbackObject. CallbackFunction - Supplies a pointer to a function which is to be executed when the Callback notification occures. CallbackContext - Supplies a pointer to an arbitrary data structure that will be passed to the function specified by the CallbackFunction parameter. Return Value: Returns handle to callback registration. --*/ { PCALLBACK_REGISTRATION CallbackRegistration; BOOLEAN Inserted; KIRQL OldIrql; NTSTATUS Status; ASSERT (CallbackFunction); ASSERT (KeGetCurrentIrql() < DISPATCH_LEVEL); // // Add reference to object // ObReferenceObject (CallbackObject); // // Begin by attempting to allocate storage for the CallbackRegistration. // one cannot be allocated, return the error status. // CallbackRegistration = ExAllocatePoolWithTag( NonPagedPool, sizeof( CALLBACK_REGISTRATION ), 'eRBC' ); if( !CallbackRegistration ) { ObDereferenceObject (CallbackObject); return NULL; } // // Initialize the callback packet // CallbackRegistration->CallbackObject = CallbackObject; CallbackRegistration->CallbackFunction = CallbackFunction; CallbackRegistration->CallbackContext = CallbackContext; CallbackRegistration->Busy = 0; CallbackRegistration->UnregisterWaiting = FALSE; Inserted = FALSE; KeAcquireSpinLock (&CallbackObject->Lock, &OldIrql); if( CallbackObject->AllowMultipleCallbacks || IsListEmpty( &CallbackObject->RegisteredCallbacks ) ) { // // add CallbackRegistration to tail // Inserted = TRUE; InsertTailList( &CallbackObject->RegisteredCallbacks, &CallbackRegistration->Link ) } KeReleaseSpinLock (&CallbackObject->Lock, OldIrql); if (!Inserted) { ExFreePool (CallbackRegistration); CallbackRegistration = NULL; } return (PVOID) CallbackRegistration; }

VOID ExUnregisterCallback (  IN PVOID  CbRegistration  )

Definition at line 479 of file ex/callback.c. References ASSERT, _CALLBACK_REGISTRATION::Busy, _CALLBACK_REGISTRATION::CallbackObject, DISPATCH_LEVEL, Executive, ExFreePool(), ExpCallbackEvent, FALSE, KeAcquireSpinLock, KeClearEvent, KeReleaseSpinLock(), KernelMode, KeWaitForSingleObject(), _CALLBACK_REGISTRATION::Link, _CALLBACK_OBJECT::Lock, NULL, ObDereferenceObject, PCALLBACK_OBJECT, PCALLBACK_REGISTRATION, TRUE, and _CALLBACK_REGISTRATION::UnregisterWaiting. : This function removes the callback registration for the callbacks from the list of callback object . Arguments: CallbackRegistration - Pointer to device object for the file system. Return Value: None. --*/ { PCALLBACK_REGISTRATION CallbackRegistration; PCALLBACK_OBJECT CallbackObject; KIRQL OldIrql; ASSERT (KeGetCurrentIrql() < DISPATCH_LEVEL); CallbackRegistration = (PCALLBACK_REGISTRATION) CbRegistration; CallbackObject = CallbackRegistration->CallbackObject; KeAcquireSpinLock (&CallbackObject->Lock, &OldIrql); // // Wait for registration // while (CallbackRegistration->Busy) { // // Set waiting flag, then wait. (not performance critical - use // single global event to wait for any and all unregister waits) // CallbackRegistration->UnregisterWaiting = TRUE; KeClearEvent (&ExpCallbackEvent); KeReleaseSpinLock (&CallbackObject->Lock, OldIrql); KeWaitForSingleObject ( &ExpCallbackEvent, Executive, KernelMode, FALSE, NULL ); // // Synchronize with callback object and recheck registration busy // KeAcquireSpinLock (&CallbackObject->Lock, &OldIrql); } // // Registration not busy, remove it from the callback object // RemoveEntryList (&CallbackRegistration->Link); KeReleaseSpinLock (&CallbackObject->Lock, OldIrql); // // Free memory used for CallbackRegistration // ExFreePool (CallbackRegistration); // // Remove reference count on CallbackObject // ObDereferenceObject (CallbackObject); }

---

Variable Documentation

POBJECT_TYPE ExCallbackObjectType

Definition at line 43 of file ex/callback.c. Referenced by ExCreateCallback(), and ExpInitializeCallbacks().

KEVENT ExpCallbackEvent

Definition at line 49 of file ex/callback.c. Referenced by ExNotifyCallback(), ExpInitializeCallbacks(), and ExUnregisterCallback().

GENERIC_MAPPING ExpCallbackMapping

Initial value: { STANDARD_RIGHTS_READ , STANDARD_RIGHTS_WRITE | CALLBACK_MODIFY_STATE, STANDARD_RIGHTS_EXECUTE | SYNCHRONIZE, CALLBACK_ALL_ACCESS } Definition at line 56 of file ex/callback.c. Referenced by ExpInitializeCallbacks().

---