Functions that provide initialization and control of the connected black box fish finder and of the STFishFinder API. More...

Functions
static FF_Error_t	STFF::STFishFinder::SetCallbacks (Callback_SettingChanged_t pSettingChanged, Callback_DataItemReceived_t pDataItemReceived, Callback_DepthAlarmStateChange_t pDepthAlarmStateChange, Callback_FishAlarmTrigger_t pFishAlarmTrigger, Callback_StreamDataToFF_t pStreamDataToFF)
	Specifies the static callback functions to be called by the STFishFinder API when specific events occur. More...

FF_Error_t	STFF::STFishFinder::Hello ()
	Initiates communication with the black box fish finder after a connection is established. More...

FF_ApiStatus_t	STFF::STFishFinder::GetApiStatus () const
	Returns the status of the STFishFinder API. More...

FF_Error_t	STFF::STFishFinder::Control (FF_ControlCommand_t command, const void *pParam)
	Provides a facility to alter system-related behavior of the black box and API. More...

FF_Error_t	STFF::STFishFinder::ParseFFInputStream (char *pInputStream, uint32_t numBytes)
	This function parses and interprets the stream of messages from the black box fish finder, and calls API methods to perform actions according to the data received. More...

FF_Error_t	STFF::STFishFinder::StartRecording (Replay *pReplay)
	This function enables the recording of an API session. More...

FF_Error_t	STFF::STFishFinder::StopRecording ()
	This function discontinues the recording of the API session that was initiated by a call to StartRecording. More...

void	STFF::STFishFinder::TimerTick ()
	Provides a means by which time-dependent processes within the STFishFinder API can be serviced on a periodic basis. More...

FF_Error_t	STFF::STFishFinder::SilenceDepthAlarm (FF_DepthAlarmType_t alarmType, int32_t durationSeconds)
	Sends a message to the black box instructing it to temporarily silence a currently active depth alarm. More...

FF_Error_t	STFF::STFishFinder::GetDepthAlarmState (FF_DepthAlarmState_t pShallowAlarmState, FF_DepthAlarmState_t pDeepAlarmState, FF_DataStatus_t *pStatus) const
	Provides the current state of both the shallow depth alarm and the deep depth alarm. More...

Detailed Description

Functions that provide initialization and control of the connected black box fish finder and of the STFishFinder API.

See also: Callbacks; Getters; Setters

Function Documentation

STFF::STFishFinder::Control	(	FF_ControlCommand_t	command,
		const void *	pParam
	)

#include <STFF-FishFinder.h>

Provides a facility to alter system-related behavior of the black box and API.

In particular, the Control() function is used to enable and/or disable the transmission of black box originated data messages.

On initial connection to a black box, transmission of data messages (Depth, Speed, Temperature, Battery Voltage, Image data, Fish data, and Depth Alarm messages) is disabled. After a connection is established, and the API initialized via a call to Hello(), the Control() function must be called in order to establish the periodic transmission of required data messages.

Parameters

[in]	command	the command to be performed
[in]	pParam	Usage depends on the value of `command`. If `command` is FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES, then `pParam` must be cast to a value of type FF_ControlEnableBlackBoxMsg_t. The `pParam` value may be a logical OR of different FF_ControlEnableBlackBoxMsg_t values, in order to enable the transmission of more than one type of message.

Return values

FF_ERR_NO_ERROR	normal return
FF_ERR_ARGUMENT_OUT_OF_RANGE	if one or both of the arguments contained an unrecognized value
FF_ERR_API_NOT_INITIALIZED	if the Hello() function was not previously called, or did not return successfully.
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Todo:: Add a command to the Control() method to specify whether the API and black box should use a secondary communication channel (e.g. UDP instead of TCP) for transmission of Image data.

Todo:: Add a command to the Control() method to enable or disable calls to individual callbacks

See also: FF_ControlCommand_t; FF_ControlEnableBlackBoxMsg_t

STFF::STFishFinder::GetApiStatus ( ) const

#include <STFF-FishFinder.h>

Returns the status of the STFishFinder API.

This function may be used to poll the API after calling Hello(), to determine whether the black box has finished uploading the initial state to the API.

Note: This function can be used in conjunction with the Callback_SettingChanged_t callback function. This callback will be called when the API status changes from FF_API_STATUS_INITIALIZING_PLEASE_WAIT to FF_API_STATUS_READY, which occurs when the uploading operation has completed.

API Status Described

