STFF-Version.h

Go to the documentation of this file.

///
/// @file   STFF-Version.h
///
/// Header file for the STFF::Version class; also contains version macros
/// for the entire STFishFinder API.
///
/// @copyright
/// Copyright (c) 2012-2015 Sifferman Technology, LLC.  All rights reserved.
///

#ifndef STFF_Version_h_
#define STFF_Version_h_

#include <cstdint>


////////////////////////////////////////////////////////////////////////////
//
// STFishFinder API Version Macros
//
////////////////////////////////////////////////////////////////////////////

// The current version info for the STFishFinder API is defined here:

#define     API_VERSION_MAJOR                   0
#define     API_VERSION_MINOR                   1
#define     API_VERSION_PATCH                   0
#define     API_VERSION_PRERELEASE_STRING       ""
#define     API_VERSION_BUILD_METADATA_STRING   ""



////////////////////////////////////////////////////////////////////////////
//
// STFF::Version class declaration
//
////////////////////////////////////////////////////////////////////////////

namespace STFF {

    ////////////////////////////////////////////////////////////////////////////
    /// @class Version
    /// The %Version class provides software version information.
    ///
    /// In the STFishFinder API, instances of the Version class are used to
    /// provide version information for the API itself, and for the bootloader
    /// and firmware in a connected black box fish finder.
    ///
    /// The version data in this class attempts to conform to the
    /// Semantic Versioning Specification v2.0.0; see www.semver.org for an
    /// explanation of how to interpret the meaning of a version number
    /// change.
    ///
    /// @see        STFishFinder::GetApiVersion()
    /// @see        STFishFinder::GetFirmwareVersion()
    /// @see        STFishFinder::GetBootloaderVersion()
    ///
    class Version {

    public:

        /// @var MaxStringLength
        ///
        /// Maximum size of character strings, including the terminating '\\0',
        /// provided by certain Version getter member functions.
        /// In the unlikely event a string were to exceed this length, it will
        /// be truncated to this length by the getter function before storing
        /// to the caller's buffer.
        ///
        static const uint16_t MaxStringLength = 256;


        /// @fn GetMajor
        ///
        /// Provides the major version number, e.g., 1 for "1.2.3".
        ///
        /// @returns    the major version number
        ///
        uint32_t GetMajor () const;


        /// @fn GetMinor
        ///
        /// Provides the minor version number, e.g., 2 for "1.2.3".
        ///
        /// @returns    the minor version number
        ///
        uint32_t GetMinor () const;


        /// @fn GetPatch
        ///
        /// Provides the patch version number, e.g., 3 for "1.2.3".
        ///
        /// @returns    the patch version number
        ///
        uint32_t GetPatch () const;


        /// @fn GetPreReleaseString
        ///
        /// Provides the pre-release string component of the version.
        ///
        /// @param[out] pPreReleaseString
        ///             Pointer to buffer into which this function will store
        ///             a null-terminated C-style string containing the
        ///             pre-release component of the version.
        ///             The number of characters written, including the
        ///             terminating '\\0', will never exceed the value of
        ///             Version::MaxStringLength.
        ///             If this parameter is a null pointer,
        ///             then nothing will be written to the buffer.
        ///
        /// @param[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.
        ///
        /// @returns    void
        ///
        /// @note       The provided string does not include the hyphen ("-")
        ///             prefix to the pre-release string.
        ///
        /// @see        MaxStringLength
        ///
        void GetPreReleaseString (char *pPreReleaseString, uint16_t *pLength) const;


        /// @fn GetBuildMetadataString
        ///
        /// Provides the build metadata component of the version.
        ///
        /// @param[out] pBuildMetadata
        ///             Pointer to buffer into which this function will store
        ///             a null-terminated C-style string containing the
        ///             build metadata component of the version.
        ///             The number of characters written, including the
        ///             terminating '\\0', will never exceed the value of
        ///             Version::MaxStringLength.
        ///             If the @p pBuildMetadata parameter is a null pointer,
        ///             then nothing will be written to the buffer.
        ///
        /// @param[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.
        ///
        /// @returns    void
        ///
        /// @note       The returned string does not include the ("+")
        ///             prefix to the build metadata string.
        ///
        /// @see        MaxStringLength
        ///
        void GetBuildMetadataString (char *pBuildMetadata, uint16_t *pLength) const;

        
        /// @fn GetVersionString
        ///
        /// Provides the full version number as a string,
        /// e.g., "1.2.3-prerelease+buildmetadata".
        ///
        /// @param[out] pVersion
        ///             Pointer to buffer into which this function will store
        ///             a null-terminated C-style string containing the
        ///             entire version string.
        ///             The number of characters written, including the
        ///             terminating '\\0', will never exceed the value of
        ///             Version::MaxStringLength.
        ///             If the @p pVersion parameter is a null pointer,
        ///             then nothing will be written to the buffer.
        ///
        /// @param[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.
        ///
        /// @returns    void
        ///
        /// @see        MaxStringLength
        ///
        void GetVersionString (char *pVersion, uint16_t *pLength) const;


