Not every function is documented

by Michael S. Kaplan, published on 2005/05/21 17:15 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2005/05/21/420762.aspx

Ivan Leo posted the following note in the suggestion box:

Why isn't RtlCreateUnicodeString() documented? I mean, it's a damn simple interface that has no reason to change, and is useful is one needs lots of UNICODE_STRINGs

I cannot speak for the owners of these Rtl* functions, but it is likely a question that makes a lot more sense to ask in a more "DDK-esque" kind of forum. In my whole "opening it all up" mindset, I have no problwm with documenting functions and putting them in public header files, but in practice I know it is not as easy as that -- there are often good reasons to proceed with caution that are not immediately apparent.

This particular function has been around for a while, but AFAIK none of the semantics of use have ever really been enumerated before, like allocation rules, legal IRQ levels at which the function can be called, etc....

# Larry Osterman [MSFT] on 21 May 2005 3:20 PM:

The answer to this is really quite simple: To my knowledge, there's no part of the Win32 API set that deals with UNICODE_STRING structures.

They're used in the NT kernel, but they're not a part of the public API set.

So why document an API if the API is totally useless?

# Ivan Leo on 21 May 2005 4:42 PM:

> So why document an API if the API is totally useless?
So you're saying you've documented RtlInitUnicodeString because it's useless?

# Mike Dimmick on 21 May 2005 5:30 PM:

RtlCreateUnicodeString is both a kernel-mode and a user-mode API - it lives in ntdll.dll in user-mode. And UNICODE_STRING *is* used in some parts of the Local Security Authority API, though admittedly not ones that are often used or terribly well documented (some structures passed to LsaLogonUser, for example). A UNICODE_STRING is one of the members of a MCAST_SCOPE_ENTRY, a structure used in the MADCAP (dynamic allocation of multicast addresses) API. You might also need it if you were implementing a Security Support Provider (not very likely, I hope!)

However, RtlInitUnicodeString *is* documented.

# Michael S. Kaplan on 21 May 2005 5:33 PM:

Larry is right insofar as whether I would be the right person to ask. :-)

To put it another way, there may be some basis for believing the guy at the Burger King counter may know why the burgers at Burger King taste funny. But there is no real basis to ask the guy at the Wendy's counter. Which is kind of what it is like asking me. :-)

But you could use RtlInitUnicodeString, which *is* documented: http://msdn.microsoft.com/library/en-us/winui/winui/windowsuserinterface/lowlevelclientsupport/misc/rtlinitunicodestring.asp and then call it a day....

# Michael S. Kaplan on 21 May 2005 5:45 PM:

Ivan, RtlInitUnicodeString gets around many of the issues I pointed out -- it uses the string you pass in, which means that the caller handles allocaton. This is in sharp contract to RtlCreateUnicodeString, which actually allocates and copies the string.

This difference moves the API to a whole new level in terms of things toaorry about and potential for unintenional misuse....
Please consider a donation to keep this archive running, maintained and free of advertising.
Donate €20 or more to receive an offline copy of the whole archive including all images.

go to newer or older post, or back to index or month or day