diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 93 |
1 files changed, 93 insertions, 0 deletions
@@ -0,0 +1,93 @@ +NAME + libgeome - Locate local user's geographical location + +SYNOPSIS + #include <libgeome.h> + + #define LIBGEOME_DATUM_LATITUDE /* omitted */ + #define LIBGEOME_DATUM_LONGITUDE /* omitted */ + #define LIBGEOME_DATUM_ALTITUDE /* omitted */ + + struct libgeome_data { + uint64_t requested_data; + double latitude; + double longitude; + double altitude; + }; + + struct libgeome_context { + union { + const void *cptr; + void *ptr; + int i; + unsigned int u; + size_t n; + } user_data; + void (*print_error)(struct libgeome_context *, const char *, ...); + void (*print_abort)(struct libgeome_context *, const char *, ...); + void (*print_debug)(struct libgeome_context *, const char *, ...); + }; + + struct libgeome_netservice { + uint64_t can_fetch; + size_t service_id; + size_t limit; + unsigned int alarm_seconds; + const char *path; + const char *const *args; + }; + + extern struct libgeome_netservice libgeome_netservices[]; + extern const size_t libgeome_netservices_count; + + void libgeome_basic_context(struct libgeome_context *, const char *); + + int libgeome_get_from_time(struct libgeome_context *, struct libgeome_data *); + int libgeome_get_from_timezone(struct libgeome_context *, struct libgeome_data *); + int libgeome_get_from_file(struct libgeome_context *, struct libgeome_data *, const char *); + int libgeome_get_from_command(struct libgeome_context *, struct libgeome_data *, size_t, + unsigned int, const char *, const char *const *); + int libgeome_get_from_netservice(struct libgeome_context *, struct libgeome_data *, + const struct libgeome_netservice *); + + Link with -lgeome -lm. + +DESCRIPTION + libgeome is a library which provides functionally for looking up + the local user's location on the Globe. + + To use libgeome, first create and initialise a struct libgeome_context + which will be used for all other library calls. This can easily be done + by creating a statically allocated struct libgeome_context and call the + libgeome_basic_context(3) function with it as the first argument and + the name of the program as the second argument, optionally with + "libgeome" added make it clear where error messages are printed from. + + libgeome_get_from_file(3) can be used to check if the user has specified + his location in /etc/geolocation (use NULL as the third argument) or any + other file (specified by the third argument). + + The next best thing is to use libgeome_get_from_timezone(3) to get a + rough location based on the user's timezone. But if this doesn't work, + libgeome_get_from_time(3) must be used, which provides only gives an + approximate longitude based one the current timezone, which is affected + by daylight saving, which may be desirable for some applications but not + for other applications. + + Unless the location was determined using the libgeome_get_from_file(3) + function, it may be desirable to attempt to get a more accurate location + using network location services. This should of course not be done + without the user's consent as this connects to a third party service. + The function libgeome_get_from_netservice(3) is used for this, and a + list of services is provided in libgeome_netservices(3), with the number + of services listed provided in libgeome_netservices_count(3). You can + also add custom services, or run local program, using the + libgeome_get_from_command(3) function. If it cannot parse the output, + can reformat it as "%s %s\n", <latitude>, <longitude>. + + When alling a libgeome function, any struct libgeome_data must have + its .requested_data set. This lets the called function 1) know what data + to request, and 2) what fields are available in the application's + version of the structure so that it doesn't write outside it if it is + out of date. There for it is critical that the application doesn't + simply set all but, but instead only recognised ones. |