Functions to query the current license state. More...

Macros
#define	LI_COMMONVISIONBLOX 1
	Image Manager licensed through CVB-type dongle. More...

#define	LI_CVB11_FP_LICENSE 8
	Image Manager and Foundation Package licensed through CVB License engine.

#define	LI_CVB11_IM_LICENSE 7
	Image Manager licensed through CVB License engine.

#define	LI_CVC 2
	Image Manager licensed through CVC-type dongle. More...

#define	LI_FOUNDATION_V1 6
	Image Manager licensed through CVB-type dongle with version 1 Foundation license. More...

#define	LI_HARDWARE 5
	Image Manager licensed through other hardware (e.g. node-locked). More...

#define	LI_MINOS 4
	Image Manager licensed through Minos dongle. More...

#define	LI_NOLICENSE 0
	No Image Manager license found.

#define	LI_VISIONBLOX 3
	Image Manager licensed through VisionBlox dongle. More...

Functions
cvbval_t	GetLicenseCount ()
	Returns the number of licenses in the current snapshot. More...

cvblicres_t	GetLicenseInfo ()
	Indicates whether Common Vision Blox has been licensed or not. More...

cvbres_t	GetLicenseInfoEx (cvbval_t Index, cvblicres_t &SerialNumber, cvbbool_t &IsFoundation)
	Accesses one of the licenses in the current snapshot. More...

cvbres_t	GetMagicNumber (size_t Index, char ProviderName, size_t &ProviderNameBufferSize, char ToolID, size_t &ToolIDBufferSize, char *MagicNumber, size_t &MagicNumberBufferSize, cvblicres_t &SerialNumber)
	Retrieve a Magic Number data set from the last snapshot. More...

cvbval_t	GetMagicNumberCount ()
	Gets the total number of Magic Numbers currently available from the last snapshot. More...

cvblicres_t	GetSerialNumber ()
	Returns the serial number of Common Vision Blox. More...

cvbres_t	GetToolMagicNumber (const char ToolID, size_t Index, char ProviderName, size_t &ProviderNameBufferSize, char *MagicNumber, size_t &MagicNumberBufferSize, cvblicres_t &SerialNumber)
	Retrieve a Magic Number data set for a specific tool ID from the last snapshot. More...

cvbval_t	GetToolMagicNumberCount (const char *ToolID)
	Gets the number of Magic Numbers currently available for a specific ToolID from the last snapshot. More...

cvbbool_t	IsSerialNumberAvailable (cvblicres_t SerialNumber)
	Checks if a specific Common Vision Blox serial number is available in the last snapshot. More...

cvbbool_t	IsToolMagicNumberAvailable (const char *ToolID, cvbbool_t IgnoreSerial999)
	Checks if a tool magic number is available for the given ToolID on the last snapshot. More...

cvbres_t	UpdateLicenses ()
	Update the set of license information that can be queried with the GetLicenseCount and GetLicenseInfoEx. More...

cvbres_t	UpdateLicensesDeep ()
	Updates a snapshot of the full set of licensing information currently provided by the Common Vision Blox License infrastructure. More...

Detailed Description

Functions to query the current license state.

When to use #UpdateLicenses and when to use #UpdateLicensesDeep?

You are probably familiar with the approach Common Vision Blox takes for licensing tools like e.g. Minos: A Common Vision Blox serial number is paired with a Common Vision Blox Magic Number, and during runtime the tool verifies - through an undisclosed hashing algorithm - whether the serial number and the Magic Number match, outputting a message and/or limiting its functionality if they don't.

