CmGetBoxContents2

<< Click here to display Table of Contents >> Navigation: Functions / Methods > Managing operations:

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 be 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 mulLicenseTransferUpdateCounter;

CMULONG mflSetNativePios;

CMULONG mflSetEffectivePios;

CMULONG mflSetPios;

/* Product Item data */

CMULONG mulProductCode;

CMULONG mulFeatureMap;

CMTIME mcmMaintenancePeriodStart;

CMTIME mcmMaintenancePeriodEnd;

CMULONG mulUnitCounter;

CMTIME mcmExpirationTime;

CMTIME mcmActivationTime;

CMULONG mulUsagePeriodLifeTime;

CMTIME mcmUsagePeriodStartTime;

CMULONG mulLicenseQuantity;

CMULONG mflLicenseQuantityFlags;

CMULONG mulLicenseTag;

CMULONG mflTransferStatus;

CMBYTE mabProductItemId[10];

CMUSHORT musMaxEncryptionRate;

CMBYTE mfbDependencyPC;

CMBYTE mfbDependencyFM;

CMBYTE mfbDependencyMP;

CMBYTE mfbDependencyUC;

CMBYTE mfbDependencyET;

CMBYTE mfbDependencyAT;

CMBYTE mfbDependencyUP;

CMBYTE mfbDependencyLQ;

CMBYTE mfbDependencyLT;

CMBYTE mfbDependencyMV;

CMUSHORT musModuleRef;

CMUSHORT musProductItemRef;

CMUSHORT musTransferBoxMask;

CMULONG mulTransferSerialNumber;

CMTIME mcmTransferBorrowExpirationTime;

CMBYTE mabTransferId[10];

} CMBOXENTRY2;

Parameter

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

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

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

CM_GF_TRANSFERBASED specifies that the Firm Item has been created based on a license transfer.

CM_GF_FI_ALLOWED_TO_PULL specifies the license transfer can be actively performed.

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.

mulLicenseTransferUpdateCounter contains the Update Counter of the License Transfer.

mflSetNativePios specifies in the context of used Module Items the native representation of the PIOs as programmed.

mflSetEffectivePios specifies in the context of used Module Items the effective representation, i.e including eventually inherited PIOs.

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 an Expiration Time.

CM_BE_ACTTIME specifies that the Product Item contains an Activation Time.

CM_BE_UNITCOUNTER specifies that the Product Item contains an 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 an User Data.

CM_BE_TEXT specifies that the Product Item contains a Text.

CM_BE_USAGEPERIOD specifies that the Product Item contains an 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.

Please note that borrowing in this context does not involve a license transfer. Rather it refers to borrowing using Firm Codes smaller than 6,000,000 and especially prepared CmContainer.

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

Please note that borrowing in this context does not involve a license transfer. Rather it refers to borrowing using Firm Codes smaller than 6,000,000 and especially prepared CmContainer.

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.

CM_BE_LINGERTIME specifies that the Product Item contains a Linger Time.

CM_BE_MINIMUMVERSION specifies that the Product Item contains a Minimal Runtime Version.

CM_BE_MODULE_ITEM specifies that the Product Item contains a Module Item.

CM_BE_BORROWEXPIRATIONTIME specifies that the Product Item contains a Borrow Expiration Time based on a license transfer.

CM_BE_HISTORY specifies that the Product Item is part of a license transfer process and holds History Data.

CM_BE_TRANSFEROPTIONS specifies that the Product Item contains license transfer options.

CM_BE_RETURNINFO specifies that the Product Item contains a license return information.

CM_BE_ACCEPTSPULL specifies that the Product Item can be pulled.

CM_BE_NAMEDUSER specifies that the Product Item contains a Named User information.

CM_BE_MAX_ENCRYPTION_RATE specifies that the Product Item contains a Maximum Encryption Rate information.

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.

mflLicenseQuantityFlags contains the flags for license access options, i.e. local accesses.

CM_LQ_DENIEDUSERLIMIT

CM_LQ_DENIEDNOUSERLIMIT

CM_LQ_DENIEDEXCLUSIVE

CM_LQ_DENIEDSTATIONSHARE

CM_LQ_ALLOWCMWAN

CM_LQ_TRIPLEMODEREDUNDANCY

CM_LQ_LOCALACCESSONLY

CM_LQ_DENIEDALL

CM_LQ_MAXVALUE

mulLicenseTag contains information in the context of Triple Mode Redundancy feature if available.

mflTransferStatus contains the flag of the transfer status. The following flags exist:

CM_TRANSFER_STATUS_ENABLED

CM_TRANSFER_STATUS_DISABLED

CM_TRANSFER_STATUS_RETURNED

CM_TRANSFER_STATUS_EXPIRED

mabProductItemId contains an unique identifier for the Product Item.

musMaxEncryptionRate contains the Maximum Encryption Rate.

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.

mfbDependencyLT contains the dependency flags of the Linger Time.

mfbDependencyMV contains the dependency flags of the Minimum Runtime Version.

musModuleRef contains the Product Item Reference of the super-ordinated Product Item of a Module Item. All items of a module then have the same ModulRef if available.

musProductItemRef holds the Product Item Reference.

musTransferBoxMask holds the box mask of the source CmContainer in the case of a transferred license if available.

mulTransferSerialNumber holds the serial number of the source CmContainer in the case of a transferred license if available.

mcmTransferBorrowExpirationTime holds the time at which a borrowed license (license transfer) expires if available.

mabTransferId[10] holds the Id of the transfer (corresponds to the Id in the history item of the sender) if available.

Notes

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

The dependency parameters (mfbDependencyXX) can 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

CmGetBoxContents2() is supported since CodeMeter Version 4.30.