callbacks...

[Ryan C. Gordon]

Latest subversion has some added APIs for callbacks.

Anything that returns a string list now has a callback equivalent, which
can be handy if you want to handle the data one item at a time, or
filter the data, or allocate copies in a more appropriate way.

Internally, the original APIs now call the callback versions, too, and
use their internal callback to create the string lists that the
application expects.

The non-callback versions still exist, and are not considered
deprecated. Use whichever makes you more comfortable.

Usual good-vibes apply: this cleaned up the archivers and platform
drivers a little, simplified things, and trimmed out some malloc
pressure, blahblahblah.

To use them:

Before you'd do something like this:

 char **cds = PHYSFS_getCdRomDirs();
 char **i;
 
 for (i = cds; *i != NULL; i++)
     printf("cdrom dir [%s] is available.\n", *i);
 
 PHYSFS_freeList(cds);


Now you can do this:

 void cdCallback(void *data, const char *str)
 {
    printf("cdrom dir [%s] is available.\n", str);
 }

 PHYSFS_getCdRomDirsCallback(cdCallback, NULL);

(data) is callback-specific data, in case you need to feed it something,
like, say, a File Selector Dialog object from your GUI or whatever.

You can also use a callback version of PHYSFS_getSearchPath() and
PHYSFS_enumerateFiles().

Here's the tricky part:
- PHYSFS_getCdRomDirsCallback() doesn't promise that data will come in a
specific order (but neither did PHYSFS_getCdRomDirs()). Generally this
is only a problem on Windows and OS/2, where you want to have "A:\"
reported before "B:\", etc...those platform drivers _do_ guarantee
alphabetical order by the nature of their implementation. The Unix and
Mac implementations are feeding the callback with data in whatever order
it was given to them by the OS, though, which may not be the
alphabetical order of the real filesystem's mount points.

- PHYSFS_getSearchPathCallback() returns data in the same order as
PHYSFS_getSearchPath() does...the order that the search path is
organized by the app (highest priority archives returned first).

- PHYSFS_enumerateFilesCallback() is nasty. Not only does it not
guarantee that the results will be fed to the callback sorted in any
order, it also doesn't guarantee that you won't get duplicates. This
can't be avoided without allocating memory and maintaining all the data
the archivers feed back, which defeats the purpose of a callback. If
this is important to you, you'll either have to check for dupes yourself
and/or sort the final list, or use the original PHYSFS_enumerateFiles(),
which does this work for you.

Comments welcome. The code in Subversion works and didn't make valgrind
barf with a brief test, but every platform driver was touched and I
haven't verified that everything still compiles on anything but Linux.

Discussion on the new API calls is welcome, too. I'm not sold on it if
there's a better idea.

--ryan.