Docs for g_file_enumerator_next_files_async () are unclear about end condition
Submitted by Owen Taylor
The docs for g_file_enumerator_next_files_async() are unclear about how you are supposed to know that you've reached the end of the list of files.
Both Matthias and I read:
The callback can be called with less than num_files files in case of error or at the end of the enumerator
as saying that a short return means you are at the end, but you actually need to call the function until you get an empty list.
<alex_away> owen: yes, or you can call it again and get NULL
<alex_away> owen: i guess its not quite 100% right to stop on short read
<alex_away> owen: as you then don't know if your eof or some other error
<alex_away> but, you're unlikely to care
<owen> but if you have some other error, the error is set, right?
<alex_away> No, gio in general don't report a result + an error
<alex_away> like in read() if you read 20 bytes correctly and then get an error we return 20 bytes as a short read, and the error on next read
<alex_away> same with readdir
<owen> Ah, yeah, it says that in the case of error you have to call it again...
Since docs do describe the extra call in the case of error, it's logically possible to figure it out given enough thought. But the section should be rewritten to say something like:
At the end of the enumerator is reached or an error occurs, the callback will be called with an empty list. (In this case, the previous call to g_file_enumerator_next_files_async() will frequently have returned less than num_files items.)
The short read is a detail, the empty read is the main point, not the other way around.