The FF_ApiStatus_t value provided by this function can have one of the following three states:

Here is a description of the meanings of these three states as they apply to the process of initializing the API.

FF_API_STATUS_NOT_INITIALIZED
After the STFishFinder() class constructor has been called (creating a STFishFinder instance), but before the Hello() member function has been called, the API status is FF_API_STATUS_NOT_INITIALIZED. In this case, the only STFishFinder class member functions that will produce meaningful results are Hello() and GetApiStatus(). Calls to all other member functions when in this state will only produce a return error code of FF_ERR_API_NOT_INITIALIZED.
FF_API_STATUS_INITIALIZING_PLEASE_WAIT
When Hello() is called, a special message is transmitted from the API to the black box, and the API status changes to FF_API_STATUS_INITIALIZING_PLEASE_WAIT. Upon return from Hello(), this is normally the API status. When the black box has received the special message, it begins uploading initial state information to the API. The API receives this state information through a series of wrapper calls to ParseFFInputStream(). While this is occurring, the API status remains at FF_API_STATUS_INITIALIZING_PLEASE_WAIT.
FF_API_STATUS_READY
When the process of uploading the initial state has completed, the API status changes to FF_API_STATUS_READY, and the Callback_SettingChanged_t callback function is called, with its first argument containing the value FF_SETTING_TYPE_API_READY. At this time, all other member functions become usable. It is recommended that the application program now perform its own initialization of the API by calling the various Setters functions, followed by a call to Control() to enable transmission of data messages.

Return values

FF_API_STATUS_NOT_INITIALIZED	the application needs to call the API function Hello() before calling other API member functions
FF_API_STATUS_INITIALIZING_PLEASE_WAIT	the black box is uploading initial state information to the API
FF_API_STATUS_READY	the API is ready for use

See also: Hello(); Callback_SettingChanged_t; FF_ApiStatus_t; How To Connect to a Black Box Fish Finder

