CmEmbedded_4c_transp CmAccess2

Description

CmAccess() opens the access to a:

•computer (SubSystem Access)

•CmContainer (Box Access)

•single Firm Item (FC, Firm Item Access) or a

•CmContainer entry (FC:PC, Entry Access) in a given subsystem.

Please note the detailed description of the Access Modes.

information_weiss_klein26

Please note that CmAccess2() provides enhanced functionality to access a CmContainer. This function is implemented since CodeMeter Version 3.30.

A SubSystem Access represents a superset of Box Access. A Box Access is a superset of Firm Item Access. A Firm Item Access is a superset of an Entry Access. Anything that can be done with a SubSystem Access can also be done with Box Access, but not vice versa!

information_weiss_klein26

Please note that on a Box Access the mask m and serial number s may change anytime depending on CodeMeter chip versions.

Please consider these possible changes for future CmContainer generations on programming accesses for CmContainer.

The subsystem is the local computer (CmLocal) or a local or wide area network system (CmLAN, CmWAN). For CmWAN please consult the CodeMeter Developer Guide. This implies that a CodeMeter License Server process must be started with a CmContainer connected on an other system in the network.

The communication between protected applications and CodeMeter License Server bases on the Transmission Control Protocol/Internet Protocol (TCP/IP). This is valid not only for locally existing licenses, but also for licenses which are provided via a network.

By default, CodeMeter uses the port 22350 registered by Wibu-Systems at IANA (Internet Assigned Numbers Authority) and uniquely assigned for the CodeMeter communication. The list of assigned ports can be viewed at www.iana.org/assignments/port-numbers.

In order to make available a client access to a CodeMeter License Server on the network, a communication using the CodeMeter port must be supported. If the server should locate in another network area, eventually the port must be made known and accessible as part of the infrastructure (router, firewall, etc.).

For the direct access to CodeMeter License Server on the network, the communication bases on TCP. For an automatic search of servers on the network, additionally a broadcast via UDP (User Datagram Protocol) is performed.

information_weiss_klein26

The access using the CodeMeter port is performed only for the access to CodeMeter License Servers and this only within the organization which runs the network server.

In particular, using this port no communication into the internet is performed.

In CodeMeter settings of CodeMeter WebAdmin an option exist to configure the CodeMeter port to a value other than the default of 22350. However, such a change should have plausible reasons, e.g. in the case of parallel test environments on the same network. In addition, such a change requires the same configuration of all affected CodeMeter License Servers.

The desired subsystem and the search order can be set in the special flags.

If a network access to another computer is performed, it will be available until the access is closed with CmRelease(). If more than one connection between two instances should be required, CmAccess() will open only one connection which is the medium for all communication between the two clients.

  • C, C++

Note

CmAccess2() provides enhanced functionality to access a CmContainer by using the hmtoggle_plus1 CMCREDENTIAL feature.

Structure CMCREDENTIAL

CMCREDENTIAL holds parameters that can be used for a CmAccess2() call to refine the license allocation and the assignment to the CodeMeter License Server, for example, via an arbitrary user name.

Syntax

typedef struct __CMCREDENTIAL {

CMULONG mulPID;

CMULONG mulSession;

CMULONG mulCleanupTime;

CMULONG mulMaxLifeTime;

CMULONG mulCreationTime;

CMULONG mulAccessCtrl;

CMULONG mulUserDefinedID;

char mszUserDefinedText[128];

char mszUsername[32];

CMULONG mulCurrentCmInstanceUid;

CMULONG mulPreviousCmInstanceUid;

char mszDomainName[16];

char mabReserved2[4]

} CMCREDENTIAL;

Parameter

mulPID contains the process ID that is set by the CodeMeter library (read only).

mulSession is always zero on the user site.

mulCleanupTime this parameter overwrites the CleanupTime profiling value for license releasing in minutes.

mulMaxLifeTime defines the maximum lifetime (in minutes) of the license that is allocated.

mulCreationTime holds the creation time of the license that was accessed in seconds since 01.01.2000.

mulAccessCtrl holds the type of access (since 4.20):

The first group of flags hold information about local or Lan access:

nav_openCM_CRED_LICENSE_LOCATION_LOCAL handle to the local system.

nav_openCM_CRED_LICENSE_LOCATION_LAN handle to a network system.

The second group defines the access type:

nav_openCM_CRED_HANDLE_ACCESS_ENTRY an entry handle.

nav_openCM_CRED_HANDLE_ACCESS_FI a Firm Item handle.

nav_openCM_CRED_HANDLE_ACCESS_BOX a box handle.

nav_openCM_CRED_HANDLE_ACCESS_SUBSYSTEM a subsystem handle.

mulUserDefinedID contains the user defined ID.

mszUserDefinedText contains a user defined text (UTF-8 encoded).