        /// @fn IsAtLeast (const Version *) const
        ///
        /// Compares a provided version against the actual version.
        /// Returns true if the actual version is greater than or equal to
        /// the provided version.
        ///
        /// @param[in]  pCompareVersion
        ///             pointer to Version object containing the version
        ///             to be compared against
        ///
        /// @retval     true
        ///             if the current API version >= *pCompareVersion.
        ///
        /// @retval     false otherwise
        ///
        /// @note       The precedence rules for the comparison operation
        ///             follow the conventions of Semantic Versioning v2.0.0,
        ///             described at www.semver.org.
        ///
        /// @note       The build metadata field is not considered when
        ///             comparing precedence between versions.
        ///
        bool IsAtLeast (const Version *pCompareVersion) const;


        /// @fn IsAtLeast (uint32_t, uint32_t, uint32_t, const char*) const
        ///
        /// Compares a provided version against the actual version.
        /// Returns true if the actual version is greater than or equal to
        /// the provided version.
        ///
        /// @param[in]  major
        ///             the major version number to be compared,
        ///             e.g., 1 for "1.2.3"
        ///
        /// @param[in]  minor
        ///             the minor version number to be compared,
        ///             e.g., 2 for "1.2.3"
        ///
        /// @param[in]  patch
        ///             the patch version number to be compared,
        ///             e.g., 3 for "1.2.3"
        ///
        /// @param[in]  pPreRelease
        ///             pointer to a buffer containing a null-terminated
        ///             C-style string representing the pre-release version
        ///             field to be compared.
        ///             If this parameter is null, then the pre-release string
        ///             is regarded as an empty string.
        ///
        /// @retval     true
        ///             if the current API version >= (major.minor.patch-prerelease_version).
        ///
        /// @retval     false otherwise
        ///
        /// @note       The precedence rules for the comparison operation
        ///             follow the conventions of Semantic Versioning v2.0.0,
        ///             described at www.semver.org.
        ///
        /// @note       The build metadata field is not considered when
        ///             comparing precedence between versions.
        ///
        bool IsAtLeast (uint32_t major,
                        uint32_t minor,
                        uint32_t patch,
                        const char* pPreRelease = 0) const;


#if 0
        /// @fn GetCopyrightMessage
        ///
        /// Provides the Copyright Message for the associated software.
        ///
        /// @param[out] pCopyrightMessage
        ///             Pointer to buffer into which this function will store
        ///             a null-terminated C-style string containing the
        ///             copyright string.
        ///             To prevent the possibility of a buffer overrun,
        ///             ensure the provided buffer is at least
        ///             MaxCopyrightStringLength bytes long.
        ///             If the @p pCopyrightMessage parameter is a null pointer,
        ///             then nothing will be written to the buffer.
        ///
        /// @returns    void
        ///
        void GetCopyrightMessage (char *pCopyrightMessage) const;


        /// @var MaxCopyrightStringLength
        ///
        /// Static const var that contains the maximum possible length
        /// of the character string provided by function
        /// GetCopyrightMessage(), including the terminating \\0.
        /// This value can be used to statically allocate a buffer that is
        /// large enough to contain any string that might be provided by
        /// GetCopyrightMessage().
        ///
        /// Example:
        /// @code
        ///             char copyright [MaxCopyrightStringLength];
        ///             GetCopyrightMessage (copyright);
        /// @endcode
        ///
        /// @see        GetCopyrightMessage()
        ///
        static constexpr uint32_t MaxCopyrightStringLength;
#endif

        
        /// @fn Version (uint32_t, uint32_t, uint32_t, const char*, uint32_t, const char*, uint32_t)
        ///
        /// Constructor for the Version class.
        ///
        /// @param[in]  major
        ///             the major version number,
        ///             e.g., 1 for "1.2.3"
        ///
        /// @param[in]  minor
        ///             the minor version number,
        ///             e.g., 2 for "1.2.3"
        ///
        /// @param[in]  patch
        ///             the patch version number,
        ///             e.g., 3 for "1.2.3"
        ///
        /// @param[in]  preReleaseString
        ///             pointer to a buffer containing a C-style string
        ///             representing the pre-release field of
        ///             the version.
        ///             If this parameter is null, then the pre-release string
        ///             is regarded as an empty string.
        ///
        /// @param[in]  preReleaseLength
        ///             number of characters in @p preReleaseString.
        ///             
        /// @param[in]  buildMetadataString
        ///             pointer to a buffer containing a C-style string
        ///             representing the build metadata field of
        ///             the version.
        ///             If this parameter is null, then the pre-release string
        ///             is regarded as an empty string.
        ///
        /// @param[in]  buildMetadataLength
        ///             number of characters in @p buildMetadataString.
        ///
        /// @returns    N/A
        ///
        /// @see        ~Version ()
        ///
        Version (uint32_t   major,
                 uint32_t   minor,
                 uint32_t   patch,
                 const char *preReleaseString,
                 uint32_t   preReleaseLength,
                 const char *buildMetadataString,
                 uint32_t   buildMetadataLength);


        /// @fn Version (const Version &)
        ///
        /// Copy constructor for the Version class.
        ///
        Version (const Version &);


        /// @fn Version &operator= (const Version &)
        ///
        /// Assignment operator for the Version class.
        ///
        Version &operator= (const Version &);
        
        
        /// @fn ~Version ()
        ///
        /// Destructor for the Version class.
        ///
        /// @see Version (uint32_t, uint32_t, uint32_t, const char*, uint32_t, const char*, uint32_t)        
        ///
        ~Version ();

        
    private:

        friend class STFishFinder;

        // Default ctor is inaccessible
        Version ();

        class impl;
        impl *m_pimpl;

    };  // class Version

}       // namespace STFF

#endif  // defined (STFF_Version_h_)