New file access API

[paxswill]

With proj_api.h being removed (#837) in the future, are there plans for an alternative file access API to replace projFileAPI, pj_ctx_set_fileapi and pj_ctx_get_fileapi? For my particular use case, I'm bundling the normal data files into a framework for iOS/macOS, and providing an alternative open file function that searches in the bundle resources for those files.

[kbevers]

Nothing is decided yet but I would say that it is likely to happen, yes. It has been very difficult to determine if anyone was actually using that part of the code. Several enquiries has been made on the mailing list with no positive feedback, so it has not been a priority to build that into the new API so far. Since then a few cases of it being used has surfaced (including this) so at least there is now some evidence that it is used and not just a few thousand lines of unused code.

It would be fairly easy to wrap the existing code into new functions in the proj.h API but that is not necessarily the best way to go. I know that @busstoptaktik has been missing a fgetc function in the current fileapi. It has not been possible to build that in without breaking the existing API as far as I understand. So that could be a place where we want to change things a little bit for the new API. If we want to include the fileapi in proj.h for version 6 where proj_api.h and proj.h will co-exists it might be necessary to break the existing API. Would that be acceptable to you?

Also, if you could design the fileapi form scratch, how would you go about doing it?

Finally, Is the code you are using it for open source? I'd like to see use of this in the wild if possible.

[paxswill]

I have no problem with breaking the fileapi, my application is really just using the fopen function to search in some extra areas at the moment.

One thing I was toying with for later was adding a sort of “in-memory init file” using the fileapi, but I’m not sure at the moment how I’d redesign the API to make that easier. I’ll have to think a bit more about this.

I’ve really just wrote the framework this week, so not much external use yet, but here it is, specifically bundle-reader.c

[kbevers]

I see you have written this comment below. So really exposing pj_set_searchpath and pj_set_finder the new API might be better for you?

/*
 In truth, using pj_set_searchpath would be easier, but it (and pj_set_finder,
 which would also be easier) has been deprecated and is due to be removed in a
 future release of PROJ. Instead we're doing some shenanigans with testing to
 see if a file with a given name exists in the Framework resources, and reading
 from there preferentially. This is also used instead of trying to set PROJ_LIB,
 as communicating over an environment variable seems janky. It also leaves open
 the option for a user to define PROJ_LIB to point to some data files they
 provide, while still providing the option of the Framework-provided data files.
 */

[paxswill]

For the specific case of my framework, yes, exposing pj_set_searchpath or pj_set_finder would be easier.

Thinking about the API design a bit more, I'm not sure exposing both is the right decision. They overlap a fair bit in intended purpose. Maybe something along the lines of a proj_set_find_func, proj_get_find_func and proj_reset_find_func. The default find_func implementation could run through the default search path, and alternative implementations could define their own search paths, optionally calling the default implementation if they want to fall back to that. Modifying the search path wouldn't be exposed in this case.

As far as the fileapi, I still think that should be exposed. Another use case would be if the data files are packaged in an archive (a ZIP file for example). A custom fileapi could then read these files transparently. As far as which functions are needed in the API, I think the current set is sufficient. fgetc can be approximated with repeated calls to fread, right @busstoptaktik?

[kbevers]

So something like the excerpt below to define the file API in proj.h. Possibly with a fgetc function thrown in there as well. It is basically the same as in proj_api.h just with updated type and function names.

typedef int *PJ_FILE;
typedef struct {
     PJ_FILE (*PJ_FOPEN)(PJ_CONTEXT *ctx, const char *filename, const char *access);
     size_t  (*PJ_FREAD)(void *buffer, size_t size, size_t nmemb, PJ_FILE file);
     int     (*PJ_FSEEK)(PJ_FILE file, long offset, int whence);
     long    (*PJ_FTELL)(PJ_FILE file);
     void    (*PJ_FCLOSE)(PJ_FILE);
} PJ_FILEAPI;

void       proj_set_fileapi(PJ_CONTEXT *ctx, PJ_FILEAPI fileapi);
PJ_FILEAPI proj_get_fileapi(PJ_CONTEXT *ctx);

Thanks for your thoughts on the search path. I am not sure about what's the best way to go. I'll have to give that some more thought. I hope that others will share their thoughts on this as well.

[kbevers]

@schwehr I suspect you are also using the file API in it's current form. Do you have any input regarding how it should be dealt with in the new API?

[schwehr]

I'm reading the data files from data embedded in the binary using pj_ctx_set_fileapi. I don't really have a local filesystem that I can use in my containers. As long as proj has a way to bundle the data into the binary and get it when necessary, I'm fine ditching pj_ctx_set_fileapi and the loader that isn't open source. In fact, I'd rather use something fully in proj that anyone could also use if they wanted.

[basiliscos]

@kbevers yes, this API for locating init-files and other data would be nice to have. I write perl-bindings, and the data-files are located in custom folder. So, it would be nice to let user specify PROJ_LIB to load his additional data, and, in addition, lookup that data in some default locations (not determined at compile-time).

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.