Syntax
int CMAPIENTRY CmProgram(HCMSysEntry hcmse, CMULONG flCtrl, void *pvCtrl, CMUINT cbCtrl, void *pvVerify, CMUINT cbVerify)
Parameter
hcmse contains a handle opened by CmAccess2. The access mode can be Box Access, Firm Item Access or Entry Access. The required access mode depends on the operation set in flCtrl. The handle is connected to a CmLocal subsystem with a connected CmDongle. This CmDongle will be used for programming.
flCtrl contains one of the following commands:
CM_GF_ADD_FIRMITEM adds a Firm Item into a CmDongle. pvCtrl is pointing to a 
CMPROGRAM_ADD_FIRMITEM structure. hcmse must be Box Access.
Structure CMPROGRAM_ADD_FIRMITEM
CMPROGRAM_ADD_FIRMITEM contains all needed information to add a Firm Item to a CmDongle. The following parameters of the structure are encrypted: musFirm ItemTypeEncrypted to mabSessionId (inclusive). This member defines a sequence of 64 bytes which are encrypted by AES-CBC. The key and the CBC initialization vector depends on the addressed Firm Code and of parameters of the addressed CmDongle.
Syntax
typedef struct __CMPROGRAM_ADD_FIRMITEM {
/* plain members */
CMUSHORT musFirmItemReference;
CMUSHORT musFirmItemTypePlain;
CMBYTE mabPublicLicensorKey[CM_PUBLIC_KEY_LEN];
/* encrypted members */
CMUSHORT musFirmItemTypeEncrypted;
CMUSHORT musFirmAccessCounter;
CMULONG mulFirmUpdateCounter;
CMULONG mulFirmPreciseTime;
CMULONG mulReserved;
CMBYTE mabFirmKey[CM_BLOCKCIPHER_KEY_LEN];
CMBYTE mabSessionId[2 * CM_SESSIONID_LEN];
/* plain members */
CMUSHORT mcchText;
/* variable length, max = 256 */
CMUSHORT mausText[CM_MAX_STRING_LEN];
} CMPROGRAM_ADD_FIRMITEM;
|
Parameter
musFirmItemReference contains the reserved Firm Item Reference received with CmReserveFirmItem().
musFirmItemTypePlain specifies the type of the Firm Item. The following flags can be set:
CM_GF_BOXBASED specifies that the Firm Item is programmed in the Box-Based-Mode.
CM_GF_FILEBASED specifies that the Firm Item is programmed in the File-Based-Mode.
CM_GF_TRANSFERBASED specifies that the Firm Item has been created based on a license transfer.
mabPublicLicensorKey contains 64 bytes of ECC Licensor Key which is required to decrypt the specified data via the private Box Key, Serial Key, Firm Common Key and Serial Number of the addressed CmDongle.
musFirmItemTypeEncrypted (encrypted) 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_TRANSFERBASED specifies that the Firm Item has been created based on a license transfer.
This value must be equal to musFirmItemTypePlain!
musFirmAccessCounter (encrypted) contains the initial value of the Firm Access Counter. If this member is set to 0xFFFF (the recommended value), this counter is not decremented by an encryption which targets this counter.
mulFirmUpdateCounter (encrypted) contains the initial value of the Firm Update Counter. The recommended value is 0.
mulFirmPreciseTime (encrypted) contains the new Firm Precise Time in seconds since 1st January 2000, 0:00:00. If the value is not used, 0 must be specified, which sets this field to the Running Box Clock value.
mulReserved (encrypted) should be set to 0. Reserved for future purposes.
mabFirmKey (encrypted) contains the secret Firm Key, which has a fixed length of 32 bytes.
mabSessionId (encrypted) contains the Session ID received with CmReserveFirmItem().
mcchText contains the initial length of the Firm Item Text of the Firm Item to program.
mausText contains the initial Firm Item Text of the Firm Item to program.
|
CM_GF_UPDATE_FIRMITEM updates a Firm Item in a CmDongle. pvCtrl is pointing to a CMPROGRAM_UPDATE_FIRMITEM structure. hcmse must be Firm Item Access or Entry Access.
Structure CMPROGRAM_UPDATE_FIRMITEM
CMPROGRAM_UPDATE_FIRMITEM contains all needed parameters to update a Firm Item.
Syntax
typedef struct __CMPROGRAM_UPDATE_FIRMITEM {
CMUSHORT musFirmItemReference;
CMUSHORT musCtrl;
CMUSHORT musFirmAccessCounter;
CMULONG mulFirmUpdateCounter;
CMULONG mulFirmPreciseTime;
CMUSHORT mcchText;
/* variable length, max = 256, expand structure on the stack */
CMUSHORT mausText[1];
} CMPROGRAM_UPDATE_FIRMITEM;
|
Parameter
musFirmItemReference contains the Firm Item Reference of the Firm Item.
musCtrl specifies the flags, which parameters should be updated.
CM_UFI_FAC specifies that the Firm Access Counter should be updated.
CM_UFI_FUC specifies that the Firm Update Counter should be updated.
CM_UFI_FPT specifies that the FirmPreciseTime should be updated.
CM_UFI_TEXT specifies that the Firm Item Text should be updated.
musFirmAccessCounter (encrypted) contains the initial value of the Firm Access Counter. If this member is set to 0xFFFF (the recommended value), this counter is not decremented by an encryption which targets this counter.
mulFirmUpdateCounter (encrypted) contains the initial value of the Firm Update Counter. The recommended value is 0.
mulFirmPreciseTime (encrypted) contains the new Firm Precise Time in seconds since 1st January 2000, 0:00:00. If the value is not used, 0 must be specified, which sets this field to the Running Box Clock value.
mcchText contains the initial length of the Firm Item Text of the Firm Item to program.
mausText contains the initial Firm Item Text of the Firm Item to program.
|
CM_GF_DELETE_FIRMITEM deletes a Firm Item in a CmDongle. pvCtrl is pointing to a CMPROGRAM_DELETE_FIRMITEM structure. hcmse must be Firm Item Access or Entry Access.
Structure CMPROGRAM_DELETE_FIRMITEM
CMPROGRAM_DELETE_FIRMITEM contains all parameters needed for deleting a complete Firm Item.
Syntax
typedef struct __CMPROGRAM_DELETE_FIRMITEM {
CMUSHORT musFirmItemReference;
CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];
} CMPROGRAM_DELETE_FIRMITEM;
|
Parameter
musFirmItemReference contains the Reference of the Firm Item which has to be removed.
mabTrailingValidationBlock contains a 16-byte TVB (Trailing Validation Block), which must be valid to execute the operation. This TVB is ignored, if the addressed Firm Item was directly created with CmReserveFirmItem().
|
CM_GF_ADD_PRODUCTITEM adds a Product Item into a CmDongle. pvCtrl is pointing to a CMPROGRAM_ADD_PRODUCTITEM structure. hcmse must be Entry Access.
Structure CMPROGRAM_ADD_PRODUCTITEM
CMPROGRAM_ADD_PRODUCTITEM contains all needed information to add a Product Item to a CmDongle. All parameters are encrypted.
Syntax
typedef struct __CMPROGRAM_ADD_PRODUCTITEM {
CMUSHORT musFirmItemReference;
CMUSHORT musProductItemSuccessorReference;
/* variable length, expand structure on the stack */
CMBYTE mabProductItemOptionBuffer[1];
} CMPROGRAM_ADD_PRODUCTITEM;
|
Parameter
musFirmItemReference (encrypted) contains the Reference of the Firm Item for which the Product Item is to be added. If this is 1, the IFI (Implicit Firm Item) is used. The addressed item must not have set the type. 0 is either not permitted.
musProductItemSuccessorReference (encrypted) contains the Reference of the Product Item, which will be the successor of the newly added Product Item. If this value is 0, the Product Item is created at the end of the Product Item list. If musFirmItemReference specifies 0 for the IFI, the Product Item may be individually addressed by setting 2 for User Product Item (UPI). 1 for the Common Product Item (CPI) is not permitted because this must be always the first Product Item of the IFI.
mabProductItemOptionBuffer (encrypted) contains a byte sequence of variable length which specifies the added Product Code and all further Product Item Options. The sequence is defined by one or more subsequent CMCPIO_... structures. The parameter is filled with CmCreateProductItemOption() and finalized with CmCreateSequence(). The complete list is encrypted by AES-CBC. Finally, a 16-bytes TVB (Trailing Validation Block) is added, which is the encrypted SHA-256 hash of the preceding padded byte sequence.
|
CM_GF_UPDATE_PRODUCTITEM updates a Product Item in a CmDongle. pvCtrl is pointing to a CMPROGRAM_UPDATE_PRODUCTITEM structure. hcmse must be Entry Access.
Structure CMPROGRAM_UPDATE_PRODUCTITEM
CMPROGRAM_UPDATE_PRODUCTITEM contains all needed parameters to update a Product Item.
Syntax
typedef struct __CMPROGRAM_UPDATE_PRODUCTITEM {
CMUSHORT musFirmItemReference;
CMUSHORT musProductItemReference;
CMUSHORT musCtrl;
/* variable length, expand structure on the stack */
CMBYTE mabProductItemOptionBuffer[1];
} CMPROGRAM_UPDATE_PRODUCTITEM;
|
Parameter
musFirmItemReference contains the reference of the Firm Item in which the Product Item should be updated.
musProduct ItemReference contains the reference of the Product Item which should be updated.
musCtrl contains flags set internally by the driver.
mabProductItemOptionBuffer contains a byte sequence of variable length which specifies the added Product Code and all further Product Item Options. The sequence is defined by one or more subsequent CMCPIO_... structures. The parameter is filled with CmCreateProductItemOption() and finialized with CmCreateSequence(). The complete list is encrypted by AES-CBC. Finally, a 16-bytes TVB (Trailing Validation Block) is added, which is the encrypted SHA-256 hash of the preceding padded byte sequence.
|
|
CM_GF_DELETE_PRODUCTITEM deletes a Product Item in a CmDongle. pvCtrl is pointing to a CMPROGRAM_DELETE_PRODUCTITEM structure. hcmse must be Entry Access.
Structure CMPROGRAM_DELETE_PRODUCTITEM
CMPROGRAM_DELETE_PRODUCTITEM contains the parameters for deleting a Product Item.
Syntax
typedef struct __CMPROGRAM_DELETE_PRODUCTITEM {
CMUSHORT musFirmItemReference;
CMUSHORT musProductItemReference;
CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];
} CMPROGRAM_DELETE_PRODUCTITEM;
|
Parameter
musFirmItemReference contains the reference of the Firm Item in which the Product Item is deleted.
musProductItemReference contains the reference of the Product Item which is to be deleted.
mabTrailingValidationBlock contains the Trailing Validation Block (TVB) which checks, if the delete operation is valid.
|
|
CM_GF_SET_BOXCONTROL sets the control flag of the CmDongle. pvCtrl is pointing to a CMPROGRAM_BOXCONTROL structure.
Structure CMPROGRAM_BOXCONTROL
CMPROGRAM_BOXCONTROL contains the parameters to program the CmDongle control registers.
Syntax
typedef struct __CMPROGRAM_BOXCONTROL {
CMULONG mflCtrl;
CMUSHORT musIndicatorFlags;
CMUSHORT musReserve;
} CMPROGRAM_BOXCONTROL;
|
Parameter
mflCtrl specifies the kind of the programming of the CmDongle control registers.
CM_BC_ABSOLUTE specifies that the control registers is programmed absolutely.
CM_BC_SWITCH specifies that the control registers is programmed in the switch mode.
musIndicatorFlags contains the two bytes to program or switch.
musReserve is reserved for future purposes.
|
CM_GF_SET_FIRMKEY programs a Firm Key into an already programmed FSB entry in a CmDongle. pvCtrl is pointing to a 32 element byte array. hcmse must be Entry Access.
CM_GF_ADD_ENABLEBLOCK adds a new Enable Block Item to a Firm Item. The input parameters are stored in a CMENABLING_WRITEADD structure. The return value of the function is the index of the created Enable Block Item in the Enable Block Table. If no Enable Block Item is created, then 0 is returned and an error code is set.
Structure CMENABLING_WRITEADD
CMENABLING_WRITEADD describes the request sequence of the adding a Enable Block Item.
Syntax
typedef struct __CMENABLING_WRITEADD {
CMULONG mcbLength;
CMUSHORT musFirmItemReference;
CMENABLING_ENABLEBLOCKITEM mcmEnableBlockItem;
} CMENABLING_WRITEADD;
|
Parameter
mcbLength contains the size of this structure.
musFirmItemReference contains the reference of the Firm Item in which the Enabling Block is added. If this is 0, the IFI (Implicit Firm Item) is used.
mcmEnableBlockItem specifies the Enabling Block Item which is added.
This is a variable length sequence which depends on the Enabling Block Item Type. The subsequent bytes are encrypted by AES-CBC. The sequence is padded with 0 bytes to a multiple of 16 bytes which is encrypted.
After this sequence a TVB (Trailing Validation Block) is added, which is the AES-encryption of the SHA-256 hash of the data before they are encrypted including the padded area (see structure CMENABLING_ENABLEBLOCKITEM).
Structure CMENABLING_ENABLEBLOCKITEM
CMENABLING_ENABLEBLOCKITEM contains data of a Enable Block Item (EBI) when they should be set into the CmContainer.
Syntax
typedef struct __CMENABLING_ENABLEBLOCKITEM {
CMUSHORT musOption;
CMBYTE mbIndex;
CMBYTE mbType;
union {
/* variable length */
CMENABLING_SIMPLEPIN mcmSimplePin;
CMENABLING_TIMEPIN mcmTimePin;
} mEnableType;
} CMENABLING_ENABLEBLOCKITEM;
|
Parameter
musOption specifies the following flags.
CM_EBI_VALID specifies that the enabling block item is a valid structure.
CM_EBI_ENABLED specifies that the block is permanently enabled.
CM_EBI_DISABLED specifies that the Disabling Flag of the Enable Block Item is set and the block is permanently disabled.
CM_EBI_TEMPENABLED specifies that the Enable Block Item is temporarily enabled, independently of the static Enabling Status of the Enable Block Item. For a Firmware version smaller than version 1.18 this option is only permitted, if the Enable Block Item is owned by the IFI (Implicit Firm Item = Firm Code 0).
mbIndex specifies the EBI Index inside a Firm Item (or IFI).
mbType specifies the type of the used enabling. This can be one of the following flags:
CM_EBI_SIMPLEPIN specifies that SimplePin enabling is used.
CM_EBI_TIMEPIN specifies that TimePin enabling is used.
mcmSimplePin contains the data when the EBI is using SimplePin enabling (see structure CMENABLING_SIMPLEPIN).
Structure CMENABLING_SIMPLEPIN
CMENABLING_SIMPLEPIN describes an Enabling Block of type "Simple PIN" in the Add Enable Block or Update Enable Block command request sequence.
Syntax
typedef struct __CMENABLING_SIMPLEPIN {
CMBYTE mcbEnableAccessCode;
/* variable length, max = 16 */
CMBYTE mabEnableAccessCode[CM_CHALLENGE_LEN];
} CMENABLING_SIMPLEPIN;
|
Parameter
mcbEnableAccessCode contains the number of bytes which are defined in the Enable Access Code. This must be a value between 2 and 16.
mabEnableAccessCode contains the Enable Access Code bytes, the length is defined by the mcbEnableAccessCode member.
|
mcmTimePin contains the data when the EBI is using TimePin enabling (see structure CMENABLING_TIMEPIN).
Structure CMENABLING_TIMEPIN
CMENABLING_TIMEPIN describes an Enabling Block of type "Time PIN" in the Add Enable Block or Update Enable Block command request sequence.
Syntax
typedef struct __CMENABLING_TIMEPIN {
CMULONG mulDisableTime;
CMBYTE mcbEnableAccessCode;
CMUSHORT mcchText;
/* variable length, AccessCode + Text added, expand structure on the stack */
CMBYTE mabBuffer[1];
} CMENABLING_TIMEPIN;
|
Parameter
mulDisableTime contains the Disable Time. This is number of seconds since the 1st January 2000 0:00:00 (UTC).
mcbEnableAccessCode contains the number of bytes which are defined in the Enable Access Code. This must be a value between 2 and 16.
mcchText contains the length of the description text.
mabBuffer specifies the text of the "Time PIN" and contains mcbEnableAccessCode bytes of Access Code and mcchText Unicode characters.
|
|
|
|
CM_GF_UPDATE_ENABLEBLOCK updates the content of an existing Enable Block Item. The input parameters are stored in a byte array (pointer to unsigned char). The return value for this flag is 1 (TRUE), if no error occurred, else 0 (FALSE).
CM_GF_DELETE_ENABLEBLOCK deletes an existing Enable Block Item in a Firm Item. The input parameters are stored in a CMENABLING_WRITEDELETE structure. The return value for this flag is 1 (TRUE), if no error occurred, else 0 (FALSE).
Structure CMENABLING_WRITEDELETE
CMENABLING_WRITEDELETE describes the request sequence for deleting a Enable Block Item (EBI). command.
Syntax
typedef struct __CMENABLING_WRITEDELETE {
/* plain members */
CMUSHORT musFirmItemReference;
CMBYTE mbEnableBlockIndex;
CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];
} CMENABLING_WRITEDELETE;
|
Parameter
musFirmItemReference contains the reference of the Firm Item which defines the Enabling Block. If this is 0, the IFI (Implicit Firm Item) is used.
mbEnableBlockIndex contains the index of the Enabling Block which is deleted. This must be a value between 0 and 30.
mabTrailingValidationBlock contains the Trailing Validation Block (TVB), which checks whether the delete operation is valid. This is an AES encryption of the SHA-256 hash of the preceding bytes.
|
CM_GF_ATTACH_ENABLEBLOCK attaches an existing Enable Block Item to a Firm Item or Product Item. The input parameters are stored in a CMENABLING_WRITEATTACHDETACH structure. The return value for this flag is 1 (TRUE), if if no error occurred, else 0 (FALSE).
Structure CMENABLING_WRITEATTACHDETACH
CMENABLING_WRITEATTACHDETACH describes the request sequence for attaching or detaching a Enable Block Item (EBI).
Syntax
typedef struct __CMENABLING_WRITEATTACHDETACH {
CMBYTE mbEnableBlockIndex;
CMUSHORT musFirmItemReference;
CMUSHORT musProductItemReference;
CMULONG mulFirmUpdateCounter;
CMENABLING_ENABLELOOKUPENTRY mcmEnableLookupEntry;
CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];
} CMENABLING_WRITEATTACHDETACH;
|
Parameter
mbEnableBlockIndex contains the index of the Enabling Block Item which is attached.
The subsequent bytes are encrypted by AES-CBC or Triple-DES-CBC. They have a fixed length of 32 bytes.
musFirmItemReference contains the reference of the Firm Item in which the Enabling Block is attached. If this is 0, the IFI (Implicit Firm Item) is used.
musProductItemReference contains the Reference of the Product Item in which the Enabling Block is attached. If the Enabling Block should be attached to the Firm Item, this member must be set to 0. If musFirmItemReference specifies 0, the Product Item may be individually addressed by setting Common Product Item (CPI) or User product item (UPI).
mulFirmUpdateCounter contains the current value of the Firm Update Counter of the Firm Item which owns the Enabling Block.
mcmEnableLookupEntry contains the Enabling Lookup Entry which defines the attachment. If the mbEnableLevel member is set to CM_ELUE_DETACH, the Enabling Lookup Entry is deleted.
mabTrailingValidationBlock contains the TVB (Trailing Validation Block), which contains the current hash sequence (16 bytes) to validate that the sequence is correctly encrypted.
Notes
All parameters set by the user to this structure must be set in Little Endian format! Normally this must be noticed on Big Endian CPU's like the Apple Macintosh. On PC's (x86) the parameters (16 & 32 Bit) are stored in Little Endian so that the user has nothing to mentioned (Little/Big Endian).
|
CM_GF_DETACH_ENABLEBLOCK detaches an existing Enable Block Item from a Firm Item or Product Item. The input parameters are stored in a CMENABLING_WRITEATTACHDETACH structure. The return value for this flag is 1 (TRUE), if no error occurred, else 0 (FALSE).
CM_GF_ENABLEITEM enables the Enabling Block Item defined in CMENABLING_CONTEXT
Structure CMENABLING_CONTEXT
CMENABLING_CONTEXT contains enabling data. It can be collected using CmGetInfo with option CM_GEI_ENABLEINFO. It can be used for enabling using CmProgram.
Syntax
typedef struct __CMENABLING_CONTEXT {
CMULONG mulFirmCode;
CMULONG mulProductCode;
CMUSHORT musOption;
CMBYTE mbIndex;
CMBYTE mbType;
CMULONG mulDisableTime;
CMUSHORT mausText[CM_MAX_STRING_LEN];
CMUSHORT musFlags;
CMBYTE mbItemType;
CMBYTE mcbEnableAccessCode;
CMBYTE mabEnableAccessCode[CM_CHALLENGE_LEN];
CMUSHORT musEnablePassword[CM_MAX_PASSWORD_LEN];
CMBYTE mbEnableLevel;
CMBYTE mbDisableLevel;
} CMENABLING_CONTEXT;
|
Parameter
mulFirmCode contains the Firm Code the enabling block is attached to.
mulProductCode contains the Product Code the enabling block is attached to. In the case of a value of 0, check mbItemType to see, if it is attached to Product Item with Product Code 0 or to the Firm Item.
musOption specifies the following flags.
CM_EBI_VALID specifies that the enabling block item is a valid structure.
CM_EBI_ENABLED specifies that the block is permanently enabled.
CM_EBI_DISABLED specifies that the Disabling Flag of the Enabling Block Item is set and the block is permanently disabled.
CM_EBI_TEMPENABLED specifies that the Enabling Block Item is temporarily enabled, independently of the static Enabling Status of the Enable Block Item. For Firmware version smaller than version 1.18 this option is only permitted, if the Enable Block Item is owned by the IFI (Implicit Firm Item = Firm Code 0).
mbIndex specifies the EBI Index inside a Firm Item (or IFI).
mbType specifies the type of the used enabling. This can be one of the following flags:
CM_EBI_SIMPLEPIN specifies that Simple Pin enabling is used.
CM_EBI_TIMEPIN specifies that Time Pin enabling is used.
mulDisableTime contains disable time in seconds since the 1st January 2000 0:00:00 (UTC).
mausText contains the text of the Enabling Block Item. Only available for Time Pin and Finger Pin.
musFlags specifies the following states:
CM_ELUE_VALID specifies that the Enabling Lookup Entry is a valid structure.
CM_ELUE_IFI specifies that the Enabling Block Item of the IFI is used and not of the owning Firm Item.
CM_ELUE_REQUIRED specifies that this lookup entry must permit the operation independent to other settings.
musFlags specifies the following states:
mbItemType specifies the following item types:
CM_EC_PRODUCTITEM specifies that the Enabling Block Item is attached to the Product Item.
CM_EC_FIRMITEM specifies that the Enabling Block Item is attached to the Firm Item.
CM_EC_GLOBALITEM specifies that the Enabling Block Item is attached to the IFI (Implicit Firm Item = Firm Code 0)
mcbEnableAccessCode contains the number of bytes which are defined in the Enable Access Code. This must be a value between 2 and 16.
mabEnableAccessCode contains the Enable Access Code.
musEnablePassword contains the Enable Password.
mbEnableLevel specifies the Enable Level. This can be one of the following flags (see mbDisableLevel).
mbDisableLevel specifies the Disable Level. This can be one of the following flags:
CM_ELUE_LOCATE only the reading of the Firm Code, the Product Code, the Enabling Block Table and the Enabling Lookup Table is permitted.
CM_ELUE_READ the reading of the Firm Item or Product Item is permitted but no operations.
CM_ELUE_ENCRYPT encryption, decryption and signature calculation is permitted but not with modification of the Unit Counter.
CM_ELUE_UNITUSE encryption, decryption and signature calculation may change the Unit Counter. In a Firm Item, the Firm Update Counter and the Access Counter may be changed.
CM_ELUE_MODIFY all operations are permitted including modification of the properties by update commands.
Note
You may either use mabEnableAccessCode or musEnablePassword for enabling / disabling the item depending on the value of mcbEnableAccessCode. If mcbEnableAccessCode is 0, the text in musEnablePassword is used, otherwise the code of musEnableAccessCode is used.
CMENABLING_CONTEXT is supported since CodeMeter Version 4.30.
|
|
CM_GF_DISABLEITEM disables the Enabling Block Item defined in CMENABLING_CONTEXT.
CM_GF_TEMPENABLEITEM enables temporarily the Enabling Block Item defined in CMENABLING_CONTEXT.
pvCtrl contains a structure depending on the flCtrl flag (see above).
cbCtrl contains the number of bytes of the pvCtrl byte buffer/structure.
pvVerify contains a byte buffer receiving the verification sequence for the programmer. Except of the CM_GF_DELETE_FIRMITEM command this is a signed list command of the added/updated/deleted Firm Item (Signed List of the whole Firm Item). CM_GF_DELETE_FIRMITEM handles the creation of a verification sequence in the CmDongle internally. A CMVALIDATE_DELETEFI structure must be passed here. If the parameter is NULL (==>> cbVerify = 0), no verification sequence is returned. If the buffer is to small for the verification sequence, the return value is larger than the cbVerify value and the error code CMERROR_BUFFER_OVERFLOW is set.
Structure CMVALIDATE_DELETEFI
CMVALIDATE_DELETEFI contains the data received by a CmDongle after deleting a Firm Item to validate, if a Firm Item is deleted correctly with a Firm Security Box (FSB).
Syntax
typedef struct __CMVALIDATE_DELETEFI {
CMULONG mflFiCtrl;
CMULONG mulFirmCode;
CMULONG mulSystemTime;
CMULONG mulFirmUpdateCounter;
CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];
} CMVALIDATE_DELETEFI;
|
Parameter
mflFiCtrl specifies the type of a Firm Item. This can be one of the following values:
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_TRANSFERBASED specifies that the Firm Item has been created based on a license transfer.
CM_GF_FI_RESERVED specifies that the Firm Item is a Reserved Firm Item.
mulFirmCode contains the deleted Firm Code
mulSystemTime contains the current value of the System Running Box Clock. This is the number of seconds since 1st January 2000, 0:00:00. This value is used to build the TVB for an authentication that the Firm Item was deleted.
mulFirmUpdateCounter contains the final value of the Firm Update Counter. This value is used to build the TVB for an authentication that the Firm Item was deleted.
mabTrailingValidationBlock contains a 16-byte Trailing Validation Block (TVB), which may be recalculated by the sender of the Request Sequence that the operation was successfully executed.
|
cbVerify contains the number of bytes of the byte buffer/structure stored in pvVerify.
Return
If the programming task is executed successfully and if pvVerify is NULL, then TRUE is returned, else FALSE is returned. If pvVerify contains enough memory, the length of the signed list or a CMVALIDATE_DELETEFI structure is returned. If pvVerify does not contain enough memory, the number of required bytes will be returned. In this case the return value is larger than the cbVerify parameter and error code CMERROR_BUFFER_OVERFLOW is set.
The following flags (and the corresponding functionality) are only available since CodeMeter Version 4.30:
•CM_GF_ENABLEITEM
•CM_GF_DISABLEITEM
•CM_GF_TEMPENABLEITEM
CmProgram