RE: [ros-dev] Undocumented APIs

[Murphy, Ged (Bolton)]

Casper Hornstrup wrote:
> "If an API or a particular behaviour of an API which is part of the
> Windows(R) operating system is not publicly documented by 
> Microsoft, then
> the API or the particular behaviour of the API may only be 
> implemented in
> ReactOS if there is documentation of published software which 
> depend on the
> API or the particular behaviour of the API, and which is not only
> distributed with the Windows(R) operating system. The 
> documentation must be
> available in the repository."

What if a particular API is required for a particular program to work, but
that API is undocumented by both Microsoft and the owner of the said
program?

Also, what about using code from 3rd parties which might contain
undocumented API's, like Wine for instance?

Ged.

************************************************************************
The information contained in this message or any of its
attachments is confidential and is intended for the exclusive
use of the addressee. The information may also be legally
privileged. The views expressed may not be company policy,
but the personal views of the originator. If you are not the
addressee, any disclosure, reproduction, distribution or other
dissemination or use of this communication is strictly prohibited.
If you have received this message in error, please contact
[e-mail] 
mailto:[e-mail] and then delete this message.

Exide Technologies is an industrial and transportation battery
producer and recycler with operations in 89 countries.
Further information can be found at www.exide.com

[Casper Hornstrup]

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On
> Behalf Of Murphy, Ged (Bolton)
> Sent: 31. januar 2006 11:00
> To: 'ReactOS Development List'
> Subject: RE: [ros-dev] Undocumented APIs
>
> What if a particular API is required for a particular program to work, but
> that API is undocumented by both Microsoft and the owner of the said
> program?

We don't need documentation from the author of the software that needs the
API. We just need to document that the software needs the API.
> Also, what about using code from 3rd parties which might contain
> undocumented API's, like Wine for instance?

Wine has a similar policy, but in general we should try to fix issues
upstream. If we can't do that, then so be it. Forking source code isn't
usually worth it.

Casper

[Thomas Weidenmueller]

Casper Hornstrup wrote:
> Wine has a similar policy, but in general we should try to fix issues
> upstream. If we can't do that, then so be it. Forking source code isn't
> usually worth it.

The problem I see is that wine has a lot less undocumented stuff by
definition. They don't need to implement the lower levels that we do
need. Unfortunately those lower levels are much less thoroughly
documented, but IMO we should at least get the publicly known interfaces
right. I'm not talking about internal things.

- Thomas

[Casper Hornstrup]

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On
> Behalf Of Thomas Weidenmueller
> Sent: 31. januar 2006 12:20
> To: ReactOS Development List
> Subject: Re: [ros-dev] Undocumented APIs
>
> Casper Hornstrup wrote:
> > Wine has a similar policy, but in general we should try to fix issues
> > upstream. If we can't do that, then so be it. Forking source code isn't
> > usually worth it.
>
> The problem I see is that wine has a lot less undocumented stuff by
> definition. They don't need to implement the lower levels that we do
> need. Unfortunately those lower levels are much less thoroughly
> documented, but IMO we should at least get the publicly known interfaces
> right. I'm not talking about internal things.
> Thomas

Why implement something which is not used? From a survival POV, ReactOS is
better off doing what is needed instead of doing what is not needed.

Casper

[Thomas Weidenmueller]

Casper Hornstrup wrote:
> Why implement something which is not used? From a survival POV, ReactOS is
> better off doing what is needed instead of doing what is not needed.

Good luck. From a survival POV, we shouldn't even implement anything not
documented publicly. Okay, then let's reinvent a native api to the
kernel. If it turns out an application or driver really depends one one
we're in deep sh... Not that I cared.

- Thomas

[Casper Hornstrup]

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On
> Behalf Of Thomas Weidenmueller
> Sent: 31. januar 2006 13:12
> To: ReactOS Development List
> Subject: Re: [ros-dev] Undocumented APIs
>
> Casper Hornstrup wrote:
> > Why implement something which is not used? From a survival POV, ReactOS
>
> is
> > better off doing what is needed instead of doing what is not needed.
>
> Good luck. From a survival POV, we shouldn't even implement anything not
> documented publicly. Okay, then let's reinvent a native api to the
> kernel. If it turns out an application or driver really depends one one
> we're in deep sh... Not that I cared.
> Thomas

