Callbacks

Callbacks provide a facility for the API to call a function in the wrapper layer or in the application when a certain event occurs. More...

Typedefs
typedef void(*	STFF::Callback_SettingChanged_t) (const STFishFinder *, FF_SettingType_t, FF_Frequency_t)
	'Setting Changed' callback. More...
typedef void(*	STFF::Callback_DataItemReceived_t) (const STFishFinder *, FF_DataType_t, const void *)
	'Data Item Received' callback. More...
typedef void(*	STFF::Callback_DepthAlarmStateChange_t) (const STFishFinder *, FF_DepthAlarmType_t)
	'Depth Alarm State Change' callback. More...
typedef void(*	STFF::Callback_FishAlarmTrigger_t) (const STFishFinder *, FF_FishData_t)
	'Fish Alarm Trigger' callback. More...
typedef void(*	STFF::Callback_StreamDataToFF_t) (const STFishFinder *, const char *, uint32_t)
	'Stream Data to FishFinder' callback. More...

Detailed Description

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 also

STFishFinder::SetCallbacks()

Typedef Documentation

STFF::Callback_DataItemReceived_t

#include <STFF-Callbacks.h>

'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:

void OnDataItemReceived (const STFishFinder *pFF,
                         FF_DataType_t dataType,
                         const void* pParam);

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.

Parameters

[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.
[in]	FF_DataType_t	the type of data that has been received
[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 also

STFishFinder::SetCallbacks()

FF_DataType_t

Definition at line 190 of file STFF-Callbacks.h.

STFF::Callback_DepthAlarmStateChange_t

#include <STFF-Callbacks.h>

'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:

void OnDepthAlarmStateChange (const STFishFinder *pFF,
                              FF_DepthAlarmState_t depthAlarmState);

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.

Parameters

[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.
[in]	FF_DepthAlarmType_t	the type of depth alarm affected (shallow or deep)

Returns

void

See also

STFishFinder::SetCallbacks()

STFishFinder::GetDepthAlarmState()

STFishFinder::SilenceDepthAlarm()

How To Use the Depth Alarms

Definition at line 240 of file STFF-Callbacks.h.

STFF::Callback_FishAlarmTrigger_t

#include <STFF-Callbacks.h>

'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:

void OnFishAlarmTrigger (const STFishFinder *pFF,
                         FF_FishData_t fishData);

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.

Parameters

[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.
[in]	FF_FishData_t	data structure providing information regarding the detected target

Returns

void

See also

STFishFinder::SetCallbacks()

STFishFinder::SetFishAlarmSetting()

STFishFinder::GetFishAlarmSetting()

::FF_FishAlarmSetting_t

Definition at line 287 of file STFF-Callbacks.h.

STFF::Callback_SettingChanged_t

#include <STFF-Callbacks.h>

'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 SetRange() , 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 validated flag in the response from the getter function. If this is the first call to the callback after a setting change, then the validated flag will be 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 validated flag will be 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:

void OnSettingChanged (const STFishFinder *pFF,
                       FF_SettingType_t settingType,
                       FF_Frequency_t frequency);

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.

Parameters

[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.
[in]	FF_SettingType_t	the type of setting that has changed
[in]	FF_Frequency_t	the sonar frequency context for this setting change (applies only to frequency-dependent settings)

Returns

void

See also

STFishFinder::SetCallbacks()

FF_SettingType_t

Setters

Definition at line 131 of file STFF-Callbacks.h.

STFF::Callback_StreamDataToFF_t

#include <STFF-Callbacks.h>

'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:

void StreamDataToFF (const STFishFinder *pFF,
                     const char *pData,
                     uint32_t numChars);

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.

Parameters

[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.
[in]	const	char* pointer to character string containing message to be transmitted
[in]	uint32_t	number of characters in the string

Returns

void

See also

STFishFinder::SetCallbackStreamDataToFF

Definition at line 337 of file STFF-Callbacks.h.