STFF-Callbacks.h

Go to the documentation of this file.

///
/// @file   STFF-Callbacks.h
///
/// Header file containing type definitions for @link callbacks callback @endlink
/// functions used in the %STFishFinder API.
///
/// @copyright
/// Copyright (c) 2012-2015 Sifferman Technology, LLC.  All rights reserved.
///

#ifndef STFF_Callbacks_h_
#define STFF_Callbacks_h_

#include "STFF-Types.h"


namespace STFF {

    // forward declaration
    class STFishFinder;

    ////////////////////////////////////////////////////////////////////////
    //
    // CALLBACK TYPEDEFS
    //
    ////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////
    /// @defgroup   callbacks                       Callbacks
    /// @ingroup    stff_member_functions
    ///
    /// Callbacks provide a facility for the API to call a function in the
    /// wrapper layer or in the application when a certain event occurs.
    /// Callback functions are platform- and application-dependent, and
    /// must be written by users of the STFishFinder API.
    ///
    /// @see        STFishFinder::SetCallbacks()
    ////////////////////////////////////////////////////////////////////////


    ////////////////////////////////////////////////////////////////////////
    /// @typedef    Callback_SettingChanged_t
    ///
    /// 'Setting Changed' callback.
    ///
    /// Type definition for a static callback function that is called by the
    /// STFishFinder API when a setting is changed.
    ///
    /// This callback may be used to send a notification message to
    /// the application to update any GUI elements that depend on
    /// API settings.
    /// For example, if the user changes the range,
    /// the application will call function
    /// @link STFishFinder::SetRange() SetRange() @endlink,
    /// which will send
    /// a Set Range command to the black box fish finder, and will also
    /// call this callback to notify the application to update those
    /// GUI elements that display the range.
    ///
    /// Usually, this callback is called twice each time a setting is
    /// changed by a user. The first call is made immediately when one of
    /// the API setter functions is called from the application.  This
    /// first call to the callback generally occurs concurrently with
    /// sending the associated command to the black box fish finder.
    ///
    /// The second call to this callback occurs when a response message
    /// is received from the black box fish finder, confirming the
    /// setting change.
    ///
    /// These two calls to this callback can be used to provide a
    /// more intuitive behavior in the application when the user
    /// changes a setting.  A recommended approach is to have the
    /// callback function send a notification message to
    /// a delegate for the GUI element(s) that are affected by the
    /// changed setting.  Upon receiving the message, the delegate
    /// would call the getter member
    /// function for the setting type specified in the first argument
    /// of the callback function (e.g. GetRange() ), and then check
    /// the <i>validated</i> flag in the response from the getter
    /// function.  If this is the first call to the callback after
    /// a setting change, then the <i>validated</i> flag will be
    /// @p false.  Since the new setting has not been validated by
    /// the black box, the delegate would change the GUI to display
    /// the new value, but in a dimmed or grayed-out form.
    ///
    /// In the second call to the callback, the
    /// <i>validated</i> flag will be @p true (with the setting value
    /// having been adjusted to a legal value by the black box, if necessary).
    /// In this case, the
    /// new setting value can be shown in the GUI in its normal,
    /// full-contrast form.
    ///
    /// This callback is also called when the API status changes from
    /// ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT to ::FF_API_STATUS_READY,
    /// which occurs after calling the Hello() function and after the
    /// uploading of the initial API state from the black box has completed.
    ///
    /// Below is a suggested C/C++ style declaration for this callback:
    ///
    /// @code
    ///             void OnSettingChanged (const STFishFinder *pFF,
    ///                                    FF_SettingType_t settingType,
    ///                                    FF_Frequency_t frequency);
    /// @endcode
    ///
    /// @note       Before creating any STFishFinder objects, it is
    ///             necessary to call STFishFinder::SetCallbacks()
    ///             to specify the addresses of this and all
    ///             other STFishFinder class callback functions.
    ///
    /// @param[in]  const STFishFinder*
    ///             pointer to the STFishFinder object that initiated
    ///             the call to the callback;
    ///             serves as a 'this' pointer that can be used within
    ///             the callback function to provide object context.
    ///
    /// @param[in]  ::FF_SettingType_t
    ///             the type of setting that has changed
    ///
    /// @param[in]  ::FF_Frequency_t
    ///             the sonar frequency context for this setting change
    ///             (applies only to frequency-dependent settings)
    ///
    /// @returns    void
    ///
    /// @see        STFishFinder::SetCallbacks()
    /// @see        ::FF_SettingType_t
    /// @see        @ref setters
    ///
    /// @ingroup    callbacks
    ///
    typedef void (*Callback_SettingChanged_t) (const STFishFinder*, FF_SettingType_t, FF_Frequency_t);