If you define deep sh... as having a reason to implement it, then yes.

Casper

[D. Hazelton]

On Tuesday 31 January 2006 07:33, Casper Hornstrup wrote:
> > -----Original Message-----
> > From: [e-mail] [mailto:[e-mail]] On
> > Behalf Of Thomas Weidenmueller
> > Sent: 31. januar 2006 13:12
> > To: ReactOS Development List
> > Subject: Re: [ros-dev] Undocumented APIs
> >
> > Casper Hornstrup wrote:
> > > Why implement something which is not used? From a survival POV, ReactOS
> >
> > is
> > > better off doing what is needed instead of doing what is not needed.
> >
> > Good luck. From a survival POV, we shouldn't even implement anything not
> > documented publicly. Okay, then let's reinvent a native api to the
> > kernel. If it turns out an application or driver really depends one one
> > we're in deep sh... Not that I cared.

According to the legal repercussions that came about from the first MS//US DOJ 
lawsuit there are to be _no_ undocumented function calls within the Microsoft 
operating systems. If you are worried about function calls from the older 
windows releases, I believe there is enough documentation out there to 
implement those without requiring reverse engineering.

For the rest, if MS hasn't documented a function it is using then they should 
be in deep sh.. over that. IANAL, but IIRC, the first lawsuit against them 
covered undocumented functions and stated that MS could not have them as it 
was a monopolistic move. By that it meant that MS was not giving other 
companies a fair chance to compete, so all functions had to be documented.

There may be hundreds or even thousands of structures with undocumented 
members, but, personally, it might be good to do something like fix the value 
of those members to known values - either by writing a program to dump those 
values or just by picking a number at random. At some point the use of those 
values should become clear and proper values can then begin to be inserted by 
the code, as well as having a proper name given to the member.

Someone mentioned that regedit might be a piece of code which is the only one 
to use a function call... All modern windows releases ship with two versions 
of regedit, regedit.exe and regedt32.exe - and there have been several 
third-party replacements for regedit released. If possible it might be best 
for ReactOS to ship with one of the free third-party regedit's - this would 
save development time and the author of said tool might have information on 
undocumented API's.

When I've finished my other projects (one of which I'm hoping to have 
functioning in ReactOS) and have more time free I'll start trolling bugzilla 
and offering my help in keeping the bugs there cleaned up...

D. Hazelton

[Jonathan Wilson]

> According to the legal repercussions that came about from the first MS//US DOJ 
> lawsuit there are to be _no_ undocumented function calls within the Microsoft 
> operating systems. If you are worried about function calls from the older

There are MANY function calls inside even the most basic low-level 
libraries for which no documentation exists.
For example, in user32.dll is the function RegisterUserAPIHooks. That is 
totally undocumented.

That is just one example.
However, it is one of the many undocumented functions that only exist to 
allow components of windows to talk to each other (in this case it exists 
only to allow uxtheme/comctl32 to hook user32 and do non-client-area themeing).
The question is, do we implement such functions?

[Sebastiaan Roodenburg]

> For example, in user32.dll is the function RegisterUserAPIHooks. That is
> totally undocumented.
>
> However, it is one of the many undocumented functions that only exist to
> allow components of windows to talk to each other (in this case it exists
> only to allow uxtheme/comctl32 to hook user32 and do
> non-client-area themeing).
> The question is, do we implement such functions?

Well... If it is exported by the DLL then it should be exported. But if it
is undocumented I don't think it should be implemented until an application
is found which uses it. Not having a RegisterUserAPIHooks implementation
doesn't make ReactOS run less windows programs. I would suggest something
like introducing a "UNDOCUMENTED;" macro (like the UNIMPLEMENTED; macro) to
track down used undocumented functions...

Sebastiaan

[Robert Shearman]

Thomas Weidenmueller wrote:
> Casper Hornstrup wrote:
> > Why implement something which is not used? From a survival POV, ReactOS is
> > better off doing what is needed instead of doing what is not needed.
>
> Good luck. From a survival POV, we shouldn't even implement anything not
> documented publicly. Okay, then let's reinvent a native api to the
> kernel. If it turns out an application or driver really depends one one
> we're in deep sh... Not that I cared.

