Getters for Attributes

Functions that retrieve information about unchangeable attributes of the connected black box fish finder. More...

Functions
FF_Error_t	STFF::STFishFinder::GetApiVersion (Version *pApiVersion) const
	Getter function to provide an STFF::Version object containing version information for the present instance of the STFishFinder API. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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. More...
FF_Error_t	STFF::STFishFinder::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 black box fish finder. More...

Detailed Description

Functions that retrieve information about unchangeable attributes of the connected black box fish finder.

These are member functions of the STFishFinder class.

See also

Getters for Local Settings

Getters for Master Settings

Getters for Limits

Getters for Data

Function Documentation

STFF::STFishFinder::GetApiVersion

(

Version *

pApiVersion

)

const

#include <STFF-FishFinder.h>

Getter function to provide an STFF::Version object containing version information for the present instance of the STFishFinder API.

Parameters

[out]

pApiVersion

Pointer to an STFF::Version object into which this function will store the version information. If this parameter is a null pointer, then nothing will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Example:

using namespace STFF;

Version apiVersion;
FF_Error_t error;

error = GetApiVersion (&apiVersion);

if (error == FF_ERR_NO_ERROR) {
    char apiVersionBuf [Version::MaxVersionStringLength];
    apiVersion.GetVersionString (apiVersionBuf);

    // apiVersionBuf now contains a
    // null-terminated string containing the
    // STFishFinder API version.
}

See also

STFF::Version

STFF::STFishFinder::GetBootloaderVersion	(	char *	pBootloaderVersion,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Bootloader Version string for the connected black box fish finder.

The Bootloader Version is a read-only attribute of the black box. There is no corresponding setter function.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 10 characters.

Parameters

[out]	pBootloaderVersion	Pointer to buffer into which this function will store a null-terminated C-style string containing the Bootloader Version. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided bootloader version value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pBootloaderVersion argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pBootloaderVersion argument.

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

Todo:

Redefine the GetBootloaderVersion() function to return a STFF::Version object instead of a string

STFF::STFishFinder::GetCompanyName	(	char *	pCompanyName,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Company Name for the connected black box fish finder.

The Company Name string contains the name of the brand or manufacturer of the black box hardware. The Company Name is a read-only attribute of the black box. There is no corresponding setter function.

Remarks

The Company Name for the Pocket Marine Fishing Bug 20 is "Pocket Marine, LLC". Other Company Names will be assigned to FE2 derivatives as needed.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 40 characters.

Parameters

[out]	pCompanyName	Pointer to buffer into which this function will store a null-terminated C-style string containing the Company Name. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided Company Name value (valid/invalid, simulated, or log playback).

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pCompanyName argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pMfrName argument.

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

STFF::STFishFinder::GetFWVersion	(	char *	pFWVersion,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Firmware Version string for the connected black box fish finder.

The Firmware Version is a read-only attribute of the black box. There is no corresponding setter function.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 10 characters.

Parameters

[out]	pFWVersion	Pointer to buffer into which this function will store a null-terminated C-style string containing the Firmware Version. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided firmware version value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pFWVersion argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pFWVersion argument.

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

Todo:

Redefine the GetFWVersion() function to return a STFF::Version object instead of a string

STFF::STFishFinder::GetHWVersion	(	char *	pHWVersion,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Hardware Version string for the connected black box fish finder.

The Hardware Version is a read-only attribute of the black box. There is no corresponding setter function.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 10 characters.

Parameters

[out]	pHWVersion	Pointer to buffer into which this function will store a null-terminated C-style string containing the Hardware Version. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided hardware version value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pHWVersion argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pHWVersion argument.

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

STFF::STFishFinder::GetMaxPossibleDepth	(	FF_Frequency_t	frequency,
		FF_DepthUnits_t	units,
		uint32_t *	pMaxDepth,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the maximum possible depth at the specified frequency for the connected black box fish finder.

The maximum possible depth is a read-only attribute of the black box. There is no corresponding setter function.

Note

This value represents the deepest depth to which the sounder might "look" when pinging at the specified frequency. It does not represent the capability of the hardware to actually achieve the detection of a bottom echo at that depth.

Parameters

[in]	frequency	The frequency selection for which the maximum possible depth value is requested.
[in]	units	The depth units in which the maximum possible depth value will be reported.
[out]	pMaxDepth	Pointer to location into which this function will store the "maximum possible depth" value. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided maximum possible depth value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_INVALID_FREQUENCY	if the provided frequency parameter has an invalid value (see FF_Frequency_t)
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the provided units parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

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

Todo:

The GetMaxPossibleDepth() function should probably be deprecated.

STFF::STFishFinder::GetProductName	(	char *	pProductName,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Product Name for the connected black box fish finder.

The Product Name is a read-only attribute of the black box. There is no corresponding setter function.

Remarks

The Product Name for the Pocket Marine Fishing Bug 20 is "Fishing Bug 20". Other Product Names will be assigned to FE2 derivatives as needed.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 25 characters.

Parameters

[out]	pProductName	Pointer to buffer into which this function will store a null-terminated C-style string containing the Product Name. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided product name value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pProductName argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pProductName argument.

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

See also

GetProductId

STFF::STFishFinder::GetSerialNumber	(	char *	pSerialNumber,
		uint16_t *	pLength,
		FF_DataStatus_t *	pStatus
	)		const

#include <STFF-FishFinder.h>

Getter function to provide the Serial Number of the connected black box fish finder.

The Serial Number is a read-only attribute of the black box. There is no corresponding setter function.

Note

When displaying this value in the GUI, it is suggested to provide room on the screen to display a string of at least 15 characters.

Parameters

[out]	pSerialNumber	Pointer to buffer into which this function will store a null-terminated C-style string containing the Serial Number. The number of characters written, including the terminating '\0', will never exceed the value of STFF::STFishFinder::MaxAttributeStringLength. If this parameter is a null pointer, then nothing will be written to the buffer.
[out]	pLength	Pointer to location into which this function will store the number of characters in the string. The value stored does not account for the terminating '\0'. If this parameter is a null pointer, then no value will be stored.
[out]	pStatus	pointer to a location that will be written with the status of the provided serial number value (valid/invalid, simulated, or log playback). If this parameter is a null pointer, then no value will be stored.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Note

To determine the length of the buffer required to contain the string, call this function twice: In the first call set the pSerialNumber argument to null and read the length from the location provided to the pLength argument. When allocating the buffer, be sure to add 1 to the buffer length to account for the terminating '\0'. Then call this function a second time, providing the address of the buffer to the pSerialNumber argument.

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