File containing macros, types and function prototypes needed to work with libvigicrues. More...

#include <time.h>

Data Structures
struct	vigicrues_t
	A structure to hold the data retreived from the vigicrues service. More...

Macros
#define	VIGICRUES_MAJOR_VERSION
	An integer specifying the current major version.

#define	VIGICRUES_MINOR_VERSION
	An integer specifying the current minor version.

#define	VIGICRUES_PATCH_VERSION
	An integer specifying the current patch version.

#define	VIGICRUES_VERSION
	A string representation of the current version. More...

#define	VIGICRUES_VERSION_HEX
	A 3-byte hexadecimal representation of the current version, e.g. 0x010203 for version 1.2.3. More...

#define	VIGICRUES_IGNORE_PARAM
	An integer used to bypass the `ent`, `range` and `timeout` parameters when calling the function vigicrues_get(). More...

Typedefs
typedef vigicrues_status_t(*	vigicrues_f) (const vigicrues_t p_data, void param)
	Specifies the signature each user defined callback must respect. More...

Enumerations
enum	vigicrues_e { VIGICRUES_HEIGHT, VIGICRUES_FLOW, VIGICRUES_VIGILANCE }
	Specifies the type of data to retreive for a station. More...

enum	vigicrues_vigilance_e { VIGICRUES_VIGILANCE_GREEN, VIGICRUES_VIGILANCE_YELLOW, VIGICRUES_VIGILANCE_ORANGE, VIGICRUES_VIGILANCE_RED }
	Specifies the different vigilance states. More...

enum	vigicrues_error_t { VIGICRUES_ERROR_INVALID, VIGICRUES_ERROR_RANGE, VIGICRUES_ERROR_OUTDATED, VIGICRUES_ERROR_CANT_CONNECT, VIGICRUES_ERROR_TIMEDOUT, VIGICRUES_ERROR_CANCELED, VIGICRUES_ERROR_OUT_OF_MEMORY, VIGICRUES_ERROR_OTHER }
	Specifies the different error codes that can be reported in case of failure. More...

enum	vigicrues_status_t { VIGICRUES_FAILURE, VIGICRUES_SUCCESS }
	Specifies the values that can be returned by a function to indicate its execution status. More...

Functions
vigicrues_status_t	vigicrues_get (unsigned ent, const char id, enum vigicrues_e type, unsigned range, vigicrues_f func, void param, unsigned timeout, vigicrues_error_t *p_error)
	Retreives data from the vigicrues service. More...

Detailed Description

File containing macros, types and function prototypes needed to work with libvigicrues.

Author: Valentin Lahaye

Copyright: Copyright (c) 2017 Valentin Lahaye
This file is part of a free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/lgpl-3.0.html

See also: https://valentin.lahaye.pro/libvigicrues

Macro Definition Documentation

#define VIGICRUES_IGNORE_PARAM

An integer used to bypass the ent, range and timeout parameters when calling the function vigicrues_get().

See also: vigicrues_get

Examples:: heights.c, and vigilance.c.

#define VIGICRUES_VERSION

A string representation of the current version.

Patch version is ommited if it's 0.

#define VIGICRUES_VERSION_HEX

A 3-byte hexadecimal representation of the current version, e.g. 0x010203 for version 1.2.3.

This is useful in numeric comparisons, e.g. :

 #if VIGICRUES_VERSION_HEX >= 0x010203
 // Code specific to version 1.2.3 and above
 #endif

Typedef Documentation

typedef vigicrues_status_t(* vigicrues_f) (const vigicrues_t *p_data, void *param)

Specifies the signature each user defined callback must respect.

Parameters

[in]	p_data	A pointer to the data retreived by the function vigicrues_get(). This pointer makes reference to a statically allocated structure and therefore must not be freed.
[in]	param	A user defined parameter passed to the callback each time it's being fired.

Return values

VIGICRUES_FAILURE	Unsuccessful execution of the callback. The caller routine e.g. vigicrues_get() is stopped and returns immediately with status VIGICRUES_FAILURE.
VIGICRUES_SUCCESS	Successful execution of the callback.

See also: vigicrues_get

