<< Click here to display Table of Contents >> Navigation: »No topics above this level«

CmGetBoxContents2

Contents

Description

This function returns the entries of a CmContainer.

Syntax

int CMAPIENTRY CmGetBoxContents2(HCMSysEntry hcmse, CMULONG flCtrl, CMULONG ulFirmCode, CMBOXINFO *pcmBoxInfo, CMBOXENTRY2 *pcmBoxEntry, CMUINT cbBoxEntry)

Parameter

•hcmse contains a handle opened by CmAccess2 (can be Box Access, Entry Access or Subsystem Access).

•flCtrl contains one of the following commands:

•CM_GBC_FI: All entries returned must match the Firm Item provided in ulFirmCode.

•CM_GBC_BOX: All entries returned must match the CmContainer properties provided in pcmBoxInfo.

•CM_GBC_ALLENTRIES: All entries of all connected CmContainers available at hcmse will be returned.

The above flags can be or'ed with

CM_GBC_USELOCALTIME: Returns the time values using the local time zone instead of UTC.

The flags CM_GBC_FI and CM_GBC_BOX can be combined. If the value of ulFirmCode or pcmBoxInfo is not relevant for the desired flag operation the value is ignored.

•ulFirmCode contains the Firm Code of the Firm Item the returned entries should have (used with CM_GBC_FI flag).

•pcmBoxInfo contains the CmContainer information of the CmContainer the entries should be returned from (used with CM_GBC_BOX flag).

•pcmBoxEntry contains an array of CMBOXENTRY2 structure.

Structure CMBOXENTRY2

CMBOXENTRY2 contains data of one entry. An entry is containing one Firm Item and one Product Item. In this structure all static data are stored. The dynamic data must read out of the CmContainer explicitly.

Syntax

typedef struct __CMBOXENTRY2 {

CMULONG mflFiCtrl;

CMULONG mulFirmCode;

CMUSHORT musFirmAccessCounter;

CMULONG mulFirmUpdateCounter;

CMULONG mulFirmPreciseTime;

CMUSHORT mausFirmItemText[CM_MAX_STRING_LEN];

CMULONG mflSetPios;

CMULONG mulProductCode;

CMULONG mulFeatureMap;

CMTIME mcmMaintenancePeriodStart;

CMTIME mcmMaintenancePeriodEnd;

CMULONG mulUnitCounter;

CMTIME mcmExpirationTime;

CMTIME mcmActivationTime;

CMULONG mulUsagePeriodLifeTime;

CMTIME mcmUsagePeriodStartTime;

CMULONG mulLicenseQuantity;

CMBYTE mfbDependencyPC;

CMBYTE mfbDependencyFM;

CMBYTE mfbDependencyMP;

CMBYTE mfbDependencyUC;

CMBYTE mfbDependencyET;

CMBYTE mfbDependencyAT;

CMBYTE mfbDependencyUP;

CMBYTE mfbDependencyLQ;

CMBYTE mfbDependencyLT;

CMBYTE mfbDependencyMV;

CMUSHORT musProductItemRef;

} CMBOXENTRY2;

Parameter

mflFiCtrl specifies the type of the Firm Item. The following flags can be set:

CM_GF_BOXBASED specifies that the Firm Item was programmed in the Box-Based-Mode.

CM_GF_FILEBASED specifies that the Firm Item was programmed in the File-Based-Mode.

CM_GF_FI_RESERVED specifies that the Firm Item is a Reserved Firm Item.

mulFirmCode contains the Firm Code of the Firm Item.

musFirmAccessCounter contains the Firm Access Counter of the Firm Item.

mulFirmUpdateCounter contains the Firm Update Counter of the Firm Item.

mulFirmPreciseTime contains the FirmPreciseTime of the Firm Item.

mausFirmItemText[CM_MAX_STRING_LEN] contains the Firm Item Text of the Firm Item.

mflSetPios specifies all available PIO's at this Product Item. The following flags can be set:

CM_BE_PRODUCTCODE specifies that the Product Item contains a Product Code.

CM_BE_FEATUREMAP specifies that the Product Item contains a Feature Map.

CM_BE_EXPTIME specifies that the Product Item contains a Expiration Time.

CM_BE_ACTTIME specifies that the Product Item contains a Activation Time.

CM_BE_UNITCOUNTER specifies that the Product Item contains a Unit Counter.

