Skip to content

CoPilot SDK Licensing

For an overview of CoPilot Licensing also see CoPilot Licensing.

Msg_ActivateLicense

This function use to activate the license by passing the product key. Response of the activation is being send by Msg_ID_LicenseResponse. Register callback on Msg_ID_LicenseResponse to receive the activation response.

When licensing map data only one single region can be activated on a device cia this API. If PAN region maps are installed, following the activation of one single key region, a second single region key cannot be activated. If upgrading to additional map data following a sing region activation, this API only supports the upgrade to a PAN region.

Supported Since Minimum Operating System
CoPilot 9.2.0* Windows 10, Android 4.1

Note

When reactivating a license that has already been activated on a device, it must be reset before activated. For example, the following sequence would be required`

  1. Activate using Msg_ActivateLicense resetOpt set to activate
  2. Deactivate using Msg_DeactivateLicense
  3. Reset using Msg_ActivateLicense resetOpt set to reset
  4. Activate using Msg_ActivateLicense resetOpt set to activate

* This API is not supported in v9.2.1

Syntax (Prototyped in alkmsg.h)

long Msg_ActivateLicense(const char * pProductKey,
                               EActivationOptions resetOpt);

Parameters

Parameter Description
pProductKey Product Key
resetOpt Option to define whether activate, reset or extend the product key.

Return Value

  • ≤ 0 - Failed
  • > 0 - Successful

enum EActivationOptions

{
ACTIVATE_OPT_OFFLINE_EPK   = 4, //Offline activate the license with number of days in
                                //the product key

ACTIVATE_OPT_RESET_OFFLINE = 5, //Offline reactivate the license with number of days
                                //in the product key offline

ACTIVATE_OPT_EXTEND_OFFLINE = 6 //Offline license will be reactivated and the
                                //expiration period will include the number of
                                //remaining days from the previous activation and the
                                //number of days included in the Enterprise key.
};

Notes

  • It is advisable to restart the CoPilot after successful activation so all the global objects are properly initialize.
  • Response of the activation is being send by Msg_ID_LicenseResponse. Msg_GetLicenseNotification responsible to retrieve the error code from Msg_ID_LicenseResponse.

Msg_DeactivateLicense

This function use to deactivate the license by passing the product key. Response of the deactivation is being send by Msg_ID_LicenseResponse. Register callback on Msg_ID_LicenseResponse to receive the deactivation response.

Supported Since Minimum Operating System
CoPilot 9.2.0* Windows 10, Android 4.1

* This API is not supported in v9.2.1

Note

Once Msg_DeactivateLicense has been used and you wish to reactivate the same license on the same device. Msg_ActivateLicense resetOpt reset must be used before activating the license again.

Syntax (Prototyped in alkmsg.h)

long Msg_DeactivateLicense(const char * pProductKey, EActivationOptions resetOpt);

Parameters

Parameter Description
pProductKey Product Key
resetOpt Option to define whether deactivate online or offline.

Return Value

  • ≤ 0 - Failed
  • > 0 - Successful
enum EActivationOptions
{
  ACTIVATE_OPT_OFFLINE_EPK    = 4, // Deactivate the product key offline
  ACTIVATE_OPT_RESET_OFFLINE  = 5, // Not in use
  ACTIVATE_OPT_EXTEND_OFFLINE = 6  // Not in use
};

Notes

Response of the deactivation is being send by Msg_ID_LicenseResponse. Msg_GetLicenseNotification responsible to retrieve the error code from Msg_ID_LicenseResponse.


Msg_LicenseStatus

This function use to retrieve the license information associated with given product key. Response of the status request is being send by Msg_ID_LicenseStatus. Register callback on Msg_ID_LicenseStatus to receive the license status associated with given product key.

If checking the status of more than one product key, all keys may be passed via this API at the same time. This will reduce the time taken to receive the license status results. Results will be received via the Msg_ID_LicenseStatus callback in the order in which the keys were passed via the API in a FIFO basis.

Supported Since Minimum Operating System
CoPilot 9.2.0* Windows 10, Android 4.1

* This API is not supported in v9.2.1

Syntax (Prototyped in alkmsg.h)

long Msg_LicenseStatus(const char * pProductKey);

Parameters

Parameter Description
pProductKey Product Key

Return Value

  • ≤ 0 - Failed
  • > 0 - Successful

Notes

Response of the status request is being send by Msg_ID_LicenseStatus. Register callback on Msg_ID_LicenseStatus to receive the license status associated with given product key.


Msg_GetLicenseNotification

This function is helper function to decode the response received in context of Msg_ActivateLicense and Msg_DeactivateLicense. This function is also use when CoPilot send the notification regarding license when CoPilot start up. It is strongly recommend user to register callback function for Msg_ID_LicenseResponse as immediately after Msg_StartUp so user can catch the license notification send by CoPilot.

Supported Since Minimum Operating System
CoPilot 9.2.0* Windows 10, Android 4.1

* This API is not supported in v9.2.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetLicenseNotification(const void * pBuffer,
                              unsigned int lBufLen,
                              ELicenseResponseType &response,
                              int &lStatus);

Parameters

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
response Whether response received in context of Msg_ActivateLicense, Msg_DeactivateLicense or notification from CoPilot.
lStatus Status code. Either success or detailed error code. Please see the status code and its description

Return Value

  • \<0 - Error
  • ≥0 - Successful
enum ELicenseResponseType
{
  License_Activation_Response=0, // Activation Response
  License_Deactivation_Response, // Deactivation Response
  License_Notification           // CoPilot send notification during the startup
};

//Status Codes Description

//Generic success
#define LIC_SUCCESS 0

//Product Key Errors
#define PK_SUCCESS LIC_SUCCESS
#define PK_ERR_INVALID_PARAMS -601
#define PK_ERR_PK_LEN -602
#define PK_ERR_CHECKSUM -603
#define PK_ERR_FORMAT -604
#define PK_ERR_INVALID_CHARS -605
#define PK_NOT_FOUND -606
#define PK_VERSION_MISMATCH -607
#define PK_BASEKEY_REQUIRED -608
#define PK_DUPLICATE -609
#define PK_ERR_HASH                   -610
#define PK_ERR_BASEKEY_STILLACTIVE    -611

//License Check Error/Warnings
#define LIC_NO_LICENSE_FILE           -701
#define LIC_IN_GRACE_PERIOD           -702
#define LIC_EXPIRED                   -703
#define LIC_FILE_CORRUPT              -704
#define LIC_GRACE_PERIOD_EXPIRED      -705
#define LIC_DEVICE_MISMATCH           -706
#define LIC_WRITE_FAILED              -707
#define LIC_PRODUCT_MISMATCH          -708
#define LIC_ENTERPRISE_MISMATCH       -709
#define LIC_NO_LICENSE                -710
#define LIC_DATA_REGION_MISMATCH      -711
#define LIC_READ_FAILED               -712
#define LIC_DEACTIVATED               -713
#define LIC_WILL_EXPIRE               -714
#define LIC_BASEKEY_REQUIRED          -715
#define LIC_ILLEGAL_DEVICE            -716
#define LIC_DATA_VERSION_MISMATCH     -717
#define LIC_USER_LIMIT_EXCEEDED       -718
#define LIC_NET_SHARE_MISMATCH        -719
#define LIC_ERROR_UNKNOWN             -720
#define LIC_LICENSE_NOT_FOUND         -721
#define LIC_FREE_TRIAL_ALREADY_USED   -722
#define LIC_ANDROID_CHECK_FAILED      -723
#define LIC_PCMTRAFFIC_PROMO_EXISTS   -724
#define LIC_ANDROID_CHECK_CONN_FAIL   -725
#define LIC_ANDROID_CHECK_NO_RESPONSE -726
#define LIC_PASS_INCORRECT            -727
#define LIC_PASS_NOPASS               -728
#define LIC_PASS_DONTMATCH            -729
#define LIC_PASS_GENERALERROR         -730
#define LIC_INVALID_FEATURE           -731
#define LIC_CP_PRO_PRODUCT_INACTIVE   -754

Msg_GetLicenseStatus

This function is helper function to decode the response received in context of Msg_LicenseStatus.

Supported Since Minimum Operating System
CoPilot 9.2.0* Windows 10, Android 4.1

* This API is not supported in v9.2.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetLicenseStatus(const void * pBuffer,
                                unsigned int lBufLen,
                                LicenseStatus &licenseStatus);

Parameters

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
licenseStatus License status information

Return Value

Less than 0 - Error Greater than or equal to 1 - Successful

struct LicenseStatus
{
        long m_lError;        //Error code… If lError \<0 then all subsequent
                              //informations not being used.
        long m_iStatus;       //Status of the license
        long m_enterprise;    //1 : Enterprise license or 0: Consumer license
        long m_bActivated;    //1: Activated 0: Not activated
        long m_daysRemaining; //Number of days remaining
};

Notes

User need to call Msg_LicenseStatus which is responsible for send license status. Response of the license status is being send by Msg_ID_LicenseStatusResponse.


Msg_GetCurrentMapRegion

This API will be used following Msg_ActivateLicense to determine which map region CoPilot is currently locked to for licensing purposes, or to determine that a map region has not yet been selected. This should be used following the activation of a major region license, for instance, UK, France or DACH. It is not required if you have a PAN region license as there is no selection necessary.

This can be used in conjunction with Msg_GetAllowedMapRegions() and Msg_SetLockedMapRegion() to manage the selection of a map region programmatically.

Use the following APIs to parse responses from Msg_GetCurrentMapRegion()

  Msg_ParseMapRegionResponseActionCode()
  Msg_ParseMapRegionResponseStatusCode()
  Msg_ParseMapRegionResponseNumberOfRegions()
  Msg_ParseMapRegionResponseRegionInfo()
Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetCurrentMapRegion()

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Msg_GetAllowedMapRegions

This API will be used following Msg_ActivateLicense to determine a list of the available map data regions with the current license. This should be used following the activation of a major region license, for instance, UK and Ireland, France or DACH. It is not required if you have a PAN region license as there is no selection necessary.

This can be used in conjunction with Msg_GetCurrentMapRegion() and Msg_SetLockedMapRegion() to manage the selection of a map region programmatically.

Use the following APIs to parse responses from Msg_GetAllowedMapRegions()

Msg_ParseMapRegionResponseActionCode()
Msg_ParseMapRegionResponseStatusCode()
Msg_ParseMapRegionResponseNumberOfRegions()
Msg_ParseMapRegionResponseRegionInfo()
Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetAllowedMapRegions()

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Msg_SetLockedMapRegion()

This API can be used to specify the map region CoPilot will use, on the condition that the current license allows for that region as determined by Msg_GetAllowedMapRegions. Once a region has been set it can not be changed.

This can also be used in conjunction with Msg_GetCurrentMapRegions() to manage the selection of a map region programmatically.

Use the following APIs to parse responses from Msg_SetLockedMapRegion()

Msg_ParseMapRegionResponseActionCode()
Msg_ParseMapRegionResponseStatusCode()
Msg_ParseMapRegionResponseNumberOfRegions()
Msg_ParseMapRegionResponseRegionInfo()
Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SetLockedMapRegion(unsigned int regionId)

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Msg_ParseMapRegionResponseActionCode()

This API can be used to interpret the data received from Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions(), Msg_SetLockedMapRegion(). This will provide the action code related to the callback and indicate which API the response you have received relates to.

Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ParseMapRegionResponseActionCode(const void* pBuffer, int lBufLen, int& actionCode)

Return Values

  • ≤ 0 - Failed
  • 0 - Successful

Parameters

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
actionCode The action code indicating which operation the response relates to. The value can be one of the following, Get Current Region Get Allowed Regions Set Region

Msg_ParseMapRegionResponseStatusCode

This API can be used to interpret the data received from Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions(), Msg_SetLockedMapRegion(). This will provide the action code related to the callback and indicate the status of the response you have received.

Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ParseMapRegionResponseStatusCode(const void* pBuffer, int lBufLen, int& actionCode )

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Parameters

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
actionCode The status code indicating the outcome of the operation the response relates to. The status code can be None Success No Regions Available Lock Region Failed Region Not Allowed No Region Locked Region Already Locked No License

Msg_ParseMapRegionResponseNumberOfRegions

This API can be used to determine the number of regions that are included in a response from a call to either Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions () or Msg_SetLockedMapRegion(). Use this API alongside Msg_ParseMapRegionResponseRegionInfo() to extract more detailed information about each region that was included in the response.

Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ParseMapRegionResponseNumberOfRegions(const void* pBuffer, int lBufLen, int& count )

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Parameters

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
count The number of map regions included in the response. If there is no map region information available, then this will be zero.

Msg_ParseMapRegionResponseRegionInfo

This API can be used to extract the map region info included in a response from a call to either Msg_GetCurrentMapRegion()Msg_GetAllowedMapRegions or Msg_SetLockedMapRegion(). Use this API alongside Msg_ParseMapRegionResponseNumberOfRegions() to extract more detailed information about each region that was included in the response.

Supported Since Minimum Operating System
CoPilot 9.6.8 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ParseMapRegionResponseRegionInfo(const void* pBuffer, int lBufLen, int& regionId, char* regionName, int regionNameLen)

Return Values

  • ≤ 0 - Failed
  • > 0 - Successful

Parameters

Parameter Description
pBuffer The message buffer
lBufLen The message buffer length
regionIndex The index of the map region in the response’s set of results which you want to extract. Use Msg_ParseMapRegionResponseNumberOfRegions() to check how many regions are available in the response.
regionId This will contain the map ID of the region, which you can then use with API Msg_SetLockedMapRegion() to set the map region.
regionName This will contain the name of the region. You should specify how much space you have allocated for regionName buffer in the next parameter regionNameLen.

Last update: June 17, 2020