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!