SHLWAPI pre-submit questions

[Jon Griffiths]

Hi,

I've been hacking on SHLWAPI.dll for a couple of months now while
holidaying around Thailand, using a beaten up laptop. Since I just
obtained free use of a real machine with a good net connection, I
want to start submitting my work but I thought I'd clear up a few
style issues beforehand:

1. Is it OK to give meaningful names to undocumented functions?
e.g. SHLWAPI_1/2 => UrlGetInfoA/W
       SHLWAPI_5/6 => PathFindOnPathExA/W

I want to do this where the names are no-brainers, as in the case
above, and the functions are referenced by the dll internally.

2. Is it OK to sync shlwapi.h with the windows version ?

e.g. Remove undocumented entries
       Remove its dependence on obj_base.h (windows has none)
       Add the function exclusion defines as per windows

I assume this is fine, but doing this causes the next question -

3. How to deal with shared undocumented functions?

e.g. StrRetToBufA/W is used by shell32, but should not defined in
shlwapi.h.

Here there are 4 Choices:
1. Define twice (Ugly)
2. Put into a new wine/undocshlwapi.h (Seems that these are
depreciated?)
3. Define anyway  (Im not a fan of having undoc functions in public
headers)
4. Have shell32 functions #include "../shlwapi/internal.h" (A little
unclean)

I'd like to go for 4, any objections?

I'll start feeding in the new function implementations over the next
little while, once the structure is sorted.

Cheers,
Jon

=====
"Don't wait for the seas to part, or messiahs to come;
 Don't you sit around and waste this chance..." - Live

[e-mail]

__________________________________________________
Do You Yahoo!?
Buy the perfect holiday gifts at Yahoo! Shopping.
http://shopping.yahoo.com

[Andreas Mohr]

On Tue, Dec 04, 2001 at 03:12:10AM -0800, Jon Griffiths wrote:
> Hi,
>
> I've been hacking on SHLWAPI.dll for a couple of months now while
> holidaying around Thailand, using a beaten up laptop. Since I just
> obtained free use of a real machine with a good net connection, I
> want to start submitting my work but I thought I'd clear up a few
> style issues beforehand:
> - Is it OK to give meaningful names to undocumented functions?
>
> e.g. SHLWAPI_1/2 => UrlGetInfoA/W
>        SHLWAPI_5/6 => PathFindOnPathExA/W
>
> I want to do this where the names are no-brainers, as in the case
> above, and the functions are referenced by the dll internally.

Ugh, I wouldn't do this.
At least mark the function name clearly as being undocumented.
That's the way to go IMHO.
Otherwise you really pollute the undoc ratio of Me$$y$oft ;)
(no, really: that way nobody will be able to tell any more whether
a function is undocumented or not)
> - Is it OK to sync shlwapi.h with the windows version ?
>
> e.g. Remove undocumented entries
>        Remove its dependence on obj_base.h (windows has none)
>        Add the function exclusion defines as per windows

I'm not sure whether I'm qualified to talk about this,
but I think it's ok.
I would be rather careful about removing undocumented entries,
though.
> I assume this is fine, but doing this causes the next question -
> - How to deal with shared undocumented functions?
>
> e.g. StrRetToBufA/W is used by shell32, but should not defined in
> shlwapi.h.
>
> Here there are 4 Choices:
> - Define twice (Ugly)
> - Put into a new wine/undocshlwapi.h (Seems that these are
>
> depreciated?)
> 3. Define anyway  (Im not a fan of having undoc functions in public
> headers)
> 4. Have shell32 functions #include "../shlwapi/internal.h" (A little
> unclean)
>
> I'd like to go for 4, any objections?

No opinion here ;)

*Great* work, BTW !

[Francois Gouget]

On Tue, 4 Dec 2001, Jon Griffiths wrote:
> Hi,
>
> I've been hacking on SHLWAPI.dll for a couple of months now while
> holidaying around Thailand, using a beaten up laptop. Since I just
> obtained free use of a real machine with a good net connection, I
> want to start submitting my work but I thought I'd clear up a few
> style issues beforehand:

[...]
> - Is it OK to sync shlwapi.h with the windows version ?

Yes, it's always a good idea to have the headers match more closely
their windows cousins.
> - How to deal with shared undocumented functions?
>
> e.g. StrRetToBufA/W is used by shell32, but should not defined in
> shlwapi.h.

Actually it's no longer the case and there is a nice comment that
explains why (thanks Guy :-).

Guy has been doing a lot of work on SHLWAPI lately. Since you have
been working on it while being disconnected from the net for so long (my
assumption since you were on holiday abroad, I may be wrong), it's
probably worth a good check to make sure there's no conflict with Guy's
work.
> Here there are 4 Choices:
> - Define twice (Ugly)
> - Put into a new wine/undocshlwapi.h (Seems that these are
>
> depreciated?)
> 3. Define anyway  (Im not a fan of having undoc functions in public
> headers)
> 4. Have shell32 functions #include "../shlwapi/internal.h" (A little
> unclean)