CM_BE_PROTDATA specifies that the Product Item contains a Protected Data.

CM_BE_EXTPROTDATA specifies that the Product Item contains one or more Extended Protected Data.

CM_BE_HIDDENDATA specifies that the Product Item contains one or more Hidden Data.

CM_BE_SECRETDATA specifies that the Product Item contains one or more Secret Data.

CM_BE_USERDATA specifies that the Product Item contains a User Data.

CM_BE_TEXT specifies that the Product Item contains a Text.

CM_BE_USAGEPERIOD specifies that the Product Item contains a Usage Period.

CM_BE_LICENSEQUANTITY specifies that the Product Item contains a License Quantity.

CM_BE_BORROWCLIENT specifies that the Product Item contains a Borrow Client entry.

CM_BE_BORROWSERVER specifies that the Product Item contains a Borrow Server entry.

CM_BE_COLI specifies that the Product Item contains a Customer Owned License Information (COLI).

CM_BE_MAINTENANCEPERIOD specifies that the Product Item contains a Maintenance Period entry.

CM_BE_LINGERTIME specifies that the Product Item contains a Linger Time entry.

CM_BE_MINIMALVERSION specifies that the Product Item contains a Minimal Runtime Version entry.
If the current Runtime Version does not match the set Minimal Runtime Version, the error CMERROR_RUNTIME_VERSION_TOO_OLD displays.

CM_BE_PIO_MASK specifies all flags for the Product Item Options.

•mulProductCode contains the Product Code of the Product Item.

•mulFeatureMap contains the Feature Map of the Product Item.

•mcmMaintenancePeriodStart contains the start date of the Maintenance Period of the Product Item if available.

•mcmMaintenancePeriodEnd contains the end date of the Maintenance Period of the Product Item if available.

•mulUnitCounter contains the Unit Counter of the Product Item if available.

•mcmExpirationTime contains the Expiration Time of the Product Item if available (see CMTIME structure).

•mcmActivationTime contains the Activation Time of the Product Item if available (see CMTIME).

•mulUsagePeriodLifeTime contains the period length of the Usage Period in seconds if available.

•mcmUsagePeriodStartTime contains the start time of the Usage Period if available (see CMTIME).

•mulLicenseQuantity contains the License Quantity of the Product Item if available.

•mfbDependencyPC contains the dependency flags of the Product Code.

•mfbDependencyFM contains the dependency flags of the Feature Map.

•mfbDependencyUC contains the dependency flags of the Unit Counter.

•mfbDependencyET contains the dependency flags of the Expiration Time.

•mfbDependencyAT contains the dependency flags of the Activation Time.

•mfbDependencyUP contains the dependency flags of the Usage Period.

•mfbDependencyLQ contains the dependency flags of the License Quantity.

•musProductItemRef holds the Product Item Reference.

Notes

The dynamic data can be read out with GetInfo()/CM_GEI_ENTRYDATA.

The dependency parameters (mfbDependencyXX) can be have one or more of the following flags:

•CM_GF_DATA specifies that the parameter depends on the contents of the data of the Firm Item.

•CM_GF_FUC specifies that the parameter depends on the Firm Update Counter of the Firm Item.

•CM_GF_SERIAL specifies that the parameter depends on the Serial Number of the CmContainer.

On Windows the mausFirmItemText array can be simply converted via CmConvertString() into the specified character set.

CMBOXENTRY2 is supported since CodeMeter Version 4.30.

•cbBoxEntry contains the number of CMBOXENTRY2 elements stored in pcmBoxEntry.

Return

The number of found entries is returned. If the number is larger than cbBoxEntry, the array in pcmBoxEntry is too small. In this case only cbBoxEntry entries are stored in pcmBoxEntry. To get the rest call the function with the correct array length again. If the array is to small the error code CMERROR_BUFFER_OVERFLOW is set. If 0 is returned then no entry was found and depending on flCtrl error code CMERROR_ENTRY_NOT_FOUND or CMERROR_BOX_NOT_FOUND is set.

Notes

This function does not really scan all available or desired ports for connected CmContainers because of CodeMeter License Server's Plug&Play mechanism and the implementation of storing all CmContainers and their content in internal lists. The function call checks the internal lists only and returns the matching data.

CmGetBoxContents2() is supported since CodeMeter Version 4.30.