Enumeration Type Documentation

enum vigicrues_e

Specifies the type of data to retreive for a station.

Enumerator
VIGICRUES_HEIGHT	Retreive the water heights.
VIGICRUES_FLOW	Retreive the water flows.
VIGICRUES_VIGILANCE	Retreive the current vigilance state.

enum vigicrues_error_t

Specifies the different error codes that can be reported in case of failure.

The normal use of vigicrues_error_t is to allocate it on the stack, and pass a pointer to a function, e.g. :

 int main(void) {
   vigicrues_error_t error;
   vigicrues_status_t status = vigicrues_get(VIGICRUES_IGNORE_PARAM, "J262301002",
                                             VIGICRUES_HEIGHT, 1, &func, NULL,
                                             VIGICRUES_IGNORE_PARAM, &error);
   if (status == VIGICRUES_FAILURE) {
       // The error variable contains error informations
   }
   ...
 }

Also note that if the call succeeded, the content of p_error is left unspecified. All functions also accept NULL as the vigicrues_error_t pointer, in which case no error information is returned to the caller.

Enumerator
VIGICRUES_ERROR_INVALID	One parameter or more is incorrect.
VIGICRUES_ERROR_RANGE	All requested values could not be returned to the caller.
VIGICRUES_ERROR_OUTDATED	The vigicrues service version has changed, the library needs to be updated.
VIGICRUES_ERROR_CANT_CONNECT	Can't connect to the vigicrues service.
VIGICRUES_ERROR_TIMEDOUT	The maximum time allowed for the transfer operation to take has been exceeded.
VIGICRUES_ERROR_CANCELED	The function has been stopped by the user defined routine.
VIGICRUES_ERROR_OUT_OF_MEMORY	A memory allocation request failed.
VIGICRUES_ERROR_OTHER	An unhandled error occurred.

enum vigicrues_status_t

Specifies the values that can be returned by a function to indicate its execution status.

Enumerator
VIGICRUES_FAILURE	Unsuccessful execution of a function.
VIGICRUES_SUCCESS	Successful execution of a function.

enum vigicrues_vigilance_e

Specifies the different vigilance states.

Enumerator
VIGICRUES_VIGILANCE_GREEN	Green vigilance state.
VIGICRUES_VIGILANCE_YELLOW	Yellow vigilance state.
VIGICRUES_VIGILANCE_ORANGE	Orange vigilance state.
VIGICRUES_VIGILANCE_RED	Red vigilance state.

Function Documentation

vigicrues_status_t vigicrues_get	(	unsigned	ent,
		const char *	id,
		enum vigicrues_e	type,
		unsigned	range,
		vigicrues_f	func,
		void *	param,
		unsigned	timeout,
		vigicrues_error_t *	p_error
	)

Retreives data from the vigicrues service.

In case range is greater than 1, values are retreived from most recent to oldest.

Parameters

[in]	ent	The ID of the flood forecasting service to which the station belongs. This parameter must be set to VIGICRUES_IGNORE_PARAM if `type` is equal to either VIGICRUES_HEIGHT or VIGICRUES_FLOW.
[in]	id	The ID of the station for which to retreive data.
[in]	type	The type of data to retreive.
[in]	range	The number of values to retreive. This parameter must be set to VIGICRUES_IGNORE_PARAM if `type` is equal to VIGICRUES_VIGILANCE.
[in]	func	A user defined function to be called each time a value is retreived.
[in]	param	A user defined parameter to be passed to the callback each time it's being fired. This parameter is optional and therefore can be set to NULL.
[in]	timeout	The maximum time in seconds that you allow the function transfer operation to take. Set this parameter to VIGICRUES_IGNORE_PARAM for it to never time out.
[out]	p_error	A pointer to a vigicrues_error_t variable to store error information in case of failure. This parameter can be set to NULL to ignore error reporting.

Return values

VIGICRUES_FAILURE	Unsuccessful execution of the function, in which case `p_error` is filled with information about the error.
VIGICRUES_SUCCESS	Successful execution of the function.

See also: VIGICRUES_IGNORE_PARAM

Examples:: heights.c, and vigilance.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation