sbgVersion.h File Reference

Helper methods and definitions used to handle version. More...

#include "../sbgDefines.h"
#include "../sbgErrorCodes.h"
#include "../sbgTypes.h"
#include <stdbool.h>

Include dependency graph for sbgVersion.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_SbgVersion

Macros
#define	SBG_VERSION_BASIC(major, minor, rev, build)
#define	SBG_VERSION_SOFT_SCHEME   (0x00000001u << 31)
#define	SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)
#define	SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)
#define	SBG_VERSION_SOFT_SCHEME_MAJOR_MASK   (0x3F)
#define	SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT   (22)
#define	SBG_VERSION_SOFT_SCHEME_MINOR_MASK   (0x3F)
#define	SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT   (16)
#define	SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK   (0x07)
#define	SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)
#define	SBG_VERSION_SOFTWARE(major, minor, build, qualifier)

Typedefs
typedef struct _SbgVersion	SbgVersion
typedef enum _SbgVersionCmpThresold	SbgVersionCmpThresold
typedef enum _SbgVersionQualifier	SbgVersionQualifier

Enumerations
enum	_SbgVersionCmpThresold {   SBG_VERSION_CMP_THRESOLD_MAJOR = 0, SBG_VERSION_CMP_THRESOLD_MINOR = 1, SBG_VERSION_CMP_THRESOLD_REVISION = 2, SBG_VERSION_CMP_THRESOLD_BUILD = 3,   SBG_VERSION_CMP_THRESOLD_QUALIFIER = 4 }
enum	_SbgVersionQualifier {   SBG_VERSION_QUALIFIER_DEV = 0, SBG_VERSION_QUALIFIER_ALPHA = 1, SBG_VERSION_QUALIFIER_BETA = 2, SBG_VERSION_QUALIFIER_RC = 3,   SBG_VERSION_QUALIFIER_STABLE = 4, SBG_VERSION_QUALIFIER_HOT_FIX = 5 }

Functions
	SBG_DEPRECATED (SBG_INLINE uint32 SBG_VERSION(uint8 major, uint8 minor, uint8 rev, uint8 build))
	SBG_DEPRECATED (SBG_INLINE uint8 SBG_VERSION_GET_MAJOR(uint32 encodedVersion))
SBG_INLINE uint32	SBG_VERSION (uint8 major, uint8 minor, uint8 rev, uint8 build)
SBG_INLINE uint8	SBG_VERSION_GET_BUILD (uint32 encodedVersion)
SBG_INLINE uint8	SBG_VERSION_GET_MAJOR (uint32 encodedVersion)
SBG_INLINE uint8	SBG_VERSION_GET_MINOR (uint32 encodedVersion)
SBG_INLINE uint8	SBG_VERSION_GET_REV (uint32 encodedVersion)
int32	sbgVersionCompare (const SbgVersion *pVersionA, const SbgVersion *pVersionB, SbgVersionCmpThresold thresold)
SBG_INLINE int32	sbgVersionCompareEncoded (uint32 versionA, uint32 versionB, SbgVersionCmpThresold thresold)
void	sbgVersionDecode (uint32 encodedVersion, SbgVersion *pVersionInfo)
uint32	sbgVersionEncode (const SbgVersion *pVersionInfo)
SbgErrorCode	sbgVersionFromString (const char *pVersionStr, SbgVersion *pVersionInfo)
SbgErrorCode	sbgVersionFromStringEncoded (const char *pVersionStr, uint32 *pVersion)
SBG_INLINE bool	sbgVersionIsUsingSoftwareScheme (uint32 encodedVersion)
SbgErrorCode	sbgVersionToString (const SbgVersion *pVersionInfo, char *pBuffer, uint32 sizeOfBuffer)
SbgErrorCode	sbgVersionToStringEncoded (uint32 version, char *pBuffer, uint32 sizeOfBuffer)

Detailed Description

Helper methods and definitions used to handle version.

Author

SBG Systems (Raphael Siryani)

Date

23 April 2015

