Question about replacing a stub...

[Gregory M. Turner]

On Sunday 28 December 2003 10:16 pm, Joshua Walker wrote:
> Hi all.
>      On my ever winding quest to fill in the win32 API
> documentation, I have found, I think, an intresting
> issue.
>      When the documentation is generated with
> c2man.pl, it checks the .spec file to see if the
> function is a stub or not. The problem is that if it
> is a stub, no documentation will be generated for that
> API. I've decieded to take it upon myself to "fill in
> the blankes" as it were, but I need to know if I'm
> doing this correctly.
>
> For my example I'm going to use the stubbed function
> "AdjustTokenGroups" that is found in avdapi32.dll.
>
> The fist thing I did was update the .spec file so
> c2man.pl will parse the function correctly.
>
> I changed
> @ stub AdjustTokenGroups
>
> to:
> @ stdcall AdjustTokenGroups (long long ptr long ptr
> ptr)

looks right (assuming you have the right calling convention).

> That allows c2man to parse the function. So now all I
> need to do is add that function to security.c. I added
> the following.
> ---------------------
> /******************************************************
>  * AdjustTokenGroups [ADVAPI32.@]
>  *
>  * Adjust the group privileges of an open token
> handle.
>  *
>  */
>
> BOOL WINAPI
>   AdjustTokenGroups(
>   HANDLE TokenHandle,
>   BOOL ResetToDefault,
>   PTOKEN_GROUPS NewState,
>   DWORD BufferLength,
>   PTOKEN_GROUPS PreviousState,
>   PDWORD ReturnLength
> )
>
>
> {
> }
> -------------------------
>
>
>
> And whamo-blamo, the documentation is generated...

hmm...

> Now, I'm not too hot on coding, did I just break
> something to get my API to document?

Yes, I'm afraid so.  These are excellent questions, so I've annotated each 
one.

> Should I be
> adding a fixme?

Yep.  The pattern to follow would be to put a "stub" fixme, you will see 
examples in the source... but see below for more caveats :)

> Should I be returning something even
> though it's an empty function?

Yes, "proper" C coding requires that any function with a return type other 
than "void" return something.  When you compile, you will see a new compiler 
warning about this.  Now, /what/ to return, may take some thinking, or, 
depending on the function, even some code to construct dummy structures, etc, 
even though there is no real functionality in your stub.

> I didn't compile it to
> see if it worked.

You probably would want to do so, if you take this approach.  The best (well, 
the quickest) way I know of is to compile a test with a Microsoft compiler, 
run it in Windows to make sure it works, and then run it in wine.  If you see 
your fixme, and there is no crash, then you probably have it right.

> The AdjustTokenGroups.html file that
> was generated says "Not defined in a Wine header. The
> function is either undocumented, or missing from
> Wine." Is it ok to leave that right now? Should I me
> putting something in a header file somewhere?

Often, you need to ("ought to" might be more accurate) define a function in a 
wine header somewhere.  The trick is to get the Platform SDK from Microsoft 
and grep for the function definition in their headers.   Now you know which 
header it belongs in :)  So open that header in your editor, and follow the 
existing coding conventions you see there (i.o.w., do not cut-and-paste from 
the Microsoft header).  However, the definition might already be in the wine 
headers (even though the function wasn't in wine), so grep there first.

Now, here comes the bad news: many Windows programs do the following:

o Reach the point where it would be appropriate to call XYZFunction
o Call GetProcAddress for XYZFunction
o branch: if it comes back as NULL, assume it does not exist in this version 
of windows.  Go down codepath A.  Otherwise, codepath B.

This means, sometimes, you could change the behavior of a program, by 
implementing the stub.  This has been a problem in wine before.  It seems 
tempting to just create stubs for everything, but this can break working apps 
(or fix broken ones -- it's a balancing act).

With a function like AdjustTokenGroups, which I presume is NT-specific, I'm 
afraid Alexandre is probably going to reject the patch unless the function 
has some kind of meaningful implementation, or a stated reason to be there.

So, you have a couple choices:

1) Convince somebody to change the documentation thingy to work even though 
there's a stub (or make this change yourself)
2) Stick to documenting functions wine already has.

Your call, but I suggest route #2: There are many, many, many functions 
already implemented in wine, but undocumented.  Enough to keep you busy for 
years, I would bet.  Furthermore, the functions implemented in wine are the 
ones that are going to be used most frequently in Windows apps (for obvious 
reasons).

Glad to see you are still at this -- good luck!

-- 
gmt

"It is to be the assent and ratification of the several States,
derived from the supreme authority in each State, the authority
of the people themselves.  The act, therefore, establishing the
Constitution, will not be a NATIONAL, but a FEDERAL act." --James
Madison, Federalist No. 39