Setters

Functions that allow changing settings in the API and in the connected black box fish finder. More...

Modules
	Setters for Local Settings
	Functions for changing Local Settings.
	Setters for Master Settings
	Functions for changing Master Settings.

Detailed Description

Functions that allow changing settings in the API and in the connected black box fish finder.

Upon calling a setter function, the following sequence of steps occurs:

1. The input parameter(s) are limit checked within the API to ensure their values are within the allowable bounds. At this stage of the process, the input values are not coerced to legal values; if the input values are outside the legal limits, then the setter function will fail with an error message.
   
   
2. A request is sent to the black box to change the setting, and the local setting status corresponding to that setting is set to FF_SETTING_STATUS_PENDING.
   
   

3. The Callback_SettingChanged_t callback function is invoked by the setter function. The parameters provided to the callback are as follows:

   • FF_SettingType_t is set to a unique value that specifies the specific setting that is being changed.
   • If the setting is specific to a frequency context, then the FF_Frequency_t parameter in the call to the Callback_SettingChanged_t callback is set to either FF_FREQUENCY_200_KHZ or FF_FREQUENCY_50_KHZ, depending on the frequency specified in the call to the setter function. If the setting is not frequency-specific, then the FF_Frequency_t parameter is set to FF_INVALID_FREQUENCY.
   • The STFishFinder* parameter is set to point to the present instance of the STFishFinder class. This pointer may be used within the callback to access a getter function.

   Within the callback function, the getter function corresponding to the setting being changed may be called. The pStatus value provided by the getter function will be FF_SETTING_STATUS_PENDING indicating that this call to the callback is occurring prior to having received the response from the black box.
   
   

4. After return from the callback, the setter function returns control to the caller of the setter function.
   
   
5. A short time later, the black box will transmit a response to the API that announces the new setting value. If the setting is a Master Setting, the same message will be transmitted to all displays and apps simultaneously connected to the same black box.
   
   In some circumstances, the new setting may have been coerced by the black box to a slightly different value than the one requested. For example, a value might be rounded off. When the API receives the response, it stores the new setting value within the API, and the local setting status value is set to FF_SETTING_STATUS_VALID.
   
   
6. The Callback_SettingChanged_t callback function is now invoked a second time, with the same parameters as in step 3. This time, a call by the callback to the getter function corresponding to the setting being changed will produce a pStatus of FF_SETTING_STATUS_VALID, indicating that this call to the callback is occurring after the black box has provided a confirmed setting.
   
   If the setting is a Master Setting , and the setting was initiated by a different app (in a different display device) connected to the same black box, then this callback call within the present device will be the first and only invocation of the callback within the present device occurring as a result of the setting change.

Each setter function has a corresponding getter function, which allows the setting to be immediately read back from the local API storage. The See Also section in the description for each setter function includes a link to the description for its corresponding getter function.

Setters are member functions of the STFishFinder class.

See also

Getters

Initialization and Control Functions

Callback_SettingChanged_t