mirror of
https://github.com/ByteWelder/Tactility.git
synced 2026-10-17 02:45:05 +00:00
70 lines
2.2 KiB
C
70 lines
2.2 KiB
C
// SPDX-License-Identifier: Apache-2.0
|
|
#pragma once
|
|
|
|
#include <location/location.h>
|
|
|
|
#include <stdbool.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* Interface between the location service and a location provider. Not part of the app SDK.
|
|
*/
|
|
|
|
/** The service, as seen by a provider */
|
|
struct LocationHost;
|
|
|
|
struct LocationProviderApi {
|
|
/** Unique id, at most LOCATION_PROVIDER_ID_MAX_LENGTH characters */
|
|
const char* id;
|
|
|
|
/**
|
|
* A fallback provider (e.g. IP geolocation) is only used while no other provider reported a fix in the last
|
|
* 2 minutes. It should only work when location_host_needs_fallback() returns true.
|
|
*/
|
|
bool fallback;
|
|
|
|
/**
|
|
* Start the provider. Called when the service starts, or when the provider registers while the service runs.
|
|
* @return the provider state, NULL on failure
|
|
*/
|
|
void* (*create)(struct LocationHost* host);
|
|
|
|
/** Stop the provider. It must not report anymore once this returns. */
|
|
void (*destroy)(void* provider);
|
|
};
|
|
|
|
/** Maximum number of registered providers */
|
|
#define LOCATION_PROVIDER_MAX_COUNT 4
|
|
|
|
/**
|
|
* Register a provider. Usually called from the provider module's start().
|
|
* @retval ERROR_ALREADY_EXISTS when a provider with the same id is registered
|
|
* @retval ERROR_RESOURCE when LOCATION_PROVIDER_MAX_COUNT providers are registered
|
|
*/
|
|
error_t location_provider_register(const struct LocationProviderApi* api);
|
|
|
|
/** @retval ERROR_NOT_FOUND when @a api is not registered */
|
|
error_t location_provider_unregister(const struct LocationProviderApi* api);
|
|
|
|
/**
|
|
* Report a new fix. Can be called from any task.
|
|
* The service sets the `provider` and `uptime_ms` fields.
|
|
*/
|
|
void location_host_report(struct LocationHost* host, const struct Location* location);
|
|
|
|
/**
|
|
* Reduce a fix to LOCATION_PRECISION_APPROXIMATE: the position snaps to a grid and only position and time remain.
|
|
* Providers that can report precise fixes apply this when location_get_precision() is LOCATION_PRECISION_APPROXIMATE.
|
|
*/
|
|
void location_make_approximate(struct Location* location);
|
|
|
|
/** @return true when no provider that isn't a fallback reported a fix in the last 2 minutes */
|
|
bool location_host_needs_fallback(void);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|