STFishFinder API  API version 0.0.0, Documentation version 3 -PRELIMINARY-
STFF-FishFinder.h
Go to the documentation of this file.
1 ///
2 /// @file STFF-FishFinder.h
3 ///
4 /// Header file for the STFF::STFishFinder class.
5 ///
6 /// @copyright
7 /// Copyright (c) 2012-2015 Sifferman Technology, LLC. All rights reserved.
8 ///
9 
10 #ifndef STFF_STFishFinder_h_
11 #define STFF_STFishFinder_h_
12 
13 #include "STFF-Callbacks.h"
14 #include "STFF-Replay.h"
15 #include "STFF-Types.h"
16 #include "STFF-Version.h"
17 #include <cstdint>
18 
19 
20 ////////////////////////////////////////////////////////////////////////////////
21 /// @namespace STFF
22 /// This is the namespace containing the platform-independent
23 /// %STFishFinder API.
24 /// Within the @b %STFF namespace, the API contains four classes:
25 /// STFishFinder, ImageColumn, Replay, and Version, and a few non-member
26 /// utility functions for performing units conversions and value checking.
27 ///
28 namespace STFF {
29 
30  ////////////////////////////////////////////////////////////////////////////
31  /// @class STFishFinder
32  ///
33  /// This is the main class for the %STFishFinder API.
34  ///
35  /// This class should be instantiated when a connection
36  /// (e.g. a TCP session over IP, or a serial port connection)
37  /// has been established with a compatible black box fish finder.
38  /// It must also be instantiated in order to operate the API in
39  /// either Simulator Mode or Playback Mode.
40  ///
41  /// The instance should be destroyed upon loss of the connection, or
42  /// when the STFishFinder object is no longer needed.
43  ///
44  /// This class contains the current state of the black box fish finder
45  /// as it pertains to the present app. The state may be queried or
46  /// changed through the various member functions provided by this class.
47  ///
48  /// There are two cases where an app might want to create more than
49  /// one instance of the STFishFinder class:
50  /// - The app might display live data and previously recorded data
51  /// simultaneously, in separate windows
52  /// - Conceivably, an app could operate multiple black box fish finders
53  /// simultaneously
54  /// In these cases, an instance of this class would be created for each
55  /// connected black box or virtual session.
56  ///
57  /// @todo Add a member function to reset non-volatile memory in the
58  /// black box to factory default
59  ///
60  /// @todo Add a module for providing firmware updates to the black box
61  ///
62  /// @todo Rename FishAlarmTrigger callback to FishDetected.
63  /// (This callbacks would be used for both fish alarms and Fish ID.)
64  ///
65  /// @todo Add setter and getter functions for Fish Alarm functionality.
66  ///
67  /// @todo Eliminate FF_WaterType_t, and GetWaterType() and SetWaterType().
68  /// Replace all with GetSoundSpeed() and SetSoundSpeed(), and
69  /// add constants for soundspeed for saltwater and freshwater.
70  ///
71  /// @todo Define attribute getters to provide both short form and long form
72  /// copyright and license info for both the API and the black box
73  /// firmware, in a choice of limited html or plain text.
74  ///
75  /// @todo Create SetBitDepth() and GetBitDepth() functions.
76  ///
77  /// @todo Add getters and setters for adjusting the STC.
78  ///
79  /// @todo Add getters and setters for adjusting sonar image filters
80  /// (such as, e.g. water filter, clutter filter, noise filter,
81  /// interference rejection, and DSP BW filters)
82  ///
83  class STFishFinder {
84 
85  public:
86 
87  /// @var MaxAttributeStringLength
88  ///
89  /// Maximum size of character strings, including the terminating '\\0',
90  /// provided by certain getter member functions in this class.
91  /// In the unlikely event a string were to exceed this length, it will
92  /// be truncated to this length by the getter function before storing
93  /// to the caller's buffer.
94  ///
95  static const uint16_t MaxAttributeStringLength = 256;
96 
97 
98  ////////////////////////////////////////////////////////////////////////
99  /// @defgroup stff_member_functions Member Functions
100  ///
101  /// Member functions of the STFishFinder class.
102  ///
103  /// @see stff_non_member_functions
104  ////////////////////////////////////////////////////////////////////////
105 
106 
107  ////////////////////////////////////////////////////////////////////////
108  //
109  // CONSTRUCTORS AND DESTRUCTORS
110  //
111  ////////////////////////////////////////////////////////////////////////
112 
113  ////////////////////////////////////////////////////////////////////////
114  /// @defgroup stff_ctors_dtors Constructors and Destructors
115  ///
116  /// Constructors and destructors for the STFishFinder class.
117  ////////////////////////////////////////////////////////////////////////
118 
119 
120  ////////////////////////////////////////////////////////////////////////
121  /// @fn STFishFinder* CreateFishFinder
122  ///
123  /// Use this function to create an STFishFinder API object
124  /// once a connection (or session) has been established with a
125  /// compatible black box fish finder.
126  ///
127  /// This function is a wrapper for the @b %STFishFinder() class
128  /// constructor.
129  /// The actual @b %STFishFinder() constructor is a private member
130  /// of the STFishFinder class.
131  /// The present member function insulates the calling environment
132  /// from any exceptions that might be thrown when constructing the
133  /// STFishFinder object. If an exception occurs, this function
134  /// catches the exception and provides an appropriate error code
135  /// to the caller.
136  ///
137  /// Conceptually, if a system is otherwise designed to accommodate
138  /// multiple black box fish finders, this function should be called
139  /// once for each connected black box.
140  ///
141  /// @param[out] pError
142  /// pointer to a location that will be written with an
143  /// ::FF_Error_t error code indicating whether the
144  /// STFishFinder object was successfully created.
145  /// If the @p pError parameter is a null pointer,
146  /// then no error code will be stored.
147  /// Specific error codes include:
148  /// - ::FF_ERR_NO_ERROR : the STFishFinder object was created successfully
149  /// - ::FF_ERR_EXCEPTION_OCCURRED : an exception occurred when attempting to construct the STFishFinder object
150  ///
151  /// @returns STFishFinder*
152  /// pointer to a new STFishFinder object, or
153  /// @p null if an error occurs
154  ///
155  /// @note When the returned STFishFinder object is no longer
156  /// needed, use the ~STFishFinder() destructor to
157  /// deallocate the memory used by the object.@n
158  /// For example:
159  /// @code
160  /// using namespace STFF;
161  ///
162  /// STFishFinder* pFF;
163  /// FF_Error_t error;
164  ///
165  /// pFF = CreateFishFinder (&error);
166  ///
167  /// if (error == FF_ERR_NO_ERROR && pFF) {
168  /// pFF->Hello();
169  ///
170  /// // (Use the created STFishFinder object)
171  ///
172  /// // When the object is eventually no longer needed:
173  /// delete pFF;
174  /// }
175  /// @endcode
176  ///
177  /// @see STFishFinder* CreateSimulatedFishFinder
178  /// @see STFishFinder* CreateFishFinderForPlayback
179  ///
180  /// @see ~STFishFinder()
181  ///
182  /// @ingroup stff_ctors_dtors
183  ///
184  static STFishFinder* CreateFishFinder (FF_Error_t *pError);
185 
186 
187  ////////////////////////////////////////////////////////////////////////
188  /// @fn STFishFinder* CreateSimulatedFishFinder
189  ///
190  /// Use this function to create an STFishFinder API object
191  /// that provides simulated data for demonstration purposes
192  /// in the absence of an actual black box fish finder.
193  ///
194  /// This function is a wrapper for a @b STFishFinder() class
195  /// constructor.
196  /// The actual @b STFishFinder() constructor is a private member
197  /// of the STFishFinder class.
198  /// The present member function insulates the calling environment
199  /// from any exceptions that might be thrown when constructing the
200  /// STFishFinder object. If an exception occurs, this function
201  /// catches the exception and provides an appropriate error code
202  /// to the caller.
203  ///
204  /// @param[out] pError
205  /// pointer to a location that will be written with an
206  /// FF_Error_t error code indicating whether the
207  /// STFishFinder object was successfully created.
208  /// If the @p pError parameter is a null pointer,
209  /// then no error code will be stored.
210  /// Specific error codes include:
211  /// - ::FF_ERR_NO_ERROR : the STFishFinder object was created successfully
212  /// - ::FF_ERR_EXCEPTION_OCCURRED : an exception occurred when attempting to construct the STFishFinder object
213  ///
214  /// @returns STFishFinder*
215  /// pointer to a new STFishFinder object, or
216  /// @p null if an error occurs
217  ///
218  /// @note When the returned STFishFinder object is no longer
219  /// needed, use the ~STFishFinder() destructor to
220  /// deallocate the memory used by the object.@n
221  /// For example:
222  /// @code
223  /// using namespace STFF;
224  ///
225  /// STFishFinder* pFF;
226  /// FF_Error_t error;
227  ///
228  /// pFF = CreateSimulatedFishFinder (&error);
229  ///
230  /// if (error == FF_ERR_NO_ERROR && pFF) {
231  /// pFF->Hello();
232  ///
233  /// // (Use the created STFishFinder object)
234  ///
235  /// // When the object is eventually no longer needed:
236  /// delete pFF;
237  /// }
238  /// @endcode
239  ///
240  /// @see STFishFinder* CreateFishFinder
241  /// @see STFishFinder* CreateFishFinderForPlayback
242  ///
243  /// @ingroup stff_ctors_dtors
244  ///
245  static STFishFinder* CreateSimulatedFishFinder (FF_Error_t *pError);
246 
247 
248  ////////////////////////////////////////////////////////////////////////
249  /// @fn STFishFinder* CreateFishFinderForPlayback
250  ///
251  /// Use this function to create an STFishFinder API object
252  /// for the purpose of playing back a previously recorded session.
253  ///
254  /// This function is a wrapper for a @b STFishFinder() class
255  /// constructor.
256  /// The actual @b STFishFinder() constructor is a private member
257  /// of the STFishFinder class.
258  /// The present member function insulates the calling environment
259  /// from any exceptions that might be thrown when constructing the
260  /// STFishFinder object. If an exception occurs, this function
261  /// catches the exception and provides an appropriate error code
262  /// to the caller.
263  ///
264  /// @param[in] pPlaybackData
265  /// pointer to Replay object containing the
266  /// session data to be played back.
267  /// If this parameter is a null pointer, then
268  /// no STFishFinder object will be created,
269  /// the @p pError location will be written with
270  /// ::FF_ERR_INVALID_POINTER, and the function will
271  /// return @p null.
272  ///
273  /// @param[out] pError
274  /// pointer to a location that will be written with an
275  /// ::FF_Error_t error code indicating whether the
276  /// STFishFinder object was successfully created.
277  /// If the @p pError parameter is a null pointer,
278  /// then no error code will be stored.
279  /// Specific error codes include:
280  /// - ::FF_ERR_NO_ERROR : the STFishFinder object was created successfully
281  /// - ::FF_ERR_EXCEPTION_OCCURRED : an exception occurred when attempting to construct the STFishFinder object
282  /// - ::FF_ERR_INVALID_POINTER : the @p pPlaybackData parameter was a null pointer
283  ///
284  /// @returns STFishFinder*
285  /// pointer to a new STFishFinder object, or
286  /// @p null if an error occurs
287  ///
288  /// @note When the returned STFishFinder object is no longer
289  /// needed, use the ~STFishFinder() destructor to
290  /// deallocate the memory used by the object.@n
291  /// For example:
292  /// @code
293  /// using namespace STFF;
294  ///
295  /// STFishFinder* pFF;
296  /// FF_Error_t error;
297  ///
298  /// const Replay* pPlaybackObject = &PreviouslySavedReplayObject;
299  ///
300  /// pFF = CreateFishFinderForPlayback (pPlaybackObject, &error);
301  ///
302  /// if (error == FF_ERR_NO_ERROR && pFF) {
303  /// pFF->Hello();
304  ///
305  /// // (Use the created STFishFinder object)
306  ///
307  /// // When the object is eventually no longer needed:
308  /// delete pFF;
309  /// }
310  /// @endcode
311  ///
312  /// @see STFishFinder* CreateFishFinder
313  /// @see STFishFinder* CreateSimulatedFishFinder
314  ///
315  /// @ingroup stff_ctors_dtors
316  ///
317  static STFishFinder* CreateFishFinderForPlayback
318  (const Replay* pPlaybackData,
319  FF_Error_t *pError
320  );
321 
322 
323  ////////////////////////////////////////////////////////////////////////
324  /// @fn ~STFishFinder
325  ///
326  /// This is the STFishFinder class destructor.
327  ///
328  /// The ~STFishFinder() destructor should be called when
329  /// - the connection to the associated black box fish finder has been lost
330  /// (or the session has closed), or
331  /// - an STFishFinder object created for use in Simulator Mode or
332  /// Playback Mode is no longer needed.
333  ///
334  /// @returns (not applicable)
335  ///
336  /// @ingroup stff_ctors_dtors
337  ///
338  ~STFishFinder ();
339 
340 
341  ////////////////////////////////////////////////////////////////////////
342  //
343  // INITIALIZATION AND CONTROL FUNCTIONS
344  //
345  ////////////////////////////////////////////////////////////////////////
346 
347  ////////////////////////////////////////////////////////////////////////
348  /// @defgroup init_and_control Initialization and Control Functions
349  /// @ingroup stff_member_functions
350  ///
351  /// Functions that provide initialization and control of the connected
352  /// black box fish finder and of the %STFishFinder API.
353  ///
354  /// @see callbacks
355  /// @see getters
356  /// @see setters
357  ////////////////////////////////////////////////////////////////////////
358 
359 
360  ////////////////////////////////////////////////////////////////////////
361  /// @fn SetCallbacks
362  ///
363  /// Specifies the static callback functions to be called by
364  /// the STFishFinder API when specific events occur.
365  /// This static member function must be called once to initialize
366  /// the API callback pointers prior to instantiating any STFishFinder
367  /// objects.
368  ///
369  /// @param[in] pSettingChanged
370  /// pointer to static callback function that manages
371  /// setting changes for the app.
372  /// If this parameter is a null pointer, then the
373  /// <i>Setting Changed</i> callback mechanism
374  /// will be disabled.
375  ///
376  /// @param[in] pDataItemReceived
377  /// pointer to static callback function that
378  /// handles data received from the black box.
379  /// If this parameter is a null pointer, then the
380  /// <i>Data Item Received</i> callback mechanism
381  /// will be disabled.
382  ///
383  /// @param[in] pDepthAlarmStateChange
384  /// pointer to static callback function that handles
385  /// changes in the state of the Depth Alarm.
386  /// If this parameter is a null pointer, then the
387  /// <i>Depth Alarm State Change</i> callback mechanism
388  /// will be disabled.
389  ///
390  /// @param[in] pFishAlarmTrigger
391  /// pointer to static callback function that handles the
392  /// sounding of an alarm upon detection of a fish target.
393  /// If this parameter is a null pointer, then the
394  /// <i>Fish Alarm Trigger</i> callback mechanism
395  /// will be disabled.
396  ///
397  /// @param[in] pStreamDataToFF
398  /// pointer to static callback function that passes
399  /// messages from the @b %STFishFinder API to a
400  /// connected black box via an appropriate driver
401  /// on the platform.
402  /// If this parameter is a null pointer, then the
403  /// API will be unable to communicate with a
404  /// black box fish finder.
405  ///
406  /// @retval ::FF_ERR_NO_ERROR
407  /// normal return
408  ///
409  /// @retval ::FF_ERR_CANT_CHANGE_CALLBACKS
410  /// the function was called after instantiating an
411  /// STFishFinder object
412  ///
413  /// @note This function will fail with error code
414  /// ::FF_ERR_CANT_CHANGE_CALLBACKS if it is called when
415  /// one or more STFishFinder objects exist.
416  /// This function must be called before calling
417  /// CreateFishFinder(), CreateSimulatedFishFinder(), or
418  /// CreateFishFinderForPlayback().
419  ///
420  /// @note All API callback mechanisms will be disabled if
421  /// STFishFinder is instantiated without first calling
422  /// this function.
423  ///
424  /// @see callbacks
425  ///
426  /// @ingroup init_and_control
427  ///
428  static FF_Error_t SetCallbacks (Callback_SettingChanged_t pSettingChanged,
429  Callback_DataItemReceived_t pDataItemReceived,
430  Callback_DepthAlarmStateChange_t pDepthAlarmStateChange,
431  Callback_FishAlarmTrigger_t pFishAlarmTrigger,
432  Callback_StreamDataToFF_t pStreamDataToFF);
433 
434 
435  ////////////////////////////////////////////////////////////////////////
436  /// @fn Hello
437  ///
438  /// Initiates communication with the black box fish finder after a
439  /// connection is established.
440  ///
441  /// This function should be called immediately after successfully
442  /// opening the communication channel to the black box fish finder.
443  ///
444  /// This function performs the following tasks:
445  /// - Initiates the first exchange of messages between the
446  /// STFishFinder API and the newly-connected black box
447  /// - Changes the API Status to ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT
448  ///
449  /// On return from this function, the API status remains at
450  /// ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT while the black box
451  /// uploads the initial state to the API. (This uploading process
452  /// occurs through wrapper calls to function ParseFFInputStream() as
453  /// messages are received from the black box.)
454  ///
455  /// @note After this function is called, the
456  /// @link GetApiStatus() API status @endlink
457  /// must reach the ::FF_API_STATUS_READY state, before
458  /// calling other STFishFinder class member functions.
459  ///
460  /// @retval ::FF_ERR_NO_ERROR
461  /// normal return
462  ///
463  /// @retval ::FF_ERR_API_ALREADY_INITIALIZED
464  /// if the API status prior to calling @b %Hello() was not
465  /// ::FF_API_STATUS_NOT_INITIALIZED
466  ///
467  /// @retval ::FF_ERR_BAD_DATABASE
468  /// if the API encounters an internal error
469  ///
470  /// @see GetApiStatus()
471  /// @see FF_ApiStatus_t
472  /// @see @ref how_to_connect
473  ///
474  /// @ingroup init_and_control
475  ///
476  FF_Error_t Hello ();
477 
478 
479  ////////////////////////////////////////////////////////////////////////
480  /// @fn GetApiStatus
481  ///
482  /// Returns the status of the %STFishFinder API.
483  /// This function may be used to poll the API after calling
484  /// Hello(), to determine whether the black box has
485  /// finished uploading the initial state to the API.
486  ///
487  /// @note This function can be used in conjunction with the
488  /// @ref Callback_SettingChanged_t callback function.
489  /// This callback will be called when the API status
490  /// changes from ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT
491  /// to ::FF_API_STATUS_READY, which occurs when the uploading
492  /// operation has completed.
493  ///
494  /// @par API Status Described
495  /// The ::FF_ApiStatus_t value provided by this function can have one
496  /// of the following three states:
497  /// - ::FF_API_STATUS_NOT_INITIALIZED
498  /// - ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT
499  /// - ::FF_API_STATUS_READY
500  ///
501  /// @parblock
502  /// Here is a description of the meanings of these three states
503  /// as they apply to the process of initializing the API.
504  ///
505  /// - ::FF_API_STATUS_NOT_INITIALIZED @n
506  /// After the STFishFinder() class constructor has been
507  /// called (creating a STFishFinder instance), but before the Hello()
508  /// member function has been called, the API status is
509  /// ::FF_API_STATUS_NOT_INITIALIZED. In this case,
510  /// the only STFishFinder class member functions that will
511  /// produce meaningful results are Hello() and GetApiStatus().
512  /// Calls to all other member functions when in this state will
513  /// only produce a return error code of
514  /// ::FF_ERR_API_NOT_INITIALIZED. @n @n
515  ///
516  /// - ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT @n
517  /// When Hello() is called, a special message is
518  /// transmitted from the API to the black box, and the API status
519  /// changes to ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT. Upon
520  /// return from Hello(), this is normally the API status.
521  /// When the black box has received the special message, it begins
522  /// uploading initial state information to the API. The API
523  /// receives this state information through a series of wrapper calls
524  /// to ParseFFInputStream(). While this is occurring, the API status
525  /// remains at ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT. @n @n
526  ///
527  /// - ::FF_API_STATUS_READY @n
528  /// When the process of uploading the initial state has completed,
529  /// the API status changes to ::FF_API_STATUS_READY, and the
530  /// @ref Callback_SettingChanged_t callback function
531  /// is called, with its first argument containing the value
532  /// ::FF_SETTING_TYPE_API_READY. At this time, all other member
533  /// functions become usable. It is recommended that the application
534  /// program now perform its own initialization of the API by calling
535  /// the various @ref setters functions, followed by a call to
536  /// Control() to enable transmission of data messages. @n @n
537  /// @endparblock
538  ///
539  /// @retval ::FF_API_STATUS_NOT_INITIALIZED
540  /// the application needs to call the API function Hello()
541  /// before calling other API member functions
542  ///
543  /// @retval ::FF_API_STATUS_INITIALIZING_PLEASE_WAIT
544  /// the black box is uploading initial state information
545  /// to the API
546  ///
547  /// @retval ::FF_API_STATUS_READY
548  /// the API is ready for use
549  ///
550  /// @see Hello()
551  /// @see Callback_SettingChanged_t
552  /// @see ::FF_ApiStatus_t
553  /// @see @ref how_to_connect
554  ///
555  /// @ingroup init_and_control
556  ///
557  FF_ApiStatus_t GetApiStatus () const;
558 
559 
560  ////////////////////////////////////////////////////////////////////////
561  /// @fn Control
562  ///
563  /// Provides a facility to alter system-related behavior of the
564  /// black box and API.
565  /// In particular, the Control() function is used to enable and/or
566  /// disable the transmission of black box originated data messages.
567  ///
568  /// On initial connection to a black box, transmission of data
569  /// messages (Depth, Speed, Temperature, Battery Voltage, Image data,
570  /// Fish data, and Depth Alarm messages) is disabled.
571  /// After a connection is established, and the API initialized
572  /// via a call to Hello(), the Control() function must be called
573  /// in order to establish the periodic transmission of required
574  /// data messages.
575  ///
576  /// @param[in] command
577  /// the command to be performed
578  ///
579  /// @param[in] pParam
580  /// Usage depends on the value of @p command.
581  /// If @p command is
582  /// ::FF_CONTROL_COMMAND_ENABLE_BLACK_BOX_MESSAGES,
583  /// then @p pParam must be cast to a value of type
584  /// ::FF_ControlEnableBlackBoxMsg_t.
585  /// The @p pParam value may be a logical OR of different
586  /// ::FF_ControlEnableBlackBoxMsg_t values,
587  /// in order to enable the transmission of more than
588  /// one type of message.
589  ///
590  /// @retval ::FF_ERR_NO_ERROR
591  /// normal return
592  ///
593  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
594  /// if one or both of the arguments contained an
595  /// unrecognized value
596  ///
597  /// @retval ::FF_ERR_API_NOT_INITIALIZED
598  /// if the Hello() function was not previously called,
599  /// or did not return successfully.
600  ///
601  /// @retval ::FF_ERR_BAD_DATABASE
602  /// if the API encounters an internal error
603  ///
604  /// @note Do not call this function before the
605  /// @link GetApiStatus() API status @endlink has reached
606  /// ::FF_API_STATUS_READY. See @ref how_to_connect
607  /// for details.
608  ///
609  /// @todo Add a command to the Control() method to specify
610  /// whether the API and black box should use a secondary
611  /// communication channel (e.g. UDP instead of TCP) for
612  /// transmission of Image data.
613  ///
614  /// @todo Add a command to the Control() method to enable or
615  /// disable calls to individual callbacks
616  ///
617  /// @see ::FF_ControlCommand_t
618  /// @see ::FF_ControlEnableBlackBoxMsg_t
619  ///
620  /// @ingroup init_and_control
621  ///
622  FF_Error_t Control (FF_ControlCommand_t command, const void *pParam);
623 
624 
625  ////////////////////////////////////////////////////////////////////////
626  /// @fn ParseFFInputStream
627  ///
628  /// This function parses and interprets the stream of messages from
629  /// the black box fish finder, and calls API methods to perform
630  /// actions according to the data received. This function is to be
631  /// called by a handler in the wrapper when a packet of data
632  /// received from the black box fish finder becomes available
633  /// on the input stream.
634  ///
635  /// @param[in] pInputStream
636  /// pointer to a buffer containing the received data
637  ///
638  /// @param[in] numBytes
639  /// number of characters in the buffer
640  ///
641  /// @retval ::FF_ERR_NO_ERROR
642  ///
643  /// @ingroup init_and_control
644  ///
645  FF_Error_t ParseFFInputStream (char *pInputStream, uint32_t numBytes);
646 
647 
648  ////////////////////////////////////////////////////////////////////////
649  /// @fn StartRecording
650  ///
651  /// This function enables the recording of an API session.
652  /// After this function is called, all subsequent data items received
653  /// from the connected black box will be recorded and appended to
654  /// previously recorded data in the provided Replay object.
655  ///
656  /// @param[in] pReplay
657  /// pointer to Replay object that will contain the
658  /// recorded session data.
659  ///
660  /// @retval ::FF_ERR_NO_ERROR : Recording of the session was successfully started.
661  ///
662  /// @retval ::FF_ERR_INVALID_POINTER : the @p pReplay parameter was a null pointer
663  ///
664  /// @see StopRecording
665  /// @see CreateFishFinderForPlayback
666  /// @see Replay
667  ///
668  /// @ingroup init_and_control
669  ///
670  FF_Error_t StartRecording (Replay *pReplay);
671 
672 
673  ////////////////////////////////////////////////////////////////////////
674  /// @fn StopRecording
675  ///
676  /// This function discontinues the recording of the API session
677  /// that was initiated by a call to StartRecording.
678  ///
679  /// @retval ::FF_ERR_NO_ERROR
680  ///
681  /// @see StartRecording
682  /// @see CreateFishFinderForPlayback
683  ///
684  /// @ingroup init_and_control
685  ///
686  FF_Error_t StopRecording ();
687 
688 
689  ////////////////////////////////////////////////////////////////////////
690  /// @fn TimerTick
691  ///
692  /// Provides a means by which time-dependent processes within the
693  /// %STFishFinder API can be serviced on a periodic basis.
694  ///
695  /// The TimerTick() function should be called approximately every
696  /// 100 milliseconds by a system timer process under control of
697  /// the wrapper.
698  ///
699  /// TimerTick() is used by the %STFishFinder API to perform API
700  /// housekeeping, and to initiate the generation of data messages
701  /// in simulator and playback modes.
702  ///
703  /// @returns void
704  ///
705  /// @ingroup init_and_control
706  ///
707  void TimerTick ();
708 
709 
710  ////////////////////////////////////////////////////////////////////////
711  /// @fn SilenceDepthAlarm
712  ///
713  /// Sends a message to the black box instructing it to temporarily
714  /// silence a currently active depth alarm.
715  ///
716  /// This function will transmit the message to the black box
717  /// regardless of whether the specified depth alarm is in fact
718  /// active at the time of transmission.
719  ///
720  /// The result of silencing an active depth alarm is that the black
721  /// box will transmit a message to all connected display devices
722  /// (including the one that invoked the SilenceDepthAlarm() function)
723  /// instructing them to change the state for the specified depth alarm
724  /// to ::FF_DEPTH_ALARM_STATE_SILENCED. In each display device, the
725  /// receipt of this message will trigger a call to the
726  /// designated @ref Callback_DepthAlarmStateChange_t callback function.
727  /// This callback should then turn off the audible alert within the
728  /// application. It is recommended that a visual indicator remain
729  /// onscreen to remind the user that the given alarm condition is
730  /// still present.
731  ///
732  /// @param[in] alarmType
733  /// enumeration specifying whether the alarm to be
734  /// silenced is the shallow depth alarm or the
735  /// deep depth alarm
736  ///
737  /// @param[in] durationSeconds
738  /// number of seconds for which the specified alarm
739  /// should be silenced. This parameter is regarded as a
740  /// request, not a mandate; the black box may choose to
741  /// override this value. A value of 30 seconds is
742  /// suggested as a nominal value for this parameter.
743  ///
744  /// @retval ::FF_ERR_NO_ERROR
745  ///
746  /// @see Callback_DepthAlarmStateChange_t
747  ///
748  /// @ingroup init_and_control
749  ///
750  FF_Error_t SilenceDepthAlarm (FF_DepthAlarmType_t alarmType,
751  int32_t durationSeconds);
752 
753 
754  ////////////////////////////////////////////////////////////////////////
755  /// @fn GetDepthAlarmState
756  ///
757  /// Provides the current state of both the
758  /// shallow depth alarm and the deep depth alarm.
759  ///
760  /// @param[out] pShallowAlarmState
761  /// pointer to a location where the current shallow alarm
762  /// state will be stored.
763  /// If this parameter is a null pointer, then no value
764  /// will be stored.
765  ///
766  /// @param[out] pDeepAlarmState
767  /// pointer to a location where the current deep alarm
768  /// state will be stored.
769  /// If this parameter is a null pointer, then no value
770  /// will be stored.
771  ///
772  /// @param[out] pStatus
773  /// pointer to a location that will be written with the
774  /// status of the provided depth alarm state values
775  /// (valid/invalid, simulated, or log playback).
776  /// If this parameter is a null pointer, then no value
777  /// will be stored.
778  ///
779  /// @retval ::FF_ERR_NO_ERROR
780  ///
781  /// @see Callback_DepthAlarmStateChange_t
782  /// @see SilenceDepthAlarm
783  ///
784  /// @ingroup init_and_control
785  ///
786  FF_Error_t GetDepthAlarmState (FF_DepthAlarmState_t *pShallowAlarmState,
787  FF_DepthAlarmState_t *pDeepAlarmState,
788  FF_DataStatus_t *pStatus) const;
789 
790 
791  ////////////////////////////////////////////////////////////////////////
792  //
793  // GETTERS
794  //
795  ////////////////////////////////////////////////////////////////////////
796 
797  ////////////////////////////////////////////////////////////////////////
798  /// @defgroup getters Getters
799  /// @ingroup stff_member_functions
800  ///
801  /// Functions that retrieve information such as data and settings from
802  /// the API.
803  /// These are member functions of the STFishFinder class.
804  ///
805  /// @see setters
806  /// @see init_and_control
807  /// @see callbacks
808  ////////////////////////////////////////////////////////////////////////
809 
810 
811  ////////////////////////////////////
812  // GETTERS FOR ATTRIBUTES
813  ////////////////////////////////////
814 
815  ////////////////////////////////////////////////////////////////////////
816  /// @defgroup attributes_getters Getters for Attributes
817  /// @ingroup getters
818  ///
819  /// Functions that retrieve information about unchangeable attributes
820  /// of the connected black box fish finder.
821  /// These are member functions of the STFishFinder class.
822  ///
823  /// @see settings_getters
824  /// @see master_settings_getters
825  /// @see limits_getters
826  /// @see data_getters
827  ////////////////////////////////////////////////////////////////////////
828 
829  ////////////////////////////////////////////////////////////////////////
830  /// @fn GetApiVersion
831  ///
832  /// Getter function to provide an STFF::Version object containing
833  /// version information for the present instance of
834  /// the STFishFinder API.
835  ///
836  /// @param[out] pApiVersion
837  /// Pointer to an STFF::Version object into which this
838  /// function will store the version information.
839  /// If this parameter is a null pointer, then nothing
840  /// will be stored.
841  ///
842  /// @retval ::FF_ERR_NO_ERROR
843  /// if the operation completed successfully
844  ///
845  /// @retval ::FF_ERR_BAD_DATABASE
846  /// if the API encounters an internal error
847  ///
848  /// @par Example:
849  /// @code
850  /// using namespace STFF;
851  ///
852  /// Version apiVersion;
853  /// FF_Error_t error;
854  ///
855  /// error = GetApiVersion (&apiVersion);
856  ///
857  /// if (error == FF_ERR_NO_ERROR) {
858  /// char apiVersionBuf [Version::MaxVersionStringLength];
859  /// apiVersion.GetVersionString (apiVersionBuf);
860  ///
861  /// // apiVersionBuf now contains a
862  /// // null-terminated string containing the
863  /// // STFishFinder API version.
864  /// }
865  /// @endcode
866  ///
867  /// @see STFF::Version
868  ///
869  /// @ingroup attributes_getters
870  ///
871  FF_Error_t GetApiVersion (Version *pApiVersion) const;
872 
873 
874  ////////////////////////////////////////////////////////////////////////
875  /// @fn GetCompanyName
876  ///
877  /// Getter function to provide the Company Name for the connected
878  /// black box fish finder. The Company Name string contains the name
879  /// of the brand or manufacturer of the black box hardware.
880  /// The Company Name is a read-only attribute of the black box.
881  /// There is no corresponding setter function.
882  ///
883  /// @remark The Company Name for the
884  /// <em>Pocket Marine Fishing Bug 20</em> is "Pocket Marine, LLC".
885  /// Other Company Names will be assigned to FE2 derivatives
886  /// as needed.
887  ///
888  /// @note When displaying this value in the GUI, it is suggested
889  /// to provide room on the screen to display a string
890  /// of at least 40 characters.
891  ///
892  /// @param[out] pCompanyName
893  /// Pointer to buffer into which this function will store
894  /// a null-terminated C-style string containing the
895  /// Company Name.
896  /// The number of characters written, including the
897  /// terminating '\\0', will never exceed the value of
898  /// STFF::STFishFinder::MaxAttributeStringLength.
899  /// If this parameter is a null pointer,
900  /// then nothing will be written to the buffer.
901  ///
902  /// @param[out] pLength
903  /// Pointer to location into which this function will
904  /// store the number of characters in the string.
905  /// The value stored does not account for the terminating
906  /// '\\0'.
907  /// If this parameter is a null pointer, then no value
908  /// will be stored.
909  ///
910  /// @param[out] pStatus
911  /// pointer to a location that will be written with the
912  /// status of the provided Company Name value
913  /// (valid/invalid, simulated, or log playback).
914  ///
915  /// @retval ::FF_ERR_NO_ERROR
916  /// if the operation completed successfully
917  ///
918  /// @retval ::FF_ERR_API_NOT_INITIALIZED
919  /// if the @link GetApiStatus() API status @endlink
920  /// is not ::FF_API_STATUS_READY prior to calling this
921  /// function
922  ///
923  /// @retval ::FF_ERR_BAD_DATABASE
924  /// if the API encounters an internal error
925  ///
926  /// @note To determine the length of the buffer required
927  /// to contain the string, call this function twice:
928  /// In the first call set the pCompanyName
929  /// argument to @p null and read the length from the
930  /// location provided to the pLength argument.
931  /// When allocating the buffer, be sure to add 1 to the
932  /// buffer length to account for the terminating '\\0'.
933  /// Then call this function a second time, providing the
934  /// address of the buffer to the pMfrName argument.
935  ///
936  /// @note Do not call this function before the
937  /// @link GetApiStatus() API status @endlink has reached
938  /// ::FF_API_STATUS_READY. See @ref how_to_connect
939  /// for details.
940  ///
941  /// @ingroup attributes_getters
942  ///
943  FF_Error_t GetCompanyName (char *pCompanyName,
944  uint16_t *pLength,
945  FF_DataStatus_t *pStatus) const;
946 
947 
948  ////////////////////////////////////////////////////////////////////////
949  /// @fn GetProductName
950  ///
951  /// Getter function to provide the Product Name for the connected
952  /// black box fish finder. The Product Name is a read-only
953  /// attribute of the black box. There is no corresponding setter
954  /// function.
955  ///
956  /// @remark The Product Name for the
957  /// <em>Pocket Marine Fishing Bug 20</em> is "Fishing Bug 20".
958  /// Other Product Names will be assigned to FE2 derivatives
959  /// as needed.
960  ///
961  /// @note When displaying this value in the GUI, it is suggested
962  /// to provide room on the screen to display a string
963  /// of at least 25 characters.
964  ///
965  /// @param[out] pProductName
966  /// Pointer to buffer into which this function will store
967  /// a null-terminated C-style string containing the
968  /// Product Name.
969  /// The number of characters written, including the
970  /// terminating '\\0', will never exceed the value of
971  /// STFF::STFishFinder::MaxAttributeStringLength.
972  /// If this parameter is a null pointer,
973  /// then nothing will be written to the buffer.
974  ///
975  /// @param[out] pLength
976  /// Pointer to location into which this function will
977  /// store the number of characters in the string.
978  /// The value stored does not account for the terminating
979  /// '\\0'.
980  /// If this parameter is a null pointer, then no value
981  /// will be stored.
982  ///
983  /// @param[out] pStatus
984  /// pointer to a location that will be written with the
985  /// status of the provided product name value
986  /// (valid/invalid, simulated, or log playback).
987  /// If this parameter is a null pointer, then no value
988  /// will be stored.
989  ///
990  /// @retval ::FF_ERR_NO_ERROR
991  /// if the operation completed successfully
992  ///
993  /// @retval ::FF_ERR_API_NOT_INITIALIZED
994  /// if the @link GetApiStatus() API status @endlink
995  /// is not ::FF_API_STATUS_READY prior to calling this
996  /// function
997  ///
998  /// @retval ::FF_ERR_BAD_DATABASE
999  /// if the API encounters an internal error
1000  ///
1001  /// @note To determine the length of the buffer required
1002  /// to contain the string, call this function twice:
1003  /// In the first call set the pProductName
1004  /// argument to @p null and read the length from the
1005  /// location provided to the pLength argument.
1006  /// When allocating the buffer, be sure to add 1 to the
1007  /// buffer length to account for the terminating '\\0'.
1008  /// Then call this function a second time, providing the
1009  /// address of the buffer to the pProductName argument.
1010  ///
1011  /// @note Do not call this function before the
1012  /// @link GetApiStatus() API status @endlink has reached
1013  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1014  /// for details.
1015  ///
1016  /// @see GetProductId
1017  ///
1018  /// @ingroup attributes_getters
1019  ///
1020  FF_Error_t GetProductName (char *pProductName,
1021  uint16_t *pLength,
1022  FF_DataStatus_t *pStatus) const;
1023 
1024 
1025  ////////////////////////////////////////////////////////////////////////
1026  /// @fn GetSerialNumber
1027  ///
1028  /// Getter function to provide the Serial Number of the connected
1029  /// black box fish finder. The Serial Number is a read-only
1030  /// attribute of the black box. There is no corresponding setter
1031  /// function.
1032  ///
1033  /// @note When displaying this value in the GUI, it is suggested
1034  /// to provide room on the screen to display a string
1035  /// of at least 15 characters.
1036  ///
1037  /// @param[out] pSerialNumber
1038  /// Pointer to buffer into which this function will store
1039  /// a null-terminated C-style string containing the
1040  /// Serial Number.
1041  /// The number of characters written, including the
1042  /// terminating '\\0', will never exceed the value of
1043  /// STFF::STFishFinder::MaxAttributeStringLength.
1044  /// If this parameter is a null pointer,
1045  /// then nothing will be written to the buffer.
1046  ///
1047  /// @param[out] pLength
1048  /// Pointer to location into which this function will
1049  /// store the number of characters in the string.
1050  /// The value stored does not account for the terminating
1051  /// '\\0'.
1052  /// If this parameter is a null pointer, then no value
1053  /// will be stored.
1054  ///
1055  /// @param[out] pStatus
1056  /// pointer to a location that will be written with the
1057  /// status of the provided serial number value
1058  /// (valid/invalid, simulated, or log playback).
1059  /// If this parameter is a null pointer, then no value
1060  /// will be stored.
1061  ///
1062  /// @retval ::FF_ERR_NO_ERROR
1063  /// if the operation completed successfully
1064  ///
1065  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1066  /// if the @link GetApiStatus() API status @endlink
1067  /// is not ::FF_API_STATUS_READY prior to calling this
1068  /// function
1069  ///
1070  /// @retval ::FF_ERR_BAD_DATABASE
1071  /// if the API encounters an internal error
1072  ///
1073  /// @note To determine the length of the buffer required
1074  /// to contain the string, call this function twice:
1075  /// In the first call set the pSerialNumber
1076  /// argument to @p null and read the length from the
1077  /// location provided to the pLength argument.
1078  /// When allocating the buffer, be sure to add 1 to the
1079  /// buffer length to account for the terminating '\\0'.
1080  /// Then call this function a second time, providing the
1081  /// address of the buffer to the pSerialNumber argument.
1082  ///
1083  /// @note Do not call this function before the
1084  /// @link GetApiStatus() API status @endlink has reached
1085  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1086  /// for details.
1087  ///
1088  /// @ingroup attributes_getters
1089  ///
1090  FF_Error_t GetSerialNumber (char *pSerialNumber,
1091  uint16_t *pLength,
1092  FF_DataStatus_t *pStatus) const;
1093 
1094 
1095  ////////////////////////////////////////////////////////////////////////
1096  /// @fn GetHWVersion
1097  ///
1098  /// Getter function to provide the Hardware Version string for the
1099  /// connected black box fish finder. The Hardware Version is a
1100  /// read-only attribute of the black box. There is no corresponding
1101  /// setter function.
1102  ///
1103  /// @note When displaying this value in the GUI, it is suggested
1104  /// to provide room on the screen to display a string
1105  /// of at least 10 characters.
1106  ///
1107  /// @param[out] pHWVersion
1108  /// Pointer to buffer into which this function will store
1109  /// a null-terminated C-style string containing the
1110  /// Hardware Version.
1111  /// The number of characters written, including the
1112  /// terminating '\\0', will never exceed the value of
1113  /// STFF::STFishFinder::MaxAttributeStringLength.
1114  /// If this parameter is a null pointer,
1115  /// then nothing will be written to the buffer.
1116  ///
1117  /// @param[out] pLength
1118  /// Pointer to location into which this function will
1119  /// store the number of characters in the string.
1120  /// The value stored does not account for the terminating
1121  /// '\\0'.
1122  /// If this parameter is a null pointer, then no value
1123  /// will be stored.
1124  ///
1125  /// @param[out] pStatus
1126  /// pointer to a location that will be written with the
1127  /// status of the provided hardware version value
1128  /// (valid/invalid, simulated, or log playback).
1129  /// If this parameter is a null pointer, then no value
1130  /// will be stored.
1131  ///
1132  /// @retval ::FF_ERR_NO_ERROR
1133  /// if the operation completed successfully
1134  ///
1135  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1136  /// if the @link GetApiStatus() API status @endlink
1137  /// is not ::FF_API_STATUS_READY prior to calling this
1138  /// function
1139  ///
1140  /// @retval ::FF_ERR_BAD_DATABASE
1141  /// if the API encounters an internal error
1142  ///
1143  /// @note To determine the length of the buffer required
1144  /// to contain the string, call this function twice:
1145  /// In the first call set the pHWVersion
1146  /// argument to @p null and read the length from the
1147  /// location provided to the pLength argument.
1148  /// When allocating the buffer, be sure to add 1 to the
1149  /// buffer length to account for the terminating '\\0'.
1150  /// Then call this function a second time, providing the
1151  /// address of the buffer to the pHWVersion argument.
1152  ///
1153  /// @note Do not call this function before the
1154  /// @link GetApiStatus() API status @endlink has reached
1155  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1156  /// for details.
1157  ///
1158  /// @ingroup attributes_getters
1159  ///
1160  FF_Error_t GetHWVersion (char *pHWVersion,
1161  uint16_t *pLength,
1162  FF_DataStatus_t *pStatus) const;
1163 
1164 
1165  ////////////////////////////////////////////////////////////////////////
1166  /// @fn GetFWVersion
1167  ///
1168  /// Getter function to provide the Firmware Version string for the
1169  /// connected black box fish finder. The Firmware Version is a
1170  /// read-only attribute of the black box. There is no corresponding
1171  /// setter function.
1172  ///
1173  /// @note When displaying this value in the GUI, it is suggested
1174  /// to provide room on the screen to display a string
1175  /// of at least 10 characters.
1176  ///
1177  /// @param[out] pFWVersion
1178  /// Pointer to buffer into which this function will store
1179  /// a null-terminated C-style string containing the
1180  /// Firmware Version.
1181  /// The number of characters written, including the
1182  /// terminating '\\0', will never exceed the value of
1183  /// STFF::STFishFinder::MaxAttributeStringLength.
1184  /// If this parameter is a null pointer,
1185  /// then nothing will be written to the buffer.
1186  ///
1187  /// @param[out] pLength
1188  /// Pointer to location into which this function will
1189  /// store the number of characters in the string.
1190  /// The value stored does not account for the terminating
1191  /// '\\0'.
1192  /// If this parameter is a null pointer, then no value
1193  /// will be stored.
1194  ///
1195  /// @param[out] pStatus
1196  /// pointer to a location that will be written with the
1197  /// status of the provided firmware version value
1198  /// (valid/invalid, simulated, or log playback).
1199  /// If this parameter is a null pointer, then no value
1200  /// will be stored.
1201  ///
1202  /// @retval ::FF_ERR_NO_ERROR
1203  /// if the operation completed successfully
1204  ///
1205  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1206  /// if the @link GetApiStatus() API status @endlink
1207  /// is not ::FF_API_STATUS_READY prior to calling this
1208  /// function
1209  ///
1210  /// @retval ::FF_ERR_BAD_DATABASE
1211  /// if the API encounters an internal error
1212  ///
1213  /// @note To determine the length of the buffer required
1214  /// to contain the string, call this function twice:
1215  /// In the first call set the pFWVersion
1216  /// argument to @p null and read the length from the
1217  /// location provided to the pLength argument.
1218  /// When allocating the buffer, be sure to add 1 to the
1219  /// buffer length to account for the terminating '\\0'.
1220  /// Then call this function a second time, providing the
1221  /// address of the buffer to the pFWVersion argument.
1222  ///
1223  /// @note Do not call this function before the
1224  /// @link GetApiStatus() API status @endlink has reached
1225  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1226  /// for details.
1227  ///
1228  /// @todo Redefine the GetFWVersion() function to return a
1229  /// STFF::Version object instead of a string
1230  ///
1231  /// @ingroup attributes_getters
1232  ///
1233  FF_Error_t GetFWVersion (char *pFWVersion,
1234  uint16_t *pLength,
1235  FF_DataStatus_t *pStatus) const;
1236 
1237 
1238  ////////////////////////////////////////////////////////////////////////
1239  /// @fn GetBootloaderVersion
1240  ///
1241  /// Getter function to provide the Bootloader Version string for the
1242  /// connected black box fish finder. The Bootloader Version is a
1243  /// read-only attribute of the black box. There is no corresponding
1244  /// setter function.
1245  ///
1246  /// @note When displaying this value in the GUI, it is suggested
1247  /// to provide room on the screen to display a string
1248  /// of at least 10 characters.
1249  ///
1250  /// @param[out] pBootloaderVersion
1251  /// Pointer to buffer into which this function will store
1252  /// a null-terminated C-style string containing the
1253  /// Bootloader Version.
1254  /// The number of characters written, including the
1255  /// terminating '\\0', will never exceed the value of
1256  /// STFF::STFishFinder::MaxAttributeStringLength.
1257  /// If this parameter is a null pointer,
1258  /// then nothing will be written to the buffer.
1259  ///
1260  /// @param[out] pLength
1261  /// Pointer to location into which this function will
1262  /// store the number of characters in the string.
1263  /// The value stored does not account for the terminating
1264  /// '\\0'.
1265  /// If this parameter is a null pointer, then no value
1266  /// will be stored.
1267  ///
1268  /// @param[out] pStatus
1269  /// pointer to a location that will be written with the
1270  /// status of the provided bootloader version value
1271  /// (valid/invalid, simulated, or log playback).
1272  /// If this parameter is a null pointer, then no value
1273  /// will be stored.
1274  ///
1275  /// @retval ::FF_ERR_NO_ERROR
1276  /// if the operation completed successfully
1277  ///
1278  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1279  /// if the @link GetApiStatus() API status @endlink
1280  /// is not ::FF_API_STATUS_READY prior to calling this
1281  /// function
1282  ///
1283  /// @retval ::FF_ERR_BAD_DATABASE
1284  /// if the API encounters an internal error
1285  ///
1286  /// @note To determine the length of the buffer required
1287  /// to contain the string, call this function twice:
1288  /// In the first call set the pBootloaderVersion
1289  /// argument to @p null and read the length from the
1290  /// location provided to the pLength argument.
1291  /// When allocating the buffer, be sure to add 1 to the
1292  /// buffer length to account for the terminating '\\0'.
1293  /// Then call this function a second time, providing the
1294  /// address of the buffer to the pBootloaderVersion
1295  /// argument.
1296  ///
1297  /// @note Do not call this function before the
1298  /// @link GetApiStatus() API status @endlink has reached
1299  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1300  /// for details.
1301  ///
1302  /// @todo Redefine the GetBootloaderVersion() function to return a
1303  /// STFF::Version object instead of a string
1304  ///
1305  /// @ingroup attributes_getters
1306  ///
1307  FF_Error_t GetBootloaderVersion (char *pBootloaderVersion,
1308  uint16_t *pLength,
1309  FF_DataStatus_t *pStatus) const;
1310 
1311 
1312  ////////////////////////////////////////////////////////////////////////
1313  /// @cond
1314  /// ^^^^^ Do not include documentation for this function
1315  ///
1316  /// @fn GetCopyrightMessage
1317  ///
1318  /// Getter function to provide the Copyright Message for the
1319  /// connected black box. The Copyright Message is a read-only
1320  /// attribute. There is no corresponding setter
1321  /// function.
1322  ///
1323  ///
1324  /// @param[out] pCopyrightMessage
1325  /// Pointer to buffer into which this function will store
1326  /// a null-terminated C-style string containing the
1327  /// Copyright Message.
1328  /// The number of characters written, including the
1329  /// terminating '\\0', will never exceed the value of
1330  /// STFF::STFishFinder::MaxAttributeStringLength.
1331  /// If this parameter is a null pointer,
1332  /// then nothing will be written to the buffer.
1333  ///
1334  /// @param[out] pLength Pointer to location into which this function
1335  /// will store the number of characters in the
1336  /// string. The value stored does not account
1337  /// for the terminating '\\0'.
1338  /// If this parameter is a null pointer, then
1339  /// no value will be stored.
1340  ///
1341  /// @retval FF_ERR_NO_ERROR if the operation completed
1342  /// successfully
1343  /// @retval FF_ERR_API_NOT_INITIALIZED if the Hello() function
1344  /// was not previously
1345  /// called, or did not return
1346  /// successfully.
1347  /// @retval FF_ERR_BAD_DATABASE if the API has an internal
1348  /// error
1349  ///
1350  /// @ingroup attributes_getters
1351  ///
1352  FF_Error_t GetCopyrightMessage (char *pCopyrightMessage,
1353  uint16_t *pLength) const;
1354  /// @endcond
1355 
1356 
1357  ////////////////////////////////////////////////////////////////////////
1358  /// @fn GetMaxPossibleDepth
1359  ///
1360  /// Getter function to provide the maximum possible depth at the
1361  /// specified frequency for the connected black box fish finder.
1362  /// The maximum possible depth is a read-only attribute of the black
1363  /// box. There is no corresponding setter function.
1364  ///
1365  /// @note This value represents the deepest depth to which the
1366  /// sounder might "look" when pinging at the specified
1367  /// frequency. It does not represent the capability
1368  /// of the hardware to actually achieve the detection
1369  /// of a bottom echo at that depth.
1370  ///
1371  /// @param[in] frequency
1372  /// The frequency selection for which the maximum
1373  /// possible depth value is requested.
1374  ///
1375  /// @param[in] units
1376  /// The depth units in which the maximum possible
1377  /// depth value will be reported.
1378  ///
1379  /// @param[out] pMaxDepth
1380  /// Pointer to location into which this function will
1381  /// store the "maximum possible depth" value.
1382  /// If this parameter is a null pointer, then no value
1383  /// will be stored.
1384  ///
1385  /// @param[out] pStatus
1386  /// pointer to a location that will be written with the
1387  /// status of the provided maximum possible depth value
1388  /// (valid/invalid, simulated, or log playback).
1389  /// If this parameter is a null pointer, then no value
1390  /// will be stored.
1391  ///
1392  /// @retval ::FF_ERR_NO_ERROR
1393  /// if the operation completed successfully
1394  ///
1395  /// @retval ::FF_ERR_INVALID_FREQUENCY
1396  /// if the provided @p frequency parameter has an invalid
1397  /// value (see ::FF_Frequency_t)
1398  ///
1399  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
1400  /// if the provided @p units parameter is outside the
1401  /// range of allowable values.
1402  ///
1403  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1404  /// if the @link GetApiStatus() API status @endlink
1405  /// is not ::FF_API_STATUS_READY prior to calling this
1406  /// function
1407  ///
1408  /// @retval ::FF_ERR_BAD_DATABASE
1409  /// if the API encounters an internal error
1410  ///
1411  /// @note Do not call this function before the
1412  /// @link GetApiStatus() API status @endlink has reached
1413  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1414  /// for details.
1415  ///
1416  /// @todo The GetMaxPossibleDepth() function should probably be
1417  /// deprecated.
1418  ///
1419  /// @ingroup attributes_getters
1420  ///
1421  FF_Error_t GetMaxPossibleDepth (FF_Frequency_t frequency,
1422  FF_DepthUnits_t units,
1423  uint32_t *pMaxDepth,
1424  FF_DataStatus_t *pStatus) const;
1425 
1426 
1427  ////////////////////////////////////////////////////////////////////////
1428  /// @cond
1429  /// ^^^^^ Do not include documentation for these functions
1430  ///
1431  /// Bit Depth getter member function.
1432  ///
1433  FF_Error_t GetBitDepth (FF_BitDepth_t *pBitDepth, FF_SettingStatus_t *pStatus) const;
1434  /// getters for diagnostic data (read-only)
1435  FF_Error_t GetPostResult (FF_PostResult_t *pPostResult) const;
1436  FF_Error_t GetConfigJumperValue (uint8_t *pConfigJumperValue) const;
1437  /// @endcond
1438 
1439 
1440  ////////////////////////////////////
1441  // GETTERS FOR LIMITS
1442  ////////////////////////////////////
1443 
1444  ////////////////////////////////////////////////////////////////////////
1445  /// @defgroup limits_getters Getters for Limits
1446  /// @ingroup getters
1447  ///
1448  /// Functions that retrieve information from the black box fishfinder
1449  /// regarding the allowable range of input values for certain setter
1450  /// functions.
1451  /// These are member functions of the STFishFinder class.
1452  ///
1453  /// These functions are provided to enable the application program to
1454  /// verify that the arguments it provides to a setter function
1455  /// are valid values for that function.
1456  ///
1457  /// @see setters
1458  /// @see settings_getters
1459  /// @see master_settings_getters
1460  /// @see attributes_getters
1461  /// @see data_getters
1462  ////////////////////////////////////////////////////////////////////////
1463 
1464  ////////////////////////////////////////////////////////////////////////
1465  /// @fn GetInputSamplesLimits
1466  ///
1467  /// Getter function to provide limits for the parameter to the
1468  /// SetNumInputSamples() member function.
1469  ///
1470  /// This function provides the minimum and maximum limits
1471  /// that define the range of allowable values that may be used
1472  /// in the @p numInputSamples parameter when calling the
1473  /// SetNumInputSamples() member function.
1474  ///
1475  /// The limits provided apply to both 200 kHz and 50 kHz frequencies.
1476  ///
1477  /// The provided limits are read-only, and are defined by the
1478  /// black box. They do not change during the course of a session.
1479  /// There is no corresponding setter function for changing the limits.
1480  ///
1481  /// @param[out] pMinInputSamples
1482  /// Pointer to location into which this function will
1483  /// store the lower limit.
1484  /// If this parameter is a null pointer, then no value
1485  /// will be stored.
1486  ///
1487  /// @param[out] pMaxInputSamples
1488  /// Pointer to location into which this function will
1489  /// will store the upper limit.
1490  /// If this parameter is a null pointer, then no value
1491  /// will be stored.
1492  ///
1493  /// @retval ::FF_ERR_NO_ERROR
1494  /// if the operation completed successfully
1495  ///
1496  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1497  /// if the @link GetApiStatus() API status @endlink
1498  /// is not ::FF_API_STATUS_READY prior to calling this
1499  /// function
1500  ///
1501  /// @retval ::FF_ERR_BAD_DATABASE
1502  /// if the API encounters an internal error
1503  ///
1504  /// @note Do not call this function before the
1505  /// @link GetApiStatus() API status @endlink has reached
1506  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1507  /// for details.
1508  ///
1509  /// @see SetNumInputSamples()
1510  ///
1511  /// @ingroup limits_getters
1512  ///
1513  FF_Error_t GetInputSamplesLimits (uint16_t *pMinInputSamples,
1514  uint16_t *pMaxInputSamples) const;
1515 
1516 
1517  ////////////////////////////////////////////////////////////////////////
1518  /// @fn GetSpeedPulsesPerNauticalMileLimits
1519  ///
1520  /// Getter function to provide limits for the parameter to the
1521  /// SetSpeedPulsesPerNauticalMile() member function.
1522  ///
1523  /// This function provides the minimum and maximum limits
1524  /// that define the range of allowable values that may be used
1525  /// in the @p speedPPNM parameter when calling the
1526  /// SetSpeedPulsesPerNauticalMile() member function.
1527  ///
1528  /// The provided limits are read-only, and are defined by the
1529  /// black box. They do not change during the course of a session.
1530  /// There is no corresponding setter function for changing the limits.
1531  ///
1532  /// @param[out] pMinSpeedPPNM
1533  /// Pointer to location into which this function will
1534  /// store the lower limit.
1535  /// If this parameter is a null pointer, then no value
1536  /// will be stored.
1537  ///
1538  /// @param[out] pMaxSpeedPPNM
1539  /// Pointer to location into which this function will
1540  /// will store the upper limit.
1541  /// If this parameter is a null pointer, then no value
1542  /// will be stored.
1543  ///
1544  /// @retval ::FF_ERR_NO_ERROR
1545  /// if the operation completed successfully
1546  ///
1547  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1548  /// if the @link GetApiStatus() API status @endlink
1549  /// is not ::FF_API_STATUS_READY prior to calling this
1550  /// function
1551  ///
1552  /// @retval ::FF_ERR_BAD_DATABASE
1553  /// if the API encounters an internal error
1554  ///
1555  /// @note Do not call this function before the
1556  /// @link GetApiStatus() API status @endlink has reached
1557  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1558  /// for details.
1559  ///
1560  /// @see SetSpeedPulsesPerNauticalMile()
1561  ///
1562  /// @ingroup limits_getters
1563  ///
1564  FF_Error_t GetSpeedPulsesPerNauticalMileLimits (uint32_t *pMinSpeedPPNM,
1565  uint32_t *pMaxSpeedPPNM) const;
1566 
1567 
1568  ////////////////////////////////////////////////////////////////////////
1569  /// @fn GetTemperatureOffsetLimits
1570  ///
1571  /// Getter function to provide limits for the parameter to the
1572  /// SetTemperatureOffset() member function.
1573  ///
1574  /// This function provides the minimum and maximum limits
1575  /// that define the range of allowable values that may be used
1576  /// in the @p temperatureOffset parameter when calling the
1577  /// SetTemperatureOffset() member function.
1578  ///
1579  /// The provided limits are read-only, and are defined by the
1580  /// black box. They do not change during the course of a session.
1581  /// There is no corresponding setter function for changing the limits.
1582  ///
1583  /// @param[in] units
1584  /// The requested temperature units in which the
1585  /// @p pMinTempOffset and @p pMaxTempOffset values
1586  /// will be provided.
1587  /// The values will be converted by this function to
1588  /// the units specified in this parameter.
1589  ///
1590  /// @param[out] pMinTempOffset
1591  /// Pointer to location into which this function will
1592  /// store the lower limit. The value provided will
1593  /// be in hundredths of the unit specified in the
1594  /// @p units parameter. For example, if the lower
1595  /// limit is -10 degrees C, and the provided @p units
1596  /// parameter is ::FF_TEMPERATURE_UNITS_CELSIUS,
1597  /// then the value stored in *pMinTempOffset will be
1598  /// -1000.
1599  /// If this parameter is a null pointer, then no value
1600  /// will be stored.
1601  ///
1602  /// @param[out] pMaxTempOffset
1603  /// Pointer to location into which this function will
1604  /// store the upper limit. The value provided will
1605  /// be in hundredths of the unit specified in the
1606  /// @p units parameter. For example, if the upper
1607  /// limit is +10 degrees C, and the provided @p units
1608  /// parameter is ::FF_TEMPERATURE_UNITS_CELSIUS,
1609  /// then value stored in *pMaxTempOffset will be
1610  /// 1000.
1611  /// If this parameter is a null pointer, then no value
1612  /// will be stored.
1613  ///
1614  /// @retval ::FF_ERR_NO_ERROR
1615  /// if the operation completed successfully
1616  ///
1617  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1618  /// if the @link GetApiStatus() API status @endlink
1619  /// is not ::FF_API_STATUS_READY prior to calling this
1620  /// function
1621  ///
1622  /// @retval ::FF_ERR_BAD_DATABASE
1623  /// if the API encounters an internal error
1624  ///
1625  /// @note Do not call this function before the
1626  /// @link GetApiStatus() API status @endlink has reached
1627  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1628  /// for details.
1629  ///
1630  /// @see SetTemperatureOffset()
1631  ///
1632  /// @ingroup limits_getters
1633  ///
1634  FF_Error_t GetTemperatureOffsetLimits (FF_TemperatureUnits_t units,
1635  int16_t *pMinTempOffset,
1636  int16_t *pMaxTempOffset) const;
1637 
1638 
1639  ////////////////////////////////////////////////////////////////////////
1640  /// @fn GetRangeLimits
1641  ///
1642  /// Getter function to provide limits for the parameter to the
1643  /// SetRange() member function.
1644  ///
1645  /// This function provides the minimum and maximum limits
1646  /// that define the range of allowable values that may be used
1647  /// in the @link FF_RangeSetting_t.rangeDeep rangeDeep @endlink
1648  /// field of the @p pRangeSetting parameter when calling the SetRange()
1649  /// member function.
1650  ///
1651  /// The limits provided apply to both 200 kHz and 50 kHz frequencies.
1652  ///
1653  /// The provided limits are read-only, and are defined by the
1654  /// black box. They do not change during the course of a session.
1655  /// There is no corresponding setter function for changing the limits.
1656  ///
1657  /// @note
1658  /// -# This function does not pertain directly to the
1659  /// @link FF_RangeSetting_t::rangeShallow rangeShallow
1660  /// @endlink field of the @p pRangeSetting parameter.
1661  /// The limits for the
1662  /// @link FF_RangeSetting_t.rangeShallow rangeShallow
1663  /// @endlink field depend on the current value of the
1664  /// @link FF_RangeSetting_t.rangeDeep rangeDeep
1665  /// @endlink field as follows: @n
1666  /// 0 <= @e rangeShallow <= <em>(rangeDeep - pMinRangeDeep)</em>
1667  /// @n @n
1668  /// -# Separate values are provided for each of the
1669  /// different depth units settings that reflect natural
1670  /// grid divisions for the given units.
1671  /// For example, the minimum range limit in fathoms might
1672  /// be 1.0 fathom, and the minimum range limit in meters
1673  /// might be 2.0 meters, even though these do not refer
1674  /// to the same depth. The units provided when calling
1675  /// this function should therefore be the same as the
1676  /// units that will be used when calling SetRange().
1677  ///
1678  /// @param[in] units
1679  /// The depth units for which and in which the
1680  /// @p pMinRangeDeep and @p pMaxRangeDeep values
1681  /// will be provided.
1682  ///
1683  /// @param[out] pMinRangeDeep
1684  /// Pointer to location into which this function will
1685  /// store the minimum allowable value for the
1686  /// @link FF_RangeSetting_t::rangeDeep rangeDeep
1687  /// @endlink member of the range setting for the
1688  /// specified depth units.
1689  /// The value provided will be in hundredths of the unit
1690  /// specified by the @p units parameter.
1691  /// For example, if the provided @p units parameter is
1692  /// ::FF_DEPTH_UNITS_METERS, and the limit is 2 meters,
1693  /// then the value stored in *pMinRangeDeep will be 200.
1694  /// If this parameter is a null pointer, then no value
1695  /// will be stored.
1696  ///
1697  /// @param[out] pMaxRangeDeep
1698  /// Pointer to location into which this function will
1699  /// store the maximum allowable value for the
1700  /// @link FF_RangeSetting_t::rangeDeep rangeDeep
1701  /// @endlink member of the range setting for the
1702  /// specified depth units.
1703  /// The value provided will be in hundredths of the unit
1704  /// specified by the @p units parameter.
1705  /// For example, if the provided @p units parameter is
1706  /// ::FF_DEPTH_UNITS_METERS, and the limit is 300 meters,
1707  /// then the value stored in *pMaxRangeDeep will be 30,000.
1708  /// If this parameter is a null pointer, then no value
1709  /// will be stored.
1710  ///
1711  /// @retval ::FF_ERR_NO_ERROR
1712  /// if the operation completed successfully
1713  ///
1714  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1715  /// if the @link GetApiStatus() API status @endlink
1716  /// is not ::FF_API_STATUS_READY prior to calling this
1717  /// function
1718  ///
1719  /// @retval ::FF_ERR_BAD_DATABASE
1720  /// if the API encounters an internal error
1721  ///
1722  /// @note Do not call this function before the
1723  /// @link GetApiStatus() API status @endlink has reached
1724  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1725  /// for details.
1726  ///
1727  /// @see SetRange()
1728  ///
1729  /// @ingroup limits_getters
1730  ///
1731  FF_Error_t GetRangeLimits (FF_DepthUnits_t units,
1732  uint32_t *pMinRangeDeep,
1733  uint32_t *pMaxRangeDeep) const;
1734 
1735 
1736  ////////////////////////////////////////////////////////////////////////
1737  /// @fn GetGainLimits
1738  ///
1739  /// Getter function to provide limits for the parameter to the
1740  /// SetGain() member function.
1741  ///
1742  /// This function provides the minimum and maximum limits
1743  /// that define the range of allowable values that may be used
1744  /// in the @p gainSetting parameter when calling the SetGain()
1745  /// member function.
1746  ///
1747  /// The limits provided apply to both 200 kHz and 50 kHz frequencies.
1748  ///
1749  /// The provided limits are read-only, and are defined by the
1750  /// black box. They do not change during the course of a session.
1751  /// There is no corresponding setter function for changing the limits.
1752  ///
1753  /// @param[out] pMinGain
1754  /// Pointer to location into which this function will
1755  /// store the minimum allowable value for the
1756  /// gain setting.
1757  /// If this parameter is a null pointer, then no value
1758  /// will be stored.
1759  ///
1760  /// @param[out] pMaxGain
1761  /// Pointer to location into which this function will
1762  /// store the maximum allowable value for the
1763  /// gain setting.
1764  /// If this parameter is a null pointer, then no value
1765  /// will be stored.
1766  ///
1767  /// @retval ::FF_ERR_NO_ERROR
1768  /// if the operation completed successfully
1769  ///
1770  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1771  /// if the @link GetApiStatus() API status @endlink
1772  /// is not ::FF_API_STATUS_READY prior to calling this
1773  /// function
1774  ///
1775  /// @retval ::FF_ERR_BAD_DATABASE
1776  /// if the API encounters an internal error
1777  ///
1778  /// @note Do not call this function before the
1779  /// @link GetApiStatus() API status @endlink has reached
1780  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1781  /// for details.
1782  ///
1783  /// @see SetGain()
1784  ///
1785  /// @ingroup limits_getters
1786  ///
1787  FF_Error_t GetGainLimits (uint16_t *pMinGain,
1788  uint16_t *pMaxGain) const;
1789 
1790 
1791  ////////////////////////////////////////////////////////////////////////
1792  /// @fn GetGainOffsetLimits
1793  ///
1794  /// Getter function to provide limits for the parameter to the
1795  /// SetGainOffset() member function.
1796  ///
1797  /// This function provides the minimum and maximum limits
1798  /// that define the range of allowable values that may be used
1799  /// in the @p gainOffset parameter when calling the SetGainOffset()
1800  /// member function.
1801  ///
1802  /// The limits provided apply to both 200 kHz and 50 kHz frequencies.
1803  ///
1804  /// The provided limits are read-only, and are defined by the
1805  /// black box. They do not change during the course of a session.
1806  /// There is no corresponding setter function for changing the limits.
1807  ///
1808  /// @param[out] pMinOffset
1809  /// Pointer to location into which this function will
1810  /// store the minimum allowable value for the
1811  /// gain offset setting.
1812  /// If this parameter is a null pointer, then no value
1813  /// will be stored.
1814  ///
1815  /// @param[out] pMaxOffset
1816  /// Pointer to location into which this function will
1817  /// store the maximum allowable value for the
1818  /// gain offset setting.
1819  /// If this parameter is a null pointer, then no value
1820  /// will be stored.
1821  ///
1822  /// @retval ::FF_ERR_NO_ERROR
1823  /// if the operation completed successfully
1824  ///
1825  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1826  /// if the @link GetApiStatus() API status @endlink
1827  /// is not ::FF_API_STATUS_READY prior to calling this
1828  /// function
1829  ///
1830  /// @retval ::FF_ERR_BAD_DATABASE
1831  /// if the API encounters an internal error
1832  ///
1833  /// @note Do not call this function before the
1834  /// @link GetApiStatus() API status @endlink has reached
1835  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1836  /// for details.
1837  ///
1838  /// @see SetGainOffset()
1839  ///
1840  /// @ingroup limits_getters
1841  ///
1842  FF_Error_t GetGainOffsetLimits (int16_t *pMinOffset,
1843  int16_t *pMaxOffset) const;
1844 
1845 
1846  ////////////////////////////////////////////////////////////////////////
1847  /// @fn GetGainColorOffsetsLimits
1848  ///
1849  /// Getter function to provide:
1850  /// - the number of required elements in the <em>Gain Color Offsets</em>
1851  /// array provided in the @p pGainColorOffsets parameter to the
1852  /// GetGainColorOffsets() and SetGainColorOffsets() member functions
1853  /// - minimum and maximum limits that define the range of allowable
1854  /// values that may be used in the array when calling the
1855  /// SetGainColorOffsets() member function.
1856  ///
1857  /// The limits provided apply to both 200 kHz and 50 kHz frequencies.
1858  ///
1859  /// The provided limits are read-only, and are defined by the
1860  /// black box. They do not change during the course of a session.
1861  /// There is no corresponding setter function for changing the limits.
1862  ///
1863  /// @param[out] pNumOffsets
1864  /// Pointer to location into which this function will
1865  /// store a value representing the required number of
1866  /// elements in the @p pGainColorOffsets array
1867  /// passed to the GetGainColorOffsets() and
1868  /// SetGainColorOffsets() member functions.
1869  /// If the pNumOffsets parameter is a null pointer,
1870  /// then no value will be stored.
1871  ///
1872  /// @param[out] pMinLargestOffset
1873  /// Pointer to location into which this function will
1874  /// store the minimum allowable value for the last
1875  /// element in the @p pGainColorOffsets array passed to
1876  /// the SetGainColorOffsets() member function.
1877  /// If this parameter is a null pointer, then no value
1878  /// will be stored.
1879  ///
1880  /// @param[out] pMaxLargestOffset
1881  /// Pointer to location into which this function will
1882  /// store the maximum allowable value for the last
1883  /// element in the @p pGainColorOffsets array passed to
1884  /// the SetGainColorOffsets() member function.
1885  /// If this parameter is a null pointer, then no value
1886  /// will be stored.
1887  ///
1888  /// @retval ::FF_ERR_NO_ERROR
1889  /// if the operation completed successfully
1890  ///
1891  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1892  /// if the @link GetApiStatus() API status @endlink
1893  /// is not ::FF_API_STATUS_READY prior to calling this
1894  /// function
1895  ///
1896  /// @retval ::FF_ERR_BAD_DATABASE
1897  /// if the API encounters an internal error
1898  ///
1899  /// @note Do not call this function before the
1900  /// @link GetApiStatus() API status @endlink has reached
1901  /// ::FF_API_STATUS_READY. See @ref how_to_connect
1902  /// for details.
1903  ///
1904  /// @see GetGainColorOffsets()
1905  /// @see SetGainColorOffsets()
1906  ///
1907  /// @ingroup limits_getters
1908  ///
1909  FF_Error_t GetGainColorOffsetsLimits (uint16_t *pNumOffsets,
1910  uint16_t *pMinLargestOffset,
1911  uint16_t *pMaxLargestOffset) const;
1912 
1913 
1914  ////////////////////////////////////////////////////////////////////////
1915  /// @cond
1916  /// ^^^^^ Do not include documentation for these functions
1917  ///
1918  FF_Error_t GetFstcLimits (uint16_t *pMinFsts, uint16_t *pMaxFsts, uint16_t *pMinFstd, uint16_t *pMaxFstd) const;
1919  FF_Error_t GetDstcLimits (uint16_t *pMinDsts, uint16_t *pMaxDsts, uint16_t *pMinDstd, uint16_t *pMaxDstd) const;
1920  /// @endcond
1921 
1922 
1923  ////////////////////////////////////
1924  // GETTERS FOR DATA
1925  ////////////////////////////////////
1926 
1927  ////////////////////////////////////////////////////////////////////////////
1928  /// @defgroup data_getters Getters for Data
1929  /// @ingroup getters
1930  ///
1931  /// Functions that retrieve depth, speed, temperature, and
1932  /// battery voltage data from the connected black box fish finder.
1933  /// These are member functions of the STFishFinder class.
1934  ///
1935  /// @note The function to retrieve image data is not a member
1936  /// of the STFishFinder class, but is in fact a member
1937  /// of the STFishFinder::ImageColumn class.
1938  /// See STFishFinder::ImageColumn::GetImageData().
1939  ///
1940  /// @see settings_getters
1941  /// @see master_settings_getters
1942  /// @see attributes_getters
1943  /// @see limits_getters
1944  ////////////////////////////////////////////////////////////////////////////
1945 
1946 
1947  ////////////////////////////////////////////////////////////////////////
1948  /// @fn GetTemperature
1949  ///
1950  /// Getter function to provide the current water temperature data.
1951  /// The temperature data reported by this function will have already
1952  /// been adjusted by the
1953  /// @link SetTemperatureOffset() Temperature Offset @endlink
1954  /// master setting.
1955  ///
1956  /// @param[in] units
1957  /// the requested temperature units
1958  /// (Celsius or Fahrenheit) in which the data value
1959  /// will be provided
1960  ///
1961  /// @param[out] pTemperatureData
1962  /// pointer to a location where the requested
1963  /// Temperature data will be stored.
1964  /// The @p *pTemperatureData value is a struct of type
1965  /// ::FF_TemperatureData_t.
1966  /// The struct contains a
1967  /// @link FF_TemperatureData_t::units units @endlink
1968  /// member that will mirror the units parameter in the
1969  /// call to this function, a
1970  /// @link FF_TemperatureData_t::temperature temperature
1971  /// @endlink member containing the current water temperature
1972  /// in hundredths of the specified units, and a
1973  /// @link FF_TemperatureData_t::FF_DataStatus_t status @endlink
1974  /// value that indicates whether the provided temperature
1975  /// value is valid, invalid, simulated, or a log playback.
1976  /// The application should not
1977  /// display an invalid value, or should clearly indicate
1978  /// that the displayed value is invalid.
1979  /// If @p pTemperatureData is a null pointer, then no value
1980  /// will be stored.
1981  ///
1982  /// @retval ::FF_ERR_NO_ERROR
1983  /// if the operation completed successfully
1984  ///
1985  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
1986  /// if the value provided in the @p units parameter
1987  /// is outside the range of allowable values.
1988  ///
1989  /// @retval ::FF_ERR_API_NOT_INITIALIZED
1990  /// if the @link GetApiStatus() API status @endlink
1991  /// is not ::FF_API_STATUS_READY prior to calling this
1992  /// function
1993  ///
1994  /// @retval ::FF_ERR_BAD_DATABASE
1995  /// if the API encounters an internal error
1996  ///
1997  /// @remark Typically, this function would be called as a result
1998  /// of the @ref Callback_DataItemReceived_t callback
1999  /// function being called with a ::FF_DataType_t
2000  /// parameter of ::FF_DATA_TYPE_TEMPERATURE.
2001  ///
2002  /// @note Do not call this function before the
2003  /// @link GetApiStatus() API status @endlink has reached
2004  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2005  /// for details.
2006  ///
2007  /// @ingroup data_getters
2008  ///
2009  FF_Error_t GetTemperature (FF_TemperatureUnits_t units,
2010  FF_TemperatureData_t *pTemperatureData) const;
2011 
2012 
2013  ////////////////////////////////////////////////////////////////////////
2014  /// @fn GetSpeed
2015  ///
2016  /// Getter function to provide the current Speed Through Water data.
2017  ///
2018  /// @param[in] units
2019  /// the requested speed units
2020  /// (knots, mph, or kph) in which the data value
2021  /// will be provided
2022  ///
2023  /// @param[out] pSpeedData
2024  /// pointer to a location where the requested
2025  /// Speed data will be stored.
2026  /// The @p *pSpeedData value is a struct of type
2027  /// ::FF_SpeedData_t.
2028  /// The struct contains a
2029  /// @link FF_SpeedData_t::units units @endlink
2030  /// member that will mirror the units parameter in the
2031  /// call to this function, a
2032  /// @link FF_SpeedData_t::speed speed
2033  /// @endlink member containing the current speed
2034  /// in hundredths of the specified units, and a
2035  /// @link FF_SpeedData_t::FF_DataStatus_t status @endlink
2036  /// value that indicates whether the provided speed
2037  /// value is valid, invalid, simulated, or a log playback.
2038  /// The application should not
2039  /// display an invalid value, or should clearly indicate
2040  /// that the displayed value is invalid.
2041  /// If @p pSpeedData is a null pointer, then no value
2042  /// will be stored.
2043  ///
2044  /// @retval ::FF_ERR_NO_ERROR
2045  /// if the operation completed successfully
2046  ///
2047  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
2048  /// if the value provided in the @p units parameter
2049  /// is outside the range of allowable values.
2050  ///
2051  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2052  /// if the @link GetApiStatus() API status @endlink
2053  /// is not ::FF_API_STATUS_READY prior to calling this
2054  /// function
2055  ///
2056  /// @retval ::FF_ERR_BAD_DATABASE
2057  /// if the API encounters an internal error
2058  ///
2059  /// @remark Typically, this function would be called as a result
2060  /// of the @ref Callback_DataItemReceived_t callback
2061  /// function being called with a ::FF_DataType_t
2062  /// parameter of ::FF_DATA_TYPE_SPEED.
2063  ///
2064  /// @note Do not call this function before the
2065  /// @link GetApiStatus() API status @endlink has reached
2066  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2067  /// for details.
2068  ///
2069  /// @ingroup data_getters
2070  ///
2071  FF_Error_t GetSpeed (FF_SpeedUnits_t units,
2072  FF_SpeedData_t *pSpeedData) const;
2073 
2074 
2075  ////////////////////////////////////////////////////////////////////////
2076  /// @fn GetDepth
2077  ///
2078  /// Getter function to provide the current Depth data.
2079  ///
2080  /// @param[in] units
2081  /// the requested depth units
2082  /// (feet, meters, or fathoms) in which the data value
2083  /// will be provided
2084  ///
2085  /// @param[out] pDepthData
2086  /// pointer to a location where the requested
2087  /// Depth data will be stored.
2088  /// The @p *pDepthData value is a struct of type
2089  /// ::FF_DepthData_t.
2090  /// The struct contains a
2091  /// @link FF_DepthData_t::units units @endlink
2092  /// member that will mirror the units parameter in the
2093  /// call to this function, a
2094  /// @link FF_DepthData_t::depth depth
2095  /// @endlink member containing the current depth
2096  /// in hundredths of the specified units, and a
2097  /// @link FF_DepthData_t::FF_DataStatus_t status @endlink
2098  /// value that indicates whether the provided depth
2099  /// value is valid, invalid, simulated, or a log playback.
2100  /// The application should not
2101  /// display an invalid value, or should clearly indicate
2102  /// that the displayed value is invalid.
2103  /// If @p pDepthData is a null pointer, then no value
2104  /// will be stored.
2105  ///
2106  /// @retval ::FF_ERR_NO_ERROR
2107  /// if the operation completed successfully
2108  ///
2109  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
2110  /// if the value provided in the @p units parameter
2111  /// is outside the range of allowable values.
2112  ///
2113  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2114  /// if the @link GetApiStatus() API status @endlink
2115  /// is not ::FF_API_STATUS_READY prior to calling this
2116  /// function
2117  ///
2118  /// @retval ::FF_ERR_BAD_DATABASE
2119  /// if the API encounters an internal error
2120  ///
2121  /// @remark Typically, this function would be called as a result
2122  /// of the @ref Callback_DataItemReceived_t callback
2123  /// function being called with a ::FF_DataType_t
2124  /// parameter of ::FF_DATA_TYPE_DEPTH.
2125  ///
2126  /// @note Do not call this function before the
2127  /// @link GetApiStatus() API status @endlink has reached
2128  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2129  /// for details.
2130  ///
2131  /// @ingroup data_getters
2132  ///
2133  FF_Error_t GetDepth (FF_DepthUnits_t units, FF_DepthData_t *pDepthData) const;
2134 
2135 
2136  ////////////////////////////////////////////////////////////////////////
2137  /// @fn GetBatteryVoltage
2138  ///
2139  /// Getter function to provide the current Battery Voltage data.
2140  ///
2141  /// @param[out] pBatteryVoltageData
2142  /// pointer to a location where the requested
2143  /// Battery Voltage data will be stored.
2144  /// The @p *pBatteryVoltageData value is a struct of type
2145  /// ::FF_BatteryVoltageData_t.
2146  /// The struct contains a
2147  /// @link FF_BatteryVoltageData_t::voltage voltage
2148  /// @endlink member containing the current voltage of
2149  /// the battery powering the black box,
2150  /// in hundredths of a volt, and a
2151  /// @link FF_BatteryVoltageData_t::FF_DataStatus_t status @endlink
2152  /// value that indicates whether the provided battery voltage
2153  /// value is valid, invalid, simulated, or a log playback.
2154  /// The application should not
2155  /// display an invalid value, or should clearly indicate
2156  /// that the displayed value is invalid.
2157  /// If @p pBatteryVoltageData is a null pointer, then no value
2158  /// will be stored.
2159  ///
2160  /// @retval ::FF_ERR_NO_ERROR
2161  /// if the operation completed successfully
2162  ///
2163  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2164  /// if the @link GetApiStatus() API status @endlink
2165  /// is not ::FF_API_STATUS_READY prior to calling this
2166  /// function
2167  ///
2168  /// @retval ::FF_ERR_BAD_DATABASE
2169  /// if the API encounters an internal error
2170  ///
2171  /// @remark Typically, this function would be called as a result
2172  /// of the @ref Callback_DataItemReceived_t callback
2173  /// function being called with a ::FF_DataType_t
2174  /// parameter of ::FF_DATA_TYPE_BATTERY_VOLTAGE.
2175  ///
2176  /// @note Do not call this function before the
2177  /// @link GetApiStatus() API status @endlink has reached
2178  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2179  /// for details.
2180  ///
2181  /// @ingroup data_getters
2182  ///
2183  FF_Error_t GetBatteryVoltage (FF_BatteryVoltageData_t *pBatteryVoltageData) const;
2184 
2185 
2186  ////////////////////////////////////
2187  // GETTERS FOR SETTINGS
2188  ////////////////////////////////////
2189 
2190  ////////////////////////////////////////////////////////////////////////
2191  /// @defgroup settings_getters Getters for Local Settings
2192  /// @ingroup getters
2193  ///
2194  /// Functions that retrieve information about changeable settings
2195  /// that are local to the present application.
2196  /// These settings do not affect other displays and applications
2197  /// that are simultaneously connected to the same black box.
2198  /// These are member functions of the STFishFinder class.
2199  ///
2200  /// Each of the functions in this category has a corresponding "setter"
2201  /// function that provides the ability to change the setting. See the
2202  /// <b>"See also"</b> section in each function description for a link to the
2203  /// corresponding setter for that function.
2204  ///
2205  /// @see settings_setters
2206  /// @see master_settings_getters
2207  /// @see attributes_getters
2208  /// @see limits_getters
2209  /// @see data_getters
2210  ////////////////////////////////////////////////////////////////////////
2211 
2212  ////////////////////////////////////////////////////////////////////////
2213  /// @fn GetNumInputSamples
2214  ///
2215  /// Getter function to provide the current setting for the
2216  /// number of samples that will be provided by the black box
2217  /// when transferring each column of image data to the API.
2218  ///
2219  /// A single Number of Input Samples setting applies to both the
2220  /// 200 kHz and 50 kHz frequency contexts.
2221  ///
2222  /// @param[out] pNumInputSamples
2223  /// Pointer to location into which this function will
2224  /// store the current Number of Input Samples setting.
2225  /// If this parameter is a null pointer, then no value
2226  /// will be stored.
2227  ///
2228  /// @param[out] pStatus
2229  /// Pointer to location into which this function will
2230  /// store the status (invalid, pending, or valid)
2231  /// of the provided Number of Input Samples setting.
2232  /// If this parameter is a null pointer, then no value
2233  /// will be stored.
2234  ///
2235  /// @retval ::FF_ERR_NO_ERROR
2236  /// if the operation completed successfully
2237  ///
2238  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2239  /// if the @link GetApiStatus() API status @endlink
2240  /// is not ::FF_API_STATUS_READY prior to calling this
2241  /// function
2242  ///
2243  /// @retval ::FF_ERR_BAD_DATABASE
2244  /// if the API encounters an internal error
2245  ///
2246  /// @note Do not call this function before the
2247  /// @link GetApiStatus() API status @endlink has reached
2248  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2249  /// for details.
2250  ///
2251  /// @see SetNumInputSamples()
2252  ///
2253  /// @ingroup settings_getters
2254  ///
2255  FF_Error_t GetNumInputSamples (uint16_t *pNumInputSamples,
2256  FF_SettingStatus_t *pStatus) const;
2257 
2258 
2259  ////////////////////////////////////////////////////////////////////////
2260  /// @fn GetFrequencyMode
2261  ///
2262  /// Getter function to provide the current Frequency Mode setting.
2263  /// The Frequency Mode specifies whether the black box should
2264  /// provide image data for 200 kHz only, 50 kHz only, or
2265  /// alternating 200 kHz / 50 kHz.
2266  ///
2267  /// @param[out] pFrequencyMode
2268  /// Pointer to location into which this function will
2269  /// store the current Frequency Mode setting.
2270  /// If this parameter is a null pointer, then no value
2271  /// will be stored.
2272  ///
2273  /// @param[out] pStatus
2274  /// Pointer to location into which this function will
2275  /// store the status (invalid, pending, or valid)
2276  /// of the provided Frequency Mode setting.
2277  /// If this parameter is a null pointer, then no value
2278  /// will be stored.
2279  ///
2280  /// @retval ::FF_ERR_NO_ERROR
2281  /// if the operation completed successfully
2282  ///
2283  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2284  /// if the @link GetApiStatus() API status @endlink
2285  /// is not ::FF_API_STATUS_READY prior to calling this
2286  /// function
2287  ///
2288  /// @retval ::FF_ERR_BAD_DATABASE
2289  /// if the API encounters an internal error
2290  ///
2291  /// @note Do not call this function before the
2292  /// @link GetApiStatus() API status @endlink has reached
2293  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2294  /// for details.
2295  ///
2296  /// @see SetFrequencyMode()
2297  ///
2298  /// @ingroup settings_getters
2299  ///
2300  FF_Error_t GetFrequencyMode (FF_FrequencyMode_t *pFrequencyMode,
2301  FF_SettingStatus_t *pStatus) const;
2302 
2303 
2304  ////////////////////////////////////////////////////////////////////////
2305  /// @fn GetAutoGainSetting
2306  ///
2307  /// Getter function to provide the current Auto Gain setting.
2308  /// The Auto Gain setting is either ::FF_AUTO_GAIN_SETTING_MANUAL
2309  /// or ::FF_AUTO_GAIN_SETTING_AUTO.
2310  ///
2311  /// A single Auto Gain setting applies to both the
2312  /// 200 kHz and 50 kHz frequency contexts.
2313  ///
2314  /// @param[out] pAutoGainSetting
2315  /// Pointer to location into which this function will
2316  /// store the current Auto Gain setting.
2317  /// If this parameter is a null pointer, then no value
2318  /// will be stored.
2319  ///
2320  /// @param[out] pStatus
2321  /// Pointer to location into which this function will
2322  /// store the status (invalid, pending, or valid)
2323  /// of the provided Auto Gain setting.
2324  /// If this parameter is a null pointer, then no value
2325  /// will be stored.
2326  ///
2327  /// @retval ::FF_ERR_NO_ERROR
2328  /// if the operation completed successfully
2329  ///
2330  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2331  /// if the @link GetApiStatus() API status @endlink
2332  /// is not ::FF_API_STATUS_READY prior to calling this
2333  /// function
2334  ///
2335  /// @retval ::FF_ERR_BAD_DATABASE
2336  /// if the API encounters an internal error
2337  ///
2338  /// @note Do not call this function before the
2339  /// @link GetApiStatus() API status @endlink has reached
2340  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2341  /// for details.
2342  ///
2343  /// @see SetAutoGainSetting()
2344  ///
2345  /// @ingroup settings_getters
2346  ///
2347  FF_Error_t GetAutoGainSetting (FF_AutoGainSetting_t *pAutoGainSetting,
2348  FF_SettingStatus_t *pStatus) const;
2349 
2350 
2351  ////////////////////////////////////////////////////////////////////////
2352  /// @cond
2353  /// ^^^^^ Do not include documentation for this function
2354  ///
2355  FF_Error_t GetWaterFilterSetting (FF_Frequency_t frequency, FF_WaterFilterSetting_t *pWaterFilterSetting, FF_SettingStatus_t *pStatus) const;
2356  /// @endcond
2357 
2358 
2359  ////////////////////////////////////////////////////////////////////////
2360  /// @fn GetAutoRangeSetting
2361  ///
2362  /// Getter function to provide the current Auto Range setting.
2363  /// The Auto Range setting has one of the following values:
2364  /// - ::FF_AUTO_RANGE_SETTING_MANUAL
2365  /// - ::FF_AUTO_RANGE_SETTING_AUTO_RANGE
2366  /// - ::FF_AUTO_RANGE_SETTING_AUTO_SHIFT
2367  ///
2368  /// A single Auto Range setting applies to both the
2369  /// 200 kHz and 50 kHz frequency contexts.
2370  ///
2371  /// @param[out] pAutoRange
2372  /// Pointer to location into which this function will
2373  /// store the current Auto Range setting.
2374  /// If this parameter is a null pointer, then no value
2375  /// will be stored.
2376  ///
2377  /// @param[out] pUnits
2378  /// Pointer to location into which this function will
2379  /// store the current depth units used for the Range
2380  /// setting.
2381  /// If this parameter is a null pointer, then no value
2382  /// will be stored.
2383  ///
2384  /// @param[out] pStatus
2385  /// Pointer to location into which this function will
2386  /// store the status (invalid, pending, or valid)
2387  /// of the provided Auto Range setting.
2388  /// If this parameter is a null pointer, then no value
2389  /// will be stored.
2390  ///
2391  /// @retval ::FF_ERR_NO_ERROR
2392  /// if the operation completed successfully
2393  ///
2394  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2395  /// if the @link GetApiStatus() API status @endlink
2396  /// is not ::FF_API_STATUS_READY prior to calling this
2397  /// function
2398  ///
2399  /// @retval ::FF_ERR_BAD_DATABASE
2400  /// if the API encounters an internal error
2401  ///
2402  /// @note Do not call this function before the
2403  /// @link GetApiStatus() API status @endlink has reached
2404  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2405  /// for details.
2406  ///
2407  /// @see SetAutoRangeSetting()
2408  ///
2409  /// @ingroup settings_getters
2410  ///
2411  FF_Error_t GetAutoRangeSetting (FF_AutoRangeSetting_t *pAutoRange,
2412  FF_DepthUnits_t *pUnits,
2413  FF_SettingStatus_t *pStatus) const;
2414 
2415 
2416  ////////////////////////////////////////////////////////////////////////
2417  /// @fn GetRange
2418  ///
2419  /// Getter function to provide the current Range setting.
2420  /// The provided Range setting is an aggregate of type
2421  /// ::FF_RangeSetting_t, containing a shallow depth, a
2422  /// deep depth, and a depth units specifier.
2423  ///
2424  /// A single Range setting applies to both the
2425  /// 200 kHz and 50 kHz frequency contexts.
2426  ///
2427  /// @param[out] pRangeSetting
2428  /// Pointer to location into which this function will
2429  /// store the current Range setting.
2430  /// If this parameter is a null pointer, then no value
2431  /// will be stored.
2432  ///
2433  /// @param[out] pStatus
2434  /// Pointer to location into which this function will
2435  /// store the status (invalid, pending, or valid)
2436  /// of the provided Range setting.
2437  /// If this parameter is a null pointer, then no value
2438  /// will be stored.
2439  ///
2440  /// @retval ::FF_ERR_NO_ERROR
2441  /// if the operation completed successfully
2442  ///
2443  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2444  /// if the @link GetApiStatus() API status @endlink
2445  /// is not ::FF_API_STATUS_READY prior to calling this
2446  /// function
2447  ///
2448  /// @retval ::FF_ERR_BAD_DATABASE
2449  /// if the API encounters an internal error
2450  ///
2451  /// @note Do not call this function before the
2452  /// @link GetApiStatus() API status @endlink has reached
2453  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2454  /// for details.
2455  ///
2456  /// @see SetRange()
2457  ///
2458  /// @ingroup settings_getters
2459  ///
2460  FF_Error_t GetRange (FF_RangeSetting_t *pRangeSetting,
2461  FF_SettingStatus_t *pStatus) const;
2462 
2463 
2464  ////////////////////////////////////////////////////////////////////////
2465  /// @fn GetGain
2466  ///
2467  /// Getter function to provide the current Gain setting.
2468  ///
2469  /// @param[in] frequency
2470  /// The frequency context for which the Gain setting is
2471  /// requested.
2472  ///
2473  /// @param[out] pGainSetting
2474  /// Pointer to location into which this function will
2475  /// store the current Gain setting.
2476  /// If this parameter is a null pointer, then no value
2477  /// will be stored.
2478  ///
2479  /// @param[out] pStatus
2480  /// Pointer to location into which this function will
2481  /// store the status (invalid, pending, or valid)
2482  /// of the provided Gain setting.
2483  /// If this parameter is a null pointer, then no value
2484  /// will be stored.
2485  ///
2486  /// @retval ::FF_ERR_NO_ERROR
2487  /// if the operation completed successfully
2488  ///
2489  /// @retval ::FF_ERR_INVALID_FREQUENCY
2490  /// if the provided @p frequency parameter has an invalid
2491  /// value (see ::FF_Frequency_t)
2492  ///
2493  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2494  /// if the @link GetApiStatus() API status @endlink
2495  /// is not ::FF_API_STATUS_READY prior to calling this
2496  /// function
2497  ///
2498  /// @retval ::FF_ERR_BAD_DATABASE
2499  /// if the API encounters an internal error
2500  ///
2501  /// @note Do not call this function before the
2502  /// @link GetApiStatus() API status @endlink has reached
2503  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2504  /// for details.
2505  ///
2506  /// @see SetGain()
2507  ///
2508  /// @ingroup settings_getters
2509  ///
2510  FF_Error_t GetGain (FF_Frequency_t frequency,
2511  uint16_t *pGainSetting,
2512  FF_SettingStatus_t *pStatus) const;
2513 
2514 
2515  ////////////////////////////////////////////////////////////////////////
2516  /// @fn GetGainOffset
2517  ///
2518  /// Getter function to provide the current Gain Offset setting.
2519  ///
2520  /// @param[in] frequency
2521  /// The frequency context for which the Gain Offset
2522  /// setting is requested.
2523  ///
2524  /// @param[out] pGainOffset
2525  /// Pointer to location into which this function will
2526  /// store the current Gain Offset setting.
2527  /// If this parameter is a null pointer, then no value
2528  /// will be stored.
2529  ///
2530  /// @param[out] pStatus
2531  /// Pointer to location into which this function will
2532  /// store the status (invalid, pending, or valid)
2533  /// of the provided Gain Offset setting.
2534  /// If this parameter is a null pointer, then no value
2535  /// will be stored.
2536  ///
2537  /// @retval ::FF_ERR_NO_ERROR
2538  /// if the operation completed successfully
2539  ///
2540  /// @retval ::FF_ERR_INVALID_FREQUENCY
2541  /// if the provided @p frequency parameter has an invalid
2542  /// value (see ::FF_Frequency_t)
2543  ///
2544  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2545  /// if the @link GetApiStatus() API status @endlink
2546  /// is not ::FF_API_STATUS_READY prior to calling this
2547  /// function
2548  ///
2549  /// @retval ::FF_ERR_BAD_DATABASE
2550  /// if the API encounters an internal error
2551  ///
2552  /// @note Do not call this function before the
2553  /// @link GetApiStatus() API status @endlink has reached
2554  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2555  /// for details.
2556  ///
2557  /// @see SetGainOffset()
2558  ///
2559  /// @ingroup settings_getters
2560  ///
2561  FF_Error_t GetGainOffset (FF_Frequency_t frequency,
2562  int16_t *pGainOffset,
2563  FF_SettingStatus_t *pStatus) const;
2564 
2565 
2566  ////////////////////////////////////////////////////////////////////////
2567  /// @fn GetGainColorOffsets
2568  ///
2569  /// Getter function to provide the number of colors used when
2570  /// generating the STFF::ImageColumn data, and the table of
2571  /// gain offset values used for separating the received sonar
2572  /// signal into its colors.
2573  ///
2574  /// @param[in] frequency
2575  /// the frequency context for which the Gain Color Offsets
2576  /// data is requested.
2577  ///
2578  /// @param[in] pNumColors
2579  /// pointer to location into which this function will
2580  /// store the number of colors used.
2581  /// If this parameter is a null pointer, then no value
2582  /// will be stored.
2583  ///
2584  /// @param[in] pGainColorOffsets
2585  /// pointer to location into which this function will
2586  /// store an array of Gain Color Offset values.
2587  /// The number of values stored in the array
2588  /// will be (@p *pNumColors - 2).
2589  /// If this parameter is a null pointer, then no
2590  /// array values will be stored.
2591  ///
2592  /// @param[out] pStatus
2593  /// Pointer to location into which this function will
2594  /// store the status (invalid, pending, or valid)
2595  /// of the provided Gain Color Offsets data.
2596  /// If this parameter is a null pointer, then no value
2597  /// will be stored.
2598  ///
2599  /// @retval ::FF_ERR_NO_ERROR
2600  /// if the operation completed successfully
2601  ///
2602  /// @retval ::FF_ERR_INVALID_FREQUENCY
2603  /// if the provided @p frequency parameter has an invalid
2604  /// value (see ::FF_Frequency_t)
2605  ///
2606  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2607  /// if the @link GetApiStatus() API status @endlink
2608  /// is not ::FF_API_STATUS_READY prior to calling this
2609  /// function
2610  ///
2611  /// @retval ::FF_ERR_BAD_DATABASE
2612  /// if the API encounters an internal error
2613  ///
2614  /// @note Do not call this function before the
2615  /// @link GetApiStatus() API status @endlink has reached
2616  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2617  /// for details.
2618  ///
2619  /// @remark It is recommended that this function be called twice:
2620  /// On the first call, set the @p pGainColorOffsets parameter
2621  /// to @p null, and read the @p pNumColors value.
2622  /// This will provide the size of the array to allocate.
2623  /// After allocating the memory for the array,
2624  /// call this function a second time to read the array
2625  /// into the allocated memory.
2626  ///
2627  /// @remark See the description of the SetGainColorOffsets()
2628  /// function for an explanation of the meaning of the
2629  /// @p pGainColorOffsets array.
2630  ///
2631  /// @see SetGainColorOffsets()
2632  ///
2633  /// @ingroup settings_getters
2634  ///
2635  FF_Error_t GetGainColorOffsets (FF_Frequency_t frequency,
2636  uint16_t *pNumColors,
2637  uint16_t *pGainColorOffsets,
2638  FF_SettingStatus_t *pStatus) const;
2639 
2640 
2641  ////////////////////////////////////////////////////////////////////////
2642  /// @cond
2643  /// ^^^^^ Do not include documentation for this function
2644  ///
2645  FF_Error_t GetFstc (FF_Frequency_t frequency, FF_FstcSetting_t *pFstcSetting, FF_SettingStatus_t *pStatus) const;
2646  /// @endcond
2647 
2648 
2649  ////////////////////////////////////////////////////////////////////////
2650  /// @fn GetFishIdSetting
2651  ///
2652  /// Getter function to provide the current Fish ID setting.
2653  /// The provided Fish ID setting is an aggregate of type
2654  /// ::FF_FishIdSetting_t.
2655  ///
2656  /// @param[in] frequency
2657  /// The frequency context for which the Fish ID
2658  /// setting is requested.
2659  ///
2660  /// @param[out] pFishIdSetting
2661  /// Pointer to location into which this function will
2662  /// store the current Fish ID setting.
2663  /// If this parameter is a null pointer, then no value
2664  /// will be stored.
2665  ///
2666  /// @param[out] pStatus
2667  /// Pointer to location into which this function will
2668  /// store the status (invalid, pending, or valid)
2669  /// of the provided Fish ID setting.
2670  /// If this parameter is a null pointer, then no value
2671  /// will be stored.
2672  ///
2673  /// @retval ::FF_ERR_NO_ERROR
2674  /// if the operation completed successfully
2675  ///
2676  /// @retval ::FF_ERR_INVALID_FREQUENCY
2677  /// if the provided @p frequency parameter has an invalid
2678  /// value (see ::FF_Frequency_t)
2679  ///
2680  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2681  /// if the @link GetApiStatus() API status @endlink
2682  /// is not ::FF_API_STATUS_READY prior to calling this
2683  /// function
2684  ///
2685  /// @retval ::FF_ERR_BAD_DATABASE
2686  /// if the API encounters an internal error
2687  ///
2688  /// @note Do not call this function before the
2689  /// @link GetApiStatus() API status @endlink has reached
2690  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2691  /// for details.
2692  ///
2693  /// @see SetFishIdSetting()
2694  ///
2695  /// @ingroup settings_getters
2696  ///
2697  FF_Error_t GetFishIdSetting (FF_Frequency_t frequency,
2698  FF_FishIdSetting_t *pFishIdSetting,
2699  FF_SettingStatus_t *pStatus) const;
2700 
2701 
2702  ////////////////////////////////////////////////////////////////////////
2703  /// @cond
2704  /// ^^^^^ Do not include documentation for this function
2705  ///
2706  /// @fn GetFishAlarmSetting
2707  ///
2708  /// Getter function to provide the current Fish Alarm setting.
2709  ///
2710  /// @param[in] frequency
2711  /// The frequency context for which the Fish Alarm
2712  /// setting is requested.
2713  ///
2714  /// @param[out] pFishAlarmSetting
2715  /// Pointer to location into which this function will
2716  /// store the current Fish Alarm setting.
2717  /// If this parameter is a null pointer, then no value
2718  /// will be stored.
2719  ///
2720  /// @param[out] pStatus
2721  /// Pointer to location into which this function will
2722  /// store the status (invalid, pending, or valid)
2723  /// of the provided Fish Alarm setting.
2724  /// If this parameter is a null pointer, then no value
2725  /// will be stored.
2726  ///
2727  /// @retval ::FF_ERR_NO_ERROR
2728  /// if the operation completed successfully
2729  ///
2730  /// @retval ::FF_ERR_INVALID_FREQUENCY
2731  /// if the provided @p frequency parameter has an invalid
2732  /// value (see ::FF_Frequency_t)
2733  ///
2734  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2735  /// if the @link GetApiStatus() API status @endlink
2736  /// is not ::FF_API_STATUS_READY prior to calling this
2737  /// function
2738  ///
2739  /// @retval ::FF_ERR_BAD_DATABASE
2740  /// if the API encounters an internal error
2741  ///
2742  /// @note Do not call this function before the
2743  /// @link GetApiStatus() API status @endlink has reached
2744  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2745  /// for details.
2746  ///
2747  /// @see SetFishAlarmSetting()
2748  /// @see @ref Callback_FishAlarmTrigger_t
2749  ///
2750  /// @ingroup settings_getters
2751  ///
2752  // FF_Error_t GetFishAlarmSetting (FF_Frequency_t frequency, FF_FishAlarmSetting_t *pFishAlarmSetting, FF_SettingStatus_t *pStatus) const;
2753  FF_Error_t GetFishAlarmSetting (); // to be deleted
2754  /// @endcond
2755 
2756 
2757  ////////////////////////////////////
2758  // GETTERS FOR MASTER SETTINGS
2759  ////////////////////////////////////
2760 
2761  ////////////////////////////////////////////////////////////////////////
2762  /// @defgroup master_settings_getters Getters for Master Settings
2763  /// @ingroup getters
2764  ///
2765  /// Functions that retrieve information about Master Settings that
2766  /// affect all display devices connected to the present black box
2767  /// fish finder.
2768  /// Master Settings are stored in nonvolatile memory within the
2769  /// black box. They are changeable, and globally affect all displays
2770  /// and applications that are simultaneously connected to the same
2771  /// black box.
2772  /// These are member functions of the STFishFinder class.
2773  ///
2774  /// @see master_settings_setters
2775  /// @see settings_getters
2776  /// @see attributes_getters
2777  /// @see limits_getters
2778  /// @see data_getters
2779  ////////////////////////////////////////////////////////////////////////
2780 
2781  ////////////////////////////////////////////////////////////////////////
2782  /// @fn GetTemperatureOffset
2783  ///
2784  /// Getter function to provide the current Temperature Offset
2785  /// master setting.
2786  ///
2787  /// @param[in] units
2788  /// The requested temperature units in which the
2789  /// @p pTemperatureOffset will be provided.
2790  ///
2791  /// @param[out] pTemperatureOffset
2792  /// Pointer to location into which this function will
2793  /// store the current Temperature Offset master setting.
2794  /// If this parameter is a null pointer, then no value
2795  /// will be stored.
2796  ///
2797  /// @param[out] pStatus
2798  /// Pointer to location into which this function will
2799  /// store the status (invalid, pending, or valid)
2800  /// of the provided Temperature Offset master setting.
2801  /// If this parameter is a null pointer, then no value
2802  /// will be stored.
2803  ///
2804  /// @retval ::FF_ERR_NO_ERROR
2805  /// if the operation completed successfully
2806  ///
2807  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2808  /// if the @link GetApiStatus() API status @endlink
2809  /// is not ::FF_API_STATUS_READY prior to calling this
2810  /// function
2811  ///
2812  /// @retval ::FF_ERR_BAD_DATABASE
2813  /// if the API encounters an internal error
2814  ///
2815  /// @note Do not call this function before the
2816  /// @link GetApiStatus() API status @endlink has reached
2817  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2818  /// for details.
2819  ///
2820  /// @see SetTemperatureOffset()
2821  ///
2822  /// @ingroup master_settings_getters
2823  ///
2824  FF_Error_t GetTemperatureOffset (FF_TemperatureUnits_t units,
2825  int16_t *pTemperatureOffset,
2826  FF_SettingStatus_t *pStatus) const;
2827 
2828 
2829  ////////////////////////////////////////////////////////////////////////
2830  /// @fn GetSpeedPulsesPerNauticalMile
2831  ///
2832  /// Getter function to provide the current Speed PPNM
2833  /// master setting.
2834  ///
2835  /// @param[out] pSpeedPPNM
2836  /// Pointer to location into which this function will
2837  /// store the current Speed PPNM master setting.
2838  /// If this parameter is a null pointer, then no value
2839  /// will be stored.
2840  ///
2841  /// @param[out] pStatus
2842  /// Pointer to location into which this function will
2843  /// store the status (invalid, pending, or valid)
2844  /// of the provided PPNM master setting.
2845  /// If this parameter is a null pointer, then no value
2846  /// will be stored.
2847  ///
2848  /// @retval ::FF_ERR_NO_ERROR
2849  /// if the operation completed successfully
2850  ///
2851  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2852  /// if the @link GetApiStatus() API status @endlink
2853  /// is not ::FF_API_STATUS_READY prior to calling this
2854  /// function
2855  ///
2856  /// @retval ::FF_ERR_BAD_DATABASE
2857  /// if the API encounters an internal error
2858  ///
2859  /// @note Do not call this function before the
2860  /// @link GetApiStatus() API status @endlink has reached
2861  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2862  /// for details.
2863  ///
2864  /// @see SetSpeedPulsesPerNauticalMile()
2865  ///
2866  /// @ingroup master_settings_getters
2867  ///
2868  FF_Error_t GetSpeedPulsesPerNauticalMile (uint32_t *pSpeedPPNM,
2869  FF_SettingStatus_t *pStatus) const;
2870 
2871 
2872  ////////////////////////////////////////////////////////////////////////
2873  /// @cond
2874  /// ^^^^^ Do not include documentation for this function
2875  ///
2876  FF_Error_t GetWaterType (FF_WaterType_t *pWaterType, FF_SettingStatus_t *pStatus) const;
2877  FF_Error_t GetDstc (FF_Frequency_t frequency, FF_DstcSetting_t *pDstcSetting, FF_SettingStatus_t *pStatus) const;
2878  /// @endcond
2879 
2880 
2881  ////////////////////////////////////////////////////////////////////////
2882  /// @fn GetDepthAlarmSettings
2883  ///
2884  /// Getter function to provide the current Depth Alarm
2885  /// master settings.
2886  ///
2887  /// @param[out] pUnits
2888  /// Pointer to location into which this function will
2889  /// store the depth units in which the Depth Alarms
2890  /// were originally specified.
2891  /// If this parameter is a null pointer, then no value
2892  /// will be stored.
2893  ///
2894  /// @param[out] pShallowAlarm
2895  /// Pointer to location into which this function will
2896  /// store the current Shallow Depth Alarm master setting.
2897  /// The value provided will be in hundredths of the unit
2898  /// reported in the @p *pUnits value.
2899  /// For example, if the reported @p *pUnits value is
2900  /// ::FF_DEPTH_UNITS_METERS, and the reported
2901  /// *pShallowAlarm value is 300, then this represents
2902  /// a Shallow Depth Alarm setting of 3.0 meters.
2903  /// If the stored value is 0, this indicates that the
2904  /// Shallow Depth Alarm is disabled.
2905  /// If this parameter is a null pointer, then no value
2906  /// will be stored.
2907  ///
2908  /// @param[out] pDeepAlarm
2909  /// Pointer to location into which this function will
2910  /// store the current Deep Depth Alarm master setting.
2911  /// The value provided will be in hundredths of the unit
2912  /// reported in the @p *pUnits value.
2913  /// (See the example above in the description for the
2914  /// @p pShallowAlarm parameter.)
2915  /// If the stored value is 0, this indicates that the
2916  /// Deep Depth Alarm is disabled.
2917  /// If this parameter is a null pointer, then no value
2918  /// will be stored.
2919  ///
2920  /// @param[out] pStatus
2921  /// Pointer to location into which this function will
2922  /// store the status (invalid, pending, or valid)
2923  /// of the provided Depth Alarm master settings.
2924  /// If this parameter is a null pointer, then no value
2925  /// will be stored.
2926  ///
2927  /// @retval ::FF_ERR_NO_ERROR
2928  /// if the operation completed successfully
2929  ///
2930  /// @retval ::FF_ERR_API_NOT_INITIALIZED
2931  /// if the @link GetApiStatus() API status @endlink
2932  /// is not ::FF_API_STATUS_READY prior to calling this
2933  /// function
2934  ///
2935  /// @retval ::FF_ERR_BAD_DATABASE
2936  /// if the API encounters an internal error
2937  ///
2938  /// @note Do not call this function before the
2939  /// @link GetApiStatus() API status @endlink has reached
2940  /// ::FF_API_STATUS_READY. See @ref how_to_connect
2941  /// for details.
2942  ///
2943  /// @see SetDepthAlarmSettings()
2944  ///
2945  /// @ingroup master_settings_getters
2946  ///
2947  FF_Error_t GetDepthAlarmSettings (FF_DepthUnits_t *pUnits,
2948  uint32_t *pShallowAlarm,
2949  uint32_t *pDeepAlarm,
2950  FF_SettingStatus_t *pStatus) const;
2951 
2952 
2953  ////////////////////////////////////////////////////////////////////////
2954  //
2955  // SETTERS
2956  //
2957  ////////////////////////////////////////////////////////////////////////
2958 
2959  ////////////////////////////////////////////////////////////////////////
2960  /// @defgroup setters Setters
2961  /// @ingroup stff_member_functions
2962  ///
2963  /// Functions that allow changing settings in the API and in the
2964  /// connected black box fish finder.
2965  ///
2966  /// Upon calling a setter function, the following sequence of steps
2967  /// occurs:
2968  ///
2969  /// 1. The input parameter(s) are limit checked within the API
2970  /// to ensure their values are within the allowable bounds.
2971  /// At this stage of the process, the input values are not
2972  /// coerced to legal values; if the input values are outside
2973  /// the legal limits, then the setter function will fail with
2974  /// an error message. @n @n
2975  ///
2976  /// 2. A request is sent to the black box to change the setting,
2977  /// and the local
2978  /// @link ::FF_SettingStatus_t setting status @endlink
2979  /// corresponding to that setting is set to
2980  /// ::FF_SETTING_STATUS_PENDING. @n @n
2981  ///
2982  /// 3. The @ref Callback_SettingChanged_t callback
2983  /// function is invoked by the setter function.
2984  /// The parameters provided to the callback are as follows:
2985  /// - ::FF_SettingType_t is set to a unique value that specifies
2986  /// the specific setting that is being changed.
2987  ///
2988  /// - If the setting is specific to a frequency context, then the
2989  /// ::FF_Frequency_t parameter in the call to the
2990  /// @ref Callback_SettingChanged_t callback is set to either
2991  /// ::FF_FREQUENCY_200_KHZ or ::FF_FREQUENCY_50_KHZ, depending
2992  /// on the frequency specified in the call to the setter
2993  /// function.
2994  /// If the setting is not frequency-specific, then the
2995  /// ::FF_Frequency_t parameter is set to ::FF_INVALID_FREQUENCY.
2996  ///
2997  /// - The @p STFishFinder* parameter is set to point to the
2998  /// present instance of the STFishFinder class. This pointer
2999  /// may be used within the callback to access a getter function.
3000  ///
3001  /// Within the callback function, the getter function corresponding
3002  /// to the setting being changed may be called.
3003  /// The @link ::FF_SettingStatus_t pStatus @endlink value
3004  /// provided by the getter function will be
3005  /// ::FF_SETTING_STATUS_PENDING indicating that this call to the
3006  /// callback is occurring prior to having received the response
3007  /// from the black box. @n @n
3008  ///
3009  /// 4. After return from the callback, the setter function returns
3010  /// control to the caller of the setter function. @n @n
3011  ///
3012  /// 5. A short time later, the black box will transmit a response to
3013  /// the API that announces the new setting value. If the setting
3014  /// is a <em>Master Setting</em>, the same message will be
3015  /// transmitted to @e all displays and apps simultaneously
3016  /// connected to the same black box. @n @n
3017  /// In some circumstances, the new setting may have been coerced
3018  /// by the black box to a slightly different value than the one
3019  /// requested. For example, a value might be rounded off.
3020  /// When the API receives the response, it stores the new setting
3021  /// value within the API, and the local
3022  /// @link ::FF_SettingStatus_t setting status @endlink value
3023  /// is set to ::FF_SETTING_STATUS_VALID. @n @n
3024  ///
3025  /// 6. The @ref Callback_SettingChanged_t callback
3026  /// function is now invoked a second time, with the same parameters
3027  /// as in step 3.
3028  /// This time, a call by the callback to the getter function
3029  /// corresponding to the setting being changed will produce a
3030  /// @link ::FF_SettingStatus_t pStatus @endlink of
3031  /// ::FF_SETTING_STATUS_VALID, indicating that this call to the
3032  /// callback is occurring after the black box has provided a
3033  /// confirmed setting. @n @n
3034  /// If the setting is a <em>Master Setting </em>, and the setting
3035  /// was initiated by a different app (in a different display device)
3036  /// connected to the same black box, then this callback call within
3037  /// the present device will be the first and only invocation of the
3038  /// callback within the present device occurring as a result of the
3039  /// setting change.
3040  ///
3041  ///
3042  /// Each setter function has a corresponding getter function, which
3043  /// allows the setting to be immediately read back from the local
3044  /// API storage. The <b>See Also</b> section in the description
3045  /// for each setter function includes a link to the description
3046  /// for its corresponding getter function.
3047  ///
3048  /// Setters are member functions of the STFishFinder class.
3049  ///
3050  /// @see getters
3051  /// @see init_and_control
3052  /// @see @ref Callback_SettingChanged_t
3053  ////////////////////////////////////////////////////////////////////////
3054 
3055 
3056  ////////////////////////////////////
3057  // SETTERS FOR LOCAL SETTINGS
3058  ////////////////////////////////////
3059 
3060  ////////////////////////////////////////////////////////////////////////
3061  /// @defgroup settings_setters Setters for Local Settings
3062  /// @ingroup setters
3063  ///
3064  /// Functions for changing Local Settings.
3065  /// These are member functions of the STFishFinder class.
3066  ///
3067  /// Local Settings (unlike Master Settings) do not affect other displays
3068  /// and applications that are simultaneously connected to the same black
3069  /// box.
3070  /// Local Settings are volatile, and are not retained by the black box
3071  /// through disconnect/reconnect cycles. It is therefore recommended
3072  /// that the application program store Local Settings in persistent
3073  /// storage (e.g. flash memory, hard drive, etc.), and call the various
3074  /// setter functions upon each
3075  /// @link how_to_connect reconnection @endlink to the black box.
3076  ///
3077  /// @see settings_getters
3078  /// @see master_settings_setters
3079  ////////////////////////////////////////////////////////////////////////
3080 
3081  ////////////////////////////////////////////////////////////////////////
3082  /// @fn SetNumInputSamples
3083  ///
3084  /// Setter function to establish the number of samples that will
3085  /// be provided by the black box when transferring each column of
3086  /// image data to the API.
3087  ///
3088  /// A single Number of Input Samples setting applies to both the
3089  /// 200 kHz and 50 kHz frequency contexts.
3090  ///
3091  /// The Number of Input Samples setting is a
3092  /// @link settings_setters Local Setting @endlink.
3093  ///
3094  /// @note
3095  /// -# The value to be used in the parameter to this
3096  /// function should be chosen carefully.
3097  /// Higher values increase the resolution of the image
3098  /// that may be displayed, but also increase the amount
3099  /// of data that must be transferred and the amount of
3100  /// data that must be processed by the API and by the
3101  /// application program.
3102  /// It is suggested that performance benchmark testing
3103  /// be conducted in a loaded system to determine an
3104  /// optimum value for @p numInputSamples to achieve a
3105  /// good balance between scrolling speed, responsiveness,
3106  /// and image resolution.
3107  /// @n @n
3108  /// -# The value provided in the @p numInputSamples
3109  /// parameter should be regarded as a request. It is
3110  /// possible that the black box might override the
3111  /// value requested with a different value. This can
3112  /// happen if this function is called with an illegal
3113  /// value, or the black box may attempt to balance the
3114  /// needs of multiple connected display devices
3115  /// by adjusting some of the settings values.
3116  /// Therefore, it is recommended that after the black
3117  /// box has responded to the setting change, the
3118  /// GetNumInputSamples() function be called to verify
3119  /// the new setting. This can be done in the
3120  /// @ref Callback_SettingChanged_t callback function.
3121  ///
3122  /// @param[in] numInputSamples
3123  /// the number of samples per column requested to be
3124  /// provided by the black box when it transfers image
3125  /// data to the API. This value must fall within the
3126  /// range of values established by a prior call to
3127  /// GetInputSamplesLimits(), such that
3128  /// MinInputSamples <= numInputSamples <= MaxInputSamples
3129  ///
3130  /// @retval ::FF_ERR_NO_ERROR
3131  /// if the operation completed successfully
3132  ///
3133  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3134  /// if the @p numInputSamples parameter is outside the
3135  /// range of allowable values.
3136  ///
3137  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3138  /// if the @link GetApiStatus() API status @endlink
3139  /// is not ::FF_API_STATUS_READY prior to calling this
3140  /// function
3141  ///
3142  /// @retval ::FF_ERR_BAD_DATABASE
3143  /// if the API encounters an internal error
3144  ///
3145  /// @par Callback
3146  /// This function will cause the @ref Callback_SettingChanged_t
3147  /// callback function to be invoked.
3148  /// The parameters to that callback will be as follows:
3149  ///
3150  /// @par
3151  /// Callback Parameter | Value
3152  /// ------------------ | -----
3153  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_NUM_INPUT_SAMPLES
3154  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3155  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3156  ///
3157  ///
3158  /// @note Do not call this function before the
3159  /// @link GetApiStatus() API status @endlink has reached
3160  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3161  /// for details.
3162  ///
3163  /// Refer to @ref setters for a general description of the actions
3164  /// performed by setters such as this function, and the subsequent
3165  /// events that result.
3166  ///
3167  /// @see GetNumInputSamples()
3168  /// @see GetInputSamplesLimits()
3169  /// @see setters
3170  ///
3171  /// @ingroup settings_setters
3172  ///
3173  FF_Error_t SetNumInputSamples (uint16_t numInputSamples);
3174 
3175 
3176  ////////////////////////////////////////////////////////////////////////
3177  /// @fn SetFrequencyMode
3178  ///
3179  /// Setter function to specify the Frequency Mode setting for the
3180  /// black box and the API.
3181  /// The Frequency Mode specifies whether the black box should
3182  /// provide image data for 200 kHz only, 50 kHz only, or
3183  /// alternating 200 kHz / 50 kHz.
3184  ///
3185  /// The Frequency Mode setting is a
3186  /// @link settings_setters Local Setting @endlink.
3187  ///
3188  /// @param[in] frequencyMode
3189  /// the requested Frequency Mode setting.
3190  ///
3191  /// @retval ::FF_ERR_NO_ERROR
3192  /// if the operation completed successfully
3193  ///
3194  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3195  /// if the @p frequencyMode parameter is outside the
3196  /// range of allowable values.
3197  ///
3198  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3199  /// if the @link GetApiStatus() API status @endlink
3200  /// is not ::FF_API_STATUS_READY prior to calling this
3201  /// function
3202  ///
3203  /// @retval ::FF_ERR_BAD_DATABASE
3204  /// if the API encounters an internal error
3205  ///
3206  /// @par Callback
3207  /// This function will cause the @ref Callback_SettingChanged_t
3208  /// callback function to be invoked.
3209  /// The parameters to that callback will be as follows:
3210  ///
3211  /// @par
3212  /// Callback Parameter | Value
3213  /// ------------------ | -----
3214  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_FREQUENCY_MODE
3215  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3216  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3217  ///
3218  ///
3219  /// @note Do not call this function before the
3220  /// @link GetApiStatus() API status @endlink has reached
3221  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3222  /// for details.
3223  ///
3224  /// Refer to @ref setters for a general description of the actions
3225  /// performed by setters such as this function, and the subsequent
3226  /// events that result.
3227  ///
3228  /// @see GetFrequencyMode()
3229  /// @see ::FF_FrequencyMode_t
3230  /// @see setters
3231  ///
3232  /// @ingroup settings_setters
3233  ///
3234  FF_Error_t SetFrequencyMode (FF_FrequencyMode_t frequencyMode);
3235 
3236 
3237  ////////////////////////////////////////////////////////////////////////
3238  /// @fn SetAutoGainSetting
3239  ///
3240  /// Setter function to specify the Auto Gain setting for the
3241  /// black box and the API. The Auto Gain setting can have one of
3242  /// two values: Auto or Manual.
3243  ///
3244  /// The Auto Gain setting applies to both the
3245  /// 200 kHz and 50 kHz frequency contexts.
3246  ///
3247  /// In addition to changing the Auto Gain setting to Auto or Manual,
3248  /// this function also affects the Gain and/or Gain Offset values
3249  /// for both frequencies as follows:
3250  /// - If Auto Gain is being changed from Manual to Auto, then the
3251  /// Gain Offset value for each frequency is reset to 0 upon
3252  /// entering Auto mode.
3253  /// - If Auto Gain is being changed from Auto to Manual, then
3254  /// the Gain value for each frequency is increased or decreased
3255  /// by the corresponding current setting of the Gain Offset value,
3256  /// so as to maintain the same effective level of gain.
3257  ///
3258  /// The Auto Gain setting is a
3259  /// @link settings_setters Local Setting @endlink.
3260  ///
3261  /// @param[in] autoGainSetting
3262  /// the requested Auto Gain setting.
3263  ///
3264  /// @retval ::FF_ERR_NO_ERROR
3265  /// if the operation completed successfully
3266  ///
3267  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3268  /// if the @p autoGainSetting parameter is outside the
3269  /// range of allowable values.
3270  ///
3271  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3272  /// if the @link GetApiStatus() API status @endlink
3273  /// is not ::FF_API_STATUS_READY prior to calling this
3274  /// function
3275  ///
3276  /// @retval ::FF_ERR_BAD_DATABASE
3277  /// if the API encounters an internal error
3278  ///
3279  /// @par Callback
3280  /// This function will cause the @ref Callback_SettingChanged_t
3281  /// callback function to be invoked.
3282  /// The parameters to that callback will be as follows:
3283  ///
3284  /// @par
3285  /// Callback Parameter | Value
3286  /// ------------------ | -----
3287  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_AUTO_GAIN_SETTING
3288  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3289  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3290  ///
3291  ///
3292  /// @note Do not call this function before the
3293  /// @link GetApiStatus() API status @endlink has reached
3294  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3295  /// for details.
3296  ///
3297  /// Refer to @ref setters for a general description of the actions
3298  /// performed by setters such as this function, and the subsequent
3299  /// events that result.
3300  ///
3301  /// @see GetAutoGainSetting()
3302  /// @see ::FF_AutoGainSetting_t
3303  /// @see SetGain()
3304  /// @see SetGainOffset()
3305  /// @see setters
3306  ///
3307  /// @ingroup settings_setters
3308  ///
3309  FF_Error_t SetAutoGainSetting (FF_AutoGainSetting_t autoGainSetting);
3310 
3311 
3312  ////////////////////////////////////////////////////////////////////////
3313  /// @cond
3314  /// ^^^^^ Do not include documentation for this function
3315  ///
3316  FF_Error_t SetWaterFilterSetting (FF_Frequency_t frequency, const FF_WaterFilterSetting_t *pWaterFilterSetting);
3317  /// @endcond
3318 
3319 
3320  ////////////////////////////////////////////////////////////////////////
3321  /// @fn SetAutoRangeSetting
3322  ///
3323  /// Setter function to specify the Auto Range setting for the
3324  /// black box and the API. The Auto Range setting can have one of
3325  /// three values: Auto Range, Auto Shift, or Manual.
3326  /// - In Auto Range mode, the shallow range limit is fixed at 0, and
3327  /// the deep range limit is adjusted automatically to keep the
3328  /// seabed visible in the lower part of the image column.
3329  /// - In Auto Shift mode, the delta between the shallow and deep
3330  /// range limits is fixed, and they are adjusted automatically
3331  /// in tandem to keep the seabed visible. The amount of delta
3332  /// is established as the delta at the time the Auto Range setting
3333  /// is changed to Auto Shift mode.
3334  /// - In Manual mode, the shallow and deep range limits are fixed
3335  /// and may be specified by calling SetRange().
3336  ///
3337  /// The Auto Range setting applies to both the
3338  /// 200 kHz and 50 kHz frequency contexts.
3339  ///
3340  /// The Auto Range setting is a
3341  /// @link settings_setters Local Setting @endlink.
3342  ///
3343  /// @param[in] autoRangeSetting
3344  /// the requested Auto Range setting.
3345  ///
3346  /// @param[in] units
3347  /// the depth units that the Auto Range or Auto Shift
3348  /// modes should use when automatically changing the
3349  /// range. This parameter is ignored when the
3350  /// @p autoRangeSetting parameter is set to
3351  /// ::FF_AUTO_RANGE_SETTING_MANUAL.
3352  ///
3353  /// @retval ::FF_ERR_NO_ERROR
3354  /// if the operation completed successfully
3355  ///
3356  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3357  /// if the @p autoRangeSetting parameter is outside the
3358  /// range of allowable values.
3359  ///
3360  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3361  /// if the @link GetApiStatus() API status @endlink
3362  /// is not ::FF_API_STATUS_READY prior to calling this
3363  /// function
3364  ///
3365  /// @retval ::FF_ERR_BAD_DATABASE
3366  /// if the API encounters an internal error
3367  ///
3368  /// @par Callback
3369  /// This function will cause the @ref Callback_SettingChanged_t
3370  /// callback function to be invoked.
3371  /// The parameters to that callback will be as follows:
3372  ///
3373  /// @par
3374  /// Callback Parameter | Value
3375  /// ------------------ | -----
3376  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_AUTO_RANGE_SETTING
3377  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3378  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3379  ///
3380  ///
3381  /// @note Do not call this function before the
3382  /// @link GetApiStatus() API status @endlink has reached
3383  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3384  /// for details.
3385  ///
3386  /// Refer to @ref setters for a general description of the actions
3387  /// performed by setters such as this function, and the subsequent
3388  /// events that result.
3389  ///
3390  /// @see GetAutoRangeSetting()
3391  /// @see ::FF_AutoRangeSetting_t
3392  /// @see SetRange()
3393  /// @see setters
3394  ///
3395  /// @ingroup settings_setters
3396  ///
3397  FF_Error_t SetAutoRangeSetting (FF_AutoRangeSetting_t autoRangeSetting,
3398  FF_DepthUnits_t units);
3399 
3400 
3401  ////////////////////////////////////////////////////////////////////////
3402  /// @fn SetRange
3403  ///
3404  /// Setter function to "manually" specify the Range setting for the
3405  /// black box and the API.
3406  ///
3407  /// The Range setting applies to both the
3408  /// 200 kHz and 50 kHz frequency contexts.
3409  ///
3410  /// The Range setting is a
3411  /// @link settings_setters Local Setting @endlink.
3412  ///
3413  /// @note If the Auto Range setting is not already in
3414  /// Manual mode prior to calling this function
3415  /// (i.e. ::FF_AUTO_RANGE_SETTING_MANUAL), then the
3416  /// call to this function SetRange() shall change
3417  /// the Auto Range setting to Manual as a
3418  /// consequence of setting the range.
3419  ///
3420  /// @param[in] pRangeSetting
3421  /// pointer to a location containing the requested
3422  /// Range setting.
3423  /// The @p *pRangeSetting value is a struct of type
3424  /// ::FF_RangeSetting_t that specifies the shallow and
3425  /// deep limits to be used for
3426  /// subsequently transmitted ImageColumn objects.
3427  /// The struct contains a shallow depth value
3428  /// corresponding to the first sample in the ImageColumn
3429  /// buffer, a deep depth value corresponding to the last
3430  /// sample, and a depth units specifier indicating
3431  /// whether the depth values are in units of feet,
3432  /// meters, or fathoms. @n @n
3433  /// The depth values must be
3434  /// provided in hundredths of the specified depth
3435  /// units. For example, for a 20 to 40 foot range,
3436  /// the @link FF_RangeSetting_t.rangeShallow rangeShallow
3437  /// @endlink member should contain 2000, the
3438  /// @link FF_RangeSetting_t.rangeDeep rangeDeep
3439  /// @endlink member should contain 4000, and the
3440  /// @link FF_RangeSetting_t.units units @endlink
3441  /// member should contain ::FF_DEPTH_UNITS_FEET. @n @n
3442  /// The value of the
3443  /// @link FF_RangeSetting_t.rangeDeep rangeDeep
3444  /// @endlink member must fall within the range of
3445  /// values specified by the GetRangeLimits() function.
3446  /// The value of the
3447  /// @link FF_RangeSetting_t.rangeShallow rangeShallow
3448  /// @endlink member must obey the following rule:
3449  /// 0 <= @e rangeShallow < @e rangeDeep
3450  ///
3451  /// @retval ::FF_ERR_NO_ERROR
3452  /// if the operation completed successfully
3453  ///
3454  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3455  /// if any of the members of the ::FF_RangeSetting_t
3456  /// struct pointed to by the @p pRangeSetting parameter
3457  /// are outside the range of allowable values.
3458  ///
3459  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3460  /// if the @link GetApiStatus() API status @endlink
3461  /// is not ::FF_API_STATUS_READY prior to calling this
3462  /// function
3463  ///
3464  /// @retval ::FF_ERR_BAD_DATABASE
3465  /// if the API encounters an internal error
3466  ///
3467  /// @par Callback
3468  /// This function will cause the @ref Callback_SettingChanged_t
3469  /// callback function to be invoked.
3470  /// The parameters to that callback will be as follows:
3471  ///
3472  /// @par
3473  /// Callback Parameter | Value
3474  /// ------------------ | -----
3475  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_RANGE
3476  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3477  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3478  ///
3479  ///
3480  /// @note Do not call this function before the
3481  /// @link GetApiStatus() API status @endlink has reached
3482  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3483  /// for details.
3484  ///
3485  /// Refer to @ref setters for a general description of the actions
3486  /// performed by setters such as this function, and the subsequent
3487  /// events that result.
3488  ///
3489  /// @see GetRange()
3490  /// @see GetRangeLimits()
3491  /// @see ::FF_RangeSetting_t
3492  /// @see SetAutoRangeSetting()
3493  /// @see setters
3494  ///
3495  /// @ingroup settings_setters
3496  ///
3497  FF_Error_t SetRange (const FF_RangeSetting_t *pRangeSetting);
3498 
3499 
3500  ////////////////////////////////////////////////////////////////////////
3501  /// @fn SetGain
3502  ///
3503  /// Setter function to "manually" specify the Gain setting for the
3504  /// black box. Separate Gain settings are used for the 200 kHz and
3505  /// 50 kHz frequency contexts.
3506  ///
3507  /// The Gain setting is a
3508  /// @link settings_setters Local Setting @endlink.
3509  ///
3510  /// @note If the Auto Gain setting is not already in
3511  /// Manual mode prior to calling this function
3512  /// (i.e. ::FF_AUTO_GAIN_SETTING_MANUAL), then the
3513  /// call to this function SetGain() shall change
3514  /// the Auto Gain setting to Manual as a
3515  /// consequence of setting the gain.
3516  ///
3517  /// @param[in] frequency
3518  /// The frequency context for which the Gain is to be set.
3519  ///
3520  /// @param[in] gainSetting
3521  /// the requested Gain setting.
3522  /// The value of the @p gainSetting parameter must fall
3523  /// within the range of values specified by the
3524  /// GetGainLimits() function.
3525  ///
3526  /// @retval ::FF_ERR_NO_ERROR
3527  /// if the operation completed successfully
3528  ///
3529  /// @retval ::FF_ERR_INVALID_FREQUENCY
3530  /// if the provided @p frequency parameter has an invalid
3531  /// value (see ::FF_Frequency_t)
3532  ///
3533  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3534  /// if the provided @p gainSetting parameter is outside the
3535  /// range of allowable values.
3536  ///
3537  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3538  /// if the @link GetApiStatus() API status @endlink
3539  /// is not ::FF_API_STATUS_READY prior to calling this
3540  /// function
3541  ///
3542  /// @retval ::FF_ERR_BAD_DATABASE
3543  /// if the API encounters an internal error
3544  ///
3545  /// @par Callback
3546  /// This function will cause the @ref Callback_SettingChanged_t
3547  /// callback function to be invoked.
3548  /// The parameters to that callback will be as follows:
3549  ///
3550  /// @par
3551  /// Callback Parameter | Value
3552  /// ------------------ | -----
3553  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_GAIN
3554  /// ::FF_Frequency_t | the value of the @p frequency argument in the call to SetGain()
3555  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3556  ///
3557  ///
3558  /// @note Do not call this function before the
3559  /// @link GetApiStatus() API status @endlink has reached
3560  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3561  /// for details.
3562  ///
3563  /// Refer to @ref setters for a general description of the actions
3564  /// performed by setters such as this function, and the subsequent
3565  /// events that result.
3566  ///
3567  /// @see GetGain()
3568  /// @see GetGainLimits()
3569  /// @see SetAutoGainSetting()
3570  /// @see setters
3571  ///
3572  /// @ingroup settings_setters
3573  ///
3574  FF_Error_t SetGain (FF_Frequency_t frequency, uint16_t gainSetting);
3575 
3576 
3577  ////////////////////////////////////////////////////////////////////////
3578  /// @fn SetGainOffset
3579  ///
3580  /// Setter function to specify the Gain Offset setting for the
3581  /// black box. Separate Gain Offset settings are used for the
3582  /// 200 kHz and 50 kHz frequency contexts.
3583  ///
3584  /// The Gain Offset setting is a
3585  /// @link settings_setters Local Setting @endlink.
3586  ///
3587  /// @param[in] frequency
3588  /// The frequency context for which the Gain Offset
3589  /// is to be set.
3590  ///
3591  /// @param[in] gainOffset
3592  /// the requested Gain Offset setting.
3593  /// The value of the @p gainOffset parameter must fall
3594  /// within the range of values specified by the
3595  /// GetGainOffsetLimits() function.
3596  ///
3597  /// @retval ::FF_ERR_NO_ERROR
3598  /// if the operation completed successfully
3599  ///
3600  /// @retval ::FF_ERR_INVALID_FREQUENCY
3601  /// if the provided @p frequency parameter has an invalid
3602  /// value (see ::FF_Frequency_t)
3603  ///
3604  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3605  /// if the provided @p gainOffset parameter is outside the
3606  /// range of allowable values.
3607  ///
3608  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3609  /// if the @link GetApiStatus() API status @endlink
3610  /// is not ::FF_API_STATUS_READY prior to calling this
3611  /// function
3612  ///
3613  /// @retval ::FF_ERR_BAD_DATABASE
3614  /// if the API encounters an internal error
3615  ///
3616  /// @par Callback
3617  /// This function will cause the @ref Callback_SettingChanged_t
3618  /// callback function to be invoked.
3619  /// The parameters to that callback will be as follows:
3620  ///
3621  /// @par
3622  /// Callback Parameter | Value
3623  /// ------------------ | -----
3624  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_GAIN_OFFSET
3625  /// ::FF_Frequency_t | the value of the @p frequency argument in the call to SetGainOffset()
3626  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3627  ///
3628  ///
3629  /// @note Do not call this function before the
3630  /// @link GetApiStatus() API status @endlink has reached
3631  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3632  /// for details.
3633  ///
3634  /// Refer to @ref setters for a general description of the actions
3635  /// performed by setters such as this function, and the subsequent
3636  /// events that result.
3637  ///
3638  /// @see GetGainOffset()
3639  /// @see GetGainOffsetLimits()
3640  /// @see SetAutoGainSetting()
3641  /// @see setters
3642  ///
3643  /// @ingroup settings_setters
3644  ///
3645  FF_Error_t SetGainOffset (FF_Frequency_t frequency,
3646  int16_t gainOffset);
3647 
3648 
3649  ////////////////////////////////////////////////////////////////////////
3650  /// @fn SetGainColorOffsets
3651  ///
3652  /// Setter function to specify the number of colors the API should
3653  /// provide in the STFF::ImageColumn data, and the table of
3654  /// gain offset steps to use for separating the received sonar
3655  /// signal into its colors.
3656  ///
3657  /// The table of gain offset steps establishes the total
3658  /// <i>dynamic range</i> of the displayed image, and plays a
3659  /// significant role in defining the 'personality' of the
3660  /// fish finder. A wider dynamic range tends to provide more
3661  /// information on the fish finder display (i.e. more signal, and
3662  /// possibly more clutter).
3663  ///
3664  /// The number of colors must be the same for both 200 kHz and 50 kHz
3665  /// frequency contexts, but the tables of gain offset steps are
3666  /// specified separately for the two frequencies.
3667  ///
3668  /// The Gain Color Offsets settings are
3669  /// @link settings_setters Local Settings @endlink.
3670  ///
3671  /// @param[in] frequency
3672  /// the frequency context for which the Gain Color Offsets
3673  /// are to be set.
3674  ///
3675  /// @param[in] numColors
3676  /// the total number of colors in the spectrum within
3677  /// STFF::ImageColumn objects generated by the API.
3678  /// This value must be between 2 and 2^(bit depth)
3679  /// inclusive. Therefore:
3680  ///
3681  /// - For bit depth 4: 2 <= @p numColors <= 16
3682  /// - For bit depth 8: 2 <= @p numColors <= 256
3683  ///
3684  /// <em>Important Note:</em> The same value must be used
3685  /// for the @p numColors parameter in both 200 kHz and
3686  /// 50 kHz frequency contexts. Do not specify a different
3687  /// value for @p numColors for 50 kHz than for 200 kHz.
3688  ///
3689  /// @param[in] pGainColorOffsets
3690  /// pointer to the start of an array of Gain Color Offset
3691  /// values. The number of values in the array must be
3692  /// (@p numColors - 2).
3693  /// Each value in the array corresponds to a relative
3694  /// threshold of signal strength that divides two
3695  /// adjacent colors in the spectrum.
3696  /// With the total number of colors being @p numColors,
3697  /// the total number of boundaries between adjacent
3698  /// colors is (@p numColors - 1).
3699  /// The boundary between the strongest color and the
3700  /// second-strongest color is defined to have an offset
3701  /// of 0. All other offsets are relative to this
3702  /// specific boundary.
3703  /// Since this first offset is fixed at 0, it doesn't
3704  /// need to be expressly provided in the
3705  /// @p pGainColorOffsets array.
3706  /// The array therefore consists of the offsets for the
3707  /// remaining (@p numColors - 2) color boundaries.
3708  /// Each value in the array is a signal strength offset,
3709  /// measured in gain steps, from the lowest threshold (0)
3710  /// to the current threshold.
3711  /// The first provided element in the array (at array
3712  /// index 0) must contain the difference in signal strength
3713  /// (measured in gain steps) between the lowest threshold
3714  /// (0) and the threshold between the second-strongest
3715  /// color and the third-strongest color.
3716  /// Each subsequent element in the array must be >= the
3717  /// previous element in the array.
3718  /// The values near the beginning of the array correspond
3719  /// to color offsets for strong signals, and the values
3720  /// near the end of the array correspond to color offsets
3721  /// for weak signals.
3722  ///
3723  /// @retval ::FF_ERR_NO_ERROR
3724  /// if the operation completed successfully
3725  ///
3726  /// @retval ::FF_ERR_INVALID_FREQUENCY
3727  /// if the provided @p frequency parameter has an invalid
3728  /// value (see ::FF_Frequency_t)
3729  ///
3730  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3731  /// if the provided @p numColors value is outside the
3732  /// range of 2 <= @p numColors <= 2^(bit depth),
3733  /// or if the provided values in the pGainColorOffsets
3734  /// array do not follow the rule
3735  /// pGainColorOffsets[n] >= pGainColorOffsets[n-1]
3736  /// for all n, 0 < n < (numColors-2)
3737  ///
3738  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3739  /// if the @link GetApiStatus() API status @endlink
3740  /// is not ::FF_API_STATUS_READY prior to calling this
3741  /// function
3742  ///
3743  /// @retval ::FF_ERR_BAD_DATABASE
3744  /// if the API encounters an internal error
3745  ///
3746  /// @par Callback
3747  /// This function will cause the @ref Callback_SettingChanged_t
3748  /// callback function to be invoked.
3749  /// The parameters to that callback will be as follows:
3750  ///
3751  /// @par
3752  /// Callback Parameter | Value
3753  /// ------------------ | -----
3754  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_GAIN_COLOR_OFFSETS
3755  /// ::FF_Frequency_t | the value of the @p frequency argument in the call to SetGainOffset()
3756  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3757  ///
3758  ///
3759  /// @note Do not call this function before the
3760  /// @link GetApiStatus() API status @endlink has reached
3761  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3762  /// for details.
3763  ///
3764  /// Refer to @ref setters for a general description of the actions
3765  /// performed by setters such as this function, and the subsequent
3766  /// events that result.
3767  ///
3768  /// @see GetGainColorOffsets()
3769  /// @see GetGainColorOffsetsLimits()
3770  /// @see setters
3771  ///
3772  /// @ingroup settings_setters
3773  ///
3774  FF_Error_t SetGainColorOffsets (FF_Frequency_t frequency,
3775  uint16_t numColors,
3776  const uint16_t *pGainColorOffsets);
3777 
3778 
3779  ////////////////////////////////////////////////////////////////////////
3780  /// @cond
3781  /// ^^^^^ Do not include documentation for this function
3782  ///
3783  FF_Error_t SetFSTC (FF_Frequency_t frequency, const FF_FstcSetting_t *pFstcSetting);
3784  /// @endcond
3785 
3786 
3787  ////////////////////////////////////////////////////////////////////////
3788  /// @fn SetFishIdSetting
3789  ///
3790  /// Setter function to specify the Fish ID setting for the
3791  /// black box and the API.
3792  /// Separate Fish ID settings are used for the 200 kHz and
3793  /// 50 kHz frequency contexts.
3794  ///
3795  /// The Fish ID setting is a
3796  /// @link settings_setters Local Setting @endlink.
3797  ///
3798  /// @param[in] frequency
3799  /// The frequency context for which the Fish ID
3800  /// setting will apply.
3801  ///
3802  /// @param[in] pFishIdSetting
3803  /// pointer to a location containing the requested
3804  /// Fish ID setting.
3805  /// The @p *pFishIdSetting value is a struct of type
3806  /// ::FF_FishIdSetting_t.
3807  /// [Further description TBD]
3808  ///
3809  /// @retval ::FF_ERR_NO_ERROR
3810  /// if the operation completed successfully
3811  ///
3812  /// @retval ::FF_ERR_INVALID_FREQUENCY
3813  /// if the provided @p frequency parameter has an invalid
3814  /// value (see ::FF_Frequency_t)
3815  ///
3816  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3817  /// if any of the members of the ::FF_FishIdSetting_t
3818  /// struct pointed to by the @p pFishIdSetting parameter
3819  /// are outside the range of allowable values.
3820  ///
3821  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3822  /// if the @link GetApiStatus() API status @endlink
3823  /// is not ::FF_API_STATUS_READY prior to calling this
3824  /// function
3825  ///
3826  /// @retval ::FF_ERR_BAD_DATABASE
3827  /// if the API encounters an internal error
3828  ///
3829  /// @par Callback
3830  /// This function will cause the @ref Callback_SettingChanged_t
3831  /// callback function to be invoked.
3832  /// The parameters to that callback will be as follows:
3833  ///
3834  /// @par
3835  /// Callback Parameter | Value
3836  /// ------------------ | -----
3837  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_FISH_ID_SETTING
3838  /// ::FF_Frequency_t | the value of the @p frequency argument in the call to SetFishIdSetting()
3839  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3840  ///
3841  ///
3842  /// @note Do not call this function before the
3843  /// @link GetApiStatus() API status @endlink has reached
3844  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3845  /// for details.
3846  ///
3847  /// Refer to @ref setters for a general description of the actions
3848  /// performed by setters such as this function, and the subsequent
3849  /// events that result.
3850  ///
3851  /// @see GetFishIdSetting()
3852  /// @see setters
3853  ///
3854  /// @ingroup settings_setters
3855  ///
3856  FF_Error_t SetFishIdSetting (FF_Frequency_t frequency,
3857  const FF_FishIdSetting_t *pFishIdSetting);
3858 
3859 
3860  ////////////////////////////////////////////////////////////////////////
3861  /// @cond
3862  /// ^^^^^ Do not include documentation for this function
3863  ///
3864  FF_Error_t SetFishAlarmSetting (/* tbd */);
3865  /// @endcond
3866 
3867 
3868  ////////////////////////////////////
3869  // SETTERS FOR MASTER SETTINGS
3870  ////////////////////////////////////
3871 
3872  ////////////////////////////////////////////////////////////////////////
3873  /// @defgroup master_settings_setters Setters for Master Settings
3874  /// @ingroup setters
3875  ///
3876  /// Functions for changing Master Settings.
3877  /// These are member functions of the STFishFinder class.
3878  ///
3879  /// Unlike Local Settings, which only affect the present display and
3880  /// application, Master Settings globally affect all displays and
3881  /// applications that are simultaneously connected to the same
3882  /// black box.
3883  /// Master Settings are saved in nonvolatile memory within the black box
3884  /// and restored on each power up. They should @e not be stored in the
3885  /// local application's persistent storage, and the setters for Master
3886  /// Settings should @e not be called as a matter of course when the
3887  /// @link settings_setters setters for Local Settings @endlink
3888  /// are called during
3889  /// @link how_to_connect API initialization @endlink.
3890  ///
3891  /// Changing a Master Setting will cause a message to be sent to
3892  /// all display devices that are connected to the black box at the
3893  /// time the setting is changed. This message will result in the
3894  /// @ref Callback_SettingChanged_t callback function being called on all
3895  /// connected devices. As a consequence of this behavior, if another
3896  /// connected display device calls one of these functions, the
3897  /// @ref Callback_SettingChanged_t callback in the present application
3898  /// might be called at any time without warning to notify the
3899  /// application of the changed setting.
3900  ///
3901  /// @see master_settings_getters
3902  /// @see setters
3903  ////////////////////////////////////////////////////////////////////////
3904 
3905  ////////////////////////////////////////////////////////////////////////
3906  /// @fn SetTemperatureOffset
3907  ///
3908  /// Setter function to specify the Temperature Offset calibration
3909  /// setting for the black box. This setting is used to apply a
3910  /// correction to the water temperature reading provided by the
3911  /// GetTemperature() function. The Temperature Offset value is
3912  /// added to the raw temperature value to produce the corrected
3913  /// value reported by GetTemperature().
3914  ///
3915  /// The Temperature Offset setting is a
3916  /// @link master_settings_setters Master Setting @endlink, affecting
3917  /// all devices that connect to the presently connected black box.
3918  /// This setting is saved in the non-volatile memory within the
3919  /// black box and restored on each power-up.
3920  ///
3921  /// @param[in] units
3922  /// The temperature units (Celsius or Fahrenheit)
3923  /// in which the @p temperatureOffset parameter is
3924  /// specified.
3925  ///
3926  /// @param[in] temperatureOffset
3927  /// the requested Temperature Offset setting, in
3928  /// hundredths of the specified units.
3929  /// For example, if the required Temperature Offset is
3930  /// -1.5 degrees Celsius, then the @p temperatureOffset
3931  /// parameter would be -150, and the @p units parameter
3932  /// would be ::FF_TEMPERATURE_UNITS_CELSIUS.
3933  /// The value of the @p temperatureOffset parameter
3934  /// must fall within the range of values specified by the
3935  /// GetTemperatureOffsetLimits() function.
3936  ///
3937  /// @retval ::FF_ERR_NO_ERROR
3938  /// if the operation completed successfully
3939  ///
3940  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
3941  /// if either of the input parameters is outside the
3942  /// range of allowable values.
3943  ///
3944  /// @retval ::FF_ERR_API_NOT_INITIALIZED
3945  /// if the @link GetApiStatus() API status @endlink
3946  /// is not ::FF_API_STATUS_READY prior to calling this
3947  /// function
3948  ///
3949  /// @retval ::FF_ERR_BAD_DATABASE
3950  /// if the API encounters an internal error
3951  ///
3952  /// @par Callback
3953  /// This function will cause the @ref Callback_SettingChanged_t
3954  /// callback function to be invoked in the present app, as well as
3955  /// on all fish finder apps (in all devices) simultaneously connected
3956  /// to the same black box.
3957  /// The parameters to that callback will be as follows:
3958  ///
3959  /// @par
3960  /// Callback Parameter | Value
3961  /// ------------------ | -----
3962  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_MASTER_TEMPERATURE_OFFSET
3963  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
3964  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
3965  ///
3966  ///
3967  /// @note Do not call this function before the
3968  /// @link GetApiStatus() API status @endlink has reached
3969  /// ::FF_API_STATUS_READY. See @ref how_to_connect
3970  /// for details.
3971  ///
3972  /// Refer to @ref setters for a general description of the actions
3973  /// performed by setters such as this function, and the subsequent
3974  /// events that result.
3975  ///
3976  /// @see GetTemperatureOffset()
3977  /// @see GetTemperatureOffsetLimits()
3978  /// @see setters
3979  ///
3980  /// @ingroup master_settings_setters
3981  ///
3982  FF_Error_t SetTemperatureOffset (FF_TemperatureUnits_t units,
3983  int16_t temperatureOffset);
3984 
3985 
3986  ////////////////////////////////////////////////////////////////////////
3987  /// @fn SetSpeedPulsesPerNauticalMile
3988  ///
3989  /// Setter function to specify the Speed Pulses Per Nautical Mile
3990  /// (PPNM) setting used by the black box to determine
3991  /// Speed Through Water. This setting affects the water speed
3992  /// reading provided by the GetSpeed() function.
3993  ///
3994  /// @remark Manufacturer's specifications for commonly-available
3995  /// paddlewheel sensors typically claim a nominal
3996  /// pulse rate of 20,000 PPNM (which is equivalent to
3997  /// approximately 5.56 Hertz per knot).
3998  /// The actual pulse rate varies from one installation
3999  /// to the next, depending on the rate of water flow
4000  /// at the specific mounting location of the paddlewheel
4001  /// sensor on the vessel.
4002  ///
4003  /// The Speed PPNM setting is a
4004  /// @link master_settings_setters Master Setting @endlink, affecting
4005  /// all devices that connect to the presently connected black box.
4006  /// This setting is saved in the non-volatile memory within the
4007  /// black box and restored on each power-up.
4008  ///
4009  /// @param[in] speedPPNM
4010  /// the requested Speed PPNM setting.
4011  /// The value of the @p speedPPNM parameter
4012  /// must fall within the range of values specified by the
4013  /// GetSpeedPulsesPerNauticalMileLimits() function.
4014  ///
4015  /// @retval ::FF_ERR_NO_ERROR
4016  /// if the operation completed successfully
4017  ///
4018  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
4019  /// if the input parameter is outside the
4020  /// range of allowable values.
4021  ///
4022  /// @retval ::FF_ERR_API_NOT_INITIALIZED
4023  /// if the @link GetApiStatus() API status @endlink
4024  /// is not ::FF_API_STATUS_READY prior to calling this
4025  /// function
4026  ///
4027  /// @retval ::FF_ERR_BAD_DATABASE
4028  /// if the API encounters an internal error
4029  ///
4030  /// @par Callback
4031  /// This function will cause the @ref Callback_SettingChanged_t
4032  /// callback function to be invoked in the present app, as well as
4033  /// on all fish finder apps (in all devices) simultaneously connected
4034  /// to the same black box.
4035  /// The parameters to that callback will be as follows:
4036  ///
4037  /// @par
4038  /// Callback Parameter | Value
4039  /// ------------------ | -----
4040  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_MASTER_SPEED_PPNM
4041  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
4042  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
4043  ///
4044  ///
4045  /// @note Do not call this function before the
4046  /// @link GetApiStatus() API status @endlink has reached
4047  /// ::FF_API_STATUS_READY. See @ref how_to_connect
4048  /// for details.
4049  ///
4050  /// Refer to @ref setters for a general description of the actions
4051  /// performed by setters such as this function, and the subsequent
4052  /// events that result.
4053  ///
4054  /// @see GetSpeed()
4055  /// @see GetSpeedPulsesPerNauticalMile()
4056  /// @see GetSpeedPulsesPerNauticalMileLimits()
4057  /// @see setters
4058  ///
4059  /// @ingroup master_settings_setters
4060  ///
4061  FF_Error_t SetSpeedPulsesPerNauticalMile (uint32_t speedPPNM);
4062 
4063 
4064  ////////////////////////////////////////////////////////////////////////
4065  /// @cond
4066  /// ^^^^^ Do not include documentation for this function
4067  ///
4068  FF_Error_t SetWaterType (FF_WaterType_t waterType);
4069  FF_Error_t SetDSTC (FF_Frequency_t frequency, const FF_DstcSetting_t *pDstcSetting);
4070  /// @endcond
4071 
4072 
4073  ////////////////////////////////////////////////////////////////////////
4074  /// @fn SetDepthAlarmSettings
4075  ///
4076  /// Setter function to set the Shallow Depth Alarm and
4077  /// Deep Depth Alarm master settings within the black box.
4078  ///
4079  /// The Depth Alarm settings are a
4080  /// @link master_settings_setters Master Setting @endlink, affecting
4081  /// all devices that connect to the presently connected black box.
4082  /// These settings are saved in the non-volatile memory within the
4083  /// black box and restored on each power-up.
4084  ///
4085  /// @param[in] units
4086  /// the depth units in which the @p shallowAlarmSetting
4087  /// and @p deepAlarmSetting are provided. Note that
4088  /// the Shallow and Deep alarms must both be specified
4089  /// in the same units.
4090  ///
4091  /// @param[in] shallowAlarmSetting
4092  /// the new value for the Shallow Depth Alarm setting.
4093  /// This value will be in hundredths of the unit
4094  /// specified in the @p units value.
4095  /// For example, if the specified @p units value is
4096  /// ::FF_DEPTH_UNITS_METERS, and the specified
4097  /// shallowAlarmSetting value is 300, then this
4098  /// establishes a Shallow Depth Alarm setting of
4099  /// 3.0 meters.
4100  /// If the @link GetDepth depth @endlink becomes
4101  /// shallower than the Shallow Depth Alarm setting,
4102  /// this will trigger the invocation of the
4103  /// @ref Callback_DepthAlarmStateChange_t callback
4104  /// function.
4105  /// To disable the Shallow Depth Alarm,
4106  /// set this parameter to 0.
4107  ///
4108  /// @param[in] deepAlarmSetting
4109  /// the new value for the Deep Depth Alarm setting.
4110  /// This value will be in hundredths of the unit
4111  /// specified in the @p units value.
4112  /// For example, if the specified @p units value is
4113  /// ::FF_DEPTH_UNITS_METERS, and the specified
4114  /// deepAlarmSetting value is 500, then this
4115  /// establishes a Deep Depth Alarm setting of
4116  /// 5.0 meters.
4117  /// If the @link GetDepth depth @endlink becomes
4118  /// deeper than the Deep Depth Alarm setting,
4119  /// this will trigger the invocation of the
4120  /// @ref Callback_DepthAlarmStateChange_t callback
4121  /// function.
4122  /// To disable the Deep Depth Alarm,
4123  /// set this parameter to 0.
4124  ///
4125  /// @retval ::FF_ERR_NO_ERROR
4126  /// if the operation completed successfully
4127  ///
4128  /// @retval ::FF_ERR_ARGUMENT_OUT_OF_RANGE
4129  /// if any of the input parameters is outside the
4130  /// range of allowable values.
4131  ///
4132  /// @retval ::FF_ERR_API_NOT_INITIALIZED
4133  /// if the @link GetApiStatus() API status @endlink
4134  /// is not ::FF_API_STATUS_READY prior to calling this
4135  /// function
4136  ///
4137  /// @retval ::FF_ERR_BAD_DATABASE
4138  /// if the API encounters an internal error
4139  ///
4140  /// @par Callback
4141  /// This function will cause the @ref Callback_SettingChanged_t
4142  /// callback function to be invoked in the present app, as well as
4143  /// on all fish finder apps (in all devices) simultaneously connected
4144  /// to the same black box.
4145  /// The parameters to that callback will be as follows:
4146  ///
4147  /// @par
4148  /// Callback Parameter | Value
4149  /// ------------------ | -----
4150  /// ::FF_SettingType_t | ::FF_SETTING_TYPE_MASTER_DEPTH_ALARM_SETTING
4151  /// ::FF_Frequency_t | ::FF_INVALID_FREQUENCY
4152  /// const STFishFinder* | pointer to the present instance of the STFishFinder class
4153  ///
4154  ///
4155  /// @note Do not call this function before the
4156  /// @link GetApiStatus() API status @endlink has reached
4157  /// ::FF_API_STATUS_READY. See @ref how_to_connect
4158  /// for details.
4159  ///
4160  /// Refer to @ref setters for a general description of the actions
4161  /// performed by setters such as this function, and the subsequent
4162  /// events that result.
4163  ///
4164  /// @see GetDepthAlarmSettings()
4165  /// @see @ref depth_alarms_how_to
4166  /// @see setters
4167  ///
4168  /// @ingroup master_settings_setters
4169  ///
4170  FF_Error_t SetDepthAlarmSettings (FF_DepthUnits_t units,
4171  uint32_t shallowAlarmSetting,
4172  uint32_t deepAlarmSetting);
4173 
4174  private:
4175 
4176  friend class ImageColumn;
4177  friend class Replay;
4178  friend class STFF_Client;
4179 
4180  // Default constructor is private.
4181  // See member function CreateFishFinder().
4182  STFishFinder ();
4183 
4184  // Constructor for use with Simulator and Playback modes
4185  // is private.
4186  // See member functions CreateSimulatedFishFinder() and
4187  // CreateFishFinderForPlayback().
4188  STFishFinder (const Replay*);
4189 
4190  // Private copy, swap, and assignment
4191  STFishFinder (const STFishFinder &); // copy ctor
4192  void Swap (STFishFinder& other) throw(); // swap
4193  const STFishFinder &operator= (const STFishFinder &); // assign. opr.
4194 
4195  class impl;
4196  impl *m_pimpl;
4197 
4198  }; // class STFishFinder
4199 
4200 } // namespace STFF
4201 
4202 #endif // defined (STFF_STFishFinder_h_)
4203 
4204 
STFF::STFishFinder::GetTemperature
FF_Error_t GetTemperature(FF_TemperatureUnits_t units, FF_TemperatureData_t *pTemperatureData) const
Getter function to provide the current water temperature data.
FF_DepthUnits_t
FF_DepthUnits_t
Depth Units selection.
Definition: STFF-Types.h:96
STFF::STFishFinder::GetSpeed
FF_Error_t GetSpeed(FF_SpeedUnits_t units, FF_SpeedData_t *pSpeedData) const
Getter function to provide the current Speed Through Water data.
STFF::STFishFinder::SetNumInputSamples
FF_Error_t SetNumInputSamples(uint16_t numInputSamples)
Setter function to establish the number of samples that will be provided by the black box when transf...
STFF::Callback_SettingChanged_t
void(* Callback_SettingChanged_t)(const STFishFinder *, FF_SettingType_t, FF_Frequency_t)
'Setting Changed' callback.
Definition: STFF-Callbacks.h:131
FF_BatteryVoltageData_t
Battery Voltage Data structure.
Definition: STFF-Types.h:586
STFF::STFishFinder::TimerTick
void TimerTick()
Provides a means by which time-dependent processes within the STFishFinder API can be serviced on a p...
FF_DstcSetting_t
DSTC Setting structure.
Definition: STFF-Types.h:675
STFF::STFishFinder::GetFrequencyMode
FF_Error_t GetFrequencyMode(FF_FrequencyMode_t *pFrequencyMode, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Frequency Mode setting.
STFF::STFishFinder::GetAutoGainSetting
FF_Error_t GetAutoGainSetting(FF_AutoGainSetting_t *pAutoGainSetting, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Auto Gain setting.
STFF::STFishFinder::GetGainLimits
FF_Error_t GetGainLimits(uint16_t *pMinGain, uint16_t *pMaxGain) const
Getter function to provide limits for the parameter to the SetGain() member function.
FF_DepthAlarmState_t
FF_DepthAlarmState_t
Depth Alarm State options.
Definition: STFF-Types.h:444
FF_SpeedUnits_t
FF_SpeedUnits_t
Speed Units selection.
Definition: STFF-Types.h:117
FF_SettingStatus_t
FF_SettingStatus_t
Setting Status options.
Definition: STFF-Types.h:193
STFF::Callback_DepthAlarmStateChange_t
void(* Callback_DepthAlarmStateChange_t)(const STFishFinder *, FF_DepthAlarmType_t)
'Depth Alarm State Change' callback.
Definition: STFF-Callbacks.h:240
STFF::STFishFinder::GetFWVersion
FF_Error_t GetFWVersion(char *pFWVersion, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Firmware Version string for the connected black box fish finder...
STFF::STFishFinder::GetGainColorOffsets
FF_Error_t GetGainColorOffsets(FF_Frequency_t frequency, uint16_t *pNumColors, uint16_t *pGainColorOffsets, FF_SettingStatus_t *pStatus) const
Getter function to provide the number of colors used when generating the STFF::ImageColumn data...
STFF::STFishFinder::GetHWVersion
FF_Error_t GetHWVersion(char *pHWVersion, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Hardware Version string for the connected black box fish finder...
STFF::STFishFinder::SetTemperatureOffset
FF_Error_t SetTemperatureOffset(FF_TemperatureUnits_t units, int16_t temperatureOffset)
Setter function to specify the Temperature Offset calibration setting for the black box...
STFF::Version
The Version class provides software version information.
Definition: STFF-Version.h:58
STFF::STFishFinder::SetGainColorOffsets
FF_Error_t SetGainColorOffsets(FF_Frequency_t frequency, uint16_t numColors, const uint16_t *pGainColorOffsets)
Setter function to specify the number of colors the API should provide in the STFF::ImageColumn data...
STFF::STFishFinder::SetCallbacks
static FF_Error_t 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 occ...
STFF::STFishFinder::CreateFishFinder
static STFishFinder * CreateFishFinder(FF_Error_t *pError)
Use this function to create an STFishFinder API object once a connection (or session) has been establ...
STFF-Types.h
Header file containing enumerations and simple struct types used in the STFishFinder API...
STFF::ImageColumn
The ImageColumn class is a container for sample data retrieved from a single sonar ping...
Definition: STFF-ImageColumn.h:43
STFF::STFishFinder::Control
FF_Error_t Control(FF_ControlCommand_t command, const void *pParam)
Provides a facility to alter system-related behavior of the black box and API.
STFF::STFishFinder::SetDepthAlarmSettings
FF_Error_t SetDepthAlarmSettings(FF_DepthUnits_t units, uint32_t shallowAlarmSetting, uint32_t deepAlarmSetting)
Setter function to set the Shallow Depth Alarm and Deep Depth Alarm master settings within the black ...
STFF::STFishFinder::GetDepthAlarmState
FF_Error_t 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.
STFF::STFishFinder::StopRecording
FF_Error_t StopRecording()
This function discontinues the recording of the API session that was initiated by a call to StartReco...
STFF::Callback_StreamDataToFF_t
void(* Callback_StreamDataToFF_t)(const STFishFinder *, const char *, uint32_t)
'Stream Data to FishFinder' callback.
Definition: STFF-Callbacks.h:337
STFF::STFishFinder::GetTemperatureOffsetLimits
FF_Error_t GetTemperatureOffsetLimits(FF_TemperatureUnits_t units, int16_t *pMinTempOffset, int16_t *pMaxTempOffset) const
Getter function to provide limits for the parameter to the SetTemperatureOffset() member function...
STFF::STFishFinder::ParseFFInputStream
FF_Error_t ParseFFInputStream(char *pInputStream, uint32_t numBytes)
This function parses and interprets the stream of messages from the black box fish finder...
STFF::Replay
Replay class.
Definition: STFF-Replay.h:48
STFF::STFishFinder::GetDepth
FF_Error_t GetDepth(FF_DepthUnits_t units, FF_DepthData_t *pDepthData) const
Getter function to provide the current Depth data.
FF_ApiStatus_t
FF_ApiStatus_t
API Status selection.
Definition: STFF-Types.h:484
STFF::STFishFinder::SetFishIdSetting
FF_Error_t SetFishIdSetting(FF_Frequency_t frequency, const FF_FishIdSetting_t *pFishIdSetting)
Setter function to specify the Fish ID setting for the black box and the API.
STFF::STFishFinder::GetAutoRangeSetting
FF_Error_t GetAutoRangeSetting(FF_AutoRangeSetting_t *pAutoRange, FF_DepthUnits_t *pUnits, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Auto Range setting.
STFF::STFishFinder::GetProductName
FF_Error_t GetProductName(char *pProductName, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Product Name for the connected black box fish finder.
STFF::STFishFinder::GetSerialNumber
FF_Error_t GetSerialNumber(char *pSerialNumber, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Serial Number of the connected black box fish finder.
STFF::STFishFinder::GetFishIdSetting
FF_Error_t GetFishIdSetting(FF_Frequency_t frequency, FF_FishIdSetting_t *pFishIdSetting, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Fish ID setting.
FF_DataStatus_t
FF_DataStatus_t
Data Status options.
Definition: STFF-Types.h:231
STFF::STFishFinder::CreateFishFinderForPlayback
static STFishFinder * CreateFishFinderForPlayback(const Replay *pPlaybackData, FF_Error_t *pError)
Use this function to create an STFishFinder API object for the purpose of playing back a previously r...
FF_DepthAlarmType_t
FF_DepthAlarmType_t
Depth Alarm Type selection.
Definition: STFF-Types.h:423
FF_Error_t
FF_Error_t
Error codes.
Definition: STFF-Types.h:50
STFF
This is the namespace containing the platform-independent STFishFinder API.
FF_TemperatureUnits_t
FF_TemperatureUnits_t
Temperature Units selection.
Definition: STFF-Types.h:138
STFF::STFishFinder::GetRange
FF_Error_t GetRange(FF_RangeSetting_t *pRangeSetting, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Range setting.
STFF::STFishFinder::SetAutoRangeSetting
FF_Error_t SetAutoRangeSetting(FF_AutoRangeSetting_t autoRangeSetting, FF_DepthUnits_t units)
Setter function to specify the Auto Range setting for the black box and the API.
STFF::STFishFinder::Hello
FF_Error_t Hello()
Initiates communication with the black box fish finder after a connection is established.
STFF::STFishFinder::GetGainOffset
FF_Error_t GetGainOffset(FF_Frequency_t frequency, int16_t *pGainOffset, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Gain Offset setting.
STFF-Version.h
Header file for the STFF::Version class; also contains version macros for the entire STFishFinder API...
STFF::STFishFinder::GetSpeedPulsesPerNauticalMile
FF_Error_t GetSpeedPulsesPerNauticalMile(uint32_t *pSpeedPPNM, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Speed PPNM master setting.
STFF::Callback_FishAlarmTrigger_t
void(* Callback_FishAlarmTrigger_t)(const STFishFinder *, FF_FishData_t)
'Fish Alarm Trigger' callback.
Definition: STFF-Callbacks.h:287
STFF::STFishFinder::SetFrequencyMode
FF_Error_t SetFrequencyMode(FF_FrequencyMode_t frequencyMode)
Setter function to specify the Frequency Mode setting for the black box and the API.
STFF::STFishFinder::GetInputSamplesLimits
FF_Error_t GetInputSamplesLimits(uint16_t *pMinInputSamples, uint16_t *pMaxInputSamples) const
Getter function to provide limits for the parameter to the SetNumInputSamples() member function...
STFF::STFishFinder::GetMaxPossibleDepth
FF_Error_t GetMaxPossibleDepth(FF_Frequency_t frequency, FF_DepthUnits_t units, uint32_t *pMaxDepth, FF_DataStatus_t *pStatus) const
Getter function to provide the maximum possible depth at the specified frequency for the connected bl...
STFF::STFishFinder::~STFishFinder
~STFishFinder()
This is the STFishFinder class destructor.
FF_AutoGainSetting_t
FF_AutoGainSetting_t
Auto Gain setting options.
Definition: STFF-Types.h:380
FF_FishIdSetting_t
Fish ID Setting structure.
Definition: STFF-Types.h:695
FF_RangeSetting_t
Range Setting structure.
Definition: STFF-Types.h:640
STFF::STFishFinder::GetApiVersion
FF_Error_t GetApiVersion(Version *pApiVersion) const
Getter function to provide an STFF::Version object containing version information for the present ins...
STFF::STFishFinder
This is the main class for the STFishFinder API.
Definition: STFF-FishFinder.h:83
FF_ControlCommand_t
FF_ControlCommand_t
Control Command options.
Definition: STFF-Types.h:257
FF_FrequencyMode_t
FF_FrequencyMode_t
Sonar Frequency Mode options.
Definition: STFF-Types.h:314
STFF::STFishFinder::SetSpeedPulsesPerNauticalMile
FF_Error_t SetSpeedPulsesPerNauticalMile(uint32_t speedPPNM)
Setter function to specify the Speed Pulses Per Nautical Mile (PPNM) setting used by the black box to...
STFF::STFishFinder::SilenceDepthAlarm
FF_Error_t 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...
STFF::STFishFinder::GetApiStatus
FF_ApiStatus_t GetApiStatus() const
Returns the status of the STFishFinder API.
STFF::STFishFinder::GetBatteryVoltage
FF_Error_t GetBatteryVoltage(FF_BatteryVoltageData_t *pBatteryVoltageData) const
Getter function to provide the current Battery Voltage data.
STFF::STFishFinder::StartRecording
FF_Error_t StartRecording(Replay *pReplay)
This function enables the recording of an API session.
STFF::STFishFinder::GetTemperatureOffset
FF_Error_t GetTemperatureOffset(FF_TemperatureUnits_t units, int16_t *pTemperatureOffset, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Temperature Offset master setting.
STFF::STFishFinder::CreateSimulatedFishFinder
static STFishFinder * CreateSimulatedFishFinder(FF_Error_t *pError)
Use this function to create an STFishFinder API object that provides simulated data for demonstration...
STFF::Callback_DataItemReceived_t
void(* Callback_DataItemReceived_t)(const STFishFinder *, FF_DataType_t, const void *)
'Data Item Received' callback.
Definition: STFF-Callbacks.h:190
STFF::STFishFinder::GetDepthAlarmSettings
FF_Error_t GetDepthAlarmSettings(FF_DepthUnits_t *pUnits, uint32_t *pShallowAlarm, uint32_t *pDeepAlarm, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Depth Alarm master settings.
STFF::STFishFinder::GetBootloaderVersion
FF_Error_t GetBootloaderVersion(char *pBootloaderVersion, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Bootloader Version string for the connected black box fish finder...
STFF-Replay.h
Header file for the STFF::Replay class.
STFF::STFishFinder::GetGain
FF_Error_t GetGain(FF_Frequency_t frequency, uint16_t *pGainSetting, FF_SettingStatus_t *pStatus) const
Getter function to provide the current Gain setting.
STFF::STFishFinder::GetGainOffsetLimits
FF_Error_t GetGainOffsetLimits(int16_t *pMinOffset, int16_t *pMaxOffset) const
Getter function to provide limits for the parameter to the SetGainOffset() member function...
STFF::STFishFinder::SetRange
FF_Error_t SetRange(const FF_RangeSetting_t *pRangeSetting)
Setter function to "manually" specify the Range setting for the black box and the API...
STFF::STFishFinder::GetGainColorOffsetsLimits
FF_Error_t GetGainColorOffsetsLimits(uint16_t *pNumOffsets, uint16_t *pMinLargestOffset, uint16_t *pMaxLargestOffset) const
Getter function to provide:
FF_TemperatureData_t
Temperature Data structure.
Definition: STFF-Types.h:522
STFF::STFishFinder::GetCompanyName
FF_Error_t GetCompanyName(char *pCompanyName, uint16_t *pLength, FF_DataStatus_t *pStatus) const
Getter function to provide the Company Name for the connected black box fish finder.
FF_SpeedData_t
Speed Data structure.
Definition: STFF-Types.h:545
FF_DepthData_t
Depth Data structure.
Definition: STFF-Types.h:566
STFF::STFishFinder::SetAutoGainSetting
FF_Error_t SetAutoGainSetting(FF_AutoGainSetting_t autoGainSetting)
Setter function to specify the Auto Gain setting for the black box and the API.
STFF-Callbacks.h
Header file containing type definitions for callback functions used in the STFishFinder API...
FF_Frequency_t
FF_Frequency_t
Sonar Frequency options.
Definition: STFF-Types.h:77
FF_FstcSetting_t
FSTC Setting structure.
Definition: STFF-Types.h:658
STFF::STFishFinder::GetSpeedPulsesPerNauticalMileLimits
FF_Error_t GetSpeedPulsesPerNauticalMileLimits(uint32_t *pMinSpeedPPNM, uint32_t *pMaxSpeedPPNM) const
Getter function to provide limits for the parameter to the SetSpeedPulsesPerNauticalMile() member fun...
STFF::STFishFinder::MaxAttributeStringLength
static const uint16_t MaxAttributeStringLength
Maximum size of character strings, including the terminating '\0', provided by certain getter member ...
Definition: STFF-FishFinder.h:95
STFF::STFishFinder::GetRangeLimits
FF_Error_t GetRangeLimits(FF_DepthUnits_t units, uint32_t *pMinRangeDeep, uint32_t *pMaxRangeDeep) const
Getter function to provide limits for the parameter to the SetRange() member function.
FF_AutoRangeSetting_t
FF_AutoRangeSetting_t
Auto Range setting options.
Definition: STFF-Types.h:359
STFF::STFishFinder::GetNumInputSamples
FF_Error_t GetNumInputSamples(uint16_t *pNumInputSamples, FF_SettingStatus_t *pStatus) const
Getter function to provide the current setting for the number of samples that will be provided by the...
STFF::STFishFinder::SetGainOffset
FF_Error_t SetGainOffset(FF_Frequency_t frequency, int16_t gainOffset)
Setter function to specify the Gain Offset setting for the black box.
STFF::STFishFinder::SetGain
FF_Error_t SetGain(FF_Frequency_t frequency, uint16_t gainSetting)
Setter function to "manually" specify the Gain setting for the black box.