If you think a driver or application will depend on something then you 
can write a test program/driver and include it in the ReactOS tree. That 
would seem to satisfy the requirements. Black box testing is also 
"cleaner" (and usually faster) than clean-room reverse engineering.
-- 
Rob Shearman

[Thomas Weidenmueller]

Robert Shearman wrote:
> If you think a driver or application will depend on something then you
> can write a test program/driver and include it in the ReactOS tree. That
> would seem to satisfy the requirements. Black box testing is also
> "cleaner" (and usually faster) than clean-room reverse engineering.

I'm perfectly ok with that. I don't have problems providing tests for
the stuff I implement(ed).

I may have missed parts of the discussions because I'm a bit short on
time, so I apologize. It just seemed that unless a 3rd party application
exists it could never be OK to implement something (more or less)
undocumented.

- Thomas

[Royce Mitchell III]

Thomas Weidenmueller wrote:
> I may have missed parts of the discussions because I'm a bit short on
> time, so I apologize. It just seemed that unless a 3rd party application
> exists it could never be OK to implement something (more or less)
> undocumented.

Perhaps this is silly or an oversimplification, but if we can't find a 
program that uses an undocumented API, then what's the point in 
implementing it? After all, if you're able to get ReactOS to run every 
app you care about, then haven't we succeeded?

[Thomas Weidenmueller]

Royce Mitchell III wrote:
> Perhaps this is silly or an oversimplification, but if we can't find a
> program that uses an undocumented API, then what's the point in
> implementing it? After all, if you're able to get ReactOS to run every
> app you care about, then haven't we succeeded?

I implemented a large number of APIs probably only very few applications
use. I usually did that out of boredom or just for fun. Most of them are
documented but I think the same applies to "undocumented" APIs. It's not
a problem for me to provide test cases but not being allowed to
implement them at all is a bit too much IMO. I understand we have to be
paranoid to a certain extent, but IMO this rather concerns internal
implementations than more or less public interfaces. It's something I
didn't like WINE for. I found it quite odd having to find a "real-world"
application that depends on something, and not even a test application
would be sufficient to justify a change or implementation.

- Thomas

[Casper Hornstrup]

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On
> Behalf Of Thomas Weidenmueller
> Sent: 31. januar 2006 16:52
> To: ReactOS Development List
> Subject: Re: [ros-dev] Undocumented APIs
>
> I implemented a large number of APIs probably only very few applications
> use. I usually did that out of boredom or just for fun.
> Thomas

Which is of course fine, but since ReactOS has no use for it, why commit it?
It isn't needed to meet the goals of ReactOS.

Casper

[Thomas Weidenmueller]

Casper Hornstrup wrote:
> Which is of course fine, but since ReactOS has no use for it, why commit it?
> It isn't needed to meet the goals of ReactOS.

Of cours it's not needed to meet the goals. Not everything contributed
was essential to meet the goals. Many tools aren't really necessary but
they exist because someone thought it might be a good idea to have them.
What was I supposed to do? Trash the patches? Call that a waste of efforts.

- Thomas

[Steven Edwards]

Hi,

On 1/31/06, Thomas Weidenmueller [e-mail] wrote:
> Of cours it's not needed to meet the goals. Not everything contributed
> was essential to meet the goals. Many tools aren't really necessary but
> they exist because someone thought it might be a good idea to have them.
> What was I supposed to do? Trash the patches? Call that a waste of efforts.

I think that if you want to implement a new api just for fun you
should be free do so however I 100% agree with Caspers point of view.
I hightly doubt your implementing a new API without any documentation
on MSDN or somewhere on the net even if you can't find a 3rd party
application so just quote your source for the API in the documentation
tree and that should be good enough.

--
Steven Edwards - ReactOS and Wine developer

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Thomas Weidenmueller]

Steven Edwards wrote:
> I think that if you want to implement a new api just for fun you
> should be free do so however I 100% agree with Caspers point of view.
> I hightly doubt your implementing a new API without any documentation
> on MSDN or somewhere on the net even if you can't find a 3rd party
> application so just quote your source for the API in the documentation
> tree and that should be good enough.

