Undocumented functions: a digest

Fri Feb 8 09:46:34 CST 2002

Thanks to everyone who sent me examples of undocumented
information; I have passed that along; I think it
will be very helpful.

I was hoping to edit it, and make it a bit more definitive,
but I seem to have run out of time.

So, I thought I'd just post the raw replies here so 
it didn't vanish into the bit bucket.

Cheers,

Jeremy

-------------- next part --------------
From: Richard A Lough <ralough.ced at dnet.co.uk>

Jeremy White wrote:
> 
> I'm working with someone involved in the Microsoft trial,
> and they are looking for some information from the
> Wine team.
> 
> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.
> 
> I've asked around CodeWeavers, and we had a few examples,
> but we're in a bit of a time crunch (48 hours), and I was hoping to
> ask a broader audience to pitch in.
> 
> In an effort to keep this off topic traffic down,
> please reply just to me; if you like, I can post a summary
> of the results.
> 

I'm working from a memory over three years old, and as 
I'm also not a programmer there is even more room for confusion.

LocalAllocate (16bit) can fail to allocate memory correctly.
When this happens, IIRC it pushes a number onto the stack.
Anything other than zero causes a GPF in Windows. 

I'll happily check whether or not this is documented if you 
can point me at a web address or other resource.

Apologies for the lack of clarity in this reply. 

R A Lough

--------------------------------------------

From: James <jas88 at cam.ac.uk>

On Wednesday 06 February 2002 5:03 pm, you wrote:
> I'm working with someone involved in the Microsoft trial,
> and they are looking for some information from the
> Wine team.
>
> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.

Obvious example: the ENTIRE NT/2k Native API, AFAICS... (Their compiler and 
linker have an entire layer of totally undocumented functionality for 
building native binaries; see sysinternals.com for details.)
Also, the file system defragmentation API.

Not APIs, but still need to be documented for interoperability:
NTFS on-disk structures.
Some of the SMB protocol - see Samba for details.
Exchange's mail protocol, I think?

James.

--------------------------------------------

From: Eric Pouech <eric.pouech at wanadoo.fr>