mszUsername holds an arbitrary user name (read only).

 

It is available since CodeMeter Version 3.30 and offers a user-defined timing to release licenses that were allocated locally or in the network.

This release interval overwrites the default timing value CleanUpTimeOut of the CodeMeter profiling. The benefit is that the user cannot influence this timing anymore.

Additionally, the validity period of the handle returned by CmAccess2() can be determined. This feature can be used to limit the usage period of an application that allocates a license using CmAccess2().

The mapping of the licenses on a CodeMeter server can be simplified by giving an user-defined string or number (session-ID) that is displayed on the server once the license was allocated.

Syntax

HCMSysEntry CMAPIENTRY CmAccess2(CMULONG flCtrl, CMACCESS *pcmAcc)

Parameter

 

information_weiss_klein26

Please note, that if your module configuration includes Module Runtime Bridge but without Module LAN, then the flag CM_ACCESS_LAN cannot be used and the error code CM_ERROR_FUNCTION_NOT_SUPPORTED is set.

The flag CM_ACCESS_LOCAL_LAN tries to access first the local subsystem and subsequently cannot find the LAN subsystem. Here the error code CM_ERROR_FUNCTION_NOT_SUPPORTED is set.

 

flCtrl specifies one of the following commands to set the desired subsystems. Only one of these constants can be set:

nav_open CM_ACCESS_LOCAL only searches in CmLocal for a CmContainer with a matching entry.

nav_open CM_ACCESS_LAN only searches in CmLAN for a CmContainer with a matching entry.

nav_open CM_ACCESS_LOCAL_LAN searches CmLocal first for a CmContainer with a matching entry and after that in CmLAN, if no CmContainer was found locally.

nav_open CM_ACCESS_LAN_LOCAL searches CmLAN first for a CmContainer with a matching entry and after that in CmLocal, if no CmContainer was found in the network.

nav_open CM_ACCESS_LANWAN searches in CmLAN and CmWAN for a CmContainer with a matching entry.

nav_open CM_ACCESS_LOCAL_LANWAN searches CmLocal first after that in CmLAN and CmWAN for a CmContainer with a matching entry.

nav_open CM_ACCESS_LANWAN_LOCAL searches first in CmLAN and CmWAN and after that in CmLocal for a CmContainer with a matching entry.

pcmAcc sets the needed data for the desired access (see structure hmtoggle_plus1 CMACCESS2).

Structure CMACCESS2

CMACCESS2 specifies additional data for the Access Modes to a computer (Subsystem Access), to a CmContainer (Box Access), to a single Firm Item (FC, Firm Item Access) or a CmContainer entry (FC:PC, Entry Access) in a given subsystem.

Syntax

typedef struct __CMACCESS2{

CMULONG mflCtrl;

CMULONG mulFirmCode;

CMULONG mulProductCode;

CMULONG mulFeatureCode;

CMULONG mulUsedRuntimeVersion;

CMULONG mulProductItemReference;

CMBYTE mbMinBoxMajorVersion;

CMBYTE mbMinBoxMinorVersion;

CMUSHORT musBoxMask;

CMULONG mulSerialNumber;

CMULONG mulLicenseQuantity;

char mszServername[128];

CMTIME mcmReleaseDate;

CMBYTE mabCmActId[4];

CMCREDENTIAL mcmCredential;

} CMACCESS2;

Parameter

mflCtrl:specifies the kind of the subsystem access by setting one of the following flags.

nav_open CM_ACCESS_USERLIMIT needs a license for each CmAccess2 () call. The License Quantity will be decreased by one at each access.

nav_open CM_ACCESS_NOUSERLIMIT needs no license for each CmAccess2 () call. The License Quantity will not be decreased in this mode.

nav_open CM_ACCESS_EXCLUSIVE needs a license for each CmAccess2 () call and on a computer only one access to the specified entry is permitted. The License Quantity will be decreased by one at each access.

nav_open CM_ACCESS_FIRMITEM forces a Firm Item access to an CmContainer entry.

nav_open CM_ACCESS_STATIONSHARE needs a license for each CmAccess2 () call and on a computer only one license to the specified entry is blocked. The License Quantity will be decreased by one once per computer.

nav_open CM_ACCESS_CONVENIENT needs in the local subsystem (CmLocal) no license (works here as CM_ACCESS_NOUSERLIMIT) and in the network (CmLAN) one license per access (works here as CM_ACCESS_USERLIMIT).

These flags can be or'ed with the following flags:

nav_open CM_ACCESS_FORCE forces the access to an entry, which has a expired Expiration Time, an invalid Activation Time or a Unit Counter, which is 0. Usually, CmAccess2 () does not return a valid handle, if one of the three Product Item Options has not a true value.