Version information is stored within a single uint32. There are two different versions schemes to better handle software revisions and file format / hardware ones.

Software version are only used for firmware and software. This versions is defined as a <Major>.<Minor>.<Build>-<Qualifier> for example: 1.3.1845-RC Major and Minor can range from 0 to 63. Build is an uint16 ranging from 0 to 65535. Qualifier is an enum encoded on 3 bits.

Basic version is used for hardware or file formats and is the legacy one for software. This versions is defined as a <Major>.<Minor>.<Revision>.<Build> Each element is stored in an uint8. The Major version should NEVER go above 31

Copyright Notice

Copyright (C) 2007-2015, SBG Systems SAS. All rights reserved.

This source code is intended for use only by SBG Systems SAS and those that have explicit written permission to use it from SBG Systems SAS.

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

Definition in file sbgVersion.h.

Macro Definition Documentation

#define SBG_VERSION_BASIC	(		major,
			minor,
			rev,
			build
	)

Value:

(       (((uint32)(major)) << 24)       |               \
                                                                                                                                                (((uint32)(minor)) << 16)       |               \
                                                                                                                                                (((uint32)(rev)) << 8)          |               \
                                                                                                                                                (((uint32)(build)))                     )

Compile a version number using the basic scheme based on major, minor, revision and build information

Parameters

[in]	maj	The major version between 0 to 127.
[in]	min	The minor version between 0 to 255.
[in]	rev	The revision version between 0 to 255.
[in]	build	The build number between 0 to 255.

Returns

The encoded version number.

Definition at line 121 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME   (0x00000001u << 31)

Set to 1 to indicate a version number that uses the software scheme. Set to 0 means a basic version scheme.

Definition at line 52 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)

Mask used to keep only the build version field.

Definition at line 63 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)

Bitshift used to get the build version field.

Definition at line 64 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MAJOR_MASK   (0x3F)

Mask used to keep only the major version field.

Definition at line 57 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT   (22)

Bitshift used to get the major version field.

Definition at line 58 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MINOR_MASK   (0x3F)

Mask used to keep only the minor version field.

Definition at line 60 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT   (16)

Bitshift used to get the minor version field.

Definition at line 61 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK   (0x07)

Mask used to keep only the version qualifier enum.

Definition at line 54 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)

Bitshift to apply to get the qualifier enum.

Definition at line 55 of file sbgVersion.h.

#define SBG_VERSION_SOFTWARE	(		major,
			minor,
			build,
			qualifier
	)

Value:

(       SBG_VERSION_SOFT_SCHEME |                                                                                                                                                                               \
                                                                                                                                                ((((uint32)(qualifier)) & SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK) << SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT) | \
                                                                                                                                                ((((uint32)(major)) & SBG_VERSION_SOFT_SCHEME_MAJOR_MASK) << SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT)               |               \
                                                                                                                                                ((((uint32)(minor)) & SBG_VERSION_SOFT_SCHEME_MINOR_MASK) << SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT)               |               \
                                                                                                                                                ((((uint32)(build)) & SBG_VERSION_SOFT_SCHEME_BUILD_MASK) << SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT)               )

Compile a version number using the software scheme based on major, minor, build, qualifier.

Parameters

[in]	major	The major version between 0 to 63.
[in]	minor	The major version between 0 to 63.
[in]	build	The major version between 0 to 65535.
[in]	qualifier	The version qualifier within the SbgVersionQualifier enum.

Returns

The encoded version number.

Definition at line 134 of file sbgVersion.h.

Typedef Documentation

typedef struct _SbgVersion SbgVersion

This structure contains all the fields provided by a version number. It handles both basic and software version numbers.

typedef enum _SbgVersionCmpThresold SbgVersionCmpThresold

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

typedef enum _SbgVersionQualifier SbgVersionQualifier

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

Enumeration Type Documentation

enum _SbgVersionCmpThresold

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

