Some quick questions about contexts and refcount

NTFSD
1

there are a few things that are not fully clear to me regarding contexts.

every FltGet***Context must be accompanied with a FltReleaseContext.
but if i i store a stream context pointer inside a streamhandle context, i dont have to release it after saving the reference in the context, only when cleaning up the streamhandle context.
is that right?

according to the help page of FltReleaseContext, “the Context pointer returned by FltDeleteContext must also be released by calling FltReleaseContext when they are no longer needed”.
but it is not stated anywhere on the FltDeleteContext page that it “returns” any context, and it’s only parameter has an “IN” prefix anyway
could it mean that this is true only in the case of FltDelete***Context, where the last parameter is OUT? (and i suppose it does not increase the refcount if this parameter is NULL, since it is OPTIONAL)

last questions are about setting contexts:
suppose i am in the InstanceSetupCallback.
i call a FltAllocateContext with FLT_INSTANCE_CONTEXT, if successfull, it now has the refcount of 1.
then i call a FltSetInstanceContext with FLT_SET_CONTEXT_KEEP_IF_EXISTS and NULL for OldContext.
in this case if it is successfull, the context would have a refcount of 2?

if i call FltSet***Context, and it returns STATUS_SUCCESS, it increases the refcount of the NewContext.
if i provide and OldContext too, will it increase the refcount if i set FLT_SET_CONTEXT_REPLACE_IF_EXISTS or FLT_SET_CONTEXT_KEEP_IF_EXISTS?
the help states the following: “After calling FltSetInstanceContext, the caller must call FltReleaseContext to decrement the reference count on NewContext, even if the call to FltSetInstanceContext was unsuccessful”
what is considered unsuccessfull?
does it really mean that FltSet***Context increases refcount (for NewContext) only when it returns STATUS_SUCCESS, STATUS_FLT_CONTEXT_ALREADY_DEFINED or STATUS_FLT_CONTEXT_ALREADY_LINKED?

thanks

2

> there are a few things that are not fully clear to me regarding contexts.

The documentation can be confusing since it is prescriptive rather than
descriptive (that’s its job), as some background, although it seems that you
have worked it out…

Contexts are managed as reference counted objects. A Sucessful FltGetXXX
will increment the refcount, the deference decrement it. Indeed any (I
think) call to the filter manager which returns a context will return it
referenced.

Where people often get confused is that when the context is associated with
a OS System structure (Stream, StreamHandle, File, …) the reference count
is also incremented and when the link between that structure and the context
is broken the reference is decremented. The link is usually broken when
the object goes away but might be the result of a FltDeleteContext.

every FltGet***Context must be accompanied with a FltReleaseContext.
but if i i store a stream context pointer inside a streamhandle context, i
dont have to release it after saving the
reference in the context, only when cleaning up the streamhandle context.

is that right?

Absolutely, indeed it would not be unusual to keep a reference count
associated with every copy of the contexts address. That way you can know
that the object will not got away. [*]

according to the help page of FltReleaseContext, “the Context pointer
returned by FltDeleteContext must also be released by calling
FltReleaseContext when they are no longer needed”.

This has actually been cleaned up in the current version:

" Note that the OldContext pointer returned by FltSetXxxContext and the
Context parameter that is used to call FltDeleteContext must also be
released by calling FltReleaseContext when they are no longer needed.

The case it is thinking of is

FltGetContext // You gain a reference
FltDeleteContext // Something happens, but your reference is still there
FltDerefContext // your reference

In practice is is almost unheard of to ever use FltDeleteContext, so I’d not
worry about it at this stage.

last questions are about setting contexts:
suppose i am in the InstanceSetupCallback.
i call a FltAllocateContext with FLT_INSTANCE_CONTEXT, if successfull, it
now has the refcount of 1.

Yup

then i call a FltSetInstanceContext with FLT_SET_CONTEXT_KEEP_IF_EXISTS
and NULL for OldContext.
in this case if it is successfull, the context would have a refcount of 2?

Yup, one for you and one for the instance it is associated with.

if i call FltSet***Context, and it returns STATUS_SUCCESS, it increases
the refcount of the NewContext.
yes

if i provide and OldContext too, will it increase the refcount if i set
FLT_SET_CONTEXT_REPLACE_IF_EXISTS or FLT_SET_CONTEXT_KEEP_IF_EXISTS?
the help states the following: “After calling FltSetInstanceContext, the
caller must call FltReleaseContext to decrement the reference count on
NewContext, even if the call to
FltSetInstanceContext was unsuccessful”
what is considered unsuccessfull?
does it really mean that FltSet***Context increases refcount (for
NewContext) only when it returns STATUS_SUCCESS,
STATUS_FLT_CONTEXT_ALREADY_DEFINED or
STATUS_FLT_CONTEXT_ALREADY_LINKED?

I would imagine so. I think a better way of thinking about it is “If
FltSetXXXContext returns a value in OldContext, then it will be referenced”,
this may not be the correct thing to write in documentation, but I firmly
believe it would be the best way to code it. As I said at the top “any call
to the filter manager which returns a context will return it referenced”.

I hope this helps.

Rod

[*] Of course you do need to be careful about circularity of reference (if A
references B, B references C and C references A, nothing will every go
away). I usually manage this by having a hierarchy of references
(StreamHandle references Stream references File references Instance
references Volume)

3

thanks for the reply

4

Rob did a great job of answering your questions. If you still have any other questions I have a blog post on this very topic, here: http://fsfilters.blogspot.com/2010/02/context-usage-in-minifilters.html.

Thanks,
Alex.
On Apr 23, 2013, at 1:31 AM, xxxxx@gmail.com wrote:

thanks for the reply

NTFSD is sponsored by OSR

OSR is hiring!! Info at http://www.osr.com/careers

For our schedule of debugging and file system seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at http://www.osronline.com/page.cfm?name=ListServer