    ////////////////////////////////////////////////////////////////////////
    /// @typedef    Callback_DataItemReceived_t
    ///
    /// 'Data Item Received' callback.
    ///
    /// Type definition for a static callback function that is called by the
    /// STFishFinder API when a data item is received from the
    /// black box.
    ///
    /// This callback is called upon receipt of the following kinds of
    /// data from the black box:
    /// - Depth
    /// - Water Speed
    /// - Water Temperature
    /// - Battery Voltage
    /// - Image Data
    /// - Detected Fish
    ///
    /// This callback may be used to send a notification message to
    /// the application to update GUI elements that display data
    /// produced by the black box.
    ///
    /// Below is a suggested C/C++ style declaration for this callback:
    ///
    /// @code
    ///             void OnDataItemReceived (const STFishFinder *pFF,
    ///                                      FF_DataType_t dataType,
    ///                                      const void* pParam);
    /// @endcode
    ///
    /// @note       Before creating any STFishFinder objects, it is
    ///             necessary to call STFishFinder::SetCallbacks()
    ///             to specify the addresses of this and all
    ///             other STFishFinder class callback functions.
    ///
    /// @param[in]  const STFishFinder*
    ///             pointer to the STFishFinder object that initiated
    ///             the call to the callback;
    ///             serves as a 'this' pointer that can be used within
    ///             the callback function to provide object context.
    ///
    /// @param[in]  ::FF_DataType_t
    ///             the type of data that has been received
    ///
    /// @param[in]  const void*
    ///             - For data type ::FF_DATA_TYPE_IMAGE:
    ///               Pointer to the ImageColumn object containing the image data
    ///             - For all other data types: Pointer to the originating STFishFinder object
    ///
    /// @returns    void
    ///
    /// @see        STFishFinder::SetCallbacks()
    /// @see        ::FF_DataType_t
    ///
    /// @ingroup    callbacks
    ///
    typedef void (*Callback_DataItemReceived_t) (const STFishFinder*, FF_DataType_t, const void*);


    ////////////////////////////////////////////////////////////////////////
    /// @typedef    Callback_DepthAlarmStateChange_t
    ///
    /// 'Depth Alarm State Change' callback.
    ///
    /// Type definition for a static callback function that is called by the
    /// STFishFinder API when the shallow depth alarm or deep depth
    /// alarm changes state.  It is intended that this callback reside
    /// in the wrapper layer.
    ///
    /// This callback may be used to send a notification message to
    /// the application to play an alarm sound, or to terminate
    /// the playing of an alarm sound indicating an active depth alarm.
    /// It may also be used to send a notification message to cause
    /// an alarm popup window to appear, or to cause some other visual
    /// indication of the presence of an alarm condition.
    ///
    /// Below is a suggested C/C++ style declaration for this callback:
    ///
    /// @code{.cpp}
    ///             void OnDepthAlarmStateChange (const STFishFinder *pFF,
    ///                                           FF_DepthAlarmState_t depthAlarmState);
    /// @endcode
    ///
    /// @note       Before creating any STFishFinder objects, it is
    ///             necessary to call STFishFinder::SetCallbacks()
    ///             to specify the addresses of this and all
    ///             other STFishFinder class callback functions.
    ///
    /// @param[in]  const STFishFinder*
    ///             pointer to the STFishFinder object that initiated
    ///             the call to the callback;
    ///             serves as a 'this' pointer that can be used within
    ///             the callback function to provide object context.
    ///
    /// @param[in]  ::FF_DepthAlarmType_t
    ///             the type of depth alarm affected (shallow or deep)
    ///
    /// @returns    void
    ///
    /// @see        STFishFinder::SetCallbacks()
    /// @see        STFishFinder::GetDepthAlarmState()
    /// @see        STFishFinder::SilenceDepthAlarm()
    /// @see        @ref depth_alarms_how_to
    ///
    /// @ingroup    callbacks
    ///
    typedef void (*Callback_DepthAlarmStateChange_t) (const STFishFinder*, FF_DepthAlarmType_t);