The same approach may be used by programs using Common Vision Blox, making use of the infrastructure provided by Common Vision Blox. All you need in order to implement this is a hashing algorithm. Enter your Magic Number into the License.ini file (e.g. through the Management Console) under a tool ID chosen by you (make sure it doesn't collide with one of the IDs that are already in use). When your tool initializes, use the functions GetToolMagicNumberCount and GetToolMagicNumber to query the available Magic Numbers for your algorithm (note that there may be more than one of them available!) and use GetLicenseCount and GetLicenseInfoEx to retrieve the set of available serial numbers. Once you have gathered that data, check if there is a match between one of the serial numbers and one of the Magic Numbers, and if there is, memorize the serial number for which the match was made.

After that, whenever restricted functionality is being called you can simply use UpdateLicenses and IsSerialNumberAvailable (both operate with only little latency) to make sure that the license (dongle) with the matching serial number is still present.

Macro Definition Documentation

◆ LI_COMMONVISIONBLOX

#define LI_COMMONVISIONBLOX 1

Image Manager licensed through CVB-type dongle.

Deprecated:: Not used anymore.

◆ LI_CVC

#define LI_CVC 2

Image Manager licensed through CVC-type dongle.

Deprecated:: Not used anymore.

◆ LI_FOUNDATION_V1

#define LI_FOUNDATION_V1 6

Image Manager licensed through CVB-type dongle with version 1 Foundation license.

Deprecated:: Not used anymore.

◆ LI_HARDWARE

#define LI_HARDWARE 5

Image Manager licensed through other hardware (e.g. node-locked).

Deprecated:: Not used anymore.

◆ LI_MINOS

#define LI_MINOS 4

Image Manager licensed through Minos dongle.

Deprecated:: Not used anymore.

◆ LI_VISIONBLOX

#define LI_VISIONBLOX 3

Image Manager licensed through VisionBlox dongle.

Deprecated:: Not used anymore.

Function Documentation

◆ GetLicenseCount()

cvbval_t GetLicenseCount ( )

Returns the number of licenses in the current snapshot.

Returns: Number of licenses in the current license snapshot; 0 if no license is available.

See also: See UpdateLicenses to learn more about license snapshots and GetLicenseInfoEx for the actual license information.

◆ GetLicenseInfo()

cvblicres_t GetLicenseInfo ( )

Indicates whether Common Vision Blox has been licensed or not.

Deprecated:: Use UpdateLicenses, GetLicenseCount and GetLicenseInfoEx instead.

Returns

The return value is determined as follows:

if there is no license available, LI_NOLICENSE is returned
if there is at least one license available that serves as a foundation license, LI_CVB11_FP_LICENSE is returned
otherwise, LI_CVB11_IM_LICENSE is returned

◆ GetLicenseInfoEx()

cvbres_t GetLicenseInfoEx	(	cvbval_t	Index,
		cvblicres_t &	SerialNumber,
		cvbbool_t &	IsFoundation
	)

Accesses one of the licenses in the current snapshot.

Note: A SerialNumber 0 is also considered to be a valid license! The Common Vision Blox CameraSuite will always be a serial number 0.

Parameters

[in]	Index	Index of the license to be retrieved (must be in the range [0...GetLicenseCount()[)
[out]	SerialNumber	Variable to receive the serial number of the license at Index.
[out]	IsFoundation	true if the license at Index is also valid for the Common Vision Blox Foundation Package.

Returns: Smaller than zero on error. See ErrorHandling on how to work with error codes.

◆ GetMagicNumber()

cvbres_t GetMagicNumber	(	size_t	Index,
		char *	ProviderName,
		size_t &	ProviderNameBufferSize,
		char *	ToolID,
		size_t &	ToolIDBufferSize,
		char *	MagicNumber,
		size_t &	MagicNumberBufferSize,
		cvblicres_t &	SerialNumber
	)

Retrieve a Magic Number data set from the last snapshot.

The data this function works on may be updated using the UpdateLicensesDeep. The available Magic Number count may be queried using GetMagicNumberCount.

Parameters

[in]	Index	Index of the Magic Number entry to be retrieved. Must be in the range [0, GetMagicNumberCount()[.
[in,out]	ProviderName	Pointer to a buffer to be filled with the string identifying the Magic Number provider from which this entry comes. May be nullptr to query this name's ProviderNameBufferSize.
[in,out]	ProviderNameBufferSize	Size of the ProviderName buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]	ToolID	Pointer to a buffer to be filled with the tool ID string for this Magic Number entry. May be nullptr, in to query this id ToolIDBufferSize.
[in,out]	ToolIDBufferSize	Size of the ToolID buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]	MagicNumber	Pointer to a buffer to be filled with the Magic Number string for this Magic Number entry. May be nullptr, in to query this id MagicNumberBufferSize.
[in,out]	MagicNumberBufferSize	Size of the MagicNumber buffer in bytes. Will receive the required length of the number including nul-termination if MagicNumber is nullptr.
[out]	SerialNumber	Serial number associated with this Magic Number entry. For some Magic Number providers like the WIBU CodeMeter keys it is possible to tell for which Common Vision Blox serial number a Magic Number is intended. In that case the serial number matching this Magic Number entry will be set. In all other cases, this value will be 0.

Returns: Smaller than zero on error. See ErrorHandling on how to work with error codes. If #CVC_ERROR (#CVC_E_MEMORY) is returned, then a string buffer size is insufficient of a given buffer.

See also: GetMagicNumberCount, GetToolMagicNumber, GetToolMagicNumberCount, IsToolMagicNumberAvailable, UpdateLicensesDeep

◆ GetMagicNumberCount()

cvbval_t GetMagicNumberCount ( )

Gets the total number of Magic Numbers currently available from the last snapshot.

Returns the total number of Magic Numbers currently availably on your system. Individual Magic Numbers can be queried using the functions listed under See Also. The data this function works on, can be updated (e.g. when there is the possibility that the available set of Magic Numbers might have changed) using UpdateLicensesDeep.

For a more extensive description on the use case(s) of this function, please refer to the documentation of UpdateLicensesDeep.

Returns: The number of Magic Numbers currently available on this system.

See also: GetMagicNumber, GetToolMagicNumber, GetToolMagicNumberCount, IsToolMagicNumberAvailable, UpdateLicensesDeep

◆ GetSerialNumber()

cvblicres_t GetSerialNumber ( )

Returns the serial number of Common Vision Blox.

Deprecated:: Use UpdateLicenses, GetLicenseCount and GetLicenseInfoEx instead.

Returns: CVB serial number; a value of zero is ambiguous: it can either mean that there is no license or that there is a Common Vision Blox CameraSuite license.

◆ GetToolMagicNumber()

cvbres_t GetToolMagicNumber	(	const char *	ToolID,
		size_t	Index,
		char *	ProviderName,
		size_t &	ProviderNameBufferSize,
		char *	MagicNumber,
		size_t &	MagicNumberBufferSize,
		cvblicres_t &	SerialNumber
	)

Retrieve a Magic Number data set for a specific tool ID from the last snapshot.

The data this function works on may be updated using UpdateLicensesDeep. The available Magic Number count may be queried using GetToolMagicNumberCount.

Parameters

[in]	ToolID	Tool ID for which to retrieve a Magic Number entry.
[in]	Index	Index of the Magic Number entry to be retrieved. Must fall into the range [0, GetToolMagicNumberCount (ToolID)-1.
[in,out]	ProviderName	Pointer to a buffer to be filled with the string identifying the Magic Number provider from which this entry comes. May be nullptr to query this name's ProviderNameBufferSize.
[in,out]	ProviderNameBufferSize	Size of the ProviderName buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]	MagicNumber	Pointer to a buffer to be filled with the Magic Number string for this Magic Number entry. May be nullptr, in to query this id MagicNumberBufferSize.
[in,out]	MagicNumberBufferSize	Size of the MagicNumber buffer in bytes. Will receive the required length of the number including nul-termination if MagicNumber is nullptr.
[out]	SerialNumber	Serial number associated with this Magic Number entry. For some Magic Number providers like the WIBU CodeMeter keys it is possible to tell for which Common Vision Blox serial number a Magic Number is intended. In that case the serial number matching this Magic Number entry will be set. In all other cases, this value will be 0.

Returns: Smaller than zero on error. See ErrorHandling on how to work with error codes. If #CVC_ERROR (#CVC_E_MEMORY) is returned, then a string buffer size is insufficient of a given buffer.

See also: GetMagicNumber, GetMagicNumberCount, GetToolMagicNumberCount, IsToolMagicNumberAvailable, UpdateLicensesDeep

◆ GetToolMagicNumberCount()

cvbval_t GetToolMagicNumberCount ( const char * ToolID )

Gets the number of Magic Numbers currently available for a specific ToolID from the last snapshot.

Returns the total number of Magic Numbers currently availably on your system for the given ToolID. Individual Magic Numbers can be queried using the functions listed under See Also. The data this function works on can be updated (e.g. when there is the possibility that the available set of Magic Numbers might have changed) using UpdateLicensesDeep.

For a more extensive description on the use case(s) of this function, please refer to the documentation of UpdateLicensesDeep.

Parameters

[in] ToolID Tool ID for which to query the number of available Magic Numbers.

Returns: The number of Magic Numbers currently available on this system for the ToolID.

See also: GetMagicNumber, GetMagicNumberCount, GetToolMagicNumber, IsToolMagicNumberAvailable, UpdateLicensesDeep

◆ IsSerialNumberAvailable()

cvbbool_t IsSerialNumberAvailable ( cvblicres_t SerialNumber )

Checks if a specific Common Vision Blox serial number is available in the last snapshot.

Allows for a quick check if a given Common Vision Blox serial number is (still) available on this system. Individual serial numbers can be queried using the function GetLicenseCount and GetLicenseInfoEx. The data this function works on can be updated (e.g. when there is the possibility that the available set of Magic Numbers might have changed) using UpdateLicenses or (slower!) UpdateLicensesDeep.

For a more extensive description on the use case(s) of this function, please refer to the documentation of UpdateLicenses and UpdateLicensesDeep.

Parameters

[in] SerialNumber Serial number to check for.

Returns: true if there is a Common Vision Blox Image Manager license available with the given SerialNumber.

See also: GetLicenseCount, GetLicenseInfoEx, UpdateLicenses, UpdateLicensesDeep,

◆ IsToolMagicNumberAvailable()

cvbbool_t IsToolMagicNumberAvailable	(	const char *	ToolID,
		cvbbool_t	IgnoreSerial999
	)

Checks if a tool magic number is available for the given ToolID on the last snapshot.

Allows for a quick check if there is Magic Number information available at all for the given tool ID. Individual Magic Numbers can be queried using the functions listed under See Also. The data this function works on can be updated (e.g. when there is the possibility that the available set of Magic Numbers might have changed) using UpdateLicensesDeep.

For a more extensive description on the use case(s) of this function, please refer to the documentation of UpdateLicensesDeep.

Parameters

[in]	ToolID	Tool ID for which to query the number of available Magic Numbers.
[in]	IgnoreSerial999	true to ignore those Magic Numbers that are intended for use with the trial licenses; false otherwise.

Returns: true if there is at least one Magic Number available for the given ToolID, false otherwise.

See also: GetMagicNumber, GetMagicNumberCount, GetToolMagicNumber, GetToolMagicNumberCount, IsToolMagicNumberAvailable, UpdateLicensesDeep

◆ UpdateLicenses()

cvbres_t UpdateLicenses ( )

Update the set of license information that can be queried with the GetLicenseCount and GetLicenseInfoEx.

Starting with version 2011 (11.00.000), Common Vision Blox uses a new license concept that allows for multiple serial numbers on a system (i.e. an automatic concatenation of licenses becomes possible). With this new approach, the functions GetLicenseInfo and GetSerialNumber no longer suffice. Instead, a new set of functions has been added that allows for a more detailed query of the license state.

To avoid race conditions, these functions no longer directly query the license providers, but work on a cached snapshot of the license state. UpdateLicenses may be called to update that cache - an operation you should expect to take in the order of 1 to 2 ms.

Returns: Smaller than zero on error. See ErrorHandling on how to work with error codes.

See also: GetLicenseCount, GetLicenseInfoEx, UpdateLicensesDeep

◆ UpdateLicensesDeep()

cvbres_t UpdateLicensesDeep ( )

Updates a snapshot of the full set of licensing information currently provided by the Common Vision Blox License infrastructure.

Unlike UpdateLicenses, which just performs a quick query of the set of currently available serial numbers, this call also updates the Magic Number information.

Note: Although both functions, UpdateLicensesDeep and UpdateLicenses serve a similar purpose, a call to UpdateLicensesDeep can take considerably more time to process than a call to UpdateLicenses due to the higher amount of data that needs to be transferred. This is because UpdateLicenses (together with GetLicenseCount plus GetLicenseInfoEx) only updates a very limited set of information and has been specifically tailored to being called frequently (whenever the caller wants to verify that a dongle is is still available).

: Apart from updating the Magic Number information, a call to UpdateLicensesDeep has the same effect as UpdateLicenses, i.e. it will also update the information returned by GetLicenseCount and GetLicenseInfoEx.

Returns: Smaller than zero on error. See ErrorHandling on how to work with error codes.

See also: GetLicenseCount, GetLicenseInfoEx, GetMagicNumber, GetMagicNumberCount, GetToolMagicNumber, GetToolMagicNumberCount, IsToolMagicNumberAvailable, IsSerialNumberAvailable


Contact Legal Privacy Statement	Copyright © 2023.
	All rights reserved.

Macros

Functions

Detailed Description

When to use #UpdateLicenses and when to use #UpdateLicensesDeep?

Macro Definition Documentation

◆ LI_COMMONVISIONBLOX

◆ LI_CVC

◆ LI_FOUNDATION_V1

◆ LI_HARDWARE

◆ LI_MINOS

◆ LI_VISIONBLOX

Function Documentation

◆ GetLicenseCount()

◆ GetLicenseInfo()

◆ GetLicenseInfoEx()

◆ GetMagicNumber()

◆ GetMagicNumberCount()

◆ GetSerialNumber()

◆ GetToolMagicNumber()

◆ GetToolMagicNumberCount()

◆ IsSerialNumberAvailable()

◆ IsToolMagicNumberAvailable()

◆ UpdateLicenses()

◆ UpdateLicensesDeep()