diff options
Diffstat (limited to 'libgeome.h')
| -rw-r--r-- | libgeome.h | 124 |
1 files changed, 118 insertions, 6 deletions
@@ -25,6 +25,67 @@ /** + * Machine portability class + */ +enum libgeome_portability { + /** + * No data available about the machine's + * portability class + */ + LIBGEOME_UNKNOWN_PORTABILITY, + + /** + * libgeome guesses that the machine is + * stationary (e.g. desktop computer) + */ + LIBGEOME_GUESSED_STATIONARY, + + /** + * libgeome guesses that the machine is + * movable but is usually not moving around + * while in use, or that these movement do + * not need to be closely tracked (e.g. + * laptop computer) + */ + LIBGEOME_GUESSED_PORTABLE, + + /** + * libgeome guesses that the machine is + * frequently on the move even when in use + * and that it may be desirable to keep + * the location updated with short intervals + * (e.g. mobile telephone) + */ + LIBGEOME_GUESSED_MOBILE, + + /** + * The user has specified that the machine + * is only being moved, a significant distance, + * in exceptional circumstances and only when + * powered off + */ + LIBGEOME_STATIONARY, + + /** + * The user has specified that the machine + * is at moved from time to time, regardless + * of whether it is powered on or off, but it + * is not usually useful to keep the location + * up to date with short intervals + */ + LIBGEOME_PORTABLE, + + /** + * The user hsa specified that the is often + * on the move when in use and that it is + * useful to keep the locations updated with + * short intervals + */ + LIBGEOME_MOBILE +}; + + +/** * Geolocation data */ struct libgeome_data { @@ -158,6 +219,15 @@ struct libgeome_netservice { * and an URL) */ const char *const *args; + + /** + * Whether `.path` or `.args` contain %-patterns + * + * See `libgeome_get_from_patterned_command` for more information + * + * @since 2.0 + */ + unsigned patterned : 1; }; @@ -198,6 +268,17 @@ extern const size_t libgeome_netservices_count; void libgeome_basic_context(struct libgeome_context *ctx_out, const char *procname); /** + * Get the machine's partability class + * + * @param ctx Library context + * @param out Output parameter + * @return 0 on success, -1 on failure + * + * @since 2.0 + */ +int libgeome_get_portability(struct libgeome_context *ctx, enum libgeome_portability *out); + +/** * Get a very rough location guess based on * the current timezone's offset from UTC * @@ -269,18 +350,49 @@ int libgeome_get_from_command(struct libgeome_context *ctx, struct libgeome_data * Spawn a program and read it's standard output * to get the user's location data * + * `path` and elements of `argv` are subject to %-substitution + * using the following rules: + * + * - The string is parsed from left to right + * - Any '%' trigger substitutation + * - If the next character is not '%', the "%%" is replaced with a literal "%" + * - Otherwise the next character character must be '{' and '%' marks the beginning + * of a %-pattern. + * - Within a %-pattern "%%" is replaced with "%" and "%}" with "}", and no other + * use of "%" is invalid (nested patterns are disallowed). + * - A %-pattern ends with the first other occurance of a '}' + * - Each %-pattern shall be on one of the two forms: + * - "%%{%u:%s}", <feature set>, <text> + * - "%%{!%u:%s}", <feature set>, <text> + * The if the first pattern is used the pattern is deleted and only replaced with + * <text> if `out->requested_data & <feature set>` is non-zero. + * The if the second pattern is used the pattern is deleted and only replaced with + * <text> if `out->requested_data & <feature set>` is zero. + * <feature set> must be positive. + * + * @param ctx Library context + * @param out Output parameter, `out->requested_data` must be set + * @param limit Number of bytes to stop reading output after, zero for default + * @param alarm_sec If non-zero, the number of seconds to let the subprocess live + * @param path Path to command to spawn + * @param argv Command line arguments for the process, including the name of the command + * @return 0 if data could be retrieved, even if none of the requested data + * could be retrieved, -1 otherwise + */ +int libgeome_get_from_patterned_command(struct libgeome_context *ctx, struct libgeome_data *out, size_t limit, + unsigned int alarm_sec, const char *path, const char *const *argv); + +/** + * Spawn a program and read it's standard output + * to get the user's location data + * * @param ctx Library context * @param out Output parameter, `out->requested_data` must be set * @param svc Parameters for the command to run * @return 0 if data could be retrieved, even if none of the requested data * could be retrieved, -1 otherwise */ -inline int -libgeome_get_from_netservice(struct libgeome_context *ctx, struct libgeome_data *out, - const struct libgeome_netservice *svc) -{ - return libgeome_get_from_command(ctx, out, svc->limit, svc->alarm_seconds, svc->path, svc->args); -} +int libgeome_get_from_netservice(struct libgeome_context *ctx, struct libgeome_data *out, const struct libgeome_netservice *svc); #endif |