nav_open CM_ACCESS_CHECK_FSB specifies that the desired access must be done to a Product Code item of a Firm Security Box (FSB)  (usually 99). If the specified entry is not an FSB item, an error is returned. Only checked for Entry Access.

nav_open CM_ACCESS_CHECK_CTSB specifies that the desired access must be done to an entry in a Certified Time Security Box (CTSB) item. If the specified entry is not inside a CTSB item, an error is returned. Only checked for Entry Access.

nav_open CM_ACCESS_SUBSYSTEM specifies that the desired access can also be a Subsystem Access. In this case, mulFirmCode must be set to 0.

nav_open CM_ACCESS_IGNORE_LINGERTIME specifies that a possibly set Linger Time (a Product Item Option) is ignored for this access. Only useful in combination with CM_ACCESS_USERLIMIT or CM_ACCESS_STATIONSHARE.

mulFirmCode contains the Firm Code of the access mode. Which Firm Code must be set for the different access modes you can see at the description of the CmAccess2 () function

mulProductCode contains the Product Code of the access mode. Which Product Code must be set for the different access modes you can see at the description of the CmAccess2 () function

mulFeatureCode contains the Feature Code, which must map a given Feature Map. If the Feature Code is 0, there is no search for a matching Feature Map.

mulUsedRuntimeVersion contains the minimum runtime version of CodeMeter. To calculate the version you may want to use the macro (see hmtoggle_plus1 CM_SET_VERSION).

Macro CM_SET_VERSION

CM_SET_VERSION(a, b, c) sets the complete version in a CMULONG value.

•a: sets the major version.

•b: sets the minor version.

•c: sets the build version.

Syntax

#define CM_SET_VERSION(a,b,c) (((a) & 0xff) \

(((a) & 0xff) << 24) | (((b) & 0xff) << 16) | ((c) & 0xffff)

 

mulReserved1 is reserved for future purposes.

musProductItemReference Product Item Reference of the Product Item to access.

mbMinBoxMajorVersion contains the minimum major Firmware version of the CmContainer to access.

mbMinBoxMinorVersion contains the minimum minor Firmware version of the CmContainer to access.

musBoxMask contains the box mask of the CmContainer to access.

mulSerialNumber contains the serial number of the CmContainer to access.

mulLicenseQuantity contains the requested number of licenses to be allocated using a single handle.

information_weiss_klein26

Using this parameter requires that licenses must have a PIO License Quantity which is bigger than 1 and CodeMeter Version 6.20 must be installed.

For compatibility reasons Wibu-Systems recommends to set Version 6.20 as mimimum used version (mulUsedRuntimeVersion).

If the set runtime version is smaller than the minimum version, the access is canceled and the error message CMERROR_INVALID_PARAMETER displays.

If the requested license quantity is bigger than the number of available licenses, the error message CMERROR_NO_MORE_LICENSES displays.

mszServername contains the name or IP-address of the CodeMeter server to access. The type is detected automatically.

mcmReleaseDate contains a structure where the Release Date can be set that is checked against the Maintenance Period of the license (see hmtoggle_plus1 CMTIME).

Structure CMTIME

CMTIME sets or gets the time to or from a CmContainer.

Syntax

typedef struct __CMTIME {

CMUSHORT musYear;

CMUSHORT musMonth;

CMUSHORT musDay;

CMUSHORT musHours;

CMUSHORT musMinutes;

CMUSHORT musSeconds;

CMULONG mulSecondsSince01_01_2000;

} CMTIME;

Parameter

musYear specifies the value of the year (e.g. 2003).

musMonth specifies the value of the month (1..12).

musDay specifies the value of the day (1..31).

musHours specifies the value of the hours (0..23).

musMinutes specifies the value of the minutes (0..59).

musSeconds specifies the value of the seconds (0..59).

mulSecondsSince01_01_2000 specifies the time in seconds since 01/01/2000.

 

mabCmActId allows to specify a CmAct-ID using the following ranges: 1**** for CmDongle, 2****for CmActLicense, 3**** for CmCloud (not yet implemented).

information_weiss_klein26

Please note that a handle is returned only, if the entries match. Otherwise the error message CMERROR_CMACTID_DOES_NOT_MATCH displays.

mabReserved is reserved for future purposes.

mcmBorrowData contains a hmtoggle_plus1 CMBORROWDATA structure, where the settings for License borrowing can be set. License borrowing is available since CodeMeter Version 4.0 and requires special programming of a license container. For easy access to borrowing functionality please refer to CmBorrow().

Structure CMBORROWDATA

CMBORROWDATA stores all needed parameters needed for borrowing a license. It is used within CmAccess2() and can be filled with CmGetInfo.

information_weiss_klein26

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.

Syntax

