BazisLib::DDK::IncomingIrp Class Reference

PowerIRP-aware class that encapsulates an IRP. No extra action is required to process IRP_MJ_POWER requests. More...

#include <irp.h>

List of all members.

Public Types
enum	{   LowerDriverCalled = 0x01, IrpCompleted = 0x02, IrpMarkedPending = 0x04, IoStatusSet = 0x08,   IsPowerIrp = 0x10, StartNextPowerIrp = 0x20, FromDispatchThread = 0x40, ValidFlags = 0x7F }
Public Member Functions
bool	IsFromQueue ()
PIO_STATUS_BLOCK	GetIoStatus ()
void *	GetSystemBuffer ()
PMDL	GetMdlAddress ()
void *	GetUserBuffer ()
NTSTATUS	GetStatus ()
void	SetIoStatus (NTSTATUS Status, unsigned Information)
void	SetIoStatus (NTSTATUS Status)
void	CompleteRequest (CCHAR PriorityBoost=IO_NO_INCREMENT)
void	MarkPending ()
Private Member Functions
	IncomingIrp (IRP *pIrp, bool bIsPowerIrp, bool bStartNextPowerIrp)
	IncomingIrp (IRP *pIrp, long Flags)
	~IncomingIrp ()
Private Attributes
IRP *	m_pIrp
long	m_Flags
Friends
class	Device

---

Detailed Description

PowerIRP-aware class that encapsulates an IRP. No extra action is required to process IRP_MJ_POWER requests.

A typical driver uses at least 4 different strategies for processing IRPs. We'll overview them here:

• Call lower driver synchronously, perform some actions, and complete the IRP.
• Complete IRP by itself without calling the lower driver.
• Handle IRP (such as most PnP IRPs), set IoStatus.Status and pass the IRP to the lower driver if one exists using IoSkipCurrentIrpStackLocation() and IoCallDriver().
• Mark the IRP as pending, put it into IRP queue, unqueue it later and complete it afterwards.

The first three strategies can be simply implemented using OO approach: an overridable handler (able to call handlers of inherited classes) processes the IRP (performs synchronous lower driver calls if required), and decides what to do after the handling routine completes: to complete the IRP, or to pass it to the next driver.

The fourth strategy can also be simply implemented using IrpQueue class. See "Queueing IRPs" section below.

The IncomingIRP class allows to implement such strategies smoothly:

• The most simple situation: the driver does not want to process this IRP, it returns some status. In that case the framework sees that the IRP was untouched. So, it sets the IoStatus.Status field to the status returned by driver and passes the IRP to the next driver if one exists. If not, it completes the IRP.
• A little bit more complex: the driver alters the IoStatus field. Then the framework sees the IoStatusSet flag and does not alter the IoStatus. This allows returning one status, and setting another one in IRP.
• Just another little bit of complexity: the driver completes the IRP by calling CompleteRequest() method. The framework sees the IrpCompleted flag and does not call the next driver, or touch the IRP anyhow.
• The complex one: the driver calls the lower driver synchronously. The framework sees the LowerDriverCalled flag and also does not attempt to call lower driver. It completes the IRP if required.
• The most complex one: the driver marks the IRP as pending. The framework does not touch the IRP and returns the STATUS_PENDING result code. The driver completes the IRP later.

Please avoid using thr m_pIrp field directly, because it may make the m_Flags field outdated. Consider adding inline methods instead. Do not forget to set the LowerDriverCalled flag if the lower driver gets called using IoCallDriver() call.

The layout of the IncomingIRP class produces minimal overhead (4 extra DWORDs are allocated in stack per each IRP) and allows maintaining code readability.

Queueing IRPs

The BazisLib::DDK framework provides a smooth way for managing IRP queues. You should take 3 simple steps to convert a synchronous driver to queue-based one:

• In the constructor of your device class add the following line:

  	CreateDeviceRequestQueue();
  				

  This method creates a device IRP queue and starts dispatcher thread that dequeues and processes IRPs.
• Override the DispatchRoutine() method and use the following layout to implement it:

  	NTSTATUS YourDeviceClass::DispatchRoutine(IN IncomingIrp *Irp, IO_STACK_LOCATION *IrpSp)
  	{
  		switch (IrpSp->MajorFunction)
  		{
  		case IRP_MJ_XXX:
  		case IRP_MJ_YYY:
  			if (!Irp->IsFromQueue())
  				return EnqueuePacket(Irp);
  			break;
  		}
  		return __super::DispatchRoutine(Irp, IrpSp);
  	}
  				

  This ensures that all IRP_MJ_XXX and IRP_MJ_YYY IRPs will be put into queue and dispatched only in the context of the dispatcher thread.
• Take into consideration that the minihandlers for queued major codes will now be called only from the context of the dispatcher thread. This means that only one instance of such method will be active at a single time, and that you can safely remove synchronization objects that were used in synchronous driver version to prevent simultanious resource access from those minihandlers.

---

Member Enumeration Documentation

anonymous enum

Enumerator:

LowerDriverCalled
IrpCompleted
IrpMarkedPending
IoStatusSet
IsPowerIrp
StartNextPowerIrp
FromDispatchThread
ValidFlags

---

Constructor & Destructor Documentation

BazisLib::DDK::IncomingIrp::IncomingIrp	(	IRP *	pIrp,
		bool	bIsPowerIrp,
		bool	bStartNextPowerIrp
	)			[inline, private]

BazisLib::DDK::IncomingIrp::IncomingIrp	(	IRP *	pIrp,
		long	Flags
	)			[inline, private]

BazisLib::DDK::IncomingIrp::~IncomingIrp

(

)

[inline, private]

---

Member Function Documentation

void BazisLib::DDK::IncomingIrp::CompleteRequest

(

CCHAR

PriorityBoost = IO_NO_INCREMENT

)

[inline]

PIO_STATUS_BLOCK BazisLib::DDK::IncomingIrp::GetIoStatus

(

)

[inline]

PMDL BazisLib::DDK::IncomingIrp::GetMdlAddress

(

)

[inline]

NTSTATUS BazisLib::DDK::IncomingIrp::GetStatus

(

)

[inline]

void* BazisLib::DDK::IncomingIrp::GetSystemBuffer

(

)

[inline]

void* BazisLib::DDK::IncomingIrp::GetUserBuffer

(

)

[inline]

bool BazisLib::DDK::IncomingIrp::IsFromQueue

(

)

[inline]

void BazisLib::DDK::IncomingIrp::MarkPending

(

)

[inline]

void BazisLib::DDK::IncomingIrp::SetIoStatus

(

NTSTATUS

Status

)

[inline]

void BazisLib::DDK::IncomingIrp::SetIoStatus	(	NTSTATUS	Status,
		unsigned	Information
	)			[inline]

---

Friends And Related Function Documentation

friend class Device [friend]

---

Member Data Documentation

long BazisLib::DDK::IncomingIrp::m_Flags [private]

IRP* BazisLib::DDK::IncomingIrp::m_pIrp [private]

---

The documentation for this class was generated from the following file:

• bzsddk/irp.h