flight.h File Reference

Interface for working with a flight. More...

#include "eaarlio/edb.h"
#include "eaarlio/error.h"
#include "eaarlio/memory.h"
#include "eaarlio/raster.h"
#include "eaarlio/tld_opener.h"

Go to the source code of this file.

Data Structures
struct	eaarlio_flight
	Flight data. More...

Macros
#define	eaarlio_flight_empty()
	Empty eaarlio_flight value. More...

Functions
eaarlio_error	eaarlio_flight_init (struct eaarlio_flight *flight, struct eaarlio_memory *memory)
	Initialize an eaarlio_flight. More...
eaarlio_error	eaarlio_flight_read_raster (struct eaarlio_flight *flight, struct eaarlio_raster *raster, int32_t *time_offset, uint32_t raster_number, int include_pulses, int include_waveforms)
	Retrieve data for a raster. More...
eaarlio_error	eaarlio_flight_free (struct eaarlio_flight *flight)
	Release resources held by eaarlio_flight. More...

Detailed Description

Interface for working with a flight.

This header defines an interface for working with a flight, which in this context means an EDB file and its associated TLD files.

---

Data Structure Documentation

eaarlio_flight

struct eaarlio_flight

Flight data.

This structure contains the data necessary for working with a flight, which in this context means a set of TLD files and their associated EDB index. The structure contains the EDB data, which calling code can refer to directly. The structure can be used with eaarlio_flight_read_raster to retrieve raster data given a raster number.

Implementations must do the following:

• You must populate eaarlio_flight::edb with the data as loaded from an EDB file.
• You must populate eaarlio_flight::tld_opener with a TLD opener that will open streams for the TLD files defined in the EDB data.
• You must call eaarlio_flight_init to initialize internal state data prior to calling eaarlio_flight_read_raster.
• You must call eaarlio_flight_free to release internal state data when finished using the eaarlio_flight.

Examples:

eaarlio_yaml.c, example_flight_read_raster_pulse.c, and example_flight_read_rasters.c.

Data Fields
struct eaarlio_edb	edb	EDB data for the flight. Warning After calling eaarlio_flight_init, you must not modify eaarlio_edb::files or the eaarlio_edb_record::file_index for any entry in eaarlio_edb::records. Doing so will result in undefined behavior for eaarlio_flight_read_raster.
void *	internal	Internal data pointer used for tracking state. Calling code should not interact with this directly.
struct eaarlio_tld_opener	tld_opener	A TLD opener for the flight. Warning After calling eaarlio_flight_init, you should not modify eaarlio_flight::tld_opener. Doing so will result in undefined behavior for eaarlio_flight_read_raster.

Macro Definition Documentation

eaarlio_flight_empty

#define eaarlio_flight_empty

(

)

Value:

(struct eaarlio_flight)                                                    \
    {                                                                          \
        eaarlio_edb_empty(), eaarlio_tld_opener_empty(), NULL                  \
    }

Empty eaarlio_flight value.

All numeric fields will contain zero values. All pointers will be null.

Examples:

eaarlio_yaml.c, example_flight_read_raster_pulse.c, and example_flight_read_rasters.c.

Function Documentation

eaarlio_flight_free()

eaarlio_error eaarlio_flight_free

(

struct eaarlio_flight *

flight

)

Release resources held by eaarlio_flight.

Parameters

[in]

flight

Flight with resources to release

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Remarks

Unlike similar functions, this function does not accept a memory handler parameter because it already has an internal reference to a memory handler.

Examples:

eaarlio_yaml.c, example_flight_read_raster_pulse.c, and example_flight_read_rasters.c.

eaarlio_flight_init()

eaarlio_error eaarlio_flight_init	(	struct eaarlio_flight *	flight,
		struct eaarlio_memory *	memory
	)

Initialize an eaarlio_flight.

Parameters

[in,out]	flight	A flight to initialize
[in]	memory	A memory handler, or NULL for stdlib

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Precondition

flight->edb must already be populated with valid data.

flight->tld_opener must already be populated with a valid TLD opener.

Postcondition

On success, flight->internal will be populated with an opaque pointer for internal use.

If flight->internal is not NULL, then it represets newly allocated memory. That memory should later be released with eaarlio_flight_free.

Warning

flight keeps an internal reference to memory, which is used by eaarlio_flight_read_raster for allocating memory and by eaarlio_flight_free for releasing memory. If you provide a memory handler, you must ensure it remains valid until eaarlio_flight_free is called.

eaarlio_flight_read_raster()

eaarlio_error eaarlio_flight_read_raster	(	struct eaarlio_flight *	flight,
		struct eaarlio_raster *	raster,
		int32_t *	time_offset,
		uint32_t	raster_number,
		int	include_pulses,
		int	include_waveforms
	)

Retrieve data for a raster.

Parameters

[in]	flight	Flight to use to retrieve the raster
[out]	raster	Pointer to raster to be populated
[out]	time_offset	Pointer to time offset to be populated. This can be null if you do not want the time_offset.
[in]	raster_number	Raster number to retrieve
[in]	include_pulses	Should pulse data be read? 1 = yes, 0 = no
[in]	include_waveforms	Should waveform data be read? 1 = yes, 0 = no

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Precondition

eaarlio_flight_init must have been called to initialize flight.

flight was not modified after calling eaarlio_flight_init.

Postcondition

On success, raster is populated with the data for the raster requested.

On success, if time_offset was null null, then it is populated with the time offset detected in the EDB data. The time offset is the difference in time between the EDB timestamp and the TLD timestamp for the raster. This needs to be added to eaarlio_raster::time_seconds if you want the correct time.

On success, any non-null pointers in raster represent newly allocated memory.

Warning

You must not change the contents of flight after calling eaarlio_flight_init or between calls to eaarlio_flight_read_raster. If you do, then the behavior of this function is undefined.

Remarks

Internally, the flight keeps a stream open to the last TLD file accessed. This permits subsequent calls to eaarlio_flight_read_raster to re-use the same stream.

Unlike other functions that access streams, this function is not guaranteed to operate sequentially. If you attempt to retrieve an earlier raster number that is within the currently open stream, then the function will seek backwards in the file to read that raster.

Examples:

eaarlio_yaml.c, example_flight_read_raster_pulse.c, and example_flight_read_rasters.c.