Documentation of FindFilesWithPattern API callback

robert-j commented 3 years ago

It took me a while to realize that FindFilesWithPattern is sometimes called with no wildcards contained in its SearchPattern argument.

This can happen when programs are invoking Windows' API FindFirstFile() on a file name w/out wildcards.

Why is it good to know that this case may happen?

Well, network file systems clients, whose protocol does not implement something like FindFiles(pattern), are forced to read the whole directory, filter the names locally with DokanIsNameInExpression() and return just one entry which they could have returned beforehand right away :)

I'm now using this in my code:

if (!wcspbrk(searchPattern, L"*?\"<>")) { short-circuit ... } else { full-blown-read-dir-and-filter }

which is an immense speedup for certain Windows programs that seem to misuse FindFirstFile() a lot.

It would be great if the FindFilesWithPattern's documentation would state that SearchPattern may include meta characters, and that SearchPattern may be a normal file name as well.

Liryna commented 3 years ago

@robert-j Hi,

Thank you for your feedback!

Indeed this could be improved in the documentation. Would you be interested to do a PR or your prefer that I do it ?

Karandra commented 3 years ago

I would also document the fact that if a file system doesn't implement FindFilesWithPattern and only implements FindFiles Dokany will collect all returned file info structures into a vector and will filter it against a search pattern itself. This is nice and all but negatively impacts directory enumeration performance. At least this is what the v2.x branch does.

Speaking about that vector I'd also wanted to have a way to preallocate that vector during that call (like std::vector<T>::reserve) but that's another story.

Liryna commented 3 years ago

dokan-dev / dokany

Documentation of FindFilesWithPattern API callback #972