    ////////////////////////////////////////////////////////////////////////
    /// @typedef    Callback_FishAlarmTrigger_t
    ///
    /// 'Fish Alarm Trigger' callback.
    ///
    /// Type definition for a static callback function that is called by the
    /// STFishFinder API when a possible fish is detected.
    /// It is intended that this callback reside in the wrapper layer.
    ///
    /// This callback may be used to send a notification message to
    /// the application to play an alarm sound corresponding to the
    /// detection of a possible fish target.
    ///
    /// Below is a suggested C/C++ style declaration for this callback:
    ///
    /// @code{.cpp}
    ///             void OnFishAlarmTrigger (const STFishFinder *pFF,
    ///                                      FF_FishData_t fishData);
    /// @endcode
    ///
    /// @note       Before creating any STFishFinder objects, it is
    ///             necessary to call STFishFinder::SetCallbacks()
    ///             to specify the addresses of this and all
    ///             other STFishFinder class callback functions.
    ///
    /// @param[in]  const STFishFinder*
    ///             pointer to the STFishFinder object that initiated
    ///             the call to the callback;
    ///             serves as a 'this' pointer that can be used within
    ///             the callback function to provide object context.
    ///
    /// @param[in]  ::FF_FishData_t
    ///             data structure providing information regarding the
    ///             detected target
    ///
    /// @returns    void
    ///
    /// @see        STFishFinder::SetCallbacks()
    /// @see        STFishFinder::SetFishAlarmSetting()
    /// @see        STFishFinder::GetFishAlarmSetting()
    /// @see        ::FF_FishAlarmSetting_t
    ///
    /// @ingroup    callbacks
    ///
    typedef void (*Callback_FishAlarmTrigger_t) (const STFishFinder*, FF_FishData_t);


    ////////////////////////////////////////////////////////////////////////
    /// @typedef Callback_StreamDataToFF_t
    ///
    /// 'Stream Data to FishFinder' callback.
    ///
    /// Type definition for a static callback function that is called by the
    /// STFishFinder API when it needs to send a message to the
    /// black box fish finder.
    ///
    /// It is intended that this callback reside in the wrapper layer.
    ///
    /// Normally, this callback should simply invoke the necessary OS
    /// library function to transmit a character string over the network
    /// interface to the black box fish finder.
    ///
    /// Below is a suggested C/C++ style declaration for this callback:
    ///
    /// @code{.cpp}
    ///             void StreamDataToFF (const STFishFinder *pFF,
    ///                                  const char *pData,
    ///                                  uint32_t numChars);
    /// @endcode
    ///
    /// @note       Before creating any STFishFinder objects, it is
    ///             necessary to call STFishFinder::SetCallbacks()
    ///             to specify the addresses of this and all
    ///             other STFishFinder class callback functions.
    ///
    /// @param[in]  const STFishFinder*
    ///             pointer to the STFishFinder object that initiated
    ///             the call to the callback;
    ///             serves as a 'this' pointer that can be used within
    ///             the callback function to provide object context.
    ///
    /// @param[in]  const char*
    ///             pointer to character string containing message to be
    ///             transmitted
    ///
    /// @param[in]  uint32_t
    ///             number of characters in the string
    ///
    /// @returns    void
    ///
    /// @see        STFishFinder::SetCallbackStreamDataToFF
    ///
    /// @ingroup    callbacks
    ///
    typedef void (*Callback_StreamDataToFF_t) (const STFishFinder*, const char*, uint32_t);

}       // namespace STFF

#endif  // #defined (STFF_Callbacks_h_)