Ah, confusion reigns again regarding what pending, cancel, synchronous
i/o etc. mean. Time for a refresh yet again: let my try to explain
succintly as a set of rules (hopefully this will be more clearer). You
have to read all the rules to understand, and this is specifically
targeted towards FSD/filter developers.
1.) You can return STATUS_PENDING by default for any IRP, including
IRP_MJ_CREATE - except for a few special IRPs for which STATUS_PENDING
indicates something more. Currently these are the FSCTL_REQUEST*OPLOCK*
IRPs. If you return pending for them, the caller assumes the oplock is
granted. For every other IRP, all STATUS_PENDING means is that if it’s
synchronous i/o (such as a create), I/O manager will wait for the IRP to
complete.
2.) When you return STATUS_PENDING, if it’s a synchronous i/o, NT i/o
manager automatically waits for the i/o to complete. You needn’t worry
that you are making an inherently synchronous IRP asynchronous by
returning pending. You are not.
3.) You HAVE to do IoMarkIrpPending() if you return STATUS_PENDING from
your dispatch. You HAVE to return STATUS_PENDING if you are doing
IoMarkIrpPending() in your dispatch.
4.) If you are going to return STATUS_MORE_PROCESSING_REQUIRED from your
*completion routine* for an IRP, then in your *dispatch* (not in the
completion): you have to mark the irp pending & return pending. This
means you need to know in you dispatch if you are going to abort
processing in your completion. That’s the way it works.
5.) If you are going to return STATUS_PENDING from your dispatch
routine, and you have a completion routine, then you HAVE to propagate
the pending flag in your completion and vice versa. Propagating the
pending flag up the stack in your completion routine is as follows:
if (Irp->PendingReturned) IoMarkIrpPending( Irp );
Note the Irp->PendingReturned variable is NOT valid on the way down of
an IRP. It comes into existence only when an IRP is completing.
6.) As the converse of rule 5.) if you ARE going to wait for the IRP to
complete in your dispatch - i.e. your completion routine sets an event
and returns STATUS_MORE_PROCESSING_REQUIRED, and then you pick up in
your dispatch and return a non-pending status, you must NOT propagate
the pending flag in your completion routine. This is because you are not
going to return pending from your dispatch, you are synchronizing the
i/o essentially in your dispatch.
The rules can be probably be further simplified as:
If returning pending from dispatch, mark irp pending.
If you marked an IRP pending in dispatch, return STATUS_PENDING
from dispatch.
If you are NOT returning STATUS_PENDING from dispatch, then do
not propagate the pending flag in your completion
7.) You do not necessarily have to have a cancel routine even if you
return pending. You do need a cancel routine if you are going to hold on
to the IRP for a long time in your driver - if you are queueing it up in
your driver, then please, do implement a cancel routine. If you are
sending it off to a work queue, unfortunately since work items cannot be
cancelled, there is no point in implementing one.
8.) You have to clear the cancel routine before you do an
IoCompleteRequest() on it, or before you forward it via an
IoCallDriver().
By the way - the i/o verifier catches almost every violation of the
above rules & more. Turn it on for your driver. Ravi
This posting is provided “AS IS” with no warranties, and confers no
rights.
-----Original Message-----
From: Alexey Logachyov [mailto:xxxxx@vba.com.by]
Sent: Thursday, September 26, 2002 7:14 AM
To: File Systems Developers
Subject: [ntfsd] Re: Marking an IRP as pending in a file system filter
driver
It depends. In case thread wants to cancel the request it issued (for
example when it is terminating) it hangs until request is completed (or
cancelled). If this is OK for you don’t set up cancel routine.
One more thing. If you pass request to lower driver make sure you set
CancelRoutine to NULL.
-htfv
----- Original Message -----
From:
To: “File Systems Developers”
Sent: Thursday, September 26, 2002 4:54 PM
Subject: [ntfsd] Re: Marking an IRP as pending in a file system filter
driver
> Dear htfv,
>
> Thanks for your valuable information.
>
> One more question is should filter driver definitely set cancel
> routine when it returns status pending.
>
> Thanx in advance,
> Kedar.
>
> > You don’t need to put anything to IoStatus. If operation is
> > syncronous
IO
> > manager will wait for operation completion and it does not care for
IoStatus
> > values. If operation is asynchronous you cannot get any status until
> > operation is actually completed. But I remember that I read
> > somewhere
that
> > it is not allowed to set IoStatus.Status to STATUS_PENDING.
> >
> > One more detail. Microsoft does not recommend to return
> > STATUS_PENDING
in
> > response to IRP_MJ_CREATE from FSFD. The only reason I see for that
> > is
one
> > that if you return STATUS_PENDING and later pass the request to
> > lower device, thread context may change and thus security check may
> > fail.
Though I
> > think correctly designed driver should be able to handle this
> > situation.
> >
> > -htfv
> >
> >
> > ----- Original Message -----
> > From:
> > To: “File Systems Developers”
> > Sent: Thursday, September 26, 2002 2:51 PM
> > Subject: [ntfsd] Re: Marking an IRP as pending in a file system
> > filter driver
> >
> >
> > > Dear htfv,
> > >
> > > Thanks for your information.
> > >
> > > Correct values means IoStatus.Status = STATUS_PENDING
> > > and IoStatus.Information = 0;
> > > So I should not put these values. What are the correct values to
> > > put
here.
> > >
> > > So does your solution works for any kind(with any options) of
> > > IRP_MJ_CREATE.
> > >
> > > Thanx,
> > > Kedar.
> > >
> > >
> > > > Yes Notepad will wait until request is completed. But please
> > > > explain
> > what do
> > > > you mean with ‘correct status values in IoStatus’. You should
> > > > not
set
> > > > IoStatus.Status=STATUS_PENDING.
> > > >
> > > > -htfv
> > > >
> > > >
> > > > ----- Original Message -----
> > > > From:
> > > > To: “File Systems Developers”
> > > > Sent: Thursday, September 26, 2002 1:38 PM
> > > > Subject: [ntfsd] Marking an IRP as pending in a file system
> > > > filter
> > driver
> > > >
> > > >
> > > > > Hai All,
> > > > >
> > > > > I have a question regarding the file system filter driver on
windows
> > 2000.
> > > > >
> > > > > Please see the case below:
> > > > >
> > > > > i) I open a file called text1.txt with notepad
> > > > > i) my file system FILTER driver receives an IRP_MJ_CREATE for
> > > > > the
> > file
> > > > > ii) my FILTER driver marks the IRP as pending by calling
> > > > > IoMarkIrpPending(Irp) and returns STATUS_PENDING with
correct
> > > > > status values in IoStatus.
> > > > >
> > > > > My question here is does NOTEPAD wait until my filter driver
completes
> > the
> > > > > create request successfully? if no, is there procedure that I
> > > > > can
> > delay
> > > > > the notepad request.
> > > > >
> > > > > Any information will be greatly helpful.
> > > > > Thanx in advance,
> > > > > Kedar.
> > > > >
> > > > > —
> > > > > You are currently subscribed to ntfsd as: xxxxx@vba.com.by To
> > > > > unsubscribe send a blank email to %%email.unsub%%
> > > > >
> > >
> > > —
> > > You are currently subscribed to ntfsd as: xxxxx@vba.com.by To
> > > unsubscribe send a blank email to %%email.unsub%%
> > >
>
> —
> You are currently subscribed to ntfsd as: xxxxx@vba.com.by
> To unsubscribe send a blank email to %%email.unsub%%
>
—
You are currently subscribed to ntfsd as: xxxxx@windows.microsoft.com
To unsubscribe send a blank email to %%email.unsub%%