Enumerator
SBG_VERSION_CMP_THRESOLD_MAJOR	Compare only the major field.
SBG_VERSION_CMP_THRESOLD_MINOR	Compare the major and minor fields.
SBG_VERSION_CMP_THRESOLD_REVISION	Compare the major, minor and revision fields (only for basic versions).
SBG_VERSION_CMP_THRESOLD_BUILD	Compare the major, minor, revision and build fields.
SBG_VERSION_CMP_THRESOLD_QUALIFIER	Compare the major, minor, revision, build and qualifier fields (only for software scheme).

Definition at line 86 of file sbgVersion.h.

enum _SbgVersionQualifier

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

Enumerator
SBG_VERSION_QUALIFIER_DEV	Development only version or pre-alpha. Customer shouldn't get this version qualifier.
SBG_VERSION_QUALIFIER_ALPHA	Alpha version, missing features, can be unstable and could cause crashes or data loss. API can still change.
SBG_VERSION_QUALIFIER_BETA	Beta version, features are freezed, can be unstable and could cause crashes or data loss. API shouldn't change.
SBG_VERSION_QUALIFIER_RC	Release Candidate, features are freezed, with no known bug. API is freezed.
SBG_VERSION_QUALIFIER_STABLE	Stable release, the version is the standard delivered one.
SBG_VERSION_QUALIFIER_HOT_FIX	Hot fixes were applied on a stable release. It should be bug fixes. This qualifier is temporary as the version should return to stable release as soon as the test procedure has been performed.

Definition at line 71 of file sbgVersion.h.

Function Documentation

SBG_DEPRECATED

(

SBG_INLINE uint32

SBG_VERSIONuint8 major, uint8 minor, uint8 rev, uint8 build

)

Define all these methods as deprecated.

SBG_DEPRECATED

(

SBG_INLINE uint8

SBG_VERSION_GET_MAJORuint32 encodedVersion

)

SBG_INLINE uint32 SBG_VERSION	(	uint8	major,
		uint8	minor,
		uint8	rev,
		uint8	build
	)

DEPRECATED macro, please update your code Compile a version number using the basic scheme based on major, minor, revision and build information

Parameters

[in]	maj	The major version between 0 to 127.
[in]	min	The minor version between 0 to 255.
[in]	rev	The revision version between 0 to 255.
[in]	build	The build number between 0 to 255.

Returns

The encoded version number.

Definition at line 291 of file sbgVersion.h.

SBG_INLINE uint8 SBG_VERSION_GET_BUILD

(

uint32

encodedVersion

)

DEPRECATED method, please update your code. Extract a basic version scheme using legacy methods.

Parameters

[in]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 368 of file sbgVersion.h.

SBG_INLINE uint8 SBG_VERSION_GET_MAJOR

(

uint32

encodedVersion

)

DEPRECATED method, please update your code. Extract a basic version scheme using legacy methods.

Parameters

[in]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 305 of file sbgVersion.h.

SBG_INLINE uint8 SBG_VERSION_GET_MINOR

(

uint32

encodedVersion

)

DEPRECATED method, please update your code. Extract a basic version scheme using legacy methods.

Parameters

[in]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 326 of file sbgVersion.h.

SBG_INLINE uint8 SBG_VERSION_GET_REV

(

uint32

encodedVersion

)

DEPRECATED method, please update your code. Extract a basic version scheme using legacy methods.

Parameters

[in]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 347 of file sbgVersion.h.

int32 sbgVersionCompare	(	const SbgVersion *	pVersionA,
		const SbgVersion *	pVersionB,
		SbgVersionCmpThresold	thresold
	)

Compare two version information structures and return if the version A is greater, less or equal than the version B. The computation is roughly result = version A - version B We can define how far we will check if the version A is greater than the version B. For example, we can only check the major or major and minor fields.

Parameters

[in]	pVersionA	The first version to compare.
[in]	pVersionB	The second version to compare.
[in]	thresold	The comparaison thresold to know if we are checking the major, minor, revision, build, ...

Returns

A positive value if the version A is greater than B, a negative one if version A is less than B and 0 if the two versions are the same (according to the thresold).

Definition at line 124 of file sbgVersion.c.

