STFF-Types.h

Go to the documentation of this file.

///
/// @file   STFF-Types.h
///
/// Header file containing enumerations and simple struct types used in the
/// %STFishFinder API.
/// The type definitions defined in this file reside in the global namespace.
///
/// @copyright
/// Copyright (c) 2012-2015 Sifferman Technology, LLC.  All rights reserved.
///

#ifndef STFF_Types_h_
#define STFF_Types_h_

#ifdef __APPLE__
#include <stdint.h>
#else
#include <cstdint>
#endif

    ////////////////////////////////////////////////////////////////////////////////
    /// @defgroup global_namespace Global Namespace
    ///
    /// Certain parts of the STFishFinder API reside in the global namespace.
    /// This includes certain enumerations and simple structs, all of which
    /// are defined as typedefs.
    ///
    ////////////////////////////////////////////////////////////////////////////////

    ////////////////////////////////////////////////////////////////////////////////
    /// @defgroup global_enums Global Enumerations
    ///
    /// These are type definitions for enumerations in the global namespace.
    ///
    /// @remarks These have been placed in the global namespace to simplify linking
    /// with application code written in languages that do not support namespaces.
    ///
    /// @ingroup global_namespace
    ///
    ////////////////////////////////////////////////////////////////////////////////

    /// Error codes.
    ///
    /// This is a type definition for an enumeration specifying an Error Code
    /// returned by a STFF::STFishFinder class member function.
    /// This enumeration resides in the global namespace.
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_ERR_UNKNOWN_ERROR = -999,
        FF_ERR_INVALID_FREQUENCY,       ///< Frequency argument provided was not valid.
        FF_ERR_INVALID_POINTER,         ///< A provided pointer argument was not valid.
        FF_ERR_ARGUMENT_OUT_OF_RANGE,   ///< The value of an argument was not within the allowed range.
        FF_ERR_BAD_DATABASE,            ///< The API encountered an internal error.
        FF_ERR_API_NOT_INITIALIZED,     ///< The requested method may not be called before initializing the API.
        FF_ERR_API_ALREADY_INITIALIZED, ///< The Hello() function was already called for the present connection.
        FF_ERR_EXCEPTION_OCCURRED,      ///< An exception was thrown and caught within the API.
        FF_ERR_CANT_CHANGE_CALLBACKS,   ///< Function STFF::STFishFinder::SetCallbacks() may not be called if any STFishFinder objects exist.
        FF_ERR_FEATURE_NOT_AVAILABLE,

        FF_ERR_NO_ERROR = 0             ///< Successful completion of the method.
    } FF_Error_t;


    /// Sonar Frequency options.
    ///
    /// This is a type definition for an enumeration specifying a
    /// sonar frequency context.  Two frequencies
    /// are supported: 50 kHz and 200 kHz.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::valid(FF_Frequency_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_FREQUENCY = -1,              ///< Invalid frequency or frequency not specified
        FF_FREQUENCY_200_KHZ,                   ///< Specifies a 200 kilohertz sonar context.
        FF_FREQUENCY_50_KHZ,                    ///< Specifies a 50 kilohertz sonar context.
        FF_TOTAL_FREQUENCIES
    } FF_Frequency_t;


    /// Depth Units selection.
    ///
    /// This is a type definition for an enumeration specifying distance units
    /// (feet, meters, or fathoms) used with an associated depth value.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::ConvertDepth()
    /// @see STFF::valid(FF_DepthUnits_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_DEPTH_UNITS = -1,
        FF_DEPTH_UNITS_FEET,                    ///< Depth units are Feet
        FF_DEPTH_UNITS_METERS,                  ///< Depth units are Meters
        FF_DEPTH_UNITS_FATHOMS,                 ///< Depth units are Fathoms
        FF_TOTAL_DEPTH_UNITS
    } FF_DepthUnits_t;


    /// Speed Units selection.
    ///
    /// This is a type definition for an enumeration specifying speed units
    /// (knots, miles per hour, or kilometers per hour) used with an
    /// associated speed-through-water value.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::ConvertSpeed()
    /// @see STFF::valid(FF_SpeedUnits_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_SPEED_UNITS = -1,
        FF_SPEED_UNITS_KNOTS,                   ///< Speed units are knots (nautical miles per hour)
        FF_SPEED_UNITS_MPH,                     ///< Speed units are statute miles per hour
        FF_SPEED_UNITS_KPH,                     ///< Speed units are kilometers per hour
        FF_TOTAL_SPEED_UNITS
    } FF_SpeedUnits_t;


    /// Temperature Units selection.
    ///
    /// This is a type definition for an enumeration specifying temperature units
    /// (degrees Celsius or degrees Fahrenheit) used with an associated
    /// temperature value.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::ConvertTemperature()
    /// @see STFF::valid(FF_TemperatureUnits_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_TEMPERATURE_UNITS = -1,
        FF_TEMPERATURE_UNITS_CELSIUS,           ///< Temperature units are degrees Celsius
        FF_TEMPERATURE_UNITS_FAHRENHEIT,        ///< Temperature units are degrees Fahrenheit
        FF_TOTAL_TEMPERATURE_UNITS
    } FF_TemperatureUnits_t;


    /// Setting Type options.
    ///
    /// This is a type definition for an enumeration specifying a Setting type
    /// or a Master Setting type.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::valid(FF_SettingType_t)
    /// @see STFF::STFishFinder::Hello()
    /// @see @ref setters
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_SETTING_TYPE = -1,
        FF_SETTING_TYPE_API_READY,                  ///< Not a setting type per se, but is provided to the onSettingChanged callback when the API is ready to service calls to setter and getter functions
        FF_SETTING_TYPE_CONTROL,                    ///< Specifies the setting type for Control messages.                                               @see STFF::STFishFinder::Control()
        FF_SETTING_TYPE_BIT_DEPTH,                  ///< Specifies the setting type for Bit Depth.                                                      @see STFF::STFishFinder::SetBitDepth()
        FF_SETTING_TYPE_NUM_INPUT_SAMPLES,          ///< Specifies the setting type for Number of Input Samples.                                        @see STFF::STFishFinder::SetNumInputSamples()
        FF_SETTING_TYPE_FREQUENCY_MODE,             ///< Specifies the setting type for Frequency Mode.                                                 @see STFF::STFishFinder::SetFrequencyMode()
        FF_SETTING_TYPE_DEPTH_UNITS,                ///< Specifies the setting type for Depth Units.                                                    @see STFF::STFishFinder::SetDepthUnits()
        FF_SETTING_TYPE_AUTO_GAIN_SETTING,          ///< Specifies the setting type for Auto Gain.                                                      @see STFF::STFishFinder::SetAutoGainSetting()
        FF_SETTING_TYPE_WATER_FILTER_SETTING,       ///< Specifies the setting type for Water Filter.                                                   @see STFF::STFishFinder::SetWaterFilterSetting()
        FF_SETTING_TYPE_AUTO_RANGE_SETTING,         ///< Specifies the setting type for Auto Range.                                                     @see STFF::STFishFinder::SetAutoRangeSetting()
        FF_SETTING_TYPE_RANGE,                      ///< Specifies the setting type for Range.                                                          @see STFF::STFishFinder::SetRange()
        FF_SETTING_TYPE_GAIN,                       ///< Specifies the setting type for Gain.                                                           @see STFF::STFishFinder::SetGain()
        FF_SETTING_TYPE_GAIN_OFFSET,                ///< Specifies the setting type for Gain Offset.                                                    @see STFF::STFishFinder::SetGainOffset()
        FF_SETTING_TYPE_GAIN_COLOR_OFFSETS,         ///< Specifies the setting type for Gain Color Offsets.                                             @see STFF::STFishFinder::SetGainColorOffsets()
        FF_SETTING_TYPE_FSTC,                       ///< Specifies the setting type for FSTC (Fishfinder Sensitivity Time Constant).                    @see STFF::STFishFinder::SetFstc()
        FF_SETTING_TYPE_FISH_ID_SETTING,            ///< Specifies the setting type for Fish ID.                                                        @see STFF::STFishFinder::SetFishIdSetting()
        FF_SETTING_TYPE_FISH_ALARM_SETTING,         ///< Specifies the setting type for Fish Alarm.                                                     @see STFF::STFishFinder::SetFishAlarmSetting()
        FF_SETTING_TYPE_MASTER_DEPTH_ALARM_SETTING, ///< Specifies the master setting type for Depth Alarm.                                             @see STFF::STFishFinder::SetDepthAlarmSetting()
        FF_SETTING_TYPE_MASTER_SPEED_PPNM,          ///< Specifies the master setting type for Speed Pulses Per Nautical Mile.                          @see STFF::STFishFinder::SetSpeedPpnm()
        FF_SETTING_TYPE_MASTER_TEMPERATURE_OFFSET,  ///< Specifies the master setting type for Temperature Offset.                                      @see STFF::STFishFinder::SetTemperatureOffset()
        FF_SETTING_TYPE_MASTER_DSTC,                ///< Specifies the master setting type for DSTC (Depth Sensitivity Time Constant).                  @see STFF::STFishFinder::SetDstc()
        FF_SETTING_TYPE_MASTER_WATER_TYPE,          ///< Specifies the master setting type for Water Type (for establishing speed of sound constant).   @see STFF::STFishFinder::SetWaterType()
        FF_TOTAL_SETTING_TYPES
    } FF_SettingType_t;


    /// Setting Status options.
    ///
    /// This is a type definition for an enumeration specifying the status of
    /// a setting item reported by an API setting getter member function.
    /// This enumeration resides in the global namespace.
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_SETTING_STATUS_INVALID = 0,          ///< The associated setting is not valid, and should not be used.
        FF_SETTING_STATUS_PENDING,              ///< The associated setting has been sent to the black box, but a confirmation has not yet been received.
        FF_SETTING_STATUS_VALID,                ///< The associated setting is valid.
    } FF_SettingStatus_t;


    /// Data Type options.
    ///
    /// This is a type definition for an enumeration specifying a Data Type,
    /// in reference to data messages transmitted from a black box fish finder.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::valid(FF_DataType_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_DATA_TYPE = -1,
        FF_DATA_TYPE_DEPTH,                     ///< Specifies the Depth data type
        FF_DATA_TYPE_SPEED,                     ///< Specifies the Speed data type
        FF_DATA_TYPE_TEMPERATURE,               ///< Specifies the Temperature data type
        FF_DATA_TYPE_BATTERY_VOLTAGE,           ///< Specifies the Battery Voltage data type
        FF_DATA_TYPE_IMAGE,                     ///< Specifies the Fish Finder Image data type
        FF_DATA_TYPE_FISH,                      ///< Specifies the Fish data type
        FF_DATA_TYPE_DEPTH_ALARM,               ///< Specifies the Depth Alarm data type
        FF_TOTAL_DATA_TYPES
    } FF_DataType_t;


    /// Data Status options.
    ///
    /// This is a type definition for an enumeration specifying the status of
    /// a data item reported by an API data getter member function.
    /// This enumeration resides in the global namespace.
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_DATA_STATUS_INVALID = 0,             ///< The associated data item is not valid, and should not be relied upon.
        FF_DATA_STATUS_VALID,                   ///< The associated data item is valid and usable.
        FF_DATA_STATUS_SIMULATED,               ///< The associated data item is simulated. If displayed to the user, it must be identified as being a simulation.
        FF_DATA_STATUS_PLAYBACK_VALID           ///< The associated data item was generated during a replay of a previously recorded session, and when originally recorded, was valid data. It does not represent current data.
    } FF_DataStatus_t;


    /// Control Command options.
    ///
    /// This is a type definition for an enumeration specifying valid commands
    /// for use with the API member function STFF::STFishFinder::Control().
    /// This enumeration resides in the global namespace.
    ///
    /// @note
    /// -# The values in this enumeration apply to the first parameter (@p command)
    ///    in the call to STFF::STFishFinder::Control().
    /// -# At present only one value is supported:
    ///    ::FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES.
    ///
    /// @see STFF::STFishFinder::Control()
    /// @see STFF::valid(FF_ControlCommand_t)
    /// @see FF_ControlEnableBlackBoxMsg_t
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_CONTROL_COMMAND = -1,
        FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES,   ///< Command to instruct the black box to enable or disable transmission of certain data messages
        FF_TOTAL_CONTROL_COMMANDS
    } FF_ControlCommand_t;


    /// Control command parameter options for use with the
    /// ::FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES option when
    /// calling STFF::STFishFinder::Control().
    ///
    /// This is a type definition for an enumeration specifying valid
    /// mask values that are each used to enable periodic transmission
    /// by the black box of a specific data message.  These apply only
    /// when calling STFF::STFishFinder::Control() with the
    /// ::FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES value in the
    /// first parameter.  The selected values in this enumeration
    /// are to be logically ORed together and provided in the second
    /// parameter (pParam) in the call to STFF::STFishFinder::Control().
    /// Mask values that are omitted will result in the corresponding data
    /// message becoming disabled.
    ///
    /// @remarks
    /// In many systems, it is anticipated that all messages will be enabled.
    /// In this case, the ::FF_ENABLE_ALL_MESSAGES value may be used.
    ///
    /// @see STFF::STFishFinder::Control()
    /// @see FF_ControlCommand_t
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_ENABLE_MESSAGE_DEPTH = 1,   ///< Enable periodic transmission of Depth data message
        FF_ENABLE_MESSAGE_SPEED = 2,   ///< Enable periodic transmission of Speed data message
        FF_ENABLE_MESSAGE_TEMPERATURE = 4,   ///< Enable periodic transmission of Temperature data message
        FF_ENABLE_MESSAGE_BATTERY_VOLTAGE = 8,   ///< Enable periodic transmission of Battery Voltage data message
        FF_ENABLE_MESSAGE_IMAGE = 16,   ///< Enable periodic transmission of Image data message
        FF_ENABLE_MESSAGE_FISH = 32,   ///< Enable transmission of Fish data message on detection of possible fish target
        FF_ENABLE_MESSAGE_DEPTH_ALARM = 64,   ///< Enable transmission of Depth Alarm state message on every state change
        FF_ENABLE_ALL_MESSAGES = 127   ///< Enable transmission of all messages
    } FF_ControlEnableBlackBoxMsg_t;


    /// Sonar Frequency Mode options.
    ///
    /// This is a type definition for an enumeration specifying sonar
    /// frequency(ies) to be used for the image data provided by the
    /// sounder electronics. Three options are provided: 200 kHz, 50 kHz,
    /// and Dual mode.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetFrequencyMode()
    /// @see STFF::STFishFinder::GetFrequencyMode()
    /// @see STFF::valid(FF_FrequencyMode_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_FREQUENCY_MODE = -1,
        FF_FREQUENCY_MODE_200_KHZ,              ///< Specifies that the provided sonar image data is to be at the 200 kHz frequency.
        FF_FREQUENCY_MODE_50_KHZ,               ///< Specifies that the provided sonar image data is to be at the 50 kHz frequency.
        FF_FREQUENCY_MODE_DUAL,                 ///< Specifies that the provided sonar image data is to alternate between the 200 kHz and 50 kHz frequencies.
        FF_TOTAL_FREQUENCY_MODES
    } FF_FrequencyMode_t;


    /// @cond
    /// ^^^^^ Do not include documentation for this typedef
    ///
    /// Sampling Bit Depth options.
    ///
    /// This is a type definition for an enumeration specifying a
    /// sampling bit depth used for image data.  Presently, only a bit depth
    /// of 4 bits (16 intensity levels) is supported.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetBitDepth()
    /// @see STFF::STFishFinder::GetBitDepth()
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_BIT_DEPTH = -1,
        FF_BIT_DEPTH_4,                         ///< Bit depth of 4 bits (16 intensity levels)
        FF_TOTAL_BIT_DEPTHS
    } FF_BitDepth_t;
    /// @endcond


    /// Auto Range setting options.
    ///
    /// This is a type definition for an enumeration specifying an
    /// Auto Range setting.  Three settings are provided: Manual Range,
    /// Auto Range, and Auto Shift.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetAutoRangeSetting()
    /// @see STFF::STFishFinder::GetAutoRangeSetting()
    /// @see STFF::valid(FF_AutoRangeSetting_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_AUTO_RANGE_SETTING = -1,
        FF_AUTO_RANGE_SETTING_MANUAL,           ///< The shallow and deep range limits are set manually, using function STFishFinder::SetRange().
        FF_AUTO_RANGE_SETTING_AUTO_RANGE,       ///< The shallow range limit is fixed at 0, and the deep range limit is adjusted automatically to keep the seabed visible.
        FF_AUTO_RANGE_SETTING_AUTO_SHIFT,       ///< The delta between the shallow and deep range limits is fixed, and they are adjusted automatically in tandem to keep the seabed visible.
        FF_TOTAL_AUTO_RANGE_SETTINGS
    } FF_AutoRangeSetting_t;


    /// Auto Gain setting options.
    ///
    /// This is a type definition for an enumeration specifying an
    /// Auto Gain setting.  Two settings are provided: Manual Gain and Auto Gain.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetAutoGainSetting()
    /// @see STFF::STFishFinder::GetAutoGainSetting()
    /// @see STFF::valid(FF_AutoGainSetting_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_AUTO_GAIN_SETTING = -1,
        FF_AUTO_GAIN_SETTING_MANUAL,            ///< Gain setting is fixed and specified by calling SetGain
        FF_AUTO_GAIN_SETTING_AUTO,              ///< Gain setting is adjusted automatically to maximize the visible target-to-clutter ratio
        FF_TOTAL_AUTO_GAIN_SETTINGS
    } FF_AutoGainSetting_t;


    ////////////////////////////////////////////////////////////////////////
    /// @cond
    /// ^^^^^ Do not include documentation for this function
    ///
    /// Water Type selection.
    ///
    /// This is a type definition for an enumeration specifying a water type
    /// for the purpose of selecting an appropriate constant for
    /// speed of sound through water.
    /// This enumeration resides in the global namespace.
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_WATER_TYPE = -1,
        FF_WATER_TYPE_FRESHWATER,               ///< Speed of sound constant set to nominal value for freshwater
        FF_WATER_TYPE_SALTWATER,                ///< Speed of sound constant set to nominal value for saltwater
        FF_WATER_TYPE_CUSTOM,
        FF_TOTAL_WATER_TYPES
    } FF_WaterType_t;
    /// @endcond


    /// Depth Alarm Type selection.
    ///
    /// This is a type definition for an enumeration specifying a Depth Alarm Type
    /// (shallow alarm or deep alarm).
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::GetDepthAlarmSetting()
    /// @see STFF::STFishFinder::SetDepthAlarmSetting()
    /// @see STFF::valid(FF_DepthAlarmType_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_DEPTH_ALARM_TYPE = -1,
        FF_DEPTH_ALARM_TYPE_SHALLOW,            ///< Specifies the Shallow depth alarm type
        FF_DEPTH_ALARM_TYPE_DEEP,               ///< Specifies the Deep depth alarm type
        FF_TOTAL_DEPTH_ALARM_TYPES
    } FF_DepthAlarmType_t;


    /// Depth Alarm State options.
    ///
    /// This is a type definition for an enumeration specifying a Depth Alarm State
    /// (disabled, normal, active, or silenced).
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::GetDepthAlarmState()
    /// @see STFF::STFishFinder::SilenceDepthAlarm()
    /// @see STFF::valid(FF_DepthAlarmState_t)
    /// @see STFF::STFishFinder::Callback_DepthAlarmStateChange_t
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_DEPTH_ALARM_STATE = -1,
        FF_DEPTH_ALARM_STATE_DISABLED,          ///< Specifies a depth alarm state of Disabled (depth alarm is disabled)
        FF_DEPTH_ALARM_STATE_NORMAL,            ///< Specifies a depth alarm state of Normal (depth alarm is enabled, but an alarm condition is not present)
        FF_DEPTH_ALARM_STATE_ACTIVE,            ///< Specifies a depth alarm state of Active (depth alarm is enabled, an alarm condition is present, and alarm is sounding)
        FF_DEPTH_ALARM_STATE_SILENCED,          ///< Specifies a depth alarm state of Silenced (depth alarm is enabled, an alarm condition is present, but alarm has been temporarily silenced)
        FF_TOTAL_DEPTH_ALARM_STATES
    } FF_DepthAlarmState_t;


    ////////////////////////////////////////////////////////////////////////
    /// @cond
    /// ^^^^^ Do not include documentation for this yet
    ///
    /// Fish Alarm Setting selection.
    ///
    /// @see STFF::valid(FF_FishAlarmSetting_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_FISH_ALARM_SETTING = -1,
        FF_FISH_ALARM_SETTING_DISABLED,         ///< tbd
        FF_FISH_ALARM_SETTING_ENABLED,          ///< tbd
        FF_TOTAL_FISH_ALARM_SETTINGS
    } FF_FishAlarmSetting_t;
    /// @endcond


    /// API Status selection.
    ///
    /// This is a type definition for an enumeration specifying the status of
    /// the STFishFinder API.
    /// This enumeration resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::GetApiStatus()
    /// @see STFF::valid(FF_ApiStatus_t)
    ///
    /// @ingroup global_enums
    ///
    typedef enum {
        FF_INVALID_API_STATUS = -1,
        FF_API_STATUS_READY,                    ///< Initialization has completed; OK to call getters/setters
        FF_API_STATUS_NOT_INITIALIZED,          ///< Initialization not started; please call the Hello() function
        FF_API_STATUS_INITIALIZING_PLEASE_WAIT, ///< Hello() has been called; now waiting for initialization to complete
        FF_TOTAL_API_STATUSES
    } FF_ApiStatus_t;


    ////////////////////////////////////////////////////////////////////////////////
    /// @defgroup global_structs Global Structures
    ///
    /// These are type definitions for simple structs in the global namespace.
    ///
    /// @remarks These have been placed in the global namespace to simplify linking
    /// with application code written in languages that do not support namespaces.
    ///
    /// @ingroup global_namespace
    ///
    ////////////////////////////////////////////////////////////////////////////////


    /// @struct FF_TemperatureData_t
    ///
    /// Temperature Data structure.
    ///
    /// This is a type definition for a simple struct containing a
    /// water temperature reading.
    /// This struct resides in the global namespace.
    ///
    /// The temperature member of the struct is in hundredths of a degree
    /// (Celsius or Fahrenheit, depending on the value of the units member).
    /// For example, a value of 2510 would represent 25.10 degrees.
    ///
    /// @see STFF::STFishFinder::GetTemperature()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        FF_TemperatureUnits_t   units;          ///< Units (degrees Celsius or degrees Fahrenheit) for the provided temperature value
        int16_t                 temperature;    ///< Temperature value, in hundredths of the specified units
        FF_DataStatus_t         status;         ///< Status of the provided temperature value (valid/invalid, simulated, or log playback)
    } FF_TemperatureData_t;


    /// @struct FF_SpeedData_t
    ///
    /// Speed Data structure.
    ///
    /// This is a type definition for a simple struct containing a
    /// speed-through-water reading.
    /// This struct resides in the global namespace.
    ///
    /// The speed member of the struct is in hundredths of a unit
    /// (knots, mph, or kph, depending on the value of the units member).
    /// For example, a value of 1020 would represent 10.20 knots (or mph, or kph).
    ///
    /// @see STFF::STFishFinder::GetSpeed()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        FF_SpeedUnits_t         units;          ///< Units (knots, mph, or kph) for the provided speed value
        uint16_t                speed;          ///< Speed value, in hundredths of the specified units
        FF_DataStatus_t         status;         ///< Status of the provided speed value (valid/invalid, simulated, or log playback)
    } FF_SpeedData_t;


    /// Depth Data structure.
    ///
    /// This is a type definition for a simple struct containing a depth reading.
    /// This struct resides in the global namespace.
    ///
    /// The depth member of the struct is in hundredths of a unit
    /// (feet, meters, or fathoms, depending on the value of the units member).
    /// For example, a value of 730 would represent 7.30 feet (or meters, or
    /// fathoms).
    ///
    /// @see STFF::STFishFinder::GetDepth()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        FF_DepthUnits_t         units;          ///< Units (feet, meters, or fathoms) for the provided depth value
        uint32_t                depth;          ///< Depth value, in hundredths of the specified units
        FF_DataStatus_t         status;         ///< Status of the provided depth value (valid/invalid, simulated, or log playback)
    } FF_DepthData_t;


    /// Battery Voltage Data structure.
    ///
    /// This is a type definition for a simple struct containing a battery voltage
    /// reading.
    /// This struct resides in the global namespace.
    ///
    /// The voltage member of the struct is in hundredths of a volt.
    /// For example, a value of 1250 would represent 12.50 volts.
    ///
    /// @see STFF::STFishFinder::GetBatteryVoltage()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        uint16_t                voltage;        ///< Voltage of the battery used to power the black box fish finder, in hundredths of a volt
        FF_DataStatus_t         status;         ///< Status of the provided battery voltage value (valid/invalid, simulated, or log playback)
    } FF_BatteryVoltageData_t;


    /// Fish Data structure.
    ///
    /// This is a type definition for a simple struct containing details
    /// regarding a detected "possible fish."
    /// This struct resides in the global namespace.
    ///
    /// When the Fish ID feature is enabled, the black box will perform
    /// heuristics to attempt to detect fish targets in the received signal.
    /// When the black box decides that a given monitored structure meets
    /// the qualifications required to be declared a possible fish target,
    /// it sends the detailed data regarding the possible fish target to the
    /// display device using this struct.
    ///
    /// @todo   The present contents of the ::FF_FishData_t struct
    ///         are only tentative; these need to be firmed up.
    ///
    /// @see    STFF::STFishFinder::SetFishIdSetting()
    /// @see    STFF::STFishFinder::GetFishIdSetting()
    /// @see    FF_FishIdSetting_t
    /// 
    /// @ingroup global_structs
    ///
    typedef struct {
        FF_DepthUnits_t         units;          ///< Units (feet, meters, or fathoms) for the provided depth of the target
        uint32_t                depth;          ///< Depth of target, in hundredths of the specified units
        FF_Frequency_t          frequency;      ///< Frequency context in which the target was detected
        uint16_t                size;           ///< Relative size of target
        uint16_t                intensity;      ///< Relative intensity of target
        FF_DataStatus_t         status;         ///< Status of the data in this struct (valid/invalid, simulated, or log playback)
    } FF_FishData_t;


    /// Range Setting structure.
    ///
    /// This is a type definition for a simple struct containing a fish finder
    /// range setting.
    /// This struct resides in the global namespace.
    ///
    /// The rangeShallow and rangeDeep members of the struct are in hundredths
    /// of a unit (feet, meters, or fathoms, depending on the value of the
    /// units member).  For example, a value of 2000 would represent
    /// 20.00 feet (or meters, or fathoms).
    ///
    /// @see STFF::STFishFinder::SetRange()
    /// @see STFF::STFishFinder::GetRange()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        FF_DepthUnits_t         units;          ///< Units (feet, meters, or fathoms) for the provided rangeShallow and rangeDeep values
        uint32_t                rangeShallow;   ///< Depth corresponding to the first sample in the image buffer, in hundredths of the specified units
        uint32_t                rangeDeep;      ///< Depth corresponding to the last sample in the image buffer, in hundredths of the specified units
    } FF_RangeSetting_t;


    /// FSTC Setting structure.
    ///
    /// This is a type definition for a simple struct containing a FSTC
    /// (Fishfinder Sensitivity Time Constant) setting.
    /// This struct resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetFSTC()
    /// @see STFF::STFishFinder::GetFstc()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        uint16_t                fsts;           ///< Magnitude of gain attenuation at the start of the FSTC ramp at the surface of the transducer
        uint16_t                fstd;           ///< Depth, in tenths of a meter, at the end of the FSTC ramp
    } FF_FstcSetting_t;


    /// DSTC Setting structure.
    ///
    /// This is a type definition for a simple struct containing a DSTC
    /// (Depth Sensitivity Time Constant) setting.
    /// This struct resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetDSTC()
    /// @see STFF::STFishFinder::GetDstc()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        uint16_t                dsts;           ///< Magnitude of gain attenuation at the start of the DSTC ramp at the surface of the transducer
        uint16_t                dstd;           ///< Depth, in tenths of a meter, at the end of the DSTC ramp
    } FF_DstcSetting_t;


    /// Fish ID Setting structure.
    ///
    /// This is a type definition for a simple struct containing a Fish ID setting.
    /// This struct resides in the global namespace.
    ///
    /// @todo   The present contents of the ::FF_FishIdSetting_t struct
    ///         are only tentative; these need to be firmed up.
    ///
    /// @see    STFF::STFishFinder::SetFishIdSetting()
    /// @see    STFF::STFishFinder::GetFishIdSetting()
    /// @see    FF_FishData_t
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        bool                    enabled;
        uint16_t                threshold;
    } FF_FishIdSetting_t;


    ////////////////////////////////////////////////////////////////////////
    /// @cond
    /// ^^^^^ Do not include documentation for this struct
    ///
    /// Water Filter Setting structure.
    ///
    /// This is a type definition for a simple struct containing a
    /// Water Filter setting.
    /// This struct resides in the global namespace.
    ///
    /// @see STFF::STFishFinder::SetWaterFilterSetting()
    /// @see STFF::STFishFinder::GetWaterFilterSetting()
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        bool                    enabled;
    } FF_WaterFilterSetting_t;
    /// @endcond


    ////////////////////////////////////////////////////////////////////////
    /// @cond
    /// ^^^^^ Do not include documentation for this struct
    ///
    /// POST Result structure.
    ///
    /// This is a type definition for a simple struct containing results of a
    /// Power-On Self Test operation.
    /// This struct resides in the global namespace.
    ///
    /// @ingroup global_structs
    ///
    typedef struct {
        // tbd
        int dummy;
    } FF_PostResult_t;
    /// @endcond


#endif  // defined(STFF_Types_h_)