what is an invalid HKEY?

NTDEV
1

In my installer I need to programmatically open up a registry key. I
want the code to go like:

HKEY mykey =

…
open key
…

cleanup:
if (mykey != )
close key

Is NULL the accepted invalid handle (or specifically, HKEY) value or is
there some other value I should use?

Thanks

James

2

I thought INVALID_HANDLE_VALUE was the correct constant to use. I don’t
think there is a guarantee that 0 is an invalid handle value.

Jan

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:bounce-428877-
xxxxx@lists.osr.com] On Behalf Of James Harper
Sent: Saturday, October 23, 2010 12:43 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] what is an invalid HKEY?

In my installer I need to programmatically open up a registry key. I want
the
code to go like:

HKEY mykey =
>
> …
> open key
> …
>
> cleanup:
> if (mykey != )
> close key
>
> Is NULL the accepted invalid handle (or specifically, HKEY) value or is
there
> some other value I should use?
>
> Thanks
>
> James
>
> —
> NTDEV is sponsored by OSR
>
> For our schedule of WDF, WDM, debugging and other 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

3

registry key opening functions will return “INVALID_HANDLE_VALUE” if they fail. so you can use that.

4

From an API contract perspective, NULL can be inferred to be an invalid registry key handle given the documentation for RegOverridePredefKey (see http://msdn.microsoft.com/en-us/library/ms724901.aspx ). I’m unaware of any documentation describing INVALID_HANDLE_VALUE for use with registry handles.

  • S

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of James Harper
Sent: Saturday, October 23, 2010 12:43 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] what is an invalid HKEY?

In my installer I need to programmatically open up a registry key. I want the code to go like:

HKEY mykey =

…
open key
…

cleanup:
if (mykey != )
close key

Is NULL the accepted invalid handle (or specifically, HKEY) value or is there some other value I should use?

Thanks

James

—
NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other 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

5

>

I thought INVALID_HANDLE_VALUE was the correct constant to use. I
don’t
think there is a guarantee that 0 is an invalid handle value.

That sounds quite reasonable. Thanks.

James

6

Actually, the registry key open/create functions do not guarantee that the output key handle will be initialized to any particular value on failure. You cannot rely on this as it’s not the case in all situations. (I went ahead and checked the code on this, if you’re wondering.)

  • S (Msft)

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of xxxxx@yahoo.com
Sent: Saturday, October 23, 2010 12:52 AM
To: Windows System Software Devs Interest List
Subject: RE:[ntdev] what is an invalid HKEY?

registry key opening functions will return “INVALID_HANDLE_VALUE” if they fail. so you can use that.

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other 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

7

>

Actually, the registry key open/create functions do not guarantee that
the
output key handle will be initialized to any particular value on
failure. You
cannot rely on this as it’s not the case in all situations. (I went
ahead and
checked the code on this, if you’re wondering.)

I initialise the output key myself. I only need a guarantee that the
handle will be untouched on error, and that the invalid value I use
(whether it be NULL or INVALID_HANDLE_VALUE) will never be returned to
me as a valid handle. The actual code is more like:

handle1 = INVALID_HANDLE_VALUE
handle2 = INVALID_HANDLE_VALUE
handle3 = INVALID_HANDLE_VALUE

hr = open(HKEY_LOCAL_MACHINE, “somekey”, &handle1)
if (hr is failure)
goto cleanup

…

hr = open(handle1, “some other key”, &handle2)
if (hr is failure)
goto cleanup

…
if (some error condition)
goto cleanup

…

hr = open(handle1, “yet another key”, &handle3)
if (hr is failure)
goto cleanup

…

cleanup:
if (handle3 != INVALID_HANDLE_VALUE)
close(handle3)
if (handle2 != INVALID_HANDLE_VALUE)
close(handle2)
if (handle1 != INVALID_HANDLE_VALUE)
close(handle1)

it makes the cleanup routine easier to do it this way, rather than
repeat the closing of opened resources every time I check for an error
or create Boolean values to tell me if the handle needs closing or not.

thanks

James

8

James, the contract for the registry functions is that the output handle might be set to an undefined value should RegOpenKey*/RegCreateKey* fail. (There is no documentation stating otherwise.) You cannot assume that a particular value is retained, nor that a particular sentinel value is returned on failure. In fact, there are cases where the code as you have written it will do the wrong thing in today’s implementation.

While it is less convenient, you cannot assume any particular value in the output parameter of these functions as neither the contract or the implementation guarantee it.

Additionally, NULL is the only contractually defined invalid registry key handle. It would be specific to today’s implementation to assume INVALID_HANDLE_VALUE is also outlawed (though this is admittedly a pedantic and likely academic point; the usage of the output key hande parameter as described above, is not).

  • S

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of James Harper
Sent: Saturday, October 23, 2010 1:58 AM
To: Windows System Software Devs Interest List
Subject: RE: RE:[ntdev] what is an invalid HKEY?

Actually, the registry key open/create functions do not guarantee that
the
output key handle will be initialized to any particular value on
failure. You
cannot rely on this as it’s not the case in all situations. (I went
ahead and
checked the code on this, if you’re wondering.)