If there are still undocumented functions that need to be shared,
then I would go for either 2 or 5:

5. define the functions in shlwapi.h inside an '#ifdef __WINE__'.

--
Francois Gouget         [e-mail]        http://fgouget.free.fr/
                  In a world without fences who needs Gates?

[Alexandre Julliard]

Jon Griffiths  writes:
> - Is it OK to give meaningful names to undocumented functions?
>
> e.g. SHLWAPI_1/2 => UrlGetInfoA/W
>        SHLWAPI_5/6 => PathFindOnPathExA/W

No, this will cause major confusion. What you can do is create a
SHLWAPI_UrlGetInfo internal function that is called both by SHLWAPI_1
and by other functions that need it.
> - How to deal with shared undocumented functions?
>
> e.g. StrRetToBufA/W is used by shell32, but should not defined in
> shlwapi.h.
>
> Here there are 4 Choices:
> - Define twice (Ugly)
> - Put into a new wine/undocshlwapi.h (Seems that these are
>
> depreciated?)
> 3. Define anyway  (Im not a fan of having undoc functions in public
> headers)
> 4. Have shell32 functions #include "../shlwapi/internal.h" (A little
> unclean)
>
> I'd like to go for 4, any objections?

3. is much better. As long as the functions are actually exported from
shlwapi, there's no reason not to export the prototypes too. Besides,
by being implemented in Wine they are now documented <g>

[Jon Griffiths]

Hiya,

Thanks for your prompt responses. Based on yourfeedback I'll:

1. Create internal functions with meaningful names and call them
   when ordinal calls are used within the DLL (A plus to this is
   that the ordinal functions can stay in ordinal.c, and
   the implementation can go into the appropriate file, eg. path.c).

2. Make shlwapi.h correspond to its windows cousin, except that:
   -Any functions exported by name get defined too, along with
   structures needed to call them (I think we should wrap these in
   "#if defined (__WINE__) || defined (SHLWAPI_UNDOC)", but that can
   wait).
   -All ordinal functions get defined in shlwapi/ordinal.h
   -Internal functions go into shlwapi/ordinal.h too.

There shouldn't be any conflicts with Guys work: my tree is so out of
date I have to adapt everything anyway, so I'll make the changes as
non-gratuitous as possible. The first patch only might be a little
large due to the header re-org.

Header patches coming first, followed by code in managable chunks.
I've been dying to get this code out in case someone nicks my laptop
or it blows up (its 7 years old, the poor thing)...

Cheers,
Jon

=====
"Don't wait for the seas to part, or messiahs to come;
 Don't you sit around and waste this chance..." - Live

[e-mail]

__________________________________________________
Do You Yahoo!?
Buy the perfect holiday gifts at Yahoo! Shopping.
http://shopping.yahoo.com

[Alexandre Julliard]

Jon Griffiths  writes:
> - Make shlwapi.h correspond to its windows cousin, except that:
> -Any functions exported by name get defined too, along with
> structures needed to call them (I think we should wrap these in
> "#if defined (__WINE__) || defined (SHLWAPI_UNDOC)", but that can
> wait).

I'm not sure if this is what you mean or not, but you should only
define the functions and structures that are actually needed by other
dlls; there's no need to put every single undocumented function in
there.

[Jon Griffiths]

> I'm not sure if this is what you mean or not, but you should only
> define the functions and structures that are actually needed by
> other dlls; there's no need to put every single undocumented

function in
> there.

I was just going to put the functions exported by name there. Beyond
the url functions (which are used elsewhere), there are only a couple
of others to add.

Cheers,
Jon

=====
"Don't wait for the seas to part, or messiahs to come;
 Don't you sit around and waste this chance..." - Live

[e-mail]

__________________________________________________
Do You Yahoo!?
Send your FREE holiday greetings online!
http://greetings.yahoo.com

[Guy L. Albertelli]

----- Original Message -----
From: "Jon Griffiths" 
To: 
Cc: "Guy L. Albertelli" 
Sent: Tuesday, December 04, 2001 6:12 AM
Subject: SHLWAPI pre-submit questions
> - Is it OK to sync shlwapi.h with the windows version ?
>
> e.g. Remove undocumented entries

Be careful here, some of the entries took a long time to find since it is
not that they are undocumented, but just not well documented (in fact I only
found some of the #defines in Borlands lastest bcc).
>    Remove its dependence on obj_base.h (windows has none)

This would be good.

[snip]
> - Put into a new wine/undocshlwapi.h (Seems that these are
>
> depreciated?)

Jon,

I created "shlwapi/ordinal.h" for that very purpose (since ordinal.c has the
"undocumented" routines) and defined the structures for _1 and _2 in it.
Note that _1 and _2 are used by other parts of shlwapi.

Guy