First commit

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 93 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..c94d7fd
--- /dev/null
+++ b/README
@@ -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.