I initialise the output key myself. I only need a guarantee that the handle will be untouched on error, and that the invalid value I use (whether it be NULL or INVALID_HANDLE_VALUE) will never be returned to me as a valid handle. The actual code is more like:

handle1 = INVALID_HANDLE_VALUE
handle2 = INVALID_HANDLE_VALUE
handle3 = INVALID_HANDLE_VALUE

hr = open(HKEY_LOCAL_MACHINE, “somekey”, &handle1) if (hr is failure)
goto cleanup

…

hr = open(handle1, “some other key”, &handle2) if (hr is failure)
goto cleanup

…
if (some error condition)
goto cleanup

…

hr = open(handle1, “yet another key”, &handle3) if (hr is failure)
goto cleanup

…

cleanup:
if (handle3 != INVALID_HANDLE_VALUE)
close(handle3)
if (handle2 != INVALID_HANDLE_VALUE)
close(handle2)
if (handle1 != INVALID_HANDLE_VALUE)
close(handle1)

it makes the cleanup routine easier to do it this way, rather than repeat the closing of opened resources every time I check for an error or create Boolean values to tell me if the handle needs closing or not.

thanks

James

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other 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

9

>

James, the contract for the registry functions is that the output
handle might
be set to an undefined value should RegOpenKey*/RegCreateKey* fail.
(There is
no documentation stating otherwise.) You cannot assume that a
particular
value is retained, nor that a particular sentinel value is returned on
failure. In fact, there are cases where the code as you have written
it will
do the wrong thing in today’s implementation.

While it is less convenient, you cannot assume any particular value in
the
output parameter of these functions as neither the contract or the
implementation guarantee it.

Additionally, NULL is the only contractually defined invalid registry
key
handle. It would be specific to today’s implementation to assume
INVALID_HANDLE_VALUE is also outlawed (though this is admittedly a
pedantic
and likely academic point; the usage of the output key hande parameter
as
described above, is not).

That’s exactly the sort of thing I needed to know - could save heaps of
time with curious crashes later on.

Thanks again!

James

10

Thanks Ken for the information. Since James mentioned about installer my response was based upon setupdi functions like SetupDiOpenDevRegKey/SetupDiCreateDevRegKey which return INVALID_HANDLE_VALUE upon failure.

11

Unfortunately, the HANDLE-like interfaces are somewhat inconsistent about whether they prefer that or NULL in their contracts. It’s something you really need to check the documentation about to be certain of as a result (it would certainly have been nicer if, in retrospect, everyone had used the same construct).

  • S

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of xxxxx@yahoo.com
Sent: Saturday, October 23, 2010 9:46 AM
To: Windows System Software Devs Interest List
Subject: RE:[ntdev] what is an invalid HKEY?

Thanks Ken for the information. Since James mentioned about installer my response was based upon setupdi functions like SetupDiOpenDevRegKey/SetupDiCreateDevRegKey which return INVALID_HANDLE_VALUE upon failure.

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other 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

12

>Is NULL the accepted invalid handle (or specifically, HKEY) value or is

Note that HKEY is not a kernel handle, but more like an RPC binding handle or such.

So, INVALID_HANDLE_VALUE hardly applies to HKEY.

–
Maxim S. Shatskih
Windows DDK MVP
xxxxx@storagecraft.com
http://www.storagecraft.com

13

“Maxim S. Shatskih” wrote in message
news:xxxxx@ntdev…
>>Is NULL the accepted invalid handle (or specifically, HKEY) value or is
>
> Note that HKEY is not a kernel handle, but more like an RPC binding
> handle or such.
>
> So, INVALID_HANDLE_VALUE hardly applies to HKEY.
>

Well, then, what is your advice to the OP?

From ideas seen in various places - I’ve seen people defined functions
like IsValidSomethingHandle() for various kinds of handles.
And, in case they may forget to call it, they override operator ! so
that (!handle) translates to the above function.

Maybe when creating new kind of handles, one should ensure that valid values
cannot be either 0 or -1.

And let’s not forget about the “tag bits”. For example 0x1 is neither 0 nor
INVALID_HANDLE_VALUE, but can it be a valid handle?
Depends on the application.

Regards,
–pa

14

>

“Maxim S. Shatskih” wrote in message
> news:xxxxx@ntdev…
> >>Is NULL the accepted invalid handle (or specifically, HKEY) value or
is
> >
> > Note that HKEY is not a kernel handle, but more like an RPC
binding
> > handle or such.
> >
> > So, INVALID_HANDLE_VALUE hardly applies to HKEY.
> >
>
> Well, then, what is your advice to the OP?
>
> From ideas seen in various places - I’ve seen people defined functions
> like IsValidSomethingHandle() for various kinds of handles.
> And, in case they may forget to call it, they override operator ! so
> that (!handle) translates to the above function.
>
> Maybe when creating new kind of handles, one should ensure that valid
values
> cannot be either 0 or -1.
>
> And let’s not forget about the “tag bits”. For example 0x1 is neither
0 nor
> INVALID_HANDLE_VALUE, but can it be a valid handle?
> Depends on the application.
>