I understand that. However, I only implemented documented Vista APIs.
Pretty much all of them are already documented in the Platform SDK, a
few are documented in some PDC presentations. Of course there's no real
world application that already uses them because the OS isn't even released.

The point is their implementation in most cases is based on the (mostly)
officially undocumented native API. But since wine also starts
implementing them I guess it's OK, although only very few applications
might use them.

- Thomas

[Casper Hornstrup]

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On
> Behalf Of Thomas Weidenmueller
> Sent: 31. januar 2006 19:36
> To: ReactOS Development List
> Subject: Re: [ros-dev] Undocumented APIs
>
> Steven Edwards wrote:
> > I think that if you want to implement a new api just for fun you
> > should be free do so however I 100% agree with Caspers point of view.
> > I hightly doubt your implementing a new API without any documentation
> > on MSDN or somewhere on the net even if you can't find a 3rd party
> > application so just quote your source for the API in the documentation
> > tree and that should be good enough.
>
> I understand that. However, I only implemented documented Vista APIs.
> Pretty much all of them are already documented in the Platform SDK, a
> few are documented in some PDC presentations. Of course there's no real
> world application that already uses them because the OS isn't even
> released.

Then the APIs are "publicly documented by Microsoft" and I don't see the
relevance of using them as an argument in this thread.

Casper

[art yerkes]

On Tue, 31 Jan 2006 17:17:30 +0100
"Casper Hornstrup" [e-mail] wrote:
> > -----Original Message-----
> > From: [e-mail] [mailto:[e-mail]] On
> > Behalf Of Thomas Weidenmueller
> > Sent: 31. januar 2006 16:52
> > To: ReactOS Development List
> > Subject: Re: [ros-dev] Undocumented APIs
> >
> > I implemented a large number of APIs probably only very few applications
> > use. I usually did that out of boredom or just for fun.
> > Thomas
>
> Which is of course fine, but since ReactOS has no use for it, why commit it?
> It isn't needed to meet the goals of ReactOS.
>
> Casper

I don't agree with this sentiment at all.  We've always before been proactive
about implementing at least visible parts of the API to make it more likely
that applications we didn't know about would have a chance to work.  I think
that's a reasonable way to work, especially if you're working in an area you've
got a good understanding of.
-- 
Here's a simple experiment. Stand on a train track between two
locomotives which are pushing on you with equal force in opposite
directions. You will exhibit no net motion. None the less, you may
soon begin to notice that something important is happening.
-- Robert Stirniman

[James Tabor]

art yerkes wrote:
> On Tue, 31 Jan 2006 17:17:30 +0100
> "Casper Hornstrup" [e-mail] wrote:
> > > -----Original Message-----
> > > From: [e-mail] [mailto:[e-mail]] On
> > > Behalf Of Thomas Weidenmueller
> > > Sent: 31. januar 2006 16:52
> > > To: ReactOS Development List
> > > Subject: Re: [ros-dev] Undocumented APIs
> > >
> > > I implemented a large number of APIs probably only very few applications
> > > use. I usually did that out of boredom or just for fun.
> > > Thomas
> >
> > Which is of course fine, but since ReactOS has no use for it, why commit it?
> > It isn't needed to meet the goals of ReactOS.
> >
> > Casper
>
> I don't agree with this sentiment at all.  We've always before been proactive
> about implementing at least visible parts of the API to make it more likely
> that applications we didn't know about would have a chance to work.  I think
> that's a reasonable way to work, especially if you're working in an area you've
> got a good understanding of.

I agree with arty! I'm sick and tired about this anti-Reactos points of view! It's
obvious now, we have some developers not interested in making Reactos work with other
applications.

Exception just the bootsectors, but I'm not starting until I see the modified IP policy

[Robert Shearman]

