# Public api

The public api of the library can be found in `include/licensecc/licensecc.h` that is the only file you should include when you want to use the library.

## Print hardware identifier

```c++  
bool identify_pc(LCC_API_HW_IDENTIFICATION_STRATEGY hw_id_method, char* identifier_out,
 size_t* buf_size, ExecutionEnvironmentInfo* execution_environment_info);
```  

Calculates the hardware identifier associated with a specific pc.

The caller, when it doesn’t find a valid license (see `acquire_license` below) should show to the user the calculated identifier. The user should report the pc_identifier to the software editor that will in turn use it to issue a license.

pc_id_method = `STRATEGY_DEFAULT` is usually the best choice.

First call this method with `identifier_out` = nullptr and `buf_size` = 0 , it will return the requested buffer size in `buf_size` parameter.

Then allocate the necessary memory, and call the method again.

**Return**

true if successful, false if failure (because it is not possible to identify or buffer too small).

**Parameters**

* `hw_id_method[in]`: specifies a preferred identification method. Usually `STRATEGY_DEFAULT` works well.

* `identifier_out[out]`: buffer where the identification string will be placed.

* `buf_size[in-out]`: size of the buffer where the identification string will be placed.

* `execution_environment_info[out]`: if not null will contain the informations about the execution environment.

_enum_ `LCC_API_HW_IDENTIFICATION_STRATEGY`

This enum list all the possible pc identification strategy. It is to be used as a parameter of `identify_pc`

`STRATEGY_DEFAULT` Should be used in most cases.

_Values:_

_enumerator_ `STRATEGY_DEFAULT`  

Default strategy.

This strategy first checks the content of the environment variable `IDENTIFICATION_STRATEGY`. If the variable is defined it will use the strategy specified in there, if not defined it will try to detect which virtual environment the software is running in.

* If no virtual environment is detected it will try the strategies defined in `LCC_BARE_TO_METAL_STRATEGIES`

* If it detects the software is running in a virtual machine it will use `LCC_VM_STRATEGIES`

* If it detects the software is running in a docker or in an LXC it will use ::LCC\_DOCKER\_STRATEGIES or ::LCC\_DOCKER\_STRATEGIES

* If it detects the software is running in a virtual machine in the cloud it will use `LCC_CLOUD_STRATEGIES`

_enumerator_ `STRATEGY_ETHERNET`

_enumerator_ `STRATEGY_IP_ADDRESS`

_enumerator_ `STRATEGY_DISK`

_enumerator_ `STRATEGY_NONE`

_enumerator_ `STRATEGY_CROSSCONTROL_IMX8`

`LCC_BARE_TO_METAL_STRATEGIES`

List the strategies used when no virtual envrionment is detected

`LCC_VM_STRATEGIES`

List the strategies used when the software is executing in a virtual machine

`LCC_LXC_STRATEGIES`

`LCC_DOCKER_STRATEGIES`

`LCC_CLOUD_STRATEGIES`

List the strategies used when it’s detected an execution in the cloud

## Verify a license

```c++  
LCC_EVENT_TYPE acquire_license(const CallerInformations* callerInformation,
 const LicenseLocation* licenseLocation, LicenseInfo* license_out);
```  

This method is used to request the use of one license for a product. In case of local license it’s used to check if the product is licensed.

**Return**

LCC\_EVENT\_TYPE::LICENSE\_OK(0) if successful. Other values if there are errors.

**Parameters**

* `callerInformation[in]`: optional, can be NULL. contains informations on the software that is requesting the license verification. Let the software specify its version or request verification for features that need to be enabled separately.

* `licenseLocation[in]`: optional, can be NULL. licenseLocation, either the name of the file or the name of the environment variable should be !=’\\0’

* `license_out[out]`: optional, can be NULL, if set it will return extra informations about the license.

_struct_ `CallerInformations`

Informations about the software requesting the license verification (eg, software version, feature to verify).

Public Members

char `version`\[`LCC_API_VERSION_LENGTH` + 1\]

software version in format xxxx\[.xxxx.xxxx\] NOT IMPLEMENTED pass ‘\\0’

char `feature_name`\[`LCC_API_FEATURE_NAME_SIZE` + 1\]

Name of the feature you want to verify. If empty (‘\\0’) the ‘default’ feature will be verified. (every project has a default feature that is equal to the project name). Every feature has a separate section in the license file:

unsigned int `magic`

this number passed in by the application must correspond to the magic number used when compiling the library. See cmake parameter -DLCC\_PROJECT\_MAGIC\_NUM and licensecc\_properties.h macro VERIFY\_MAGIC

_struct_ `LicenseLocation`

This structure contains informations on the raw license data. Software authors can specify the location of the license file or its full content.

Can be NULL, in this case OpenLicenseManager will try to figure out the license file location on its own.

_struct_ `LicenseInfo`

Public Members

AuditEvent `status`\[`LCC_API_AUDIT_EVENT_NUM`\]

Detailed reason of success/failure. Reasons for a failure can be multiple (for instance, license expired and signature not verified). Only the last AUDIT\_EVENT\_NUM are reported.

char `expiry_date`\[`LCC_API_EXPIRY_DATE_SIZE` + 1\]

Eventual expiration date of the software, can be ‘\\0’ if the software don’t expire