SBG_INLINE int32 sbgVersionCompareEncoded	(	uint32	versionA,
		uint32	versionB,
		SbgVersionCmpThresold	thresold
	)

Compare two encoded versions and return if the version A is greater, less or equal than the version B. The computation is roughly result = version A - version B We can define how far we will check if the version A is greater than the version B. For example, we can only check the major or major and minor fields.

Parameters

[in]	versionA	The first compiled version to compare.
[in]	versionB	The second compiled version to compare.
[in]	thresold	The comparaison thresold to know if we are checking the major, minor, revision, build, ...

Returns

A positive value if the version A is greater than B, a negative one if version A is less than B and 0 if the two versions are the same (according to the thresold).

Definition at line 208 of file sbgVersion.h.

void sbgVersionDecode	(	uint32	encodedVersion,
		SbgVersion *	pVersionInfo
	)

Fill a SbgVersion structure based on an uint32 that stores the 'compiled' version information.

Parameters

[in]	encodedVersion	The version information stored within a uint32.
[out]	pVersionInfo	Pointer on an allocated SbgVersion structure to fill.

Definition at line 13 of file sbgVersion.c.

uint32 sbgVersionEncode

(

const SbgVersion *

pVersionInfo

)

Construct a uint32 containing a version information based on a SbgVersion structure.

Parameters

[in]

pVersionInfo

Pointer on a read only version structure to encode.

Returns

The encoded version information on an uint32 or 0 if an error has occurred.

Definition at line 70 of file sbgVersion.c.

SbgErrorCode sbgVersionFromString	(	const char *	pVersionStr,
		SbgVersion *	pVersionInfo
	)

Convert a human readable string to a version structure.

Parameters

[in]	pVersionStr	The string containing the version to convert.
[out]	pVersionInfo	Pointer to a version structure to store the parsed version info.

Returns

SBG_NO_ERROR if the version information has been converted from a string.

Definition at line 351 of file sbgVersion.c.

SbgErrorCode sbgVersionFromStringEncoded	(	const char *	pVersionStr,
		uint32 *	pVersion
	)

Convert an encoded version number to a human readable string.

Parameters

[in]	pVersionStr	The string containing the version to convert.
[out]	pVersion	Returned encoded version value parsed from the string.

Returns

SBG_NO_ERROR if the version information has been converted from a string.

Definition at line 472 of file sbgVersion.c.

SBG_INLINE bool sbgVersionIsUsingSoftwareScheme

(

uint32

encodedVersion

)

Returns true if this encoded version number is using a software scheme.

Parameters

[in]

encodedVersion

The encoded version number to test stored in a uint32.

Returns

true if the version number is using a software scheme.

Definition at line 167 of file sbgVersion.h.

SbgErrorCode sbgVersionToString	(	const SbgVersion *	pVersionInfo,
		char *	pBuffer,
		uint32	sizeOfBuffer
	)

Convert a version information to a human readable string.

Parameters

[in]	pVersionInfo	Pointer on a read only version structure to convert to a human readable string.
[out]	pBuffer	Buffer to store the version as a human readable null terminated string.
[in]	sizeOfBuffer	Maximum buffer size including the null terminated char.

Returns

SBG_NO_ERROR if the version information has been converted to a string. SBG_BUFFER_OVERFLOW is the buffer isn't big enough to store the converted version string.

Definition at line 229 of file sbgVersion.c.

SbgErrorCode sbgVersionToStringEncoded	(	uint32	version,
		char *	pBuffer,
		uint32	sizeOfBuffer
	)

Convert an encoded version number to a human readable string.

Parameters

[in]	version	Encoded version value to to convert to a human readable string.
[out]	pBuffer	Buffer to store the version as a human readable null terminated string.
[in]	sizeOfBuffer	Maximum buffer size including the null terminated char.

Returns

SBG_NO_ERROR if the version information has been converted to a string. SBG_BUFFER_OVERFLOW is the buffer isn't big enough to store the converted version string.

Definition at line 326 of file sbgVersion.c.