James Tabor wrote:
> art yerkes wrote:
> > On Tue, 31 Jan 2006 17:17:30 +0100
> > "Casper Hornstrup" [e-mail] wrote:
> > > > I implemented a large number of APIs probably only very few 
> > > > applications
> > > > use. I usually did that out of boredom or just for fun.
> > > > Thomas
> > >
> > > Which is of course fine, but since ReactOS has no use for it, why 
> > > commit it?
> > > It isn't needed to meet the goals of ReactOS.
> > >
> > > Casper
> >
> > I don't agree with this sentiment at all.  We've always before been 
> > proactive
> > about implementing at least visible parts of the API to make it more 
> > likely
> > that applications we didn't know about would have a chance to work.  
> > I think
> > that's a reasonable way to work, especially if you're working in an 
> > area you've
> > got a good understanding of.
>
> I agree with arty! I'm sick and tired about this anti-Reactos points 
> of view! It's
> obvious now, we have some developers not interested in making Reactos 
> work with other
> applications.

What's the point in making ReactOS work with all applications if people 
are too scared to use it because of the methods used to implement it?
-- 
Rob Shearman

[Alex Ionescu]

Robert Shearman wrote:
> James Tabor wrote:
> > art yerkes wrote:
> > > On Tue, 31 Jan 2006 17:17:30 +0100
> > > "Casper Hornstrup" [e-mail] wrote:
> > > > > I implemented a large number of APIs probably only very few 
> > > > > applications
> > > > > use. I usually did that out of boredom or just for fun.
> > > > > Thomas
> > > >
> > > > Which is of course fine, but since ReactOS has no use for it, why 
> > > > commit it?
> > > > It isn't needed to meet the goals of ReactOS.
> > > >
> > > > Casper
> > >
> > > I don't agree with this sentiment at all.  We've always before been 
> > > proactive
> > > about implementing at least visible parts of the API to make it more 
> > > likely
> > > that applications we didn't know about would have a chance to work.  
> > > I think
> > > that's a reasonable way to work, especially if you're working in an 
> > > area you've
> > > got a good understanding of.
> >
> > I agree with arty! I'm sick and tired about this anti-Reactos points 
> > of view! It's
> > obvious now, we have some developers not interested in making Reactos 
> > work with other
> > applications.
>
> What's the point in making ReactOS work with all applications if 
> people are too scared to use it because of the methods used to 
> implement it?

I don't see people afraid of using IBM products... or installing 
ATI/NVIDIA drivers... or installing Norton Antivirus...actually, quite a 
lot of people and big corporations use IBM software on their ATI 
videocard, while protected by NAV.

Best regards,
Alex Ionescu

[Steven Edwards]

On 2/1/06, Alex Ionescu [e-mail] wrote:
> > What's the point in making ReactOS work with all applications if
> > people are too scared to use it because of the methods used to
> > implement it?
>
> I don't see people afraid of using IBM products... or installing
> ATI/NVIDIA drivers... or installing Norton Antivirus...actually, quite a
> lot of people and big corporations use IBM software on their ATI
> videocard, while protected by NAV.

Those corporations have the money to defend the customers in the event
of a SCO type lawsuit. Remember SCO sued Delmar-Chrysler and Autozone
for migrating to Linux from Sco OpenServer. The autozone deal was a
Redhat customer. I assure you any code they write for the Linux kernel
fails under our proposed standard for clean-room reverse enginering if
they did get any ideas from Unix.

--
Steven Edwards - ReactOS and Wine developer

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Brandon Turner]

art yerkes wrote:
> On Tue, 31 Jan 2006 17:17:30 +0100
> "Casper Hornstrup" [e-mail] wrote:
> > > -----Original Message-----
> > > From: [e-mail] [mailto:[e-mail]] On
> > > Behalf Of Thomas Weidenmueller
> > > Sent: 31. januar 2006 16:52
> > > To: ReactOS Development List
> > > Subject: Re: [ros-dev] Undocumented APIs
> > >
> > > I implemented a large number of APIs probably only very few applications
> > > use. I usually did that out of boredom or just for fun.
> > > Thomas
> >
> > Which is of course fine, but since ReactOS has no use for it, why commit it?
> > It isn't needed to meet the goals of ReactOS.
> >
> > Casper
>
> I don't agree with this sentiment at all.  We've always before been proactive
> about implementing at least visible parts of the API to make it more likely
> that applications we didn't know about would have a chance to work.  I think
> that's a reasonable way to work, especially if you're working in an area you've
> got a good understanding of.

++

Brandon