Image Manager (CVCImg.dll) 14.1
License Queries

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:

◆ 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]IndexIndex of the license to be retrieved (must be in the range [0...GetLicenseCount()[)
[out]SerialNumberVariable to receive the serial number of the license at Index.
[out]IsFoundationtrue if the license at Index is also valid for the Common Vision Blox Foundation Package.
Returns
Smaller than zero on error. See Error Handling 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]IndexIndex of the Magic Number entry to be retrieved. Must be in the range [0, GetMagicNumberCount()[.
[in,out]ProviderNamePointer 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]ProviderNameBufferSizeSize of the ProviderName buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]ToolIDPointer 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]ToolIDBufferSizeSize of the ToolID buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]MagicNumberPointer 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]MagicNumberBufferSizeSize of the MagicNumber buffer in bytes. Will receive the required length of the number including nul-termination if MagicNumber is nullptr.
[out]SerialNumberSerial 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 Error Handling 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]ToolIDTool ID for which to retrieve a Magic Number entry.
[in]IndexIndex of the Magic Number entry to be retrieved. Must fall into the range [0, GetToolMagicNumberCount (ToolID)-1.
[in,out]ProviderNamePointer 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]ProviderNameBufferSizeSize of the ProviderName buffer in bytes. Will receive the required length of the name including nul-termination if ProviderName is nullptr.
[in,out]MagicNumberPointer 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]MagicNumberBufferSizeSize of the MagicNumber buffer in bytes. Will receive the required length of the number including nul-termination if MagicNumber is nullptr.
[out]SerialNumberSerial 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 Error Handling 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]ToolIDTool 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]SerialNumberSerial 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]ToolIDTool ID for which to query the number of available Magic Numbers.
[in]IgnoreSerial999true 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 Error Handling 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 Error Handling on how to work with error codes.
See also
GetLicenseCount, GetLicenseInfoEx, GetMagicNumber, GetMagicNumberCount, GetToolMagicNumber, GetToolMagicNumberCount, IsToolMagicNumberAvailable, IsSerialNumberAvailable