STFF::STFishFinder::GetDepthAlarmState	(	FF_DepthAlarmState_t *	pShallowAlarmState,
		FF_DepthAlarmState_t *	pDeepAlarmState,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Provides the current state of both the shallow depth alarm and the deep depth alarm.

Parameters

[out]	pShallowAlarmState	pointer to a location where the current shallow alarm state will be stored. If this parameter is a null pointer, then no value will be stored.
[out]	pDeepAlarmState	pointer to a location where the current deep alarm state will be stored. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided depth alarm state values (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR

See also: Callback_DepthAlarmStateChange_t; SilenceDepthAlarm

STFF::STFishFinder::Hello ( )

#include <STFF-FishFinder.h>

Initiates communication with the black box fish finder after a connection is established.

This function should be called immediately after successfully opening the communication channel to the black box fish finder.

This function performs the following tasks:

Initiates the first exchange of messages between the STFishFinder API and the newly-connected black box
Changes the API Status to FF_API_STATUS_INITIALIZING_PLEASE_WAIT

On return from this function, the API status remains at FF_API_STATUS_INITIALIZING_PLEASE_WAIT while the black box uploads the initial state to the API. (This uploading process occurs through wrapper calls to function ParseFFInputStream() as messages are received from the black box.)

Note: After this function is called, the API status must reach the FF_API_STATUS_READY state, before calling other STFishFinder class member functions.

Return values

FF_ERR_NO_ERROR	normal return
FF_ERR_API_ALREADY_INITIALIZED	if the API status prior to calling Hello() was not FF_API_STATUS_NOT_INITIALIZED
FF_ERR_BAD_DATABASE	if the API encounters an internal error

See also: GetApiStatus(); FF_ApiStatus_t; How To Connect to a Black Box Fish Finder

STFF::STFishFinder::ParseFFInputStream	(	char *	pInputStream,
		uint32_t	numBytes
	)

#include <STFF-FishFinder.h>

This function parses and interprets the stream of messages from the black box fish finder, and calls API methods to perform actions according to the data received.

This function is to be called by a handler in the wrapper when a packet of data received from the black box fish finder becomes available on the input stream.

Parameters

[in]	pInputStream	pointer to a buffer containing the received data
[in]	numBytes	number of characters in the buffer

Return values

FF_ERR_NO_ERROR

STFF::STFishFinder::SetCallbacks	(	Callback_SettingChanged_t	pSettingChanged,
		Callback_DataItemReceived_t	pDataItemReceived,
		Callback_DepthAlarmStateChange_t	pDepthAlarmStateChange,
		Callback_FishAlarmTrigger_t	pFishAlarmTrigger,
		Callback_StreamDataToFF_t	pStreamDataToFF
	)

static

#include <STFF-FishFinder.h>

Specifies the static callback functions to be called by the STFishFinder API when specific events occur.

This static member function must be called once to initialize the API callback pointers prior to instantiating any STFishFinder objects.

Parameters

[in]	pSettingChanged	pointer to static callback function that manages setting changes for the app. If this parameter is a null pointer, then the Setting Changed callback mechanism will be disabled.
[in]	pDataItemReceived	pointer to static callback function that handles data received from the black box. If this parameter is a null pointer, then the Data Item Received callback mechanism will be disabled.
[in]	pDepthAlarmStateChange	pointer to static callback function that handles changes in the state of the Depth Alarm. If this parameter is a null pointer, then the Depth Alarm State Change callback mechanism will be disabled.
[in]	pFishAlarmTrigger	pointer to static callback function that handles the sounding of an alarm upon detection of a fish target. If this parameter is a null pointer, then the Fish Alarm Trigger callback mechanism will be disabled.
[in]	pStreamDataToFF	pointer to static callback function that passes messages from the STFishFinder API to a connected black box via an appropriate driver on the platform. If this parameter is a null pointer, then the API will be unable to communicate with a black box fish finder.

Return values

FF_ERR_NO_ERROR	normal return
FF_ERR_CANT_CHANGE_CALLBACKS	the function was called after instantiating an STFishFinder object

Note: This function will fail with error code FF_ERR_CANT_CHANGE_CALLBACKS if it is called when one or more STFishFinder objects exist. This function must be called before calling CreateFishFinder(), CreateSimulatedFishFinder(), or CreateFishFinderForPlayback().; All API callback mechanisms will be disabled if STFishFinder is instantiated without first calling this function.

See also: Callbacks

STFF::STFishFinder::SilenceDepthAlarm	(	FF_DepthAlarmType_t	alarmType,
		int32_t	durationSeconds
	)

#include <STFF-FishFinder.h>

Sends a message to the black box instructing it to temporarily silence a currently active depth alarm.

This function will transmit the message to the black box regardless of whether the specified depth alarm is in fact active at the time of transmission.

The result of silencing an active depth alarm is that the black box will transmit a message to all connected display devices (including the one that invoked the SilenceDepthAlarm() function) instructing them to change the state for the specified depth alarm to FF_DEPTH_ALARM_STATE_SILENCED. In each display device, the receipt of this message will trigger a call to the designated Callback_DepthAlarmStateChange_t callback function. This callback should then turn off the audible alert within the application. It is recommended that a visual indicator remain onscreen to remind the user that the given alarm condition is still present.

Parameters

[in]	alarmType	enumeration specifying whether the alarm to be silenced is the shallow depth alarm or the deep depth alarm
[in]	durationSeconds	number of seconds for which the specified alarm should be silenced. This parameter is regarded as a request, not a mandate; the black box may choose to override this value. A value of 30 seconds is suggested as a nominal value for this parameter.

Return values

FF_ERR_NO_ERROR

See also: Callback_DepthAlarmStateChange_t

STFF::STFishFinder::StartRecording ( Replay * pReplay )

#include <STFF-FishFinder.h>

This function enables the recording of an API session.

After this function is called, all subsequent data items received from the connected black box will be recorded and appended to previously recorded data in the provided Replay object.

Parameters

[in] pReplay pointer to Replay object that will contain the recorded session data.

Return values

FF_ERR_NO_ERROR	: Recording of the session was successfully started.
FF_ERR_INVALID_POINTER	: the `pReplay` parameter was a null pointer

See also: StopRecording; CreateFishFinderForPlayback; Replay

STFF::STFishFinder::StopRecording ( )

#include <STFF-FishFinder.h>

This function discontinues the recording of the API session that was initiated by a call to StartRecording.

Return values

FF_ERR_NO_ERROR

See also: StartRecording; CreateFishFinderForPlayback

STFF::STFishFinder::TimerTick ( )

#include <STFF-FishFinder.h>

Provides a means by which time-dependent processes within the STFishFinder API can be serviced on a periodic basis.

The TimerTick() function should be called approximately every 100 milliseconds by a system timer process under control of the wrapper.

TimerTick() is used by the STFishFinder API to perform API housekeeping, and to initiate the generation of data messages in simulator and playback modes.

Returns: void