I think Mr[1] Skywing has already dealt the death blow to my plan when
he commented that the various RegXxx(…, &handle) values can modify
handle even in the fail case, which means I can’t rely on handle
retaining my invalid handle value to determine if I need to close/free
it or not. The documentation doesn’t specify either way but it certainly
doesn’t contradict him.

So while continuing the discussion is interesting it’s not going to help
my case.

Thanks

James

[1] I don’t actually know the gender of “skywing” but am making an
assumption.

15

From a general development standpoint, my recommendation would be to program conservatively in matters where the API contract doesn’t specify a behavior. The way I usually look at it is as though the API contract is a set of promises provided to you; assuming something not promised puts you onto implementation-specific grounds (at best).

(Yes, documentation isn’t always perfect, but from an engineering standpoint – behaviors such as whether a routine uses output only parameters for scratch space are certainly reasonable to assume either way in the absence of an explicit statement. Thus it would be wise to avoid relying on a specific behavior in that matter, one way or another, without a contract guarantee.)

  • S

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of James Harper
Sent: Saturday, October 23, 2010 5:03 PM
To: Windows System Software Devs Interest List
Subject: RE: [ntdev] what is an invalid HKEY?

“Maxim S. Shatskih” wrote in message
> news:xxxxx@ntdev…
> >>Is NULL the accepted invalid handle (or specifically, HKEY) value or
is
> >
> > Note that HKEY is not a kernel handle, but more like an RPC
binding
> > handle or such.
> >
> > So, INVALID_HANDLE_VALUE hardly applies to HKEY.
> >
>
> Well, then, what is your advice to the OP?
>
> From ideas seen in various places - I’ve seen people defined functions
> like IsValidSomethingHandle() for various kinds of handles.
> And, in case they may forget to call it, they override operator ! so
> that (!handle) translates to the above function.
>
> Maybe when creating new kind of handles, one should ensure that valid
values
> cannot be either 0 or -1.
>
> And let’s not forget about the “tag bits”. For example 0x1 is neither
0 nor
> INVALID_HANDLE_VALUE, but can it be a valid handle?
> Depends on the application.
>

I think Mr[1] Skywing has already dealt the death blow to my plan when he commented that the various RegXxx(…, &handle) values can modify handle even in the fail case, which means I can’t rely on handle retaining my invalid handle value to determine if I need to close/free it or not. The documentation doesn’t specify either way but it certainly doesn’t contradict him.

So while continuing the discussion is interesting it’s not going to help my case.

Thanks

James

[1] I don’t actually know the gender of “skywing” but am making an assumption.

—
NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other 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

16

> I initialise the output key myself. I only need a guarantee that the handle will be untouched on error,

and that the invalid value I use (whether it be NULL or INVALID_HANDLE_VALUE) will never be returned
to me as a valid handle

Why do you want to do something that like that??? It is so incredibly fragile. Unless you get ERROR_SUCCESS you can assume that your call has failed, check the error status and act accordingly. Pure, simple, independent of a particular implementation and in 100% conformance with documentation…

Anton Bassov

17

“James Harper” wrote in message
news:xxxxx@ntdev…
>
> I think Mr[1] Skywing has already dealt the death blow to my plan when
> he commented that the various RegXxx(…, &handle) values can modify
> handle even in the fail case, which means I can’t rely on handle
> retaining my invalid handle value to determine if I need to close/free
> it or not. The documentation doesn’t specify either way but it certainly
> doesn’t contradict him.
>
> So while continuing the discussion is interesting it’s not going to help
> my case.
>
> Thanks
>
> James

Why it is not going to help? IMHO based on the information you can just
write a little wrapper that works exacty as you want, ex.

HKEY my_openKey(… ) /* returns (HKEY)0 on failure /

or, for paranoic types worrying that 0 still may be a valid handle:

HKEY my_openKey( OUT bool opened, … ) /* on failure returns opened =
false */

– pa

18

>

> I initialise the output key myself. I only need a guarantee that the
handle
will be untouched on error,
> and that the invalid value I use (whether it be NULL or
INVALID_HANDLE_VALUE) will never be returned
> to me as a valid handle

Why do you want to do something that like that??? It is so incredibly
fragile.
Unless you get ERROR_SUCCESS you can assume that your call has
failed, check
the error status and act accordingly. Pure, simple, independent of a
particular implementation and in 100% conformance with
documentation…

As per previous email, it’s to make cleanup easier. I’m opening many
registry keys and if an error occurs at any point I want to close them,
but I want a single cleanup routine that just runs through them all and
checks which are open, without having to have a bool or something to say
handlex_is_open.

James

19

> Well, then, what is your advice to the OP?

Add a boolean - or an error code - variable.

–
Maxim S. Shatskih
Windows DDK MVP
xxxxx@storagecraft.com
http://www.storagecraft.com

20

>I think Mr[1] Skywing has already dealt the death blow to my plan when

he commented that the various RegXxx(…, &handle) values can modify
handle even in the fail case

I think most functions do update their OUT parameters even in failure case.

–
Maxim S. Shatskih
Windows DDK MVP
xxxxx@storagecraft.com
http://www.storagecraft.com