typedef struct __CMBORROWDATA {

CMULONG mulStatus;

CMUSHORT midEnableBlock;

CMUSHORT midCps;

CMULONG mulFirmCode;

CMULONG mulProductCode;

CMULONG mulFeatureMap;

CMUSHORT musReserved;

CMUSHORT musBoxMask;

CMULONG mulBoxSerial;

CMBYTE mabSerialPublicKey[CM_PUBLIC_KEY_LEN];

CMBYTE mabServerID[CM_BORROW_SERVERID_LEN];

char mszClientName[128];

CMBYTE mabTrailingValidationBlock[CM_TVB_LEN];

CMULONG mulClientRequestTime;

CMULONG mulMaintenancePeriodStart;

CMULONG mulMaintenancePeriodEnd;

} CMBORROWDATA;

Parameter

mulStatus contains the current status of the enabling block:

nav_open CM_EBI_DISABLED the entry is disabled, the license can not be used at the client.

nav_open CM_EBI_ENABLED the entry is enabled, the license can be used at the client.

midEnableBlock contains the index of the enabling block used for the borrowing operation.

midCps contains the used copy protection system on client side:

nav_open CM_CPS_CODEMETER The borrowing client is using CmDongle.

nav_open CM_CPS_CODEMETERACT The borrowing client is using CmActLicense.

mulFirmCode contains Firm Code of the borrow license on the client side.

mulProductCode contains the Product Code of the borrow license on the client side.

mulFeatureMap contains the Feature Map of the borrow license on the client side.

musReserved is reserved for future purposes.

musBoxMask contains the box mask of the license container on the client side.

mulBoxSerial contains the serial number of the license container on the client side.

mabSerialPublicKey contains the Public Serial Key of the license container on the client side.

mabServerID contains the id of the borrow server.

mszClientName contains the DNS name of the borrowing client.

mabTrailingValidationBlock contains the trading validation block that allows a validation of the contents of this structure.

mulClientRequestTime contains the system time of the client.

mulMaintenancePeriodStart contains the start date of the Maintenance Period of the Product Item, if available.

mulMaintenancePeriodEnd contains the end date of the Maintenance Period of the Product Item, if available

 

mcmCredential contains a hmtoggle_plus1 CMCREDENTIAL structure, where some settings for the access to a license server can be set.

Structure CMCREDENTIAL

CMCREDENTIAL holds parameters that can be used for a CmAccess2() call to refine the license allocation and the assignment to the CodeMeter License Server, for example, via an arbitrary user name.

Syntax

typedef struct __CMCREDENTIAL {

CMULONG mulPID;

CMULONG mulSession;

CMULONG mulCleanupTime;

CMULONG mulMaxLifeTime;

CMULONG mulCreationTime;

CMULONG mulAccessCtrl;

CMULONG mulUserDefinedID;

char mszUserDefinedText[128];

char mszUsername[32];

CMULONG mulCurrentCmInstanceUid;

CMULONG mulPreviousCmInstanceUid;

char mszDomainName[16];

char mabReserved2[4]

} CMCREDENTIAL;

Parameter

mulPID contains the process ID that is set by the CodeMeter library (read only).

mulSession is always zero on the user site.

mulCleanupTime this parameter overwrites the CleanupTime profiling value for license releasing in minutes.

mulMaxLifeTime defines the maximum lifetime (in minutes) of the license that is allocated.

mulCreationTime holds the creation time of the license that was accessed in seconds since 01.01.2000.

mulAccessCtrl holds the type of access (since 4.20):

The first group of flags hold information about local or Lan access:

nav_openCM_CRED_LICENSE_LOCATION_LOCAL handle to the local system.

nav_openCM_CRED_LICENSE_LOCATION_LAN handle to a network system.

The second group defines the access type:

nav_openCM_CRED_HANDLE_ACCESS_ENTRY an entry handle.

nav_openCM_CRED_HANDLE_ACCESS_FI a Firm Item handle.

nav_openCM_CRED_HANDLE_ACCESS_BOX a box handle.

nav_openCM_CRED_HANDLE_ACCESS_SUBSYSTEM a subsystem handle.

mulUserDefinedID contains the user defined ID.

mszUserDefinedText contains a user defined text (UTF-8 encoded).

mszUsername holds an arbitrary user name (read only).

 

 

 

Return

The handle to the desired CmContainer entry or CmContainer in the desired subsystem is returned. If no matching CmContainer entry or CmContainer is found, NULL is returned.

Notes

Access to Firm Item 0 can only be performed locally. If tried using CmLAN, CmAccess2 will trigger Error 200 (Entry not found).

CmAccess2() is supported since CodeMeter Version 3.30.

The following flags (and the corresponding functionality) are only available since CodeMeter Version 5.0:

•CM_ACCESS_LANWAN

•CM_ACCESS_LOCAL_LANWAN

•CM_ACCESS_LANWAN_LOCAL