> I've asked around CodeWeavers, and we had a few examples,
> but we're in a bit of a time crunch (48 hours), and I was hoping to
> ask a broader audience to pitch in.
from the undocumented part, there's (mostly coming from the multimedia
part):
- in all notification methods for low level drivers (like waveOut
functions), 
using 6 as a DCB_???? value is not documented. however, it's used by
most
of MS MCI drivers
- the (waveOut|waveIn|midiOut|midiIn)Message functions support some 
undocumented flags (when used on driver ID, not handles). all the 
DRV_QUERY???? are defined in the SDK headers, but not documented. IIRC,
those
are used by some MS MCI drivers (and some programs around as well,
halflife is
one of them)
- there's a ton of undocumented functions in the console handling, which
are
used by all the UI of the console (here's my internal list)

(         AddConsoleAlias[AW]
	  CloseConsoleHandle
	  ConsoleSubst
	  ExpungeConsoleCommandHistory[AW]
	  GetConsoleAlias[AW]
	  GetConsoleAliasExes[AW]
	  GetConsoleAliasExesLength[AW]
	  GetConsoleAliases[AW]
	  GetConsoleAliasesLength[AW]
	  GetConsoleCommandHistory[AW] (dword dword dword)
	  GetConsoleCommandHistoryLength[AW]
	  BOOL WINAPI GetConsoleDisplayMode(LPDWORD dwConsoleDisplayMode);
	  GetConsoleFontInfo
	  GetConsoleFontSize
	  GetConsoleHardwareState
	  GetConsoleInputWaitHandle
	  GetCurrentConsoleFont
	  GetNumberOfConsoleFonts
	  InvalidateConsoleDIBits
	  OpenConsoleW
	  BOOL SetConsoleCommandHistoryMode (DWORD => new mode ???)
	  SetConsoleCursor
	  DWORD WINAPI SetConsoleDisplayMode(HANDLE hConsoleHandle, DWORD
dwConsoleDisplayMode, LPDWORD dwPreviousDisplayMode); 
	       - seems to be an out handle
	       - 1 seems to mean full screen, while 0 ?? means windowed
	  SetConsoleFont
	  SetConsoleHardwareState
	  SetConsoleKeyShortcuts
	  SetConsoleMaximumWindowSize
	  SetConsoleMenuClose
	  SetConsoleNumberOfCommands[AW]
	  SetConsolePalette
	  SetLastConsoleEventActive
	  ShowConsoleCursor
	  VerifyConsoleIoHandle

	  DuplicateConsoleHandle
	  GetConsoleInputExeName[AW]
	  GetConsoleKeyboardLayoutName[AW]
	  ReadConsoleInputEx[AW]
	  SetConsoleIcon
	  SetConsoleInputExeName[AW])

from another topic, it seems that some functions have been a bit better 
documented. for example, the loading of installable drivers wasn't
properly
documented one year ago. it's a bit better now (I noticed it, because
there's
still bugs in wine about this, I fixed it in one part thinking a very
local
issue, whereas it's a broader one). that may be also some parts to add
to
the case

A+
-- 
---------------
Eric Pouech (http://perso.wanadoo.fr/eric.pouech/)
"The future will be better tomorrow", Vice President Dan Quayle

--------------------------------------------

From: Ove Kaaven <ovehk at ping.uio.no>

On 6 Feb 2002, Jeremy White wrote:

> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.

Are you talking about stuff that's only used internally by Windows (stuff
like that one DLL uses undocumented entry points of another DLL), or stuff
that's of use to windows extensions (explorer.exe replacements), or stuff
of use to applications (e.g. office)?

For stuff in the first category, I'd mention rpcrt4.dll (MS-RPC runtime).
It has like 500 entry points, and only like 150 of them are documented,
the rest is used internally by ole32/oleaut32 (to implement DCOM), or by
proxies generated with MIDL.exe. Granted, most of those entry points have
virtually self-documenting names and stuff, but it's still not obvious how
they're used, and the format strings the marshalling entry points use are
completely undocumented.

--------------------------------------------

From: "Gerhard W. Gruber" <sparhawk at gmx.at>

Jeremy White wrote:

> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.

I know of a bunch of functions in the rpcrt4.dll. Most of them starting
with Ndrxxx. many of these functions are nowhere even mentioned. I don't
know if they are of much help because usually they ar enot used
directly, but I worked for a company where we had problems with them
because they contain bugs and we couldn't get help and had to rewrite
the code (advised by MS).

If you need specific names I can dig some up if you want. Just drop me
an email or answer in the list.

--------------------------------------------

From: "Dmitry Timoshkov" <dmitry at baikal.ru>

"Jeremy White" <jwhite at codeweavers.com> wrote:

> I'm working with someone involved in the Microsoft trial,
> and they are looking for some information from the
> Wine team.
> 
> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.
> 
> I've asked around CodeWeavers, and we had a few examples,
> but we're in a bit of a time crunch (48 hours), and I was hoping to
> ask a broader audience to pitch in.

Jeremy, at that time I hadn't any examples. But after refreshing
my mind browsing ChangeLog, I have found my old battle with
FindResource and FindResourceEx. Their real behaviour is substantially
different from a documented one.

-- 
Dmitry.

--------------------------------------------

From: "Dmitry Timoshkov" <dmitry at baikal.ru>

"Jeremy White" <jwhite at codeweavers.com> wrote:

> Right!  I seem to remember that.  Can you give me a few
> concrete examples to arm Andrew with?

Unfortunately the URL which has pointed out to the wrong description
http://msdn.microsoft.com/library/books/devintl/s24b3_b.htm
is no more available on the ms' site.

I managed to find out only this one
http://support.microsoft.com/default.aspx?scid=kb;en;q169483
which apparently tries to describe the FindResource behaviour. Although
it also mentions FindResourceEx, there is no description for its behaviour
at all.

-- 
Dmitry.

--------------------------------------------

From: Andreas Mohr <andi at rhlx01.fht-esslingen.de>

On Wed, Feb 06, 2002 at 11:03:32AM -0600, Jeremy White wrote:
> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.

Off the top of my head:

#1 (not documented):
SETUPX !/SETUPAPI (only setupx.h available with incomplete info)

NTDLL should be rather low hanging fruits for complaints...
(it's not only our fault that our NT compatibility is so weak, I think)

SHLWAPI (seems most named functions are documented somewhere, but I can't
find any info about ordinal only functions)
Hmm, OTOH I can't even find docu for PathIsDirectoryEmpty/PathIsDirectoryEmptyA

SHDOCVW might be a bit useful, too (couldn't find anything for e.g.
SetShellOfflineState)

RPCRT4 could have a lot of undocumented functions.
I don't know much about it, but a first guess at RpcMgmtInqStats didn't give
me *any* useful results.
Ove should be the expert here.

#2 (substantially different):
>> 90% ;-)
(well, to be serious, the amount of very misleading info from MSDN is pretty
high, as can be witnessed from 400000 lines out of 1000000 lines in Wine code
consisting of MSDN comments :)

Oh, one additional note:
I think you really should post a final memo for everybody to review.
We would look pretty silly if it turned out that some functionality
we listed is actually pretty well-documented...

Thanks for this activity !

-- 
Andreas Mohr                        Stauferstr. 6, D-71272 Renningen, Germany
Tel. +49 7159 800604                http://home.nexgo.de/andi.mohr/

--------------------------------------------

From: "Guy L. Albertelli" <galberte at neo.lrun.com>

----- Original Message -----
From: "Jeremy White" <jwhite at codeweavers.com>
To: <wine-devel at winehq.com>
Sent: Wednesday, February 06, 2002 12:03 PM
Subject: Favor: I need examples of un or poorly documented APIs

> I'm working with someone involved in the Microsoft trial,
> and they are looking for some information from the
> Wine team.
>
> Specifically, they need clear examples of Windows APIs
> that are not documented, or cases where the actual
> working of an API is substantially different from the
> documented behavior.
>
> I've asked around CodeWeavers, and we had a few examples,
> but we're in a bit of a time crunch (48 hours), and I was hoping to
> ask a broader audience to pitch in.
>
> In an effort to keep this off topic traffic down,
> please reply just to me; if you like, I can post a summary
> of the results.

One example is from shlwapi.dll:

SHGetInverseCMAP  -  searching MSDN returns 0 hits. We know for a fact that
Outlook Express 5.x uses it and will not work without. Investigation shows
that it has 2 arguments.

There are literally 100's of other. Most are exported as ordinals only with
no documentation, but are required to run IE, OE, Outlook, Excel, etc.

Guy

--------------------------------------------

From: John Freed <john at integrita.com>

SETUPAPI is almost entirely undocumented