CoPilot SDK Licensing

For an overview of CoPilot Licensing also see CoPilot Licensing.

Msg_GetActiveAMSUser

This function is used to get information about the current user who is logged in to CoPilot using Account Manager credentials. The retrieved Account Manager info is returned via Msg_ID_AMSUserInfoResponse.

Syntax

Alkmsg.h

long Msg_GetActiveAMSUser();

AlkMsg.java

long Msg_GetActiveAMSUser();

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.

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

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.

* 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

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.

* This API is not supported in v9.2.1

Syntax (Prototyped in alkmsg.h)

long Msg_LicenseStatus(const char * pProductKey);

Parameters

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 MsgActivateLicense 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.

* 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

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.

* 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

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
                              //information is 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()

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()

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()

Syntax (Prototyped in alkmsg.h)

long Msg_SetLockedMapRegion(unsigned int regionId)

Return Values

• ≤ 0 - Failed

• 0 - Successful

Msg_ParseAMSUserInfoResponse

This is a helper function used to decode the response received in context of Msg_ID_AMSUserInfoResponse.

Syntax

Alkmsg.h

long Msg_ParseAMSUserInfoResponse(const void* pBuffer, unsigned int lBufLen, char* pAssetID, int assetLen, char* pCompanyID, int companyLen, char* pExternalAcctID, int externalAcctLen, char* pPartnerID, int partnerLen);

Alkmsg.java

long Msg_ParseAMSUserInfoResponse (long pBuffer, int lBufLen, byte[] pAssetID, int assetLen, byte[] pCompanyID, int companyLen, byte[] pExternalAcctID, int externalAcctLen, byte[] pPartnerID, int partnerLen);

Parameters

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.

Syntax (Prototyped in alkmsg.h)

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

Return Values

• ≤ 0 - Failed

• 0 - Successful

Parameters

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.

Syntax (Prototyped in alkmsg.h)

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

Return Values

• ≤ 0 - Failed

• 0 - Successful

Parameters

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.

Syntax (Prototyped in alkmsg.h)

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

Return Values

• ≤ 0 - Failed

• 0 - Successful

Parameters

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.

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