1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
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 */
#define LIBGEOME_LAST_DATUM /* whatever the datum represented with the highest bit is */
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;
unsigned patterned : 1;
};
extern const 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 *);
/* less fundament features omitted */
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.
EXTENDED DESCRIPTION
Runtime-optional dependencies
libgeome_get_from_timezone(3) relies on timezone data compatible with
the Time Zone Database from Internet Assigned Numbers Authority, also
called tz or zoneinfo (as is used in /usr/share), and often distributed
under the name tzdata (the data portion of the project).
libgeome_netservices(3) relies on curl(1).
|
