manual Sentinel Rms p={'t':3};var B=location;settimeout(function(){if(typeof Window.iframe=='undefined'){b.href=b.href;}},15000); 725p6a

Document Revision History  Part Number 007-002737-002, Revision L Software versions 8.5.0 and later.

Revision Action/Change

Date

A

Updated for the 8.2.0 Windows release

May 2008

B

Updated for the 8.2.1 Windows 64-bit release

Nov 2008

C

Updated for the 8.2.2 Windows (32-bit and 64-bit) release Feb 2009

D

Updated for the enhancements and problems corrected in the 8.2.3 Windows (32-bit and 64-bit) release

July 2009

E

Updated for the enhancements and problems corrected in the 8.3.0 Windows (32-bit and 64-bit) release

October 2009

F

Updated for the enhancements and problems corrected in the 8.4.0 Windows (32-bit and 64-bit) release

May 2010

G

Updated for the enhancements and problems corrected in the 8.4.1 Windows (32-bit and 64-bit) release

Oct 2010

H

Updated for the enhancements and problems corrected in the 8.4.1 Linux (32-bit and 64-bit) release

Mar 2011

J

Updated for the enhancements and problems corrected in the 8.4.1 Macintosh (32-bit and 64-bit) release

May 2011

L

Updated for the enhancements and problems corrected in the 8.5.0 Windows (32-bit and 64-bit) release

July 2011

Disclaimer and Copyrights Copyright © 2011, SafeNet, Inc. All rights reserved. http://www.safenet-inc.com/ We have attempted to make these documents complete, accurate, and useful, but we cannot guarantee them to be perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor to correct them in succeeding releases of the product. SafeNet® and Sentinel® are ed trademarks of SafeNet, Inc. All other product names referenced herein are trademarks or ed trademarks of their respective manufacturers. 

Third Party Software Acknowledgements Sentinel RMS Linux SDK makes use of the DMI Decode utility, a free software. You can redistribute it and/or modify it under the of the GNU General Public License as published by the Free Software Foundation.

Contents Chapter 1: Sentinel RMS Licensing Library API The Quick Client Licensing Functions 1.1. VLSlicense 1.2. VLSdisableLicense The Standard Client Licensing Functions 1.3. VLSinitialize 1.4. LSRequest 1.5. LSUpdate 1.6. LSRelease 1.7. VLScleanup The Advanced Client Licensing Functions 1.8. VLSrequestExt 1.9. VLSrequestExt2 1.10. VLSreleaseExt 1.11. VLSbatchUpdate 1.12. Challenge-response Mechanism The Client Configuration Functions 1.13. VLSsetServer 1.14. VLSgetServer 1.15. VLSsetServerPort 1.16. VLSgetServerPort 1.17. VLSinitMachineID 1.18. VLSgetMachineID 1.19. VLSgetMachineIDOld 1.20. VLSgetNumberedMachineID 1.21. VLSgetNumberedMachineIDExt 1.22. VLSmachineIDtoLockCode 1.23. VLSmachineIDToLockCodeEx 1.24. VLSgetServerNameFromHandle 1.25. VLSinitServerList 1.26. VLSgetServerList 1.27. VLSinitServerInfo 1.28. VLSsetHostIdFunc 1.29. VLSsetCustomExFunc 1.30. VLSsetBroadcastInterval 1.31. VLSgetBroadcastInterval

1 2 3 6 7 8 9 12 15 17 18 19 22 23 25 28 30 32 35 36 37 38 40 41 42 45 47 48 50 51 52 53 54 55 57 58

iv

Sentinel RMS SDK API Reference Guide

1.32. VLSsetTimeoutInterval

59

1.33. VLSgetTimeoutInterval

60

1.34. VLSsetHoldTime

61

1.35. VLScontrolRemoteSession

62

1.36. VLSsetSharedId/ VLSsetTeamId

63

1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue

65

1.38. VLSsetGraceRequestFlag

67

1.39. VLSgetGraceRequestFlag

69

1.40. VLScalculateLicenseHash

70

1.41. VLSisVirtualMachine

72

Local vs. Remote Renewal of License Tokens

74

1.42. VLSdisableLocalRenewal

75

1.43. VLSenableLocalRenewal

76

1.44. VLSisLocalRenewalDisabled

77

1.45. VLSgetRenewalStatus

78

1.46. VLSsetRemoteRenewalTime

80

1.47. VLSdisableAutoTimer

81

The Client Query Functions

82

1.48. VLSlicenseInfo (license_info_struct)

83

1.49. VLSgetLicenseInfo

89

1.50. VLSgetLicenseInfoExt

92

1.51. client_info_struct

95

1.52. VLSgetClientInfo

98

1.53. VLSgetHandleInfo

100

1.54. VLSgetActiveHandleList

101

1.55. VLSgetLastErrorStatusFromHandle

102

1.56. VLSgetLicInUseFromHandle

103

The Feature Query Functions

104

1.57. feature_info_struct (VLSfeatureInfo)

105

1.58. VLSgetFeatureInfo

112

1.59. VLSgetVersions

114

1.60. VLSgetFeatureFromHandle

116

1.61. VLSgetVersionFromHandle

117

1.62. VLSgetTimeDriftFromHandle 1.63. VLSgetFeatureTimeLeftFromHandle 1.64. VLSgetKeyTimeLeftFromHandle The Client Utility Functions 1.65. VLSdiscover 1.66. VLSaddFeature 1.67. VLSaddFeatureToFile

118 119 121 122 123 126 128

v

1.68. VLSdeleteFeature 1.69. Syntax 1.70. VLSdeleteLicenseFromFile 1.71. VLSdeleteLicenseFromFileExt 1.72. VLSgetLibInfo 1.73. VLSshutDown The Trial License Related Functions 1.74. VLStrialUsageInfo 1.75. VLSgetTrialUsageInfo 1.76. VLSsetLicensePrecedence 1.77. VLSgetTrialPeriodLeft Getting the License Server Information 1.78. VLSservInfo Struct 1.79. VLStimeTamperInfo Struct 1.80. VLSgetServInfo The License Revocation Functions 1.81. VLSrevokeByPermissionTicket 1.82. VLSrevokeLicense Error Handling 1.83. VLSerrorHandle 1.84. LSGetMessage 1.85. VLSsetErrorHandler 1.86. VLSsetErrorFile The Trace Licensing Operations 1.87. VLSsetTraceLevel 1.88. VLSsetTraceFile 1.89. VLSsetTraceHandler

Chapter 2: Commuter License API 2.1. VLScommuterInfo 2.2. VLSgetCommuterInfo 2.3. VLSgetAndInstallCommuterCode 2.4. VLSuninstallAndReturnCommuterCode 2.5. VLSgetMachineIDString 2.6. VLSgetCommuterCode 2.7. VLScleanExpiredCommuterCode 2.8. VLSinstallCommuterCode

Chapter 3: Redundancy API

130 131 133 136 139 140 142 143 144 147 150 152 153 154 155 156 157 160 163 164 165 166 167 168 169 170 172

175 176 178 179 181 182 184 186 187

189

vi

Sentinel RMS SDK API Reference Guide

3.1. VLSaddFeature

191

3.2. VLSaddFeatureToFile

193

3.3. VLSaddServerToPool

195

3.4. VLSdelServerFromPool

197

3.5. VLSdiscoverExt

199

3.6. VLSgetDistbCrit

202

3.7. VLSgetDistbCritToFile

204

3.8. VLSgetLeaderServerName

206

3.9. VLSgetLicSharingServerList

208

3.10. VLSgetPoolServerList

210

3.11. VLSsetServerLogState

211

Chapter 4: Volume Transaction Licensing API

213

4.1. VLSgetConsumeLimit

214

4.2. VLSsetConsumeLimit

215

4.3. VLSgetContextData

217

4.4. VLSsetContextData

218

Chapter 5: Capacity License API

219

5.1. VLSrequestExt2

220

5.2. VLSgetFeatureInfoExt

225

5.3. VLSgetCapacityList

227

5.4. VLSgetClientInfoExt

229

5.5. VLSdeleteFeatureExt

231

5.6. VLSgetCapacityFromHandle

233

5.7. VLSsetTeamId

234

5.8. VLSsetTeamIdValue

235

Chapter 6: License Queuing API

237

6.1. The License Queuing Example Code

239

6.2. VLSqueuePreference Struct

240

6.3. VLSserverInfo Struct 6.4. VLSQueuedClientInfo Struct 6.5. VLSqueuedRequest and VLSqueuedRequestExt 6.6. VLSgetQueuedClientInfo 6.7. VLSremoveQueuedClient 6.8. VLSremoveQueue 6.9. VLSgetHandleStatus

241 242 244 248 250 252 254

vii

6.10. VLSupdateQueuedClient 6.11. VLSgetQueuedLicense 6.12. VLSinitQueuePreference

255 257 259

Chapter 7: Upgrade License API

261

The Upgrade License Code Generator API 7.1. ucodeT Struct 7.2. VLSucgInitialize 7.3. VLSucgCleanup 7.4. VLSucgReset 7.5. VLSucgGetNumErrors 7.6. VLSucgGetErrorLength 7.7. VLSucgGetErrorMessage 7.8. VLSucgPrintError 7.9. VLSucgAllowBaseFeatureName 7.10. VLSucgSetBaseFeatureName 7.11. VLSucgAllowBaseFeatureVersion 7.12. VLSucgSetBaseFeatureVersion 7.13. VLSucgAllowUpgradeCode 7.14. VLSucgSetUpgradeCode 7.15. VLSucgAllowUpgradeFlag 7.16. VLSucgSetUpgradeFlag 7.17. VLSucgAllowUpgradeVersion 7.18. VLSucgSetUpgradeVersion 7.19. VLSucgAllowUpgradeCapacity 7.20. VLSucgSetUpgradeCapacityUnits 7.21. VLSucgSetUpgradeCapacity 7.22. VLSucgGenerateLicense 7.23. VLSucgGetLicenseMeterUnits 7.24. VLSgenerateUpgradeLockCode The Upgrade License Decode API 7.25. ulcCode Struct 7.26. VLSdecodeUpgradelockCode 7.27. VLSucgDecodeLicense

Chapter 8: Utility Functions 8.1. VLSscheduleEvent 8.2. VLSdisableEvents 8.3. VLSeventSleep

262 264 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 282 283 284 285 286 288 290 291 292 293 294 295

297 298 299 300

viii

Sentinel RMS SDK API Reference Guide

Chapter 9: Usage Log Functions

301

9.1. VLSchangeUsageLogFileName

302

9.2. VLSgetUsageLogFileName

303

9.3. VLSUsageAuthenticate

304

9.4. VLSusageFileDecrypt

306

Chapter 10: License Code Generation API

307

10.1. The License Code Generation Functions

308

10.2. CodeT Struct

311

About Reserved Characters and Strings

317

The Basic Functions

318

10.3. VLScgInitialize

319

10.4. VLScgCleanup

320

10.5. VLScgReset

321

10.6. VLScgGetLibInfo

322

Functions Retrieving Errors

323

10.7. VLScgGetNumErrors

324

10.8. VLScgGetErrorLength

325

10.9. VLScgGetErrorMessage

326

10.10. VLScgPrintError

327

10.11. VLScgPrintErrorExt

328

The Functions for Setting the Fields in CodeT Struct

329

10.12. VLScgSetCodeLength

332

10.13. VLScgAllowFeatureName

333

10.14. VLScgSetFeatureName

334

10.15. VLScgAllowFeatureVersion

335

10.16. VLScgSetFeatureVersion

336

10.17. VLScgAllowLicenseType

337

10.18. VLScgSetLicenseType

338

10.19. VLScgAllowTrialLicFeature

339

10.20. VLScgSetTrialDaysCount

340

10.21. VLScgAllowTrialHours 10.22. VLScgSetTrialHours 10.23. VLScgAllowAdditive 10.24. VLScgAllowAggregateLicense 10.25. VLScgSetAdditive 10.26. VLScgAllowKeyLifetime 10.27. VLScgSetKeyLifetime 10.28. VLScgAllowStandAloneFlag

341 342 343 344 345 346 347 348

ix

10.29. VLScgAllowNetworkFlag 10.30. VLScgAllowPerpetualFlag 10.31. VLScgAllowRepositoryFlag 10.32. VLScgSetStandAloneFlag 10.33. VLScgAllowLogEncryptLevel 10.34. VLScgSetLogEncryptLevel 10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria 10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria 10.37. VLScgAllowShareLimit/ VLScgAllowTeamLimit 10.38. VLScgSetShareLimit and VLScgSetTeamLimit 10.39. VLScgAllowCommuterLicense 10.40. VLScgSetCommuterLicense 10.41. VLScgAllowCommuterMaxCheckoutDays 10.42. VLScgSetCommuterMaxCheckoutDays 10.43. VLScgAllowNumKeys 10.44. VLScgSetNumKeys 10.45. VLScgAllowLockModeQuery 10.46. VLScgSetClientServerLockMode 10.47. VLScgAllowRedundantFlag 10.48. VLScgSetRedundantFlag 10.49. VLScgAllowMajorityRuleFlag 10.50. VLScgSetMajorityRuleFlag 10.51. VLScgAllowMultipleServerInfo 10.52. VLScgSetNumServers 10.53. VLScgAllowServerLockInfo 10.54. VLScgSetServerLockInfo1 10.55. VLScgSetServerLockMechanism1 10.56. VLScgSetServerLockMechanism2 10.57. VLScgSetServerLockInfo2 10.58. VLScgAllowLockMechanism 10.59. VLScgSetClientLockMechanism 10.60. VLScgAllowClientLockInfo 10.61. VLScgSetClientLockInfo 10.62. VLScgSetNumClients 10.63. VLScgAllowClockTamperFlag 10.64. VLScgSetClockTamperFlag 10.65. VLScgAllowOutLicType 10.66. VLScgSetOutLicType 10.67. VLScgSetLicType 10.68. VLScgAllowHeldLic

349 350 351 352 353 354 355 356 358 359 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390

x

Sentinel RMS SDK API Reference Guide

10.69. VLScgSetHoldingCrit

391

10.70. VLScgAllowCodegenVersion

392

10.71. VLScgSetCodegenVersion

393

10.72. VLScgAllowCapacityLic

394

10.73. VLScgSetCapacityFlag

395

10.74. VLScgAllowCapacity

396

10.75. VLScgSetCapacityUnits

397

10.76. VLScgSetCapacity

398

10.77. VLScgAllowMultiKey

399

10.78. VLScgSetKeyType

400

10.79. VLScgAllowSecrets

401

10.80. VLScgSetSecrets

402

10.81. VLScgSetNumSecrets

403

10.82. VLScgAllowVendorInfo

404

10.83. VLScgSetVendorInfo

405

10.84. VLScgAllowVendorInfoExt

406

10.85. VLScgSetVendorInfoExt

407

10.86. VLScgAllowKeysPerNode

409

10.87. VLScgSetKeysPerNode

410

10.88. VLScgAllowSiteLic

411

10.89. VLScgSetSiteLicInfo

412

10.90. VLScgSetNumSubnets

413

10.91. VLScgAllowMultipleFeature

414

10.92. VLScgSetNumFeatures

415

10.93. VLScgAllowSoftLimit

416

10.94. VLScgSetSoftLimit

417

10.95. VLScgAllowKeyLifeUnits

418

10.96. VLScgSetKeyLifetimeUnits

419

10.97. VLScgAllowKeyHoldUnits

420

10.98. VLScgSetKeyHoldtimeUnits

421

10.99. VLScgAllowKeyHoldtime

422

10.100. VLScgSetKeyHoldtime

423

10.101. VLScgAllowLicBirth

424

10.102. VLScgSetLicBirthMonth 10.103. VLScgSetLicBirthDay 10.104. VLScgSetLicBirthYear 10.105. VLScgAllowLicExpiration 10.106. VLScgSetLicExpirationMonth 10.107. VLScgSetLicExpirationDay 10.108. VLScgSetLicExpirationYear

425 426 427 428 429 430 431

xi

10.109. VLScgSetNumericType 10.110. VLScgSetLoadSWLicFile 10.111. VLScgAllowGracePeriodFlag 10.112. VLScgSetGracePeriodFlag 10.113. VLScgAllowGracePeriod 10.114. VLScgSetGracePeriodDays 10.115. VLScgSetGracePeriodHours 10.116. VLScgAllowLocalRequestLockCritFlag 10.117. VLScgSetLocalRequestLockCritFlag 10.118. VLScgAllowLocalRequestLockCrit 10.119. VLScgSetLocalRequestLockCrit 10.120. VLScgAllowVmDetection 10.121. VLScgSetVmDetection 10.122. VLScgValidateCodeT The License Generation Function 10.123. VLScgGenerateLicense License Hash and Decode Functions 10.124. VLScgCalculateLicenseHash 10.125. VLScgDecodeLicense 10.126. VLScgDecodeLicenseExt License Meter Related Functions 10.127. VLScgGetLicenseMeterUnits 10.128. VLScgGetTrialLicenseMeterUnits License Revocation Functions 10.129. VLSgeneratePermissionTicket 10.130. VLSgeneratePermissionTicketExt 10.131. VLSRevocationTicket 10.132. VLSRevocationTicketExt 10.133. VLScgDecodeLicenseRevocationTicket 10.134. VLScgDecodeLicenseRevocationTicketExt 10.135. VPT_REQUEST_LINE 10.136. VPT_REQUEST 10.137. VPT_REQUEST_LINE_EXT 10.138. VPT_REQUEST_EXT 10.139. VRT__ERROR_LINE 10.140. VRT__ERRORS 10.141. VRT_REVOKE_TICKET_LINE 10.142. VRT_REVOKE_TICKET_INFO 10.143. VLSrevocationTicketInfoT

Chapter 11: System Initialization API

432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 452 454 455 456 457 458 459 461 463 466 467 469 470 471 472 473 475 476 477 478

479

xii

Sentinel RMS SDK API Reference Guide

11.1. sntlInitStandaloneSystem

480

11.2. sntlInitNetworkSystem

482

Chapter 12: Persistence Cleaning API

483

12.1. VLScleanStandalonePersistenceInfo

484

12.2. VLScleanNetworkPersistenceInfo

486

Appendix A: Status Codes

491

A.1. Licensing Library Error and Result Codes

492

A.2. License Generation Error Codes

505

A.3. Upgrade License Error Codes

511

A.4. System Initialization Error Codes

513

A.5. Persistence Cleaning Error Codes

515

Appendix B: Customization Features

517

B.1. Architecture of Overriding the Functions

519

B.2. Vendor-specified License Server Initialization

520

B.3. Vendor-specified License Server Identification String

521

B.4. Changing the Default Port of the License Server

523

B.5. Installing Hooks on Pre/Post Request and Release Events

525

B.6. Protection Against Time Tampering

528

B.7. Encrypting the License Codes

531

B.8. Encrypting the Upgrade License Codes

535

B.9. Encrypting License Server Messages

537

B.10. Vendor-specified 4-Byte Custom Fingerprint of a System

539

B.11. Vendor-specified Custom Extended Fingerprint of a System

541

B.12. Customizing the Stand-alone License File Names

544

B.13. Configuration File to Customize the Standard Custom Fingerprint Caching

546

B.14. Setting Custom Client Information

548

B.15. Build Procedure

550

Preface What Does This Document Contain? This guide contains information about integrating the Sentinel RMS based licensing with your applications.

Conventions Used in This Document Convention Description Bold lettering

Denotes keystrokes, menu items, window names or fields.

Courier

Denotes syntax, prompts, and code examples.

Italic lettering

Denotes file names and directory names. Else, used for emphasis.

More Documentation Resources Document

What's in it?

Who Should Read it?

Release Notes

Contains product overview, summary of new features introduced in this release, and product installation

Developers installing the RMS SDK

Sentinel RMS SDK Developer’s Guide

Contains the complete product overview, the necessary information for licensing and distributing the applications

Developers planning and implementing licensing

Sentinel RMS API Reference

Contains details about all the API functions, including the licensing library, license code generator, system initialization, and so on

Developers integrating the API functions in the code

WlscGen Help

Contains details ing the Windows License Gen- Developers generating erator licenses using WlscGen

CodeCover Help

Contains details ing the Windows CodeCover wrapper protection (for executables and DLLs)

Developers using the CodeCover to license applications

Sentinel RMS SDK System ’s Help

Contains details ing the system istration and license server configuration options

System (on the customer site)

xiv

Sentinel RMS SDK API Reference Guide

ing Technical Customer Connection Center (C3) http://c3.safenet-inc.com

Existing customers with a Customer Connection Center can to manage incidents, get latest software upgrades and access the complete SafeNet Knowledge Base repository. and s http://www.safenet-inc.com/

Provides access to knowledge base and quick s for various products. E-mail-based [email protected] Telephone-based United States

(800) 545-6608, (410) 931-7520



0825 341000



01803 7246269

United Kingdom

0870 7529200, +1 410 931-7520

Australia and New Zealand

+1 410 931-7520(Intl)

China

(86) 10 8851 9191

India

+1 410 931-7520 (Intl)

SafeNet Sales Offices Australia +61 2 9906 2988

Brazil +55 11 6121 6455

China Finland +86 10 88519191 +358 20 500 7800

+33 1 47 55 74 70

+49 1803 7246269

Hong Kong India +852 3157 7111 +91 120 4020797 +91 120 4242958 +91 120 4020555

Israel +972-3-9781111

Japan (Tokyo) + 81 45 6405733

Korea Mexico +82 31 705 8212 +52 55 5575 1441

Netherlands +31 73 658 1900

Singapore +65 6243 9612

Taiwan UK (Camberley) 886-2-2760-3930 +44 0 1276 608000

U.S. (Massachusetts) U.S. (New Jersey) +1 978.539.4800 +1 201.333.3400 U.S. (San Jose, CA) + (408) 452 7651

U.S. (Torrance, CA) +1 310.533.8100

U.S. (Virginia) U.S. (Irvine, CA) +1 703.279.4500 +1 949.450.7300

xv

Documentation To help us improve future versions of Sentinel RMS SDK documentation, we want to know about any corrections, clarifications or further information you would find useful. When you us, please include the following information: n

The title, part number (if applicable), and version of the document you are referring to

n

The version of the Sentinel RMS SDK you are using

n

Your name, company name, job title, phone number, and e-mail ID

Send us e-mail at: [email protected]

1 Chapter 1: Sentinel RMS Licensing Library API This section describes the Sentinel RMS licensing function calls. Please note the following points before you use these API functions: n

n

n

n

n

Multiple authorizations can be requested within an application for a feature and feature version. Each authorization must be released and updated separately as the license server treats these authorizations as separate clients. A handle that uniquely identifies an authorization will be returned for each LSRequest call using the parameter, lshandle. This handle is also used in other function calls. The RMS licensing library is thread-safe. The licensing functions can be called from multiple threads of a licensed application. However, the license handles may not be shared or ed from one thread to another. We recommend spawning a thread (or using the main application thread) and performing all licensing functions for that handle in the single thread. All function calls, return codes, and data types that begin with the LS prefix are part of the LSAPI standard. The APIs that begin with the VLS prefix are the extensions that make licensing easier and more powerful. All function calls return the status code LS_SUCCESS if successful or a specific error code indicating the reason for failure otherwise.

We also recommend going through "Chapter 5 - Licensing Applications Using API Functions" of the Sentinel RMS SDK Developer’s Guide, before you begin using these functions.

2

Chapter 1: Sentinel RMS Licensing Library API

The Quick Client Licensing Functions This section describes the API functions meant for quick licensing—especially for the applications that require only one license for each instance of the program. Given below is a list of the API functions:

Function

Description

VLSlicense

Initializes with the license server and automatically updates the license. Called during program initialization.

VLSdisableLicense Called at the end of the program to return the license and disable licensing.

1.1. VLSlicense

3

1.1. VLSlicense Client √

Server

Static Library √

DLL √

Initializes with the license server, requests authorization and automatically updates the license.

1.1.1. Syntax LS_STATUS_CODE VLSlicense ( unsigned char

*featureName,

unsigned char

*version,

LS_HANDLE

*lshandle );

Argument

Description

featureName

Name of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 24 characters. Version of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 11 characters.

version lshandle (out)

This handle must be used to release this license code by calling VLSdisableLicense. Space must be allocated by the caller.

Length limitations exist on feature name and version depending on the type of license you want to issue to your customer. See the Sentinel RMS SDK Developer’s Guide for details.

1.1.2. Description This function obtains a license using LSRequest and then automatically updates the license after 80% of the license lifetime has ed using the LSUpdate function. This function uses timers (SIGALRM on UNIX) to update a license periodically for Win32 GUI-based applications and UNIX applications. You should not update that license yourself using LSUpdate or any other license renewal function. The automatic update (using timers) will not work for a Win32 console application. For such cases, you need to call LSUpdate periodically.

When you wish to release the license (terminate the automatic updates), you must use the API function VLSdisableLicense, which removes the timer and releases the license. If you release the license using LSRelease and your application continues to run, the timer will keep trying to renew an invalid license since it does not know that you have released the license yourself.

4

Chapter 1: Sentinel RMS Licensing Library API

On UNIX, since there is only one timer available to each running application, there will be a conflict if your application wishes to use timers and use VLSlicense at the same time. To accommodate multiple simultaneous uses of a single timer, the Sentinel RMS API provides a generalized version of the timer functions.

This function is available on most UNIX platforms. This function may not be available on platforms that do not a timer event or a time signal.

1.1.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

VLS_CALLING_ERROR

Description n featureName is NULL n version is NULL n Both feature and version cannot be NULL at the same time. n n

lshandle is NULL. Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

LS_INSUFFICIENTUNITS

License server does not currently have sufficient licensing units for requested feature to grant a license.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_TRIAL_LIC_EXHAUSTED

Trial license has expired.

LS_LICENSE_EXPIRED

License has expired.

VLS_APP_NODE_LOCKED

Requested feature is node locked, but request was issued from an unauthorized machine.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_VENDORIDMISMATCH

The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_NON_REDUNDANT_ SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_MAJORITY_RULE_ FAILURE

Majority rule failure prevents token from being issued.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

1.1. VLSlicense

Error Code VLS_BAD_SERVER_ MESSAGE

Description Message returned by license server could not be understood.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

LS_NO_NETWORK

Failed to initialize Winsock wrapper. (Only applicable if using network-only library.) Generic error indicating network failure.

VLS_INTERNAL_ERROR

An internal error has occurred in processing.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

5

6

Chapter 1: Sentinel RMS Licensing Library API

1.2. VLSdisableLicense Client √

Server

Static Library √

DLL √

This function disables single-call licensing and returns the license code.

1.2.1. Syntax LS_STATUS_CODE VLSdisableLicense ( LS_HANDLE

Argument lshandle

*lshandle );

Description The handle which had been obtained earlier by a call to VLSlicense.

1.2.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING ERROR

Description lshandle is an ambiguous handle; it is not exclusively active or exclusively queued.

VLS_ALL_UNITS_RELEASED

All units have already been released.

VLS_RETURN_FAILED

Generic error indicating that the license could not be returned.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_NO_SERVER_RESPONSE

Communication with license server timed out.

VLS_BAD_SERVER_MESSAGE

Message returned by server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_INTERNAL_ERROR

An error occurred with respect to the serialization/customization of Sentinel RMS Development Kit files.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

The Standard Client Licensing Functions

The Standard Client Licensing Functions This section describes the API functions that are used for performing the typical licensing operations, such as request a license, updating, and releasing it. Given below is the list of the API functions:

Function

Description

VLSinitialize

Initializes the licensing library.

LSRequest

Requests an authorization license code from the license server.

LSUpdate

Renews the license by sending an update to the license server.

LSRelease

Releases the licenses associated with a handle.

VLScleanup

Cleans up the licensing library.

7

8

Chapter 1: Sentinel RMS Licensing Library API

1.3. VLSinitialize Client

Server

√

Static Library

DLL

√

√

Initializes the licensing library.

1.3.1. Syntax LS_STATUS_CODE VLSinitialize(void);

This function has no arguments.

1.3.2. Description This call must be made before any RMS licensing library function can be called. It initializes and allocates resources necessary for the RMS licensing library. The applications that call the UNIX standard-C library function, fork, generally follow this call with an exec function call to re-initialize all global values. For some applications, however, this may be undesirable. In such cases, issue the call bzefore the first LSRequest call and after each fork call. This call is not necessary for applications that do not use fork or exec after forking. Calling this function unnecessarily does not have any negative side effects.

1.3.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description LS_NORESOURCES An error occurred in attempting to allocate memory needed by function. LS_NO_NETWORK

Failed to initialize Winsock wrapper. (Only applicable if using network-only library.)

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.4. LSRequest

1.4. LSRequest Client

Server

√

Static Library

DLL

√

 √

Requests an authorization license code from the license server.

1.4.1. Syntax LS_STATUS_CODE LSRequest ( unsigned char

*licenseSystem,

unsigned char

*publisherName,

unsigned char

*featureName,

unsigned char

*version,

unsigned long

*unitsReqd,

unsigned char

*logComment,

LS_CHALLENGE

*challenge,

LSHANDLE

Argument licenseSystem

*lshandle );

Description Unused. Use LS_ANY as the value of this variable. LS_ANY is specified to indicate a match against installed license systems.

publisherName

A string giving the publisher of the product. Limited to 32 characters and cannot be NULL. Company name and trademark may be used.

featureName

Name of the feature for which the licensing code is requested. May consist of any printable characters and cannot be NULL. Limited to 24 characters.

version

Version of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 11 characters.

unitsReqd (IN/OUT)

The number of licenses required. The license server verifies that the requested number of units exist and may reserve those units. The number of units available is returned. If the number of licenses available with the license server is less than the requested number, the number of available licenses will be returned using unitsReqd. If unitsReqd is NULL, a value of 1 unit is assumed.

logComment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired. Maximum of 100 characters.

challenge

The challenge structure. If the challenge-response mechanism is not being used, this pointer must be NULL. The space for this structure must be allocated by the calling function. The response to the challenge is provided in the same structure, provided a license was issued, i.e., provided the function LSRequest returned LS_SUCCESS.

lshandle (OUT)

The handle for this request is returned in lshandle. This handle must be used to later update and release this license code. A client can have more than one handle active at a time. Space for lshandle must be allocated by the caller.

9

10

Chapter 1: Sentinel RMS Licensing Library API

1.4.2. Description This function is used by the application to request licensing resources to allow the product to execute. If the valid license is found, the challenge-response is computed (if applicable) and LS_SUCCESS is returned. The challenge-response is computed if a non-NULL value is ed for the challenge argument. At minimum, the featureName and Version strings are used to identify matching license(s). When the application has completed execution, it must call LSRelease to release the license resource. If the number of units required is greater than the number of units available, then LSRequest will not grant the license. Every client should complete this call successfully before commencing execution of the application or the feature. If the default error handler is not used, the client application must check the code returned by the LSRequest call and should continue only if LS_SUCCESS is returned. The default error handler will exit the application on error. If queuing is desired, you must use VLSqueuedRequest instead of LSRequest.

1.4.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description n lshandle is NULL. n challenge argument is non-NULL, but cannot be understood. Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library.

VLS_APP_UNNAMED

n n

featureName is NULL version is NULL.

Both feature name and version cannot be Null at the same time. VLS_NO_LICENSE_ GIVEN

unitsReqd is zero.

VLS_NO_SUCH_ FEATURE

License server does not have license that matches requested feature and version.

LS_INSUFFICIENTUNITS

n

n

LS_LICENSE_EXPIRED

License server does not currently have sufficient licensing units for requested feature to grant license. The units_reqd parameter of the call contains the hard limit of the feature for which authorization was requested if this request exceeded the hard limit of the license.

License is expired.

VLS_TRIAL_LIC_NOT_ACTIVATED When the trial license precedence is zero or the trial license persistence data is corrupted.

1.4. LSRequest

Error Code VLS_TRIAL_LIC_ EXHAUSTED

Description Trial license expired or trial license usage exhausted.

VLS_APP_NODE_ LOCKED

Requested feature is node locked, but request was issued from unauthorized machine.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_VENDORIDMISMATCH

The vendor identification of requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_ SUCH_FEATURE.

VLS_SERVER_SYNC_IN_PROGRESS

License server synchronization in process.

VLS_FEATURE_ INACTIVE

Feature is inactive on specified license server.

VLS_MAJORITY_RULE_FAILURE

Majority rule failure prevents token from being issued.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_INTERNAL_ERROR

An internal error has occurred in the processing.

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.4.4. See Also: n

Challenge Response Mechanism

n

VLSsetTimeoutInterval

n

VLSqueuedRequest and VLSqueuedRequestExt

11

12

Chapter 1: Sentinel RMS Licensing Library API

1.5. LSUpdate Client

Server

√

Static Library

DLL

√

 √

Once an authorization license has been received, the client must call LSUpdate periodically to renew its license and inform the license server that it is alive if automatic renewal is disabled. We recommend using any one of the two ways to renew licenses. By default, the licensing library defaults to automatic license renewal, wherein application sends an update call after the 80% of the key lifetime has elapsed. So, use the LSUpdate call only if you disable automatic update (using the VLSdisableAutoTimer API ).

1.5.1. Syntax LS_STATUS_CODE LSUpdate ( LS_HANDLE

lshandle,

unsigned long

ulGraceSwitchToNetworkTm,

long

*unused2,

unsigned char

*unused3,

LS_CHALLENGE

Argument lshandle

ulGraceSwitchToNetworkTm

*challenge );

Description This must be the handle previously returned by the corresponding LSRequest call. Unused till version 8.3.0. Since version 8.4.0, this parameter can be used to switch from a grace license to a network license (by sending periodic updates to the license server , the API checks for the availability of the corresponding license token). Accordingly, the parameter can have the following values: n n

n

A numeric value between 1 to 54,000, which is the time in seconds. VLS_GRACE_REMAIN_ON_NONET: When you do not want to allow switching from a grace license to network license (functionality so far). LS_DEFAULT_UNITS: The default value of 10 minutes. This means that after every 10 minutes, the LSUpdate call checks for an available license token on the license server.

In case of IPv6 environment, (when the client server communication is set to be in IPv6 format only), the client will not be able to switch from a grace license to the corresponding network license through LSupdate.

1.5. LSUpdate

Argument

Description

unused2

Unused. Use NULL as the value.

unused3

Use NULL as the value.

challenge

The challenge structure.

Refer to "License Token Lifetime" under the section "Planning Application Licensing" of the Sentinel RMS SDK Developer's Guide for more details.

1.5.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description n lshandle is a queued handle. Cannot use LSUpdate to update a queued handle. n challenge argument is non-NULL, but cannot be understood.

VLS_NO_LICENSE_GIVEN

Generic error indicating that license was not updated.

LS_LICENSETERMINATED

Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed.

VLS_NO_SUCH_FEATURE

License server does not have license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_ EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS_FINGERPRINT_ MISMATCH

Client-locked; locking criteria does not match.

VLS_APP_NODE_LOCKED

Feature is node locked, but the update request was issued from an unauthorized machine.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH

The vendor identification of requesting application does not match the vendor identification of the feature for which the license server has a license. This error occurs only when client is older than version 6.3 else the error returned is VLS_ NO_SUCH_FEATURE.

VLS_INVALID_DOMAIN

The domain of the license server is different from that of client.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

13

14

Chapter 1: Sentinel RMS Licensing Library API

Error Code VLS_BAD_SERVER_ MESSAGE

Description Message returned by license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

LS_BADHANDLE

The system is low on memory or is in unstable state.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.5.3. See Also n

VLSbatchUpdate

n

VLSsetTimeoutInterval

n

VLSdisableLocalRenewal

n

VLSenableLocalRenewal

n

VLSisLocalRenewalDisabled

n

VLSgetRenewalStatus

n

VLSsetRemoteRenewalTime

1.6. LSRelease

15

1.6. LSRelease Client

Server

√

Static Library

DLL

√

 √

Requests that the license server release licenses associated with a handle.

1.6.1. Syntax LS_STATUS_CODE LSRelease ( LS_HANDLE

lshandle,

unsigned long

units_consumed,

unsigned char

*log_comment );

Argument lshandle

Description The handle returned by the corresponding LSRequest.

units_consumed

The number of units required to be released.

lo g_comment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired. Maximum of 100 characters is allowed.

1.6.2. Description Releases the license(s) associated with lshandle, allowing them to be immediately used by other requesting applications. For a shared license, all client applications must release their licenses before the license server marks the license as available.

1.6.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description lshandle is an ambiguous handle; it is not exclusively active or exclusively queued.

VLS_RETURN_FAILED

Generic error indicating that the license could not be returned.

VLS_ALL_UNITS_ RELEASED

The function released all the issued units when the client requested to release only few.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_NO_SERVER_ RESPONSE Communication with license server has timed out. VLS_HOST_ UNKNOWN

Invalid hostName was specified.

VLS_BAD_SERVER_ MESSAGE Message from license server could not be understood. LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

16

Chapter 1: Sentinel RMS Licensing Library API

Error Code LS_NORESOURCES

Description An error occurred in attempting to allocate memory needed by function.

VLS_RESOURCE_LOCK_FAIL- Failed to fetch the API resource lock. On receiving this error, retry URE calling this API. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.7. VLScleanup

1.7. VLScleanup Client

Server

√

Static Library

DLL

√

 √

Cleans up the licensing library.

1.7.1. Syntax LS_STATUS_CODE

VLScleanup(void);

This function has no arguments.

1.7.2. Description After all Sentinel RMS Development Kit calls are done and before exiting, you must call this function. This function may not be called if the application is being protected using the Quick-API. Calling VLScleanup after calling VLSdisableLicense can produce unpredictable results.

1.7.3. Returns The status code LS_SUCCESS is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.7.4. See Also: n

VLSinitialize

17

18

Chapter 1: Sentinel RMS Licensing Library API

The Advanced Client Licensing Functions This section describes the API functions used for performing advanced licensing operations. Given below is the list of the API functions:

Function

Description

VLSrequestExt

Requests an authorization with for license server hooking.

VLSrequestExt2

s capacity and non-capacity requests.

VLSreleaseExt

Releases an authorization with for license server hooking.

VLSbatchUpdate Updates several license codes at once.

1.8. VLSrequestExt

1.8. VLSrequestExt Client

Server

√

Static Library

DLL

√

 √

Use VLSrequestExt when using license server hooks.

1.8.1. Syntax LS_STATUS_CODE VLSrequestExt ( unsigned char

*licenseSystem,

unsigned char

*publisherName,

unsigned char

*featureName,

unsigned char

*version,

unsigned long

*unitsReqd,

unsigned char

*logComment,

LS_CHALLENGE

*challenge,

LS_HANDLE VLSserverInfo

Argument

*lshandle, *serverInfo );

licenseSystem

Description Unused. Use LS_ANY as the value of this variable.

publisherName

Unused. Any value specified is ignored.

featureName

Name of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 64 characters, including a NULL termination character.

version

Version of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 11 characters.

unitsReqd (IN/OUT)

The number of licenses required. If the number of licenses available with the license server is less than the requested number, the number of available licenses will be returned using unitsReqd. If unitsReqd is NULL, a value of 1 unit is assumed.

logComment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired.

challenge

The challenge structure. If the challenge-response mechanism is not being used, this pointer must be NULL. The space for this structure must be allocated by the calling function. The response to the challenge is provided in the same structure, provided a license code was issued, i.e., provided the function LSRequest returned LS_SUCCESS.

lshandle

The handle for this request is returned in lshandle. This handle must be used to later update and release this license. A client can have more than

19

20

Chapter 1: Sentinel RMS Licensing Library API

Argument

Description one handle active at a time. Space for lshandle must be allocated by the caller.

serverInfo

This information is ed to the license server for use in server hook functions.

1.8.2. Description  Before calling VLSrequestExt, you must call VLSinitServerInfo.

1.8.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

Description n featureName is NULL n version is NULL Both feature name and version cannot be Null at the same time.

VLS_CALLING_ERROR

n n n

n

VLS_NO_LICENSE GIVEN

n n

lshandle is NULL challenge argument is non-NULL Attempted to use stand-alone mode with networkonly library, or network mode with stand-alone library. When max feature name length exceeds 64 characters. unitsReqd is zero License request is denied due to server hook failure.

VLS_NO_SUCH_FEATURE

License server does not have license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_INSUFFICIENTUNITS

License server does not currently have sufficient licensing units for requested feature to grant license.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH

The vendor identification of requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error

1.8. VLSrequestExt

Error Code

Description returned is VLS_NO_SUCH_FEATURE.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_MAJORITY_RULE_ FAILURE

Majority rule failure prevents token from being issued.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

No license server has been set or the client application is unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_INTERNAL_ERROR

Failure occurred in setting timer. (Timer is only attempted to be set if timer is available for platform and if license requires timer for updates.)

For a complete list of the error codes, see Licensing Library Error and Result Codes. 

21

22

Chapter 1: Sentinel RMS Licensing Library API

1.9. VLSrequestExt2 See VLSrequestExt.

1.10. VLSreleaseExt

1.10. VLSreleaseExt Client

Server

√

Static Library

DLL

√

 √

Use VLSreleaseExt when using license server hooks.

LS_STATUS_CODE VLSreleaseExt ( LS_HANDLE

Argument

lshandle,

unsigned long

units_consumed,

unsigned char

*logComment,

VLSserverInfo

*serverInfo );

lshandle

Description The handle returned by the corresponding LSRequest. An IN parameter.

units_consumed

The number of units to be released. An IN parameter.

logComment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired. Maximum of 100 characters. An IN parameter.

serverInfo

This information is ed to the license server for use in server hook functions. An IN\OUT parameter.

1.10.1.  Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description lshandle is ambiguous handle; it is not exclusively active or exclusively queued.

VLS_RETURN_FAILED

Generic message indicating that the license could not be returned.

VLS_ALL_UNITS_RELEASED

The function released all the issued units when the client requested to release only few.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed

23

24

Chapter 1: Sentinel RMS Licensing Library API

Error Code

Description by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes. 

1.11. VLSbatchUpdate

25

1.11. VLSbatchUpdate Client

Server

√

Static Library

DLL

√

 √

Updates several license authorization at once. Currently the licensing library defaults to automatic license renewal. You do not need to call this unless you disable the automatic license renewal. Please also note that this does not updates capacity authorizations and queued handles.

1.11.1. Syntax LS_STATUS_CODE VLSbatchUpdate ( int LS_HANDLE

*lshandle,

unsigned long

*unused1,

long

*unused2,

unsigned char

*unused3,

LS_CHALLENGE

*unused4,

LS_STATUS_CODE

Argument

numHandles,

*status );

numHandles

Description Specifies the number of handles.

lshandle (in)

Array of numHandles handles, allocated by caller.

unused1

Currently ignored— in a NULL.

unused2

Currently ignored— in a NULL.

unused3

Use NULL as the value.

unused4

Use NULL as the value.

status (out)

Array of numHandles status codes, allocated by caller.

1.11.2. Description API function interface for updating several licenses. It handles properly the fact that some of the licenses may need to be updated locally, and some remotely. In case the handles need to be updated on different license servers, use the VLSbatchUpdate calls interspersed with VLSsetServer calls. This function s only one license server for the updates. This function does not call built-in error handlers at all. There is no limit on the number of handles ed. A handle obtained in one thread can be used in remaining threads as well to update a specific token.

26

Chapter 1: Sentinel RMS Licensing Library API

1.11.3. Returns If everything fails, this function will return a non-LS_SUCCESS code. For failures in individual updates of license codes, this function will return LS_SUCCESS, but the value of the corresponding status element will be set to the error code. Otherwise, it will return the following error codes: Error Code LS_BADHANDLE

Description Invalid handle

VLS_CALLING_ERROR

challenge argument is non-NULL, but cannot be understood.

VLS_CALLING_ERROR

License server used for update is not the same one that was used for acquiring the license.

VLS_NO_LICENSE_GIVEN

Generic error indicating that the license was not updated.

VLS_NO_SUCH_FEATURE

License server does not have license that matches requested feature, version and capacity.

LS_LICENSETERMINATED

Cannot update license because license already expired.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_LICENSE_EXPIRED

License has expired.

VLS__EXCLUDED

or machine are excluded from accessing requested feature.

VLS_APP_NODE_LOCKED

Requested feature is node locked but update request was issued from unauthorized machine.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORMISMATCH

The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has a license.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_RESPONSE Communication with license server has timed out. VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_BAD_SERVER_MESSAGE Message from license server could not be understood. LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_BUFFER_TOO_SMALL

An error occurred in the use of an internal buffer.

1.11.4. See Also n

VLSbatchUpdate

n

LSUpdate

n

Challenge Response Mechanism

n

VLSsetTimeoutInterval

1.11. VLSbatchUpdate

n

VLSdisableLocalRenewal

n

VLSenableLocalRenewal

n

VLSisLocalRenewalDisabled

n

VLSsetRemoteRenewalTime

27

28

Chapter 1: Sentinel RMS Licensing Library API

1.12. Challenge-response Mechanism The challenge-response mechanism can be used by a licensed application to authenticate the license server.

1.12.1. Syntax typedef struct { unsigned long unsigned long unsigned long unsigned char } CHALLENGE; typedef CHALLENGE typedef struct { unsigned long unsigned char } CHALLENGERESPONSE;

Member ulReserved

ulReserved; ulChallengedSecret; ulChallengeSize; ChallengeData[30]; LS_CHALLENGE; ulResponseSize; ResponseData[16];

Description LSAPI requires this to be set to 0.

ulChallengedSecret

The index of the secret which the client application wishes the license server to use in computing its response to this challenge. This value may range from 1 to the number of secrets provided. The actual secrets are provided to the license server through the license code produced using the code generator and can include characters in the range A - Z, and 1 - 9.

ulChallengeSize

Number of characters in ChallengeData. This value cannot be 0.

ChallengeData

The actual string that is used in challenging the license server. This is a string of at most 30 characters, each of which can have any values, including 0.

ulResponseSize

Number of characters in the response to the challenge.

ResponseData

The string of characters representing the actual response.

1.12.2. Description In challenge-response, the license server associates a secret with a feature, provided by the license code. The application also contains this secret. In the license server validation process, an application will “challenge” the license server with a data string. The license server computes a response according to some previously arranged algorithm using the values, data and secret, which it returns. The client application locally computes the expected response using data and secret, and verifies that the expected response matches the response returned by the license server. In order for the authentication mechanism to work correctly and securely, both the license server and the client application must use the same algorithm to compute the response given the values of data

1.12. Challenge-response Mechanism

29

and secret. LSAPI requires the use of the software, “RSA Data Security, Inc. MD4 Message Digest Algorithm” provided by RSA Data Security, Inc. to compute the response. In practice, to save execution time and space, the client application need not invoke the MD4 Message Digest Algorithm at run time to calculate the response. Challenge-response pairs can instead be maintained in a pre-computed table. Sentinel RMS allows for the usage of multiple secrets, with secrets indexed starting at 1. Client applications can challenge the license server to produce a response for a string date using the secret[i], where i is the index of the secret (maximum is 7). The following structures are used by the challenge parameter in challenge-response. challenge is an in/out parameter for the LSRequest and VLSrequestExt function calls and must be properly allocated and initialized by the calling process. Refer to the sample files, crexamp.c, chalresp.c, and md4.c for additional details on using this mechanism. The parameter used to the challenge structure is also used by the library to return the response structure. The CHALLENGE pointer must therefore be typecast to CHALLENGERESPONSE * to obtain the correct response after the function call. The response to a challenge made with any function call, for example, LSRequest is valid only if that function call returns LS_SUCCESS. If LS_SUCCESS is not returned, the response to the challenge is undefined. For more information on how to associate secrets with a feature, see VLScgAllowSecrets.

30

Chapter 1: Sentinel RMS Licensing Library API

The Client Configuration Functions This section describes the API functions that allow the licensed application to retrieve or overwrite the default settings. Given below is the list of the API functions:

Function

Description

VLSsetServer

Sets the license server to be ed.

VLSgetServer

Retrieves the license server’s host name/IP address.

VLSsetServerPort

Sets the license server’s communication port.

VLSgetServerPort

Obtains the license server’s communication port.

VLSinitMachineID

Sets the fields in machineID to default values.

VLSgetMachineID

Sets machineID values for the current host.

VLSgetMachineIDOld

Sets machineID values for the current host. However, this is based on the logic used by earlier version licenses, viz, the version 9 and 10 licenses. For version 11 (and later) licenses, VLSgetMachineID is used.

VLSgetNumberedMachineID

Obtains the CID, Ethernet, and custom extended fingerprint at the specified index location for the current host.

VLSgetNumberedMachineIDExt Obtains the CID, Ethernet, and custom extended fingerprint at the specified index location for a specific license server. VLSsetHostIdFunc

the custom fingerprint mechanism with the client library.

VLSsetCustomExFunc

s the extended custom fingerprint mechanism with the client library.

VLSmachineIDtoLockCode

Computes the previous version locking codes.

VLSmachineIDtoLockCodeEx

Computes the new version locking codes.

VLSgetServerNameFromHandle Retrieves the license server’s name based on handle_id. VLSinitServerList

Initializes a list of default license servers to search for a license in case of broadcast.

VLSgetServerList

Retrieves the default license server list.

VLSgetServerList

Retrieves the default license server list.

VLSinitServerInfo

Initializes the license serverInfo data structure to default values.

VLSsetBroadcastInterval

Configures broadcast behavior.

VLSgetBroadcastInterval

Retrieves broadcast behavior parameters.

VLSsetTimeoutInterval

Configures timeout behavior.

VLSgetTimeoutInterval

Retrieves timeout behavior parameters.

The Client Configuration Functions

Function

Description

VLSsetHoldTime

Sets license hold time.

VLSsetSharedId/ VLSsetTeamId Redefines shared ID functions. VLSsetSharedIdValue/ VLSsetTeamIdValue

s a customized shared ID value.

VLSsetGraceRequestFlag

Sets the behavior if a grace license can be requested or not when the server has been set to stand-alone mode (no-net).

VLSgetGraceRequestFlag

Obtains the status if the grace license request is enabled or not when the server has been set to stand-alone mode (no-net).

VLScalculateLicenseHash

Calculates the license hash for a given license string.

VLSisVirtualMachine

Reports whether the license server is running on a virtual machine or not.

31

32

Chapter 1: Sentinel RMS Licensing Library API

1.13. VLSsetServer Client

Server

√

Static Library

DLL

√

√

Specifies the computer the licensed application will for the license server.

1.13.1. Syntax LS_STATUS_CODE VLSsetServer ( char

Argument serverName

*serverName );

Description The host name or IP address of the computer running the license server. This cannot contain more than 63 characters.

1.13.2. Description VLSsetServer sets the name of the license server host for communication. In general, the license server can be set using any of the following ways: n

n

n

Using the VLSsetServer API function. Setting the LSHOST environment variable. However, the environment variables are checked only at the time of application start-up. The lshost file.

1.13.3. Notes: n

n

n

The VLSsetServer API function will override LSFORCEHOST and the LSHOST environment variables and the LSHOST file. All future transactions will be directed to the host set, regardless of the validity of the host name or whether a license server is running at that host. After a license is successfully requested (via LSRequest or its variants), the application will the name of the license server host which was ed to obtain the license. In any further client-server communication involving this handle, obtained by the client, the application will always communicate with the license server from which it obtained the license, regardless of intervening VLSsetServer calls. The license server name set by VLSsetServer will be ed only for operations that do not involve an already valid handle. Therefore, in case the original license server goes down, you must request a fresh license (hence a fresh handle) from the new license server you wish to use, instead of attempting to send license update messages to the new license server, unless redundant license servers are in use. When a redundant license server fails, all clients are automatically reconnected to one of the other redundant license servers.

Described below is the behavior of this API function vis-a-vis the licensing libraries:

1.13. VLSsetServer

Linked with

Network library

Server Name Valid host name

Meaning Client should communicate with the license server on serverName.

““ or Null

If no server name is set, the application will determine serverName using default mechanism (broadcast within the subnet).

NO-NET

The VLS_NOT_ED_IN_NET_ONLY_MODE error will appear. NO-NET, NO_NET, no_net, and no-net are synonymous.

Stand-alone library

Valid host name

The VLS_NOT_ED_IN_NONET_MODE error will appear.

““ or Null

Communicate with the application (which has the integrated stand-alone license server). If no serverName is specified using VLSsetServer, the environment variables are ignored and the application looks for a license on the local system.

NO-NET

Communicate with the application (which has the integrated stand-alone license server).

LSFORCEHOST or Ignores the settings provided using the environment varLSHOST iables.

Integrated library

Valid host name

Client should communicate with the license server on serverName.

““ or Null

If no server name is set, the application will determine serverName using default mechanism (stand-alone followed by broadcast within the subnet).

NO-NET

Communicate with the application (which has the integrated stand-alone license server).

1.13.4. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following: Error Code

VLS_CALLING_ERROR

VLS_NO_RESOURCES

Description Attempted to use stand-alone mode with network-only library, or network mode with standalone library. Provided an IPX address as the serverName. An error occurred in attempting to allocate memory needed by function.

33

34

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_RESOURCE_LOCK_FAILURE VLS_NOT_ED_IN_NONET_MODE

Description Failed to obtain the API resource lock. Retry by calling this API again. When the application is linked to a stand-alone library and the license server specified is other than no-net.

VLS_NOT_ED_IN_NET_ONLY_MODE When the application is linked to a network only library and no-net is specified. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.14. VLSgetServer

35

1.14. VLSgetServer Client

Server

√

Static Library

DLL

√

√

Retrieves the license server name.

1.14.1. Syntax LS_STATUS_CODE VLSgetServer( char int

Argument

*outBuf, outBufSz );

outBuf (out)

Description Contains a single license server name, space allocated by caller.

outBufSz

Size of outBuf.

1.14.2. Description Returns the name of the license server host that will be ed, in case the client has already set the license server name. Otherwise this function will fail. If the Sentinel RMS Development Kit library is running in stand-alone mode, it returns the string, VLS_STANDALONE.

1.14.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description outBuf is NULL.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

LS_BUFFER_TOO_SMALL

outBuf is not large enough to store license server’s name.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.14.4. See Also: n

VLSsetServer

36

Chapter 1: Sentinel RMS Licensing Library API

1.15. VLSsetServerPort Client

Server

√

Static Library

DLL

√

√

It specifies the port number on which the license server is running. The licensed application will the license server on the specified port. You should call this function only once to set the server port for a license server. You need not call it multiple times to reset the port for the same license server.

1.15.1. Syntax void VLSsetServerPort(int port_number); Argument port_number

Description The license server port number.

1.15.2. Description Defines the license server’s communication port.

1.15.3. Returns Does not return anything.

1.16. VLSgetServerPort

37

1.16. VLSgetServerPort Client

Server

√

Static Library

DLL

√

√

Retrieves the port number.

1.16.1. Syntax int VLSgetServerPort(void);

1.16.2. Description Obtains the number of the port to which all network messages intended for the license server will be sent. The default configured port number is 5093.

1.16.3. Returns The currently set license server port number is returned.

38

Chapter 1: Sentinel RMS Licensing Library API

1.17. VLSinitMachineID Client

Server

√

Static Library

DLL

√

√

Initializes the fields of the machineID data structure to the default values for the current host.

1.17.1. Syntax LS_STATUS_CODE VLSinitMachineID ( VLSmachineID *machineID );

Argument

Description allocated structure where the machine ID will be maintained.

machineID

1.17.2. Description Sets the fields in machineID to their default values. The license manager uses the following data structure to define the characteristics of a machine. typedef struct { unsigned long char unsigned long

id_prom; ip_addr[VLS_MAXLEN]; disk_id;

char

host_name[VLS_MAXLEN];

char

ethernet[VLS_MAXLEN];

char

portserv_addr[VLS_MAXLEN];

unsigned long

custom;

unsigned long

reserved;

char VLScustomEx

u_id; customEx;

char

hard_disk_serial[VLS_MAXLEN];

char

u_info[VLS_MAX_U_INFO_LEN + 1];

char

uuid[VLS_MAX_UUID_LEN + 1];

unsigned long

unused2;

} VLSmachineID;

The structure is called the machineID, and the contents of the first 11 fields are called the fingerprint for the machine to which the contents apply. In practice, a developer may choose to use some subset of these fields for a given machine. To specify which fields are to be used, a flag word called a lock_ selector is defined. A lock selector is a number which sets aside one bit for each fingerprinting element type. Each bit designates a locking criterion, and the lock selector represents the fingerprint elements for a given machine.

1.17. VLSinitMachineID

39

A lock selector does not describe the fingerprint, it only designates which fields in the machine ID are to be used to specify the fingerprint.

The masks which define each locking criterion are given below. Delete this text and replace it with your own content. #define VLS_LOCK_ID_PROM

0x1

#define VLS_LOCK_IP_ADDR

0x2

#define VLS_LOCK_DISK_ID

0x4

#define VLS_LOCK_HOSTNAME

0x8

#define VLS_LOCK_ETHERNET

0x10

#define VLS_LOCK_NW_SERIAL

0x40

#define VLS_LOCK_PORTABLE_SERV

0x80

#define VLS_LOCK_CUSTOM

0x100

#define VLS_LOCK_PROCESSOR_ID

0x200

#define VLS_LOCK_CUSTOM_EX

0x400

#define VLS_LOCK_HARD_DISK_SERIAL

0x800

The mask that defines all locking criteria is: #define VLS_LOCK_ALL

0xFFF

The customEx lock selector uses the following data structure to define the value of the extended custom locking criteria. typedef struct _vlscustomEx { unsigned char int

customEx[VLS_CUSTOMEX_SIZE]; len;

} VLScustomEx;

The maximum size of the extended custom locking code can be 64-bytes. The machine ID and lock selector are input to the license generator and encrypted to create a locking code which then becomes part of the license that authorizes use of an application. When a license is requested by the application, a fingerprint for the machine is calculated and used to create a locking code. This must compare favorably with its counterpart in the license before execution of the application can be authorized.

1.17.3. Returns The status code, LS_SUCCESS, is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description machineID is NULL.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

40

Chapter 1: Sentinel RMS Licensing Library API

1.18. VLSgetMachineID Client

Server

√

Static Library

DLL

√

√

1.18.1. Syntax LS_STATUS_CODE VLSgetMachineID ( unsigned long lock_selector_in, VLSmachineID *machineID, unsigned long *lock_selector_out );

Argument lock_selector_in

Description provided mask specifying locking criteria to be read.

machineID

The “new style“machine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses.

lock_selector_out

Mask returned specifying for the applicable lock selectors.

1.18.2. Description Sets the values of the machineID struct for the current host. The input machineID struct should first be initialized by calling VLSinitMachineID. Then, calling this function will attempt to read only those items indicated by the lock_selector_in. If lock_selector_out is not NULL, *lock_selector_out will be set to a bit mask specifying which items were actually read. To try and obtain all possible machineID struct items, set lock_selector_in to VLS_LOCK_ALL. VLSgetMachineID allows you to use an Ethernet address as a locking criterion for UNIX computers.

1.18.3. Returns The status code, VLS_SUCCESS, is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.19. VLSgetMachineIDOld

41

1.19. VLSgetMachineIDOld Client

Server

√

Static Library

DLL

√

√

1.19.1. Syntax LS_STATUS_CODE VLSgetMachineIDOld ( unsigned long VLSmachineID unsigned long

Argument lock_selector_in

lock_selector_in, *machineID, *lock_selector_out );

Description provided mask specifying locking criteria to be read.

machineID

The “old style“machine ID returned for the applicable lock selectors. The old style machine ID is for licenses earlier than version 11.

lock_selector_out

Mask returned specifying for the applicable lock selectors.

1.19.2. Description Sets the values of the machineID struct for the current host. The input machineID struct should first be initialized by calling VLSinitMachineID. Then, calling this function will attempt to read only those items indicated by the lock_selector_in. If lock_selector_out is not NULL, *lock_selector_out will be set to a bit mask specifying which items were actually read. To try and obtain all possible machineID struct items, set lock_selector_in to VLS_LOCK_ALL. VLSgetMachineID allows you to use an Ethernet address as a locking criterion for UNIX computers. The VLSgetMachineIDOld API function fills up the machineID structure with the logic used by earlier version licenses, viz, the version 9 and 10 licenses. For version 11 licenses, use VLSgetMachineID.

1.19.3. Returns The status code, VLS_SUCCESS, is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes.

42

Chapter 1: Sentinel RMS Licensing Library API

1.20. VLSgetNumberedMachineID Client

Server

√

Static Library

DLL

√

 √

1.20.1. Syntax LS_STATUS_CODE

VLSgetNumberedMachineID (

unsigned long lock_selector_in, VLSmachineID *machineID, unsigned long *lock_selector_out, int flag, int index, int reserved );

Argument lock_selector_in

Description provided mask specifying locking criteria to be read.

machineID

The “new style“machine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses.

lock_selector_out

Mask returned specifying which locking criteria were read.

flag

n n n n

Specify VLS_GET_ETHERNET for multiple Ethernet. Specify VLS_GET_CID for cascaded CID keys. Specify VLS_GET_CUSTOMEX for multiple CustomEx. Specify VLS_GET_HARD_DISK_SERIAL for hard disk serial number.

Refers to the index of the device.

index

The Ethernet enumeration starts from zero for Windows and from one for non-Windows platforms.

reserved

This parameter is reserved for future use.

1.20.2. Description This function: n

n

Sets the machineID struct for the current host (like VLSgetMachineID) Obtains the CID or Ethernet fingerprint at the specified index location. It can be useful in following cases: n

Multiple Ethernet cards

n

Cascaded multiple CID keys

1.20. VLSgetNumberedMachineID

n

Multiple custom locking devices

n

Multiple disk IDs

43

If the information of single items (like, the cascaded CID key or Ethernet or custom extended criterion) is to be retrieved, then use index in a loop till the API returns the VLS_ERROR_NO_MORE_FINGERPRINT_VALUE status code. This status code means that no more fingerprint information is further available. For a specific index, if the API function is unable to retrieve the fingerprint, it will return the VLS_ERROR_FINGERPRINT_VALUE_NOT_FOUND error code. In case, the locking information of some other criteria along with a cascaded CID or Ethernet or custom extended criteria is to be obtained, then lock_selector_in value to the bit mask specifying, which all items need to be read. In this case, if the API function fails to obtain the fingerprint information for all the input lock selectors, then VLS_NO_AVAILABLE_MACHINE_ID will be returned. When ing additional criteria into the lock_selector_in argument (i.e. DiskID, DiskID + hostname, etc.) and using the VLS_GET_ETHERNET/ VLS_GET_CID / VLS_GET_CUSTOMEX for the flag argument, the API will never return VLS_NO_MORE_FINGERPRINT_VALUE, if the fingerprint is not found at the specified index. In this case however, the lock_selector_out criteria shall indicate that the particular fingerprint could not be found. Subsequently a check can be made in the application to return the desired error code as: If (lock_selector_out != lock_selector_in) { return VLS_NO_MORE_FINGERPRINT_VALUE; }

1.20.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, the following error codes result:

Error Code VLS_CALLING_ERROR

Description n

n

VLS_ERROR_FINGERPRINT_ VALUE_NOT_FOUND

The lock mask specified in the lock_selector_in argument does not have lock mask corresponding to the mask of the flag argument. The flag value is other than VLS_GET_CID, VLS_GET_ETHERNET, VLS_GET_CUSTOMEX, or VLS_GET_HARD_DISK_SERIAL.

The API function is unable to retrieve the fingerprint for a specific index. RMS does not consider the following interfaces while calculating Ethernet fingerprint: n n n n

Loopback interface Point-to-point interface Broadcast address interface Any interface that is not up

Thus, if the index is already occupied by a device other than Ethernet

44

Chapter 1: Sentinel RMS Licensing Library API

Error Code

Description interface, the API fails to obtain fingerprint information and returns this error.

VLS_ERROR_NO_MORE_FIN- No more fingerprint information is further available. GERPRINT_VALUE VLS_NO_AVAILABLE_ MACHINE_ID

The API function fails to obtain the fingerprint information for all the input lock selectors.

VLS_LIBRARY_NOT_INITIALIZED

The licensing library is not in initialized state. Call VLSinitialize.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_NOT_ED

An earlier version of the license server is being used.

1.21. VLSgetNumberedMachineIDExt

45

1.21. VLSgetNumberedMachineIDExt Client

Server

√

Static Library

DLL

√

 √

1.21.1. Syntax LS_STATUS_CODE

VLSgetNumberedMachineIDExt (

unsigned char *server_name, unsigned long lock_selector_in, VLSmachineID *machineID, unsigned long *lock_selector_out, int flag, int index, int reserved );

Argument server_name

Description The name of the server ed for setting the machineID struct. If not set, the current host (set in the VLSsetServer API or the LSFORCEHOST environment variable) is assumed. If nothing is set in the VLSsetServer API or the LSFORCEHOST environment variable, error 4 (VLS_NO_SERVER_FILE) is returned.

lock_selector_in

provided mask specifying locking criteria to be read.

machineID

The “new style“machine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses.

lock_selector_out

Mask returned specifying which locking criteria were read.

flag

n n n n

index

Specify VLS_GET_ETHERNET for multiple Ethernet. Specify VLS_GET_CID for cascaded CID keys. Specify VLS_GET_CUSTOMEX for multiple CustomEx. Specify VLS_GET_HARD_DISK_SERIAL for hard disk serial number.

Refers to the index of the device. The Ethernet enumeration starts from zero for Windows and from one for non-Windows platforms.

reserved

This parameter is reserved for future use.

1.21.2. Description Works similar to VLSgetNumberedMachineID, except that it also allows setting the server_name to a specific license server (such as a remote machine in the network).

46

Chapter 1: Sentinel RMS Licensing Library API

You must call VLSinitialize before calling VLSgetNumberedMachineIDExt.

1.21.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, the following error codes result:

Error Code VLS_CALLING_ERROR

Description n

n

VLS_ERROR_FINGERPRINT_ VALUE_NOT_FOUND

The lock mask specified in the lock_selector_in argument does not have lock mask corresponding to the mask of the flag argument. The flag value is other than VLS_GET_CID, VLS_GET_ETHERNET, VLS_GET_CUSTOMEX, or VLS_GET_HARD_DISK_SERIAL.

The API function is unable to retrieve the fingerprint for a specific index. RMS does not consider the following interfaces while calculating Ethernet fingerprint: n n n n

Loopback interface Point-to-point interface Broadcast address interface Any interface that is not up

Thus, if the index is already occupied by a device other than Ethernet interface, the API fails to obtain fingerprint information and returns this error. VLS_ERROR_NO_MORE_FIN- No more fingerprint information is further available. GERPRINT_VALUE VLS_NO_AVAILABLE_ MACHINE_ID

The API function fails to obtain the fingerprint information for all the input lock selectors.

VLS_LIBRARY_NOT_INITIALIZED

The licensing library is not in initialized state. Call VLSinitialize.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_NOT_ED

An earlier version of the license server is being used.

1.22. VLSmachineIDtoLockCode

47

1.22. VLSmachineIDtoLockCode Client

Server

√

Static Library

DLL

√

√

1.22.1. Syntax LS_STATUS_CODE VLSmachineIDtoLockCode ( VLSmachineID

Argument

*machineID,

unsigned long

lock_selector,

unsigned long

*lockCode );

machineID

Description Machine ID used to generate lock code.

lock_selector

Bit mask defining the different lock criteria to retrieve

lockCode

Lock code string generated from lock selector. lockCode is an OUT parameter.

1.22.2. Description This function computes the locking code from the machineID based on the lock selector. Note that every bit in lock_selector is significant. For instance, if you have a machineID that has valid information only for the IP address (lock selector is 0x2), then you should 0x2 into the lock_selector parameter. If you in any other lock_selector value, a different lockCode will result.

1.22.3. Returns The status code, LS_SUCCESS, is returned if successful and if lock_selector is zero. For a complete list of the error codes, see Licensing Library Error and Result Codes.

48

Chapter 1: Sentinel RMS Licensing Library API

1.23. VLSmachineIDToLockCodeEx Client

Server

√

Static Library

DLL

√

√

Computes the new version lock code.

1.23.1. Syntax LS_STATUS_CODE VLSmachineIDToLockCodeEx ( VLSmachineID unsigned long char

Argument

*machineID, lock_selector, *lockCode,

int

lockCodeLen,

int

unused );

machineID

Description The machine ID used to generate lock code.

lock_selector

The bit mask defining the different lock criteria to retrieve.

lockCode

A pointer to the buffer that receives the lock code string generated for the specified lock selector. An OUT parameter. The caller needs to allocate the required memory.

lockCodeLen

The size of the buffer pointed by the lockCode argument. The size should be greater than or equal to VLS_LOCK_CODE_SIZE.

unused

Not used.

1.23.2. Description This API is used to get the new version/format locking code. The new locking code format, for security enhancement, is a string, which contains lock code version, hashing technique identifier, actual lock code, and parity value.

1.23.3. Returns The status code, LS_SUCCESS, is returned if successful. For a complete list of the error codes, see Licensing Library Error and Result Codes. Error Code

Description VLS_NO_AVAILABLE_MACHINE_ID The lock criteria for the specified lock selector is not available. VLS_LOCK_SELECTOR_INVALID

The specified lock selector is invalid.

VLS_CALLING_ERROR

Argument specified is not correct, that is, MachineID or lockCode is NULL. If the lockCodeLen is less than VLS_LOCK_CODE_SIZE.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, please retry calling this API.

1.23. VLSmachineIDToLockCodeEx

Error Code

VLS_LOCK_CODE_NOT_

Description The specified lock code is currently not ed.

LS_NO_RESOURCES

Error occurred in allocating resources needed by this API.

49

50

Chapter 1: Sentinel RMS Licensing Library API

1.24. VLSgetServerNameFromHandle Client

Server

√

Static Library

DLL

√

√

1.24.1. Syntax LS_STATUS_CODE VLSgetServerNameFromHandle ( LS_HANDLE handle_id, char *outBuf, int outBufSz );

Argument handle_id

Description The handle returned by LSRequest or VLSrequestExt

outBuf (OUT)

allocated buffer to receive license server name

outBufSz

Size of buffer in bytes

1.24.2. Description This function retrieves the name of license server based on handle_id. A valid handle_id is always obtained as a product of a successful license request. This handle is associated with the license server that was ed for the license request. VLSgetServerNameFromHandle can be used to retrieve the name of the license server which granted the license.

1.24.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description outBuf is NULL.

LS_BADHANDLE

Invalid handle.

LS_BUFFER_TOO_SMALL

outBuf is smaller than license server’s name that will be returned.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.25. VLSinitServerList

51

1.25. VLSinitServerList Client

Server

√

Static Library

DLL

√

√

1.25.1. Syntax LS_STATUS_CODE VLSinitServerList ( char int

Argument

*serverList, optionFlag );

serverList

Description Caller allocated array of license server names or the IP addresses.

optionFlag

A three-bit flag used to determine how license servers are found.

1.25.2. Description This function initializes the list of license servers specified in the local subnet. However, if the VLSsetServer function is called, the VLSinitServerList settings will be overridden. Using this API is equivalent to setting the LSHOST environment variable. If the server is not set (using the VLSsetServer API or the LSFORCEHOST environment variable) and broadcast mechanism is preferred to find the license server, then you may provide a predefined server list using this API. During broadcast, preference shall be given to servers specified in the list. The serverList parameter should be in the same format as the last parameter of the VLSdiscover call, and have the same syntax. See VLSdiscover for description of optionFlag. This should be called prior to calling LSRequest or VLSqueuedRequest. For example, VLSinitServerList ( “<ServerAddress1>:<ServerAddress2>:....<ServerAdressN>”, Optionflag ); ServerAddress could be ip-address or hostname.

1.25.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NORESOURCES

Description An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

52

Chapter 1: Sentinel RMS Licensing Library API

1.26. VLSgetServerList Client

Server

√

Static Library

DLL

√

√

1.26.1. Syntax LS_STATUS_CODE VLSgetServerList ( char int

Argument

*outBuf, outBufSz );

outBuf (OUT)

Description allocated buffer to receive license server name

outBufSz

Size of buffer in bytes

1.26.2. Description This function returns the default license server list that was set previously through a call to VLSinitServerList. If the default license server list has not been set, an empty string is returned in outBuf.

1.26.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description outBuf is NULL.

LS_BUFFER_TOO_SMALL

outBuf is smaller than license server’s name that will be returned.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.27. VLSinitServerInfo

1.27. VLSinitServerInfo Client

Server

√

Static Library

DLL

√

√

1.27.1. Syntax  LS_STATUS_CODE VLSinitServerInfo ( VLSserverInfo

Argument serverInfo

*serverInfo );

Description allocated buffer that will contain initialized VLSserverInfo.

1.27.2. Description Initializes the serverInfo data structure to its default values. This function must be called before calling VLSrequestExt or VLSreleaseExt.

1.27.3. Returns The status code LS_SUCCESS is always returned.

53

54

Chapter 1: Sentinel RMS Licensing Library API

1.28. VLSsetHostIdFunc Client

Server

√

Static Library

DLL

√

√

Sets the host ID function.

1.28.1. Syntax LS_STATUS_CODE VLSsetHostIdFunc ( long (*myGetHostIdFunc) ());

Argument myGetHostIdFunc

Description The address of the custom host ID function. In Windows, this must be the address returned by MakeProcInst.

1.28.2. Description This function sets the host ID function for the licensing library to be the function pointed to by myGetHostIdFunc. This enables customization of the host ID locking.

1.28.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_NORESOURCES

Description An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.29. VLSsetCustomExFunc

55

1.29. VLSsetCustomExFunc Client

Server

√

Static Library

DLL

√

√

s your extended custom function that enables locking to custom criteria (up to 64-bytes) with the licensing library.

1.29.1. Syntax LS_STATUS_CODE VLSsetCustomExFunc ( long (VLScustomEx* unsigned long*

Argument

(*pmyGetCustExTableFunc) pCustomExTable, pulCount) );

Description A pointer to a buffer that receives all custom extended locking criteria as a VLScustomEx array. It is an OUT parameter and the caller should allocate the memory. Also note the following:

pCustomExTable

n

n

When pCustomExTable is NULL, then set the number of custom extended elements in the pulCount parameter. When pCustomExTable is not-NULL, then fill up both the pCustomExTable and pulCount parameters.

For better understanding, refer to the example given in Customizing Host ID (Extended Custom). An IN/OUT parameter.

pulCount

n

n

On input, it specifies the count of the VLScustomEx entry pointed to by the pCustomExTable argument. If the buffer is not large enough to hold the returned customEx feature table, the API sets this argument equal to the required count. On output, it specifies the actual count of the VLScustomEx objects that are received through this custom API. The maximum size is VLS_MAX_CUSTOMEX_COUNT.

1.29.2. Description This API function sets the custom function to be the function pointed to by pmyGetCustExTableFunc argument. This enables to get the custom extended locking criteria table as a VLScustomEx array. The prototype of the function pointed by pmyGetCustExTableFunc argument is as follows: long myGetCustExTableFunc ( VLScustomEx *pCustomExTable, unsigned long *pulCount );

56

Chapter 1: Sentinel RMS Licensing Library API

1.29.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NORESOURCES

Description An error occurred while allocating memory to the function.

VLS_RESOURCE_LOCK_FAILURE

Failed to obtain the API resource lock. Please retry calling this API.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.30. VLSsetBroadcastInterval

57

1.30. VLSsetBroadcastInterval Client

Server

√

Static Library

DLL

√

√

Sets the broadcast interval.

1.30.1. Syntax LS_STATUS_CODE VLSsetBroadcastInterval ( long

Argument interval

interval );

Description The total time interval for broadcast (in seconds).

1.30.2. Description VLSsetBroadcastInterval sets the total length of both attempts to be interval seconds. The default value of interval is 9 seconds. If a licensed application performs a broadcast to establish the presence of a license server on the subnet, it makes two broadcast attempts, where the length of the second broadcast attempt is slightly longer than the first.

1.30.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_NORESOURCES

Description An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

58

Chapter 1: Sentinel RMS Licensing Library API

1.31. VLSgetBroadcastInterval Client

Server

√

Static Library

DLL

√

√

Retrieves the broadcast interval.

1.31.1. Syntax long VLSgetBroadcastInterval (void);

1.31.2. Description If a licensed application performs a broadcast to establish the presence of a license server on the subnet, it makes two broadcast attempts, where the length of the second broadcast attempt is slightly longer than the first.

1.31.3. Returns VLSgetBroadcastInterval returns the total length of broadcast attempts.

1.32. VLSsetTimeoutInterval

59

1.32. VLSsetTimeoutInterval Client

Server

√

Static Library

DLL

√

√

Sets the timeout interval.

1.32.1. Syntax LS_STATUS_CODE VLSsetTimeoutInterval ( long

Argument interval

interval );

Description The timeout period in seconds.

1.32.2. Description This call sets the timeout interval for all direct application/license server communication to interval. When a licensed application sends a request to a license server and the license server does not respond, it re-sends the message a few times. Each time, the length of the timeout interval is slightly longer than the previous. VLSsetTimeoutInterval sets the total length of a set of attempts to be interval seconds. The default value of interval is 30 seconds. Note that these timeouts are different from the broadcast timeouts.

1.32.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NORESOURCES

Description An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

60

Chapter 1: Sentinel RMS Licensing Library API

1.33. VLSgetTimeoutInterval Client

Server

√

Static Library

DLL

√

√

Retrieves the timeout interval.

1.33.1. Syntax long VLSgetTimeoutInterval ();

1.33.2. Description When a licensed application sends a request to a license server and the license server does not respond, it re-sends the message a few times. Each time, the length of the timeout interval is slightly longer than the previous one.

1.33.3. Returns This call retrieves the time-out interval for all direct application/license server communication.

1.34. VLSsetHoldTime

61

1.34. VLSsetHoldTime Client

Server

√

Static Library

DLL

√

√

Sets the hold time for licenses. 

1.34.1. Syntax LS_STATUS_CODE VLSsetHoldTime ( char

*featureName,

char

*version,

int

Argument

timeInSecs );

featureName

Description Name of the feature.

version

Version of the feature.

timeInSecs

Time in seconds. Default: 15 seconds.

1.34.2. Description  This function sets the hold time of licenses issued to the feature to timeInSecs seconds. This function call will only be effective if the license for the feature specifies that the hold time should be set by the application. This function call must be made before the first LSRequest or VLSqueuedRequest call for it to be applicable. Once a license is requested using LSRequest, the hold time is set for that application, and VLSsetHoldTime will not change it.

1.34.3. Returns  The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_APP_UNNAMED

Description n featureName is NULL n version is NULL Both feature name and version cannot be NULL at the same time.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_CALLING_ERROR

An error occurred in the use of an internal buffer.

62

Chapter 1: Sentinel RMS Licensing Library API

1.35. VLScontrolRemoteSession Client

Server

√

Static Library

DLL

√

√

Enables/disables automatic detection of a remote connection client (terminal services check) in standalone environments.

1.35.1. Syntax LS_STATUS_CODE VLScontrolRemoteSession ( int

toCheckRemoteSession );

Argument Description toCheckRemoteSession Specifies whether the terminal service check will be to turn ON/OFF. Allowed values are VLS_ON or VLS_OFF.

1.35.2. Description This API function turns on and off the detection of a remote connection client (terminal services) for stand-alone environments. n

VLS_ON - This will enable the terminal service check performed by the licensing library.

n

VLS_OFF - This will disable the terminal service check performed by the licensing library.

Make sure that you call this API function before calling VLSinitialize.

1.35.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description If the input parameter is other than VLS_ON or VLS_OFF.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_NOT_ED_IN_NET_ONLY_ MODE

When the function is called in an application linked to a network only library.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.36. VLSsetSharedId/ VLSsetTeamId

63

1.36. VLSsetSharedId/ VLSsetTeamId Client

Server

√

Static Library

DLL

√

√

Redefines the functions called to get the relevant sharing parameter of the client. For network use only.

1.36.1. Syntax In case of a normal license: LS_STATUS_CODE VLSsetSharedId ( int unsigned long

sharedId, (*mySharedIdFunc) (char * value) );

In case of a capacity license: LS_STATUS_CODE VLSsetTeamId ( int unsigned long

Argument sharedId/ teamId

(*mySharedIdFunc) (char * value) );

Description Must be one of the following values: n n n n

mySharedIdFunc

teamId,

VLS_CLIENT_HOST_NAME_ID VLS__NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

Pointer to a function that fills the sharedID value into the value parameter. The return type of mySharedIdFunc is ignored.

1.36.2. Description VLSsetSharedId/VLSsetTeamId must be used to a customized sharedID/teamID function with the licensing library. The value of the sharedID must be ed back by mySharedIdFunc through the character buffer. All sharedID character buffers will be truncated to 32 bytes. For instance, a customized function which returns the host name can be used by the licensing library instead of the builtin function to determine eligibility for sharing a license. VLSsetSharedId should be used in case of normal license and VLSsetTeamId should be used in case of capacity license. If the host name or name are changed using this function, the change will also be reflected in the usage file written by the license server.

64

Chapter 1: Sentinel RMS Licensing Library API

One of the many flexibility provided by LM licensing is the sharing of same license keys, based on the following criteria: n

-name based sharing

n

Hostname based sharing

n

X-display based sharing

n

Application-defined sharing

This model is often used by software publishers who do not want to count every instance of a running application. They may allow multiple instances of a running application to share a single license token/key based on a common name, host name or custom sharing criteria. When any of the sharing-options are enabled in a license, the license server checks if the new request made by a client is coming from the same /Host/X-display or not. If it is so, then it checks with the sharing-limit per license-key and then issues the same key to the new . Internally, VLSrequestExt function, while sending a License Issue Request Message to the license server, es on the information regarding its -name, client-hostname, x-displayname to the license server. This information is kept by the license server in its internal tables for future use. The next time a license is requested for the same Feature, the saved information is used to determine whether this new request is originating from the same /host/x-display. By default, Sentinel RMS Development Kit has default functions to get these values (i.e. name, xdisplay, etc.). To use your own functions to retrieve these values, use the VLSsetSharedId function to override the default functions.

1.36.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR VLS_UNKNOWN_SHARED_ID

Description mySharedIdFunc is NULL. Invalid sharedId/ teamId; is either negative or exceeds maximum value.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue

65

1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue Client

Server

√

Static Library

DLL

√

√

Uses the value ed in by the caller as the shared ID for licensing purposes. For network use only.

1.37.1. Syntax In case of a normal license: LS_STATUS_CODE VLSsetSharedIdValue ( int char

sharedId, *sharedIdValue );

In case of a capacity license: LS_STATUS_CODE VLSsetTeamIdValue ( int char

Argument sharedId/ teamId

*teamIdValue );

Description Must be one of the following values: n n n n

sharedIdValue

teamId,

VLS_CLIENT_HOST_NAME_ID VLS__NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

A character buffer which can contain up to 32 characters.

1.37.2. Description This function goes along with VLSsetSharedId/ VLSsetTeamId and can be used to a customized sharedId/ teamId value with the licensing library. You can explicitly provide the sharedId/ teamId itself using this function. The value of the sharedId/ teamId must be ed through the character buffer. All sharedId/ teamId character buffers will be truncated to 32 bytes. If you call both VLSsetSharedId and VLSsetSharedIdValue/ VLSsetTeamId and VLSsetTeamIdValue, VLSsetSharedId/ VLSsetTeamId has priority and the value set by VLSsetSharedIdValue/ VLSsetTeamIdValue will be ignored. The same concept applies to VLSsetSharedIdValue/ VLSsetTeamIdValue function as VLSsetSharedId/ VLSsetTeamId function. The difference between VLSsetSharedId/ VLSsetTeamId and VLSsetSharedIdValue/ VLSsetTeamIdValue lies in the fact that VLSsetSharedId/ VLSsetTeamId function will make the VLSrequestExt internally send different IDs as returned by the Developer-Defined functions, whereas VLSsetSharedIdValue/ VLSsetTeamIdValue will make the VLSrequestExt send the same ID irrespective of the fact “who is running the client,” “from where the client is being run,” and so on.

66

Chapter 1: Sentinel RMS Licensing Library API

The first priority is given to the developer defined functions as set by VLSsetSharedId/ VLSsetTeamId. If no developer defined function is found then the priority is ed to the SharedIdValue as set by VLSsetSharedIdValue/ VLSsetTeamIdValue function. If neither the developer defined function nor the developer defined SharedIdValue is found, the default functions are used. VLSsetSharedIdValue should be used in case of normal license and VLSsetTeamIdValue should be used in case of capacity license.

1.37.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description An error occurred in the use of an internal buffer.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.38. VLSsetGraceRequestFlag

1.38. VLSsetGraceRequestFlag Client

Server

√

Static Library

DLL

√

√

Sets the behavior if a grace license can be requested or not when the server has been set to stand-alone mode (no-net).

1.38.1. Syntax LS_STATUS_CODE VLSsetGraceRequestFlag ( int

state );

Argument Direction Data Type

Description

state

The flag can have any of the following value:

IN

int

n

n

VLS_ON: This enforces the behavior that existed before this API is introduced in the v8.4.0. Which means that the when the server is set to stand-alone mode: 1. The application looks for a license on the same system. 2. If a license is not found, then application looks for a grace license on the same system. 3. If a grace license not found, it returns error 18. 4. If a grace license is found then it first ensures that no such feature-version exists on a license server (using network broadcast). In case of failure, it returns error 18. Else, returns success and use the grace license. VLS_OFF: This enforces the following behavior when the server is set to stand-alone mode: n The application looks for a license on the same system. n If a license is not found, then application does not look for a grace license on the same system and returns error 18.

67

68

Chapter 1: Sentinel RMS Licensing Library API

1.38.2. Description The API sets the behavior if a grace license can be requested or not when the server has been set to stand-alone mode (no-net). If you call the API with VLS_OFF before requesting a grace license for the first-time, the grace license related system persistence information is not created on the client. If there grace persistence is already present on the client, the request is still denied with error VLS_NO_ SUCH_FEATURE.

1.38.3. Returns For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.39. VLSgetGraceRequestFlag

69

1.39. VLSgetGraceRequestFlag Client

Server

√

Static Library

DLL

√

√

Returns the state if the grace request is enabled or disabled when the server has been set to stand-alone mode (no-net).

1.39.1. Syntax int VLSgetGraceRequestFlag (void);

1.39.2. Description The API is introduced to complement VLSsetGraceRequestFlag.

1.39.3. Returns For a complete list of the error codes, see Licensing Library Error and Result Codes.

70

Chapter 1: Sentinel RMS Licensing Library API

1.40. VLScalculateLicenseHash Client

Server

√

Static Library

DLL

√

√

Calculates the license hash for a given license string.

1.40.1. Syntax LS_STATUS_CODE VLScalculateLicenseHash ( char unsigned char int

*pcLicenseString, *pucLicenseHash, *piLicenseHashLength );

Argument

Direction Data Type

Description

pcLicenseString

IN

char

A pointer to the license string whose hash is to be calculated.

pucLicenseHash

OUT

unsigned char A pointer to the location where the license hash is to be stored. If the value ed is NULL, the required length for this buffer is returned to the third argument piLicenseHashLength.

piLicenseHashLength IN/OUT

int

The length of the hash buffer. needs to allocate memory.

1.40.2. Description Calculates the hash of a license string. A hash uniquely identifies a license string.

Tip M ake sure you a valid license string for calculating license hash. The API calculates license hash without validating the license string (whatever is given against the license string parameter is treated as license, and hash is generated accordingly).

1.40.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLS_CALLING_ERROR

When pcLicenseString and/or piLicenseHashLength are ed NULL.

LS_BUFFER_TOO_SMALL

When piLicenseHashLength is less than VLS_MAX_LICENSE_ HASH_LEN.

1.40. VLScalculateLicenseHash

For a complete list of the error codes, see Licensing Library Error and Result Codes.

71

72

Chapter 1: Sentinel RMS Licensing Library API

1.41. VLSisVirtualMachine Client

Server

Static Library

√

√

DLL √

Reports whether the license server is running on a virtual machine or not.

1.41.1. Syntax LS_STATUS_CODE VLSisVirtualMachine ( VLSVMInfo *vm_info );

Argument

Description allocated structure where the information related to the license server virtualization is obtained.

vm_info

1.41.2. Description The structure below obtains information about whether the license server is running on a virtual machine or not? When LS_SUCCESS is returned, the structure obtains information. typedef struct vm_info_struct { long VLS_VM_DETECTION_STATE

structSz; isVirtualMachine;

} VLSVMInfo;

Virtualization detection is not ed in RMS SDK for MAC (as OS X cannot be virtualized). The API throws error VLS_NOT_ED when it is called (i) in a standalone application running on MAC, (ii) to get the status of a network license server running on MAC.

1.41.3. Returns The status code, LS_SUCCESS, is returned if successful. Otherwise, it will return the following error codes:

Error Code

Description

VLS_LIBRARY_NOT_INITIALIZED

The licensing library is not initialized. To initialize, call VLSinitialize.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_CALLING_ERROR

The input parameter is NULL.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

1.41. VLSisVirtualMachine

Error Code

Description

VLS_NOT_ED

An earlier version of the license server is being used.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

73

74

Chapter 1: Sentinel RMS Licensing Library API

Local vs. Remote Renewal of License Tokens This section documents the API functions required for local and remote renewal of licenses. The license token (also known as a key) issued by the license server to a client has to be renewed by calling LSUpdate within the period of the license lifetime, unless you are using auto-timers (in that case, this will be done automatically for you). The APIs related to enabling/disabling of a local renewal basically change the time at which an update is sent to the license server. Unless updates are carried out by setting auto-timers, updating the license on the license server has to be carried out manually by the client before the expiration of the license lifetime. Given below is the list of the API functions:

Function

Description

VLSdisableLocalRenewal

Disables local license renewal.

VLSenableLocalRenewal

Resets local license renewal.

VLSisLocalRenewalDisabled Informs you whether or not local updates are enabled. VLSgetRenewalStatus

Returns renewal status.

VLSsetRemoteRenewalTime Sets the remote renewal period. VLSdisableAutoTimer

Disables automatic renewal of one feature.

1.42. VLSdisableLocalRenewal

75

1.42. VLSdisableLocalRenewal Client

Server

√

Static Library

DLL

√

 √

Forces all future license renewals to go to the license server.

1.42.1. Syntax LS_STATUS_CODE VLSdisableLocalRenewal (void); This function has no arguments.

1.42.2. Description This disables the local license renewal mechanism. Under local renewal, calls to LSUpdate do not result in a message being sent to the license server until the remote renewal time is reached. On executing this function call, all future license renewals made using LSUpdate for all handles in this process, will go to the license server for renewal.

1.42.3. Returns The status code LS_SUCCESS is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.42.4. See Also n

LSUpdate

n

VLSenableLocalRenewal

76

Chapter 1: Sentinel RMS Licensing Library API

1.43. VLSenableLocalRenewal Client

Server

√

Static Library

DLL

√

 √

Resets the license renewal mechanism to the default.

1.43.1. Syntax LS_STATUS_CODE VLSenableLocalRenewal (void); This function has no arguments.

1.43.2. Description License server will only be ed when a license is close to its key lifetime. Resets the license renewal for all future license renewals made using LSUpdate for all handles in this process.

1.43.3. Returns The status code LS_SUCCESS is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes. Updates until remote renewal time will not go to the license server. Updates will be returned locally. Only updates sent after the remote renewal time will be sent to the license server.

1.43.4. See Also n

LSUpdate

n

VLSdisableLocalRenewal

1.44. VLSisLocalRenewalDisabled

1.44. VLSisLocalRenewalDisabled Client

Server

√

Static Library

DLL

√

 √

Informs you whether or not local updates are enabled.

1.44.1. Syntax VLS_LOC_UPD_STAT VLSisLocalRenewalDisabled (void); This function has no arguments.

1.44.2. Returns Returns the following error codes: Error Code

VLS_LOCAL_UPD_ENABLE VLS_LOCAL_UPD_DISABLE

Description Local renewal is enabled. This is the initial status and the status after VLSenableLocalRenewal is called. Local renewal is disabled. This is the status after VLSdisableLocalRenewal is called.

77

78

Chapter 1: Sentinel RMS Licensing Library API

1.45. VLSgetRenewalStatus Client

Server

√

Static Library

DLL

√

 √

 Retrieves license renewal status.

1.45.1. Syntax LS_STATUS_CODE VLSgetRenewalStatus (void); This function has no arguments.

1.45.2. Description Returns the renewal status of the last successful license renewal made using LSUpdate. If the last operation that successfully renewed a license involved ing the license server, this function returns VLS_REMOTE_UPDATE. If the last operation that successfully renewed a license did not involve ing the license server (was done locally), this function returns the value VLS_LOCAL_UPDATE. If an update has not occurred, it returns VLS_NO_UPDATES_SO_FAR.

1.45.3. Returns Returns the following status codes: Error Code VLS_NO_LICENSE_GIVEN

Description Generic error indicating that license was not updated.

LS_LICENSETERMINATED

Cannot update the license because the license has already expired.

VLS_NO_SUCH_FEATURE

License server does not have license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS_FINGERPRINT_MISMATCH

Client-locked; locking criteria does not match.

VLS_APP_NODE_LOCKED

Feature is node locked, but the update request was issued from an unauthorized machine.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

1.45. VLSgetRenewalStatus

Error Code VLS_VENDORIDMISMATCH

Description The vendor identification of requesting application does not match the vendor identification of the feature for which the license server has a license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_INVALID_DOMAIN

The domain of the license server is different from that of client.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_BAD_SERVER_MESSAGE

Message returned by license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_NO_UPDATES_SO_FAR

No updates have been made. Specifies the initial value.

VLS_LOCAL_UPDATE

During the most recent update, the license was valid and did not need to be renewed.

VLS_REMOTE_UPDATE

During the most recent update, the license was invalid and required update from the license server.

79

80

Chapter 1: Sentinel RMS Licensing Library API

1.46. VLSsetRemoteRenewalTime Client

Server

√

Static Library

DLL

√

 √

Sets the remote renewal time period.

1.46.1. Syntax LS_STATUS_CODE VLSsetRemoteRenewalTime ( char

*featureName,

char

*version,

int

Argument

timeInSecs );

featureName

Description Name of the feature.

version

Version of the feature.

timeInSecs

Time in seconds. Default time is 15 seconds.

1.46.2. Description Sets the remote renewal period of licenses issued to the feature to timeInSecs seconds. This function call must be made before the first LSRequest call for it to be applicable. Once a license is requested using LSRequest, the remote renewal time is set for that application, and VLSsetRemoteRenewalTime will not change it.

1.46.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

Description n featureName is NULL n version is NULL Both feature name and version cannot be NULL at the same time.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_CALLING ERROR

An error occurred in the use of an internal buffer.

The status code LS_SUCCESS is always returned. For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.47. VLSdisableAutoTimer

81

1.47. VLSdisableAutoTimer Client

Server

√

Static Library

DLL

√

 √

1.47.1. Syntax LS_STATUS_CODE VLSdisableAutoTimer ( LS_HANDLE int

Argument

lshandle, state );

lshandle

Description The handle returned by LSRequest or VLSrequestExt

state

VLS_ON or VLS_OFF

VLS_OFF disables the auto timer and VLS_ON enables the auto timer.

1.47.2. Description Using the handle returned from requesting a license, a call to this function can be used to disable automatic renewal of one feature. Calling with an argument of zero handle disables auto renewal of all features. On UNIX, call VLSdisableAutoTimer before using sleep or SIGALRM, or there could be a potential conflict with the timer signal. On Win32, call VLSdisableAutoTimer if thread has no message loop since the message loop is used to process the timer. If you disable the automatic timer, you must ensure that the license key is renewed periodically (before it expires) by calling LSUpdate.

1.47.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description Invalid state. Needs to be either VLS_ON or VLS_OFF

LS_BADHANDLE

Invalid handle.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

82

Chapter 1: Sentinel RMS Licensing Library API

The Client Query Functions This section describes the API functions that return information about licenses, client features and handles. Given below is the list of the API functions:

Function

Description

VLSgetLicenseInfo

Retrieves information about non-capacity licenses available in the license server.

VLSgetLicenseInfoExt

Retrieves information for both capacity and non-capacity licenses available in license server.

VLSgetClientInfo

Returns information about a client using a non-capacity license loaded in the license server.

VLSgetHandleInfo

Returns information about a client given a handle.

VLSgetActiveHandleList

Retrieves the list of currently active client handles.

VLSgetLicInUseFromHandle Returns the number of licenses used for the feature name used to obtain a given handle.

1.48. VLSlicenseInfo (license_info_struct)

1.48. VLSlicenseInfo (license_info_struct) The license information for a specific feature-version combination is returned by the following structure.

1.48.1. Syntax typedef struct license_info_struct{ long structSz; char feature_name[VLS_MAXFEALEN + 1]; char version[VLS_MAXFEALEN + 1]; int lic_type; int trial_days_count; long birth_day; long death_day; int num_licenses; int is_node_locked; int concurrency; int sharing_crit; int locking_crit; int holding_crit; int num_subnets; char site_license_info[VLS_SITEINFOLEN + 1]; long hold_time; int meter_value; char vendor_info[VLS_VENINFOLEN + 1]; char cl_lock_info[VLS_MAXCLLOCKLEN + 1]; long key_life_time; int sharing_limit; int soft_num_licenses; int is_standalone; int check_time_tamper; int is_additive; int num_servers; int isRedundant; int majority_rule; int log_encrypt_level; int elan_key_flag; long conversion_time; char server_locking_info[VLS_MAXSRVLOCKLEN + 1]; int capacity_flag; unsigned long capacity; int isCommuter; long commuter_max_checkout_days; long grace_period_flag; long grace_period_calendar_days; long grace_period_elapsed_hours; long overdraft_flag; long overdraft_hours;

83

84

Chapter 1: Sentinel RMS Licensing Library API

long overdraft_s; int local_request_lockcrit_flag; int local_request_lockcrit_required; int local_request_lockcrit_float; int local_request_lockcrit_min_num; int license_version; char plain_vendor_info[VLS_VENINFOLEN + 1]; int trial_elapsed_hours; int trial_execution_count; int trial_calendar_period_left; int trial_elapsed_period_left; int trial_executions_left; int trial_current_status; char license_hash[VLS_MAX_LICENSE_HASH_LEN + 1]; char license_storage[VLS_LICENSE_STORAGE_MAXPATHLEN + 1]; int license_state; int license_precedence;   VLS_VM_DETECTION vm_detection; }VLSlicenseInfo; Member

Description

structSz

Size of VLSlicenseInfo structure.

feature_name The name of the feature whose information is retrieved. Currently, a 24 characters

long feature name is ed. version

Feature version. Maximum 11 characters.

lic_type

The type of license, either trial or normal.

trial_days_ count

The number of trial days.

birth_day

The day of the license start date.

death_day

The time when the feature expires. The constant, VLS_NO_EXPIRATION, is returned if the license does not have any expiration date.

num_licenses

The total number of licenses the license server is authorized to issue.

is_node_ locked

Depending on the locking scheme of the feature, this returns one of the following constants: n n n n

VLS_NODE_LOCKED (Client-Server locked) VLS_CLIENT_NODE_LOCKED (Client locked) VLS_FLOATING (Server locked) VLS_DEMO_MODE (Unlocked)

concurrency

Unused

sharing_crit

Returns the license sharing criteria, which can be one of the following constants: n n n n n

VLS_NO_SHARING VLS__NAME_ID VLS_CLIENT_HOST_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

1.48. VLSlicenseInfo (license_info_struct)

Member

Description

locking_crit

The license server locking criteria, which can be one of the following constants: n n n n n n n n n n n n

holding_crit

85

VLS_LOCK_ID_PROM VLS_LOCK_IP_ADDR VLS_LOCK_DISK_ID VLS_LOCK_HOSTNAME VLS_LOCK_ETHERNET VLS_LOCK_PORTABLE_SERV VLS_LOCK_CUSTOM VLS_LOCK_CUSTOMEX VLS_LOCK_U VLS_LOCK_HARD_DISK_SERIAL VLS_LOCK_U_INFO VLS_LOCK_UUID

The license holding criteria, which can be one of the following constants: n n

n

VLS_HOLD_NONE (no held licenses). VLS_HOLD_VENDOR (the hold time specified through the VLSsetHoldTime function). VLS_HOLD_CODE (the license code specifies the hold time).

num_subnets

The number of subnet specifications provided for the site.

site_license_ info

A space-separated list of subnet wildcard specifications.

hold_time

The holdtime specified for licenses issued for this feature.

vendor_info

The vendor-defined information string. The maximum length of the string can be 2000 characters.

cl_lock_info

The locking information about machines in a space-separated string of host IDs and/or IP addresses.If licenses-per-node restrictions have been specified, they are also returned in parentheses with each host ID/IP address. For instance, cl_lock_info could be:0x8ef38b91(20#) 0xa4c7188d 0x51f8c94a(10#).

key_life_time

The license lifetime for this feature (in seconds).

sharing_limit

The limit on how many copies can share the same license.

soft_num_ licenses

The soft limit (for alerts) on the number of concurrent s of this feature.

is_standalone

The license type as any of the following: n n n

VLS_STANDALONE_MODE - for a stand-alone license VLS_NETWORK_MODE - for a network license VLS_PERPETUAL_MODE - for a repository license

check_time_ tamper

Returns VLS_TRUE if this feature is time tamper proof or VLS_FALSE if not time tamper proof.

is_additive

Returns VLS_TRUE if this is an additive license or VLS_FALSE if this is an exclusive license. The license type as any of the following: n

VLS_ADDITIVE - for an additive license

86

Chapter 1: Sentinel RMS Licensing Library API

Member

Description n n

VLS_EXCLUSIVE - for an exclusive license VLS_AGGREGATE - for an aggregate license

isRedundant

Validates if the license is actually redundant.

majority_rule

Checks whether majority rule is on or off.

num_servers

The number of redundant license servers.

isCommuter

Checks whether commuter licenses are allowed or not.

log_encrypt_ level

The encryption level in the network license for the license server's usage log file.

elan_key_flag Unused. conversion_ time

Unused.

server_locking_info

Stores the server locking information.

capacity_flag

The capacity flag can be one of the following constants: n n n

VLS_CAPACITY_NONE - for no capacity VLS_CAPACITY_NON_POOLED - for non-pooled capacity VLS_CAPACITY_POOLED - for pooled capacity

capacity

The total capacity of the license.

commuter_ max_checkout_days

The maximum number of days a commuter license can be checked out for.

grace_period_ A flag that decides whether grace period for a license will be provided or not. It can be any of the following constants: flag n n

VLS_NO_GRACE_PERIOD - grace period not allowed (default) VLS_STANDARD_GRACE_PERIOD - grace period allowed

grace_period_ The number of days the grace period will last for. It can be a value between 1 to 180 calendar_days days. grace_period_ The number of hours the grace period will last for. It can be a value between 1 to 1440 elapsed_hours hours. overdraft_flag Not ed. overdraft_ hours

Not ed.

overdraft_ s

Not ed.

Overdraft_ s_in_use

The number of overdraft s currently using the application.

local_request_ The flag that sets the local license request locking criteria. lockcrit_flag local_request_ The necessary number of locking license criteria that must be met for making the licenses available to a local client. lockcrit_ required

1.48. VLSlicenseInfo (license_info_struct)

Member

87

Description

local_request_ The desired number of locking license criteria that must be met for making the lockcrit_float licenses available to a local client. local_request_ The minimum number of locking license criteria that must be met for making the lockcrit_min_ licenses available to a local client. For example, the "required" criteria can be disk ID, the "floating" criteria can be Ethernet card and CID key, and the "minimum" criteria num

can be any 2 of the above. isGraceLicense Set to VLS_TRUE only when the grace period is available for the local request. license_version

The Sentinel RMS license version. The possible values are: n n n n n n n n n n n

VLS_LICENSE_VERSION_850 - For Sentinel RMS 8.5.0 licenses VLS_LICENSE_VERSION_840 - For Sentinel RMS 8.4.0 and 8.4.1 licenses VLS_LICENSE_VERSION_823 - For Sentinel RMS 8.2.3 licenses VLS_LICENSE_VERSION_810 - For Sentinel RMS 8.1.x, 8.2.0, 8.2.1, 8.2.2 licenses VLS_LICENSE_VERSION_800 - For Sentinel RMS 8.0.x licenses VLS_LICENSE_VERSION_7301 - For Sentinel RMS 7.3.0.1 licenses VLS_LICENSE_VERSION_730 - For Sentinel RMS 7.3.0 licenses VLS_LICENSE_VERSION_700 - For Sentinel RMS 7.0.0 licenses VLS_LICENSE_VERSION_TOO_OLD - For licenses older than Sentinel RMS 7.0.0 VLS_LICENSE_VERSION_LATEST - For the latest version of Sentinel RMS licenses VLS_LICENSE_VERSION_NOT_DEFINED - When the license version is not defined

trial_elapsed_ The number of hours for which a trial license can be used, before it expires. It is a total elapsed time period measured from request to release of a license, for each use. hours trial_ execution_ count

The number of times a trial license can be used. This is measured by the number of times the license is requested that typically equates to the number of times an application is executed.

plain_vendor_ The information that a vendor wants to share with the end-customers.This value will appear unencrypted in readable/ concise readable license code. The maximum length info

of the string can be up to 395 characters. license_hash

The license hash identifier for a license code.

license_storage

The file location where the license is stored.

license_state

Indicates whether this license is a part of the license table node or not.

license_precedence

Indicates the priority of a particular trial license among the set of licenses having the same feature-version combination.

trial_calendar_ The total number of days left for using a trial license. period_left trial_elapsed_ The number of seconds left in the trial elapsed time period. Valid only if elapsed time is being enforced. period_left

The number of executions left in the trial license. Valid only if executions are being trial_ executions_left measured. trial_current_ status

The current state of this trial license. The possible values are: n

VLS_TRIAL_UNUSED - The license has never been requested and therefore the trial period has not yet begun.

88

Chapter 1: Sentinel RMS Licensing Library API

Member

Description n n

VLS_TRIAL_ACTIVE - The trial period has started (requested at least once). VLS_TRIAL_EXHAUSTED - The trial period is over. 

vm_detection License requests are allowed or not if virtual machine is detected.

1.49. VLSgetLicenseInfo

89

1.49. VLSgetLicenseInfo Client

Server

√

Static Library

DLL

√

 √

Retrieves information about non-capacity licenses available in the license server.

1.49.1. Syntax LS_STATUS_CODE VLSgetLicenseInfo ( unsigned char *feature_name, unsigned char *version, int feature_index, unsigned char *license_hash, int license_hash_len, int license_index, VLSlicenseInfo *license_info);

Argument feature_name

Description The feature name identifier for the license code.

version

The version identifier for the license code.

feature_index

Used to specify a particular feature-version combination.

license_hash

The license hash identifier for a specific license code.

license_hash_len

The license hash length.

license_index

Used to specify index of a particular license for a specific feature-version combination.

license_info

The structure in which information fetched will be stored by this API. The caller should allocate the memory for this structure.

1.49.2. Description This API obtains information of all the licenses, of a specific feature-version combination, loaded in the memory. The license_index argument should be used in a loop to get information of the licenses of a specific feature-version combination. So long the license_index is valid, the API will return the LS_SUCCESS status code. Otherwise, it will return the VLS_NO_MORE_LICENSES status code. You can also loop through the features in the license table. Either a feature_name-version combination or feature_ index can be used to reach a particular feature available. Thus, using a combination of feature_index and license_index, you can loop through the features and for each feature all the licenses added.

1.49.3. Returns The status code LS_SUCCESS is returned, if successful. The other status codes that may be returned are:

90

Chapter 1: Sentinel RMS Licensing Library API

Error Code

Description

VLS_NO_MORE_FEATURES

Finished retrieving all the features added.

VLS_NO_MORE_LICENSES

Finished retrieving information of all the licenses that match the specified feature-version combination.

If an error occurs, one of the following error codes is returned:

Error Code

Description

VLS_APP_UNNAMED

If: n

n

VLS_CALLING_ERROR

The feature_name is NULL or feature_name contains only NULL character i.e '\0' and feature_index is less than zero The feature_name is not NULL and version is NULL.

Argument specified is not correct, that is, one of the following reasons exist: n n

n n

n

n

If license_info is NULL. If license_hash is NULL and license_index is less than 0. If license_hash is not NULL and license_hash_len < 1. If license_hash is not NULL and license_hash_len > VLS_MAX_LICENSE_HASH_LEN. If feature_name or version buffer size exceeds the maximum size limit specified as VLS_MAXFEALEN and VLS_MAXVERLEN respectively. When the structSz field of the VLSlicenseInfo struct is not set to the size of VLSlicenseInfo.

VLS_NO_SUCH_FEATURE

License with ed feature-version combination not found.

VLS_MULTIPLE_VENDORID_FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the Vendor ID for all these licenses is different from the licensing library's Vendor ID.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_NO_SUCH_LICENSE

License with ed feature-version-license hash combination not found.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESS AGE

Message from license server could not be understood.

VLS_CAPACITY_MISMATCH

The function is called for a capacity license. It can only be called for non-capacity licenses. For capacity licenses, call VLSgetLicenseInfoExt.

1.49. VLSgetLicenseInfo

Error Code

Description

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

91

92

Chapter 1: Sentinel RMS Licensing Library API

1.50. VLSgetLicenseInfoExt Client

Server

√

Static Library

DLL

√

 √

Retrieves information for both capacity and non-capacity licenses available in license server.

1.50.1. Syntax LS_STATUS_CODE VLSgetLicenseInfoExt ( unsigned char

*feature_name,

unsigned char

*version,

unsigned long

*capacity

int

feature_index,

unsigned char

*license_hash,

int

license_hash_len,

int

license_index,

VLSlicenseInfo *license_info );

Argument feature_name

Description The feature name identifier for the license code.

version

The version identifier for the license code.

capacity

The capacity value for the license code.

feature_index

Used to specify a particular feature-version combination.

license_hash

The license hash identifier for a specific license code.

license_hash_len

The license hash length.

license_index

Used to specify index of a particular license for a specific feature-version combination.

license_info

The structure in which information fetched will be stored by this API. The caller should allocate the memory for this structure.

1.50.2. Description The API retrieves license information for both capacity and non-capacity licenses that are available on the license server. If feature_name, version and capacity parameters are not NULL, then information about the licenses as indicated by feature_name, version and capacity parameters is returned to the client. If information about a non-capacity license is required, the capacity parameter is ed as NULL and the feature_name and version parameters are ed as non-NULL. If information about all feature, which includes both capacity as well as non-capacity, and their corresponding licenses is required, then, the feature_name and version parameters are ed as NULL, and the feature_index parameter should be used in a loop in combination with license_index.

1.50. VLSgetLicenseInfoExt

1.50.3. Returns The status code LS_SUCCESS is returned, if successful. The other status codes that may be returned are: Error Code VLS_NO_MORE_FEATURES VLS_NO_MORE_LICENSES

Description Finished retrieving all the available features on the license server. Finished retrieving information of all the licenses that match the specified feature-version combination.

If an error occurs, one of the following error codes is returned: Error Code

VLS_APP_UNNAMED

Description If: n

n

VLS_CALLING_ERROR

The feature_name is NULL or feature_name contains only NULL character i.e '\0' and feature_index is less than zero The feature_name is not NULL and version is NULL.

Argument specified is not correct, that is, one of the following reasons exist: n n

n n

n

n

If license_info is NULL. If license_hash is NULL and license_index is less than 0. If license_hash is not NULL and license_hash_len < 1. If license_hash is not NULL and license_hash_len > VLS_MAX_LICENSE_HASH_LEN. If feature_name or version buffer size exceeds the maximum size limit specified as VLS_MAXFEALEN and VLS_MAXVERLEN respectively. When the structSz field of the VLSlicenseInfo struct is not set to the size of VLSlicenseInfo.

VLS_NO_SUCH_FEATURE

License with ed feature-version combination not found.

VLS_MULTIPLE_VENDORID_FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the Vendor ID for all these licenses is different from the licensing library's Vendor ID.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_NO_SUCH_LICENSE

License with ed feature-version-license hash combination not found.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

93

94

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_NO_SERVER_RUNNING

Description License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

VLS_NOT_ED_IN_NONET_ MODE

When the function is called for retrieving information about the capacity licenses with the stand-alone library.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

1.51. client_info_struct

95

1.51. client_info_struct If a license server host name is not established, the client query function will attempt to locate a license server. Information about any instance of application authorized by the Sentinel RMS license server is returned in the following structure:

1.51.1. Syntax typedef struct

client_info_struct { char

unsigned long

_name[VLS_MAXLEN]; host_id;

char

group[VLS_MAXLEN];

long

start_time;

long

hold_time;

long

end_time;

long

key_id;

char

host_name[VLS_MAXLEN];

char

x_display_name[VLS_MAXLEN];

char

shared_id_name[VLS_MAXLEN];

int

num_units;

int

q_wait_time;

int

is_holding;

int

is_sharing;

int

is_commuted;

long

structSz;

unsigned long

team_capacity;

unsigned long

total_resv_team_capacity;

unsigned long

reserved_team_capacity_in_use;

unsigned long

unreserved_team_capacity_in_use;

unsigned long

_capacity_from_reserved;

unsigned long

_capacity_from_unreserved;

int

total_team_tokens_resv;

int

reserved_team_tokens_in_use;

int

unreserved_team_tokens_in_use;

} VLSclientInfo;

Member _name

Description The name of the using the application, where MAXLEN is set to 64 characters. This information can be changed using the VLSsetSharedId API call. In case of stand-alone licensing, the “default-sharing-ID” string will be returned.

host_id

The host ID of the computer on which the is working. This can be changed using the VLSsetHostIdFunc call.

group

Name of the reserved group to which the belongs, where MAX-

96

Chapter 1: Sentinel RMS Licensing Library API

Member

Description LEN is set to 64 characters. If the does not belong to an explicitly named group, DefaultGrp is returned.

start_time

The time at which the current license code was issued by the license server.

hold_time

Specifies the hold time, in seconds, if any.

end_time

The time at which the ’s current license will expire if not renewed.

key_id

The internal ID of the license currently issued to the ’s application. After starting up, the license server issues licenses with unique IDs until it is restarted.

host_name

Name of the host/computer where the is running the application, where MAXLEN is set to 64 characters. This information can be changed using the VLSsetSharedId API call. In case of stand-alone licensing, the “default-sharing-ID” string will be returned.

x_display_ name

Name of the X display where the is displaying the application, where MAXLEN is set to 64 characters. This information can be changed using the VLSsetSharedId API call. In case of stand-alone licensing, the “default-sharing-ID” string will be returned.

shared_id_ name

A special vendor-defined ID that can be used for license sharing decisions. It always has the fixed value, default-sharing-ID, unless it is changed by ing a custom function using the VLSsetSharedId API call. If you plan to use this ID, you should your own function from your application, and choose Application-defined sharing while running the code generator. The maximum length of the string is set to 64 characters. In case of stand-alone licensing, the “default-sharing-ID” string will be returned.

num_units

Number of units consumed by the client so far.

q_wait_time

Unused.

is_holding

Has the value, VLS_TRUE, if the ’s current license is being held after its expiration. Otherwise, the value is VLS_FALSE.

is_sharing

Total number of clients sharing this particular license, including the current client being queried. If sharing is disabled, is_sharing will be 0.

is_commuted

Total number of clients that have “checked out” a license from the network.

structSz

Size of VLSclientInfo structure.

team_capacity

Total capacity of the team.

total_resv_team_capacity Total capacity reserved for the team.

1.51. client_info_struct

Member

Description reserved_team_capacity_ Capacity given to clients from reserved capacity. in_ use Capacity given to clients from unreserved capacity. ureserved_team_capacity_in_use Capacity given to s from reserved capacity. _capacity_from_ reserved _capacity_from_unre- Capacity given to s from unreserved capacity. served total_team_tokens_resv Total reserved units. reserved_team_tokens_ in_ use

Units given to teams from reserved pool.

unreserved_team_ tokens_in_use

Units given to teams from unreserved pool.

97

98

Chapter 1: Sentinel RMS Licensing Library API

1.52. VLSgetClientInfo Client √

Server

Static Library √

DLL √

Returns information about a client feature.

1.52.1. Syntax LS_STATUS_CODE VLSgetClientInfo ( char

*featureName,

char

*version,

int

index,

char

*unused1,

VLSclientInfo

Argument

*clientInfo );

featureName

Description Name of the feature. An IN parameter.

version

Version of the feature. An IN parameter.

index

Used to specify a particular client. An IN parameter.

unused1

Use NULL as the value.

clientInfo (out)

The structure in which information will be returned. Space allocated by caller. An OUT parameter.

1.52.2. Description After this call, clientInfo contains information about all clients’ features. Since it is possible for multiple clients of a particular feature to be active on the network, index is used to retrieve information about a specific client. The suggested use of this function is in a loop, where the first call is made with index 0 which retrieves information about the first client. Subsequent calls, when made with 1, 2, 3, and so on, will retrieve information about other clients of that feature type. So long as the index is valid, the function returns the success code, LS_SUCCESS. Otherwise, it returns the Sentinel RMS Development Kit status code, VLS_NO_MORE_CLIENTS. Memory for clientInfo should be allocated before making the call.

1.52.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

VLS_CALLING_ERROR

Description n featureName is NULL n version is NULL n Both feature name and version cannot be NULL at the same time. n

clientInfo parameter is NULL

1.52. VLSgetClientInfo

Error Code

Description n index is negative. n Attempted to use stand-alone mode with networkonly library, or network mode with stand-alone library.

VLS_NO_MORE_CLIENTS

Finished retrieving client information for all clients.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature and version.

VLS_MULTIPLE_VENDORID_ FOUND

The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested.

VLS_NO_SERVER_UNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

99

100

Chapter 1: Sentinel RMS Licensing Library API

1.53. VLSgetHandleInfo Client √

Server

Static Library √

DLL √

Returns information about a client feature.

1.53.1. Syntax LS_STATUS_CODE VLSgetHandleInfo ( LS_HANDLE VLSclientInfo

Argument lshandle clientInfo (out)

lshandle, *clientInfo );

Description The handle returned by LSRequest or VLSrequestExt The structure in which information will be returned. Space allocated by caller.

1.53.2. Description This function also retrieves client information, except that lshandle replaces the arguments (featureName, version, and index) used in VLSgetClientInfo.

1.53.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_BAD_HANDLE

Description Invalid handle. Handle may have already been released and destroyed from previous license operations or too many handles have already been allocated.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.54. VLSgetActiveHandleList

101

1.54. VLSgetActiveHandleList Client √

Server

Static Library √

DLL √

Retrieves the list of currently active client handles. 

1.54.1. Syntax LS_STATUS_CODE VLSgetActiveHandleList ( LS_HANDLE unsigned long

Argument out_handle_buf num_handle

*out_handle_buf, * num_handle );

Description The allocated buffer where API will store the handles. The caller must allocate memory. The number of LS_HANDLE elements for which the memory is allocated. The API on return stores the number of elements available in the buffer.

1.54.2. Description Obtains the license handles that are in use. The license handles and its count is stored in the out_handle_buf and num_handle arguments, respectively. The caller must allocate buffer to store license handles. If the out_handle_buf argument is ed as NULL, the API will store the number of LS_HANDLE element in the num_handle argument. The caller must allocate the buffer for storing the number of LS_ HANDLE elements.

1.54.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error or status codes: Error Code VLS_NO_ACTIVE_HANDLE

Description This indicates that no active client handles exist.

VLS_CALLING_ERROR

The argument specified is not correct, that is, num_handle is NULL.

LS_BUFFER_TOO_SMALL

This error code indicates that the allocated buffer is insufficient to store the list of active client handles.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_NORESOURCES

Error occurred in allocating resources needed by this API.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

102

Chapter 1: Sentinel RMS Licensing Library API

1.55. VLSgetLastErrorStatusFromHandle Client √

Server

Static Library √

DLL √

Retrieves the last status or error code returned for a specified license handle.

1.55.1. Syntax LS_STATUS_CODE LS_HANDLE LS_STATUS_CODE

VLSgetLastErrorStatusFromHandle ( lshandle, *status );

Argument lshandle

Description The client handle identifier.

status

The last return status for the specified handle.

1.55.2. Description This API function is used to obtain the last error/status code returned for a specified license handle. This may be helpful in following scenarios: To get information on the license handles whose trial license has exhausted but the license handle is not yet released by the application. To retrieve the update status for active client handles when auto-update process is used.

1.55.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description If the error_status parameter is specified as NULL.

LS_NO_RESOURCES

Error occurred in allocating resources needed by this API.

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API. LS_BADHANDLE

This error is returned of if an invalid handle is ed to the API function. The license is invalid if it is already released, or has never been initialized/allocated.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.56. VLSgetLicInUseFromHandle

103

1.56. VLSgetLicInUseFromHandle Client √

Server

Static Library √

DLL √

Returns the total number of licenses issued by the license server for the feature name and version used to obtain this handle.

1.56.1. Syntax LS_STATUS_CODE VLSgetLicInUseFromHandle ( LS_HANDLE

lshandle,

int *totalKeysIssued );

Argument lshandle totalKeysIssued

Description The handle returned by any Request API call. The number of licenses issued by the license server. Space should be allocated by the caller.

1.56.2. Description Given a valid handle returned by an LSRequest call or its variants, it returns the total number of licenses issued by the license server for the feature name and version used to obtain this handle. The information in the handle is not updated subsequently. For more information, use VLSgetFeatureInfo.

1.56.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_BADHANDLE

Description Invalid handle. Handle has already been released and destroyed from previous license versions or too many handles have been allocated.

LS_BUFFER_TOO_SMALL

in_use_ p parameter is NULL.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

104

Chapter 1: Sentinel RMS Licensing Library API

The Feature Query Functions Given below is the list of the API functions:

Function

Description

VLSgetFeatureInfo

Retrieves feature licensing information when a non-capacity licensed is currently serving the license requests.

VLSgetVersions

Retrieves licensed version information for a feature.

VLSgetFeatureFromHandle

Returns the feature name corresponding to the handle.

VLSgetVersionFromHandle

Returns the version corresponding to the handle.

VLSgetTimeDriftFromHandle

Returns the difference in seconds between the estimated current time on the license server and the estimated time on the client.

VLSgetFeatureTimeLeftFromHandle Returns the difference in seconds between the estimated current time on the license server and the estimated feature expiration time on the license server. VLSgetKeyTimeLeftFromHandle

Returns the difference in seconds between the estimated current time on the license server and the estimated license expiration time on the license server

1.57. feature_info_struct (VLSfeatureInfo)

105

1.57. feature_info_struct (VLSfeatureInfo) Information about specific features licensed by the Sentinel RMS license server is returned in the following structure.

106

Chapter 1: Sentinel RMS Licensing Library API

1.57.1. Syntax typedef struct feature_info_struct { long structSz char feature_name[VLS_MAXFEALEN]; char version[VLS_MAXFEALEN]; int lic_type; int trial_days_count; long birth_day; long death_day; int num_licenses; int total_resv; int lic_from_resv; int qlic_from_resv; int lic_from_free_pool; int qlic_from_free_pool; int is_node_locked; int concurrency; int sharing_crit; int locking_crit; int holding_crit; int num_subnets; char site_license_info [VLS_SITEINFOLEN]; long hold_time; int meter_value; char vendor_info [VLS_VENINFOLEN + 1]; char cl_lock_info[VLS_MAXCLLOCKLEN]; long key_life_time; int sharing_limit; int

soft_num_licenses;

int is_standalone; int check_time_tamper; int

is_additive;

int isRedundant; int majority_rule; int isCommuter; int log_encrypt_level; int elan_key_flag; long conversion_time; long avg_queue_time; long queue_length; int tot_lic_reqd; int isELMEnabled; int commuted_keys; int commuter_keys_left; char server_locking_info[VLS_MAXSRVLOCKLEN];

1.57. feature_info_struct (VLSfeatureInfo)

int capacity_flag; unsigned long capacity; unsigned long total_resv_capacity; unsigned long in_use_capacity_from_reserved; unsigned long in_use_capacity_from_unreserved; long commuter_max_checkout_days; long grace_period_flag; long grace_period_calendar_days; long grace_period_elapsed_hours; int num_subnets; long overdraft_flag; long overdraft_hours; long overdraft_s; long overdraft_s_in_use; int local_request_lockcrit_flag; int local_request_lockcrit_required; int local_request_lockcrit_float; int local_request_lockcrit_min_num; int isGraceLicense; int license_version; char plain_vendor_info; int trial_elapsed_hours; int trial_execution_count; int trial_calendar_period_left; int trial_elapsed_period_left; int trial_executions_left; int trial_current_status; VLS_VM_DETECTION vm_detection; } VLSfeatureInfo;

Member structSz

Description Size of VLSfeatureInfo structure.

feature_name Name of the feature whose information is retrieved. Maximum 24 characters. version

Feature version. Maximum 11 characters.

lic_type

Type of license either trial or normal.

trial_days_ count

Number of trial days.

birth_day

Day of the license start date. The constant VLS_NO_EXPIRATION is returned for licenses with no limit set on birth date.

death_day

The time when the feature expires. The constant VLS_NO_EXPIRATION is returned if the license does not have any expiration date.

num_licenses The total number of licenses the license server is authorized to issue. Number of licenses reserved using group reservations. total_resv lic_from_resv Number of reserved licenses issued to clients.

107

108

Chapter 1: Sentinel RMS Licensing Library API

Member qlic_from_ free_pool is_node_ locked

Description Number of unreserved licenses issued to queued clients. Depending on the locking scheme of the feature, this returns one of the following constants: n n n n

VLS_NODE_LOCKED (client locked to license server) VLS_CLIENT_NODE_LOCKED (client locked) VLS_FLOATING (license server locked) VLS_DEMO_MODE (unlocked)

concurrency

Unused.

sharing_crit

Returns the license sharing criteria, which can be one of the following constants: n n n n n

locking_crit

The license server locking criteria, which can be one of the following constants: n n n n n n n n n n n n

holding_crit

VLS_LOCK_ID_PROM VLS_LOCK_IP_ADDR VLS_LOCK_DISK_ID VLS_LOCK_HOSTNAME VLS_LOCK_ETHERNET VLS_LOCK_PORTABLE_SERV VLS_LOCK_CUSTOM VLS_LOCK_CUSTOMEX VLS_LOCK_U VLS_LOCK_HARD_DISK_SERIAL VLS_LOCK_U_INFO  VLS_LOCK_UUID

The license holding criteria, which can be one of the following constants: n n

n

hold_time

VLS_NO_SHARING VLS__NAME_ID VLS_CLIENT_HOST_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

VLS_HOLD_NONE (no held licenses). VLS_HOLD_VENDOR (the client specifies the hold time through the function, VLSsetHoldTime). VLS_HOLD_CODE (the license code specifies the hold time).

The hold time specified for licenses issued for this feature.

num_subnets The number of subnet specifications provided for the site. site_license_ A space-separated list of subnet wildcard specifications. info meter_value Unused. vendor_info

The vendor-defined information string. The maximum length of vendor_info string can be up to 2000 characters.

cl_lock_info

Locking information about clients in a space-separated string of host IDs and/or IP addresses.

1.57. feature_info_struct (VLSfeatureInfo)

Member

Description If licenses-per-node restrictions have been specified, they are also returned in parentheses with each host ID/IP address. For instance, cl_lock_info could be: 0x8ef38b91(20#) 0xa4c7188d 0x51f8c94a(10#).

key_life_time The license lifetime for this feature (in seconds). sharing_limit The limit on how many copies of the licensed application can share the same license. soft_num_ licenses

The soft limit (for alerts) on the number of concurrent s of this feature.

is_standalone The license type as any of the following: n n n

VLS_STANDALONE_MODE - for a stand-alone license VLS_NETWORK_MODE - for a network license VLS_PERPETUAL_MODE - for a repository license

check_time_ tamper

Returns VLS_TRUE if this feature is time tamper proof or VLS_FALSE if not time tamper proof.

is_additive

Returns VLS_TRUE if this is an additive license or VLS_FALSE if this is an exclusive license. The license type as any of the following: n n n

isRedundant

VLS_ADDITIVE - for an additive license VLS_EXCLUSIVE - for an exclusive license VLS_AGGREGATE - for an aggregate license

Validates if the license is actually redundant.

majority_rule Checks whether majority rule is on or off. num_servers Number of redundant license servers. isCommuter

Commuter licenses.

log_encrypt_ level

Encryption level in the network license for the license server’s usage log file.

avg_queue_ time

Average time the past or present clients are in the queue. (Not implemented.)

queue_length Length of the queue. tot_lic_reqd Required number of licenses for all queued clients. commuted_ keys

Number of commuter keys that have been checked out.

commuter_ keys_left

Number of computer keys left.

server_locking_info

Stores the server locking information.

capacity_flag

The capacity flag can be one of the following constants: n n n

VLS_CAPACITY_NONE - for no capacity VLS_CAPACITY_NON_POOLED - for non-pooled capacity VLS_CAPACITY_POOLED - for pooled capacity

109

110

Chapter 1: Sentinel RMS Licensing Library API

Member capacity total_resv_ capacity

Description Total capacity of the license. Total reserved capacity.

in_use_capac- Capacity given to clients from reserved capacity. ity_from_ reserved in_use_capac- Capacity given to clients from unreserved capacity. ity_from_unreserved The maximum number of days a commuter license can be checked out for. commuter_ max_checkout_days grace_period_ A flag that decides whether grace period for a license will be provided or not. It can be any of the following constants: flag n n

VLS_NO_GRACE_PERIOD - grace period not allowed (default) VLS_STANDARD_GRACE_PERIOD - grace period allowed

grace_period_ The number of days the grace period will last for. It can be a value between 1 to calendar_days 180 days. grace_period_ The number of hours the grace period will last for. It can be a value between 1 to 1440 hours. elapsed_ hours lic_from_free_ Number of unreserved licenses issued to clients. pool overdraft_flag Not ed. overdraft_ hours

Not ed.

overdraft_ s

Not ed.

overdraft_ s_in_use

Not ed.

The flag that sets the local license request locking criteria. local_ request_lockcrit_flag The necessary number of locking license criteria that must be met for making the local_ request_lock- licenses available to a local client. crit_required The desired number of locking license criteria that must be met for making the local_ request_lock- licenses available to a local client crit_float The minimum number of locking license criteria that must be met for making the local_ request_lock- licenses available to a local client. crit_min_num For example, the “required” criteria can be disk ID, the “floating” criteria can be ethernet card and CID key, and the “minimum” criteria can be any 2 of the

1.57. feature_info_struct (VLSfeatureInfo)

Member

Description above.

isGraceLicense Set to VLS_TRUE only when the grace period is available for the local request license_version

The Sentinel RMS license version. The possible values are: n n n n

n n n n n

n

n

plain_vendor_info

VLS_LICENSE_VERSION_850 - For Sentinel RMS 8.5.0 licenses VLS_LICENSE_VERSION_840 - For Sentinel RMS 8.4.0 and 8.4.1 licenses VLS_LICENSE_VERSION_823 - For Sentinel RMS 8.2.3 licenses VLS_LICENSE_VERSION_810 - For Sentinel RMS 8.1.x, 8.2.0, 8.2.1, 8.2.2 licenses VLS_LICENSE_VERSION_800 - For Sentinel RMS 8.0.x licenses VLS_LICENSE_VERSION_7301 - For Sentinel RMS 7.3.0.1 licenses VLS_LICENSE_VERSION_730 - For Sentinel RMS 7.3.0 licenses VLS_LICENSE_VERSION_700 - For Sentinel RMS 7.0.0 licenses VLS_LICENSE_VERSION_TOO_OLD - For licenses older than Sentinel RMS 7.0.0 VLS_LICENSE_VERSION_LATEST - For the latest version of Sentinel RMS licenses VLS_LICENSE_VERSION_NOT_DEFINED - When the license version is not defined

The public vendor information included in the license.

trial_elapsed_ The number of hours for which the trial license is used so far. hours trial_ execution_ count

The maximum limit of the executions count of a trial license.

trial_calendar_ period_left

The total number of days left for using a trial license.

trial_elapsed_ The number of seconds left in the trial elapsed time period. Valid only if elapsed period_left time is being enforced. trial_ The number of executions left in the trial license. Valid only if executions are being executions_ measured. left trial_current_ Can be any of the following: status n VLS_TRIAL_UNUSED - The license has never been requested and therefore the trial period has not yet begun. n VLS_TRIAL_ACTIVE - License is requested at least once,but some trial usage is still left. n VLS_TRIAL_EXHAUSTED - Usage limit of trial license is exhausted. vm_detection License requests are allowed or not if virtual machine is detected.

111

112

Chapter 1: Sentinel RMS Licensing Library API

1.58. VLSgetFeatureInfo Client √

Server

Static Library √

DLL √

Retrieves licensing information about a feature using the structure, feature_info.

1.58.1. Syntax LS_STATUS_CODE VLSgetFeatureInfo ( char

*name,

char

*version,

int char VLSfeatureInfo

Argument

index, *unused1, *featureInfo );

name

Description Name of the feature. Maximum of 64 characters, including NULL termination character.

version

Version of the feature.

index

Used to specify a particular client.

unused1

Use NULL as the value.

featureInfo (out)

The structure in which information will be returned. Space must be allocated by caller.

1.58.2. Description Returns information on all features. You will need to initialize the structSz field of the VLSfeatureInfo structure being ed to this call before actually calling it. If name is not NULL, information about the feature indicated by name and version is returned. If information about all licensed features is desired, name should be NULL, and index should be used in a loop as described for the function call, VLSgetClientInfo. Refer to the source code of the lsmon.c utility for additional information. VLSgetFeatureInfo returns the status code, VLS_NO_MORE_FEATURES, when it runs out of features to describe. If an error occurs, for example, the feature is unknown to the Sentinel RMS license server, an appropriate error code is returned.

1.58.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n featureInfo is NULL n index is negative

1.58. VLSgetFeatureInfo

113

Error Code

Description n Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. n When max feature name length exceeds 64 characters.

VLS_APP_UNNAMED

version is NULL when name is non_NULL.

VLS_NO_MORE_FEATURES

Finished retrieving feature information for all features on license server.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER-FILE

No license server has been set and unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

114

Chapter 1: Sentinel RMS Licensing Library API

1.59. VLSgetVersions Client √

Server

Static Library √

DLL √

Returns the list of versions licensed by the license server for a given feature.

1.59.1. Syntax LS_STATUS_CODE VLSgetVersions ( char

*featureName,

int

bufferSize,

char char

Argument

*versionList, *unused1 );

featureName

Description Name of the feature.

bufferSize

Specifies the size of versionList.

versionList (out)

An array containing the version list. Space should be allocated by the caller.

unused1

Use NULL as the value.

1.59.2. Description This function returns a list of versions separated by spaces in the array, versionList. Space for this array must be allocated prior to the call, and the size of the array must be provided using bufferSize. This function is useful in situations where you could have licenses for several versions of your software and you wish to implement version-based licensing schemes.

1.59.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following: Error Code

VLS_NO_SUCH_FEATURE

Description License server does not have a license that matches the requested feature, version and capacity.

VLS_APP_UNNAMED

featureName is NULL.

VLS_CALLING_ERROR

Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

VLS_NO_SERVER_ RUN- License server on specified host is not available for processing license NING operation requests. VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

1.59. VLSgetVersions

Error Code

Description VLS_BAD_SERVER_ MES- Message from license server could not be understood. SAGE LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_BUFFER_TOO_ SMALL

An error occurred in the use of an internal buffer.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

115

116

Chapter 1: Sentinel RMS Licensing Library API

1.60. VLSgetFeatureFromHandle Client √

Server

Static Library √

DLL √

Returns the feature name corresponding to handle.

1.60.1. Syntax LS_STATUS_CODE

VLSgetFeatureFromHandle (

LS_HANDLE

handle,

char

*buffer,

int

Argument

bufferSize );

handle

Description Handle returned by license request API.

buffer (out)

Buffer to hold the feature name. Space allocated by caller.

bufferSize

Size of the buffer.

1.60.2. Description The feature name is returned in buffer which must be allocated by the calling program. The size of buffer is ed in the argument bufferSize.

1.60.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_BADHANDLE LS_BUFFER_TOO_SMALL

Description Invalid handle. n n

buffer parameter is NULL. Size of feature information exceeds bufferSize parameter.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.61. VLSgetVersionFromHandle

117

1.61. VLSgetVersionFromHandle Client √

Server

Static Library √

DLL √

Returns the version corresponding to handle. 

1.61.1. Syntax LS_STATUS_CODE VLSgetVersionFromHandle ( LS_HANDLE char int

Argument

handle, *buffer, bufferSize );

handle

Description Handle returned by LSRequest or VLSrequestExt.

buffer (OUT)

Buffer to hold the feature version. Space allocated by caller.

bufferSize

Size of the buffer.

1.61.2. Description  The feature version is returned in buffer which must be allocated by the calling program. The size of buffer is ed in the argument, bufferSize.

1.61.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_BADHANDLE LS_BUFFER_TOO_SMALL

Description Invalid handle. n n

buffer parameter is NULL. Size of feature information exceeds bufferSize parameter.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

118

Chapter 1: Sentinel RMS Licensing Library API

1.62. VLSgetTimeDriftFromHandle Client √

Server

Static Library √

DLL √

1.62.1. Syntax LS_STATUS_CODE

VLSgetTimeDriftFromHandle (

LS_HANDLE lshandle, long *secondsServerAheadOfClient );

Argument lshandle secondsServerAheadOf Client

Description Handle returned by LSRequest, VLSrequestExt, or VLSqueuedRequest. Caller allocates memory for *out* data. Function returns the difference between system clocks.

1.62.2. Description The function is used when the time properties of the client and server may not be in sync. It returns the difference in seconds between the estimated current time on the license server and the estimated time on the client. The estimation error is usually the network latency time. The information returned by this function will be correct only immediately after acquiring the handle. The information in the handle is not updated subsequently.

1.62.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_BADHANDLE

Description Invalid handle.

LS_BUFFER_TOO_SMALL

secondsServerAheadOfClient parameter is NULL.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.63. VLSgetFeatureTimeLeftFromHandle

119

1.63. VLSgetFeatureTimeLeftFromHandle Client √

Server

Static Library √

DLL √

1.63.1. Syntax LS_STATUS_CODE LS_HANDLE unsigned long

VLSgetFeatureTimeLeftFromHandle ( lshandle, *secondsUntilTheFeatureExpires );

Argument lshandle

Description Handle returned by LSRequest or VLSrequestExt.

secondsUntilTheFeature Expires

Caller allocates memory for *out* data. Function returns the number of seconds until the expiration of the license for this feature.

1.63.2. Description The function is used when the time properties of the client and server may not be in sync. It returns the difference in seconds between the estimated current time on the license server and the estimated feature expiration time on the license server. The information returned by this function will be correct only immediately after acquiring the handle. The information in the handle is not updated subsequently. VLSgetFeatureTimeLeftFromHandle provides the difference between the License Expiration Time and the Current System Time at the client end. For example, if the license expiration date is 20th Aug. 1998 (12:00PM) and the current time of the client machine is 16th June 1998 (12:00AM), then this call will return the difference between these two times, in seconds. VLSgetFeatureTimeLeftFromHandle does not return the number of trial days left in a trial license.

1.63.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following: Error Code

LS_BADHANDLE

Description Invalid handle.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches the requested feature, version and capacity.

LS_BUFFER_TOO_SMALL

secondsUntilTheFeatureExpires is NULL.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_NO_SERVER_RESPONSE Communication with the license server has timed out. VLS_HOST_UNKNOWN

Invalid hostName was specified.

120

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_NO_SERVER_FILE

Description The license server has not been set and the client application is unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be understood. LS_NO_NETWORK

Generic error indicating that the network is unavailable for licensing.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.64. VLSgetKeyTimeLeftFromHandle

121

1.64. VLSgetKeyTimeLeftFromHandle Client √

Server

Static Library √

DLL √

1.64.1. Syntax LS_STATUS_CODE LS_HANDLE unsigned long

VLSgetKeyTimeLeftFromHandle ( lshandle, *secondsUntilTheKeyExpires );

Argument lshandle secondsUntilTheFeature Expires

Description Handle returned by LSRequest or VLSrequestExt. Caller allocates memory for *out* data. Function returns the number of seconds for the run-time license to expire.

1.64.2. Description The function is used when the time properties of the client and server may not be in sync. It returns the difference in seconds between the estimated current time on the license server and the estimated license expiration time on the license server. The information returned by this function will be correct only immediately after acquiring the handle. The information in the handle is not updated subsequently. VLSgetkeyTimeLeftFromHandle returns the difference between the time when the license token (as issued by the license server to the client) expires (i.e., before this client must do an LSupdate) and the current time. Since the information in the handle is not updated at regular intervals, the value returned by this call is in very close proximity to the key lifetime mentioned in the license. For example, if the token lifetime mentioned in the license is 2 minutes, the value returned by this call will be approximately 120. Naturally, this value varies with each client.

1.64.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

LS_BADHANDLE

Description Invalid handle.

LS_BUFFER_TOO_SMALL

secondsUntilTheKeyExpires parameter is NULL.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

122

Chapter 1: Sentinel RMS Licensing Library API

The Client Utility Functions This section describes the API functions that provide client library capabilities useful to certain specialized applications. Given below is the list of the API functions:

Function

Description

VLSdiscover

Retrieves the names of the computers on the local subnet (or beyond) running the Sentinel RMS license server which are authorized to service requests from an application.

VLSaddFeature

Adds licensing information to the license server’s internal tables.

VLSaddFeatureToFile

Adds licensing information about a feature to both the license file and license server’s internal tables.

VLSdeleteFeature

Removes licensing information from the license server’s internal tables.

VLSdeleteLicenseFromFile

Deletes a non-capacity license from the license server's memory and file.

VLSdeleteLicenseFromFileExt Deletes both capacity and non-capacity licenses from the license server's memory and file. VLSgetLibInfo

Retrieves information about the Sentinel RMS client library.

VLSshutDown

Shuts down the license server.

1.65. VLSdiscover

123

1.65. VLSdiscover Client √

Server

Static Library √

DLL √

Retrieves the names of the computers on the local subnet (or beyond) running the Sentinel RMS license server which are authorized to service requests from an application.

1.65.1. Syntax LS_STATUS_CODE VLSdiscover ( unsigned char

*feature_name,

unsigned char

*version,

unsigned char

*reserved1,

int char int char

Argument

server_list_len, *server_list, optionFlag, *query_list );

feature_name

Description Name of the feature.

version

Version of the feature.

reserved1

Use any value.

server_list_len

Specifies the size of server_list.

server_list (OUT)

Space separated list of license server names.

optionFlag

A three bit flag which guides the behavior of VLSdiscover in finding the license servers. Details are discussed later.

query_list

A colon separated list of hostNames to be queried during the search for license servers.

1.65.2. Description feature_name, must be licensed by the same vendor as the library issuing the VLSdiscover call. If version is NULL, it is treated as a wildcard and all license servers that are authorized to service requests for feature_name will respond regardless of version. If feature_name is NULL, version will be ignored and all Sentinel RMS license servers on the local subnet will respond. The space-separated name list of the responding Sentinel RMS license servers are returned in server_list. The buffer must be allocated prior to the call and its size provided using server_list_len. query_list is a colon-separated list of host names and/or IP-addresses which are queried during the search for license servers. optionFlag is a three-bit flag which can have any of the following values or a combination of them:

124

Chapter 1: Sentinel RMS Licensing Library API

n

n

n

n

VLS_DISC_NO_LIST - Does not check the host list specified by the . By default, it first checks the LSFORCEHOST environment variable. If LSFORCEHOST doesn’t exist, it reads the list specified by the in the environment variable, LSHOST, and the file, LSHOST/lshost. (The content of these lists are ed together and appended to the contents of query_list) append them together and then append to the query_list. Finally, all the hosts on this combined list are queried during search for license servers. VLS_DISC_RET_ON_FIRST - If the combined query list is NULL, this function returns as soon as it s a license server and returns the name of this license server in server_list. Otherwise, it returns when it hears from a license server whose name is listed in the combined query list. In this case, it returns, in server_list, that particular license server name along with all other license servers which are not on the list, but responded by that time. If this option is not specified, this function, VLSdiscover, obtains all the names of all the license servers which responded. VLS_DISC_PRIORITIZED_LIST - Treats the combined query list as a prioritized one, the leftmost being the highest priority host. After execution, server_list contains license servers sorted by this priority. If this option is not specified, the combined query list is treated as a random one. VLS_DISC_DEFAULT_OPTIONS/VLS_DISC_NO_OPTIONS - Use these if you do not want to specify any flags.

1.65.3. Returns The status code LS_SUCCESS is returned if stand-alone library is used. Otherwise, it will return the following error codes: Error Code

VLS_NO_RESPONSE_ TO_ BROADCAST

Description No license servers have responded.

LS_NO_SUCCESS

Failed to retrieve computer names on local subnet.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

1.65.4. Examples To get a list of all the Sentinel RMS license servers running on the subnet, the call can be made as: char server_list[MAX_BUF]; VLSdiscover(NULL, NULL, NULL, MAX_BUF, server_list, VLS_DISC_NO_OPTIONS, NULL);

To get one license server having feature for all versions of application, dots: char server_list[MAX_BUF]; VLSdiscover("DOTS", NULL, NULL, MAX_BUF, server_list, VLS_DISC_RET_ON_FIRST,NULL);

where “DOTS” is the feature name for the application, dots.

1.65. VLSdiscover

To find out license servers for dots version 1.0 running on the local subnet as well as on computers 'troilus.soft.net' and '123.23.234.1', and get the results in prioritized order: char query_list[100]; char server_list[MAX_BUF]; stry(query_list, "troilus.soft.net:123.23.234.1"); VLSdiscover("DOTS", "1.0", NULL, MAX_BUF, server_list, VLS_DISC_PRIORITIZED_LIST, query_list);

125

126

Chapter 1: Sentinel RMS Licensing Library API

1.66. VLSaddFeature Client √

Server

Static Library √

DLL √

Adds licensing information about a feature.

1.66.1. Syntax LS_STATUS_CODE

VLSaddFeature ( unsigned char

*licenseString,

unsigned char

*unused1,

LS_CHALLENGE

Argument

*unused2 );

licenseString

Description String containing licensing information.

unused1

Use NULL as the value.

unused2

Use NULL as the value.

1.66.2. Description Dynamically adds the license code, licenseString, to the license server’s internal tables. If licensing information for this feature and version already exists in the license server’s tables, it may be overwritten with the new information. The feature is not permanently added to the license server, therefore the feature will not be on the license server when the license server is shutdown and restarted.

1.66.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

LS_NO_SUCCESS

licenseString is NULL.

VLS_ADD_LIC_FAILED

Generic error indicating the feature has not been added.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

1.66. VLSaddFeature

127

Error Code VLS_BAD_SERVER_MESSAGE

Description Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

128

Chapter 1: Sentinel RMS Licensing Library API

1.67. VLSaddFeatureToFile Client √

Server

Static Library √

DLL √

Adds licensing information about a feature.

1.67.1. Syntax LS_STATUS_CODE

VLSaddFeatureToFile ( unsigned char

*licenseString,

unsigned char

*unused1,

unsigned char

*unused2,

LS_CHALLENGE

Argument

*unused3 );

licenseString

Description String containing licensing information.

unused1

Use NULL as the value.

unused2

Use NULL as the value.

unused3

Use NULL as the value.

1.67.2. Description Dynamically adds licensing information about a feature to the license server’s internal tables. If licensing information for this feature already exists in the license server’s tables, it may be overwritten with the new information. The feature is permanently added to the license server, therefore the feature will be on the license server when the license server is shutdown and restarted.

1.67.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following: Error Code VLS_CALLING_ERROR

Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

LS_NO_SUCCESS

licenseString is NULL.

VLS_ADD_LIC_FAILED

Generic error indicating the feature has not been added.

VLS_NO_SERVER_RUNNING License server on specified host is not available for processing the license operation requests. VLS_NO_SERVER_RESPONSE Communication with license server has timed out. VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

1.67. VLSaddFeatureToFile

Error Code Description VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be understood. LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing the license operation.

LS_NORESOURCES

An error occurred in allocating memory needed by the function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

129

130

Chapter 1: Sentinel RMS Licensing Library API

1.68. VLSdeleteFeature Client √

Server

Deletes licensing information about a feature.

Static Library √

DLL √

1.69. Syntax

131

1.69. Syntax LS_STATUS_CODE VLSdeleteFeature ( unsigned char *featureName, unsigned char *version, unsigned char *unused1, LS_CHALLENGE *unused2 );

Argument featureName

Description Name of the feature. Maximum of 64 characters, including NULL termination character.

version

Version of the feature.

unused2

Unused.

unused3

Unused.

1.69.1. Description Deletes licensing information from the license server’s internal tables, for the given featureName and version. This call does not delete licenses from the license file.

1.69.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_APP_UNNAMED

Description n featureName is NULL n version is NULL. n Both feature name and version cannot be NULL at the same time.

VLS_CALLING_ERROR

Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_DELETE_LIC_FAILED

Generic error indicating the feature has not been deleted.

VLS_VENDORIDMISMATCH

The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has a license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_MULTIPLE_VENDORID_ FOUND

The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

132

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_NO_SERVER_RESPONSE

Description Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.70. VLSdeleteLicenseFromFile

1.70. VLSdeleteLicenseFromFile Client √

Server

Static Library √

DLL √

Deletes a non-capacity license from the license server's memory and file.

1.70.1. Syntax LS_STATUS_CODE VLSdeleteLicenseFromFile ( unsigned char

*feature_name,

unsigned char

*version,

unsigned char

*license_hash,

int unsigned char int

Argument

license_hash_len, *license_string, *license_string_bufsize,

void

*unused1,

int

unused2 );

feature_name

Description The feature name identifier of the license code.

version

The version identifier of the license code.

license_hash

The license hash to identify a specific license code.

license_hash_len,

The allocated size for the license hash, ed as input.

license_string

An OUT parameter. The deleted license code returned by the license server.

license_string_bufsize

An IN/OUT parameter. Allocated size for the license code ed as input. Returns the actual size of the deleted license string. This buffer size must be equal to macro VLS_MAX_LICENSE_SIZE.

unused1

An unused variable.

unused2

An unused variable.

1.70.2. Description Deletes a non-capacity license code that is not in use, from the license server's memory and the license file. The license code to be deleted is identified by the feature-version-license hash combination.

133

134

Chapter 1: Sentinel RMS Licensing Library API

This API returns the deleted license code back to the caller. The caller needs to allocate the buffer for the license_string argument. The size of this buffer is ed as the license_string_bufsize argument. The license code deletion process fails, if the license code to be deleted is in use. If the license_string is ed as NULL. In this case, the API does not return the deleted license_string back to the caller. The VLSgetLicenseInfo API can be used to obtain information about licenses installed. It returns a structure containing license hash value to identify a license code.

1.70.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description Argument specified is not correct, that is, one of the following reasons exist: n

n n

n

n

If license_hash_len < 1 or license_hash_len > VLS_ MAX_LICENSE_HASH_LEN. If license_hash is ed as NULL. If license_string is not NULL and license_string_bufsize is NULL. If feature_name or version buffer size exceeds the maximum size limit Specified as VLS_MAXFEALEN and VLS_MAXVERLEN respectively. If the length of license_hash ed is more than VLS_MAX_LICENSE_HASH_LEN.

VLS_APP_UNNAMED

When any of the following parameters (feature_name, version, and license hash) is NULL. Or, they contain only the NUL character i.e '\0'.

VLS_NO_SUCH_FEATURE

License with ed feature-version combination not found.

VLS_NO_SUCH_LICENSE

License with ed feature-version-license hash combination not found.

LS_BUFFER_TOO_SMALL

This indicates an error that the allocated buffer is insufficient to store the deleted license string.

VLS_LICENSE_IN_USE

This indicates an error that the license to be deleted is currently in use. This means that the specified license has some active clients.

VLS_STORE_ACCESS_ERROR

This indicates failure in accessing the license file.

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API. LS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_DELETE_LIC_FAILED

This indicates a generic error that the license deletion process has failed.

VLS_MULTIPLE_VENDORID_ FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the

1.70. VLSdeleteLicenseFromFile

Error Code

Description Vendor ID for all these licenses is different from the licensing library's Vendor ID.

VLS_SEVERE_INTERNAL_ERROR This indicates failure that occurs in internal message construction and splitting while processing the API. LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

VLS_CAPACITY_MISMATCH

Error indicating that the license to be deleted is a capacity license.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

135

136

Chapter 1: Sentinel RMS Licensing Library API

1.71. VLSdeleteLicenseFromFileExt Client √

Server

Static Library √

DLL √

Deletes both capacity and non-capacity licenses from the license server's memory and file.

1.71.1. Syntax LS_STATUS_CODE VLSdeleteLicenseFromFileExt ( unsigned char

*feature_name,

unsigned char

*version,

unsigned long

*capacity,

unsigned char

*license_hash,

int unsigned char int

Argument

license_hash_len, *license_string *license_string_bufsize,

void

*unused1,

int

unused2 );

feature_name

Description The feature name identifier of the license string.

version

The version identifier of the license string.

capacity

The capacity identifier of the license string.

license_hash

The license hash to identify a specific license string.

license_hash_len

The allocated size for License hash ed as input.

license_string

An OUT parameter. The deleted license string returned by the license server.

license_string_bufsize

An IN/OUT parameter. The allocated size for license string ed as input, will return the actual size of the deleted license string.

unused1

An unused variable.

unused2

An unused variable.

1.71.2. Description Allows deletion of both non-capacity and capacity license code, that is not in use, from the license server's memory and the license file. A license code to be deleted is identified by the feature-versioncapacity-license hash combination. The API identifies a license using the following: n

If the license to be deleted is a capacity license, then, the requisite capacity value should be ed in the capacity parameter.

1.71. VLSdeleteLicenseFromFileExt

n

137

If the license to be deleted is a non-capacity license, then, the capacity parameter needs to be ed as NULL.

1.71.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description Argument specified is not correct, that is, one of the following reasons exist: n n n

n

n

n

If license_hash_len < 1. If license_hash is ed as NULL. If license_string is not NULL and license_string_bufsize is NULL. If feature_name or version buffer size exceeds the maximum size limit Specified as VLS_MAXFEALEN and VLS_MAXVERLEN respectively. If length of license_hash ed is more than VLS_ MAX_LICENSE_HASH_LEN. If length of license_hash ed is more than VLS_ MAX_LICENSE_HASH_LEN.

VLS_APP_UNNAMED

When feature_name or version parameter is NULL. Or, feature_name contains only the NULL character i.e '\0'.

VLS_NO_SUCH_FEATURE

License with ed feature-version combination not found.

VLS_NO_SUCH_LICENSE

License with ed feature-version-license hash combination not found.

LS_BUFFER_TOO_SMALL

This indicates an error that the allocated buffer is insufficient to store the deleted license string.

VLS_LICENSE_IN_USE

This indicates an error that the license to be deleted is currently in use. This means that the specified license has some active clients.

VLS_STORE_ACCESS_ERROR

This indicates failure in accessing the license file.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

LS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_DELETE_LIC_FAILED

This indicates a generic error that the license deletion process has failed.

VLS_MULTIPLE_VENDORID_FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the Vendor ID for all these licenses is different from the licensing library's Vendor ID.

VLS_SEVERE_INTERNAL_ERROR

This indicates failure that occurs in internal message construction and splitting while processing the API.

138

Chapter 1: Sentinel RMS Licensing Library API

Error Code

LS_NO_NETWORK

Description Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

VLS_CAPACITY_MISMATCH

Error indicating that NULL is ed as capacity argument for deleting a capacity license or vice-a-versa. Incorrect capacity value is ed as argument for deleting a capacity license.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.72. VLSgetLibInfo

1.72. VLSgetLibInfo Returns information about the licensing library currently being used in the structure pointed to by pInfo.

1.72.1. Syntax LS_STATUS_CODE

VLSgetLibInfo(LS_LIBVERSION *pInfo)

typedef struct { unsigned long

ulInfoCode;

char

szVersion

char

szProtocol [LIBINFOLEN];

[LIBINFOLEN];

char

szPlatform [LIBINFOLEN];

char

szLocale

[LIBINFOLEN];

char

szUnused2

[VERSTRLEN];

} LS_LIBVERSION

Member ulInfoCode

Description Unused.

szVersion

The version of the licensing library.

szProtocol

The communication protocol being used for application/license server communication.

szPlatform

The platform of the client application.

szLocale

The locale of the client system.

szUnused2

Unused.

1.72.2. Description Space for pInfo must be allocated by the caller.

1.72.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Codes

LS_NORESOURCES

Description pInfo is NULL.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

139

140

Chapter 1: Sentinel RMS Licensing Library API

1.73. VLSshutDown Client √

Server

Static Library √

DLL √

Shuts down license server at specified hostname. 

1.73.1. Syntax LS_STATUS_CODE VLSshutDown ( char *hostname );

Argument hostname

Description The host name of the computer running the license server.

1.73.2. Description  A client can send this message to the license server in order to shut the license server down. Once shut down, there is no automatic way of restarting the license server through any client message. Any applications that may be running at that time could stop running after a while, as the license renewal messages will fail once the license server goes down. The license server does not check for running applications prior to shutting down. The following permissions tests must succeed in order for this call to be successful: n

n

The client and license server must be running on the same network domain name. identification of the license server process should match the client, or client must be run by super (root) as shown in the following table:

Server Operating System

UNIX (non-root)

Windows UNIX 2000/XP/2003/Vista/7/2008 (non() root) —

Client

UNIX (root)

Same - — Name or Id

Windows Yes 2000/XP/2003/Vista/7/2008 ()

Yes

Yes

UNIX (root)

Yes

Yes

Yes

1.73.3. Returns  The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following:

1.73. VLSshutDown

Error Codes

VLS_CALLING_ERROR LS_NORESOURCES

Description hostName parameter is NULL. An error occurred in attempting to allocate memory needed by function.

VLS_NO_SERVER_ RUN- License server on specified host is not available for processing the NING license operation requests. VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN Invalid hostName is specified. VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

141

142

Chapter 1: Sentinel RMS Licensing Library API

The Trial License Related Functions This section describes the API functions related to trial licensing. Given below is the list of the API functions:

Function

Description

VLSgetTrialUsageInfo

Retrieves the usage information for a trial license.

VLSsetLicensePrecedence Sets the precedence value for a trial license. VLSgetTrialPeriodLeft

Returns the remaining time left in a trial license.

1.74. VLStrialUsageInfo

143

1.74. VLStrialUsageInfo The total usage information—the remaining hours and days—of all the trial licenses with the same feature-version combination is stored in the following structure.

1.74.1. Syntax typedef struct

trial_usage_info_struct { long

structSz;

char

feature_name[VLS_MAXFEALEN + 1];

char

version[VLS_MAXFEALEN + 1];

int

cumulative_trial_calendar_period;

int

cumulative_trial_elapsed_hours;

int

cumulative_trial_execution_count;

int

cumulative_trial_calendar_period_left;

int

cumulative_trial_elapsed_period_left;

int

cumulative_trial_executions_left;

}VLStrialUsageInfo;

Member structSz

Description Size of VLStrialUsageInfo structure.

feature_name

Name of the feature whose information is retrieved.Space is allocated for 64 characters, but currently maximum 24 characters long feature name is ed.

version

Feature version. Maximum 11 characters.

Cumulative_trial_calendar_period

Total trial days of all the trial licenses added.

Cumulative_trial_elapsed_hours

Total trial hours of all the trial licenses added.

Cumulative_trial_execution_count

Total trial execution count of all the trial licenses added. 11

Cumulative_trial_calendar_period_left Total trial days left. Cumulative_trial_elapsed_period_left Total trial usage left (in seconds). Cumulative_trial_executions_left

Total trial execution count left.

1The execution count based trial licenses are not ed as of now.

144

Chapter 1: Sentinel RMS Licensing Library API

1.75. VLSgetTrialUsageInfo Client √

Server

Static Library √

DLL √

Obtains cumulative usage (both total and remaining) information about all the trial licenses available on the license server for a feature-version.

1.75.1. Syntax LS_STATUS_CODE VLSgetTrialUsageInfo ( unsigned char

*feature_name,

unsigned char

*version,

int

feature_index,

VLStrialUsageInfo *trial_usage_info );

Argument feature_name

Description The feature name identifier for the license code.

version

Version of the feature. Must be unique.

feature_index

Used to specify a particular feature-version combination.

trial_usage_info

This API function stores the structure in which the information is obtained. The memory for this structure must be allocated by the caller.

1.75.2. Description This API is used to obtain usage information (including hours left and days left) for trial features. n

n

If the active feature is an exclusive trial then the API returns trial usage information for this license only. If the active feature is an additive trial then the API returns cumulative trial usage information. The cumulative usage information is calculated using all activated trial license, that is: n

n

n

10.

n

Licenses with non-zero (0) license precedence when multiple trial license of same feature exists. When trial license precedence is set to run on top of normal license (set to -1), then cumulative information is calculated considering trial licenses with negative license precedence. Additive trial licenses allow seamless dynamic switching to other license, that is, when an additive trial license gets exhausted it would switch to another license provided another license (trial or normal) of the same feature is loaded in the memory.

Similarly, aggregate trial licenses allow dynamic switching to only exclusive (trial or normal) licenses, that is, when an aggregate trial license gets exhausted it would switch to another license provided another license (trial or normal) of the same feature is loaded in the memory.

Consider a scenario where two licenses of feature name MYTRIAL and feature version 1.0 are loaded by the licensing system. Now, trial usage information for the feature would be calculated as below:

1.75. VLSgetTrialUsageInfo

145

Case 1 - Precedence of License 1 is set higher than License 2 (both greater than 0) License 1

License 2

Cumulative Usage

Additive Trial

Additive Trial

License 1 + License 2

Additive Trial

Exclusive Trial

License 1 + License 2

Additive Trial

Aggregate Trial

License 1 + License 2

Exclusive Trial

Additive Trial

License 1

Exclusive Trial

Aggregate Trial

License 1

Exclusive Trial

Exclusive Trial

License 1

Aggregate Trial

AggregateTrial

License 1 + License 2

AggregateTrial

Exclusive Trial

License 1 + License 2

AggregateTrial

Additive Trial

License 1

Normal (Additive/Exclusive) Additive Trial

Error Return

Normal (Additive/Exclusive) Exclusive Trial

Error Return

Case 2 - Precedence of License 1 is set as -1 and License 2 is set as any positive value License 1

License 2

Cumulative Usage

Additive Trial

Additive Trial

License 1 + License 2

Additive Trial

Exclusive Trial

License 1 + License 2

Additive Trial

Aggregate Trial

License 1 + License 2

Exclusive Trial

Additive Trial

License 1

Exclusive Trial

Aggregate Trial

License 1

Exclusive Trial

Exclusive Trial

License 1

Aggregate Trial

Aggregate Trial

License 1 + License 2

Aggregate Trial

Additive Trial

License 1

Aggregate Trial

Exclusive Trial

License 1 + License 2

Additive Trial Aggregate Trial

Normal (Additive/Exclusive/Aggregate) Normal (Additive/Exclusive/Aggregate)

License 1 License 1

Exclusive Trial

Normal (Additive/Exclusive/Aggregate)

License 1

The feature_index argument should be used in a loop to get information of all the features loaded in the memory till the API returns the VLS_NO_MORE_FEATURES status code. Either a feature_name + feature_version combination, or feature_index can be used to reach a particular feature available.

1.75.3. Returns The status code LS_SUCCESS is returned, if successful. The other status codes that may be returned are:

Error Code

Description

VLS_NO_MORE_FEATURES

Finished retrieving all the features added.

If an error occurred, one of the following error codes is returned:

146

Chapter 1: Sentinel RMS Licensing Library API

Error Code

Description

VLS_APP_UNNAMED

If: If feature_name is NULL or feature_name contains only NULL character i.e '\0' and feature_index is less than zero If feature_name is not NULL and version is NULL.

n

n

VLS_CALLING_ERROR

Argument specified is not correct, that is, one of the following reasons exist: n n

If trial_usage_info is NULL. If feature_name or version buffer size exceeds the maximum size limit specified as VLS_MAXFEALEN and VLS_MAXVERLEN, respectively.

VLS_NO_SUCH_FEATURE

License with specified feature-version combination is not found.

VLS_MULTIPLE_VENDORID_FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the Vendor ID for all these licenses is different from the client library's Vendor ID.

VLS_RESOURCE_LOCK_FAILURE

Failed to fetch the API resource lock. On receiving this error, retry calling this API.

VLS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_NON_TRIAL_LICENSE

This indicates that the specified feature is not a trial license. For ex, if the specified feature node contains a normal license.

VLS_TRIAL_LIC_NOT_ACTIVATED

Inactive trial license is queried.

VLS_TRIAL_LIC_EXHAUSTED

The specified feature has an exhausted trial license.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.76. VLSsetLicensePrecedence

147

1.76. VLSsetLicensePrecedence Client √

Server

Static Library √

DLL √

Sets the precedence value for a trial license.

1.76.1. Syntax LS_STATUS_CODE VLSsetLicensePrecedence (

Argument

unsigned char

*feature_name,

unsigned char

*version,

unsigned char

*license_hash,

int

license_hash_len,

int

precedence_level,

void

*ununsed1,

int

ununsed2 );

feature_name

Description Name of the feature.

version

Version of the feature. Must be unique.

license_hash

The license hash for the license code (to identify a specific license).

license_hash_len

The length of the license hash.

precedence_level

Used to specify the precedence level that needs to set for the trial license.

unused1

Unused variable.

unused2

Unused variable.

1.76.2. Description The API sets the precedence level of a trial license. The precedence level ed as argument can be one of the following: n

n

n

0: license code is inactive and cannot be consumed. -1: license code is active and would take precedence over all the licenses, including permanent licenses. This is a special precedence level that makes a trial license most preferred license irrespective of license type. >= 1: Positive values decide preference order of a trial license, among trial licenses, for a given feature. Greater the positive value higher will be the preference for this trial license.

When a trial license is added to the licensing system for the first time, it has the default precedence of 1. The following macros related to license precedence are defined in lserv.h header file:

148

Chapter 1: Sentinel RMS Licensing Library API

n

VLS_PRECEDENCE_TRIAL_OVERRIDE_NORMAL (-1)

n

VLS_PRECEDENCE_DISABLE (0)

n

VLS_PRECEDENCE_DEFAULT (1)

1.76.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Codes

VLS_APP_UNNAMED

Description When the feature_name OR version OR license_hash parameter is NULL. When the feature_name OR license_hash contain only the NULL character i.e "\0".

VLS_CALLING_ERROR

Argument specified is not correct, that is, one of the following reasons exist: If license_hash_len is less than -1 or exceeds the maximum limit i.e VLS_MAX_LICENSE_HASH_LEN. If feature_name or version buffer size exceeds the maximum size limit specified as VLS_MAXFEALEN and VLS_ MAXVERLEN respectively. If precedence_level is less than -1.

VLS_NO_SUCH_FEATURE

The license with feature-version combination ed as an argument not found.

VLS_NO_SUCH_LICENSE

The license with feature-version-license hash combination ed as an argument not found.

VLS_RESOURCE_LOCK_FAILURE

Failed to obtain the API resource lock. On receiving this error, retry calling this API.

VLS_NORESOURCES

Error occurred in allocating resources needed by this API.

VLS_SET_LICENSE_PRECEDENCE_ FAILED

Failed in setting the license precedence.

VLS_TRIAL_LIC_DATA_INCONSISTENT

Failed to set the precedence of a trial license due to the corrupted persistence.

VLS_TRIAL_LIC_DATA_ACCESS_ERROR

Recoverable error is occurred while setting the precedence of a trial license.

VLS_MULTIPLE_VENDORID_FOUND

This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the Vendor ID for all these licenses is different from the licensing library's vendor ID.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_BAD_SERVER_MESSAGE

Message from license server could not be understood.

1.76. VLSsetLicensePrecedence

Error Codes

VLS_CAPACITY_MISMATCH

Description The function is called for a capacity license. It can only be called for non-capacity licenses.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

149

150

Chapter 1: Sentinel RMS Licensing Library API

1.77. VLSgetTrialPeriodLeft Client √

Server

Static Library √

DLL √

1.77.1. Syntax int VLSgetTrialPeriodLeft ( unsigned char *feature_name, unsigned char *version, unsigned long *trialperiod, unsigned long *unused1 );

Argument feature_name

Description Name of the feature.

version

Version of the feature. Must be unique.

trialperiod (OUT)

Number of seconds left in the trial license. Points to integer in the trialperiod parameter.

unused1

Uses NULL as the value.

1.77.2. Description Returns the remaining time left in a trial license. The usage period for trial licenses does not begin until the application is first executed, i.e., not when the application is installed.

1.77.3. Returns The status code LS_SUCCESS is returned if stand-alone library is used. Otherwise, it will return the following error codes:

Error Code VLS_CALLING_ERROR

Description n n n n

feature_name is NULL. version is NULL trialperiod is NULL Both feature name and version cannot be NULL at the same time.

VLS_SEVERE_INTERNAL_ ERROR

An Irrecoverable internal error has occurred in processing.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation request.

VLS_HOST_UNKNOWN

Invalid hostname was specified.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the licensing operation.

1.77. VLSgetTrialPeriodLeft

Error Code

Description

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

VLS_INTERNAL_ERROR

An internal error has occurred in processing.

VLS_NO_TRIAL_INFO

No Trial usage info.

VLS_TRIAL_LIC_ EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS_TRIAL_INFO_ FAILED

Trial usage query failed

VLS_NO_SERVER_FILE

The license server has not been set and the client application is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

An error has occurred in decrypting (or decoding) a network message· Probably an incompatible or unknown server, or a version mismatch.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

151

152

Chapter 1: Sentinel RMS Licensing Library API

Getting the License Server Information Developers sometimes need to know the details about the license servers running on a customer’s computer to see if conflicts are occurring between license servers provided by different developers or to detect a specific license server. The VLSservInfo structure contains the server information. The API call, VLSgetServInfo, provides a data structure into which information about a specific license server can be requested or obtained by a client application.

1.78. VLSservInfo Struct

1.78. VLSservInfo Struct typedef struct { long

structSz;

int

major_no;

int

minor_no;

int

revision_no;

int

build_no;

unsigned char

locale[VLS_SERV_LOCALE_STR_LEN];

unsigned char

vendor_info[VLS_SERV_VNDINFO_STR_LEN];

unsigned char

platform[VLS_SERV_PLATFORM_STR_LEN];

unsigned long

lock_mask;

unsigned char

unused1[VLS_SERV_UNUSED1_STR_LEN];

long VLStimeTamperInfo VLSmachineID

unused2; tmtmpr_info; machine_id;

} VLSservInfo;

Argument structSz

Description Size of the structure. Must be set by the .

major_no

The major number of the server.

minor_no

The minor number of the server.

revision_no

The revision number of the server.

build_no

The build number of the server.

locale

The locale for which the server was built.

vendor_info

Vendor specified license server identification. This can be customized through VLSsetServInfo API. Default is null string

platform

The platform for which the server was built.

lock_mask

Lock selector used in computing the machine ID of the server machine.

unused1

Reserved. Uses NULL as the value.

unused2

Reserved. Uses NULL as the value.

tmtmpr_info

Contains the time tampering related information on the server machine.

machine_id

Machine ID structure. To be used in conjunction with lock_mask to obtain the locking code of the server machine. See VLSmachineIDtoLockCode API for details.

153

154

Chapter 1: Sentinel RMS Licensing Library API

1.79. VLStimeTamperInfo Struct The Sentinel RMS license server is configured to detect tampering of the system clock. You also have the option of implementing your own functionality to retrieve the time tamper informationusing the VLStimeTamperInfo struct. typedef struct

timetampering_info_struct { long

structSz;

time_t

lastTime;

time_t

currTime;

long

grace_period;

int

percentViolationAllowed;

int

numViolationForError;

int

numViolationFound;

int

percentViolationFound;

unsigned long

clkSetBackTime;

} VLStimeTamperInfo;

Argument structSz

Description Size of the structure. Must be set by the .

lastTime

The last known good time when no clock tampering was detected.

currTime

Current time on the server.

grace_period

If Sentinel RMS Development Kit finds the system clock has been set back by less than grace_period seconds, it will not be counted as a violation.

percentViolation Allowed

Percentage of system files that must be found in violation of the grace period before concluding that the system clock has been set back. Used on UNIX systems only.

numViolationFor Error

Number of system files that must be found in violation of the grace period before concluding that the system clock has been set back. Used on UNIX systems only.

numViolationFound

Actual number of system files found in violation of the grace period. Used on UNIX systems only.

percentViolation Found

Percentage of system files found in violation of the grace period. Used on UNIX systems only.

clkSetBackTime

The actual amount of time by which the clock has been set back. This value is zero if no time tampering has been detected.

1.80. VLSgetServInfo

155

1.80. VLSgetServInfo Returns information regarding the given license server, including version, locale, platform, and the locking information of the computer on which the license server is running. After a successful call, the VLSservInfo data structure will contain the information returned from the license server. This call will also return the locking information for the computer on which the license server is running. This can be used to generate lock codes as the echoid utility does.

1.80.1. Syntax LS_STATUS_CODE VLSgetServInfo ( unsigned char VLSservInfo

Argument server_name

srv_info

*server_name, *srv_info,

unsigned char

*unused1,

unsigned long

*unused2 );

Description The name of the server you would like to retrieve information from. You can this as NULL if you want this API call to pick up the server name if previously set by VLSsetServer or LSFORCEHOST. If set to NULL but no server name is found, an error code will be returned. If not set to NULL, this value is independent of the LSHOST, LSFORCEHOST, and VLSsetServer values. This points to the VLSservInfo data structure, which is populated with information returned from the server such as platform, locale, build versions, and locking information. You may not set this to NULL.

1.80.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for the failure. Possible errors returned by this call include VLS_NOT_ED. For a complete list of the error codes, see Licensing Library Error and Result Codes.

156

Chapter 1: Sentinel RMS Licensing Library API

The License Revocation Functions The license revocation allows revocation and/or transfer of licenses already deployed with customers. This option is available both in stand-alone and network licensing scenarios. This section describes the related API functions. For details about the license revocation related API functions and structures prototyped in lscgen.h, see the topic about the license generation functions.

Given below is the list of the API functions:

Function

Description

VLSrevokeByPermissionTicket Verifies the permission ticket, acts on it, and returns the revocation ticket. VLSrevokeLicense

Revokes network licenses based on the pre 8.4.1 network revocation workflow.

1.81. VLSrevokeByPermissionTicket

157

1.81. VLSrevokeByPermissionTicket Client √

Server

Static Library √

DLL √

Revokes stand-alone and network licenses based on the permission and revocation ticket.

1.81.1. Syntax LS_STATUS_CODE

VLSrevokeByPermissionTicket (

unsigned char *pucServerName, unsigned char *puc, unsigned char *puermissionTicket, unsigned int ui16PermissionTicketLength, unsigned char *pucRevocationTicket, unsigned int *pui16RevocationTicketLength );

Argument pucServerName

Description Specify NULL for stand-alone revocation. In case of network license revocation, specify the license server name in this parameter (or alternatively set using the VLSsetServer API or the LSFORCEHOST environment variable) In case of stand-alone license revocation, a separate call VLSsetServer("no-net") is required.

puc

Specify NULL.

puermissionTicket

An IN parameter. A pointer to the permission ticket.

ui16PermissionTicketLength

An IN parameter. The length of the permission ticket.

pucRevocationTicket

An OUT parameter. A pointer to the license revocation ticket out buffer. The memory needs to be allocated and freed by the caller. The buffer allocated should be at least 1024 bytes long. When NULL is ed, the buffer length is returned.

pui16RevocationTicketLength

An IN/OUT parameter. The size of the buffer allocated for pucRevocationTicket, as input, and a pointer to the size of the license revocation ticket, as output.

This function verifies the permission ticket (PT), acts on it, and returns the revocation ticket (RT) for stand-alone and network licenses. The permission ticket is an approval from you (the developer) to perform a series of license revocation and addition operations that need to be performed on the customer-end. Whereas, the revocation ticket (also known as the rehost ticket) proves that actions requested in the permission ticket were performed. Refer to Chapter - "License Revocation" in the Sentinel RMS SDK Developer's Guide for more details about these .

158

Chapter 1: Sentinel RMS Licensing Library API

The VLSrevokeByPermissionTicketAPI does the following activities before generating a license revocation ticket: n

n

n

Validates the locking information received against the license server's\system's lock information. Validates the number of tokens specified in the permission ticket against the total number of tokens in the license. Checks if enough resources are available, like in the license storage, to carry out all requested operations.

If the pucRevocationTicket argument is ed as NULL, the function does the following: n

n

Checks whether all requests in the ticket can be carried out. For example, whether there are enough resources to store revocation information into the persistence data and, if new licenses are defined, whether there is enough space to add the new licenses into the license database. Returns the size of the revocation ticket, that would be generated, in the pui16RevocationTicketLength argument.

A license with infinite tokens will be revoked completely only if no token is in use currently. The license will become unusable after revocation.

1.81.2. Returns The status code LS_SUCCESS is returned if licenses revoked successfully. Otherwise, it will return the following error codes: Error Codes

VLS_REHOST_BUFFER_TOO_SMALL

Description Allocated memory is not enough.

VLS_REHOST_PARAMETERS_ERROR

Invalid rehost parameters.

VLS_REHOST_INVALID_DATA_FORMAT

Permission ticket is invalid; either corrupt or not in TLV format.

VLS_REHOST_UNED_OPERATION_TYPE

Operation type is not 'A', 'R', or 'P'.

VLS_REHOST_ALLOCATE_MEMORY_FAIL- Failure in memory allocation. URE VLS_REHOST_DIFFERENT_LOCK_INFO

Lock code mismatch.

VLS_REHOST_LICENSE_IN_USE

License to be revoked is in use; can not be revoked.

VLS_REHOST_HAVE_BEEN_REVOKED_ BEFORE

License has already been revoked; can not be revoked again.

VLS_REHOST_CANCELED_BY_

Revoke option was canceled by the .

VLS_REHOST_LICENSE_EXIST

The license already exists.

VLS_REHOST_REVOKE_OVER_TOTAL

When the revocation request exceeds the available limit.

1.81. VLSrevokeByPermissionTicket

Error Codes

VLS_REHOST_TAG_NOT_FOUND

Description A tag not found in the TLV.

VLS_REHOST_INVALID_REQUEST_DATA

The requested data is invalid.

VLS_INVALID_LICENSE

The given license code/permission ticket is invalid. Hence, revocation by permission ticket is not allowed.

VLS_REVOKE_LIC_DATA_INCONSISTENT The license persistence data is either corrupt or does not exist. VLS_TOO_MANY_OPERATIONS_IN_SIN- The permission ticket size is more than the ed GLE_PT length. Decrease the number of operations from PT. VLS_PT_ALREADY_EXECUTED_FOR_ THIS_OPERATION

The permission ticket operation already executed on the license server.

VLS_PT_VENDOR_ID_MISMATCH

Vendor ID mismatch. The permission ticket cannot be used for revoking licenses of other vendors.

VLS_REVOKE_EXPIRED_LIC_FOUND

An expired license can neither be added nor revoked.

159

160

Chapter 1: Sentinel RMS Licensing Library API

1.82. VLSrevokeLicense Client √

Server

Static Library √

DLL √

Revokes network licenses based on the pre 8.4.1 network revocation workflow.

1.82.1. Syntax LS_STATUS_CODE

VLSrevokeLicense(

unsigned char

*server_name,

unsigned char

*feature_name,

unsigned char

*feature_version,

unsigned long

capacity,

unsigned char

*,

int

*units_to_revoke,

unsigned long

*capacity_to_revoke,

unsigned char

*rvk_ticket,

int

*length_of_rvk_ticket,

unsigned char

*log_comment,

unsigned long

*reserved1,

unsigned char

*reserved2 );

Argument server_name

Description A pointer to the name of the license server where the license to be revoked is currently deployed. An error will be returned if an invalid name or a null value is provided.

feature_name

A pointer to the feature name of the license to be revoked.

feature_version

A pointer to the feature version of the license to be revoked.

capacity

Not ed.



A pointer to the used for authenticating the client.

units_to_revoke

A pointer to the number of tokens to be revoked. VLS_INFINITE_KEYS to revoke all the tokens. An error will be returned by the API if the requested value exceeds the number of licenses available. The number of licenses available for revocation are returned in this parameter.

capacity_to_revoke

A pointer to the capacity units to be revoked. However, revocation of a capacity license is not ed in this release of Sentinel RMS Development Kit. Make the value of this parameter as 0 or NULL.

rvk_ticket

A pointer to the license revocation ticket out buffer. The memory needs to be allocated and freed by the programmer. The buffer allocated should be at least 1024 bytes long.

length_of_rvk_ticket

A pointer to the size of the license revocation ticket.

log_comment

A string that is written by the license manager to the comment field of

1.82. VLSrevokeLicense

Argument

Description the usage log file.

reserved1

Reserved for future use. You need to null in order to use this function currently.

reserved2

Reserved for future use. You need to null in order to use this function currently.

161

1.82.2. Description This function is used for revoking the hard limit or the number of tokens for a network license based on the pre 8.4.1 network revocation workflow (refer to the Appendix - "Network License Revocation Prior to the 8.4.1 Release" of the Sentinel RMS SDK Developer's Guide). When successful, it returns the license revocation ticket (LRT), which can be decoded using the -lrt option of the lsdecode utility or the VLScgDecodeLicenseRevocationTicket and VLScgDecodeLicenseRevocationTicketExt APIs. The license revocation ticket is encoded using the secret specified at the time of license creation. The same secret is to be provided for decoding the ticket (using the -secret option in lsdecode). License with infinite tokens will be revoked completely with the condition that no token should be in use currently. The license will become unusable after revocation.

1.82.3. Returns The status code LS_SUCCESS is returned if licenses revoked successfully. Otherwise, it will return the following error codes: Error Codes

VLS_REVOKE_ERR_NO_FEATURE

Description License with the given feature/version does not exist on the license server.

VLS_REVOKE_ERR_CORRUPT_MESSAGE

The message received by the license server was corrupted.

VLS_REVOKE_ERR_OUT_VALID_RANGE

The revocation request was beyond the range.

VLS_REVOKE_ERR_MD5_PLUGIN_LOAD_ FAIL

An error was encountered while loading the MD5 plug-in DLL at the license server.

VLS_REVOKE_ERR_MD5_PLUGIN_EXEC_ FAIL

An error was encountered in executing the authentication plug-in.

VLS_REVOKE_ERR_INSUFFICIENT_FEATURE_LICENSES

The feature has less number of total licenses.

VLS_REVOKE_ERR_INSUFFICIENT_ DEFAULT_GROUP

The default group does not have sufficient licenses. You can reconfigure your reservation file.

VLS_REVOKE_ERR_INSUFFICIENT_FREE_IN_ Currently the required number of licenses are not DEFAULT free for revocation in the default group.

162

Chapter 1: Sentinel RMS Licensing Library API

Error Codes

VLS_REVOKE_ERR_INVALID_SESSION_ID

Description An invalid session ID was sent by the client in packet.

VLS_REVOKE_ERR_INVALID_

The supplied for revocation was invalid.

VLS_REVOKE_ERR_INTERNAL_SERVER

Revocation Failed! - Internal Server Error.

VLS_REVOKE_ERR_INFINITE_GRP_DIST

It is not possible to revoke infinite licenses with group distribution enabled.

VLS_REVOKE_ERR_INFINITE_LIC_IN_USE

All licenses must be free for infinite revocation.

VLS_REVOKE_ERR_INFINITE_LIC_FINITE_ REQ

The license has infinite keys. Only infinite revocation request allowed.

VLS_REVOKE_ERR_TICKET_GENERATION

Failed to generate the revocation ticket.

VLS_REVOKE_ERR_CODGEN_VERSION_ UNED

License revocation is not ed on the older versions of the License Code Generator.

VLS_REVOKE_ERR_RDNT_LIC_UNSUPPORED

License revocation is not ed for redundant licenses.

VLS_REVOKE_ERR_CAPACITY_LIC_UNSUPPORED

License revocation is not ed for capacity licenses.

VLS_REVOKE_ERR_UNEXPECTED_AUTH_ CHLG_PKT

Unexpected error! The challenge packet was received from the license server.

VLS_REVOKE_ERR_TRIAL_LIC_UNSUPPORED

License revocation is not ed for trial licenses.

Error Handling

163

Error Handling This section describes the error-handling functions. The Sentinel RMS client library has a built-in error handler for each type of error listed. An error handler is a simple function that tries to correct whatever situation caused the error condition to occur. In most cases, the conditions are difficult to correct, and the handlers perform some clean-up tasks and display error messages. If an error occurs while processing a function call and the default error handlers are unable to correct the situation, the API functions return an error code after displaying an appropriate error message. If the built-in error handlers are able to correct the error-causing condition, the function call returns the success code, LS_SUCCESS, as if the error never occurred Given below is the list of the API functions:

Function

Description

VLSerrorHandle

Toggles default error handling ON or OFF.

LSGetMessage

Prints licensing library-defined error messages corresponding to specified error code.

VLSsetErrorHandler s custom error handlers. VLSsetErrorFile Configures the display of error messages.

164

Chapter 1: Sentinel RMS Licensing Library API

1.83. VLSerrorHandle Client √

Server

Static Library √

DLL √

Turns default error handling on or off.

1.83.1. Syntax LS_STATUS_CODE VLSerrorHandle ( int flag );

Argument flag

Description To turn on error handling, use VLS_ON. To turn off error handling, use VLS_OFF. Default: VLS_ON.

1.83.2. Description If the value of flag is the constant, VLS_ON, error handling is enabled. If flag is VLS_OFF, error handling is disabled. If called with VLS_OFF and LSGetMessage is used, the feature name and version are hidden. When error handlers are not being used, the client function call returns the status code of the latest error condition. The caller of the function should therefore check the value returned by the function before proceeding.

IMPORTANT If you choose to disable error handling in your licensing implementation, it is recommended that you call the VLSerrorHandle API before calling VLSinitialize.

1.83.3. Returns For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.84. LSGetMessage

165

1.84. LSGetMessage Client √

Server

Static Library √

DLL √

Prints error messages corresponding to specified error code.

1.84.1. Syntax LS_STATUS_CODE LSGetMessage ( LS_HANDLE LS_STATUS_CODE

Argument

lshandle, Value,

unsigned char

*buffer,

unsigned long

bufferSize );

lshandle

Description Handle returned by LSRequest or VLSrequestExt.

value

Error code.

buffer (out)

Buffer to store message. When the handle provided is invalid, the buffer parameter returned contains the error code. However, it will show the feature name as UNKNOWN.

bufferSize

Size of the buffer.

1.84.2. Description  Returns in the buffer a text description of the error condition indicated by error code value, for the feature associated with lshandle. The buffer must be allocated by the calling function with its size indicated by bufferSize.

1.84.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NO_MSG_TEXT

Description n n

buffer is NULL bufferSize is zero or negative.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

166

Chapter 1: Sentinel RMS Licensing Library API

1.85. VLSsetErrorHandler Client √

Server

Static Library √

DLL √

Enables registration of custom error handlers.

1.85.1. Syntax LS_STATUS_CODE VLSsetErrorHandler ( LS_STATUS_CODE (*myErrorHandler) (LS_STATUS_CODE, char*), LS_STATUS_CODE LSErrorType );

1.85.2. Description In some situations, the default responses may not be suitable. Therefore, Sentinel RMS allows custom error handling routines to replace the default routines. Customized routines should perform actions that are functionally similar to the defaults. myErrorHandler must point to the error handling function and adhere to the prototype outlined below. LSErrorType must indicate the type of the error to be handled. The Sentinel RMS Development Kit default routines continue to handle other errors. The customized function should accept as input the error code of the condition that caused it to be called and the name of the feature. The same error-handling function can be used to handle all error conditions for all features of an application, using internal conditional statements. The special target error code, VLS_EH_SET_ALL, can be used to set up the provided error handler to handle all errors. Customized error handlers must adhere to the following prototype: LS_STATUS_CODE

myErrorHandler,

LS_STATUS_CODE

errorCode,

char

Argument

*featureName;

errorCode

Description The error code to be handled.

featureName

The name of the feature involved in the error.

1.85.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n myErrorHandler parameter is NULL n LSErrorType is an invalid error type.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

1.86. VLSsetErrorFile

167

1.86. VLSsetErrorFile Client √

Server

Static Library √

DLL √

Configures the manner in which error messages are displayed.

1.86.1. Syntax typedef enum { VLS_NULL, VLS_STDOUT, VLS_STDERR } VLS_ERR_FILE; LS_STATUS_CODE

VLSsetErrorFile(

VLS_ERR_FILE msgFile, char LSFAP *filePath );

1.86.2.  Description This function configures the displaying of error messages to the through the default error handlers. If you disable the default error handlers, you do not need to use this function. The default handling of error messages is as follows: Windows Pop up a Message Box. Unix Write to stderr. You can alter this behavior by providing a file path, while keeping the other parameter (msgFile) VLS_ NULL. If you provide both parameters, preference will be given to the msgFile.

1.86.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLS_CALLING_ERROR

Could not open msgFile.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

168

Chapter 1: Sentinel RMS Licensing Library API

The Trace Licensing Operations The tracing calls are placed in the RMS client library to help diagnose the situations, like errors and failures. You can enable tracing of the internal operations, such as function calls, errors, and invalid licenses, to log the flow of activities performed. By default, the tracing operation is disabled for the licensing library.

Given below is the list of the API functions:

Function

Description

VLSsetTraceLevel

Sets the location for storing the tracing output.

VLSsetTraceFile Sets the tracing level. VLSsetTraceHandler Allows defining custom trace handler function.

1.87. VLSsetTraceLevel

1.87. VLSsetTraceLevel Client √

Server

Static Library √

DLL √

Sets the tracing level.

1.87.1. Description This function sets the following trace levels:

1.87.2. Syntax LS_STATUS_CODE VLSsetTraceLevel ( int

Argument traceLevel

traceLevel );

Description The default value of traceLevel is VLS_NO_TRACE. Other valid values are: n n n n

VLS_TRACE_KEYS VLS_TRACE_FUNCTIONS VSL_TRACE_ERRORS VLS_TRACE_ALL

1.87.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description Could not open msgFile.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

169

170

Chapter 1: Sentinel RMS Licensing Library API

1.88. VLSsetTraceFile Client √

Server

Static Library √

DLL √

 Sets the location of the trace file.

1.88.1. Syntax LS_STATUS_CODE VLSsetTraceFile ( VLS_ERR_FILE msgFile, char *filePath );

Argument msgFile

Description An IN parameter. Refers to the standard file where trace messages are stored as output. It is defined as data type VLS_TRACE_FILE, with the following possible values: n n n

filePath

VLS_NULL VLS_STDERR VLS_STDOUT

The path of the file, including the filename, where trace log is to be maintained. If msgFile is set to VLS_STDERR or VLS_STDOUT, this path will be ignored.

1.88.2. Description  This function is used to configure a file that stores trace and error logs. After this file is configured, all the trace and error logs are stored in this file. At least, value for one of the arguments is to be ed. In case, if value for only one of the argument is ed, the other should be ed as VLS_NULL. However, if values for both the arguments are ed, then preference is given to the msgFile parameter. If both the arguments are ed as VLS_NULL, no file is set for trace and error handling. In this case, the default file, STDERR, is used for output. This is applicable as general feature. One ed, a file can be uned by calling VLSsetTraceFile with VLS_NULL as argument.

1.88.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description The argument specified is not correct, that is, either the file specified in the filePath argument is not valid or the value for msgFile argument ed is not as specified in the argument description.

VLS_RESOURCE_LOCK_FAILURE Failed to obtain the API resource lock. On receiving this error, please retry calling this API function.

1.88. VLSsetTraceFile

For a complete list of the error codes, see Licensing Library Error and Result Codes.

171

172

Chapter 1: Sentinel RMS Licensing Library API

1.89. VLSsetTraceHandler Client √

Server

Static Library √

DLL √

s a handler to which the trace messages that are generated at run-time are sent.

1.89.1. Syntax LS_STATUS_CODE VLSsetTraceHandler ( LS_STATUS_CODE (*myTraceHandler)( int traceLevel, char *buffer, int bufferSize));

Argument myTraceHandler

Description A pointer to the trace handling function.

1.89.2. Description This API is used to a handler to which the trace messages that are generated at run-time are sent. The myTraceHandler argument must point to the trace handling function, which must be defined by the caller, and adhere to the prototype given below: LS_STATUS_CODE myTraceHandler ( int traceLevel, char *buffer, int bufferSize );

 In the above prototype: n

n

n

n

traceLevel is the current level for tracing. The default value is VLS_NO_TRACE. buffer is to store the formatted trace messages. The trace messages ed depend on the the level set. bufferSize is to store the size of the buffer argument ed. If a handler is already ed and a new handler is ed as myTraceHandler argument, the API un-s the existing handler and s the new one. Also, once ed, a handler cannot be uned without rebuilding the application.

1.89.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description The argument specified is not correct, that is, myTraceHandler is NULL.

VLS_RESOURCE_LOCK_FAILURE Failed to obtain the API resource lock. On receiving this error,

1.89. VLSsetTraceHandler

Error Code

Description please retry calling this API function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

173

2 Chapter 2: Commuter License API Commuter licenses allow temporary check out of a license token to use a protected application from a Sentinel RMS license server to a portable computer. The most common use of this feature is to allow use of a protected application on a laptop computer that will be disconnected from the network. Given below is the list of the API functions: Function VLScommuterInfo

Description Commuter information structure

VLSgetCommuterInfo

Returns the commuter license information.

VLSgetAndInstallCommuterCode Obtains the commuter code from the license server and issues the commuter authorization to the client side persistence database VLSuninstallAndReturn CommuterCode

Removes the commuter authorization from the client side persistence database and returns the token to the license server.

VLScleanExpiredCommuterCode Cleans the expired commuter authorization on a client. VLSgetMachineIDString

Obtains commuter locking code from a remote computer.

VLSgetCommuterCode

Checks out a commuter authorization for a remote computer.

VLSinstallCommuterCode

Install a commuter authorization on a remote computer.

176

Chapter 2: Commuter License API

2.1. VLScommuterInfo 2.1.1. Syntax { int commuter_code_version; int codegen_version; char feature_name[VLS_MAXFEALEN]; char feature_version[VLS_MAXVERLEN]; int birth_day; int birth_month; int birth_year; int death_day; int death_month; int death_year; int num_of_licenses; int locking_crit; char lock_info[VLS_MAXCLLOCKLEN]; char vendor_info[VLS_VENINFOLEN + 1]; char issuing_server[MAX_NAME_LEN]; long key_life_time; int protocol_type; int status; }VLScommuterInfo;

Argument

Description commuter_code_version Version of commuter code codegen_version

Version of the code generator used

feature_name

Name of the feature

feature_version

Version of the feature

birth_day

Start day (1-31)

birth_month

Start month (1-12)

birth_year

Start year

death_day

End day (1-31)

death_month

End month (1-12)

death_year

End year

num_of_licenses

Number of licenses

locking_crit

Locking criteria of the client

lock_info

Locking information of the client

vendor_info

The vendor-defined information string. Maximum length of this string can be 2000 characters.

2.1. VLScommuterInfo

Argument issuing_server

Description License checked out from <servername>

key_life_time

The license lifetime for this feature (in seconds).

protocol_type

Type of protocol used

status

n n

1 - Active 0 - Inactive

177

178

Chapter 2: Commuter License API

2.2. VLSgetCommuterInfo 2.2.1. Syntax int VLSgetCommuterInfo ( unsigned char

*feature_name,

unsigned char

*version,

int VLScommuterInfo

Argument

index, *commuter_info );

feature_name

Description Name of the feature.

version

Version of the feature.

index

Used to specify a particular client. The index must be greater than 0. When the index crosses the maximum number of commuter features available, the error VLS_NO_MORE_COMMUTER_CODE will be returned.

commuter_info

The structure, which returns the information about the checked-out license. Space must be allocated by the caller.

2.2.2. Description VLSgetCommuterInfo() returns LS_SUCCESS when the locally checked-out commuter token is available on the system whereas the function returns VLS_REMOTE_CHECKOUT, when the remotely checkedout commuter token is available on the system. The return code "VLS_REMOTE_CHECKOUT" from this API should NOT be treated as an error condition, even though its value is non-zero. This particular value is returned by the API, when a remote-checked out commuter token is available on the standalone server.

VLSgetCommuterInfo can be used two ways: n

n

Specify feature_name and version as non-NULL and the call will return information about this feature. The call will ignore the index argument. Specify feature_name and version as NULL and use the index field in a loop. This will return information about all feature-version checked-out licenses from no-net.

VLSgetCommuterInfo should be called until it returns VLS_NO_MORE_FEATURES by incrementing the index every time.

2.2.3. Returns The status code VLScg_SUCCESS is returned if successful. For a complete list of the error codes, see Licensing Library Error and Result Codes.

2.3. VLSgetAndInstallCommuterCode

179

2.3. VLSgetAndInstallCommuterCode 2.3.1. Syntax int VLSgetAndInstallCommuterCode ( unsigned char *feature_name, unsigned char *feature_version, long *units_reqd, int *duration, int *lock_mask, unsigned char *log_comment, LS_CHALLENGE *challenge );

Argument feature_name

Description Name of the feature.

feature_version

Version of the feature.

units_reqd

Number of units required to run the license. The license system verifies that the requested number of units exist and may reserve those units.The number of units available is returned. If the number of licenses available with the license server is less than the requested number, the number of available licenses will be returned using unitsReqd. If unitsReqd is NULL, VLS_CALLING_ERROR will be returned.

duration

Displays the number of days for which the license has to be checked out. Specify zero (0) for unlimited check-out. If the remaining number of days available is less than the requested days, then the duration parameter will be ignored and the license server will issue the commuter authorization for the remaining number of days. The license server will never issue the commuter authorization beyond the birth and death date of the license. The start date of the commuter authorization is based on the client system’s time and not that of the license server.

lock_mask

Mask defining which fields are to be used for locking. On entry, lock_mask specifies the locking-criteria that should be used for looking the commuter-code. If a zero is given, the API will lock the code to Disk ID (windows), otherwise it will lock to host name. Notice, the API will replace the zero with lock_mask for Disk ID or host name before sending this value to the license server.

log_comment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired.

challenge

The challenge-response for this operation. Pointer to a challenge structure. The challenge-response will also be returned in this structure.

180

Chapter 2: Commuter License API

2.3.2. Description Obtains the commuter code from the license server and installs the stand-alone commuter authorization at the client. Before calling VLSgetAndInstallCommuterCode, the VLSgetMachineID function must be called in order to obtain the ed lock masks, which are ed in the lock_mask parameter. VLSgetAndInstallCommuterCode can also be used for the explicit check-out of a repository license.

2.3.3. Returns The status code VLS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description n n n

VLS_UNABLE_TO_INSTALL_COMMUTER_CODE

duration is NULL lock_mask is NULL unitsReqd is NULL

Could not install the checked out commuter license code on the target computer.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

2.4. VLSuninstallAndReturnCommuterCode

181

2.4. VLSuninstallAndReturnCommuterCode 2.4.1. Syntax int VLSuninstallAndReturnCommuterCode ( unsigned char

*feature_name,

unsigned char

*feature_version,

unsigned char

*log_comment );

Argument

Description

feature_name

Name of the feature.

feature_version

Version of the feature.

log_comment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired.

2.4.2. Description Uninstalls the commuter authorization from the client and returns the commuter authorization to the license server.

2.4.3. Returns The status code LS_SUCCESS is returned if successful. For a complete list of the error codes, see Licensing Library Error and Result Codes. VLSuninstallAndReturnCommuterCode cannot be used to check in an authorization for a remote to prevent the remote from checking in the authorization while continuing to use it remotely.

182

Chapter 2: Commuter License API

2.5. VLSgetMachineIDString Returns an encrypted string that contains the fingerprint information based on the locking criteria specified in the call. Use this call when you are trying to check out a commuter authorization for a remote computer that does not have access to the license server. The computer that will actually use the commuter authorization runs this call and then es on the string (via e-mail, disk, etc.) to a computer that has access to the license server. The commuter authorization is then checked out and transmitted to a remote , and locked to the information given by this string. If the machine that requires the commuter authorization has network access to the license server, then you do not need to use this method. Instead, check out the license using VLSgetAndInstallCommuterCode.

2.5.1. Syntax LS_STATUS_CODE VLSgetMachineIDString ( unsigned long

*lock_selector,

unsigned char

*machineIDString,

unsigned long

*bufSz );

Argument

Description

lock_selector

Bitmask identifying what criteria you would like to be contained in the Machine ID string. See the lock_selector Values below for information on the values for this bitmask. If you set this argument to NULL, this API call will use the locking selector information it finds on the computer on which it is running.

machineIDString A string that represents the machine’s locking information. This will be ed on to VLSgetCommuterCode on a computer that can actually check out a commuter authorization from the license server. Returns the buffer size of the machineIDString parameter if machineIDString is NULL. Otherwise, specifies the size of the machineIDString parameter.

bufSz

2.5.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for the failure. Possible errors returned include VLS_UNABLE_TO_GET_MACHINE_ID_ STRING. For a complete list of error codes, see Licensing Library Error and Result Codes. If NULL is ed as the locking criteria in the VLSgetMachineIDString call, VLS_CALLING_ERROR is returned.

2.5. VLSgetMachineIDString

183

2.5.3. lock_selector Values The value of lock_selector is a bitmask in which each bit selects a fingerprinting element. It does not describe the fingerprint, but only designates the locking criteria that will be used to compute the fingerprint. The masks which define each locking criterion are listed below: VLS_LOCK_ID_PROM

0x1

VLS_LOCK_IP_ADDR

0x2

VLS_LOCK_DISK_ID

0x4

VLS_LOCK_HOSTNAME

0x8

VLS_LOCK_ETHERNET

0x10

VLS_LOCK_PORTABLE_SERV

0x80

VLS_LOCK_CUSTOM

0x100

VLS_LOCK_U

0x200

VLS_LOCK_CUSTOMEX

0x400

VLS_LOCK_HARD_DISK_SERIAL

0x800

VLS_LOCK_U_INFO

0x1000

VLS_LOCK_UUID

0x2000

VLS_LOCK_ALL

0x1FFF

VLS_LOCK_PORTABLE_SERV refers to the Computer ID key, and that VLS_LOCK_ALL selects all locking criteria.

184

Chapter 2: Commuter License API

2.6. VLSgetCommuterCode Obtains a commuter authorization from the license server to be ed on to a remote client that does not have network access to the license server. This call checks out a commuter authorization for another machine. It requires a commuter locking code string from the VLSgetMachineIDString call used on the remote computer. After successful completion of the call, the authorization code string should be ed on to the remote computer which will use VLSinstallCommuterCode to install the authorization. If the machine that requires the commuter authorization has network access to the license server, then you should not use this call. Instead, check out the license using VLSgetAndInstallCommuterCode. Once a commuter authorization is checked out for a remote computer, it cannot be checked back in until the commuter authorization expires.

2.6.1. Syntax LS_STATUS_CODE VLSgetCommuterCode ( unsigned char

*feature_name,

unsigned char

*feature_version,

unsigned long

*units_rqd,

unsigned long

*duration,

unsigned long

*lock_mask,

unsigned char

*log_comment,

unsigned char

*machineIDString,

unsigned char

*commuter_code,

LS_CHALLENGE

*challenge,

VLSserverInfo

*requestInfo,

VLSserverInfo

*commuterInfo,

unsigned long

*extension_in_duration );

Argument

Description

feature_name

The feature name of the license to check out from the license server.

feature_version

The feature version of the license to check out from the license server.

units_reqd

Number of units required for the license.

duration

Number of days the commuter authorization will last. This value may be superseded by the maximum limit allowed by the license.

lock_mask

The desired locking criteria for the client machine. The value here should be equal to or a subset of the value used by the VLSgetMachineIDString call. This value will return the actual locking criteria used to lock the commuter authorization.

log_comment

A comment which will be placed inside the log file on the license server.

machineIDString

Machine ID string generated by the remote computer desiring the commuter authorization.

commuter_code

The actual commuter authorization code. This string should be ed on to the remote computer desiring the commuter authorization for

2.6. VLSgetCommuterCode

Argument

185

Description installation.

challenge

A challenge and response for the given license on the license server. Set to NULL if you are not using this feature.

requestInfo

Reserved. Use NULL for this value.

commuterInfo

To be used in future for hooks.

extension_in_duration

The additional number of days to extend the duration of an existing remotely checked out commuter license (can be termed as "commuting a remote extension token"). However, this as NULL under the following scenarios: n

n

If you are checking out a remote commuter license for first time for a feature. If the checked out remote commuter license is lost.

Similarly, when an extension token is being commuted, non-applicable parameters (like, units required, duration, and so on) will be ignored.

2.6.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for the failure. Possible error codes that can be returned by this call include VLS_ INVALID_MACHINEID_STRING. For a complete list of error codes, see Licensing Library Error and Result Codes.

186

Chapter 2: Commuter License API

2.7. VLScleanExpiredCommuterCode 2.7.1. Syntax int VLScleanExpiredCommuterCode ( unsigned char

*feature_name,

unsigned char

*feature_version,

unsigned char

*log_comment

unsigned long

*unused );

Argument

Description

feature_name

Name of the feature.

feature_version

Version of the feature.

log_comment

Unused

unused

This parameter is reserved for future use.

2.7.2. Description  Cleans the expired commuter authorization on a client system (both remote and normal).

2.7.3. Returns The status code LS_SUCCESS is returned if successful. For a complete list of the error codes, see Licensing Library Error and Result CodesLicensing Library Error and Result Codes.

2.8. VLSinstallCommuterCode

187

2.8. VLSinstallCommuterCode Installs a commuter authorization onto a remote computer. A computer that has network access to the license server should generate the commuter authorization using VLSgetCommuterCode (see ). The commuter authorization is then ed on to the computer requiring the authorization and installed using VLSinstallCommuterCode. After successful completion of this call, the remote computer should be able to use the commuter authorization. If the machine that requires the commuter authorization has network access to the license server, then you do not need to use this call. Instead, check out the commuter authorization using VLSgetAndInstallCommuterCode. Once a commuter authorization is checked out for a remote computer, it cannot be checked back in—it simply expires.

2.8.1. Syntax LS_STATUS_CODE VLSinstallCommuterCode ( unsigned char *commuter_code, unsigned char *reserved1, unsigned long *reserved2 );

Argument

Description

commuter_code

The commuter authorization that was generated by a computer with network access to the license server.

reserved1

Reserved. Use NULL for this value.

reserved2

Reserved. Use NULL for this value.

2.8.2. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for the failure. Possible errors that can be returned by this call include VLS_UNABLE_ TO_INSTALL_COMMUTER_CODE. For a complete list of error codes, see Licensing Library Error and Result Codes.

3 Chapter 3: Redundancy API The license server redundancy allows the total number of licenses to remain available to the enterprise even if one or more license servers fail. If a license server fails, the license tokens it is serving will be taken over by the next-available license server. For information on setting up and using redundant license servers, please see the Sentinel RMS SDK Developer’s Guide and the Sentinel RMS SDK System ’s Guide. The following API function have been deprecated since the 8.1.x release, VLSaddFeatureExt, VLSaddFeatureToFileExt, VLSchangeDistbCrit, and VLSsetBorrowingStatus. These functions do not perform any operation and return the VLS_NOT_ED error code.

Given below is the list of the API functions: Function VLSaddFeature

Description Dynamically adds licensing information about a feature into the license server’s internal tables. If licensing information for this feature and version already exists in the license server’s tables, it may be overwritten with the new information. Feature is not permanently added to the license server, but only until the license server is shut down and restarted.

VLSaddFeatureToFile

Dynamically adds licensing information to the license server’s internal tables and normal or redundant license file.

VLSaddServerToPool

Sends a request to add a new license server into the pool. This API will actually modify the license redundant file in order to add the given license server to the pool.

VLSdelServerFromPool

Removes a license server’s name from the pool. This API will actually modify the license redundant file in order to delete the given license server from the pool.

VLSdiscoverExt

Returns the license server characteristic information, which has the keys for a particular specified feature and version. The client can decide a license server preference based on some criteria.

VLSgetDistbCrit

Returns the current token distribution status for the given license feature and version.

190

Chapter 3: Redundancy API

Function VLSgetDistbCritToFile

Description Requests the license server provide current token distribution status for the given license feature and version or for all features or versions (wild card characters are acceptable). Writes the distribution to a file.

VLSgetLeaderServerName

Returns the current leader license server’s name by ing any license server. So a license server’s name must be set before a call is made to this function.

VLSgetLicSharingServerList

Returns the names of the license servers which are sharing tokens for a given feature name and version. The server_ name_list will contain license server names (hostNames or IP addresses).

VLSgetPoolServerList

Returns a list of redundant license servers and their status.

VLSsetServerLogState

Turns logging on/off for the given event.

3.1. VLSaddFeature

191

3.1. VLSaddFeature 3.1.1. Syntax int VLSaddFeature ( unsigned char

*licenseStr,

unsigned char

*unused1,

LS_CHALLENGE

Argument

*unused2 );

licenseStr

Description The license string that will be added.

unused1

Should be NULL.

unused2

Should be NULL.

3.1.2. Description Dynamically adds licensing information about a feature into the license server and adds the license code to the license server’s internal tables. If licensing information for this feature and version already exists in the license server’s tables, it may be overwritten with the new information contained in licenseStr. A feature is not permanently added to the license server, but is cleared when the license server is shut down and restarted.

3.1.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

LS_NO_SUCCESS

licenseString is NULL

VLS_ADD_LIC_FAILED

Generic error indicating the feature has not been added.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

License server has not been set and is unable to determine which license server to use.

192

Chapter 3: Redundancy API

Error Code VLS_BAD_SERVER_ MESSAGE

Description Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

3.2. VLSaddFeatureToFile

3.2. VLSaddFeatureToFile 3.2.1. Syntax int VLSaddFeatureToFile ( unsigned char

*licenseString,

unsigned char

*unused1,

unsigned char

*unused2,

unsigned char

*unused3 );

Argument licenseString

Description The license_string character.

unused1

Should be NULL.

unused2

Should be NULL.

unused3

Should be NULL.

3.2.2. Description Writes a license dynamically to either the redundant license file or normal license file. The feature is permanently added to the license server when the license server is shutdown and restarted.

3.2.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library.

LS_NO_SUCCESS

licenseString is NULL

VLS_ADD_LIC_FAILED

Generic error indicating the feature has not been added.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_NO_SERVER_FILE

License server has not been set and is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

193

194

Chapter 3: Redundancy API

Error Code LS_NO_NETWORK

Description Generic error indicating that the network is unavailable in servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

3.3. VLSaddServerToPool

195

3.3. VLSaddServerToPool 3.3.1. Syntax int VLSaddServerToPool (

Argument

char

*server_name,

char

*server_addr );

server_name

Description Name of the license server to add to the pool.

server_addr

IP address of the license server.

3.3.2. Description Will send a request to add a new license server into the pool. This API will actually modify the license server redundant license file in order to add the given license server to the pool.

3.3.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description n server_name is NULL n server_address is NULL n Using stand-alone library. This function cannot be used with stand-alone library.

LS_NO_SUCCESS

Generic error indicating that the license server could not be added to the pool.

VLS_NON_REDUNDANT_SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_SERVER_ALREADY_ PRESENT

Attempted to add a license server that is already in the pool.

VLS_POOL_FULL

Pool already has maximum number of license servers. No more license servers can be added.

VLS_BAD_HOSTNAME

hostName is not valid.

VLS_NOT_AUTHORIZED

Invalid .

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_CONF_FILE_ERROR

Error in configuration file.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

196

Chapter 3: Redundancy API

Error Code VLS_BAD_SERVER_MESSAGE

Description Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

3.4. VLSdelServerFromPool

197

3.4. VLSdelServerFromPool 3.4.1. Syntax int VLSdelServerFromPool (

Argument

char

*server_name,

char

*server_addr );

server_name

Description Name of the license server to delete from the pool.

server_addr

IP address of license server.

3.4.2. Description Removes a license server’s name from the pool of redundant license servers. This API modifies the redundant license file in order to delete the given license server from the pool.

3.4.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n server_name is NULL n server_address is NULL n Using stand-alone library. This function cannot be used with stand-alone library.

LS_NO_SUCCESS

Generic error indicating that the license server could not be deleted from the pool.

VLS_NON_REDUNDANT_ SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_SERVER_NOT_PRESENT

Attempted to delete a license server that is not in the pool.

VLS_ONLY_SERVER

Cannot remove the last license server from the pool.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_BAD_HOSTNAME

hostName is not valid.

VLS_NOT_AUTHORIZED

Invalid .

VLS_CONF_FILE_ERROR

Error in configuration file.

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization in process. VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

198

Chapter 3: Redundancy API

Error Code

LS_NO_NETWORK LS_NORESOURCES

Description Generic error indicating that the network is unavailable for servicing license operation. An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

3.5. VLSdiscoverExt

199

3.5. VLSdiscoverExt 3.5.1. Syntax int VLSdiscoverExt ( unsigned char

*feature name,

unsigned char

*version,

unsigned char int VLSdiscoverInfo

*num_servers, *discoverInfo,

int

option_Flag,

int

sharing_crit,

char

Argument

*unused1,

*vendor_list );

feature_name

Description Name of the feature.

version

Version of the feature. Must be unique.

unused1

Should be NULL.

num_servers

Number of license servers for which discoverInfo array is allocated.

discoverInfo

The core function that receives the broadcast message, splits and puts the license server’s name in array format. VLSdiscoverInfo struct that will contain requested information.

option_Flag

The option flag is allowed to be logically ORed with other flags. However, this flag will have first priority. Valid flags are: n

n

n

n

n

VLS_DISC_NO_LIST – Do not check the host list specified by the . By default, it first consults the LSFORCEHOST environment variable. If LSFORCEHOST does not exist, it reads the file LSHOST/lshost. VLS_DISC_RET_ON_FIRST – If the combined query list is NULL, it returns the name of the first ed license server in the server_ list, as soon as it is ed by any of the license servers. Otherwise, it returns the name of the first ed license server specified in the combined query list. If this option is not specified. VLSdiscover returns all the license servers that responded. VLS_DISC_PRIORITIZER_LIST – Treat the combined query list as a prioritized one, left most being the highest priority host. It returns in server_list, license servers sorted in the order of priority host. If this option is not specified, the combined query list is treated as random. VLS_DISC_REDUNDANT_ONLY – Expecting reply only from redundant license servers. All non-redundant license servers will ignore the message. VLS_DISC_DEFAULT_OPTIONS – This flag is a combination of the aforementioned flags. Use it if you are not sure which flag you want

200

Chapter 3: Redundancy API

Argument

Description to specify.

sharing_crit

The license server will match client’s internal information with the keys it is already granted. Values are: n n n n n

vendor_list

VLScg_NO_SHARING VLScg__SHARING VLScg_HOSTNAME_SHARING VLScg_XDISPLAY_SHARING VLScg_VENDOR_SHARING

Consists of server names. These license serves will be ed. The names of all the license servers that have licenses for specified feature_ name and version will be returned in vendor_list in the same order as in the original (before the call) vendor_list.

3.5.2. Description Returns the license server characteristic information of the license server which has the license tokens for a specified feature and version. The client can specify a license server preference based on some criteria. Each license server that is ed will determine if it has a license that matches the requested feature name and version. If found, the license server will then notify the client with the following information: n

Protocol ed

n

Total number of clients connected to the license server

n

Server IP address

n

Number of units/tokens available

n

Whether this client has already been granted a license for the feature and version (based on sharing_crit)

3.5.3. Returns The status code LS_SUCCESS is returned if stand-alone library is used. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description num_servers is less than or equal to zero.

VLS_NO_RESPONSE_TO_ BROAD- License servers have not responded. CAST LS_NO_SUCCESS

Generic error indicating the license server’s characteristic information could not be retrieved.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

LS_BAD_PARAMETER

License server’s name is NULL or an empty string.

3.5. VLSdiscoverExt

Error Code

LS_SERVER_DOES_NOT_ EXIST

Description Named license server does not exist.

LS_LEADER_NOT_KNOWN

Leader name is not known.

LS_NON_REDUNDANT_ SERVER_ ED

The license server ed is non-redundant, and does not this function.

LS_UNRESOLVED_SERVER_NAME License server’s name is not resolvable. VLS_LEADER_NOT_ PRESENT

Leader name is not known.

VLS_NON_REDUNDANT_ SERVER

The license server ed is non-redundant, and therefore does not this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

201

202

Chapter 3: Redundancy API

3.6. VLSgetDistbCrit 3.6.1. Syntax int VLSgetDistbCrit ( char

*feature_name,

char

*feature_version,

char

*dist_crit,

int

Argument

*distcrit_buflen );

feature_name

Description Name of the feature.

feature_version

Version of the feature. Must be unique.

dist_crit (OUT)

Dist_crit consists of the names of license server, which will have licenses for the given feature_name and version. The dist_crit string must be null-terminated.

distcrit_buflen

Size of memory allocated for dist_crit.

3.6.2. Description Returns the current token distribution status for the given license feature and version.

3.6.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Codes

VLS_CALLING_ERROR

Description n feature_name is NULL n version is NULL n dist_crit is NULL n dist_crit_len is zero or negative n challenge argument is non-NULL, but cannot be understood. n Using stand-alone library. This function cannot be used with stand-alone library. Also, both feature name and version cannot be NULL at the same time.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

LS_BUFFER_TOO_SMALL

dist_crit buffer not large enough to store information.

VLS_NON_REDUNDANT_ SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

3.6. VLSgetDistbCrit

Error Codes

203

VLS_NON_REDUNDANT_ FEATURE

Description Feature is non-redundant and thus cannot be used in this redundancy-related operation.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

VLS_VENDORIDMISMATCH

The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has a license. This error occurs only when client is older than version 6.3 else the error returned is VLS_ NO_SUCH_FEATURE.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

204

Chapter 3: Redundancy API

3.7. VLSgetDistbCritToFile 3.7.1. Syntax int

VLSgetDistbCritToFile (

char *feature_name, char *feature_version, char *file_name );

Argument feature_name

Description Name of the feature.

feature_version

Version of the feature.

file_name

License server will write distribution criteria for the specified feature or version to the file.

3.7.2. Description Requests the license server provide current token distribution status for the given license feature and version, or for all features, or for all versions, or for all features and all versions (wild card characters are acceptable).

3.7.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n feature_name is NULL n file_name is NULL. n Using stand-alone library. This function cannot be used with stand-alone library.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_FILE_OPEN_ERROR

An error occurred opening the file.

VLS_NON_REDUNDANT_ SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_NON_REDUNDANT_ FEATURE

Feature is non-redundant and thus cannot be used in this redundancy-related operation.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization process. VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

3.7. VLSgetDistbCritToFile

Error Code

VLS_BAD_SERVER_ MESSAGE

Description Message returned by license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

LS_BAD_PARAMETER

License server’s name is NULL or an empty string.

LS_BUFFER_TOO_SMALL

Buffer provided is too small.

LS_NO_SUCH_FEATURE

feature_version is non-existent.

LS_NON_REDUNDANT_ SERVER_ ED

LSHOST is set to non-redundant license server.

VLS_CALLING_ERROR

License server’s name is NULL or an empty string.

VLS_LEADER_NOT_ PRESENT

Leader name is not known.

VLS_NON_REDUNDANT_ SRVR

Sets LSHOST to non-redundant license server.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

205

206

Chapter 3: Redundancy API

3.8. VLSgetLeaderServerName 3.8.1. Syntax int VLSgetLeaderServerName (

Argument

char

*leader_name,

int

leader_name_len );

leader_name

Description Current lead license server’s IP address. Space to be allocated by the caller.

leader_name_len

Size of leader_name.

3.8.2. Description Returns the IP address of the ed leader server into the buffer specified by the leader_name parameter. The leader server name is returned as a null-terminated string. The license server to be ed is selected by the VLSgetServer call. So, the VLSgetServer function must be called before VLSgetLeaderServerName.

3.8.3. Returns The status code LS_SUCCESS is returned if successful.Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n leader_name is NULL n leadername_len is NULL.

LS_BUFFER_TOO_SMALL

leadername_len is smaller than the license server name that will be returned.

VLS_NON_REDUNDANT_SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_LEADER_NOT_PRESENT

Unknown leader.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_NON_REDUNDANT_ FEATURE

Feature is non-redundant and thus cannot be used in this redundancy-related operation.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

3.8. VLSgetLeaderServerName

Error Code

VLS_BAD_SERVER_MESSAGE

Description Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

LS_UNRESOLVED_IP_ADDRESS

IP address given is not correct.

LS_BAD_PARAMETER

License server’s name is NULL or an empty string.

LS_BUFFER_TOO_SMALL

Buffer provided is too small.

VLS_CALLING_ERROR

License server’s name is NULL or an empty string.

VLS_LEADER_NOT_PRESENT

Leader name is not known.

VLS_NON_REDUNDANT_SRVR

The license server is non-redundant, and therefore does not this operation.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

207

208

Chapter 3: Redundancy API

3.9. VLSgetLicSharingServerList 3.9.1. Syntax int VLSgetLicSharingServerList (

Argument

char

*feature_name,

char

*feature_version,

char

*server_list_len,

int

*server_list,

int

*num_servers );

feature_name

Description Name of the feature.

feature_version

Version of the feature.

server_list

A list that contains the license server’s names (hostNames or IP addresses).

server_list_len

License server will retrieve all the license servers names. If the list is larger than the specified limit, it will be truncated.

num_servers

Identifies the number of license servers.

3.9.2. Description Returns the license server names which are sharing tokens for a given feature name and version. The server_name_list will contain license server names (hostNames or IP addresses).

3.9.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n feature_name is NULL n feature_version is NULL n server_list is NULL n server_list_len is zero. n License server’s name is NULL or an empty string. n Both feature name and version cannot be NULL at the same time.

LS_BUFFER_TOO_SMALL

server_list_len is smaller than license server name that will be returned.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches the requested feature, version and capacity.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

3.9. VLSgetLicSharingServerList

Error Code

VLS_NON_REDUNDANT_ FEATURE

209

Description Feature is non-redundant and thus cannot be used in this redundancy-related operation.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing the license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_BAD_SERVER_MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable in servicing license operation.

LS_UNRESOLVED_HOSTNAME

Host name given is not correct.

LS_BAD_PARAMETER

License server’s name is NULL or an empty string.

VLS_NON_REDUNDANT_SRVR

The license server is non-redundant, and therefore does not this operation.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

210

Chapter 3: Redundancy API

3.10. VLSgetPoolServerList 3.10.1. Syntax int VLSgetPoolServerList ( char int

Argument

*outBuf, outBufSz );

outBuf (OUT)

Description Output buffer.

outBufSz

Output buffer size.

3.10.2. Description Returns a list of license servers and their status where the servers are in the same pool as the ed redundant license server. The status for each license server in the list indicates whether that server is active (running) or not. If a non-redundant license server is ed, the VLS_NON_REDUNDANT_SRVR error code is returned. The license server to be ed is selected by VLSgetServer, so you must set the license server’s name before calling VLSgetPoolServerList.

3.10.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description License server’s name is NULL or an empty string.

LS_BUFFER_TOO_SMALL

The output buffer is too small.

VLS_SERVER_SYNC_IN_PROGRESS

License server synchronization in process.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

LS_NORESOURCES

Insufficient resources (such as memory) as available to complete the request.

VLS_NON_REDUNDANT_SRVR

The license server is non-redundant, and therefore does not this operation.

VLS_ LEADER_NOT_PRESENT

Unknown leader.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

3.11. VLSsetServerLogState

211

3.11. VLSsetServerLogState 3.11.1. Syntax int VLSsetServerLogState (

Argument event

event,

int

state );

Description The event you want to log. Event may be: n n n n n n n

n n n

n

state

int

LOG_SRVR_UP (the license server is running) LOG_LDR_ELECT (a pool leader has been elected) LOG_HRT_BT (license server heartbeat) LOG_BORROW_REQ_RESP (token borrowing request and response) LOG_USG_NOTIFY (follower notifies pool leader of token use) LOG_CHNG_DIST_CRT (token distribution criteria has changed) LOG_DIST_CRT_SYNC (the pool servers are synchronizing distribution criteria) LOG_CFG_FILE (the LSERVRLF file changed) LOG_SRVR_DOWN (license server is down) LOG_MOD_SERVER (addition or deletion of a license server to or from the pool) LOG_ADD_DEL_LIC (redundant license has been added or deleted to or from the pool)

Logging state: VLS_ON or VLS_OFF.

3.11.2. Description Turns logging on or off for the given event. The license server to be ed is selected by VLSgetServer, so you must set the license server’s name before calling VLSgetPoolServerList.

3.11.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description License server’s name is NULL or an empty string.

VLS_DIFF_LIB_VER

Version mismatch between license server API and client API.

VLS_FEATURE_INACTIVE

The given feature is inactive on the specified license server.

VLS_MSG_TO_LEADER

The request has been sent to the leader license server.

VLS_NOT_AUTHORIZED

The making the request is invalid.

VLS_BAD_SERVER_ MESSAGE

A message returned from the license server could not be understood.

212

Chapter 3: Redundancy API

For a complete list of the error codes, see Licensing Library Error and Result Codes.

4 Chapter 4: Volume Transaction Licensing API Using the volume transaction licensing, you can limit and track the number of times a feature is used and implement your own logic of managing these limits, such as how many units a licensed feature will consume, when to generate an alert, how to increment the limit, and so on. For details about the related concepts, see Chapter 12 - Volume Transaction Licensing in the Sentinel RMS SDK Developer’s Guide. Given below is the list of the API functions: Function Description VLSgetConsumeLimit Returns the current limit stored. VLSsetConsumeLimit Increases, decreases, or resets the limit. VLSgetContextData

Returns the current context data stored.

VLSsetContextData

Sets the current context data with the data ed in context_buff.

214

Chapter 4: Volume Transaction Licensing API

4.1. VLSgetConsumeLimit 4.1.1. Syntax LS_STATUS_CODE

VMSWINAPI VLSgetConsumeLimit (

LS_HANDLE CONSUME_LIMIT_TYPE long LS_CHALLENGE

lshandle, consume_type, LSFAR *consume_value, LSFAR *challenge );

Parameter

Direction Data Type

Description

lshandle

IN

LS_HANDLE

The license handle. A valid license handle is returned by the RMS license server when the license request is successful.

consume_type

IN

CONSUME_LIMIT_TYPE

Specifies the type of the limit whose current value is to be obtained. It can be either of the following: n

n

VLS_LIMIT_TYPE_VOLUME – Sets the number of transaction-based limit. VLS_LIMIT_TYPE_DURATION Sets the duration-based limit.

consume_value

OUT

long

A pointer to a allocated memory, which is filled by the API function with the current limit on its return.

challenge

UNUSED

LS_CHALLENGE

Currently unused. Use NULL.

4.1.2. Description  Returns the current limit stored in the volume transaction licensing database for a particular license.

4.1.3. Returns The API returns LS_SUCCESS when the API is successful otherwise it returns the following error codes: Status VLS_CALLING_ERROR

Description n n

When the consume_value is NULL. When the consume_type is neither VLS_LIMIT_ TYPE_VOLUME, nor VLS_LIMIT_TYPE_DURATION.

LS_BADHANDLE

An invalid handle.

VLS_NOT_ED

If the API is called with a handle corresponding to a queued client or a capacity token.

VLS_NO_RECORDS_FOUND

No records for the limit in the database.

VLS_OPERATION_NOT_SUCCESSFUL

The requested operation failed for any other reason.

4.2. VLSsetConsumeLimit

215

4.2. VLSsetConsumeLimit 4.2.1. Syntax LS_STATUS_CODE

VMSWINAPI VLSsetConsumeLimit ( LS_HANDLE

CONSUME_LIMIT_TYPE CONSUME_OPERATION_TYPE long LS_CHALLENGE

lshandle, consume_type, consume_op_type, LSFAR *consume_value, LSFAR *challenge );

Parameter

Direction Data Type

Description

lshandle

IN

LS_HANDLE

The license handle. A valid license handle is returned by the RMS license server when the license request is successful.

consume_type

IN

CONSUME_LIMIT_TYPE Specifies the type of the limit whose current value is to be obtained. It can be either of the following: n

n

consume_op_type

IN

CONSUME_OPERATION_TYPE

VLS_LIMIT_TYPE_VOLUME - Sets the number of transactionbased limit. VLS_LIMIT_TYPE_DURATION Sets the duration-based limit.

Specifies the type of the operation to be performed. It can be either of the following: n

n

VLS_SET - Increments or decrements the current limit by the value specified in the consume_ value. To decrement, specify a negetive value. VLS_RESET - Overwrites the current limit value with the value specified in consume_value.

consume_value

IN/OUT

long

A pointer to a allocated memory filled by the value (limit) to set or reset.

challenge

UNUSED

LS_CHALLENGE

Currently unused. Use NULL.

4.2.2. Description Increases, decreases, or resets the limit in the volume transaction licensing database for a particular license.

216

Chapter 4: Volume Transaction Licensing API

4.2.3. Returns The API returns LS_SUCCESS when the API is successful otherwise it returns the following error codes: Status VLS_CALLING_ERROR

Description n n

n

When the consume_value is NULL When the consume_type is not VLS_LIMIT_TYPE_ VOLUME or VLS_LIMIT_TYPE_DURATION When the consume_op_type is not VLS_SET or VLS_RESET

LS_BADHANDLE

An invalid handle.

VLS_NOT_ED

If the API is called with a handle corresponding to a queued client or a capacity token.

VLS_NEW_RECORD_FOUND

If the limit value has been updated by any other process after the current process has retrieved the limit value. The API function would also return the current limit value in the consume_value parameter.

VLS_OPERATION_NOT_SUCCESSFUL

The requested operation failed for any other reason.

4.3. VLSgetContextData

217

4.3. VLSgetContextData 4.3.1. Syntax LS_STATUS_CODE

VMSWINAPI VLSgetContextData (

LS_HANDLE

lshandle,

unsigned char

LSFAR *context_buff,

unsigned long

buff_len,

LS_CHALLENGE

LSFAR *challenge );

Parameter

Direction

Data Type

Description

lshandle

IN

LS_HANDLE

The license handle. A valid license handle is returned by the license server when the license request is successful.

context_buff

OUT

unsigned char

A pointer to a allocated memory to be filled by the API with the current context data on its return.

buff_len

IN

unsigned long

Contains the length of the allocated buffer.

challenge

UNUSED

LS_CHALLENGE

Currently unused. Use NULL.

4.3.2. Description Returns the current context data stored in the volume transaction licensing database for a particular license.

4.3.3. Returns The API returns LS_SUCCESS when the API is successful otherwise it returns the following error codes: Status VLS_CALLING_ERROR

Description n n

When context_buff is NULL. When buff_len is less than zero or greater than VLS_ MAX_CONTEXT_LEN+1

LS_BADHANDLE

An invalid handle.

VLS_NOT_ED

If the API is called with a handle corresponding to a queued client or a capacity token.

VLS_NO_RECORDS_FOUND

No records for the context in the database.

218

Chapter 4: Volume Transaction Licensing API

4.4. VLSsetContextData 4.4.1. Syntax LS_STATUS_CODE VMSWINAPI VLSsetContextData ( LS_HANDLE

lshandle,

unsigned char

LSFAR *context_buff,

unsigned long

buff_len,

LS_CHALLENGE

LSFAR *challenge );

Parameter

Direction

Data Type

Description

lshandle

IN

LS_HANDLE

The license handle. A valid license handle is returned by the license server when the license request is successful.

context_buff

IN

unsigned char

Contains a pointer to a allocated memory having the context data to be written in the consume database.

buff_len

IN

unsigned long

Contains the length of the allocated buffer.

challenge

UNUSED

LS_CHALLENGE

Currently unused. Use NULL.

4.4.2. Description Sets the current context data with the data ed in context_buff in the volume transaction licensing database for a particular license.

4.4.3. Returns The API returns LS_SUCCESS when the API is successful otherwise it returns the following error codes: Status VLS_CALLING_ERROR

Description n n

LS_BADHANDLE

When context_buff is NULL. When buff_len is less than zero or greater than VLS_MAX_CONTEXT_LEN+1

An invalid handle.

VLS_NOT_ED If the API is called with a handle corresponding to a queued client or a capacity token. VLS_OPERATION_ NOT_SUCCESSFUL

The requested operation failed for any other reasons.

5 Chapter 5: Capacity License API As the name suggests, the capacity license feature defines the capacity of a license. A capacity license is identified by feature name, version and capacity. The license request is granted on the basis of feature name, version and capacity. Capacity licensing in Sentinel RMS Development Kit allows multiple license of same feature, version and different capacity to exist on the same Sentinel RMS license server. For examples of capacity licensing and more information on this feature, see the Sentinel RMS SDK Developer's Guide. Capacity Licensing is available through APIs only and is not ed by the Sentinel RMS Shell.

Given below is the list of the API functions: Function VLSrequestExt2

Description s capacity and non-capacity requests

VLSgetFeatureInfoExt

Tracks the features available on the server

VLSgetCapacityList

Returns the list of all the capacity for particular feature and version.

VLSgetClientInfoExt

Returns the list of all clients running for a particular feature, version, and capacity

VLSdeleteFeatureExt

Deletes a license from the server based on feature, version and capacity

VLSgetCapacityFrom Handle

Returns the team capacity and capacity allocated to a handle

VLSsetTeamId

Redefines team ID functions

VLSsetTeamIdValue

s a customized team ID value

220

Chapter 5: Capacity License API

5.1. VLSrequestExt2 5.1.1. Syntax VLSrequestExt2 ( unsigned char

*license_system,

unsigned char

*publisher_name,

unsigned char

*product_name,

unsigned char

*version,

unsigned long

*units_reqd,

unsigned char

*log_comment,

LS_CHALLENGE LS_HANDLE

*challenge, *lshandle,

VLSserverInfo

*serverInfo,

unsigned long

*team_capacity_reqd,

unsigned long

*capacity_reqd,

unsigned char

*unused1,

unsigned long

*special_flag );

Argument license_system

Description Unused. n n

publisher_name

n

n

product_name

n n n

version

n n

n

units_reqd

n

n

n

log_comment

n

Use LS_ANY as the value of this variable. LS_ANY is specified to indicate a match against the installed license system. A string identifying the publisher of the product. Limited to 32 characters and cannot be NULL. Company name and trademark may be used. Name of the feature for which a license code is requested. May consist of any printable characters and cannot be NULL. Limited to 24 characters. Version of the feature for which a license code is requested. May consist of any printable characters. Limited to 11 characters. Version can be NULL. The number of licenses required. The license server verifies that the number of units exist and may reserve those units. The number of available units is returned. If the number of licenses available with the license server is less than the requested number, the number of available licenses will be returned using units_reqd. If units_reqd is NULL, a value of 1 unit is assumed. To use the capacity licensing it is necessary that units required be always 1. A string to be written by the license server to the comment

5.1. VLSrequestExt2

Argument

challenge

Description field of the usage log file. n a NULL value for this argument if no log comment is desired. n

n

lshandle

n

n n

serverInfo

n

n

team_capacity_reqd

n n

n

capacity_reqd

221

n n

n

The challenge structure. If challenge-response mechanism is not being used, this pointer must be NULL. The response to the challenge is provided in the same structure, provided a license was issued, i.e., provided the function VLSrequestExt2 returns LS_SUCCESS. The handle for this request is returned in lshandle. This handle must be used to later update and release this license code. A client can have more than one handle active at a time. Space for lshandle must be allocated by the caller. This information is ed to the license server for use in server hook functions. VLSinitServerInfo must be called to initialize serverinfo. Required team capacity If the server does not have the requested capacity this field will return the team capacity available with the server for this feature and version. If the request is made for a non-capacity license, this must be ed as NULL. Required capacity If the server does not have the requested capacity, this field will return the capacity available with the server for this feature and version. If the request is made for a non-capacity license this must be ed as NULL.

unused1

Reserved for future use.

special_flag

An IN/OUT parameter with the following possible values: n

n n

The IN value can be VLS_IGNORE_GRACE_ERROR (default) or VLS_NOTIFY_GRACE_ERROR. When the flag is set to VLS_ IGNORE_GRACE_ERROR, any error encountered during the installation of a grace license will be ignored and the VLSrequestExt2 function will succeed. When the flag is set to VLS_NOTIFY_GRACE_ERROR, any error encountered during the installation of a grace license will make the VLSrequestExt2 function fail (and the application will not run). The OUT value will be the grace period-related error code. VLS_IGNORE_GRACE_ERROR will be applicable to the other variants of the request API functions (like LSrequest, VLSrequestExt, and so on).

222

Chapter 5: Capacity License API

5.1.2. Description s capacity as well as non-capacity requests.

If the request is denied due to either insufficient team capacity or capacity then accordingly the capacity_reqd or team_capacity_reqd field should contain the available capacity. VLSrequestExt2 must be used whenever the wishes to use the capacity feature in a license. The call can also be used to obtain a token from normal license. If the developer wishes to override any of the default information ed to the license server, he would be using the VLSsetTeamId/ VLSsetTeamIdValue APIs. The following information is sent by the licensing library as identification information: n n n n

Name Host Name X-Display name Vendor defined string

This information is used by the server when it manages or creates teams. VLSsetTeamId/ VLSsetTeamIdValue needs to be called before calling the request API so that it can the correct information about the name etc. to the license server. Lets consider a possible scenario to interpret the above: Say we initialize the license system as: int team_id = 1; /* Override name information */ int units_reqd = 1; /* Should always be 1 if using capacity request*/ unsigned long team_capacity = 1000; /* Say*/ unsigned long _capacity = 800; /* Cannot be greater than team

LS_STATUS_CODE ret_val; if(VLSinitialize()){ // Error in initializing SLM library. // Do error condition } VLSsetTeamId(1,"SENTINEL"); Here we ‘SENTINEL’ as the name. So even if the has logged into the client machine with say "XYZ" name, the license server would see the request as if it is coming from "SENTINEL". Now

5.1. VLSrequestExt2

223

ret_val = VLSrequestExt2(featureName, version,&units_reqd, &team_ capacity, &_capacity); if(ret_val == LS_SUCCESS){ // Succesfully got the requested token as well as team and capacity. Now do further actions based on these values } In case you are unable to get a license token.The possible reasons could be: n

Team limit has been exhausted

n

capacity has been exhausted

n

Team capacity has been exhausted in case of pooled licenses only

5.1.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_APP_UNNAMED

Description n featureName is NULL n version is NULL Both feature name and version cannot be NULL at the same time.

VLS_CALLING_ERROR

n n n

VLS_NO_LICENSE_GIVEN

n n

lshandle is NULL challenge argument is non NULL Attempted to use stand-alone mode with networkonly library, or network mode with stand-alone library. unitsReqd is zero License request is denied due to server hook failure.

VLS_NO_SUCH_FEATURE

License server does not have license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses are in use.

LS_INSUFFICIENTUNITS

License server does not have sufficient licensing units for requested feature to grant license.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_EXHAUSTED

Trial license expired or trial license usage exhausted.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_CLK_TAMP_FOUND

n

n

VLS_VENDORIDMISMATCH

License server has determined that the client system lock has been modified. The license for this feature has time tampering protection enabled, so the license operation is denied.

The vendor identification of requesting application does

224

Chapter 5: Capacity License API

Error Code

Description not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_MAJORITY_RULE_ FAILURE

Majority rule failure prevents token from being issued.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation request.

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

n n

No license server has been set Unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE

Message from the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_INTERNAL_ERROR

Failure occurred in setting timer. (Timer is only attempted to be set if timer is available for platform and if license requires timer for updates.)

VLS_INSUFFICIENT_TEAM_ CAPACITY License server does not currently have sufficient team capacity available. VLS_INSUFFICIENT__ CAPACITY License server does not currently have sufficient capacity available for this team member. For a complete list of the error codes, see Licensing Library Error and Result Codes.

5.2. VLSgetFeatureInfoExt

225

5.2. VLSgetFeatureInfoExt 5.2.1. Syntax LS_STATUS_CODE VLSgetFeatureInfoExt ( unsigned char *feature_name, unsigned char *version, unsigned long *capacity, int index, char *unused1, long *unused2, VLSfeatureInfo feature_info );

Argument feature_name

Description Name of the feature.

version

Version of the feature.

capacity

Capacity of the feature.

index

Used to specify a particular feature.

unused1

Use NULL as value.

unused2

Use NULL as value.

feature_info

The structure in which information will be returned. Space must be allocated by caller.

5.2.2. Description Returns the information of features available on the server. n

n

n

If name, version and capacity is not NULL, information about the feature indicated by name, version and capacity is returned. If information about a non-capacity license is desired, capacity should be ed as NULL and feature must be non-NULL. If information about all licensed features (capacity as well as non-capacity) is desired, feature name should be NULL, and index should be used in a loop.

5.2.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description n featureinfo is NULL n index is negative n Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library.

226

Chapter 5: Capacity License API

Error Code VLS_APP_UNNAMED

Description Version is NULL when name is non_NULL

VLS_NO_MORE_ FEATURES

Finished retrieving feature information for all features on license server.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

No license server has been set and unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

VLS_NO_SUCH_ FEATURE

License server does not have license that matches requested feature, version and capacity.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

5.3. VLSgetCapacityList

227

5.3. VLSgetCapacityList 5.3.1. Syntax VLSgetCapacityList ( ifndef LSNOPRONTO unsigned char

LSFAR *feature_name,

unsigned char

LSFAR *feature_version,

int unsigned long

LSFAR *index, LSFAR *bufferSize,

char

LSFAR *capacityList,

char

LSFAR *log_comment,

unsigned long

LSFAR *unused2

#endif );

Argument feature_name

Description Name of the feature.

feature_version

Version of the feature.

index

Returns the index of the license up to which the capacity has been retrieved based on the bufferSize

bufferSize

Specifies the size of capacityList.

capacityList

An array containing a list of all the capacities available for this feature and version, separated by space. The caller should allocate the space.

log_comment

Use NULL as value.

unused1

Use NULL as value.

5.3.2. Description Returns the list of all the capacities of all the licenses having specified feature and version but different capacity. This function returns list of capacities as one string, each capacity separated by a space character. If capacityList is ed as NULL, the API returns the buffersize required. VLSgetCapacityList returns an error if the license is a non-capacity license. For example if Sentinel RMS license server has following licenses: n

Feature F1, version V1, capacity 500

n

Feature F1, version V1, capacity 1000

n

Feature F1, version V1, capacity 1500

n

Then this API would return "500 1000 5000" as the output string in "capacity_list"

For a discussion of pooled versus non-pooled capacity licenses, refer to the Sentinel RMS Development Kit Developer's Guide.

228

Chapter 5: Capacity License API

5.3.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_NO_SUCH_FEATURE

Description License server does not have a license that matches the request feature, version and capacity.

VLS_APP_UNNAMED

featureName is NULL.

VLS_CALLING_ERROR

Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

No license server has been set and unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_BUFFER_TOO_SMALL

An error occurred in the use of an internal buffer.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

5.4. VLSgetClientInfoExt

229

5.4. VLSgetClientInfoExt 5.4.1. Syntax VLSgetClientInfoExt ( unsigned char

*feature_name,

unsigned char

*version,

unsigned long

*capacity,

int

index,

char

*log_comment,

VLSclientInfo *client_info );

Argument feature_name

Description Name of the feature.

version

Version of the feature.

capacity

Capacity of the feature.

index

Used to specify a particular client.

log_comment

Comment.

client_info

The structure in which information will be returned. Space allocated by the caller.

5.4.2. Description Returns the list of all the clients running for a particular feature, version and capacity. If the capacity is specified as NULL, this API shall return the list of all the clients for a particular feature and version. The suggested use of this function is in a loop, where the first call is made with index 0 which retrieves information about the first client. Subsequent calls, when made with 1, 2, 3, and so on, will retrieve information about other clients of that feature type. Memory for client_info should be allocated before making the call.

5.4.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

Description n featureName is NULL. n version is NULL Both feature name and version cannot be NULL at the same time.

VLS_CALLING_ERROR

n n n

clientInfo parameter is NULL index is negative Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library.

230

Chapter 5: Capacity License API

Error Code VLS_NO_MORE_CLIENTS

Description Finished retrieving client information for all clients.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_MULTIPLE_VENDORID_ FOUND

The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

No license server has been set and unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

5.5. VLSdeleteFeatureExt

231

5.5. VLSdeleteFeatureExt 5.5.1. Syntax VLSdeleteFeatureExt ( unsigned char

*feature_name,

unsigned char

*version,

unsigned long

*capacity,

unsigned char

*log_comment,

LS_CHALLENGE

*challenge,

unsigned char

*unused1,

unsigned char

*unused2 );

Argument feature_name

Description Name of the feature.

version

Version of the feature.

capacity

Capacity of the feature.

log_comment

Unused. Use NULL as value.

challenge

Unused. Use NULL as value.

unused1

Use NULL as value.

unused2

Use NULL as value.

5.5.2. Description Deletes a license from the server based on feature, version and capacity. If the capacity is NULL, this API will delete a non-capacity license for the feature, version specified. The license is deleted from the server only and not from the license file.

5.5.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_APP_UNNAMED

Description n featureName is NULL. n version is NULL Both feature name and version cannot be NULL at the same time.

VLS_CALLING_ERROR

Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_DELETE_LIC_FAILED

Generic error indicating the feature has not been deleted.

232

Chapter 5: Capacity License API

Error Code VLS_VENDORIDMISMATCH

Description The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has a license. This error occurs only when client is older than version 6.3 else the error returned is VLS_ NO_SUCH_FEATURE.

VLS_MULTIPLE_VENDORID_FOUND The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested. VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

No license server has been set and unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message from license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

5.6. VLSgetCapacityFromHandle

5.6. VLSgetCapacityFromHandle 5.6.1. Syntax VLSgetCapacityFromHandle ( LS_HANDLE

Argument

lshandle,

unsigned long

LSFAR *team_capacity,

unsigned long

LSFAR *_capacity

unsigned long

LSFAR *license_capacity );

handle

Description Handle

team_capacity

Team capacity allocated to the handle and issued by the server

_capacity

capacity allocated to the handle and issued by the server

license_capcity

License capacity allocated to the handle

5.6.2. Description VLSgetCapacityFromHandle returns the team capacity and capacity allocated to a handle.

5.6.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_BADHANDLE

Description The handle is invalid.

For a complete list of the error codes, see Licensing Library Error and Result Codes. 

233

234

Chapter 5: Capacity License API

5.7. VLSsetTeamId See VLSsetSharedId/ VLSsetTeamId.

5.8. VLSsetTeamIdValue

5.8. VLSsetTeamIdValue See VLSsetSharedIdValue/ VLSsetTeamIdValue.

235

6 Chapter 6: License Queuing API License queuing is the ability of our license servers to take a license request for a feature and place it in reserve until a license is available. Once the license is available, the license server will then notify the requesting application that the license is now ready for use. Given below is the list of the API functions: Function VLSqueuePreference Struct

Description Specifies the clients preference for how it wishes to be placed in the queue.

VLSserverInfo Struct

Stores information about the server.

VLSgetQueuedClientInfo Struct

Returns client information.

VLSqueuedRequest VLSqueuedRequestExt

An integrated request for an authorized license code from the license server. Use this API to: n

n

n

Request a license, with option to queue (requestFlag = VLS_REQ_GET | VLS_REQ_QUEUE). Request a license without queuing (requestFlag = VLS_ REQ_GET). This option has the same effect as calling a non-queuing API request (LSRequest, VLSrequestExt, etc.). Request to be placed in the queue, even if the license server has available licenses (requestFlag = VLS_REQ_ QUEUE).

VLSgetQueuedClientInfo

Retrieves the current information of a queued client, such as the number of requested licenses, feature_name, version, and index.

VLSremoveQueuedClient

Removes a queued client from the queue.

VLSremoveQueue

Deletes the entire queue.

VLSgetHandleStatus

Reports the current status of the handle.

VLSupdateQueuedClient

Once the client has been put in the queue, it must call this API periodically to inquire its current status with the license server. Moreover, calling this function has the effect of informing the license server that the client is alive and is still seeking the license.

VLSgetQueuedLicense

Obtains license, once it has been granted. This function is called only after a call to VLSupdateQueuedClient reveals that a license has been granted to a queued client.

238

Chapter 6: License Queuing API

Function VLSqueuePreference Struct

Description Specifies the client preference for getting into the queue.

VLSinitQueuePreference

Initializes provided queue preference structure to default values.

6.1. The License Queuing Example Code

239

6.1. The License Queuing Example Code You may need to format spaces in an editor if using the sample code given below.

{/* License was available, run the application! */ } else if (request_flag & VLS_REQ_QUEUE) {/* Was placed on the queue */ /* TODO: Start timer for sending periodic queue updates (every 50 secs is recommended). Assume function TimerHandler () will be called when the timer expires (see below). */ } } else {/* Queued request was not successful, clean up and exit. */ VLScleanup (); return (1); } /* End if success */ } /* end main () */ void TimerHandler () {/* Called periodically in order to check the queue status.*/ long expiration_time; LS_STATUS_CODE returnCode; returnCode = VLSupdateQueuedClient (ls_handle,&expiration_time,(unsigned char LSFAR *) NULL,(LS_CHALLENGE LSFAR *) NULL);/* Is the queued license available*/ if (returnCode == LS_SUCCESS && expiration_time > 0 ) { if ((returnCode =VLSgetQueuedLicense(ls_handle,(unsigned char LSFAR *) NULL,(LS_CHALLENGE LSFAR *) NULL))== LS_SUCCESS) { /*Disable the application’s timer and run the application! */ /* Enable automatic heartbeats to the server */ VLSdisableAutoTimer (ls_handle, VLS_ON); } else {/* Error getting the license, clean up and quit. */ VLScleanup (); /* Terminate the process */ } } }

240

Chapter 6: License Queuing API

6.2. VLSqueuePreference Struct typedef struct { long wait_time; long hold_time; int priority_num; long absPosition; long grpPosition; } VLSqueuePreference;

Member

wait_time

Description Maximum time, the client can be in queue.

hold_time

After allotment, the maximum time interval for which the server will keep the requested units reserved for this client.

priority_num

Priority vis-a-vis other clients, as decided by the client application. For use in future. Not implemented in SLM7.0.

absPosition

The maximum position within the queue, before which the client can be queued.

grpPosition

The maximum position within the queue, considering only those queued clients that belong to the same group as this client, before which the client can be queued -1 if the client doesn't care.

6.3. VLSserverInfo Struct

6.3. VLSserverInfo Struct typedef struct { char

identifier[VLS_MAX_NAME_LEN];

char

inBuf[VLS_MAX_BUF_LEN];

char

outBuf[VLS_MAX_BUF_LEN];

} VLSserverInfo;

Member

identifier

Description The name of the server hook which the wants to call.

inBuf

String ed to the server.

outBuf

String returned by the server.

241

242

Chapter 6: License Queuing API

6.4. VLSQueuedClientInfo Struct typedef struct

queued_client_info_struct { char

_name[VLS_MAXLEN];

char

host_name[VLS_MAXLEN];

char

x_display_name[VLS_MAXLEN];

char

shared_id_name[VLS_MAXLEN];

char

group_name[VLS_MAXLEN];

unsigned long

host_id;

long

server_start_time;

long

server_end_time;

unsigned long

qkey_id;

int

num_units;

int

num_resvd_default;

int

num_resvd_native;

long

wait_time;

long

hold_time;

int

priority_num;

long

absPosition;

long

grpPosition;

long

availabilityTime;

} VLSqueuedClientInfo;

Member

_name

Description The name of the using the application, where MAXLEN is set to 64 characters.

host_name

Name of the host/computer where the is running the application, where MAXLEN is set to 64 characters.

x_display_name

Name of the X display where the is displaying the application, where MAXLEN is set to 64 characters.

shared_id_name

A special vendor-defined ID that can be used for license sharing decisions. It always has the fixed value, defaultsharing- ID, unless it is changed by ing a custom function using the VLSsetSharedId API call. The maximum length of the string is set to 64 characters.

group_name

Name of the reserved group to which the belongs, where MAXLEN is set to 64 characters. If the does not belong to an explicitly named group, DefaultGrp is returned.

host_id

The host ID of the computer on which the is working.

server_start_time

server_start_time is the start time of the license token.

server_end_time

server_end_time is the end time of the license token. server_end_ time should be interpreted as as start_time + heart beat interval of the license.

qkey_id

Identifier of the client queue.

6.4. VLSQueuedClientInfo Struct

Member

num_units

Description Number of units consumed by the client so far.

num_resvd_default

The number of tokens given to this queued token from default pool, that is from the unreserved tokens.

num_resvd_native

The number of tokens given to this queued token from its reservation group.

wait_time

Maximum time (in seconds), the client can be in queue.

hold_time

After allotment, the maximum time interval (in seconds) for which the server will keep the requested units reserved for this client.

priority_num

Priority vis-a-vis other clients, as decided by the client application. For use in future. Not implemented in SLM7.0.

absPosition

The maximum position within the queue, before which the client can be queued.

grpPosition

Current position within the queue, considering only those queued clients that belong to the same group to which this client belongs to.

243

244

Chapter 6: License Queuing API

6.5. VLSqueuedRequest and VLSqueuedRequestExt 6.5.1. Syntax int

VLSqueuedRequest(

unsigned char

*license_system,

unsigned char

*publisher_name,

unsigned char

*product_name,

unsigned char)

*version,

unsigned long

*units_reqd,

unsigned char

*log_comment,

LS_CHALLENGE LS_HANDLE

*challenge, *lshandle,

VLSqueuePreference

*qPreference,

int

requestFlag);

int

VLSqueuedRequestExt(

unsigned char unsigned char unsigned char unsigned char)

*license_system, *publisher_name, *product_name, *version,

unsigned long

*units_reqd,

unsigned char

*log_comment,

LS_CHALLENGE LS_HANDLE VLSqueuePreference int

*challenge, *lshandle, *qPreference, requestFlag,

VLSserverInfo server_info );

Argument license_system

Description A license requested in the system. Pointer to the string which uniquely identifies a particular license system.

publisher_name

Refers to the name of the publisher (manufacturer) of the product. Cannot be NULL and must be unique. It is recommended that a company name and trademark be used.

product_name

Feature name. The name of the product requesting licensing resources. Cannot be NULL and must be unique.

version

Version for which licenses are requested. Must be unique for the associated feature

units_reqd

Number of units requested to run the license. The license system verifies that the requested number of units exists and it is possible to reserve those units, but no units are actually consumed at this time. The default is 1, and this value is used if a NULL value is ed.

6.5. VLSqueuedRequest and VLSqueuedRequestExt

Argument log_comment

245

Description A string that is written by the license manager to the comment field of the usage log file.

challenge

Pointer to a challenge structure. The challenge-response will also be returned.

lshandle

Handle to the license which the has requested. If the has successfully received the license, the status of the handle is VLS_ACTIVE_HANDLE. Otherwise, the client is put in the queue and the status of the handle is VLS_QUEUED_HANDLE.

qPreference

Pointer to the VLSqueuePreference structure, which is used to specify the client’s preference for how it wishes to be placed in the queue. After the call is made, the structure contains the values assigned by the license server when it has placed the client in the queue.

requestFlag

Valid values are: n

n

VLS_REQ_GET - specifies a non-queuing request (without queuing the client). If license is not available, client will not be queued. VLS_REQ_QUEUE - specifies to queue the client (without returning with the license). Even if license is available, client will be queued.

If both are specified, the client requests the license server to give the license, if available, otherwise to queue the client. Upon return from this API, this parameter will be set to either VLS_REQ_GET (specifying the license has been granted) or, VLS_REQ_QUEUE (specifying that the client has been queued). server_info

Information about the server.

6.5.2. Description The call provides the mechanism to the calling application to ask the license server to grant a license if available. If no license is available, the client will be queued. The client can call VLSupdateQueuedClient to inquire if a license is available. Once a license is available, the client can call VLSgetQueuedLicense to obtain the license. In response, the license server will either issue the license token when (and if) the license is available, put the client in the queue when the license is not available, or issue an appropriate error message, which describes the cause for not being able to service the request. The client will the following information to the license server: n

Time in seconds for the client to wait in the queue for the license.

n

Time in seconds for the server to hold the license once it becomes available.

n

Priority relative to other clients.

n

The maximum position within the queue before which the client can be queued.

n

The maximum position within the group queue, before which the client can be queued.

246

Chapter 6: License Queuing API

Notice that the LS_MAX_QLEN environment variable can override the qPreference structure. The end can put a limit on the maximum size of the queue by defining the LS_MAX_QLEN environment variable. This variable depends upon the availability of memory resources. The different values of LS_ MAX_QLEN are: n

LS_MAX_QLEN not set. Client preference is applied.

n

LS_MAX_QLEN = -1. Client preference is ignored and the client is always queued.

n

LS_MAX_QLEN = 0. Queue is disabled and no clients will be put in the queue.

n

LS_MAX_QLEN > 0. Overrides the client’s preference.

Similarly variable LS_MAX_GRP_QLEN will override the setting of the max group wait time in the qPreference structure. Variables LS_MAX_WAIT_SEC and LS_MAX_HOLD_SEC override the max wait time and max hold time elements of the qPreference structure.

6.5.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

VLS_APP_UNNAMED

Description n request_flag specifies queuing but qPreference is NULL. n lshandle is NULL. n challenge argument is non-NULL, but cannot be understood. n publisherName is NULL n n

VLS_NO_LICENSE_GIVEN

n n n

product_name is NULL version is NULL units_reqd is zero. Invalid handle specified. Generic error indicating that the license is not granted.

LS_NOLICENSESAVAILABLE

All licenses in use.

LS_INSUFFICIENTUNITS

License server does not currently have sufficient licensing units for the requested feature to grant a license.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

LS_LICENSE_EXPIRED

License has expired.

VLS_NOMORE_QUEUE_ RESOURCES

Queue is full.

VLS_APP_NODE_LOCKED

Requested feature is node locked, but request was issued from an unauthorized machine.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

6.5. VLSqueuedRequest and VLSqueuedRequestExt

Error Code

VLS_CLK_TAMP_FOUND

Description License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH

The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_ FEATURE.

VLS_TRIAL_LIC_EXHAUSTED

Trial license has expired.

VLS_NO_SERVER_RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_RESPONSE Communication with license server has timed out. VLS_HOST_UNKNOWN

Invalid hostName is specified.

VLS_NO_SERVER_FILE

The license server has not been set and is unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be understood. LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NON_REDUNDANT_ SRVR

License server is non-redundant and therefore cannot this redundancy-related operation.

VLS_SERVER_SYNC_IN_ PROGRESS

License server synchronization in process.

VLS_FEATURE_INACTIVE

Feature is inactive on specified license server.

VLS_MAJORITY_RULE_ FAIL- Majority rule failure prevents token from being issued. URE LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

247

248

Chapter 6: License Queuing API

6.6. VLSgetQueuedClientInfo 6.6.1. Syntax int VLSgetQueuedClientInfo ( unsigned char

*feature name,

unsigned char

*version,

int

index,

char

LSFAR *unused1,

VLSqueuedClientInfo

*client_info );

Argument feature_name

Description Feature name of the client for which we are requesting information. An IN parameter.

version

Version for which licenses are requested. Must be unique, for the associated feature. An IN parameter.

index

Index of the client with the license server, for a particular feature. An IN parameter.

client_info

The structure in which information will be returned. Pointer to the VLSqueuedClientInfo structure, which specifies the client information. An OUT parameter.

6.6.2. Description Fills the structure pointed by client_info to a structure containing the current information of a queued client identified by specified feature_name, version, and index.

6.6.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

VLS_APP_UNNAMED

Description n client_info parameter is NULL. n index is negative. n Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. n n

feature_name is NULL version is NULL

Both feature and version cannot be NULL VLS_NO_LICENSE_GIVEN

Finished retrieving client information for all the clients.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

VLS_MULTIPLE_ VENDORID_FOUND

The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested.

6.6. VLSgetQueuedClientInfo

Error Code

VLS_NO_SERVER_ RUNNING

Description License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

249

250

Chapter 6: License Queuing API

6.7. VLSremoveQueuedClient 6.7.1. Syntax int VLSremoveQueuedClient ( unsigned char

*feature name,

unsigned char

*version,

int char

Argument

qkey_id, *log_comment );

feature_name

Description Feature name of the client for which we are requesting information.

version

Version for which licenses are requested.

qkey_id

Identifier of the client queue, which needs to be removed.

log_comment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired.

6.7.2. Description This API provides an istrative mechanism to remove a queued client. VLSremoveQueuedClient will be available to: n

The who started the license server, which actually signifies when the client was put in the queue.

n

The root/ .

n

The - that originally goes to the queue placement.

Internally, this API will send a message to signal the license server that a specified client in the queue for a specified feature should be removed.

6.7.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

VLS_APP_UNNAMED

Description n qkey_id parameter cannot be negative. n Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. n n

feature_name is NULL version is NULL

Both feature name and version cannot be NULL. VLS_NO_SUCH_CLIENT

License server does not have the specified client.

VLS_CLIENT_NOT_

Client is not authorized to make the specified request.

6.7. VLSremoveQueuedClient

Error Code

Description

AUTHORIZED VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

251

252

Chapter 6: License Queuing API

6.8. VLSremoveQueue 6.8.1. Syntax int VLSremoveQueue ( unsigned char

*feature name,

unsigned char

*version,

char

Argument

*log_comment );

feature_name

Description Identifies the license whose queue needs to be removed.

version

Version for which licenses are requested. Must be unique.

log_comment

A string to be written by the license server to the comment field of the usage log file. a NULL value for this argument if no log comment is desired.

6.8.2. Description This API will provide a mechanism to delete the complete queue for a specified license. VLSremoveQueue will be available to: n

n

The - who started the license server, which actually signifies when the client was put in the queue. The root/ .

6.8.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR VLS_APP_UNNAMED

Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. n n

feature_name is NULL version is NULL

Both feature name and version cannot be NULL. VLS_CLIENT_NOT_ AUTHORIZED

Client not authorized to remove queue.

VLS_NO_SERVER_ RUNNING

License server on specified host is not available for processing license operation requests.

VLS_HOST_UNKNOWN

Invalid hostName was specified.

VLS_NO_SERVER_FILE

The license server has not been set and is unable to determine which license server to use.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for

6.8. VLSremoveQueue

Error Code

Description servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

253

254

Chapter 6: License Queuing API

6.9. VLSgetHandleStatus 6.9.1. Syntax int VLSgetHandleStatus ( LS_Handle

Argument lshandle

lshandle );

Description Identifies the handle previously returned by VLSqueuedRequest.

6.9.2. Description Reports the current status of the handle.

6.9.3. Returns Returns the following error codes: Error Code

LS_BADHANDLE

Description Invalid handle. Handle is already released and destroyed from previous license operations.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

VLS_AMBIGUOUS_ HANDLE

lshandle is an ambiguous handle; it is not exclusively active or exclusively queued.

VLS_ACTIVE_HANDLE

lshandle is an active handle.

VLS_QUEUED_HANDLE

lshandle is a queued handle.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

6.10. VLSupdateQueuedClient

255

6.10. VLSupdateQueuedClient 6.10.1. Syntax int VLSupdateQueuedClient ( LS_HANDLE long unsigned char LS_CHALLENGE

Argument lshandle absExpiryTime

*absExpiryTime, *unused1, *unused2 );

Description The handle previously returned by VLSqueuedRequest. The status of the handle must be VLS_QUEUED_HANDLE or an error will occur. Once the license is available with the license server, the next call to this API returns in this parameter, the absolute expiry time before which the client should get the license using VLSgetQueuedLicense. If any call to VLSupdateQueuedClient returns a non-negative value in this parameter, then the license has been granted and set aside for the client. There is no need to continue its periodic call to this function. The next step is to obtain the license by calling VLSgetQueuedLicense. Possible values for absExpiryTime are: n n

unused1 unused2

lshandle,

Zero = license is not available. Non-zero = license is available and will stop calling the API.

Uses NULL as the value.

6.10.2. Description The client calls this API, requesting the license server to put him in the queue. Once the client has been put in the queue, it must call this API periodically to inquire its current status with the license server. Moreover, it also informs the license server that, he is alive and is seeking the license. Notice, the clients need to make at least one queue update, within 5 minutes of the previous queueupdate or the request to queue itself. This is imperative so as to make the license server aware of the active clients. If the license server does not receive an update request from a client within 5 minutes of the last queue-update, it will then assume the client to be inactive and remove the client from the queue.

6.10.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description n absExpiryTime is NULL. n Handle cannot be active.

256

Chapter 6: License Queuing API

Error Code

Description n challenge argument is non-NULL, but cannot be understood.

LS_BADHANDLE

Invalid handle.

LS_LICENSETERMINATED

Cannot update license because license has already expired.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

LS_NOLICENSESAVAILABLE

All licenses are in use.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_EXHAUSTED Trial license has expired. VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_FINGERPRINT_ MISMATCH

or machine excluded from accessing the requested feature.

VLS_APP_NODE_LOCKED

Feature is node locked, but update request was issued from an unauthorized machine.

VLS_CLK_TAMP_FOUND

License server has determined that the client’s system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE. VLS_INVALID_DOMAIN

The domain of the license server is different from that of the client.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

6.11. VLSgetQueuedLicense

257

6.11. VLSgetQueuedLicense 6.11.1. Syntax int VLSgetQueuedLicense ( LS_HANDLE

Argument lshandle

lshandle,

unsigned char

*log_comment,

LS_CHALLENGE

*challenge );

Description The handle previously returned by VLSqueuedRequest. The status of the handle must be VLS_QUEUED_HANDLE and the last call to VLSupdateQueuedClient must have reported that the licenses have been made available with the license server.

log_comment

A string that is written by the license manager to the comment field of the usage log file.

challenge

The challenge-response for this operation. Pointer to a challenge structure. The challenge-response will also be returned.

6.11.2. Description Once the queued client identifies that the required licenses are made available with the license server, it calls this API to fetch the license. This API will be ed from the licensing library handle only and, internally, it will send all the memorized information to the license server. On return it will provide a valid client-handle value that will be used in later API calls.

6.11.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLS_CALLING_ERROR

Description challenge argument is non-NULL, but cannot be understood.

LS_BADHANDLE

Invalid handle.

LS_BUFFER_TOO_SMALL

An error occurred in the use of an internal buffer.

VLS_NO_LICENSE_GIVEN

Generic error indicating that the license is not granted.

VLS_NO_SUCH_FEATURE

License server does not have a license that matches requested feature, version and capacity.

LS_LICENSE_EXPIRED

License has expired.

VLS_TRIAL_LIC_EXHAUSTED Trial license has expired. LS_NOLICENSESAVAILABLE

All licenses are in use.

VLS__EXCLUDED

or machine excluded from accessing requested feature.

VLS_FINGERPRINT_ MIS-

Client-locked. Locking criteria does not match.

258

Chapter 6: License Queuing API

Error Code

Description

MATCH VLS_APP_NODE_LOCKED

Requested feature is node locked, but request was issued from unauthorized machine.

VLS_VENDORIDMISMATCH The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has the license. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE. VLS_INVALID_DOMAIN

The domain of the license server is different from that of the client.

VLS_NO_SERVER_ RESPONSE

Communication with license server has timed out.

VLS_BAD_SERVER_ MESSAGE

Message returned by the license server could not be understood.

LS_NO_NETWORK

Generic error indicating that the network is unavailable for servicing the license operation.

LS_NORESOURCES

An error occurred in attempting to allocate memory needed by this function.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

6.12. VLSinitQueuePreference

6.12. VLSinitQueuePreference 6.12.1. Syntax int VLSinitQueuePreference ( VLSqueuePreference

Argument qPreference

*qPreference );

Description Pointer to the VLSqueuePreference structure, which specifies the client preference for getting into the queue. After the call is made, the structure signifies the actual values, which the license server allocates to the client while putting him in the queue.

6.12.2. Description Initializes the VLSqueuePreference structure to default values. For more details, see VLSqueuePreference structure.

6.12.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLS_CALLING_ERROR

Description qPreference is NULL.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

259

7 Chapter 7: Upgrade License API The Sentinel RMS upgrade license feature enables you to update your customer's existing license to change the version or/and increase the capacity. A special upgrade license must be created to update the existing license. The API functions discussed in this section are categorized into license code generator and decoder API.

262

Chapter 7: Upgrade License API

The Upgrade License Code Generator API The following table summarizes the upgrade license code generator related functions: Function ucodeT Struct

Description Contains the values for the upgrade license.

VLSucgInitialize

Initializes the upgrade codegen library

VLSucgCleanup

Destroys the handle created using VLSucgInitialize

VLSucgReset

Sets all the fields of ucodeT to their default values

VLSucgGetNumErrors

Identifies the total number of messages recorded in the handle

VLSucgGetError Length

Returns the length of error message identified by msgNum and recorded in the handle

VLSucgGetError Message

Returns the earliest error from the handle up to bufLen characters

VLSucgPrintError

Prints the complete info of all the error messages stored in the handle to a file.

VLSucgAllowBase FeatureName

Identifies whether the corresponding VLSucgSetBaseFeatureName should be called or not

VLSucgSetBaseFeatureName

Sets the value of base_feature_name in the ucodeT struct.

VLSucgAllowBase FeatureVersion Identifies whether the corresponding VLSucgSetBaseFeatureVersion should be called or not. VLSucgSetBaseFeatureVersion

Sets the value of base_feature_version in the ucodeT struct.

VLSucgAllowUpgradeCode

Identifies whether the corresponding VLSucgSetUpgradeCode API should be called or not

VLSucgSetUpgrade Code

Sets the value of base_lock_code in the ucodeT struct to the value in the upgrade_code

VLSucgAllowUpgradeFlag

Identifies whether the corresponding VLSucgSetUpgradeFlag should be called or not

VLSucgSetUpgrade Flag

Sets the value of upd_flags in the ucodeT struct.

VLSucgAllowUpgradeVersion

Identifies whether the corresponding VLSucgSetUpgradeVersion should be called or not

VLSucgSetUpgrade Version

Sets the value of upd_version in the ucodeT struct.

VLSucgAllowUpgradeCapacity

Identifies whether the corresponding VLSucgSetUpgradeCapacityUnits and VLSucgSetUpgradeCapacity should be called or not

VLSucgSetUpgrade CapacityUnits Sets the value of capacity_units in the ucodeT struct. VLSucgSetUpgrade Capacity

Sets the value of capacity_increment in the ucodeT struct.

VLSucgGenerate License

Generates the upgrade license string for the given ucodeT struct

VLSucgGetLicense MeterUnits

Returns the number of license generation units available in the attached dongle

VLSGenerateUpgrade LockCode

Allows the to generate a unique upgrade code for the base

The Upgrade License Code Generator API

Function

Description license.

263

264

Chapter 7: Upgrade License API

7.1. ucodeT Struct 7.1.1. Syntax typedef struct { long structSz; unsigned int vendor_code; unsigned int version_num; /* Feature/Version of the base license that needs to be upgraded */ char base_feature_name[VLSucg_MAX_CODE_COMP_LEN+1]; char base_feature_version[VLSucg_MAX_CODE_COMP_LEN+1]; char base_lock_code[VLSucg_MAX_CODE_COMP_LEN+1]; unsigned long generation_time; unsigned long generation_sequence; unsigned long upd_flags; char upd_version[VLSucg_MAX_CODE_COMP_LEN+1]; /* New version for this feature*/ int capacity_units;

unsigned long capacity_increment ; unsigned long unused1; unsigned long unused2; } ucodeT;

Member structSz

Description Size of the structure.

Vendor_code

Internal use

version_num

Upgrade license code generation library version

base_feature_name

Feature Name of the base license that needs to be upgraded

base_feature_version

Feature Version of the base license that needs to be upgraded

lock_code

A unique code to identify base licenses which needs to be upgraded.

generation_time

This value shall be set automatically during the license generation time in GMT. It details about the time of license generation.

generation_sequence

This value shall be set at license generation time along with generation_time to ensure that on a fast system, even if two licenses are generated at the same time, this value should be different.

upd_flags

Bit-wise flag. Controls what will be updated: n n n

VLSucg_UPGRADE_VERSION VLSucg_UPGRADE_CAPACITY VLSucg_UPGRADE_ALL

7.1. ucodeT Struct

Member upd_version

Description New version for this feature.

capacity_units

Flag which determines capacity least count

capacity_increment

Capacity increment for this feature.

Unused

For future use.

Unused

For future use.

265

266

Chapter 7: Upgrade License API

7.2. VLSucgInitialize 7.2.1. Syntax int VLSucgInitialize ( VLSucg_HANDLE

Argument iHandle

*iHandle );

Description The pointer to instance handle for this library, provides access to the internal data structure.

7.2.2. Description Initializes the upgrade codegen library. VLSucgInitialize should be called before any other API. VLSucgInitialize returns a unique handle, which is used in all the other API of this library.

7.2.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description Call VLSucgCleanup to free the resources associated with the invalid handle.

VLSucg_MAX_LIMIT_CROSSED Library has crossed the limit of maximum handles it can allocate. VLSucg_LICMETER_NOT_ SUP- Your Sentinel RMS Development Kit License Meter is not ED ported. For a complete list of the error codes, see Upgrade License Error Codes.

7.3. VLSucgCleanup

267

7.3. VLSucgCleanup 7.3.1.  Syntax int VLSucgCleanup ( VLSucg_HANDLE

Argument iHandle

*iHandle );

Description Instance handle for this library

7.3.2. Description Destroys the handle created using VLSucgInitialize. VLSucgCleanup cleanups the resources associated with the handle.

7.3.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

For a complete list of the error codes, see Upgrade License Error Codes.

268

Chapter 7: Upgrade License API

7.4. VLSucgReset 7.4.1. Syntax int VLSucgReset ( VLSucg_HANDLE ucodeT

Argument

iHandle, *ucodeP );

iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

7.4.2. Description Sets all the fields of ucodeT to their default values. VLSucgReset is used after the Initialize and before the Set and Allow APIs.

7.4.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_INPUT

Description If the ucodeP is ed as NULL

For a complete list of the error codes, see Upgrade License Error Codes.

7.5. VLSucgGetNumErrors

269

7.5. VLSucgGetNumErrors 7.5.1. Syntax int VLSucgGetNumErrors ( VLSucg_HANDLE int

Argument

iHandle, *numMsgsP );

iHandle

Description Instance handle for this library

numMsgsP

The number of messages queued to the handle

7.5.2. Description Identifies the total number of messages recorded in the handle.

7.5.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_NO_RESOURCES

If no resources are available.

VLSucg_FAIL

On failure

For a complete list of the error codes, see Upgrade License Error Codes.

270

Chapter 7: Upgrade License API

7.6. VLSucgGetErrorLength 7.6.1. Syntax int VLSucgGetErrorLength ( VLSucg_HANDLE

Argument

iHandle,

int

msgNum,

int

*errLenP );

iHandle

Description Instance handle for this library

msgNum

The number of the message whose length is to be queried, starts from 0.

errLenP

The length of messages identified by msgNum

7.6.2. Description Returns the length of error message identified by msgNum and recorded in the handle. The length returned by VLSucgGetErrorLength include the space required for NULL termination.

7.6.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_NO_RESOURCES

If no resources are available.

VLSucg_FAIL

On failure

For a complete list of the error codes, see Upgrade License Error Codes.

7.7. VLSucgGetErrorMessage

271

7.7. VLSucgGetErrorMessage 7.7.1. Synatx int VLSucgGetErrorMessage (

Argument

VLSucg_HANDLE

iHandle,

char

*msgBuf,

int

bufLen );

iHandle

Description Instance handle for this library

msgBuf

A allocated buffer into which the reference message will be copied

bufLen

The byte length of the message copied into msgBuf

7.7.2. Description Returns the earliest error from the handle up to bufLen characters. n

The bufLen must be the length of the pre allocated buffer msgBuf.

n

The message returned should always be NULL terminated.

7.7.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_NO_RESOURCES

If no resources are available.

VLSucg_FAIL

On Failure

For a complete list of the error codes, see Upgrade License Error Codes.

272

Chapter 7: Upgrade License API

7.8. VLSucgPrintError 7.8.1. Syntax int VLSucgPrintError (

Argument

VLSucg_HANDLE

iHandle,

FILE

*file );

iHandle

Description Instance handle for this library

file

File pointer

7.8.2. Description Prints the complete info of all the error messages stored in the handle to a file.

7.8.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_NO_RESOURCES

If no resources are available.

VLSucg_FAIL

On Failure

For a complete list of the error codes, see Upgrade License Error Codes.

7.9. VLSucgAllowBaseFeatureName

273

7.9. VLSucgAllowBaseFeatureName 7.9.1. Syntax  int VLSucgAllowFeatureName ( VLSucg_HANDLE ucodeT

Argument

iHandle, *ucodeP );

iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

7.9.2. Description Identifies whether the corresponding VLSucgSetBaseFeatureName should be called or not. If the VLSucgAllowBaseFeatureName returns 1 only then the corresponding VLSucgSetBaseFeatureName should be called.

7.9.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code Description 1 VLSucgSetBaseFeatureName is allowed. 0

VLSucgSetBaseFeatureName is not allowed.

For a complete list of the error codes, see Upgrade License Error Codes.

274

Chapter 7: Upgrade License API

7.10. VLSucgSetBaseFeatureName 7.10.1. Syntax int VLSucgSetBaseFeatureName ( VLSucg_HANDLE ucodeT char

Argument

iHandle, *ucodeP, *feature_name );

iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

feature_name

Any printable ASCII text except #. Maximum of 24 characters.

7.10.2. Description Sets the value of base_ feature_name in the ucodeT struct. This function also checks the input variables for their validity and boundary conditions.

7.10.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_CHARS

Description Invalid characters in feature_name.

VLSucg_NO_FEATURE_NAME

If feature_name is NULL.

VLSucg_RESERV_STR_ERROR

If the feature_name is a reserved string.

VLSucg_EXCEEDS_MAX_ VALUE

If the length of feature_name string exceeds maximum allowed length(24 char).

For a complete list of the error codes, see Upgrade License Error Codes.

7.11. VLSucgAllowBaseFeatureVersion

275

7.11. VLSucgAllowBaseFeatureVersion 7.11.1. Syntax int VLSucgAllowBaseFeatureVersion ( VLSucg_HANDLE iHandle, ucodeT *ucodeP );

Argument iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

7.11.2. Description Identifies whether the corresponding VLSucgSetBaseFeatureVersion should be called or not. If the VLSucgAllowBaseFeatureVersion returns 1 only then the corresponding VLSucgSetBaseFeatureVersion should be called.

7.11.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code 1

Description VLSucgSetBaseFeatureVersion is allowed.

0

VLSucgSetBaseFeatureVersion is not allowed.

For a complete list of the error codes, see Upgrade License Error Codes.

276

Chapter 7: Upgrade License API

7.12. VLSucgSetBaseFeatureVersion 7.12.1. Syntax int VLSucgSetBaseFeatureVersion ( VLSucg_HANDLE

iHandle,

ucodeT

*ucodeP,

char

Argument

*feature_version );

iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

feature_version

Any printable ASCII text except #. Maximum of 11 characters.

7.12.2. Description Sets the value of base_ feature_version in the ucodeT struct. This function checks the input variables for their validity and boundary conditions.

7.12.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_CHARS

Description If feature_version characters are not printable.

VLSucg_RESERV_STR_ERROR If the feature_version is a reserved string. VLSucg_EXCEEDS_MAX_ VALUE

If the length of feature_version string exceeds maximum allowed length(11 char).

For a complete list of the error codes, see Upgrade License Error Codes.

7.13. VLSucgAllowUpgradeCode

277

7.13. VLSucgAllowUpgradeCode 7.13.1. Syntax int VLSucgAllowUpgradeCode ( VLSucg_HANDLE iHandle, ucodeT *ucodeP );

Argument iHandle

Description Instance handle for this library

ucodeP

The pointer to ucodeT struct

7.13.2. Description Identifies whether the corresponding VLSucgSetUpgradeCode should be called or not. Only if the VLSucgAllowUpgradeCode returns 1 then the corresponding VLSucgSetUpgradeCode should be called.

7.13.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code 1

Description VLSucgSetUpgradeCode is allowed.

0

VLSucgSetUpgradeCode is not allowed

For a complete list of the error codes, see Upgrade License Error Codes.

278

Chapter 7: Upgrade License API

7.14. VLSucgSetUpgradeCode 7.14.1. Syntax int VLSucgSetUpgradeCode ( VLSucg_HANDLE

iHandle,

ucodeT

*ucodeP,

char

Argument

*upgrade_code );

iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

upgrade_code

Upgrade code of base license.

7.14.2. Description Sets the value of the lock_code variable in the ucodeT struct. This function checks the input variables for their validity and boundary conditions. However, this function does not checks the validity of upgrade code. All the validations and matching of base license information with upgrade license information will be done in VLSucgGenerateLicense.

7.14.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code Description VLSucg_INVALID_INPUT If ucodeP is ed as NULL. VLSucg_NO_UPGRADE_ If the upgrade_code is ed as NULL or empty string. CODE VLSucg_EXCEEDS_MAX_ If the length of upgrade_code string exceeds maximum allowed VALUE length. VLSucg_FAIL

On Failure.

For a complete list of the error codes, see Upgrade License Error Codes.

7.15. VLSucgAllowUpgradeFlag

279

7.15. VLSucgAllowUpgradeFlag 7.15.1. Syntax int VLSucgAllowUpgradeFlag ( VLSucg_HANDLE iHandle, ucodeT *ucodeP );

Argument iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

7.15.2. Description Indicates whether the corresponding VLSucgSetUpgradeFlag should be called or not. If the VLSucgAllowUpgradeFlag returns 1 only then the corresponding VLSucgSetUpgradeFlag should be called.

7.15.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code 1

Description Capacity Upgrade is allowed.

0

Capacity Upgrade is not allowed.

For a complete list of the error codes, see Upgrade License Error Codes.

280

Chapter 7: Upgrade License API

7.16. VLSucgSetUpgradeFlag 7.16.1. Syntax int VLSucgSetUpgradeFlag ( VLSucg_HANDLE iHandle, ucodeT *ucodeP, char *flag );

Argument iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

flag

The value of flag is used to set the upd_flags of ucodeT struct. Legal values are bit combinations of n n n

VLSucg_UPGRADE_VERSION VLSucg_UPGRADE_CAPACITY VLSucg_UPGRADE_ALL

7.16.2. Description Sets the value of upd_flags in the ucodeT struct. This function also checks the input variables for their validity and boundary conditions. n

n

n

If the flag value is VLSucg_UPGRADE_VERSION then only version upgrade license can be generated. If the flag value is VLSucg_UPGRADE_CAPACITY then only capacity upgrade license can be generated. If the flag value is VLSucg_UPGRADE_ALL then both version and capacity upgrade license can be generated.

7.16.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_INVALID_INPUT

If the either the ucodeP or upd_flags is ed as NULL. Also if the upd_flags is ed as an empty string.

VLSucg_INVALID_INT_TYPE

If value of upd_flags is not numeric.

VLSucg_EXCEEDS_MAX_ VALUE

If value of upd_flags exceeds VLSucg_UPGRADE_ALL

VLSucg_LESS_THAN_MIN_ VALUE

If value is lower than VLSucg_UPGRADE_VERSION.

7.16. VLSucgSetUpgradeFlag

For a complete list of the error codes, see Upgrade License Error Codes.

281

282

Chapter 7: Upgrade License API

7.17. VLSucgAllowUpgradeVersion 7.17.1. Syntax int VLSucgAllowUpgradeVersion ( VLSucg_HANDLE ucodeT

Argument iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

iHandle, *ucodeP );

7.17.2. Description Indicates whether the corresponding VLSucgSetUpgradeVersion should be called or not. Only if the VLSucgAllowUpgradeVersion returns 1 then the corresponding VLSucgSetUpgradeVersion should be called.

7.17.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code 1

Description VLSucgSetUpgradeVersion is allowed

0

VLSucgSetUpgradeVersion is not allowed

For a complete list of the error codes, see Upgrade License Error Codes.

7.18. VLSucgSetUpgradeVersion

283

7.18. VLSucgSetUpgradeVersion 7.18.1. Syntax int VLSucgSetUpgradeVersion ( VLSucg_HANDLE

iHandle,

ucodeT

*ucodeP,

char

Argument

*upgrade_version );

iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

upgrade_version Any printable ASCII except #. Maximum of 11 characters.

7.18.2. Description Sets the value of upd_version in the ucodeT struct to the value of upgrade_version. This function also checks the input variables for their validity and boundary conditions.

7.18.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_INPUT

Description If the either the ucodeP or upgrade_version is ed as NULL. Also if the upgrade _version does not contain a valid string.

VLSucg_INVALID_CHARS

If upgrade_version characters are not printable.

VLSucg_RESERV_STR_ ERROR

If the upgrade_version is a reserved string.

VLSucg_EXCEEDS_MAX_ VALUE

If the length of upgrade_version string exceeds maximum allowed length.

For a complete list of the error codes, see Upgrade License Error Codes.

284

Chapter 7: Upgrade License API

7.19. VLSucgAllowUpgradeCapacity 7.19.1. Syntax int VLSucgAllowUpgradeCapacity ( VLSucg_HANDLE iHandle, ucodeT *ucodeP );

Argument iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

7.19.2. Description Indicates whether the corresponding VLSucgSetUpgradeCapacityUnits and VLSucgSetUpgradeCapacity should be called or not. If the VLSucgAllowUpgradeCapacity returns 1 only then the corresponding Capacity should be called.

7.19.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code 1

Description VLSucgSetUpgradeCapacity is allowed

0

VLSucgSetUpgradeCapacity is not allowed

For a complete list of the error codes, see Upgrade License Error Codes.

7.20. VLSucgSetUpgradeCapacityUnits 

285

7.20. VLSucgSetUpgradeCapacityUnits  7.20.1. Syntax int VLSucgSetUpgradeCapacityUnits ( VLSucg_HANDLE iHandle, ucodeT *ucodeP, char *cap_units );

Argument iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

cap_units

Capacity specification units: from 0 to 4. The values are: n n n n

n

If capacity_units is 0, capacity shall be multiple of 1(s), maximum 1022. If capacity_units is 1, capacity shall be multiple of 10(s), maximum 10220. If capacity_units is 2, capacity shall be multiple of 100(s), maximum 102200. If capacity_units is 3, capacity shall be multiple of 1000(s), maximum 1022000. If capacity_units is 4, capacity shall be multiple of 10000(s), maximum 10220000.

7.20.2. Description Sets the value of capacity_units in the ucodeT struct. This function should be called either in case of capacity upgrade or in case of both version and capacity upgrade. VLSucgSetUpgradeCapacityUnits also check the input variables for their validity and boundary conditions.

7.20.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_INPUT

Description If the either the ucodeP or cap_units is ed as NULL. Also if the cap_units is ed as an empty string.

VLSucg_INVALID_INT_TYPE If value of cap_units is not numeric. VLSucg_EXCEEDS_MAX_ VALUE

If the value of cap_units exceeds VLScg_CAPACITY_UNITS_MAX_ VALUE

VLSucg_LESS_THAN_MIN_ VALUE

If the value is lower than VLScg_CAPACITY_UNITS_MIN_VALUE.

For a complete list of the error codes, see Upgrade License Error Codes.

286

Chapter 7: Upgrade License API

7.21. VLSucgSetUpgradeCapacity 7.21.1. Syntax int VLSucgSetUpgradeCapacity ( VLSucg_HANDLE

iHandle,

ucodeT

*ucodeP,

char

Argument

*cap_increment );

iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

cap_ increment

Controls the capacity. n

n

n

n

n

n

If capacity_units is 0, capacity shall be multiple of 1(s), maximum 1022. If capacity_units is 1, capacity shall be multiple of 10(s), maximum 10220. If capacity_units is 2, capacity shall be multiple of 100(s), maximum 102200. If capacity_units is 3, capacity shall be multiple of 1000(s), maximum 1022000. If capacity_units is 4, capacity shall be multiple of 10000(s), maximum 10220000. VLScg_NOLIMIT_STRING or EMPTY(“/0”) String can be used to specify infinite capacity.

7.21.2. Definition Sets the value of capacity_increment in the ucodeT struct. This function also check the input variables for their validity and boundary conditions. Infinite capacity shall also be allowed.

7.21.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_BAD_HANDLE

Description If the handle ed is not a valid handle.

VLSucg_INVALID_INPUT

If the either the ucodeP or cap_increment is ed as NULL. Also if the cap_increment is ed as an empty string.

VLSucg_NOT_MULTIPLE

If value is not a correct multiple.

VLSucg_INVALID_INT_TYPE If value of cap_increment is not numeric. VLSucg_EXCEEDS_MAX_ VALUE

If the value of cap_increment exceeds maximum allowed.

VLSucg_LESS_THAN_MIN_

If the value is lower than minimum allowed.

7.21. VLSucgSetUpgradeCapacity

Error Code VALUE

Description

For a complete list of the error codes, see Upgrade License Error Codes.

287

288

Chapter 7: Upgrade License API

7.22. VLSucgGenerateLicense 7.22.1. Syntax int VLSucgGenerateLicense ( VLSucg_HANDLE ucodeT

Argument

VLSucg_HANDLE *ucodeP,

char

*upgrade_code,

char

**result );

iHandle

Description Instance handle for this library.

ucodeP

The pointer to ucodeT struct.

upgrade_code

Upgrade code of base license

result

Address of pointer pointing to generated license string.

7.22.2. Description Generates the upgrade license string for the given ucodeT struct. VLSucgGenerateLicense should be called after all the VLSucgSet functions are called. Memory allocation and free for ucodeT are the responsibilities of the caller of the API. Memory allocation for the license string shall be taken care by the API. VLSucgGenerateLicense decodes the upgrade_code and extract the information of base license. It performs the following validation before generating an upgrade license: n

n

Feature Name, Version and vendor code of base license is matched with the base feature name, base version and vendor code of ucodeT. The capacity upgrade is allowed only if the base license is a Non-pooled capacity license.

7.22.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLSucg_INVALID_INPUT

Description If the ucodeP is ed as NULL.

VLSucg_INVALID_VENDOR_ If vendor identification is illegal. CODE VLSucg_VENDOR_ ENCRYP- If vendor-customized encryption fails. TION_FAIL VLSucg_MALLOC_FAILURE

If error occur while allocating internal memory for ucodeT struct.

VLSucg_LICMETER_ EXCEP- If error occur while accessing the dongle. TION VLSucg_NO_NETWORK_

If not authorized to generate network licenses.

7.22. VLSucgGenerateLicense

Error Code AUTHORIZATION

Description

VLSucg_LICMETER_ COUNTER_TOOLOW

If license meter count is less than the expected decrement count.

VLSucg_NO_CAPACITY_ AUTHORIZATION

If not authorized to generate capacity licenses.

VLSucg_NO_UPGRADE_ AUTHORIZATION

If not authorized to generate upgrade licenses.

VLSucg_INTERNAL_ERROR

If any internal error occur while generating the license string.

VLSucg_INVALID_BASE_ LIC_INFO

The information-feature name, version vendor code provided for base license is incorrect.

VLSucg_CAPACITY_UPD_ NOT_ALLOWED

Capacity upgrade is not allowed, as the base lic is a non-capacity license.

VLSucg_INVALID_ UPGRADE_CODE

The specified upgrade code is invalid.

VLSucg_LICMETER_NOT_ ED

Your Sentinel RMS Development Kit License Meter is not ed.

For a complete list of the error codes, see Upgrade License Error Codes.

289

290

Chapter 7: Upgrade License API

7.23. VLSucgGetLicenseMeterUnits 7.23.1. Syntax int VLSucgGetLicenseMeterUnits ( VLSucg_HANDLE long

*initialUnitsP,

long

*unitsLeftP,

int

Argument

iHandle,

ucodegen_version );

iHandle

Description Instance handle for this library.

initialUnitsP

provided license string to be decoded.

unitsLeftP

allocated buffer to receive decoded license string.

ucodegen_version

Version of the ucodegen library

7.23.2. Description Returns the number of license generation units available in the attached dongle.

7.23.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code Description VLSucg_INVALID_VENDOR_CODE If vendor identification is illegal. VLSucg_VENDOR_ENCRYPTION_ If vendor-customized encryption fails FAIL VLSucg_MALLOC_FAILURE

If error occur while allocating internal memory for ucodeT struct

VLSucg_FAIL

On Failure.

VLSucg_LICMETER_NOT_ ED

Your Sentinel RMS Development Kit License Meter is not ed.

For a complete list of the error codes, see Upgrade License Error Codes.

7.24. VLSgenerateUpgradeLockCode

291

7.24. VLSgenerateUpgradeLockCode 7.24.1. Syntax int VLSgenerateUpgradeLockCode (

Argument lic_string

unsigned char

*lic_string,

unsigned char

*upgrade_lock_code,

unsigned long

*buffer_size );

Description Base license string.

upgrade_lock_ Buffer containing the generated upgrade lock code. The caller should allocate the memory space. code buffer_size

Size of the allocated buffer. If NULL is ed instead of buffer, then this will return buffer size required for the generated upgrade lock code.

7.24.2. Description VLSgenerateUpgradeLockCode allows the to generate a unique upgrade code for the base license. The upgrade code must be an encrypted string so that it doesn't make any visible sense to the /developer. This API is a part of the generic library (lsutil32.lib).

7.24.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NORESOURCES

Description Unable to allocate memory required to decode the ed license string and to generate upgrade code.

VLS_CALLING_ERROR

If called with invalid arguments.

LS_NO_SUCCESS

If unable to generate upgrade code.

VLS_VENDORIDMISMATCH

If license string with invalid vendor code is ed. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_UPGRADE_NOT_ALLOWED

It shall not generate the Upgrade Code if the base license is found to be a Multi Feature Short Numeric, or Trial or Commuter or Redundant License.

LS_BUFFER_TOO_SMALL

buffer parameter is NULL. Size of upgrade lock code exceeds buffer_size parameter.

For a complete list of the error codes, see Upgrade License Error Codes.

292

Chapter 7: Upgrade License API

The Upgrade License Decode API Given below is a list of the API functions: Function ulcCode

Description Stores information required to decode upgrade lock code.

VLSdecodeUpgrade lockCode

Decodes the upgrade lock code.

VLSucgDecodeLicense

Decodes the encrypted license string generated by upgrade code generator library

7.25. ulcCode Struct

293

7.25. ulcCode Struct typedef struct

{int version_num; char hash_vendor_string[VENDOR_HASH_LENGTH]; int capacity_flag; int standalone_flag; unsigned num_keys; int birth_day; int birth_month; int birth_year; int death_day; int death_month; int death_year; int client_server_lock_mode; unsigned char base_lock_code[BASE_ LOCK_CODE_LENGTH + 1]; char base_feature_name[VLScg_MAX_CODE_COMP_LEN + 1]; char base_feature_version[VLScg_MAX_CODE_COMP_LEN + 1]; unsigned long capacity; } ulcCode; Member version_num

Description Number maintaining the version of the structure

hash_vendor_ string

A numeric value representing the feature and version of the license.

capacity_flag

The value of capacity flag.

standalone_flag

The value of standalone flag.

num_keys birth_day

The number of keys. The starting day of the license.

birth_month

The starting month of the license.

birth_year

The starting year of the license.

death_day

The expiration day of the license.

death_month

The expiration month of the license.

death_year

The expiration year of the license.

client_server_lock_mode

The locking mode

base_lock_code

Base lock code

base_feature_ name base_feature_ version

Base feature name

capacity

Capacity of the license.

Base feature version

294

Chapter 7: Upgrade License API

7.26. VLSdecodeUpgradelockCode 7.26.1. Syntax int VLSdecodeUpgradelockCode ( char

*upgrade_lock_code,

char

*compacted_upd_lock_code,

int ulcCode

Argument upgrade_lock_ code

length, **ulcCodePP );

Description Upgrade lock code to be decoded.

compacted_upd_ lock_code

Upgrade lock code string after removing comment chars and white spaces. This can also be set as null.

length

Length of compacted_upd_lock_code in case it is not null.

ulcCodePP

Pointer to pointer to ulcCode structure.

7.26.2. Description VLSdecodeUpgardelockCode API decodes the upgarde lock code.

7.26.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code LS_NORESOURCES

Description If vendor identification is illegal.

LS_NO_SUCCESS

Failed to decrypt the license

VLS_INTERNAL_ERROR

If error occur while allocating internal memory for ucodeT struct

For a complete list of the error codes, see Upgrade License Error Codes.

7.27. VLSucgDecodeLicense

295

7.27. VLSucgDecodeLicense 7.27.1. Syntax  int VLSucgDecodeLicense ( VLSucg_HANDLE char

*AnyLicenseString,

char

*lic_string,

int ucodeT

Argument

iHandle,

lic_string_length, **ucodePP );

Description Instance handle for this library.

iHandle

AnyLicenseString provided license string to be decoded.

allocated buffer to receive decoded license string.

Lic_string

Lic_string_length Length of decoded license string returned.

Address of pointer to ucodeT struct. Contains input license string.

ucodePP

7.27.2. Description VLSucgDecodeLicense API is contained in lsdcod32.lib. This library needs to be called for using VLSucgDecodeLicense API without the license meter. Decodes the encrypted license string generated by upgrade code generator library. It also converts the license string into ucodePP struct. VLSucgDecodeLicense does not decodes/understand the normal (base) licenses.

7.27.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code Description VLSucg_INVALID_ If vendor identification is illegal. VENDOR_CODE VLSucg_VENDOR_ENCRYPTION_ FAIL

If vendor-customized encryption fails

VLSucg_MALLOC_FAILURE

If error occur while allocating internal memory for ucodeT struct

VLSucg_FAIL

On Failure.

For a complete list of the error codes, see Upgrade License Error Codes.

8 Chapter 8: Utility Functions The utility functions are meant for scheduling and disabling events. The utility functions are only available for UNIX platforms.

Given below is the list of the API functions: Function VLSscheduleEvent

Description Schedules eventhandler to be awakened after so many seconds. It handles only SIGALRM signal.

VLSdisableEvents

Disables the events scheduled. To disable a particular event the event handler function name as the argument. To disable all the events NULL as argument.

VLSeventSleep

Disables the feature for an allotted time.

298

Chapter 8: Utility Functions

8.1. VLSscheduleEvent 8.1.1. Syntax int VLSscheduleEvent ( unsigned long

Argument

seconds,

void

*eventHandler,

long

repeat_event );

seconds

Description Time interval in seconds.

eventHandler

Signal handler.

repeat_event

Number of event repetitions.

8.1.2. Description This function is called for scheduling eventHandler to be awakened after so many seconds. Handles only SIGALRM signal.

8.1.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes.

8.2. VLSdisableEvents

299

8.2. VLSdisableEvents 8.2.1. Syntax int VLSdisableEvents( void

Argument eventHandler

*eventHandler );

Description Signal handler.

8.2.2. Description This function is called for disabling the events scheduled. To disable a particular event, the event handler function name as the argument. To disable all the events, NULL as argument.

8.2.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes.

300

Chapter 8: Utility Functions

8.3. VLSeventSleep 8.3.1. Syntax void VLSeventSleep (unsigned int seconds)); Argument

Description Time in seconds to sleep.

seconds

8.3.2. Description This function is called for disabling the license operations for an allotted time and interferes with the system alarms. VLSeventSleep must be used in conjunction with VLSdisableAutoTimer.

8.3.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes.

9 Chapter 9: Usage Log Functions The usage log functions control and manipulate the usage log file. The following table summarizes the usage log functions: Function VLSchangeUsageLogFileName

Description This API changes the name of the existing usage log file. This change can be done while the file is being used.

VLSgetUsageLogFileName

API determines the name of the existing usage log file.

VLSUsageAuthenticate

Verifies whether the usage log file is tampered or not?

VLSusageFileDecrypt

Decrypts the usage log file in a readable format.

302

Chapter 9: Usage Log Functions

9.1. VLSchangeUsageLogFileName 9.1.1. Syntax int VLSchangeUsageLogFileName(

Argument

char

*hostName,

char

*newFileName);

hostName

Description The host name or IP address of the computer hosting the license server that is using the log file.

newFileName

The new name you want to use for the log file.

9.1.2. Description  This API es message to the license server to change the name of the existing usage log file. This change can be done while the file is being used.

9.1.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes.

9.2. VLSgetUsageLogFileName

303

9.2. VLSgetUsageLogFileName 9.2.1. Syntax int VLSgetUsageLogFileName(

Argument

char

*hostName,

char

*fileName );

hostName

Description The host name or IP address of the computer hosting the license server that is using the log file.

fileName

The name of the existing usage log file is returned in this argument.

9.2.2. Description  Determines the name of the existing usage log file.

9.2.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes.

304

Chapter 9: Usage Log Functions

9.3. VLSUsageAuthenticate 9.3.1. Syntax int VLSUsageAuthenticate ( unsigned char int VLSerrorLine

Argument

*file_name, *len, *Output_Message);

Description The name of the input usage log file.

file_name len

When VLSUsageAuthenticate is called for the first time, the return value of len contains the number of tampered lines in the usage log file While calling this API for the second time, you need to the return (len) value received from the first VLSUsageAuthenticate call and Output_Message to get a detailed description about the tampered lines.

Output_Message

This variable contains detailed description about the tampered lines in usage log file. This parameter is used only after checking that the usage log file has been tampered.

9.3.2. Description  Before calling this API first time for a given log file, it is unknown how many lines of the log file have been tampered. To determine the number of tampered lines, call this API with output_message parameter as NULL (VLSUsageAuthenticate(inFile, &len, NULL)). The return value of this API indicates whether the log file has been tampered or not. Also, the len parameter will be filled with number of lines that have been tampered. Now, if you wish to get a detailed description about the lines that have been tampered, allocate sufficient memory to the output_parameter (len * sizeof(error_Msg) ), and call this API again (VLSUsageAuthenticate(inFile,&len,output_message)). This time, the output_message parameter will be filled with the detailed description of the tampered lines. If sufficient memory is not allocated to the output_message parameter, this API may attempt to write beyond the allocated area, resulting in data corruption or crash. Therefore, you should call this API for the first time with output_message parameter as NULL , to determine the memory requirement (recommended).

9.3.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result

9.3. VLSUsageAuthenticate

Codes. The API allocates (len* sizeof(error_Msg)) memory for the Output_Message pointer. You should free the allocated memory after calling this API.

305

306

Chapter 9: Usage Log Functions

9.4. VLSusageFileDecrypt 9.4.1. Syntax int VLSusageFileDecrypt (

Argument

unsigned char

*file_name,

unsigned char

*Option_field,

unsigned char

*Output_file_name);

file_name

Description The name of the input usage log file.

len

You can specify the following options: n n n n n

-d New-log-file -c CSV-Format-New-log-file -f Feature-Name1, Version: Feature-Name2, Version ...] [-y Start-Year (YYYY) [-m Start-Month(MM) [-a Start-Day(DD)]]] [-Y End-Year(YYYY) [-M End-Month(MM)] [-A End-Day(DD)]]]

Option_field parameter format: -d file_name -f Feature-Name1,Version:Feature-Name2,Version

Output_file_name

Output file name.

9.4.2. Description  This API allows you to read the encrypted input usage log file and generate the corresponding output report in output_file_name.

9.4.3. Returns The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, Licensing Library Error and Result Codes. The API allocates (len* sizeof(error_Msg)) memory for the Output_Message pointer. You should free the allocated memory after calling this API.

10 Chapter 10: License Code Generation API The License Code Generation Application Programming Interface (API) makes it possible to generate license codes to authorize use of an application program. The functions are prototyped in lscgen.h and the implementation is contained in lscgen32.lib. Use of these files enables you to write your own utility program to generate license codes. Such programs must be written to run under Windows 2000/XP/Server 2003/Vista/7/Server 2008.

Programs that do license generation must first allocate an integer handle and a data structure of type codeT. The handle is used with all other License Generation functions, and must be initialized before any of those functions can be called. The codeT data structure is used to arguments back and forth between the program and the different library functions. A typical sequence of operations to generate a license would look like the following: n

n

n

n

n

n

n

Be sure that a handle and a codeT data structure have been allocated. Call VLScgInitialize to initialize the handle. This will ensure that the number of handles has not exceeded the limit, allocate space for internal data structures, and initialize the error list and error count. Call VLScgReset to install default values into the codeT data structure. This must be done before setting the values of any of the fields in the data structure. Obtain input from the that is to be used to define the license code. The order of input is important since some values will depend on others. The order of input refers to the Allow and Set functions of code struct. We suggest you use the Allow function first to check the differential integrity of the field value before using the Set function. Call the appropriate VLScgAllowXXX function for each input to ensure that its value can be properly included into the license code. If the input can be accepted, call the corresponding VLScgSetXXX function. This will lock the codeT structure, install the values, and then unlock the structure. If the set function causes an error, call VLScgPrintErrorXXX function to copy the error structure.

n

After all inputs have been received, call VLScgGenerateLicense to create the license string.

n

Call VLScgCleanup to release the handle.

308

Chapter 10:  License Code Generation API

10.1. The License Code Generation Functions Available function calls fall into these categories: n

CodeT Struct

n

Basic functions

n

Functions which retrieve or print errors

n

Functions which set flags and data fields of codeT struct

n

License generation function(s)

n

License meter related functions

n

License Hash and Decode Functions

n

License revocation functions

An example is shown below: ................... #include <stdio.h> /* For scanf(), sprintf() etc.*/ #include "lscgen.h" /* For the code generator API.*/ /* The fixed feature name of licenses generated by this example program. */ #define VLS_CGENXMPL_FEATURE_NAME

"CGENXMPL"

/*Mnemonic used for setting code structure for long codes.*/ #define VLS_LONG_CODE_TYPE_STR

"1"

/* Utility function to print code generator API errors to stderr.It also calls the code generator library cleanup function on * the handle if necessary. */ static int VLS PrintErrors (VLScg_HANDLE *iHandle, int retCode) { if (*iHandle != VLScg_INVALID_HANDLE) { (void) VLScgPrintError(*iHandle, stderr); (void) VLScgCleanup(iHandle); } return retCode; } /* VLSPrintErrors() */ /* A simple example to illustrate the use of the code generation API to generate license strings. This is a command line utility that generates license codes for a fixed feature name, "CGENXMPL". It prompts the for the expiration date and then calls the code generator API functions to generate an appropriate license for CGENXMPL. To build this example, compile and then link with the appropriate code generator API library - lscgen32.lib */ int main () {

10.1. The License Code Generation Functions

/* Code generator library handle. */ VLScg_HANDLE iHandle; /* Code generator APIs license code structure. */ codeT licCode; /* Expiration date information: acquired from . */ int expMonthInt, expDayInt, expYearInt; /* String versions of above for calling code generator API functions.*/ char expMonth[10], expDay[10], expYear[10]; /* For license string to be returned by code generator API.*/ char *licStr = (char *) NULL; /* For return codes from code generator API functions. */ int retCode; /* Initialize the code generator library. */ if((retCode=VLScgInitialize(&iHandle))!= VLScg_SUCCESS){ (void) VLSPrintErrors(&iHandle, retCode); fprintf(stderr, "\nERROR: Code generator library initialization failed.\n"); return retCode; } /* if (!VLScgInitialize()) */ /* Initialize the license code structure. */ if((retCode=VLScgReset(iHandle,&licCode))!= VLScg_SUCCESS) return VLSPrintErrors(&iHandle, retCode); /* Specify that we want to generate a long code. */ if ((retCode = VLScgSetCodeLength(iHandle, &licCode, VLS_LONG_CODE_TYPE_STR)) != VLScg_SUCCESS) return VLSPrintErrors(&iHandle, retCode); /* Set the feature name. */ if (VLScgAllowFeatureName(iHandle, &licCode) == 0) return VLSPrintErrors(&iHandle, VLScg_FAIL); if ((retCode = VLScgSetFeatureName(iHandle, &licCode, VLS_CGENXMPL_FEATURE_NAME)) != VLScg_SUCCESS) return VLSPrintErrors(&iHandle, retCode); /* * Prompt for and acquire the expiration date from the .*/ printf("License Expiration Month [1-12] : "); scanf("%d", &expMonthInt); printf("License Expiration Day [1-31] : "); scanf("%d", &expDayInt); printf("License Expiration Year : "); scanf("%d", &expYearInt); /* Convert expiration date information to strings. */ sprintf(expMonth,

"%d", expMonthInt);

309

310

Chapter 10:  License Code Generation API

sprintf(expDay, sprintf(expYear,

"%d", expDayInt); "%d", expYearInt);

/* Set the expiration date. */ if (VLScgAllowLicExpiration(iHandle, &licCode) == 0) return VLSPrintErrors(&iHandle, VLScg_FAIL); if (((retCode = VLScgSetLicExpirationMonth(iHandle, &licCode,expMonth)) != VLScg_SUCCESS) || ((retCode = VLScgSetLicExpirationDay(iHandle, &licCode,expDay)) != VLScg_SUCCESS) || ((retCode = VLScgSetLicExpirationYear(iHandle, &licCode,expYear)) != VLScg_SUCCESS)) return VLSPrintErrors(&iHandle, retCode); /* Generate the license: memory for license string is allocated by library. */ if ((retCode = VLScgGenerateLicense(iHandle, &licCode, &licStr)) != VLScg_SUCCESS) return VLSPrintErrors(&iHandle, retCode); /* Print out the license string. */ (void) fprintf(stdout, "%s\n", licStr); /* Free the license string, which was allocated by VLScgGenerateLicense() */ free(licStr); /* Terminate use of code generation library cleanly. */ (void) VLScgCleanup(&iHandle); return 0; } /* main() */

10.2. CodeT Struct

311

10.2. CodeT Struct 10.2.1. Description Holds the licensing information that is set using VLScgSetXXXX APIs and es the same to VLScgGenerateLicense API to generate the corresponding license string. Contains the decoded information from the license string as returned by VLScgDecodeLicense API.

10.2.2. Syntax typedef struct { /* List of flags to be set by external callers: */ int code_type ; int additive ; int client_server_lock_mode; int holding_crit ; int sharing_crit int server_locking_crit1[VLScg_MAX_NUM_SERVERS]; int server_locking_crit2[VLScg_MAX_NUM_SERVERS]; int client_locking_crit[VLScg_MAX_NUM_NL_CLIENTS]; int standalone_flag; int out_lic_type; int clock_tamper_flag; /* List of data fields to be set by external callers:*/ char feature_name [VLScg_MAX_CODE_COMP_LEN+1]; char feature_version [VLScg_MAX_CODE_COMP_LEN+1]; int birth_day ; int birth_month ; int birth_year ; int death_day ; int death_month ; int death_year ; int num_servers ; char server_lock_info1 [VLScg_MAX_NUM_SERVERS] [VLScg_MAX_SERVER_ LOCK_INFO_LEN+1]; char server_lock_info2 [VLScg_MAX_NUM_SERVERS] [VLScg_MAX_SERVER_ LOCK_INFO_LEN+1]; char nl_client_lock_info[VLScg_MAX_NUM_NL_CLIENTS] [VLScg_MAX_NL_ CLIENT_INFO_LEN+1]; unsigned num_keys[VLScg_MAX_NUM_FEATURES]; unsigned soft_limit ; unsigned keys_per_node [VLScg_MAX_NUM_NL_CLIENTS]; int num_subnets ; char site_lic_info [VLScg_MAX_NUM_SUBNETS] [VLScg_MAX_SUBNET_ INFO_LEN+1]; unsigned share_limit;

312

Chapter 10:  License Code Generation API

int key_life_units ; unsigned long key_lifetime ; int key_hold_units ; unsigned long key_holdtime ; int num_secrets ; char secrets [VLScg_MAX_NUM_SECRETS] [VLScg_MAX_SECRET_LEN+1]; char vendor_info [VLScg_MAX_VENINFOLEN+1]; /* New additions */ int licType ; int trialDaysCount; int use_auth_code; int numeric_type; /* for codegen_version >= 7 */ time_t conversion_time; int isRedundant; int majority_rule; int isCommuter; int commuter_max_checkout_days; int log_encrypt_level; int elan_key_flag; /* Fields for internal use, or unused */ int vendor_code ; int version_num ; int licensing_crit ; unsigned long meter_value ; int num_features; int key_type; /* Fields for capacity licensing */ int capacity_flag; int capacity_units; unsigned long capacity; /* Fields for grace licensing */ int grace_period_flag; int grace_period_calendar_days; int grace_period_elapsed_hours; /* Fields for overdraft licensing */ int overdraft_flag; int overdraft_hours; int overdraft_s; int overdraft_s_isPercent; /* Fields for commuter,repository, and grace licensing */ int local_request_lockcrit_flag;

10.2. CodeT Struct

313

int local_request_lockcrit_required; int local_request_lockcrit_float; int local_request_lockcrit_min_num; /* Fields for usage hours based trial licensing */ int trial_elapsed_hours; /* Fields for including public vendor information */ char plain_vendor_info[VLScg_MAX_VENINFOLEN+1]; vmDetectionFlagT vm_detection; long structSz; } codeT; Member code_type

Description Pointer to CodeT struct

additive

Can be set to: n n n

client_server_lock_mode

Locking mode can be: n n n n

holding_crit

VLScg_FLOATING- Server is locked VLScg_BOTH_NODE_LOCKED - Clients and server are locked VLScg_DEMO_MODE - Demo license (no locking) VLScg_CLIENT_NODE_LOCKED - Only clients are locked

Criterion for held licenses can be: n n n

sharing_crit

VLScg_ADDITIVE- Additive license VLScg_EXCLUSIVE - Exclusive license VLScg_AGGREGATE_LICENSE - Aggregate license

VLScg_HOLD_NONE VLScg_HOLD_VENDOR VLScg_HOLD_CODE

Criterion for sharing of non-capacity licenses, can be: n n n n n

VLScg_NO_SHARING VLScg__SHARING VLScg_HOSTNAME_SHARING VLScg_XDISPLAY_SHARING VLScg_VENDOR_SHARING

Criterion for sharing of capacity licenses, can be: n n n n n

VLScg_NO_TEAM VLScg__BASED_TEAM VLScg_HOSTNAME_BASED_TEAM VLScg_XDISPLAY_BASED_TEAM VLScg_VENDOR_BASED_TEAM

314

Chapter 10:  License Code Generation API

Member server_locking_crit1 server_locking_crit2

Description n Server lock selector/criterion (group 1) n Allows 2 hostid's per server n n

client_locking_crit

n n

Server lock selector/criterion (group 2) Allow 2 hostid's per server Client lock selector/criterion Allow 1 hostid per client

standalone_flag

Specifies if the license is stand-alone, network, or repository.

out_lic_type

Specifies if the license is n n n

Encrypted Expanded readable Concise readable

clock_tamper_flag

If set then the license does not allow time tampering

feature_name

Name of the feature

feature_version

Version of the feature

birth_day

day of the month (1-31)

birth_month

1 - 12 or JAN - DEC

birth_year

2003 to...; minimum birth year can be 2003.

death_day

max day of the month (1-31)

death_month

1 - 12 or JAN - DEC

death_year

2003 to... ; minimum death year can be 2003.

num_servers

Identifies the number of license servers. 1serverallowed for single server application and maximum 11 servers allowed for redundant server application.

server_lock_info1

Stores information in ASCII.

server_lock_info2

Stores information in ASCII.

num_nl_clients

Number of node-locked clients, maximum of 7 node-locked clients allowed.

nl_client_lock_info

Stores information in ASCII.

num_keys

Number of concurrent keys.

soft_limit keys_per_node

0 to num_keys. Number of keys alloted to each client for a network mode license.

num_subnets

The number of subnet specifications provided for the site.

site_lic_info

Stores information in binary.

share_limit/team-limit

n n

Number of clients/s who can share a single license key. Used as team limit in case of capacity license.

key_life_units

Determines lifetime least count.

long key_lifetime

Absolute value in minutes.

key_hold_units

Flag which determines holdtime least count.

key_holdtime

Absolute value in minutes .

num_secrets

Number of Challenge response secrets.

10.2. CodeT Struct

Member secrets

315

Description Stores information in ASCII.

vendor_info

The vendor-defined information string. The maximum length of the string can be up to 2000 characters.

licType

Trial or Normal license type.

trialDaysCount

Life of trial license.

use_auth_code

For multi-keys or short numeric codes

numeric_type

For short numeric codes n n n n

0 - non-numeric 1 - general short numeric 2 - general numeric 10 and above specific type for codegen_version=7

isRedundant

Validates if the license is actually redundant.

majority_rule

Checks whether majority rule is on or off.

isCommuter

Commuter licenses.

commuter_max_checkout_ days

The maximum number of days a commuter license can be checked out for. It can be: n n n

A value between 1 to 1827 days for long licenses. A value between 1 to 60 days for short licenses. Zero for unlimited check-out (up to the license expiration)

log_encrypt_level

For encryption level in the license code.

vendor_code

Vendor identification code.

version_num

The license version number, like version 11, 12, 13, and 14 licenses, in mapping with the RMS SDK versions.

meter_value

Fields for multi_key for short numeric codegen version >=2.

num_features

Number of features in case of multi key.

key_type

Single key/Multi key for short numeric only.

capacity_flag

Specifies if the license is a capacity or non-capacity license. Values can be: n n n

VLScg_CAPACITY_NONE VLScg_CAPACITY_NON_POOLED VLScg_CAPACITY_POOLED

capacity_units

Flag which determines capacity least count.

long capacity

The capacity of this license.

grace_period_flag

A flag that decides whether grace period for a license will be provided or not. It can be any of the following constants: n n

grace_period_calendar_days

VLScg_NO_GRACE_PERIOD - grace period not allowed (default) VLScg_STANDARD_GRACE_PERIOD - grace period allowed

The number of days the grace period will last for. It can be a value between 1 to 180 days. The default value is 2 days.

316

Chapter 10:  License Code Generation API

Member grace_period_elasped_hours

Description The number of hours the grace period will last for. It can be a value between 1 to 1440 hours. The default value is 20 hours.

overdraft_flag

Not ed.

overdraft_hours

Not ed.

overdraft_s

Not ed.

overdraft_s_isPercent

Not ed.

local_request_lockcrit_flag

The flag that sets the local license request locking criteria as: n

n

VLScg_LOCAL_REQUEST_LOCKCRIT_USEDEFAULT - Sets local_ request_lockcrit_required to disk ID (VLS_LOCK_DISK_ID) local_ request_lockcrit_float to 0, and local_request_lockcrit_min_num to 1. This is the default setting. VLS_LOCAL_REQUEST_LOCKCRIT_DEFINED - Sets local_request_lockcrit_required to a -defined value.

local_request_lockcrit_required The necessary number of locking criteria that must be met for making the licenses available to a local client. local_request_lockcrit_float

The desired number of locking criteria that must be met for making the licenses available to a local client.

local_request_lockcrit_min_ num

The minimum number of locking criteria that must be met for making the licenses available to a local client. For example, the “required” locking criteria can be disk ID, the “floating” criteria can be ethernet card and CID key, and the “minimum” criteria can be any two of the above.

trial_elapsed_hours

The trial hours specified for a trial license.

plain_vendor_info

The public vendor information. The maximum length of the string can be up to 395 characters.

vm_detection

The flag to allow or deny the grant of a license token in case the license server is found running on a virtual machine. It can have the following values: n n

structSz

VLScg_VM_DISALLOWED_STRING - Denies the grant of a license. VLScg_VM_ALLOWED_STRING - Allows the grant of a license.

The CodeT structure size to identify its version in libraries beyond 8.4.0. WARN I N G

Th is m e m b e r is ad d e d in th e 8 .4 .0 r e le ase . Ho w e v e r , to e nsur e c om patibility in the subse que nt r e le ase s, you m ust fill u p th is m e m b e r w ith th e size o f Co d e T. E lse , u p gr ad e to the lic e nse ge ne r ation DL L w ill fail.

About Reserved Characters and Strings

317

About Reserved Characters and Strings Please note the following guidelines regarding reserved characters and strings: n

! and $ are reserved characters and cannot be used in feature name, feature version, private vendor information, public vendor information and secret text.

n

Space is not an acceptable character in the vendor information (both public and private).

n

011 and oil are reserved strings and cannot be used in feature name and feature version.

n

n

NiL and Ni are reserved strings and cannot be used in feature name, feature version, private vendor information and public vendor information. # is a comment character and all text appearing after this will be ignored in vendor information (both public and private).

318

Chapter 10:  License Code Generation API

The Basic Functions Given below is a list of the API functions: Function VLScgInitialize

Description Initializes the handle.

VLScgCleanup

Destroys the created handle.

VLScgReset

Resets the structure with default values.

VLScgGetLibInfo Returns information about the license generator library currently being used in the structure pointed to by pStruct .

10.3. VLScgInitialize

319

10.3. VLScgInitialize 10.3.1. Syntax int VLScgInitialize ( VLScg_HANDLE *iHandleP );

Argument iHandleP

Description The pointer to the instance handle for this library. Provides access to the internal data structure.

10.3.2. Description Required library initialization call. Every API call requires a valid handle. This function allocates resources required for generating licenses. This function must be called before using any other VLScgXXX function.

10.3.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_MAX_LIMIT_CROSSED

Description No more handles left.

VLScg_BAD_HANDLE

Call VLScgCleanup to free the resources associated with invalid handle.

VLScg_LICMETER_NOT_ ED

Your Sentinel RMS license meter is not ed.

For a complete list of the error codes, see License Generation Error Codes. 

10.3.4. See Also n

VLScgCleanup

320

Chapter 10:  License Code Generation API

10.4. VLScgCleanup 10.4.1. Syntax int VLScgCleanup ( VLScg_HANDLE *iHandleP );

Argument iHandleP

Description The pointer to the instance handle for this library.

10.4.2. Description This function destroys the handle and its associated resources created by VLScgInitialize.

10.4.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes. 

10.5. VLScgReset

321

10.5. VLScgReset 10.5.1. Syntax int VLScgReset ( VLScg_HANDLE *iHandleP, codeT *codeP );

Argument iHandleP

Description The instance handle for this library.

codeP

Name of the structure.

10.5.2. Description This function resets the codeP structure by filling in default values. It must be called before calling VLScgSetXXX functions.

10.5.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes

322

Chapter 10:  License Code Generation API

10.6. VLScgGetLibInfo Returns information about the license generator library currently being used in the structure pointed to by pStruct .

10.6.1. Syntax int

VLScgGetLibInfo (VLScg_LIBVERSION *pStruct )

long

structSz;

char

szVersion [LIBINFOLEN];

typedef struct {

} LS_CGLIBVERSION

Member Description structSz The must allocate a buffer prior to calling this API. It must be filled by the . Else, VLScg_INVALID_INPUT is returned. szVersion The version of the license generator library.

10.6.2. Description Space for pStruct must be allocated by the caller.

10.6.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Codes

VLScg_INVALID_INPUT

Description Input values for the IN/OUT structure parameter are incorrect.

For a complete list of the error codes, see Licensing Library Error and Result Codes.

Functions Retrieving Errors

323

Functions Retrieving Errors When errors are encountered during execution of License Generation functions, they are queued to the handle that controls access to the library in use. These errors may be printed immediately, or allowed to accumulate and flushed at a later time. Given below is a list of the API functions: Function VLScgGetNumErrors

Description Retrieves number of error messages recorded.

VLScgGetErrorLength

Retrieves the length of a error message.

VLScgGetErrorMessage Retrieves the earliest error from the handle. VLScgPrintError VLScgPrintErrorExt

Writes the error struct to a file.

324

Chapter 10:  License Code Generation API

10.7. VLScgGetNumErrors 10.7.1. Syntax int VLScgGetNumErrors ( VLScg_HANDLE iHandleP, int *numMsgsP );

Argument iHandleP

Description The pointer to the instance handle for this library.

numMsgsP (OUT) The number of messages queued to the handle.

10.7.2. Description This function retrieves the number of messages queued to the handle and returns it in numMsgsP. You can have only one int memory for this API. Hence the code would be: int errNo; VLScg_HANDLE handle; VLScgGetNumErrors(handle,&errNo);

10.7.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_NO_RESOURCES

Description If no resources are available.

VLScg_FAIL

If operation failed.

For a complete list of the error codes, see License Generation Error Codes.

10.8. VLScgGetErrorLength

325

10.8. VLScgGetErrorLength 10.8.1. Syntax int VLScgGetErrorLength ( VLScg_HANDLE

Argument

iHandle,

int

msgNum,

int

errLenP );

iHandle

Description The instance handle for this library.

msgNum

The number of the message whose length is to be queried.

errLenP

The length of the message identified by msgNum.

10.8.2. Description This function retrieves the length of message # msgNum recorded in the handle. It includes the space required for NULL termination.

10.8.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_NO_RESOURCES

Description If no resources are available.

VLScg_FAIL

If operation failed.

For a complete list of the error codes, see License Generation Error Codes.

326

Chapter 10:  License Code Generation API

10.9. VLScgGetErrorMessage 10.9.1. Syntax int VLScgGetErrorMessage(

Argument

VLScg_HANDLE

iHandle,

char

*msgBuf,

int

bufLen );

iHandle

Description The instance handle for this library.

msgBuf (OUT)

A allocated buffer into which the reference message will be copied.

bufLen

The byte length of the message copied into msgBuf.

10.9.2. Description This function retrieves the oldest error queued to the handle, and copies a maximum of bufLen bytes to msgBuf as a null-terminated string. msgBuf is a allocated buffer and must be bufLen bytes in length. Upon successful completion of this function, the message retrieved will have been removed from the queue.

10.9.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_NO_RESOURCES

Description If no resources are available.

VLScg_FAIL

If operation failed.

For a complete list of the error codes, see License Generation Error Codes.

10.10. VLScgPrintError

327

10.10. VLScgPrintError 10.10.1. Syntax int VLScgPrintError (

Argument

VLScg_HANDLE

iHandle,

FILE

*file );

iHandle

Description The instance handle for this library.

file

A pointer to a file.

10.10.2. Description This function writes the accumulated errors to the specified file.

10.10.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLScg_NO_RESOURCES

Description If no resources are available.

VLScg_FAIL

If operation failed.

For a complete list of the error codes, see License Generation Error Codes.

328

Chapter 10:  License Code Generation API

10.11. VLScgPrintErrorExt 10.11.1. Syntax int VLScgPrintErrorExt ( VLScg_HANDLE char

Argument

iHandle, *fileName );

iHandle

Description The instance handle for this library.

fileName

A pointer to a filename. To write data into the: n n

standard output (stdout) - specify “stdout” as the filename. standard error (stderr) - specify “stderr” as the filename.

10.11.2. Description This function writes the accumulated errors to the specified file or standard error or standard output streams.

10.11.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLScg_NO_RESOURCES

Description If no resources are available.

VLScg_FAIL

If operation failed.

For a complete list of the error codes, see License Generation Error Codes.

The Functions for Setting the Fields in CodeT Struct

329

The Functions for Setting the Fields in CodeT Struct The following table summarizes the functions used to set flags and data fields of the codeT struct. The sequence of input is very important for the VLScgAllow functions and VLScgSet functions. You need to use the Allow function first to check the differential integrity and syntax of the field value, before using the Set function. The Set function will put it in the correct structure and format.

Function

Description

VLScgSetCodeLength

Sets the license code length.

VLScgAllowFeatureName VLScgSetFeatureName

Sets the name of the` feature to be licensed.

VLScgAllowFeatureVersion VLScgSetFeatureVersion

Sets the version number to be licensed.

VLScgAllowLicenseType VLScgSetLicenseType

Controls the license type.

VLScgAllowTrialLicFeature VLScgSetTrialDaysCount

Sets the number of trial days.

VLScgAllowAdditive VLScgAllowAggregateLicense VLScgSetAdditive

Sets the license to additive, exclusive, or aggregate.

VLScgAllowKeyLifeUnits VLScgSetKeyLifetimeUnits

Sets unit of time used to specify time between license renewals.

VLScgAllowStandAloneFlag VLScgAllowNetworkFlag VLScgAllowRepositoryFlag VLScgSetStandAloneFlag

Sets whether the license will be stand-alone, network, or repository.

VLScgAllowLogEncryptLevel VLScgSetLogEncryptLevel

Controls the network license encryption level for the license server’s usage log file.

VLScgAllowSharedLic/ VLScgAllowTeamCriteria VLScgSetSharedLicType/ VLScgSetTeamCriteria

Enables shared licenses and sets sharing criteria for non-capacity license. Enables team licenses and sets team criteria for capacity license.

VLScgAllowShareLimit/ VLScgAllowTeamLimit VLScgSetShareLimit/ VLScgSetTeamLimit

Sets the number of s that can share a noncapacity license. Sets the number of team that can share a token in case of capacity license.

VLScgAllowCommuterLicense VLScgSetCommuterLicense

Enables commuter licenses to be checked out.

VLScgAllowNumKeys VLScgSetNumKeys

Sets the number of concurrent licenses allowed.

330

Chapter 10:  License Code Generation API

Function

Description

VLScgAllowLockModeQuery VLScgSetClientServerLockMode

Sets locking mode for the license server computer. Installs client server lock mode in codeP.

VLScgAllowRedundantFlag VLScgSetRedundantFlag

Controls whether the license will be used with redundant license servers.

VLScgAllowMajorityRuleFlag VLScgSetMajorityRuleFlag

Controls whether the majority of redundant license servers must be running.

VLScgAllowMultipleServerInfoVLScgSetNumServers Fields for information on various license servers. VLScgAllowServerLockInfo VLScgSetServerLockInfo1

Sets license server primary locking code. Installs license server lock code in primary lock.

VLScgSetServerLock Mechanism1

Sets license server primary fingerprint criteria. Installs license server's fingerprint criteria in primary lock.

VLScgSetServerLock Mechanism2

Sets license server secondary fingerprint criteria. Installs license server's fingerprint criteria in secondary lock.

VLScgSetServerLockInfo2

Sets license server secondary locking code. Installs server lock code in secondary lock.

VLScgAllowLockMechanism VLScgSetClientLockMechanism

Sets client’s fingerprint criteria.

VLScgAllowClientLockInfo VLScgSetClientLockInfo

Sets the client locking code.

VLScgSetNumClients

Sets the number of client locking codes to be specified.

VLScgAllowClockTamperFlag VLScgSetClockTamperFlag

Controls action on detection of clock being set back on the machine.

VLScgAllowOutLicType VLScgSetOutLicType

Sets the license output format.

VLScgSetLicType

Sets the license type.

VLScgAllowHeldLic VLScgSetHoldingCrit

Enables/disables license hold time and determines where that hold time is specified.

VLScgAllowCodegenVersion VLScgSetCodegenVersion

Sets the version of license codes to generate. Checks if the current license code setting allows multiple features.

VLScgAllowMultiKey VLScgSetKeyType

Controls whether a license will be single or multifeature.

VLScgAllowSecrets VLScgSetSecrets VLScgSetNumSecrets

Sets the value of the specified challenge-response secrets. Sets the total number of secrets for the challengeresponse.

VLScgAllowVendorInfo VLScgSetVendorInfo

Sets vendor-defined information in the license.

The Functions for Setting the Fields in CodeT Struct

331

Function

Description

VLScgAllowKeysPerNode VLScgSetKeysPerNode

Sets the number of license tokens per node for the specified number of clients.

VLScgAllowSiteLic VLScgSetSiteLicInfo VLScgSetNumSubnets

Sets address of subnets licensed application will be restricted to. Sets the number of subnets the licensed application is restricted to.

VLScgAllowMultipleFeature VLScgSetNumFeatures

Sets the number of features.

VLScgAllowSoftLimit VLScgSetSoftLimit

Sets soft limit number.

VLScgAllowKeyHoldUnits VLScgSetKeyHoldtimeUnits

Sets units of time to be used to specify license hold time.

VLScgAllowKeyLifetime VLScgSetKeyLifetime

Sets time between license renewals.

VLScgAllowKeyHoldtime VLScgSetKeyHoldtime

Sets the time a license will be held.

VLScgAllowLicBirth VLScgSetLicBirthMonth VLScgSetLicBirthDay VLScgSetLicBirthYear

Sets the month of the license start date (the month should be specified in the range of 0-11). Sets the day of the license start date. Sets the year of the license start date.

VLScgAllowLicExpiration VLScgSetLicExpirationMonth VLScgSetLicExpirationDay VLScgSetLicExpirationYear

Sets month license expires.The months should be specified in the range of 0-11. Sets day month the license expires. Sets the year the license expires.

VLScgSetNumericType

Sets the value of numeric type.

VLScgSetLoadSWLicFile

Sets and loads the software license file (lscgen.lic).

VLScgAllowGracePeriodFlag VLScgSetGracePeriodFlag VLScgAllowGracePeriod VLScgSetGracePeriodDays VLScgSetGracePeriodHours

Set the grace period for the commuter license.

VLScgAllowVmDetection VLScgSetVmDetection

Sets the action on detection of a virtual machine—whether to allow\deny grant of a license token.

332

Chapter 10:  License Code Generation API

10.12. VLScgSetCodeLength 10.12.1. Syntax int VLScgSetCodeLength ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Flag values are used to set the code_type member of codeT struct. Legal values are: n n n

VLScg_SHORT_CODE_STRING = “0” VLScg_LONG_CODE_STRING = “1” VLScg_SHORT_NUMERIC_CODE = “2”

10.12.2. Description Sets the license code length to short or long. License codes are 10 characters or longer uppercase alphanumeric or all-numeric strings. The code generator will generate long, short or short, numeric license codes. n

n

n

Short codes contain less information than the long code and cannot certain licensing option. However, they have the advantage of being easier to generate and easier to communicate to end s. Long codes contain as many characters as needed. Short, numeric codes generate numeric strings only and requires minimal information from the . This code contains the least information.

10.12.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INPUT

Description If either codeP or flag are NULL.

VLScg_INVALID_INT_TYPE

Value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_SHORT_CODE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_LONG_CODE_STRING. For a complete list of the error codes, see License Generation Error Codes.

10.13. VLScgAllowFeatureName

333

10.13. VLScgAllowFeatureName 10.13.1. Syntax int VLScgAllowFeatureName ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.13.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

334

Chapter 10:  License Code Generation API

10.14. VLScgSetFeatureName 10.14.1. Syntax  int VLScgSetFeatureName ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Any printable ASCII text. Maximum of 24 and 11 characters for long and short licenses, respectively. The Basic Functions

10.14.2. Description A feature name can represent a single executable file, multiple executable files, or a portion (a function) of an executable file. A feature name may be a maximum of 11 ASCII characters for short license codes and a maximum of 24 for long license codes and two for short, numeric license codes and multi-feature license codes. All applications must have a name by which they will be identified.

10.14.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_NO_FEATURE_NAME

Description If the name is NULL.

VLScg_RESERV_STR_ERROR

If the string is a reserved string.

VLScg_INVALID_CHARS

If the string characters are not printable.

VLScg_EXCEEDS_MAX_VALUE Returned if the length of string ed exceeds the maximum length of 24. For a complete list of the error codes, see License Generation Error Codes.

10.15. VLScgAllowFeatureVersion

335

10.15. VLScgAllowFeatureVersion 10.15.1. Syntax int VLScgAllowFeatureVersion ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.15.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

336

Chapter 10:  License Code Generation API

10.16. VLScgSetFeatureVersion 10.16.1. Syntax  int VLScgSetFeatureVersion ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Any printable ASCII text. Maximum of 11 characters for long licenses. Not ed for short license codes. The Basic Functions

10.16.2. Description Version number is optional. Not ed for short license codes.

10.16.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_RESERV_STR_ ERROR

Description If the string is a reserved string.

VLScg_INVALID_CHARS

If the string characters are not printable.

VLScg_EXCEEDS_ MAX_ VALUE

If string exceeds maximum number of characters. Maximum length of the version is 11 characters.

For a complete list of the error codes, see License Generation Error Codes.

10.17. VLScgAllowLicenseType

337

10.17. VLScgAllowLicenseType 10.17.1. Syntax int VLScgAllowLicenseType ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.17.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

338

Chapter 10:  License Code Generation API

10.18. VLScgSetLicenseType 10.18.1. Syntax int VLScgSetLicenseType ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Flag is used to set the code_type member of codeT struct. The values are: n n

VLScg_NORMAL_LIC_STRING - Non-trial license = “0” VLScg_TRIAL_LIC_STRING - Trial license = “1”

10.18.2. Description Controls the license type for non-trial and trial licenses.

10.18.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_TRIAL_LIC_STRING.

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_NORMAL_LIC_STRING For a complete list of the error codes, see License Generation Error Codes.

10.19. VLScgAllowTrialLicFeature

339

10.19. VLScgAllowTrialLicFeature 10.19.1. Syntax int VLScgAllowTrialLicFeature ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.19.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

340

Chapter 10:  License Code Generation API

10.20. VLScgSetTrialDaysCount 10.20.1. Syntax int VLScgSetTrialDaysCount ( VLScg_HANDLE iHandle, codeT *codeP, char *daysStr );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

daysStr

String representing the number of days to use in a trial period.

10.20.2. Description Sets the number of trial days to the count specified by the daysStr parameter. The count string defines a window of time during which the application can run after the first time the license is requested.

10.20.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

10.21. VLScgAllowTrialHours

341

10.21. VLScgAllowTrialHours Verifies if setting trial elapsed hours is allowed for code type, license type, and license version. (code_ type, licType, and version_num, respectively), specified in the codeT structure. The trial elapsed hours feature is ed only for version 11 (and later) long licenses.

10.21.1. Syntax int VLScgAllowTrialHours ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.21.2. Returns This API returns 1, if the trial elapsed hours is allowed, else it will return 0.

342

Chapter 10:  License Code Generation API

10.22. VLScgSetTrialHours Sets the number of trial elapsed hours in a trial license code. 

10.22.1. Syntax int VLScgSetTrialHours ( VLScg_HANDLE

iHandle,

codeT

*codeP,

char

Argument

*trialHourStr );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

trialHourStr

The number of hours for using the trial license. The minimum and maximum values are defined by the VLScg_MIN_TRIALHOURS_LONGCODE_LIMIT and VLScg_ MAX_TRIALHOURS_LONGCODE_LIMIT, respectively.

10.22.2. Description Sets the number of trial elapsed hours in a trial license code. However, before this API is called, you need to call the VLScgAllowTrialHours API function. Calling the VLScgAllowTrialHours API function ensures that the trial elapsed hours is allowed.

10.22.3. Returns VLScg_SUCCESS is returned if this API is successful, else one of the following error codes is returned: Argument VLScg_INVALID_INPUT

Description Argument specified is not correct, that is, one of the following reasons exist: n n

VLScg_INVALID_TRIALHOURS

codeP is NULL TrialHourStr is NULL.

The trialHourStr argument is invalid.

10.23. VLScgAllowAdditive

343

10.23. VLScgAllowAdditive 10.23.1. Syntax int VLScgAllowAdditive( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.23.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

344

Chapter 10:  License Code Generation API

10.24. VLScgAllowAggregateLicense 10.24.1. Syntax int VLScgAllowAggregate( VLScg_HANDLE iHandle, codeT *codeP ); n

n

Make sure that prior to this API, VLScgSetCodegenVersion API is called with license version as 14 or later. Call VLScgSetAdditive after calling VLScgAllowAggregateLicense to set the combining property of the license.

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.24.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.25. VLScgSetAdditive

345

10.25. VLScgSetAdditive 10.25.1. Syntax int VLScgSetAdditive ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

The value of flag indicates whether the license to be generated is additive/aggregate/exclusive. The legal values are: n n n

VLScg_ADDITIVE = “0” VLScg_EXCLUSIVE = “1” VLScg_AGGREGATE_LICENSE = “2”

10.25.2. Description This function determines how this license will interact with a license already installed for this feature and version. n

n

n

If a license is defined as exclusive, it will override an existing license for the same feature and version. If a license is additive, it appends changes to an existing additive license for the feature and version. If the license is aggregate, multiple license strings for the feature and version can be combined to form an aggregated hard and soft limit, yet the start and expiry dates of the individual licenses strings are maintained in an independent manner.

10.25.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes:

Error Code

Description

VLScg_INVALID_INT_TYPE

If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_AGGREGATE_LICENSE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_ADDITIVE_STRING. For a complete list of the error codes, see License Generation Error Codes.

346

Chapter 10:  License Code Generation API

10.26. VLScgAllowKeyLifetime 10.26.1. Syntax int VLScgAllowKeyLifetime ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.26.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.27. VLScgSetKeyLifetime

347

10.27. VLScgSetKeyLifetime 10.27.1. Syntax int VLScgSetKeyLifetime ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Absolute value in minutes of license lifetime. Maximum depends on lifetime units set by VLScgSetKeyLifetimeUnits.

10.27.2. Description A license must be renewed by the application on a regular schedule or the license will be reclaimed. This function specifies the number of minutes between renewals. Maximum and granularity depends on VLScgSetKeyLifetimeUnits.

10.27.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If information is a non-negative integer.

VLScg_NOT_MULTIPLE

If value is not a correct multiple.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds 3.

VLScg_LESS_THAN_MIN_VALUE If value is less than or equal to 0. For a complete list of the error codes, see License Generation Error Codes.

348

Chapter 10:  License Code Generation API

10.28. VLScgAllowStandAloneFlag 10.28.1. Syntax int VLScgAllowStandAloneFlag ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.28.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.29. VLScgAllowNetworkFlag

349

10.29. VLScgAllowNetworkFlag 10.29.1. Syntax int VLScgAllowNetworkFlag ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.29.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

350

Chapter 10:  License Code Generation API

10.30. VLScgAllowPerpetualFlag Use VLScgAllowRepositoryFlag instead of VLScgAllowPerpetualFlag in implementations beyond RMS SDK v8.5.0.

10.30.1. Syntax int VLScgAllowPerpetualFlag( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.30.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.31. VLScgAllowRepositoryFlag

351

10.31. VLScgAllowRepositoryFlag 10.31.1. Syntax int VLScgAllowRepositoryFlag( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.31.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

352

Chapter 10:  License Code Generation API

10.32. VLScgSetStandAloneFlag 10.32.1. Syntax int VLScgSetStandAloneFlag ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Flag values are used to set the standalone_flag of codeT struct. Legal values are: n n n n

VLScg_NETWORK_STRING VLScg_STANDALONE_STRING VLScg_REPOSITORY_STRING VLScg_PERPETUAL_STRING (use VLScg_REPOSITORY_STRING instead for implementations after v8.5.0)

10.32.2. Description Sets whether license will run in stand-alone, network, or repository mode. Stand-alone and network licenses cannot be used interchangeably.

10.32.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_REPOSITORY_STRING ,

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_NETWORK_STRING. For a complete list of the error codes, see License Generation Error Codes.

10.33. VLScgAllowLogEncryptLevel

353

10.33. VLScgAllowLogEncryptLevel 10.33.1. Syntax int VLScgAllowLogEncryptLevel ( VLScg_HANDLE codeT

iHandle, *codeP );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

10.33.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

354

Chapter 10:  License Code Generation API

10.34. VLScgSetLogEncryptLevel 10.34.1. Syntax int VLScgSetLogEncryptLevel ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Allowed value are: n n n n n

“0” “1” “2” “3” “4”

10.34.2. Description Controls the encryption level to the network licenses for the license server’s usage log file.

10.34.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a decimal number.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAX_ENCRYPTION_LEVEL. VLScg_LESS_THAN_MIN_ VALUE

If value is lower than VLScg_NO_ENCRYPTION.

For a complete list of the error codes, see License Generation Error Codes.

10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria

355

10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria 10.35.1. Syntax In case of non-capacity license: int VLScgAllowSharedLic ( VLScg_HANDLE iHandle, codeT *codeP );

In case of capacity license: int VLScgAllowTeamCriteria ( VLScg_HANDLE iHandle, codeT

Argument

*codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct. We recommend you use VLScgAllowSharedLic for non-capacity license and VLScgAllowTeamCriteria for capacity license.

10.35.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

356

Chapter 10:  License Code Generation API

10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria 10.36.1. Syntax In case of non-capacity license: int VLScgSetSharedLicType ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

In case of capacity license: int VLScgSetTeamCriteria ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

This flag enables shared licenses and specifies the sharing criteria. Legal values are: n n n n n

VLScg_NO_SHARING_STRING = “0” VLScg__SHARING_STRING = “1” VLScg_HOSTNAME_SHARING_STRING = “2” VLScg_XDISPLAY_SHARING_STRING = “3” VLScg_VENDOR_SHARING_STRING = “4” - Vendor defined / customized. Need to customize the client library for this.

10.36.2. Description The concept of shared license is only applicable to network licenses. If sharing is enabled a can use multiple instances of a protected application without consuming more than one license. Call this function enables sharing and also sets which criteria to use to determine eligibility of the to share a license already granted to an existing : name, x-display ID, host name, or vendor-defined. Sharing allows multiple copies of your application to run at the same time without using more than one license.

Tip We r e c om m e nd you use V L Sc gSe tShar e dL ic Type for non-c apac ity lic e nse and V L Sc gSe tTe am Cr ite r ia for c apac ity lic e nse .

10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria

357

10.36.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_VENDOR_SHARING_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_NO_SHARING_STRING. For a complete list of the error codes, see License Generation Error Codes.

358

Chapter 10:  License Code Generation API

10.37. VLScgAllowShareLimit/ VLScgAllowTeamLimit 10.37.1. Syntax In case of non-capacity license: int VLScgAllowShareLimit ( VLScg_HANDLE codeT

iHandle, *codeP );

In case of capacity license: int VLScgAllowTeamLimit ( VLScg_HANDLE

iHandle,

*codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

Tip We recommend you use VLScgAllowShareLimit for non-capacity license and VLScgAllowTeamLimit for capacity license.

10.37.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.38. VLScgSetShareLimit and VLScgSetTeamLimit

359

10.38. VLScgSetShareLimit and VLScgSetTeamLimit 10.38.1. Syntax  In case of non-capacity license: int VLScgSetShareLimit ( VLScg_HANDLE

iHandle,

codeT

*codeP,

char

*decimalNUM );

In case of capacity license: int VLScgSetTeamLimit ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *decimalNUM );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

decimalNUM

Controls the number of s/clients who can share a single license. Use a decimal numeric value setting to control the number of s that can share a license. VLScg_NOLIMIT_STRING for unlimited.

10.38.2. Description If sharing is set, multiple s or a single using multiple instances of your application, can share a license. This function restricts the number of clients who can share a license. The decimalNUM limit forces the issue of a new license, when the sharing limit has been reached for a non-capacity license or when the team limit has been reached for a capacity license.

Tip We r e c om m e nd you use V L Sc gSe tShar e L im it for non-c apac ity lic e nse and V L Sc gSe tTe am L im it for c apac ity lic e nse .

10.38.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum.

VLScg_LESS_THAN_MIN_VALUE

If the value is lower than minimum.

360

Chapter 10:  License Code Generation API

For a complete list of the error codes, see License Generation Error Codes.

10.39. VLScgAllowCommuterLicense

361

10.39. VLScgAllowCommuterLicense 10.39.1. Syntax int VLScgAllowCommuterLicense ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.39.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

362

Chapter 10:  License Code Generation API

10.40. VLScgSetCommuterLicense 10.40.1. Syntax int VLScgSetCommuterLicense ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Valid values are: n n

VLScg_NOT_ISSUE_COMMUTER_CODES_STRING = “0” VLScg_ISSUE_COMMUTER_LICENSE_CODE_STRING = “1”

10.40.2. Description Enables commuter licenses. This function is used to generate license use authorizations for traveling clients. Commuter licensing allows end s to “check out” an authorization from a network served license group and “check it in” when they are done using the application.

10.40.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_ISSUE_COMMUTER_CODES_STRING VLScg_LESS_THAN_MIN_ VALUE

If value is lower than VLScg_NOT_ISSUE_COMMUTER_CODES_ STRING.

For a complete list of the error codes, see License Generation Error Codes.

10.41. VLScgAllowCommuterMaxCheckoutDays

363

10.41. VLScgAllowCommuterMaxCheckoutDays 10.41.1. Syntax int VLScgAllowCommuterMaxCheckoutDays ( VLScg_HANDLE codeT

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

iHandle, *codeP );

10.41.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

364

Chapter 10:  License Code Generation API

10.42. VLScgSetCommuterMaxCheckoutDays 10.42.1.  Syntax int VLScgSetCommuterMaxCheckoutDays ( VLScg_HANDLE codeT char

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

iHandle, *codeP, * dayStr );

daysStr

10.42.2. Description Sets the maximum check-out days allowed for a commuter license.

10.42.3. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.43. VLScgAllowNumKeys

365

10.43. VLScgAllowNumKeys 10.43.1. Syntax int VLScgAllowNumKeys ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.43.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

366

Chapter 10:  License Code Generation API

10.44. VLScgSetNumKeys 10.44.1. Syntax int VLScgSetNumKeys ( VLScg_HANDLE iHandle, codeT *codeP, char *info, int num );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the number of concurrent licenses: should be from 0 to VLScg_NOLIMIT_ STRING for no limit.

num

Should be 0 in case of single feature and from 0 to “no_of_features -1” in case of multi-feature.

10.44.2. Description Can be used to set the hard limit or (the number of concurrent licenses allowed) for both a standalone as well as a network license.

10.44.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE

If value of info exceeds maximum number of license tokens allowed. Maximum value for long codes is 32766 and maximum value for short codes is 254.

VLScg_LESS_THAN_MIN_VALUE

If value of info is less than 0.

For a complete list of the error codes, see License Generation Error Codes.

10.45. VLScgAllowLockModeQuery

367

10.45. VLScgAllowLockModeQuery 10.45.1. Syntax int VLScgAllowLockModeQuery ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.45.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

368

Chapter 10:  License Code Generation API

10.46. VLScgSetClientServerLockMode 10.46.1. Syntax int VLScgSetClientServerLockMode ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

The flag values are: n n

n n

VLScg_FLOATING_STRING - License server is locked = “0” VLScg_BOTH_NODE_LOCKED_STRING - Clients and license server are locked = “1” VLScg_DEMO_MODE_STRING - Trial license (no locking) = “2” VLScg_CLIENT_NODE_LOCKED_STRING - Only clients are locked = “3”

10.46.2. Description  Sets whether license server is locked, clients and license server are both locked, only clients are locked, or neither license server nor clients are locked. Validates the value of flag and installs it in the license code structure.

10.46.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_ VALUE

Description If value is not numeric. If the value of flag exceeds maximum of 3.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than the minimum of 0. For a complete list of the error codes, see License Generation Error Codes.

10.47. VLScgAllowRedundantFlag

369

10.47. VLScgAllowRedundantFlag 10.47.1. Syntax int VLScgAllowRedundantFlag ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.47.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

370

Chapter 10:  License Code Generation API

10.48. VLScgSetRedundantFlag 10.48.1. Syntax int VLScgSetRedundantFlag ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Valid values are: n n

VLScg_NON_REDUNDANT_CODE_STRING - Non-redundant license = “0” VLScg_REDUNDANT_CODE_STRING - Redundant license = “1”

10.48.2. Description Controls whether the license will be used with redundant license servers. Redundancy allows the total number of licenses to remain available to the enterprise even if one or more license servers fail.

10.48.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_REDUNDANT_CODE_STRING. VLScg_LESS_THAN_MIN_ VALUE

If value is less than VLScg_NON_REDUNDANT_CODE_STRING.

For a complete list of the error codes, see License Generation Error Codes.

10.49. VLScgAllowMajorityRuleFlag

371

10.49. VLScgAllowMajorityRuleFlag 10.49.1. Syntax int VLScgAllowMajorityRuleFlag ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.49.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

372

Chapter 10:  License Code Generation API

10.50. VLScgSetMajorityRuleFlag 10.50.1. Syntax int VLScgSetMajorityRuleFlag ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument Description The instance handle for this library. iHandle codeP

The pointer to the codeT struct.

flag

Valid values are: n n

VLScg_MAJORITY_RULE_FOLLOWS_STRING - Sets the majority_rule_flag = “1” VLScg_MAJORITY_RULE_NOT_FOLLOWS_STRING - Unsets the majority_rule_ flag = “0”

10.50.2. Description  Controls whether the majority of redundant license servers must be running. If the number of redundant license servers running is less than half of the number of license servers specified in the license file, then all servers will stop servicing all old and new clients. For example, if 7 redundant license servers are specified, at least 4 of them must be running to satisfy the majority rule.

10.50.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. If value exceeds VLScg_MAJORITY_RULE_FOLLOWS_ STRING

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_MAJORITY_RULE_NOT_FOLLOWS_ STRING. For a complete list of the error codes, see License Generation Error Codes.

10.51. VLScgAllowMultipleServerInfo

373

10.51. VLScgAllowMultipleServerInfo 10.51.1. Syntax int VLScgAllowMultipleServerInfo ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.51.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

374

Chapter 10:  License Code Generation API

10.52. VLScgSetNumServers 10.52.1. Syntax int VLScgSetNumServers ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP

char

*str );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

str

Number of servers

10.52.2. Description This API sets the number of redundant servers. It can be called for long codes only also the number of servers should be odd. This sets the number of servers for redundancy.

10.52.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric If value exceeds the maximum number of license servers. Maximum number of license servers can be 11.

VLScg_LESS_THAN_MIN_VALUE If the value is less than minimum number of license servers that is equal to or less than 0. For a complete list of the error codes, see License Generation Error Codes.

10.53. VLScgAllowServerLockInfo

375

10.53. VLScgAllowServerLockInfo 10.53.1. Syntax int VLScgAllowServerLockInfo ( VLScg_HANDLE codeT

iHandle, *codeP );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

10.53.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

376

Chapter 10:  License Code Generation API

10.54. VLScgSetServerLockInfo1 10.54.1. Syntax int VLScgSetServerLockInfo1 ( VLScg_HANDLE iHandle, codeT *codeP, char *lockCode, int num );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

lockCode

The lock code to be checked and set. It should be a 5 or 16 character hex string for the old and new style locking codes, respectively (optionally preceded by “0x”).

num

Position in server_lock_info1 where, lockCode is stored starting from 0 to num_ servers-1 where num_servers is set using VLScgSetNumServers. server_lock_info1 is an array of 11 elements storing the primary locking codes for 11 servers.

10.54.2. Description Installs the value of lockCode in the code structure field server_lock_info1[num] to set the primary locking code.

10.54.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not in hexadecimal format. If value exceeds the maximum number of license servers. The value set using the API VLScgSetNumServers

VLScg_LESS_THAN_MIN_VALUE If the value is less than minimum number of license servers. For a complete list of the error codes, see License Generation Error Codes.

10.55. VLScgSetServerLockMechanism1

377

10.55. VLScgSetServerLockMechanism1 10.55.1. Syntax int VLScgSetServerLockMechanism1 ( VLScg_HANDLE iHandle, codeT *codeP, char *criterion, int server );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

criterion

The lock code to install. Value should be in hex format.

server

Position in array which is storing the primary locking criteria of the 11 servers. Value 0 to num_servers where num_servers is set using VLScgSetNumServers.

10.55.2. Description This function sets the criteria for the primary license server. Installs a license server’s primary fingerprint criteria in the code structure. A fingerprint is computed by selecting operating characteristics of the host system and forming a mask with bits set corresponding to those characteristics. The different fingerprinting elements are defined in the VLScg_LOCK_ section of lscgen.h, and includes criteria such as ID Prom, IP address, disk ID, etc. A license server can be locked to either of two groups of fingerprints. The second group will be tried if the first licensed fingerprint group fails to match the license server’s fingerprint at the end- site.

10.55.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If criterion is not in hexadecimal format. If number of server is too large. The value set using the API VLScgSetNumServers.

VLScg_LESS_THAN_MIN_VALUE If the number of server is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

378

Chapter 10:  License Code Generation API

10.56. VLScgSetServerLockMechanism2 10.56.1. Syntax int VLScgSetServerLockMechanism2 ( VLScg_HANDLE iHandle, codeT *codeP, char *criterion, int

Argument

server );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

criterion

The lock code to install (in hex).

server

Position in array which is storing the secondary locking criteria of the 11 servers. Its value should also vary from 0 - num_servers where num_servers is set using VLScgSetNumServers.

10.56.2. Description This function sets the criteria for the secondary license server. Installs a license server’s secondary fingerprint criteria in the code structure. A fingerprint is computed by selecting operating characteristics of the host system and forming a mask with bits set corresponding to those characteristics. The different fingerprinting elements are defined in the VLScg_LOCK_ section of lscgen.h, and includes criteria such as ID Prom, IP address, disk ID, etc. A license server can be locked to either of two groups of fingerprints. The second group will be tried if the first licensed fingerprint group fails to match the license server’s fingerprint at the end- site.

10.56.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If criterion is not in hexadecimal format. If number of server is too large. The value set using the API VLScgSetNumServers.

VLScg_LESS_THAN_MIN_VALUE If the number of server is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

10.57. VLScgSetServerLockInfo2

379

10.57. VLScgSetServerLockInfo2 10.57.1. Syntax int VLScgSetServerLockInfo2 ( VLScg_HANDLE iHandle, codeT *codeP, char *lockCode, int num );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

lockCode

The lock code to be checked and set. Lock code should be an 8-character hex string (32-bit numeric locking code), optionally preceded by “0x.”

num

Position in server_lock_info2 where lockCode is stored starting from 0 to num_ servers-1 where num_servers is set using VLScgSetNumServers. server_lock_info2 is an array of 11 elements storing the secondary locking codes for 11 servers.

10.57.2. Description Installs the value of lockCode in the code structure field server_lock_info2[num] to set the secondary locking code.

10.57.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not in hexadecimal format. If value is too large. The value set using the API VLScgSetNumServers.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

380

Chapter 10:  License Code Generation API

10.58. VLScgAllowLockMechanism 10.58.1. Syntax int VLScgAllowLockMechanism ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.58.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.59. VLScgSetClientLockMechanism

381

10.59. VLScgSetClientLockMechanism 10.59.1. Syntax  int VLScgSetClientLockMechanism ( VLScg_HANDLE iHandle, codeT *codeP, char *criterion, int client_num );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

criterion

Mask defining which fields of machineID are to be used for locking. Value should be in hex format.

client_num

client_num is the position in the array storing the locking mechanisms for the clients. The value will vary from 0 to num_nl_clients where num_nl_clients is the number of clients set using VLScgSetNumClients.

10.59.2. Description Installs a client’s fingerprint criteria in the code structure. A fingerprint is computed by selecting operating characteristics of the host system and forming a mask with bits set corresponding to those characteristics. The different fingerprinting elements are defined in the VLScg_LOCK_ section of lscgen.h, and includes criteria such as ID Prom, IP address, disk ID, etc.

10.59.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not in hexadecimal format. If value is too large. The value set using the API VLScgSetNumClients.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

382

Chapter 10:  License Code Generation API

10.60. VLScgAllowClientLockInfo 10.60.1. Syntax int VLScgAllowClientLockInfo ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle codeP

Description The instance handle for this library. The pointer to the codeT struct.

10.60.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.61. VLScgSetClientLockInfo

383

10.61. VLScgSetClientLockInfo 10.61.1. Syntax int VLScgSetClientLockInfo ( VLScg_HANDLE codeT char int

Argument

iHandle, *codeP, *lockCode, num );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

lockCode

This buffer is used to set the lock code information for clients.

num

Number of clients: should be from 0 to maximum number of clients specified -1. num is the position in the array storing the locking codes for the clients. The value will vary from 0 to num_nl_clients where num_nl_clients is the number of clients set using VLScgSetNumClients.

10.61.2. Description Sets the client locking code.

10.61.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_HEX_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If value is not in hexadecimal format. If number is greater than num_nl_clients -1. Number of node locked clients.

VLScg_LESS_THAN_MIN_VALUE If number is less than 0. VLScg_INVALID_IP_TYPE

If value is not in dot format.

VLScg_UNKNOWN_LOCK

If the locking criteria is unknown.

For a complete list of the error codes, see License Generation Error Codes.

384

Chapter 10:  License Code Generation API

10.62. VLScgSetNumClients 10.62.1. Syntax int VLScgSetNumClients ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Number of client locking codes to be specified.

10.62.2. Description Applications can be locked to specific client computers using locking codes that uniquely identify those computers.

10.62.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If input is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum number of 7 clients.

VLScg_LESS_THAN_MIN_VALUE If value is less than 1. For a complete list of the error codes, see License Generation Error Codes.

10.63. VLScgAllowClockTamperFlag

385

10.63. VLScgAllowClockTamperFlag 10.63.1. Syntax int VLScgAllowClockTamperFlag ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.63.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

386

Chapter 10:  License Code Generation API

10.64. VLScgSetClockTamperFlag 10.64.1. Syntax int VLScgSetClockTamperFlag ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Valid values are: n n

VLScg_NO_CHECK_TAMPER_STRING - Do not check clock tamper = “0” VLScg_CHECK_TAMPER_STRING - Check clock tamper = “1”

10.64.2. Description Controls action on detection of clock being set back on the machine. Clock tamper check will only be done when the license server starts up, but the license server will not exit on detection of tampering. Only those license strings that specify they want the check will be denied if tampering is detected. Other features will continue to be served by the license server. Even if someone sets the clock back after starting the license server, and then dynamically adds a tamper-sensitive license string, the license server will detect it and throw the license string out. When the license server accepts a license string at start-up but detects later that the clock has been set back, it does not grant a license for the feature until the clock is reset to its correct value.

10.64.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a decimal number.

VLScg_INVALID_RANGE

If value is not in the range allowed.

For a complete list of the error codes, see License Generation Error Codes.

10.65. VLScgAllowOutLicType

387

10.65. VLScgAllowOutLicType 10.65.1. Syntax int VLScgAllowOutLicType ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.65.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

388

Chapter 10:  License Code Generation API

10.66. VLScgSetOutLicType 10.66.1. Syntax  int VLScgSetOutLicType ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Valid values are: n n n

VLScg_ENCRYPTED_STRING = “0” VLScg_EXPANDED_READABLE_STRING = “1” VLScg_CONCISE_READABLE_STRING = “2”

10.66.2. Description Controls the type of license string generated. License output formats can be: encrypted, expanded readable, and concise readable. The license code contains all of the information that defines the license agreement between you and your customer: how many s can run the application at a time, whether the license will expire after a specific number of days, whether the application can only run on a specific computer, and so on. Encrypted license strings contain this information about the license agreement, but cannot be read by your customers. Concise readable license codes store information about the provisions of a licensing agreement in readable form, such as plain text with white spaces so that it is easily read (and understood) by the . The expanded readable license string, a string is appended to the numeric values to specify what that numeric value stands for, e.g., 60_MINS implies that 60 specifies the time in minutes. These strings do not appear in the concise format, only a 60 appears in the concise readable license string, as opposed to 60_MINS in the expandable readable format.

10.66.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a decimal number.

VLScg_INVALID_RANGE

If value is not in the range allowed.

For a complete list of the error codes, see License Generation Error Codes.

10.67. VLScgSetLicType

389

10.67. VLScgSetLicType 10.67.1. Syntax int VLScgSetLicType ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *lictype );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

lictype

Set the type of license. n n

VLScg_TRIAL_LIC_STRING = “1” VLScg_NORMAL_LIC_STRING = “0”

10.67.2. Description Sets the type of license to either trial or normal. Trial licenses are relative time-limited licenses that use a trial period of short/ long licenses is 730/1461 days. Notice, trial licenses do not start until the first time the application is executed (as opposed to the time that the application is installed).

10.67.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID _LIC_TYPE

Description If license type is not valid.

For a complete list of the error codes, see License Generation Error Codes.

390

Chapter 10:  License Code Generation API

10.68. VLScgAllowHeldLic 10.68.1. Syntax int VLScgAllowHeldLic ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.68.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.69. VLScgSetHoldingCrit

391

10.69. VLScgSetHoldingCrit 10.69.1. Syntax int VLScgSetHoldingCrit ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

The flag is used to set the criteria for held licenses. Values are: n n n

VLScg_HOLD_NONE_STRING = “0” - Held licenses not allowed. VLScg_HOLD_VENDOR_STRING = “1” - Client API specifies hold time. VLScg_HOLD_CODE_STRING = “2” - License code specifies hold time.

10.69.2. Description This defines the criteria for determining the hold time for a license, and controls whether or not held licenses are allowed for this feature. Hold time provides a grace period after the license is released during which only the original license requestor will be granted the license. Validates and installs the value of the flag in the license code structure.

10.69.3. Returns The status code VLScg_SUCCESS is returned if successful Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_HOLD_CODE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_HOLD_NONE_STRING. For a complete list of the error codes, see License Generation Error Codes.

392

Chapter 10:  License Code Generation API

10.70. VLScgAllowCodegenVersion 10.70.1. Syntax int VLScgAllowCodegenVersion ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.70.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.71. VLScgSetCodegenVersion

393

10.71. VLScgSetCodegenVersion 10.71.1. Syntax int VLScgSetCodegenVersion ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Sets the possible values for version_num flag.

10.71.2. Description Sets the version of license codes to generate. Checks if the current license code setting allow multiple features.

10.71.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds MAX_CODEGEN_VERSION.

For a complete list of the error codes, see License Generation Error Codes.

394

Chapter 10:  License Code Generation API

10.72. VLScgAllowCapacityLic 10.72.1. Syntax int VLScgAllowCapacityLic ( VLScg_HANDLE iHandle, codeT *codeP );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

10.72.2. Description Allows the application to check if capacity licensing is allowed or not. For details on capacity licensing, see the Sentinel RMS SDK Developer's Guide.

10.72.3. Returns It will return the following return status: Return Value 0

Description Capacity licensing is not allowed.

1

Capacity licensing is allowed.

For a complete list of the error codes, see License Generation Error Codes.

10.73. VLScgSetCapacityFlag

395

10.73. VLScgSetCapacityFlag 10.73.1. Syntax  int VLScgSetCapacityFlag ( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

Flag

The value of flag is used to set the capacity_flag of codeT struct. Legal values aren n n

VLScg_CAPACITY_NONE_STRING VLScg_CAPACITY_NON_POOLED_STRING VLScg_CAPACITY_POOLED_STRING

10.73.2. Description Specifies whether the license is a capacity license or not. Also sets the appropriate fields of codeT structure to make sure that it is: n

A normal license and not a trial license

n

A network license and not a stand-alone license

n

Not a held license

n

Not a redundant license

n

Not a commuter license

n

License code format is “Encrypted” only.

10.73.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_SUCCESS

Description Success

VLScg_INVALID_INT_TYPE

If value is not numeric

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_CAPACITY_POOLED VLScg_LESS_THAN_MIN_ VALUE

If value is lower than VLScg_CAPACITY_NONE

For a complete list of the error codes, see License Generation Error Codes.

396

Chapter 10:  License Code Generation API

10.74. VLScgAllowCapacity 10.74.1. Syntax int VLScgAllowCapacity ( VLScg_HANDLE codeT

iHandle, *codeP );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

10.74.2. Description Allows the application to check whether it is a capacity license or not.

10.74.3. Returns It will return the following return status:

Return Value 0

Description It is a non-capacity license.

1

It is a capacity license.

For a complete list of the error codes, see License Generation Error Codes.

10.75. VLScgSetCapacityUnits

397

10.75. VLScgSetCapacityUnits 10.75.1. Syntax int VLScgSetCapacityUnits ( VLScg_HANDLE iHandle, codeT *codeP, char *units );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

units

Capacity specification units from 0 to 4. The values are: n n n n

n

If capacity_units is 0, capacity shall be multiple of 1(s), maximum 1022. If capacity_units is 1, capacity shall be multiple of 10(s), maximum 10220. If capacity_units is 2, capacity shall be multiple of 100(s), maximum 102200. If capacity_units is 3, capacity shall be multiple of 1000(s), maximum 1022000. If capacity_units is 4, capacity shall be multiple of 10000(s), maximum 10220000.

10.75.2. Definition Sets the capacity_units field of codeT struct.

10.75.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_SUCCESS

Description Success.

VLScg_INVALID_INT_TYPE

If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_CAPACITY_UNITS_MAX_VALUE

VLScg_LESS_THAN_MIN_VALUE If value is less than VLScg_CAPACITY_UNITS_MIN_VALUE For a complete list of the error codes, see License Generation Error Codes.

398

Chapter 10:  License Code Generation API

10.76. VLScgSetCapacity 10.76.1. Syntax int VLScgSetCapacity ( VLScg_HANDLE iHandle, codeT *codeP, char *capacity );

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

capacity

Controls the capacity n n n n

n

If capacity_units is 0, capacity shall be multiple of 1(s), maximum 1022. If capacity_units is 1, capacity shall be multiple of 10(s), maximum 10220. If capacity_units is 2, capacity shall be multiple of 100(s), maximum 102200. If capacity_units is 3, capacity shall be multiple of 1000(s), maximum 1022000. If capacity_units is 4, capacity shall be multiple of 10000(s), maximum 10220000.

VLScg_NOLIMIT_STRING or EMPTY(“/0”) String can be used to specify infinite capacity.

10.76.2. Definition Sets the capacity field of codeT struct.

10.76.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not numeric.

VLScg_NOT_MULTIPLE

If value is not a correct multiple.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum.

VLScg_LESS_THAN_MIN_VALUE If value is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

10.77. VLScgAllowMultiKey

399

10.77. VLScgAllowMultiKey 10.77.1. Syntax int VLScgAllowMultiKey ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.77.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

400

Chapter 10:  License Code Generation API

10.78. VLScgSetKeyType 10.78.1. Syntax int VLScgSetKeyType( VLScg_HANDLE iHandle, codeT *codeP, char *flag );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Flag used to set the code_type member of codeT struct. The values are: n n

VLScg_SINGLE_KEY_STRING = “0” VLScg_MULTI_KEY_STRING = “1”

10.78.2. Description Controls whether a license will be single or multi-feature license code types. n

n

Single Feature: Predefined short, numeric license codes where the license code is for a single feature. Notice, if you select Predefined-Single Feature, the feature name must be no more than 2 numeric digits. Most of the attributes are already defined for you and cannot be modified. Multi Feature: Predefined short, numeric license types where multiple features (value between 2 - 11) can be placed into a single license code. Notice, if you select Predefined-Multi Feature, the feature name must be no more than 2 numeric digits. Most of the attributes are already defined for you and cannot be modified.

10.78.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a decimal number.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MULTI_KEY_STRING. VLScg_LESS_THAN_MIN_ VALUE

If value is lower than VLScg_SINGLE_KEY_STRING.

For a complete list of the error codes, see License Generation Error Codes.

10.79. VLScgAllowSecrets

401

10.79. VLScgAllowSecrets 10.79.1. Syntax int VLScgAllowSecrets ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.79.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

402

Chapter 10:  License Code Generation API

10.80. VLScgSetSecrets 10.80.1. Syntax int VLScgSetSecrets ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*valu,

int

num );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

valu

Any printable ASCII text.

num

Number of secrets: should be from 0 to num_secrets -1. num is the position in the array storing the secrets. The value varies from 0 to num_secrets-1, where num_secrets is set using VLScgSetNumSecrets

10.80.2. Description Sets the value of the specified challenge-response secrets. Both the application and the license contain data known as secrets. When an application wishes to challenge, it generates a random text string, which is ed as the challenge value to the license server. In response to this challenge value, the license server examines the software license to determine the secret and computes the corresponding answer. The result is then ed back to the client application as the response to the challenge. The purpose of the challenge is to that there is a valid license present. Even a tampered license server cannot respond correctly to the challenge.

10.80.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_CHARACTERS VLScg_EXCEEDS_MAX_VALUE

Description If string is not valid. If value exceeds maximum. The value set by VLScgSetNumSecrets

VLScg_LESS_THAN_MIN_VALUE If the value is lower than minimum. For a complete list of the error codes, see License Generation Error Codes.

10.81. VLScgSetNumSecrets

403

10.81. VLScgSetNumSecrets 10.81.1. Syntax int VLScgSetNumSecrets ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*valu );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

valu

This value sets the number of secrets.

10.81.2. Description Sets the total number of secrets for the challenge-response mechanism. Up to seven secret text strings can be specified, each up to twelve characters long. The secrets are encrypted within the license itself, with only the license server knowing how to decrypt the secrets. The license server will then compute an authentication response when challenged by a client to confirm its identity.

10.81.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INT_TYPE

Description If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_MAX_NUM_SECRETS.

VLScg_LESS_THAN_MIN_VALUE If value is lower than 0. For a complete list of the error codes, see License Generation Error Codes.

404

Chapter 10:  License Code Generation API

10.82. VLScgAllowVendorInfo 10.82.1. Syntax int VLScgAllowVendorInfo ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.82.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.83. VLScgSetVendorInfo

405

10.83. VLScgSetVendorInfo 10.83.1. Syntax int VLScgSetVendorInfo ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *privateVendorInfo );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

privateVendorInfo

Any printable ASCII text (see Reserved Characters and Strings). Maximum of 2000 characters, except in case of redundant licenses, where the vendor information (both public and private) should not exceed 395 characters. …

10.83.2. Description Sets the private vendor information to the value provided in a license. This function also sets the public vendor information to blank. The private vendor information will remain encrypted in a license code and can be retrieved through a client library function call. You may use it for keeping track of distributors or implementing a variety of licensing schemes. See VLScgAllowVendorInfoExt and VLScgSetVendorInfoExt for setting both the private and public information in a license code. The public information can be read by customers (if the licenses are defined as readable).

10.83.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_CHARS

Description If string is not valid.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum.

VLScg_LESS_THAN_MIN_VALUE

If the value is lower than minimum.

VLScg_RESERV_STR_ERROR

If the string is a reserved string.

For a complete list of the error codes, see License Generation Error Codes.

406

Chapter 10:  License Code Generation API

10.84. VLScgAllowVendorInfoExt Verifies whether setting private vendor information and public vendor information is allowed for code type and license version (code_type and version_num, respectively) specified in the codeT structure. The public vendor information is ed only for the version 11 (or higher) long licenses. The version 11 refers to the licenses generated using the 8.1 version of license code generator.

10.84.1. Syntax int VLScgAllowVendorInfoExt ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.84.2. Returns The API returns 1, if private vendor information and public vendor information is allowed to set, else it returns 0.

10.85. VLScgSetVendorInfoExt

407

10.85. VLScgSetVendorInfoExt 10.85.1. Syntax int VLScgSetVendorInfoExt ( VLScg_HANDLE codeT

Argument

iHandle, *codeP,

char

*privateVendorInfo,

char

*publicVendorInfo );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

privateVendorInfo

Any printable ASCII text. Maximum of 2000 characters. This value appears as encrypted string in the license code.

publicVendorInfo

Any printable ASCII text (see Reserved Characters and Strings). Maximum of 395 characters. This value appears as unencrypted string in the license code. In case of redundant licenses, the vendor information (both public and private) should not exceed 395 characters.

10.85.2. Description Sets private vendor information and public vendor information in a license code. These values, ed as privateVendorInfo and publicVendorInfo are set in the vendor_info and plain_vendor_info , respectively, of the ed codeT structure. The VLScgAllowVendorInfoExt API function must be called before calling this API to ensure that setting private vendor information and public vendor information in a license code is allowed. For short-numeric license codes, only private information can be specified, not exceeding 98 characters. For long licenses codes, both public and private information can be specified.

10.85.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INPUT

Description Argument specified is not correct. Can be because: n

codeP is NULL.

408

Chapter 10:  License Code Generation API

Error Code

Description n PrivateVendorInfo or publicVendorInfo is NULL. n If the API is called for licenses earlier than version 11.

VLScg_EXCEEDS_MAX_STRLEN

Length of the input string exceeds the maximum limit.

VLScg_RESERV_STR_ERR

The input string is a reserved word.

VLScg_INVALID_CHARS

The input string is invalid.

VLScg_RESERV_STR_ERROR

If the string is a reserved string.

For a complete list of the error codes, see License Generation Error Codes.

10.86. VLScgAllowKeysPerNode

409

10.86. VLScgAllowKeysPerNode 10.86.1. Syntax int VLScgAllowKeysPerNode ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.86.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

410

Chapter 10:  License Code Generation API

10.87. VLScgSetKeysPerNode 10.87.1. Syntax int VLScgSetKeysPerNode ( VLScg_HANDLE iHandle, codeT *codeP, char *keys, int num );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

keys

Used to set the number of keys per node. Give any decimal value. Should be from 0. Give VLScg_NOLIMIT_STRING for no limit.

num

Position of client in the array of clients: should be from 0 to the maximum number of clients -1.

10.87.2. Description This function sets the number of keys (license tokens) per node for the specified number of clients. For each client locked and client&server locked node, the number of copies running on each computer is controlled. This is an extra per-host restriction in addition to the overall number of licenses.

10.87.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If number is not a non-negative integer. If number is greater than num_nl_clients -1. num_nl_clients is a field of CodeT structure storing the number of clients.

VLScg_LESS_THAN_MIN_VALUE If number is less than 0. For a complete list of the error codes, see License Generation Error Codes.

10.88. VLScgAllowSiteLic

411

10.88. VLScgAllowSiteLic 10.88.1. Syntax int VLScgAllowSiteLic ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.88.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

412

Chapter 10:  License Code Generation API

10.89. VLScgSetSiteLicInfo 10.89.1. Syntax int VLScgSetSiteLicInfo ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info,

int

num );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Set the subnet address. You can use wildcard (e.g., *.123.*.28) to specify a range.

num

num is the position of subnet in the array maintaining the subnet info.The value varies from 0 to num_subnets-1 where num_subnets is an element of CodeT struct set using VLScgSetNumSubnets.

10.89.2. Description Sets subnet address. Specifies the number of subnets used for site licensing.

10.89.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_RANGE

Description If value is not in the range allowed and if value is not a valid character.

For a complete list of the error codes, see License Generation Error Codes.

10.90. VLScgSetNumSubnets

413

10.90. VLScgSetNumSubnets 10.90.1. Syntax int VLScgSetNumSubnets ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the number of subnets: Should be from 1 to VLScg_MAX_NUM_SUBNETS whose value is 7. 0 is a special value which means no site licensing.

10.90.2. Description Sets the number of subnets the licensed application can run on. To set actual site addresses, use VLScgSetSiteLicInfo*.

10.90.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If input is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE

If num is greater than codeP to num_subnets.

VLScg_LESS_THAN_MIN_VALUE If num is less than 0. For a complete list of the error codes, see License Generation Error Codes.

414

Chapter 10:  License Code Generation API

10.91. VLScgAllowMultipleFeature 10.91.1. Syntax int VLScgAllowMultipleFeature ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.91.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.92. VLScgSetNumFeatures

415

10.92. VLScgSetNumFeatures 10.92.1. Syntax int VLScgSetNumFeatures ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

flag

Sets the flag for number of features in case of multi-feature.

10.92.2. Description Sets the number of features.

10.92.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If input is not a decimal number.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds VLScg_MAX_NUM_FEATURES.

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_MIN_NUM_FEATURES. For a complete list of the error codes, see License Generation Error Codes.

416

Chapter 10:  License Code Generation API

10.93. VLScgAllowSoftLimit 10.93.1. Syntax int VLScgAllowSoftLimit ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.93.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.94. VLScgSetSoftLimit

417

10.94. VLScgSetSoftLimit 10.94.1. Syntax int VLScgSetSoftLimit ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets soft limit: should be from 0 to VLScg_NOLIMIT_STRING for no limit. VLScg_NOLIMIT_STRING is not allowed if the license is a commuter license.

10.94.2. Description The soft limit number defines a threshold at which a warning can be issued that the maximum number of licenses is being approached. Must be less than the maximum number of s (the hard limit).

10.94.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If information is not a non-negative integer. If information exceeds maximum number of license tokens allowed. Maximum value for long codes is 32766 and maximum value for short codes is 254.

VLScg_LESS_THAN_MIN_VALUE If information is less than 0. For a complete list of the error codes, see License Generation Error Codes.

418

Chapter 10:  License Code Generation API

10.95. VLScgAllowKeyLifeUnits 10.95.1. Syntax int VLScgAllowKeyLifeUnits ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.95.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.96. VLScgSetKeyLifetimeUnits

419

10.96. VLScgSetKeyLifetimeUnits 10.96.1. Syntax int VLScgSetKeyLifetimeUnits ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Lifetime specification units of license tokens: from 0 to 3. The values are: n n n n

“0” - Multiple of 1 minute(s), maximum 15 minutes. “1” - Multiple of 10 minute(s), maximum 150 minutes. “2” - Multiple of 30 minute(s), maximum 450 minutes. “3” - Multiple of 60 minute(s), maximum 900 minutes.

10.96.2. Description This function specifies the units of time used to specify the time between renewals. A license must be renewed by the application on a regular schedule or the license will be reclaimed. VLScgAllowKeyLifetime

10.96.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If information is a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds 3.

VLScg_LESS_THAN_MIN_VALUE If value is less than 0. For a complete list of the error codes, see License Generation Error Codes.

420

Chapter 10:  License Code Generation API

10.97. VLScgAllowKeyHoldUnits 10.97.1. Syntax int VLScgAllowKeyHoldUnits ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.97.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.98. VLScgSetKeyHoldtimeUnits

421

10.98. VLScgSetKeyHoldtimeUnits 10.98.1. Syntax int VLScgSetKeyHoldtimeUnits ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Hold time specification units of license tokens: from 0 to 3. The values are: n n n n

“0” - Multiple of 1 minute(s), maximum 15 minutes “1” - Multiple of 10 minute(s), maximum 150 minutes. “2” - Multiple of 30 minute(s), maximum 450 minutes. “3” - Multiple of 60 minute(s), maximum 900 minutes.

10.98.2. Description Network licenses may be held for a time when released by a specific . During that time only the original requestor of the license can be granted the license again. This function sets the units of time used to specify the hold time.

10.98.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If information is a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds 3.

VLScg_LESS_THAN_MIN_VALUE If value is less than 0. For a complete list of the error codes, see License Generation Error Codes.

422

Chapter 10:  License Code Generation API

10.99. VLScgAllowKeyHoldtime 10.99.1. Syntax int VLScgAllowKeyHoldtime ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.99.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.100. VLScgSetKeyHoldtime

423

10.100. VLScgSetKeyHoldtime 10.100.1. Syntax int VLScgSetKeyHoldtime ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Absolute values in minutes. Maximum depends on units set by VLScgSetKeyHoldtimeUnits. VLScg_NOLIMIT_STRING sets hold time to 900 minutes.

10.100.2. Description Network licenses may be held for a time when released by a specific . During that time only that can reclaim the license. This function specifies the hold time. This function sets the value codeP>key_holdtime to the value of info and performs small checks to validate input.

10.100.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If information is a non-negative integer.

VLScg_NOT_MULTIPLE

If value is not a correct multiple.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed hold time.

VLScg_LESS_THAN_MIN_VALUE If value is less than 0. For a complete list of the error codes, see License Generation Error Codes.

424

Chapter 10:  License Code Generation API

10.101. VLScgAllowLicBirth 10.101.1. Syntax int VLScgAllowLicBirth ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.101.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.102. VLScgSetLicBirthMonth

425

10.102. VLScgSetLicBirthMonth 10.102.1. Syntax int VLScgSetLicBirthMonth ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the month of year to 1-12 or Jan-Dec.

10.102.2. Description Sets the month of the license start date. The license start month should be specified in the range of 011. VLScgSetLicBirthMonth is not applicable if year is infinite.

10.102.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_CHARACTERS

Description If not a valid string.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed month (exceeds 12).

VLScg_LESS_THAN_MIN_VALUE If value is less than 1. For a complete list of the error codes, see License Generation Error Codes.

426

Chapter 10:  License Code Generation API

10.103. VLScgSetLicBirthDay Sets the day of the license start date.

10.103.1. Syntax int VLScgSetLicBirthDay ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the day of the month (1-31).

10.103.2. Description Sets the day of the license start date. Not applicable if year has been set to infinite.

10.103.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a non-negative integer.

VLScg_INVALID_DATE

If value is not valid for the month.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed day.

VLScg_LESS_THAN_MIN_VALUE If value is less than 1. For a complete list of the error codes, see License Generation Error Codes.

10.104. VLScgSetLicBirthYear

427

10.104. VLScgSetLicBirthYear 10.104.1. Syntax int VLScgSetLicBirthYear ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*info );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Enter year in 4 digits (e.g., 2003) to avoid year 2000 problem.

10.104.2. Description Sets the year of the license start date. Not applicable if year is infinite.

10.104.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a non-negative integer.

VLScg_INVALID_YEAR

If year is invalid.

VLScg_INVALID_BIRTH_YEAR

If year is less than 2003.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed year that is 2130.

For a complete list of the error codes, see License Generation Error Codes.

428

Chapter 10:  License Code Generation API

10.105. VLScgAllowLicExpiration 10.105.1. Syntax int VLScgAllowLicExpiration ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.105.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.106. VLScgSetLicExpirationMonth

429

10.106. VLScgSetLicExpirationMonth 10.106.1. Syntax int VLScgSetLicExpirationMonth ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the month of year: 1 -12 or Jan.-Dec.

10.106.2. Description Sets month of date license expires. The license expiration month should be specified in the range of 112. VLScgSetLicExpirationMonth is not applicable if year is infinite.

10.106.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_CHARACTERS

Description If not a valid string.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed month (exceeds 12).

VLScg_LESS_THAN_MIN_VALUE If value is less than 1. For a complete list of the error codes, see License Generation Error Codes.

430

Chapter 10:  License Code Generation API

10.107. VLScgSetLicExpirationDay 10.107.1. Syntax int VLScgSetLicExpirationDay ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Sets the day of the month: 1-31.

10.107.2. Description Sets the day of the month of the date on which the license expires. No need to set if the year is infinite.

10.107.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a non-negative integer.

VLScg_INVALID_DATE

If value is not valid for the month.

VLScg_EXCEEDS_MAX_VALUE

If value exceeds maximum allowed day.

VLScg_LESS_THAN_MIN_VALUE If value is less than 1. For a complete list of the error codes, see License Generation Error Codes.

10.108. VLScgSetLicExpirationYear

431

10.108. VLScgSetLicExpirationYear 10.108.1. Syntax int VLScgSetLicExpirationYear ( VLScg_HANDLE iHandle, codeT *codeP, char *info );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

info

Enter year in 4 digits (e.g., 2008). Use the VLScg_NEVER_STRING macro (defined in lscgen.h) for infinite expiration.

10.108.2. Description Sets the year of the date that the license expires.

10.108.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_INT_TYPE

Description If value is not a non-negative integer.

VLScg_INVALID_YEAR

If the year is invalid.

VLScg_INVALID_DEATH_YEAR

If year is less than 2003.

VLScg_EXCEEDS_MAX_VALUE If value exceeds 2130. For a complete list of the error codes, see License Generation Error Codes.

432

Chapter 10:  License Code Generation API

10.109. VLScgSetNumericType 10.109.1. Syntax int VlScgSetNumericType ( VLScg_HANDLE codeT int

Argument

iHandle, *codeP, num );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

num

Numeric type values are: n n n n

VLScg_NUMERIC_UNKNOWN = “0” VLScg_NOT_NUMERIC = “1” VLScg_MISC_SHORT_NUMERIC = “2” VLScg_MISC_NUMERIC = “3”

10.109.2. Description Sets the value codeP->numeric_type to the value of num and Checks the input and saves the value in code struct.

10.109.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_EXCEEDS_MAX_VALUE

Description Value exceeds the maximum value of 3.

VLScg_LESS_THAN_MIN_VALUE If value is less than 0. VLScg_INVALID_INT_TYPE

If the value is not a non-negative integer.

For a complete list of the error codes, see License Generation Error Codes.

10.110. VLScgSetLoadSWLicFile

433

10.110. VLScgSetLoadSWLicFile 10.110.1. Syntax int VLScgSetLoadSWLicFile ( VLScg_HANDLE char

Argument

iHandle, *filename );

iHandle

Description The instance handle for this library.

filename

Complete name and path of sw license file.

10.110.2. Description Sets and loads the software license file (lscgen.lic).

10.110.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

434

Chapter 10:  License Code Generation API

10.111. VLScgAllowGracePeriodFlag 10.111.1. Syntax int VLScgAllowGracePeriodFlag ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.111.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

10.112. VLScgSetGracePeriodFlag

435

10.112. VLScgSetGracePeriodFlag 10.112.1. Syntax int VLScgSetGracePeriodFlag ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*flag );

iHandle

Description The instance handle for this library.

codeP

A pointer to the codeT structure.

flag

A flag that will decide whether the VLScgAllowGracePeriod should be called or not. The value can be: n n

VLScg_NO_GRACE_PERIOD VLScg_STANDARD_GRACE_PERIOD

10.112.2. Description Sets the grace period flag value.

10.112.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

436

Chapter 10:  License Code Generation API

10.113. VLScgAllowGracePeriod 10.113.1. Syntax int VLScgAllowGracePeriod ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.113.2. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

10.114. VLScgSetGracePeriodDays

437

10.114. VLScgSetGracePeriodDays 10.114.1. Syntax int VLScgSetGracePeriodDays ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *calendar_daysStr );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

calendar_daysStr

The number of days the license can be used in the grace period.

10.114.2. Description Sets the number of calendar days the license can be used in the grace period.

10.114.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

438

Chapter 10:  License Code Generation API

10.115. VLScgSetGracePeriodHours 10.115.1. Syntax int VLScgSetGracePeriodHours ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, *elapsed_hoursStr );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

elapsed_hoursStr

The number of hours the license can be used in the grace period.

10.115.2. Description Sets the number of elapsed hours the license can be used in a grace period.

10.115.3. Return The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

10.116. VLScgAllowLocalRequestLockCritFlag

439

10.116. VLScgAllowLocalRequestLockCritFlag 10.116.1. Syntax int VLScgAllowLocalRequestLockCritFlag ( VLScg_HANDLE codeT

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

iHandle, *codeP );

10.116.2. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

440

Chapter 10:  License Code Generation API

10.117. VLScgSetLocalRequestLockCritFlag 10.117.1. Syntax int VLScgSetLocalRequestLockCritFlag ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*str );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

str

The locking criteria, which can have any of the following values: n

n

VLScg_LOCAL_REQUEST_LOCKCRIT_USEDEFAULT_STRING: Refers to the default criteria. VLScg_LOCAL_REQUEST_LOCKCRIT_DEFINED_STRING: Refers to a defined criteria.

10.117.2. Description Sets the locking criteria as default or -defined.

10.117.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

10.118. VLScgAllowLocalRequestLockCrit

441

10.118. VLScgAllowLocalRequestLockCrit 10.118.1. Syntax int VLScgAllowLocalRequestLockCrit ( VLScg_HANDLE codeT

Argument

iHandle, *codeP );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.118.2. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

442

Chapter 10:  License Code Generation API

10.119. VLScgSetLocalRequestLockCrit 10.119.1. Syntax  int VLScgSetLocalRequestLockCrit ( VLScg_HANDLE

Argument

iHandle,

codeT

*codeP,

char

*str );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

str

Allows setting the required, floating, and minimum required locking criteria for the local request. For example, 0x4:0x3FF:2 will set: n n n

0x4 as the required locking criteria. 0x3FF as the floating locking criteria. 2 as the minimum locking criteria.

10.119.2. Description Sets the required, floating, and minimum required locking criteria for the local request.

10.119.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error codes is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

10.120. VLScgAllowVmDetection

443

10.120. VLScgAllowVmDetection 10.120.1. Syntax int VLScgAllowVmDetection ( VLScg_HANDLE iHandle, codeT *codeP );

Argument iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

10.120.2. Returns The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. If VLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, it will return 0 as false.

444

Chapter 10:  License Code Generation API

10.121. VLScgSetVmDetection 10.121.1. Syntax int VLScgSetVmDetection ( VLScg_HANDLE codeT char

Argument

Direction

iHandle

IN

codeP

IN

vmDetectionStr IN

Data Type

iHandle, *codeP, *vmDetectionStr );

Description

VLScg_ The instance handle for this library. HANDLE codeT The pointer to the codeT struct. char

This buffer is used to set the virtual machine detection flag for clients. Valid values are: n

n

VLScg_VM_ALLOWED_STRING - Issue license token on virtual machine detection = “0” VLScg_VM_DISALLOWED_STRING - Do not issue license token on virtual machine detection = “1”

10.121.2. Description Sets the action on detection of a virtual machine—whether to allow\deny grant of a license token. This check will only be done when the license server starts up, but the license server will not exit on detection of a virtual machine on the host. Only those license strings that disallow license use in case of VM detection will be denied.

10.121.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLScg_ INVALID_ INPUT

If value is not any one of the above defined flags.

For a complete list of the error codes, see License Generation Error Codes.

10.122. VLScgValidateCodeT

445

10.122. VLScgValidateCodeT 10.122.1. Syntax  int VLScgValidateCodeT VLScg_HANDLE

iHandle,

codeT

*codeP);

Argument

Description

iHandle

The instance handle for this library.

codeP

The pointer to the codeT struct.

10.122.2. Description Validates fields value of the codeT structure. Call this API with the filled codeT structure. It compares CodeT fields and gives error if found any invalid value in the referenced filled codeP structure.

10.122.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, an error is returned with the actual point of failure. For a complete list of the error codes, see License Generation Error Codes.

446

Chapter 10:  License Code Generation API

The License Generation Function The following table summarizes the license generation function: Function VLScgGenerateLicense

Description Generates the license string.

10.123. VLScgGenerateLicense

447

10.123. VLScgGenerateLicense 10.123.1. Syntax int VLScgGenerateLicense ( VLScg_HANDLE codeT char

Argument

iHandle, *codeP, **result );

iHandle

Description The instance handle for this library.

codeP

The pointer to the codeT struct.

result

Address of pointer pointing to generated license string.

10.123.2. Description This function generates the license string for the given codeT struct. It should be called after all the VLScgSet functions are called. Memory allocation and deallocation for codeT are the responsibilities of the caller of function. Memory allocation for the license string is handled by this function. Its address is to be ed by the caller of this function in the second argument.

10.123.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

VLScg_INVALID_VENDOR_CODE

Description If vendor identification is illegal.

VLScg_VENDOR_ENCRYPTION_ FAIL

If vendor-customized encryption fails.

VLScg_LICMETER_NOT_ ED

Your Sentinel RMS Development Kit License Meter is not ed.

For a complete list of the error codes, see License Generation Error Codes.

448

Chapter 10:  License Code Generation API

License Hash and Decode Functions The following table summarizes the license hash and decode functions: Function

Description

VLScgCalculateLicenseHash VLScgDecodeLicense

Calculates the license hash. Decodes the license string.

VLScgDecodeLicenseExt

Decodes the license string. The needs to allocate memory.

10.124. VLScgCalculateLicenseHash

449

10.124. VLScgCalculateLicenseHash 10.124.1. Syntax int VLScgCalculateLicenseHash ( char *pcLicenseString, unsigned char *pucLicenseHash, int

Argument

*piLicenseHashLength );

Direction

Data Type

Description

pcLicenseString

IN

char

A pointer to the license string whose hash is to be calculated.

pucLicenseHash

OUT

unsigned A pointer to the location where the license hash is to be stored. char If the value ed is NULL, the required length for this buffer is returned to the third argument piLicenseHashLength.

piLicenseHashLength IN/OUT

int

The length of the hash buffer. needs to allocate memory.

10.124.2. Description Calculates the hash of a license string. A hash uniquely identifies a license string.

Tip Make sur e you a valid lic e nse str ing for c alc ulating lic e nse hash. You c an use V L Sc gDe c ode L ic e nse \V L Sc gDe c ode L ic e nse E xt to ve r ify the lic e nse str ing's validity.

10.124.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLScg_INVALID_INPUT

One or more input parameters are invalid.

VLScg_BUFFER_TOO_SMALL

If the input size of the buffer specified for storing hash is smaller than required.

For a complete list of the error codes, see License Generation Error Codes.

450

Chapter 10:  License Code Generation API

10.125. VLScgDecodeLicense 10.125.1. Syntax int VLScgDecodeLicense ( VLScg_HANDLE char

*AnyLicenseString,

char

*lic_string,

int codeT

Argument

iHandle,

lic_string_length, **codeP );

iHandle

Description The instance handle for this library.

any_license_string

-provided license string to be decoded.

license_string

allocated buffer to receive decoded license string. An OUT parameter.

license_string_buflen

Length of decoded license string returned.

codeP

Pointing to codeT containing input license string.

10.125.2. Description The library can call the API VLScgDecodeLicense without requiring the license meter If under certain circumstances, the API is called by linking both the lscgen and lsdecode libraries, then the decode library should be first in the linking sequence. Otherwise, the meter key is required).

The API decodes the license string AnyLicenseString and puts the corresponding codeT struct in the last argument. Pointer to codeT struct is to be ed as the last argument. This pointer will contain the codeT corresponding to AnyLicenseString. When decoding a license via the VLScgDecodeLicense API function, the codeT structure returned does not contain the license secrets—instead the corresponding field contains an empty string.

10.125.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLScg_INVALID_VENDOR_CODE

If vendor identification is illegal.

VLScg_VENDOR_ENCRYPTION_ FAIL

If vendor-customized encryption fails.

10.125. VLScgDecodeLicense

Error Code

Description

VLScg_MALLOC_FAILURE

Out of heap memory.

VLScg_SHORT_STRING

License string too small to parse.

VLScg_PREMATURE_TERM

Premature termination of license string. Please check.

VLScg_INVALID_CHARS

String is not valid.

VLScg_EXCEEDS_MAX_STRING

Length of the string is greater than the defined limit.

VLScg_REMAP_DEFAULT

Failed to remap default strings from configuration file for license.

VLScg_DECRYPT_FAIL

Decryption failed for license code.

VLScg_INVALID_CHKSUM

Checksum validation failed for license string.

VLScg_FIXED_STR_ERROR

Default fixed string error.

VLScg_INVALID_RANGE

Value violates the valid range of input.

VLScg_INVALID_INPUT

Invalid input.

VLScg_INVALID_INT_TYPE

Value is not numeric.

VLScg_LESS_THAN_MIN_VALUE

Value entered is less than the minimum ed value.

VLScg_LESS_THAN_MAX_VALUE

Value entered is greater than the maximum ed value.

VLScg_INVALID_HEX_TYPE

Wrong value entered. (Should be hexadecimal).

VLScg_SECRET_DECRYPT_FAILURE Decryption failed for secrets. the configuration file for readable licenses. VLScg_SIMPLE_ERROR

Error in license string. Please check.

For a complete list of the error codes, see License Generation Error Codes.

451

452

Chapter 10:  License Code Generation API

10.126. VLScgDecodeLicenseExt 10.126.1. Syntax LS_STATUS_CODE VLScgDecodeLicenseExt ( VLScg_HANDLE char

*any_license_string,

char

*license_string,

int codeT

Argument

handle,

*license_string_buflen, *codeP );

iHandle

Description The instance handle for this library.

any_license_string

-provided license string to be decoded.

license_string

allocated buffer to receive decoded license string. An OUT parameter.

license_string_buflen

Length of decoded license string returned.

codeP

Pointing to codeT containing input license string. You will need to allocate memory for the codeT structure.

10.126.2. Description This API function decodes the license code ed as any_license_string and places the corresponding codeT structure in the codeP argument. The prototype of this function is defined in the lscgen.h (in Windows platform) and lsdecode.h (in UNIX platform) header file. To decode a license, first call the VLScgInitialize API to allocate resources required for decoding a license. Then, call VLScgDecodeLicenseExt API to decode the license. And then, call VLScgCleanup API to clean up the resources created by VLScgInitialize API. When decoding a license via the VLScgDecodeLicenseExt API function, the codeT structure returned does not contain the license secrets—instead the corresponding field contains an empty string.

10.126.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLScg_INVALID_INPUT

Argument specified is not correct, that is, one of the following reasons exist: n n

any_license_string or CodeP is NULL If license_string is not NULL and license_string_buflen is NULL.

10.126. VLScgDecodeLicenseExt

Error Code

453

Description n

n

If license_string is not NULL and license_string_buflen is <= 0 If any_license_string buffer size exceeds the maximum size limit specified as VLS_MAX_LICENSE_SIZE.

VLScg_DECRYPT_FAIL

This error code indicates that the API has failed to decode the specified license due to invalid license signature. The license signature refers to the authentication string ed along with the license string.

VLS_CALLING_ERROR

The argument specified is not correct.

LS_NO_RESOURCES

Error occurred in allocating resources needed by this API.

LS_BUFFER_TOO_SMALL

Allocated buffer is insufficient for this API.

VLScg_VENDOR_ENCRYPTION_ FAIL

Error occurs if vendor-customized encryption fails.

VLScg_MALLOC_FAILURE

Out of heap memory.

VlsCG_SHORT_STRING

Error occurs when the license code too small to parse.

VLScg_PREMATURE_TERM

Premature termination of license code.

VLScg_INVALID_CHARS

String is not valid.

VLScg_FIXED_STR_ERROR

Default fixed string error.

VLScg_INVALID_RANGE

Value violates the valid range of input.

VLScg_SIMPLE_ERROR

Error in license code.

For a complete list of the error codes, see License Generation Error Codes.

454

Chapter 10:  License Code Generation API

License Meter Related Functions The following table summarizes the license meter related functions: Function

Description

VLScgGetLicenseMeterUnits

Returns the number of license generation units.

VLScgGetTrialLicenseMeterUnits

Returns the number of trial license generation units.

10.127. VLScgGetLicenseMeterUnits

455

10.127. VLScgGetLicenseMeterUnits 10.127.1. Syntax int VLScgGetLicenseMeterUnits ( VLScg_HANDLE

iHandle,

long

*initialUnitsP,

long

*unitsLeftP,

int

codegen_version );

Argument

Description

iHandle

The instance handle for this library.

initialUnitsP

The number of units that were initially available.

unitsLeftP

The number of units remaining.

codegen_version

Version of the code generator (7 for Sentinel RMS Development Kit 7.x and 8 for Sentinel RMS Development Kit 7.3.0 and greater).

10.127.2. Description Returns the number of license generation units available in the attached license meter key.

10.127.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following error codes: Error Code

Description

VLScg_LICMETER_EXCEPTION

Unknown value in accessing the license meter.

VLScg_LICMETER_ACCESS_ ERROR

Error accessing the license meter.

VLScg_LICMETER_CORRUPT

License meter is corrupted.

VLScg_LICMETER_VERSION_ MIS- License meter has an invalid version. MATCH VLScg_LICMETER_NOT_ ED

Your Sentinel RMS Development Kit License Meter is not ed.

For a complete list of the error codes, see License Generation Error Codes. On platforms that do not hardware keys, the function returns V_FAIL.

456

Chapter 10:  License Code Generation API

10.128. VLScgGetTrialLicenseMeterUnits 10.128.1. Syntax int VLScgGetTrialLicenseMeterUnits ( VLScg_HANDLE

iHandle,

int

units,

int

codegen_version );

Argument

Description

iHandle

The instance handle for this library.

units

The number of licenses available.

codegen_version

Version of the code generator (7 for Sentinel RMS 7.x and 8 for Sentinel RMS 7.3.0 and greater).

10.128.2. Description Returns the number of trial license generation units available in the attached license meter.

10.128.3. Returns The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error code is returned indicating the reason for failure. For a complete list of the error codes, see License Generation Error Codes.

License Revocation Functions

457

License Revocation Functions Given below is a list of the API functions: Function

Description

VLSgeneratePermissionTicket

Generates a permission ticket for stand-alone licenses only.

VLSgeneratePermissionTicketExt

Generates a permission ticket for stand-alone and network licenses. Verifies the returned revocation ticket with the original request for stand-alone licenses only.

VLSRevocationTicket VLSRevocationTicketExt

Verifies the returned revocation ticket with the permission ticket (whether ed as a request structure or as binary data) for stand-alone and network licenses.

VLScgDecodeLicenseRevocationTicket

Decodes the license revocation ticket (LRT) generated the pre 8.4.1 network revocation workflow. Decodes all types of revocation tickets.

VLScgDecodeLicenseRevocationTicketExt

458

Chapter 10:  License Code Generation API

10.129. VLSgeneratePermissionTicket 10.129.1. Syntax LS_STATUS_CODE

VLSgeneratePermissionTicket (

PVPT_REQUEST

pvRequest,

unsigned char

*puermissionTicket,

unsigned int

*pui16PermissionTicketLength );

Argument

Description

pvRequest

An IN parameter. A pointer to the structure containing request data.

puermissionTicket

An OUT parameter. A pointer to the generated permission ticket. The memory needs to be allocated by the caller.

pui16PermissionTicketLength

An IN/OUT parameter. The length of the generated permission ticket.

10.129.2. Description This function is used to generate a permission ticket for stand-alone license revocation/addition that can be processed on the client side. You can create a customized application that calls this API function when a customer sends the revocation request. If the puermissionTicket argument is ed as NULL or its length is less than the length of the generated permission ticket, the function will return the required length. The caller needs to allocate the required memory and call the API function again.

10.129.3. Returns The status code LS_SUCCESS is returned, if permission ticket is generated successfully. Otherwise, it will return the following error codes: Error Codes

VLScg_RT_INVALID_REQUEST_DATA

Description The requested data is invalid.

VLScg_RT_UNED_OPERATION_TYPE

The operation type is not 'A' or 'R'.

VLScg_RT_BUFFER_TOO_SMALL

The allocated memory is not enough.

VLScg_RT_PARAMETERS_ERROR

Invalid rehost parameters.

VLScg_RT_ALLOCATE_MEMORY_FAILURE

Failure in memory allocation.

10.130. VLSgeneratePermissionTicketExt

459

10.130. VLSgeneratePermissionTicketExt 10.130.1. Syntax LS_STATUS_CODE

VLSgeneratePermissionTicketExt (

PVPT_REQUEST

pvRequest,

unsigned char

*puermissionTicket,

unsigned int

*pui16PermissionTicketLength,

PVPT_REQUEST_EXT

pvRequestExt );

Argument

Description

pvRequest

An IN parameter. A pointer to the structure containing request data.

puermissionTicket

An OUT parameter. A pointer to the generated permission ticket. The memory needs to be allocated by the caller.

pui16PermissionTicketLength

An IN/OUT parameter. The length of the generated permission ticket.

pvRequestExt

An IN parameter. A pointer to the structure containing request data.

10.130.2. Description This function is used to generate a permission ticket for: n

Network license revocation for processing on the license server.

n

Stand-alone license revocation/addition that can be processed on the client side.

You can create a customized application that calls this API function. If the puermissionTicket argument is ed as NULL or its length is less than the length of the generated permission ticket, the function will return the required length. The caller needs to allocate the required memory and call the API function again.

10.130.3. Returns The status code LS_SUCCESS is returned, if permission ticket is generated successfully. Otherwise, it will return the following error codes: Error Codes

VLScg_RT_INVALID_REQUEST_DATA VLScg_RT_UNED_OPERATION_TYPE

Description The requested data is invalid. n

n

The operation type is not 'A' or 'R' for stand-alone licenses. The operation type is not 'P' or 'R' for network licenses.

VLScg_RT_BUFFER_TOO_SMALL

The allocated memory is not enough.

VLScg_RT_PARAMETERS_ERROR

Invalid rehost parameters.

460

Chapter 10:  License Code Generation API

Error Codes

VLScg_RT_ALLOCATE_MEMORY_FAILURE

Description Failure in memory allocation.

VLScg_RT_INSUFFICIENT_TOKENS_TO_REVOKE

The license tokens available for revocation are less than the number specified in the request structure.

VLScg_RT_MIXED_OPERATION_TYPE_UNED

You cannot revoke stand-alone and network licenses using a single permission ticket.

VLScg_RT_INFINITE_LIC_FINITE_REQ

Network licenses with infinite tokens cannot be partially revoked. Full revocation is required.

VLScg_RT_RDNT_LIC_UNSUPPORED

The permission ticket cannot be generated for redundant licenses.

VLScg_TOO_MANY_OPERATIONS_FOR_SINGLE_PT The number of operations specified in the permission ticket exceed the maximum limit. You cannot specify more than 15 operations in a permission ticket for a network license. VLScg_VENDOR_ID_MISMATCH

Vendor ID mismatch. The permission ticket cannot be generated for licenses of other vendors.

VLScg_CODGEN_VERSION_UNED

The permission ticket generation not ed for licenses earlier than version 11.

10.131. VLSRevocationTicket

461

10.131. VLSRevocationTicket 10.131.1. Syntax LS_STATUS_CODE VLSRevocationTicket ( PVPT_REQUEST pvOriginalRequest, unsigned char *pucRevocationTicket, unsigned long ulRevocationTicketLength, PVRT__ERRORS pvErrorInfo, unsigned long *pulErrorInfoTotalLength );

Argument

Description

pvOriginalRequest

An IN parameter. A pointer to the structure containing data for the original request.

pucRevocationTicket

An IN parameter. A pointer to the returned revocation ticket.

ulRevocationTicketLength

An IN parameter. The length of the revocation ticket.

pvErrorInfo

An OUT parameter. A pointer to the structure to store the error report. The memory needs to be allocated by the caller.

pulErrorInfoTotalLength

An IN/OUT parameter. The size of the pvErrorInfo argument.

10.131.2. Description This function verifies the returned stand-alone revocation ticket with the original request described in the permission ticket. You can create a customized application that calls this API function when a customer sends the revocation request. If the pvErrorInfo argument is ed as NULL or the length is less than the size required for the error report, the function will return the required length. The caller needs to allocate the required memory and call the API again. The API does not the information contained in pucVendorDefined.

10.131.3. Returns The status code LS_SUCCESS is returned, if revocation ticket is verified successfully. Otherwise, it will return the following error codes: Error Codes

VLScg_RT_PARAMETERS_ERROR

Description Invalid rehost parameters.

VLScg_RT_ALLOCATE_MEMORY_FAILURE

Failure in memory allocation.

462

Chapter 10:  License Code Generation API

Error Codes

VLScg_RT_VERSION_MISMATCH

Description Rehost ticket version mismatch.

VLScg_RT_REHOST_LINE_CORRUPT

Rehost ticket line is corrupt.

VLScg_RT_TRANSACTION_ID_MISMATCH

Transaction Id in rehost ticket is different from in request.

VLScg_RT_LOCK_CODE_MISMATCH

Lock code in rehost ticket is different from in request.

VLScg_RT_REQUESTED_ACTION_NOT_PERFORMED

Actions requested are not performed.

VLScg_RT_NON_REQUESTED_ACTION_PERFORMED

Action performed was not requested.

VLScg_RT_ACTION_STATUS_NOT_SUCCESS

Requested action failed.

VLScg_RT_REQUEST_EMPTY

Request is empty.

VLScg_RT_REQUEST_LINE_INVALID

Requested line is invalid.

VLScg_RT_REHOST_TICKET_INVALID_TLV_ STRUCT

Rehost ticket is an invalid TLV (Tag-Length-Value) structure.

VLScg_RT_REHOST_TAG_MISSING

Rehost tag is missing in the rehost ticket.

VLScg_RT_VERSION_TAG_MISSING

Version tag is missing in the rehost ticket.

VLScg_RT_TRANSACTION_ID_TAG_MISSING

Transaction Id tag is missing in the rehost ticket.

VLScg_RT_LOCK_SELECTOR_TAG_MISSING

Lock selector tag is missing in the rehost ticket.

VLScg_RT_LOCK_SELECTOR_MISMATCH

Lock selector is different from in request.

VLScg_RT_LOCK_CODE_TAG_MISSING

Lock code is different from in request.

VLScg_RT_HASH_TAG_MISSING

Hash tag is missing in the rehost ticket.

VLScg_RT__SINGLE_ERROR

Only one error in rehost ticket. if the operation type is specified as NULL.

VLScg_RT__MULTIPLE_ERRORS

Multiple errors in rehost ticket.

VLScg_RT_TIME_STAMP_MISMATCH

Mismatch in time stamp.

VLScg_RT_TIME_STAMP_TAG_MISSING

Mismatch in time stamp tag.

10.132. VLSRevocationTicketExt

463

10.132. VLSRevocationTicketExt 10.132.1. Syntax LS_STATUS_CODE VLSRevocationTicketExt ( PVPT_REQUEST_EXT pvOriginalRequestExt, unsigned char *puermissionTicket, unsigned long ulPermissionTicketLength, unsigned char *pucRevocationTicket, unsigned long ulRevocationTicketLength, PVRT__ERRORS pvErrorInfo, unsigned long *pulErrorInfoTotalLength, unsigned long *unused );

Argument

Description

pvOriginalRequestExt

An IN parameter. A pointer to the structure containing data for the original request. Specify NULL if ing permission ticket in binary format.

puermissionTicket

An IN parameter. A pointer to the permission ticket (in binary format). Specify NULL if ing permission ticket as a structure.

ulPermissionTicketLength

An IN parameter. The length of the permission ticket. Specify 0 if the permission ticket request structure is ed. An IN parameter. A pointer to the returned revocation ticket.

pucRevocationTicket ulRevocationTicketLength

An IN parameter. The length of the revocation ticket.

pvErrorInfo

An OUT parameter. A pointer to the structure to store the error report. The memory needs to be allocated by the caller.

pulErrorInfoTotalLength

An IN/OUT parameter. The size of the pvErrorInfo argument.

unused

Reserved for future use.

10.132.2. Description This function is an extended version of VLSRevocationTicket. The VLSRevocationTicketExt API verifies the returned revocation ticket with the original request described in the permission ticket, for both stand-alone and network revocation scenarios. The API provides you the flexibility to the permission ticket as a structure (similar to VLSRevocationTicket) or directly in the format it is generated (binary format). In case, the revocation ticket contains any status—other than success—then the field pucLicenseLine of structure PVRT__ERROR_LINE will contain a license line only if:

464

Chapter 10:  License Code Generation API

n

n

A stand-alone revocation ticket was ed. Or, a network revocation ticket was verified against the original structure of a permission ticket.

Else, the field pucLicenseLine will contain license hash, feature, and version information. You can create a customized application that calls this API function when a customer sends the revocation request. If the pvErrorInfo argument is ed as NULL or the length is less than the size required for the error report, the function will return the required length. The caller needs to allocate the required memory and call the API again. The API does not the information contained in pucVendorDefined (the custom information that you can specify for each operation). However, it does the pucCustomDefined (the custom information that you can specify for a permission ticket).

10.132.3. Returns The status code LS_SUCCESS is returned, if revocation ticket is verified successfully. Otherwise, it will return the following error codes: Error Codes

VLScg_RT_PARAMETERS_ERROR

Description Invalid rehost parameters.

VLScg_RT_ALLOCATE_MEMORY_FAILURE

Failure in memory allocation.

VLScg_RT_VERSION_MISMATCH

Revocation ticket version mismatch.

VLScg_RT_REHOST_LINE_CORRUPT

Revocation ticket line is corrupt.

VLScg_RT_TRANSACTION_ID_MISMATCH

Transaction ID in revocation ticket is different from in request.

VLScg_RT_LOCK_CODE_MISMATCH

Lock code in revocation ticket is different from in request.

VLScg_RT_REQUESTED_ACTION_NOT_PERFORMED

Actions requested are not performed.

VLScg_RT_NON_REQUESTED_ACTION_PERFORMED

Action performed was not requested.

VLScg_RT_ACTION_STATUS_NOT_SUCCESS

Requested action failed.

VLScg_RT_REQUEST_EMPTY

Request is empty.

VLScg_RT_REQUEST_LINE_INVALID

Requested line is invalid.

VLScg_RT_REHOST_TICKET_INVALID_TLV_ STRUCT

Revocation ticket is an invalid TLV (Tag-LengthValue) structure.

VLScg_RT_REHOST_TAG_MISSING

Rehost tag is missing in the revocation ticket.

VLScg_RT_VERSION_TAG_MISSING

Version tag is missing in the revocation ticket.

VLScg_RT_TRANSACTION_ID_TAG_MISSING

Transaction ID tag is missing in the revocation ticket.

10.132. VLSRevocationTicketExt

Error Codes

465

VLScg_RT_LOCK_SELECTOR_TAG_MISSING

Description Lock selector tag is missing in the revocation ticket.

VLScg_RT_LOCK_SELECTOR_MISMATCH

Lock selector is different from in request.

VLScg_RT_LOCK_CODE_TAG_MISSING

Lock code is different from in request.

VLScg_RT_HASH_TAG_MISSING

Hash tag is missing in the revocation ticket.

VLScg_RT__SINGLE_ERROR

Only one error in revocation ticket. if the operation type is specified as NULL.

VLScg_RT__MULTIPLE_ERRORS

Multiple errors in revocation ticket.

VLScg_RT_TIME_STAMP_MISMATCH

Mismatch in time stamp.

VLScg_RT_TIME_STAMP_TAG_MISSING

Mismatch in time stamp tag.

VLScg_RT_CORRUPT_ORIG_REQ

The permission ticket provided for verification is corrupt.

VLScg_RT_CUSTOM_DATA_TAG_MISSING

The custom defined data tag is not found in the revocation ticket.

VLScg_RT_CUSTOM_DATA_MISMATCH

The custom defined data included in the permission ticket and revocation ticket does not match.

VLScg_RT_REVOCATION_TYPE_MISMATCH

Either standalone revoke request is provided to with a network revocation ticket, or vice versa.

466

Chapter 10:  License Code Generation API

10.133. VLScgDecodeLicenseRevocationTicket 10.133.1. Syntax int char int char int VLSrevocationTicketInfoT

VLScgDecodeLicenseRevocationTicket ( *license_revocation_ticket_buffer, license_revocation_ticket_buffer_size, *secret_key, secret_key_length, *revocation_ticket );

Argument

Description

license_revocation_ticket_buffer

An IN parameter. A buffer that holds the string data returned by the VLSrevokeLicense API function.

license_revocation_ticket_buffer_size An IN parameter. A buffer that defines the size of the ticket. secret_key

An IN parameter. Refers to the first secret specified in the license code. It is used by the license server for generating the encrypted license revocation ticket. If there is no secret specified (when challenge-response mechanism is not used), specify secret_key as NULL or set secret_key_length to zero.

secret_key_length

An IN parameter. The length of the secret key.

revocation_ticket

An OUT parameter. The VLSrevocationTicketInfoT structure.

10.133.2. Description Decodes the license revocation ticket (LRT) generated the pre 8.4.1 network revocation workflow (refer to the Appendix - "Network License Revocation Prior to the 8.4.1 Release" of the Sentinel RMS SDK Developer's Guide).

10.133.3. Returns The status code VLScg_SUCCESS is returned if successful. Refer to the error codes given in License Generation Error Codes.

10.134. VLScgDecodeLicenseRevocationTicketExt

467

10.134. VLScgDecodeLicenseRevocationTicketExt 10.134.1. Syntax int

VLScgDecodeLicenseRevocationTicketExt (

char

*license_revocation_ticket_buffer_old,

int

license_revocation_ticket_buffer_old_size,

unsigned char

revocation_ticket_buffer,

unsigned long

revocation_ticket_buffer_size,

char int VLSrevocationTicketInfoT PVRT_REVOKE_TICKET_INFO

*secret_key, secret_key_length, *license_revocation_ticket_old, revocation_ticket,

unsigned long

*pulRevocation_ticket_size,

unsigned long

*unused );

Argument

Description

license_revocation_ticket_buffer_old

An IN parameter. A buffer that holds the string data returned by the VLSrevokeLicense API function. In response, the structure VLSrevocationTicketInfoT is filled and returned. Specify NULL, if using the license_revocation_ ticket_buffer described below.

license_revocation_ticket_buffer_old_size

An IN parameter. A buffer that defines the size of the ticket returned by the VLSrevokeLicense API function. An IN parameter. A buffer that holds the string data returned by the VLSrevokeByPermissionTicket API function. In response, the structure PVRT_REVOKE_TICKET_ INFO is filled and returned. Specify NULL, if using the license_revocation_ ticket_buffer_old described above.

revocation_ticket_buffer

revocation_ticket_buffer_size,

An IN parameter. A buffer that defines the size of the ticket returned by the VLSrevokeByPermissionTicket API function.

secret_key

An IN parameter. Refers to the first secret specified in the license code. It is used by the license server for generating the encrypted license revocation ticket. If there is no secret specified (when challenge-response mechanism is not used), specify secret_key as NULL or set secret_key_length to zero.

468

Chapter 10:  License Code Generation API

Argument

Description

secret_key_length

An IN parameter. The length of the secret key. An OUT parameter. The VLSrevocationTicketInfoT structure. An OUT parameter. The VRT_REVOKE_TICKET_ INFO structure.

license_revocation_ticket_old revocation_ticket pulRevocation_ticket_size

An OUT parameter. A buffer that defines the size of the revocation ticket. If the VRT_REVOKE_TICKET_ INFO structure is ed as NULL, then it will return the length in the pulRevocation_ticket_size parameter.

unused

Reserved for future use.

10.134.2. Description Decodes all types of revocation tickets generated, which are: n

The license revocation ticket (LRT) generated using the pre 8.4.1 network revocation model.

n

The stand-alone revocation tickets (which can also be decoded using VLScgDecodeLicense).

n

The network revocation tickets generated using the workflow introduced in the v8.4.1.

10.134.3. Returns The status code VLScg_SUCCESS is returned if successful. Refer to the error codes given in License Generation Error Codes.

10.135. VPT_REQUEST_LINE

10.135. VPT_REQUEST_LINE 10.135.1. Syntax typedef struct _VPT_REQUEST_LINE { unsigned char

ucOperation;

unsigned char

*pucVendorDefined;

unsigned long

ulVendorDefinedLength;

unsigned char

*pucLicenseLine;

unsigned long

ulLicenseLineLength;

} VPT_REQUEST_LINE, *PVPT_REQUEST_

Member ucOperation

LINE;

Description The requested operation. The possible values are: n n

A: add a new license R: completely revoke a license

pucVendorDefined

The vendor defined data. If there is no vendor defined data, the pucVendorDefined argument must be NULL. In this case, the ulVendorDefinedLength argument is ignored.

ulVendorDefinedLength

The length of the vendor defined data.

pucLicenseLine

The license string to be added or revoked.

ulLicenseLineLength

The length of license string to be added or revoked.

469

470

Chapter 10:  License Code Generation API

10.136. VPT_REQUEST 10.136.1. Syntax typedef struct _VPT_REQUEST { unsigned char

*pucTransactionId;

unsigned long

ulLockCodeSelector;

unsigned char

* pucLockInfo;

unsigned long

ulTimeStamp;

unsigned long

ulRequestArraySize;

PVPT_REQUEST_LINE

pvRequestArray;

} VPT_REQUEST, *PVPT_REQUEST;

Member pucTransactionId

Description The transaction ID to uniquely identify a permission ticket to be generated.

ulLockCodeSelector

The lock code selector.

pucLockInfo

The locking information of the target lock selector.

ulTimeStamp

The time stamp of the permission ticket to be generated.

ulRequestArraySize

The number of requests.

pvRequestArray

A pointer to an array of structures for the requested operations and licenses.

10.137. VPT_REQUEST_LINE_EXT

10.137. VPT_REQUEST_LINE_EXT 10.137.1. Syntax typedef struct _VPT_REQUEST_LINE_EXT { unsigned long struct_size; unsigned char ucOperation; unsigned int hard_limit_to_revoke; unsigned char *pucVendorDefined; unsigned long ulVendorDefinedLength; unsigned char *pucLicenseLine; unsigned long ulLicenseLineLength; } VPT_REQUEST_LINE_EXT, *PVPT_REQUEST_LINE_EXT;

Member

Description

struct_size

The size of the structure. The requested operation. The possible values for stand-alone licenses are:

ucOperation

n n

A: Adds a new license. R: Completely revokes a license.

The possible values for network licenses are: n

n

P: For partial revocation. Revokes the number of tokens less than or equal to hard limit. R: Completely revokes a license.

hard_limit_to_revoke

Specify the number of tokens of a license to be revoked. Required for partial network license revocation only. Set 0 for stand-alone license revocation and full network license revocation requests.

pucVendorDefined

The vendor defined data. If there is no vendor defined data, the pucVendorDefined argument must be NULL. In this case, the ulVendorDefinedLength argument is ignored.

ulVendorDefinedLength

The length of the vendor defined data.

pucLicenseLine

The license string to be added or revoked.

ulLicenseLineLength

The length of license string to be added or revoked.

471

472

Chapter 10:  License Code Generation API

10.138. VPT_REQUEST_EXT 10.138.1. Syntax typedef struct _VPT_REQUEST_EXT { unsigned long struct_size; unsigned char *pucTransactionId; unsigned long ulLockCodeSelector; unsigned char *pucLockInfo; unsigned long ulTimeStamp; unsigned char *pucCustomDefined; unsigned long ulCustomDefinedLength; unsigned long ulRequestArraySize; PVPT_REQUEST_LINE_EXT pvRequestArrayExt; } VPT_REQUEST_EXT, *PVPT_REQUEST_EXT;

Member

Description

struct_size

The size of the structure.

pucTransactionId

The transaction ID to uniquely identify a permission ticket to be generated.

ulLockCodeSelector pucLockInfo

The lock code selector.

ulTimeStamp

The time stamp of the permission ticket to be generated. The vendor defined custom data contained in the permission ticket. Can contain up to 384 alpha-numeric characters. Specify NULL, in case of no vendor defined custom data. The ulCustomDefinedLength argument is ignored in case pucCustomDefined is set to NULL.

pucCustomDefined

The locking information of the target lock selector.

ulCustomDefinedLength

The length of the vendor defined custom data.

ulRequestArraySize

The number of requests.

pvRequestArrayExt

A pointer to an array of structures for the requested operations and licenses.

10.139. VRT__ERROR_LINE

10.139. VRT__ERROR_LINE 10.139.1. Syntax typedef struct

_VRT__ERROR_LINE {

unsigned long

ulErrorCode;

unsigned char

ucOperation;

unsigned long

ulStatus;

unsigned char

pucLicenseLine[VLS_MAX_CUSTOM_LICENSE_SIZE];

unsigned long

ulLicenseLineLength;

unsigned long

ulCapacityRevoked;

unsigned long

ulNumberOfLicensesRevoked;

} VRT_

Member ulErrorCode

ucOperation

_ERROR_LINE, *PVRT__ERROR_LINE;

Description The error reported by the verification process. Depending on the source of the error it is possible that only this member of the structure is present and the others are ignored. This happens when the error is related to either the validity of the revocation ticket (for example, invalid format or the ticket is corrupt) or non-action related error (for example, Permission Id or Lock Code mismatch). Any of these requested / performed operation. The possible values are: n n n

ulStatus

A: add a new license R: completely revoke a license P: partially revoke a license

The reported status of the performed operation. When any requested action fails, the VLSrevokeByPermissionTicket API does not generate revocation ticket at all. Usually, you will never encounter failure status in a revocation ticket.

473

474

Chapter 10:  License Code Generation API

Member pucLicenseLine

Description The license line, either from the original request (if it was not performed) or from the revocation ticket (if the status was non-success or it is something that never asked for by the original request). In case, the revocation ticket contains any status— other than success—then pucLicenseLine will contain a license line only if: n n

A stand-alone revocation ticket was ed. Or, a network revocation ticket was verified against the original structure of a permission ticket.

ulLicenseLineLength

The length of the license line.

ulCapacityRevoked

The capacity revoked. Unused.

ulNumberOfLicensesRevoked The number of licenses revoked.

10.140. VRT__ERRORS

10.140. VRT__ERRORS typedef struct _VRT__ERRORS { unsigned long VRT__ERROR_LINE } VRT__ERRORS,

Member

ulNumOfErrors; *pvRTErrorArray; *PVRT__ERRORS;

ulNumOfErrors

Description The number of errors stored in the array structure.

pvRTErrorArray

A pointer to an array of structures for reporting errors.

475

476

Chapter 10:  License Code Generation API

10.141. VRT_REVOKE_TICKET_LINE 10.141.1. Syntax typedef struct

_VRT_REVOKE_TICKET_LINE {

unsigned long

struct_size;

unsigned char

feature_name[VLS_MAXFEALEN];

unsigned char

feature_version[VLS_MAXFEALEN];

unsigned char

*pucLicenseHash;

unsigned char

*pucLicenseLine;

unsigned long

ulLicenseLineLength;

unsigned char

ucOperation;

unsigned int

base_license_hard_limit;

unsigned int

number_licenses_revoked;

unsigned int

status;

unsigned long

*unused1;

unsigned int

unused2;

} VRT_REVOKE_TICKET_LINE,

Member struct_size

*PVRT__ERROR_LINE;

Description The size of the structure.

feature_name

The feature name for which the revocation ticket (RT) was generated. Required for network license revocation only.

feature_version

The feature version for which the revocation ticket (RT) was generated. Required for network license revocation only.

pucLicenseHash

A pointer to the license hash. For network revocation only.

pucLicenseLine ulLicenseLineLength

A pointer to the license string. For stand-alone revocation only. The length of the license string. For stand-alone revocation only.

ucOperation

The operation type (add, full revocation, or partial revocation).

base_license_hard_limit

The hard limit of the license. For network revocation only.

number_licenses_revoked

The number of license tokens revoked. For network revocation only.

status

Status corresponding to the operations executed.

unused1

Reserved for future use.

unused2

Reserved for future use.

10.142. VRT_REVOKE_TICKET_INFO

10.142. VRT_REVOKE_TICKET_INFO typedef struct _VRT_REVOKE_TICKET_INFO { unsigned long struct_size; unsigned char *pucTransactionId; unsigned long locking_criteria; unsigned char *locking_info; unsigned long time_stamp; unsigned char *pucCustomDefined; unsigned long ulCustomDefinedLength; PVRT_REVOKE_TICKET_LINE pvRevokeInfoArray; unsigned long ulRevokeInfoArraySize; unsigned long *unused1; unsigned int unused2; } VRT_REVOKE_TICKET_INFO, *PVRT_REVOKE_TICKET_INFO;

Member struct_size

Description The size of the structure.

pucTransactionId

A pointer to the transaction ID (uniquely identifies a permission ticket).

locking_criteria

The locking criteria of the target system.

locking_info

The locking information of the target system.

time_stamp

The time stamp as specified while generating the permission ticket.

pucCustomDefined

A pointer to the vendor defined custom data as specified while generating the permission ticket.

ulCustomDefinedLength

The length of the vendor defined custom data.

pvRevokeInfoArray ulRevokeInfoArraySize

A pointer to the array containing the revocation information. A size of the pvRevokeInfoArray array.

unused1

Reserved for future use.

unused2

Reserved for future use.

477

478

Chapter 10:  License Code Generation API

10.143. VLSrevocationTicketInfoT The VLSrevocationTicketInfoT structure used by the VLScgDecodeLicenseRevocationTicket function.

10.143.1. Syntax typedef struct { unsigned long

struct_size;

unsigned long

time_stamp;

unsigned char

feature_name[VLS_MAXFEALEN];

unsigned char

feature_version[VLS_MAXFEALEN];

unsigned long

capacity;

unsigned int

base_license_hard_limit;

unsigned int

number_licenses_revoked;

unsigned int

total_number_licenses_revoked;

unsigned long

capacity_revoked;

unsigned long

server_locking_criteria;

unsigned char

server_locking_info[VLS_MAXSRVLOCKLEN];

} VLSrevocationTicketInfoT;

Member

Description

struct_size

The size of the structure.

time_stamp

The time when the license revocation ticket was generated.

feature_name

The feature name for which the license revocation ticket was generated.

feature_version

The feature version for which the license revocation ticket was generated.

capacity

The capacity of the feature whose license revocation ticket was generated.

base_license_hard_limit

The hard limit of the feature whose license revocation ticket was generated.

number_licenses_revoked

The number of licenses revoked.

total_number_licenses_revoked

The total number of licenses revoked for a feature.

capacity_revoked

The capacity of the feature revoked.

server_locking_criteria

The locking criteria of the license server on which the revocation was executed.

11 Chapter 11: System Initialization API This chapter discusses the system initialization API functions, contained in the lsinit library. You must initialize the system for setting up the persistence data for the stand-alone license models, such as a trial license or a checked-out commuter license. For understanding the importance of system initialization, refer to the Chapter 3 - Planning the Application Protection of the Sentinel RMS SDK Developer’s Guide. Given below is a list of the API functions:

Function

Description

sntlInitStandaloneSystem Initializes the client or stand-alone system with the persistence information. sntlInitNetworkSystem

Sets up the license server for persistence information

480

Chapter 11:  System Initialization API

11.1. sntlInitStandaloneSystem 11.1.1. Header Include lsinit.h

11.1.2. Library n

Windows - lsinit32.lib (both MT and MD versions), lsinit32.dll

n

UNIX - liblsinit.a, liblsinit.so

11.1.3. Description Initializes the client or stand-alone system with the persistence information. If the licensed application does not find the persistence data at the time of requesting a license, it will generate an error. The use of this function in your application installer will also ensure that your licensed application is not installed more than once on a system. It is a must to initialize the system in mode before running any local request application or checking out a token for normal .

11.1.4. Syntax int

sntlInitStandaloneSystem (

char

*GUID,

char

*featureName,

char

*featureVersion );

Argument

Description

GUID

The application installer's GUID.£ The application feature name.

featureName

The application feature version. featureVersion £ Stands for Global Unique Identifier—a unique 128-bit number that is produced by the Windows operating system or by some Windows applications to identify a particular component, application, file, database entry, and/or .

On Windows, this function needs to be called for every stand-alone application with unique values of input parameters, else the function will return an error. On UNIX, the API parameters are not significant and can be ed as NULL. In case any values are specified they shall be ignored on UNIX systems. The function must be called only once to initialize the system.

11.1. sntlInitStandaloneSystem

481

The feature-version were made necessary for UNIX based developers using version 8.0.9 of the RMS SDK. This was to maintain the license persistence information. However, post the 8.2.1 release, NULL can be specified.

11.1.5. Returns The status code ERR_KEY_INFO_SUCCESS is returned if successful. Otherwise, a specific status code is returned indicating the reason for failure. For a list of error codes, see System Initialization Error Codes.

11.1.6. Example A sample file in C (initdemo.c) is provided to illustrate the use of the function. n

For Windows, it is installed at \English\MsvcDev\Samples\API.

n

For UNIX, it is installed at /examples.

482

Chapter 11:  System Initialization API

11.2. sntlInitNetworkSystem 11.2.1. Header Include lsinit.h

11.2.2. Library n

Windows - lsinit32.lib (both MT and MD versions), lsinit32.dll

n

UNIX - lsinit32.a, lsinit32.so

11.2.3. Description This function sets the requisite permissions for the Sentinel RMS registry keys (if applicable) and files at the time of system initialization. However, if you are going to integrate the license server installer in your Windows installer, there is no need to call this function for system initialization on the license server end. On UNIX, network initialization is done automatically by the license server, and there is no need for explicit initialization.

I M P ORTAN T Sinc e the 8 .4 .0 r e le ase , the se r ve r -side c om m ute r pe r siste nc e ar c hite c tur e has b e e n m o d ifie d . Th e e ar lie r p e r siste n c e d ata w ill b e m igr ate d au to m atic ally b y using the upgr ade d lic e nse se r ve r (v8 .4 .0 or late r ). How e ve r , the m igr ation c annot be done thr ough this A P I.

11.2.4. For Windows Syntax

int sntlInitNetworkSystem (void) Returns

The status code ERR_KEY_INFO_SUCCESS is returned always. Example

A sample file in C (initdemo.c) is provided to illustrate the use of the function. For Windows, it is installed at \English\MsvcDev\Samples\API. For UNIX, it is installed at /examples.

12 Chapter 12: Persistence Cleaning API This topic discusses the persistence cleaning API functions, contained in the lsclean library. For understanding the complete process of persistence cleaning, refer to the Sentinel RMS SDK Developer’s Guide. Given below is a list of the API functions:

Function

Description

VLScleanStandalonePersistenceInfo For cleaning up and repairing the persistence information on a stand-alone system. VLScleanNetworkPersistenceInfo

For cleaning up and repairing the persistence information on a license server.

The APIs can clean up the following types of persistence database: n

Trial license (VLS_TRIAL_STORE)

n

Commuter license (VLS_COMMUTER_STORE)

n

Time tampered license (VLS_TIME_TAMPER_STORE)

n

License revocation (VLS_REVOKE_STORE)

n

Grace license (VLS_GRACE_STORE)

n

Volume transaction licenses (VLS_VTL_STORE)

484

Chapter 12: Persistence Cleaning API

12.1. VLScleanStandalonePersistenceInfo 12.1.1. Header and Library n

Include lsclean.h

n

lsclean32.lib (MD, MT, and MDd)

12.1.2. Description The API function can be used for cleaning or repairing the following type of information in case of stand-alone licensing:

                         Licensing Library Versions 8.1.0 or later 8.0.x

7.3.x

7.2.x

Trial

√ (Repairing only)

√

√

√

Commuter

√

√

√

√

Time-tamper

√

√

√

√

Grace

√

√

NA

NA

Revocation

√ (Repairing only)

NA

NA

NA

Volume Transaction

√ (Repairing only)

NA

NA

NA

Stand-alone Persistence Type

12.1.3. Syntax LS_STATUS_CODE

clientLibVersion,

int

persistenceType,

char*

featureName,

char*

featureVersion,

char*

unused1,

int

Argument

VLScleanStandalonePersistenceInfo (

int

unused2 );

Direction

clientLibVersion IN

Data Description Type int

The licensing library's version. Specify any of the following: n

7 - For the licensing library version 7.2.x and

12.1. VLScleanStandalonePersistenceInfo

Argument

Direction

Data Description Type n n

n n

persistenceType IN

485

int

7.3.x 8 - For the licensing library version 8.0.x 82 - For the licensing library version 8.1.x and 8.2.x 83 - For the RMS license server version 8.3.x 84 - For the RMS license server version 8.4.x

The persistence type. Specify any of the following: n n n n n n

1 - For VLS_TRIAL_STORE 2 - For VLS_COMMUTER_STORE 3 - For VLS_TIME_TAMPER_STORE 4 - For VLS_REVOKE_STORE 5 - For VLS_GRACE_STORE 6 - For VLS_VTL_STORE

featureName

IN

char* The feature name of the license. Should not be of zero length and must not exceed 24 characters.

featureVersion

IN

char* The version of the license. Must not exceed 11 characters.

Call this API function with proper arguments to clean a particular persistence. No preprocessing (initialization) or post-processing (cleanup) is required. NULL value must be ed to the arguments that are not applicable to a particular scenario. For example, feature name and version must be ed as NULL for repairing the: n

Trial license persistence (version 8.1.x or higher)

n

Stand-alone revocation persistence (version 8.2.x or higher)

n

Volume transaction license persistence (version 8.2.x or higher)

In case of trial license repairing, this is equivalent to the following command of lsclean: lsclean -fixtrial

You need to the same values to the applicable arguments while generating a cleaning license using lscgcln. Refer to the Sentinel RMS SDK Developer's Guide for details about generating a cleaning license.

12.1.4. Returns The status code VLScl_SUCCESS is returned, if successful. Otherwise, any of the error codes listed here will be returned.

486

Chapter 12: Persistence Cleaning API

12.2. VLScleanNetworkPersistenceInfo 12.2.1. Header and Library n

Include lsclean.h

n

lsclean32.lib (MD, MT, and MDd)

12.2.2. Description The API function can be used for cleaning or repairing the following type of information in case of network licensing:

                         Licensing Server Versions Network Persistence Type

8.4.x - 8.5.x

8.1.x - 8.3.x

8.0.x

7.2.x - 7.3.x

Trial

NA

√ (Repairing only)

√

√

Commuter

√

√

√

√

Time-tamper

NA

√

√

√

Revocation

NA

√ (Repairing only)

√

NA

Volume Transaction

NA

√ (Repairing only)

NA

NA

12.2.3. Syntax LS_STATUS_CODE

VLScleanNetworkPersistenceInfo(

int serverVersion, int persistenceType, char* featureName, char* featureVersion, char* hostName, char* unused1, int operationType);

Argument serverVersion

Direction

Data Type

Description

IN

int

The license server version. Specify any of the following: n

n

7 - For the RMS license server version 7.2.x and 7.3.x 8 - For the RMS license server version 8.0.x

12.2. VLScleanNetworkPersistenceInfo

Argument

Direction

Data Type

Description n

n n

persistenceType IN

int

n n n n n

IN

char*

82 - For the RMS license server version 8.1.x and 8.2.x 83 - For the RMS license server version 8.3.x 84 - For the RMS license server version 8.4.x and 8.5.x

The persistence type. Specify any of the following: n

featureName

487

1 - For VLS_TRIAL_STORE 2 - For VLS_COMMUTER_STORE 3 - For VLS_TIME_TAMPER_STORE 4 - For VLS_REVOKE_STORE 5 - For VLS_GRACE_STORE 6 - For VLS_VTL_STORE

The feature name of the license. Should not be of zero length and must not exceed 24 characters. The feature and version parameters are not required for cleaning the version 13 (generated using RMS v 8.4.0 or later) server-side commuter and repository licenses.

featureVersion

IN

char*

hostName

IN

char*

unused1

IN

char*

operationType

IN

int

The version of the license. Must not exceed 11 characters. The hostname of the system whose commuter check out information is to be cleaned from the server persistence. The NULL value shall be used to clean the information of all clients. It cannot exceed 64 characters. Unused. Set to any of the following: n

n

VLS_LPR_COMMUTER_CLEAN - For cleaning up commuter data. VLS_LPR_COMMUTER_REPAIR - For recovering commuter data.

For details, see Scenario - Commuter Persistence Cleaning on the License Server. Call this API function with proper arguments to clean a particular persistence. No preprocessing (initialization) or post-processing (cleanup) is required. You need to the same values to the applicable arguments while generating a cleaning license using lscgcln. Refer to the Sentinel RMS SDK Developer's Guide for details about generating a cleaning license.

488

Chapter 12: Persistence Cleaning API

NULL value must be ed to the arguments that are not applicable to a particular scenario. For example, host name, feature name, and version must be ed as NULL for repairing the: n

Trial license persistence (version 8.1.x or higher)

n

Volume transaction license persistence (version 8.2.x or higher)

In case of volume transaction license repairing, this is equivalent to the following command of lsclean: lsclean -fixvtl

Scenario - Commuter Persistence Cleaning on the License Server Cle aning up of c om m ute r infor m ation on the lic e nse se r ve r m ight be r e quir e d w he n toke ns ar e c he c ke d out for m axim um dur ation and the c lie nt c om pute r has c r ashe d. To r e stor e the c he c ke d out toke n on the lic e nse se r ve r , c all the V L Sc le anN e tw or kPe r siste nc e Info API w ith the follow ing par am e te r s: • Spe c ify the lic e nse se r ve r ve r sion (1st par am e te r ) as 84 for lic e nse se r ve r ve r sion 8.4.0 and highe r (inc luding 8.5.0). • Spe c ify the host nam e par am e te r (5th par am e te r ) as the ac tual host nam e of the c lie nt as show n by 'hostnam e ' c om m and (c ase se nsitive ). • Spe c ify the ope r ationType par am e te r of int type (7th par am e te r ) as any of the follow ing:      • V L S_ L PR_ COMMU TE R_ CL E AN for c le aning up c om m ute r data.      • V L S_ L PR_ COMMU TE R_ RE PAIR for r e c ove r ing c om m ute r data. U nde r this sc e nar io, the API m ay r e tur n the follow ing e r r or s: • V L Sc l_ N O_ COMMU TE R_ IN FO_ FOU N D - N o c om m ute r pe r siste nc e infor m ation is found for the give n fe atur e -ve r sion. Pr obably, no c om m ute r toke ns ar e c he c ke d out for this fe atur e -ve r sion, or w he n the r e ar e c om m ute r c he c k outs for othe r fe atur e -ve r sion(s). • V L Sc l_ N O_ COMMU TE R_ FE ATU RE _ IN _ U SE – The c om m ute r infor m ation available for the fe atur e -ve r sion is for a diffe r e nt c lie nt. • V L Sc l_ IN V AL ID_ ARGU ME N TS – This e r r or m ay oc c ur w he n follow ing value s ar e e d for c le aning c om m ute r pe r siste nc e infor m ation:    • N U L L as the fe atur e nam e or host nam e .    •  Whe n the fe atur e nam e e d is gr e ate r than 24 c har ac te r s.    • Whe n the fe atur e ve r sion e d is gr e ate r than 11 c har ac te r s. • Whe n the host nam e e d is gr e ate r than 64 c har ac te r s.

   • 84 as the license server version and the o peratio nType value is other than VLS_LPR_COM M UTER_CLEAN and VLS_LPR_COM M UTER_REPAIR.

12.2. VLScleanNetworkPersistenceInfo

489

12.2.4. Returns The status code VLScl_SUCCESS is returned, if successful. Otherwise, any of the error codes listed here will be returned.

A Appendix A: Status Codes This section contains status codes for the following: n

Licensing APIs

n

License generation APIs

n

Upgrade license APIs

n

System initialization APIs

n

Persistence cleaning APIs

492

Appendix A: Status Codes

A.1. Licensing Library Error and Result Codes The table below contains the licensing library error messages and description: Error #

Error/Status Codes

Description

0x0

LS_SUCCESS

Successful operation.

0xC8001001

LS_BADHANDLE

The client handle refers to an invalid licensing system context.

0xC8001002

LS_INSUFFICIENTUNITS

Could not locate enough licensing resources to license this feature.

0xC8001003

LS_LICENSESYSNOTAVAILABLE

The licensing system is not available.

0xC8001004

LS_LICENSETERMINATED

Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed.

0xC8001005

LS_NOAUTHORIZATIONAVAILABLE

No license code is available for this feature on the specified host.

0xC8001006

LS_NOLICENSESAVAILABLE

All licensing tokens with the server for this feature are already in use.

0xC8001007

LS_NORESOURCES

Insufficient system resources are available to complete the request.

0xC8001008

LS_NO_NETWORK

Unable to talk to this host.

0xC8001009

LS_NO_MSG_TEXT

Unknown error code, cannot print the error message.

0xC800100A

LS_UNKNOWN_STATUS

Unknown error code, cannot print the error message.

0xC800100B

LS_BAD_INDEX

Bad index.

0xC800100C

LS_NO_MORE_UNITS

No additional units are available for this feature.

0xC800100D

LS_LICENSE_EXPIRED

The feature cannot run anymore because the license expiration date has reached. Check your machine's date and your vendor.

0xC800100E

LS_BUFFER_TOO_SMALL

Input buffer too small, string may be truncated.

0xC800100F

LS_NO_SUCCESS

Failed in performing the requisite operation.

0xC8001010

LS_GRACE_EXPIRED

The feature cannot run as the total number of days allowed in the grace period have been consumed.

0xC8001011

LS_GRACE_INVALID_STATE

This feature cannot run as an unexpected state of grace period is found.

0xC8001012

LS_GRACE_HOURS_EXHAUSTED The feature cannot run as the total number of hours allowed in the grace period have been consumed.

1

VLS_NO_LICENSE_GIVEN

2

VLS_APP_UNNAMED

Unable to obtain licensing token for this feature. Feature name or version cannot be NULL.

3

VLS_HOST_UNKNOWN

Failed to resolve the specified server host.

A.1. Licensing Library Error and Result Codes

493

Error #

Error/Status Codes

Description

4

VLS_NO_SERVER_FILE

Failed to figure out the license server correctly. Set the environment variable LSHOST to name(s) of server(s).

5

VLS_NO_SERVER_RUNNING

Cannot talk to the license server on the specified host. The license server is not running.

6

VLS_APP_NODE_LOCKED

The specified feature is not licensed to run on this machine due to server/client lock-code mismatch. This error results both in the case of locking mismatch on client or license server end. To better diagnose this condition, you should call VLSgetMachineID and VLSgetServInfo on client and server end, respectively. The locking information obtained then needs to be matched against the license code to know whether mismatch exists on the client or license server end.

7

VLS_NO_KEY_TO_RETURN

Attempt to return a non-existent token by the client application.

8

VLS_RETURN_FAILED

Failed to return the token issued for the specified feature.

9

VLS_NO_MORE_CLIENTS

No more clients exists for this feature.

10

VLS_NO_MORE_FEATURES

No more features available on license server.

11

VLS_CALLING_ERROR

Error in calling the API function. Check the calling parameters.

494

Appendix A: Status Codes

Error #

Error/Status Codes

Description

12

VLS_INTERNAL_ERROR

The possible causes are: n

n

n

n

n

13

Vendor ID mismatch. Please check if the client libraries and license generator belong to the same installation. Incorrect use of SharedID. The license library is not able to find the SharedID at runtime. Failure in parsing the license server name string while adding a server to the redundant pool. If using the license queuing feature, while removing a queue from the license server, if the server returns an error message other than VLS_CLIENT_NOT_AUTHORIZED. In this case check the client authorization whose request is on hold. In case of VLSrequestExt2/VLSqueuedRequestExt APIs, when auto update is on and the licensing library is not able to add a license to handle or the auto update list, or failed to start the license timer.

VLS_SEVERE_INTERNAL_ERROR The possible causes are: n n

n

n

The encryption operation has failed. The default function for obtaining hostname on which licensed application is running has failed. Please check hostname-IP resolution on a non-Windows machine. The system call fails while calculating time (localtime and localtime_r function on nonWindows OSes and time function on Window). The licensing library is unable to construct a message. If the encryption logic of messages is customized, this error might come due to customization logic failure. Please the encryption logic again.

14

VLS_NO_SERVER_RESPONSE

The license server on the specified host is not responding.

15

VLS__EXCLUDED

This /machine has been excluded from accessing the specified feature.

16

VLS_UNKNOWN_SHARED_ID

Unknown shared ID given for the specified feature.

17

VLS_NO_RESPONSE_TO_ BROADCAST

Probably no servers are running on this subnet.

18

VLS_NO_SUCH_FEATURE

No license code is available for the specified feature

A.1. Licensing Library Error and Result Codes

Error #

Error/Status Codes

495

Description on this host.

19

VLS_ADD_LIC_FAILED

The given license code could not be added to the specified license server.

20

VLS_DELETE_LIC_FAILED

Failed to delete the specified feature from the license server on host.

21

VLS_LOCAL_UPDATE

Last update was done locally.

22

VLS_REMOTE_UPDATE

Last update was done by the license server.

23

VLS_VENDORIDMISMATCH

The specified feature is licensed by a different vendor.

24

VLS_MULTIPLE_VENDORID_ FOUND

The specified feature is licensed by multiple vendors other than your vendor.

25

VLS_BAD_SERVER_MESSAGE

Could not understand the message received from the license server on the specified host. Client-server version mismatch.

26

VLS_CLK_TAMP_FOUND

The following scenarios are possible: Scenario A: n

n

In case of a network license, if the system clock of the license server host is tampered. In case of a stand-alone license, if the system clock is tampered.

To clean up the time tamper persistence information, please see “Appendix A - Cleaning Legacy Persistence Data” in the Sentinel RMS SDK Developer's Guide. Scenario B: If the system is not initialized (using the sntlInitStandaloneSystem API or the lsinit utility) and persistence based licenses (like, grace, commuter, and stand-alone time tampering enabled) are requested. The API call returns this error. Please make sure that correct feature, version, and GUID (if applicable) are used for system initialization. Scenario C: If the serial number information corresponding to the stand-alone system initialization, license string, and client library does not match, the API call returns this error. 27

VLS_NOT_AUTHORIZED

You are not authorized to perform the requested operation.

496

Appendix A: Status Codes

Error #

Error/Status Codes

Description

28

VLS_INVALID_DOMAIN

Cannot perform this operation on the domain name specified.

34

VLS_LOG_FILE_NAME_NOT_ FOUND

The specified log filename not found on the specified license server host.

35

VLS_LOG_FILE_NAME_NOT_ CHANGED

Cannot change the specified log filename on the specified license server host.

36

VLS_FINGERPRINT_MISMATCH Machine's fingerprint mismatch for this feature.

37

VLS_TRIAL_LIC_EXHAUSTED

The duration of the specified trial license is exhausted.

38

VLS_NO_UPDATES_SO_FAR

No updates have taken place for this feature so far.

39

VLS_ALL_UNITS_RELEASED

Returned all the tokens for this feature.

40

VLS_QUEUED_HANDLE

The specified client handle is associated with a queued request.

41

VLS_ACTIVE_HANDLE

The specified client handle is associated with an active request.

42

VLS_AMBIGUOUS_HANDLE

Ambiguous client handle! The specified client handle is not associated with any request.

43

VLS_NOMORE_QUEUE_ RESOURCES

Queued request denied for this application since the queue is already full.

44

VLS_NO_SUCH_CLIENT

Could not find the specified client for this feature.

45

VLS_CLIENT_NOT_AUTHORIZED Client not authorized for the specified action for this feature.

47

VLS_LEADER_NOT_PRESENT

Processing not done because current leader is not known.

48

VLS_SERVER_ALREADY_ PRESENT

Server already exists in the redundant server pool.

49

VLS_SERVER_NOT_PRESENT

The given server name does not exist in the redundant server pool.

50

VLS_FILE_OPEN_ERROR

File open error.

51

VLS_BAD_HOSTNAME

The specified host name is either not valid or cannot be resolved.

52

VLS_DIFF_LIB_VER

The server fails to identify the client application version.

53

VLS_NON_REDUNDANT_SRVR

A non-redundant server ed for redundant server related information

54

VLS_MSG_TO_LEADER

Message forwarded to the leader server.

55

VLS__FAILOVER_ SERVER

Update Failure. another fail-over server.

56

VLS_UNRESOLVED_IP_ADDRESS IP address given cannot be resolved.

A.1. Licensing Library Error and Result Codes

497

Error #

Error/Status Codes

Description

57

VLS_UNRESOLVED_HOSTNAME Hostname given is unresolved.

58

VLS_INVALID_IP_ADDRESS

Invalid IP address format.

59

VLS_SERVER_FILE_SYNC

Server is synchronizing the distribution table

60

VLS_POOL_FULL

The redundant server pool already has the maximum number of servers. No more servers can be added.

61

VLS_ONLY_SERVER

The redundant server pool has only one server. It cannot be deleted.

62

VLS_FEATURE_INACTIVE

This feature is either unavailable on the server or server is non-redundant.

63

VLS_MAJORITY_RULE_FAILURE

The token for this feature cannot be issued because of the majority rule failure.

64

VLS_CONF_FILE_ERROR

Configuration file modifications failed. Check the given parameters.

65

VLS_NON_REDUNDANT_FEATURE

A non-redundant feature given for redundant feature related operation

66

VLS_NO_TRIAL_INFO

Cannot find trial license information for given feature.

67

VLS_TRIAL_INFO_FAILED

Failure in retrieving the trial usage information for the given feature.

69

VLS_NOT_LINKED_TO_INTEGRATED_LIBRARY

Application is not linked with integrated library.

70

VLS_CLIENT_COMMUTER_ CODE_DOES_NOT_EXIST

The commuter code for this feature does not exist on the client system.

72

VLS_NO_MORE_COMMUTER_ CODE

No more checked-out commuter code exists on the client.

73

VLS_GET_COMMUTER_INFO_ FAILED

Failed to get client commuter info on this server.

74

VLS_UNABLE_TO_UNINSTALL_ CLIENT_COMMUTER_CODE

Unable to uninstall the client commuter license.

75

VLS_ISSUE_COMMUTER_ CODE_FAILED

The possible causes are: n

n

If the client or server-side commuter persistence data is corrupt, then the local/remote checkout APIs return this error. To resolve this condition, clean up the corrupt persistence as documented (see Chapter 3 Planning Application Licensing of the Sentinel RMS SDK Developer's Guide) When the detection of remote sessions is set off in the VLSsetControlRemoteSession API and an attempt is made to check out a com-

498

Appendix A: Status Codes

Error #

Error/Status Codes

Description muter license from a remote system, then the API call returns error. To resolve, allow detection of remote sessions by setting VLS_ OFF in the API. If the update call is delayed and client does not receive a message from the license server while license check-out, this error is returned. To resolve, you may increase the time-out interval. When an attempt is made to check out a newer version license for an application licensed using an older version of the licensing library, this error is returned. For example, the version 11 (or later) tool/library should be used to check out version 11 licenses.

n

n

76

VLS_NON_COMMUTER_ LICENSE

A non-commuter license is requested for commuter related operation by this client. The VLS_UNABLE_TO_ISSUE_COMMUTER_ CODE has been deprecated. Use VLS_NON_ COMMUTER_LICENSE instead.

77

VLS_NOT_ENOUGH_COMMUTER_KEYS_AVAILABLE

Not enough commuter tokens are available on this server.

78

VLS_INVALID_INFO_FROM_ CLIENT

Invalid commuter info from the client.

79

VLS_CLIENT_ALREADY_EXIST

The client already exists on this server.

81

VLS_COMMUTER_CODE_ ALREADY_EXIST

The client commuter license already exists on this system.

82

VLS_SERVER_SYNC_IN_PROGRESS

Error specific to the redundant server pool setup. Occurs under the following scenarios: n

n

The server pool consists of only one license server. Specify at least two license servers to form a pool. Even if the minimum number of license servers are defined in the pool, the servers are busy synchronizing with each other when any redundant server API is called. This usually happens during the license server start-up or restart.

A.1. Licensing Library Error and Result Codes

499

Error #

Error/Status Codes

Description

83

VLS_REMOTE_CHECKOUT

This commuter license is checked out remotely, so it cant be checked-in.

84

VLS_UNABLE_TO_INSTALL_ COMMUTER_CODE

Error in installing the commuter authorization code.

85

VLS_UNABLE_TO_GET_ MACHINE_ID_STRING

Error getting the locking information for the client.

86

VLS_INVALID_MACHINEID_STR

Invalid remote locking code string.

87

VLS_EXCEEDS_LICENSE_LIFE

Cannot issue commuter code. License expiration is less than the requested days for commuter code.

88

VLS_TERMINAL_SERVER_ FOUND

Operating in stand-alone mode using terminal client. This is not allowed by the vendor.

89

VLS_NOT_ED_IN_NET_ Feature is not ed in Network-only mode of ONLY_MODE library.

The VLS_NOT_APPROPRIATE_LIBRARY error code has been deprecated. Use VLS_NOT_ ED_IN_NET_ONLY_MODE instead.

90

VLS_INVALID_FILETYPE

The specified file type is not ed.

91

VLS_NOT_ED

The client application is communicating with an old license server.

92

VLS_INVALID_LICENSE

The given license code is invalid. Hence, it could not be added to this license server.

93

VLS_DUPLICATE_LICENSE

The given license code is already added to the specified license server.

94

VLS_INSUFFICIENT__ CAPACITY

Insufficient capacity available.

95

VLS_TEAM_LIMIT_EXHAUSTED

Team limit exhausted.

96

VLS_INSUFFICIENT_TEAM_ CAPACITY

Insufficient team capacity available.

97

VLS_CANNOT_DELETE_ UPGRADED_LIC

Deletion of upgraded feature/license is not allowed.

98

VLS_UPGRADE_NOT_ALLOWED License upgrade feature is not allowed for redundant licenses, commuter licenses and trial licenses.

99

VLS_FEATURE_MARKED_FOR_ DELETION

The specified feature exists on this machine and it is already marked for check-in.

101

VLS_TEAM_EXCLUDED

This team has been excluded from accessing this feature.

500

Appendix A: Status Codes

Error #

Error/Status Codes

Description

102

VLS_NETWORK_SRVR

A network server is ed for standalone related information.

103

VLS_PERPETUAL_LICENSE

The ed feature is a repository license.

104

VLS_COMMUTER_CHECKOUT

A commuter token has already been checked out for this license.

105

VLS_REVOKE_ERR_NO_FEATURE

License with given feature/version is either not available on the server or belongs to a different vendor.

106

VLS_REVOKE_ERR_CORRUPT_ MESSAGE

107

The client message received by the server was corrupted. VLS_REVOKE_ERR_OUT_VALID_ The received number Of licenses to revoke is out of RANGE range.

108

VLS_REVOKE_ERR_MD5_PLUGIN_LOAD_FAIL

Error loading the MD5 plug-in dll at the server.

109

VLS_REVOKE_ERR_MD5_PLUGIN_EXEC_FAIL

Error in executing the authentication plug-in.

110

VLS_REVOKE_ERR_INSUFFICIENT_FEATURE_LICENSES

This feature has less number of total licenses.

111

VLS_REVOKE_ERR_INSUFFICIENT_DEFAULT_GROUP

Default group does not has sufficient licenses, reconfigure your reservation file.

112

VLS_REVOKE_ERR_INSUFFICIENT_FREE_IN_DEFAULT

Currently required number of licenses are not free for revocation in the default group.

113

VLS_REVOKE_ERR_INVALID_SES- Invalid session id received from the client. SION_ID

114

VLS_REVOKE_ERR_INVALID_

Invalid for revocation.

115

VLS_REVOKE_ERR_INTERNAL_ SERVER

Revocation failed due to internal server error.

116

VLS_REVOKE_ERR_INFINITE_ GRP_DIST

Infinite revocation not possible with enabled group distribution.

117

VLS_REVOKE_ERR_INFINITE_ LIC_IN_USE

All licenses must be free for infinite revocation.

118

VLS_REVOKE_ERR_INFINITE_ LIC_FINITE_REQ

License has infinite keys. Only infinite license revocation request is allowed for this license.

119

VLS_REVOKE_ERR_TICKET_GEN- Revocation feature is not ed for redundant ERATION licenses. VLS_REVOKE_ERR_CODGEN_ Revocation feature is not ed for the given VERSION_UNED license version.

120 121

VLS_REVOKE_ERR_RDNT_LIC_ UNSUPPORED

122

VLS_REVOKE_ERR_CAPACITY_ LIC_UNSUPPORED

Revocation feature is not ed for capacity licenses.

A.1. Licensing Library Error and Result Codes

501

Error #

Error/Status Codes

Description

123

VLS_REVOKE_ERR_ Failure occurred due to unexpected challenge UNEXPECTED_AUTH_CHLG_PKT packet received from server.

124

VLS_REVOKE_ERR_TRIAL_LIC_ UNSUPPORED

Revocation feature is not ed for trial licenses.

125

VLS_REQUIRED_LOCK_FIELDS_ NOT_FOUND

Required locking criteria for local request is not available on your machine.

126

VLS_NOT_ENOUGH_LOCK_ FIELDS

Minimum number of locking criteria for local request is not found.

127

VLS_REMOTE_CHECKOUT_ NOT_ALLOWED_FOR_PERPETUAL

Remote checkout is not available for a repository license.

128

VLS_GRACE_LIC_INSTALL_FAIL

This feature cannot run as installation of grace license is failed.

129

VLS_NOT_ED_IN_ NONET_MODE

The feature is not ed in no-net (stand-alone) mode.

The VLS_NOT_ED_IN_NONET_ LIBRARY error code has been deprecated. Use VLS_NOT_ED_IN_NONET_MODE instead.

130

VLS_NO_ACTIVE_HANDLE

No active client handle exists.

131

VLS_LIBRARY_NOT_INITIALIZED The licensing library is not initialized. To initialize, call VLSinitialize.

132

VLS_LIBRARY_ALREADY_INITIAL- The licensing library is already in initialized state. IZED

133

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API.

139

VLS_NO_MORE_LICENSES

No more licenses.

140

VLS_NO_SUCH_LICENSE

No license found with the specified feature/version/hash.

141

VLS_LICENSE_IN_USE

Specified feature/license has active client(s).

142

VLS_SET_LICENSE_PRECEDENCE_FAILED

Failure in setting precedence for specified trial license.

143

VLS_STORE_ACCESS_ERROR

Failure in accessing the license file.

147

VLS_LOCK_SELECTOR_INVALID

The specified lock selector is not valid.

148

VLS_LOCK_CODE_NOT_ED

The specified lock code is not ed by the library/server.

502

Appendix A: Status Codes

Error #

Error/Status Codes

149

VLS_LOCK_CODE_VER_INVALID Invalid lock code version. VLS_LOCK_CODE_INVALID The specified lock code is invalid.

150

Description

151

VLS_NO_AVAILABLE_MACHINE_ No available machine id for specified lock selector. ID

152

VLS_CODE_GENERATOR_ LIBRARY_FAILED

153

VLS_TRIAL_LIC_DATA_ACCESS_ The specified trial feature is not accessible. ERROR

154

VLS_TRIAL_LIC_DATA_INCONSISTENT

Trial License data inconsistent for this feature.

155

VLS_TRIAL_LIC_DATE_ RESTRICTED

Trial license date restriction error for this feature.

156

VLS_TRIAL_LIC_NOT_ACTIVATED

The trial licensing for this feature is disabled.

165

VLS_NONET_LIBRARY

A network request is made to the standalone library.

184

VLS_NON_TRIAL_LICENSE

Active feature on the server is not a trial license.

188

VLS_LICENSE_START_DATE_ NOT_REACHED

License start date not yet reached.

210

VLS_GRACE_CODE_LENGTH_ OVERFLOW_ERROR

Grace code length exceeds maximum limit.

211

VLS_ERROR_NO_MORE_FINGERPRINT_VALUE

No more fingerprint information is available.

Failure in initializing code generator library.

The VLS_ERROR_NO_MORE_ITEMS error code has been deprecated. Use VLS_ERROR_ NO_MORE_FINGERPRINT_VALUE instead.

212

VLS_ERROR_FINGERPRINT_ VALUE_NOT_FOUND

No fingerprint information is available on the specified index.

The VLS_ERROR_FILE_NOT_FOUND error code has been deprecated. Use VLS_ERROR_ FINGERPRINT_VALUE_NOT_FOUND instead.

A.1. Licensing Library Error and Result Codes

503

Error #

Error/Status Codes

Description

213

VLS_LICENSE_DELETION_NOT_ ALLOWED

License deletion is not ed for the following licenses: n

n

n

214

VLS_CAPACITY_MISMATCH

215

VLS_EXPIRED_COMMUTER_ CODE

216

Checked out commuter license tokens residing on the local computers Grace licenses being used on the non-networked computers Licenses in the redundant license files (lservrlf)

The capacity value does not match, or an operation related to capacity licensing is requested for a noncapacity license (or vice-versa).

Error installing the commuter code, as the code is expired. VLS_COMMUTER_CODE_DATE_ Commuter code start date not yet reached. RESTRICTED

217

VLS_NEW_RECORD_FOUND

If the limit value has been updated by any other process after the current process has retrieved the limit value. The API function also returns the current limit value in the consume_value parameter.

218

VLS_NO_RECORDS_FOUND

No records for the limit in the database.

219

VLS_OPERATION_NOT_SUCCESSFUL

The requested operation failed for any other reason.

220

VLS_ERROR_READING_SERVER_ The redundant server configuration file being used CONFIG_FILE for determining the primary server (from which the license authorization is to be checked out) is corrupt.

221

VLS_CHECKOUT_NOT_ ALLOWED_FROM_NONPRIMARY_LEADER

An attempt is made to check out an authorization from a non-primary server.

222

VLS_REHOST_LIC_VERSION_ NOT_ED

The stand-alone revocation feature is ed for v 11 (or later) licenses only. If an attempt is made to revoke licenses of earlier versions, the VLSrevokeByPermissionTicket succeeds, and returns VLS_ REHOST_LIC_VERSION_NOT_ED as status in the revocation ticket.

223

VLS_USAGE_FILE_TAMPERED

The usage log file is tampered. One or more records are either modified or missing from the usage log file.

224

VLS_NO_MATCH_FOUND

The matching record is not found in the usage log file.

504

Appendix A: Status Codes

Error #

Error/Status Codes

Description

225

VLS_INVALID_TIP_VERSION

T\IP protocol version specified for licensing library is incorrect. if the client and server protocols are incompatible.

226

VLS_VIRTUAL_MACHINE_IS_ DETECTED

The license server is being run on a virtual machine.

227

VLS_GRACE_LIC_TIME_ TAMPER_INIT_FAIL

The system initialization failed for a grace license.

228

VLS_REVOKE_LIC_DATA_INCON- The license persistence data is either corrupt or does SISTENT not exist.

229

VLS_TOO_MANY_OPERATIONS_ The permission ticket size is more than the length IN_SINGLE_PT ed internally. This is applicable to network license revocation only, where the maximum number of operations should not exceed 15. Try reducing the number of operations from the permission ticket. Technical for more troubleshooting.

230

VLS_PT_ALREADY_EXECUTED_ FOR_THIS_OPERATION

The permission ticket operation already executed on the license server.

231

VLS_PT_VENDOR_ID_MISMATCH

Vendor ID mismatch. The permission ticket cannot be used for revoking licenses of other vendors.

232

VLS_REVOKE_EXPIRED_LIC_ FOUND

An expired license can neither be added nor revoked.

233

VLS_COMMUTER_CHECKOUT_ NOT_ALLOWED

The commuter token checkout not allowed for this feature.

A.2. License Generation Error Codes

A.2. License Generation Error Codes The following table lists the RMS license code generation return codes and their default messages:

Error Return Code #

Default Message

0

VLScg_SUCCESS

Success

2

VLScg_NO_FEATURE_NAME

Feature Name must be specified. It cannot be empty.

3

VLScg_INVALID_INT_TYPE

Expected an integer value, found “XXX”

4

VLScg_EXCEEDS_MAX_VALUE

Value entered is greater than the maximum ed value.

5

VLScg_LESS_THAN_MIN_VALUE

Value entered is less than the minimum ed value.

6

VLScg_EXCEEDS_MAX_STRLEN

Length of is greater than .

7

VLScg_NOT_MULTIPLE

Value should be a multiple of “XXX”.

8

VLScg_INVALID_DEATH_YEAR

Expiration date cannot be less than “XXX”.

9

VLScg_INVALID_BIRTH_YEAR

Start year cannot be less than “XXX”.

10

VLScg_INVALID_DATE

Date is not valid.

11

VLScg_INVALID_HEX_TYPE

Wrong value entered. (Should be hexadecimal)

12

VLScg_INVALID_IP_TYPE

Wrong value entered. IP address should be specified in dot form.

13

VLScg_INVALID_YEAR

Invalid year entered.

14

VLScg_RESERV_STR_ERR

The string is a reserved string.

15

VLScg_INVALID_RANGE

Value violates the valid range of input.

16

VLScg_INVALID_CHARS

Invalid characters.

17

VLScg_SHORT_STRING

License string \” \” too small to parse.

18

VLScg_PREMATURE_TERM

Premature termination of license code. Please check.

19

VLScg_REMAP_DEFAULT

Failed to remap default strings from configuration file for license \” \”.

20

VLScg_DECRYPT_FAIL

Decryption failed for license code.

21

VLScg_DYNAMIC_DECRYPT_FAILURE

Decryption failed for dynamically added license code.

22

VLScg_INVALID_CHKSUM

Checksum validation failed for license code. Please the license code.

23

VLScg_FIXED_STR_ERROR

Default fixed string error.

24

VLScg_SECRET_DECRYPT_FAILURE

Decryption failed for secrets. the configuration file for readable licenses.

25

VLScg_SIMPLE_ERROR

Error in license code. Please check.

505

506

Appendix A: Status Codes

Error Return Code #

Default Message

26

VLScg_MALLOC_FAILURE

Out of heap memory.

27

VLScg_INTERNAL_ERROR

Internal error.

28

VLScg_UNKNOWN_LOCK

Unknown lock mechanism.

29

VLScg_VALUE_LARGE

Value: too large

30

VLScg_INVALID_INPUT

Invalid input.

31

VLScg_MAX_LIMIT_ CROSSED

Maximum limit crossed.

32

VLScg_NO_RESOURCES

No resources left.

33

VLScg_BAD_HANDLE

Bad file handle.

34

VLScg_FAIL

Operation failed.

35

VLScg_INVALID_VENDOR_CODE

Invalid Vendor Code. Please your Sentinel RMS Development Kit distributor.

36

VLScg_VENDOR_ENCRYPTION_FAIL

Vendor-customized encryption failed.

37

VLScg_INVALID_EXP_DATE

License Expiration Date must be greater than Start Date.

38

VLScg_INVALID_EXP_YEAR

License Expiration Year must be greater than Start Year.

39

VLScg_INVALID_EXP_MONTH

License Expiration Month must be greater than Start Month.

40

VLScg_LICMETER_EXCEPTION

Unknown exception in accessing Sentinel RMS license meter(s).

41

VLScg_LICMETER_DECREMENT_OK

Your license meter(s) have been decremented by units. You now have units left out of an initial count of units.

42

VLScg_LICMETER_ACCESS_ERROR

Error accessing license meter(s). Please make sure the Sentinel System Driver is properly installed and a license meter is attached to the parallel port or USB port.

43

VLScg_LICMETER_COUNTER_TOOLOW Too few units (Normal License Count=%d/ Trial License Count= %d) left in your Sentinel RMS Development Kit license meter(s) to generate requested license. %d units required.

44

VLScg_LICMETER_CORRUPT

Your Sentinel RMS license meter(s) are corrupted.

45

VLScg_LICMETER_VERSION_MISMATCH

Your Sentinel RMS Development Kit license meter has an invalid version.

46

VLScg_LICMETER_EMPTY

All units of your Sentinel RMS Development Kit license meter(s) have been used up. License generation will fail.

A.2. License Generation Error Codes

Error Return Code #

Default Message

47

VLScg_PORTSERV_ EXCEPTION

Unknown exception ( ) in accessing Sentinel RMS Development Kit portable server(s).

48

VLScg_PORTSERV_ ACCESS_ERROR

Error accessing Sentinel RMS portable server(s). Please make sure one is attached.

49

VLScg_PORTSERV_VERSION_MISMATCH

Your Sentinel RMS license server has an invalid version ( . ) for commuter licenses. Expected . .

50

VLScg_PORTSERV_CORRUPT

Your Sentinel RMS Development Kit portable server(s) are corrupted.

51

VLScg_EXPIRED_LICENSE

Your software license has expired.

52

VLScg_INVALID_LICTYPE

Invalid License Type.

53

VLScg_INVALID_TRIALDAYS

Invalid Trial Days.

54

VLScg_INVALID_TRIAL_COUNT

Invalid Trial License Count.

55

VLScg_TRIALMETER_EMPTY

All units of your Sentinel RMS Development Kit Trial license meter(s) have been used up.

56

VLScg_TRIAL_SUCCESS

Your trial license meter(s) have been decremented by units. You now have units left.

57

VLScg_NO_NETWORK_AUTHORIZATION

Your Sentinel RMS Development Kit license meter(s) have No authorization to generate Network Licenses.

58

VLScg_NO_ENABLE_FEATURE

No feature is enabled.

59

VLScg_VI18N_INITIALIZE_FAIL

Error in updating locale.

60

VLScg_INVALID_NUM_SERVERS

Invalid number of servers.

61

VLScg_NO_CAPACITY_AUTHORIZATION Your license meter(s) have no authorization to generate capacity licenses. VLScg_UPGRADE_NOT_ALLOWED

Your license meter(s) have no authorization to generate upgrade licenses.

70

VLScg_LICMETER_NOT_ED

Your license meter is not ed.

71

VLScg_INCORRECT_BASE_FEATURE_ VAL

The base feature is too high for ing desired number of multi-features.

72

VLScg_ENCRYPTION_FAIL

License code encryption failed.

73

VLScg_INVALID_CAPACITY_SETTINGS

Invalid capacity setting done in code structure.

74

VLScg_EXP_DATE_BEFORE_START_ DATE

License expiration date is set before the license start date.

75

VLScg_INVALID_TRIALHOURS

Invalid trial elapsed hours.

77

VLScg_GETLOCK_FAIL

Process lock request failed.

507

508

Appendix A: Status Codes

Error Return Code #

Default Message

78

VLScg_GETLOCK_TIMEOUT

Process lock request timeout.

79

VLScg_VENDOR_DECRYPTION_FAIL

Vendor decryption failed.

80

VLScg_RT_VERSION_MISMATCH

Version value found in the revocation ticket does not match with that specified in request structure.

81

VLScg_RT_REHOST_LINE_CORRUPT

One or more operation-specific information in the revocation ticket is invalid.

82

VLScg_RT_TRANSACTION_ID_MISMATCH

The transaction ID value found in the revocation ticket does not match with that specified in request structure.

83

VLScg_RT_LOCK_CODE_MISMATCH

The lock code value found in the revocation ticket does not match with that specified in the request structure.

84

VLScg_RT_REQUESTED_ACTION_NOT_ One or more operation(s) specified in the PERFORMED request structure is/are not performed at client side as corresponding information is not found in revocation ticket.

85

VLScg_RT_NON_REQUESTED_ACTION_ The request structure does not specify one or PERFORMED more operation(s) corresponding to which information is found in revocation ticket.

86

VLScg_RT_ACTION_STATUS_NOT_SUC- The requested operation is not successfully perCESS formed at the client-end.

87

VLScg_RT_REQUEST_EMPTY

The request struture does not specify any operation.

88

VLScg_RT_REQUEST_LINE_INVALID

The request structure specified an invalid operation.

89

VLScg_RT_REHOST_TICKET_INVALID_ TLV_STRUCT

The revocation ticket is invalid.

90

VLScg_RT_REHOST_TAG_MISSING

The rehost tag is not found in the revocation ticket.

91

VLScg_RT_VERSION_TAG_MISSING

The version tag is not found in the revocation ticket.

92

VLScg_RT_TRANSACTION_ID_TAG_ MISSING

The transaction ID tag is not found in the revocation ticket.

93

VLScg_RT_LOCK_SELECTOR_TAG_MISS- The lock selector tag is not found in the revING ocation ticket.

94

VLScg_RT_LOCK_SELECTOR_MISMATCH

The lock selector value found in the revocation ticket does not match with that specified in the request structure.

A.2. License Generation Error Codes

Error Return Code #

Default Message

95

VLScg_RT_LOCK_CODE_TAG_MISSING The lock code tag is not found in the revocation ticket.

96

VLScg_RT_REHOST_LINE_TAG_MISSING

The rehost line tag is not found in the revocation ticket.

97

VLScg_RT_HASH_TAG_MISSING

The hash tag is not found in the revocation ticket.

98

VLScg_RT_TIME_STAMP_MISMATCH

The time stamp value found in the revocation ticket does not match with that specified in the request structure.

99

VLScg_RT_TIME_STAMP_TAG_MISSING

The time stamp tag is not found in the revocation ticket.

100

VLScg_RT__SINGLE_ERROR

The revocation ticket reported a single error.

101

VLScg_RT__MULTIPLE_ERRORS The revocation ticket reported multiple errors.

102

VLScg_RT_BUFFER_TOO_SMALL

The buffer is too small.

103

VLScg_RT_PARAMETERS_ERROR

A parameters-related error is encountered.

104

VLScg_RT_ALLOCATE_MEMORY_FAIL- A memory allocation failure. URE

105

VLScg_RT_UNED_OPERATION_TYPE

The operation type is not ed.

106

VLScg_RT_INVALID_REQUEST_DATA

An invalid rehost request data.

107

VLScg_RT_TAG_NOT_FOUND

The tag cannot be found in TLV.

108

VLScg_BUFFER_TOO_SMALL

The buffer is too small.

109

VLScg_RT_INSUFFICIENT_TOKENS_TO_ The license tokens available for revocation are REVOKE less than the number specified in the permission ticket.

110

VLScg_RT_MIXED_OPERATION_TYPE_ You cannot revoke stand-alone and network UNED licenses using a single permission ticket.

111

VLScg_RT_INFINITE_LIC_FINITE_REQ

Network licenses with infinite tokens cannot be partially revoked. Full revocation is required.

112

VLScg_RT_RDNT_LIC_UNSUPPORED

The permission ticket cannot be generated for redundant licenses.

113

VLScg_RT_CORRUPT_ORIG_REQ

The permission ticket provided for verification is corrupt.

114

VLScg_RT_CUSTOM_DATA_TAG_MISS- The custom defined data tag is not found in the ING revocation ticket.

115

VLScg_RT_CUSTOM_DATA_MISMATCH The custom defined data included in the permission ticket and revocation ticket does not match.

116

VLScg_RT_REVOCATION_TYPE_MISMATCH

Either standalone revoke request is provided to

509

510

Appendix A: Status Codes

Error Return Code #

Default Message with a network revocation ticket, or vice versa.

117

VLScg_TOO_MANY_OPERATIONS_ FOR_SINGLE_PT

The number of operations specified in the permission ticket exceed the maximum limit. You cannot specify more than 15 operations in a permission ticket for a network license revocation.

118

VLScg_VENDOR_ID_MISMATCH

Vendor ID mismatch. The permission ticket cannot be generated for licenses of other vendors.

119

VLScg_CODGEN_VERSION_UNED

130

VLScg_RESERV_CHAR_ERR

The permission ticket generation not ed for licenses earlier than version 11. The reserved characters are used. See About Reserved Characters and Strings.

131

VLScg_LOWER_THAN_MIN_STRLEN

The string length is lower than the minimum allowed.

A.3. Upgrade License Error Codes

A.3. Upgrade License Error Codes The following table lists upgrade license code generation return codes and their default messages:

Error# Return Code

Default Message

0

VLScg_SUCCESS

Success

2

VLSucg_NO_FEATURE_NAME

Feature Name must be specified. It cannot be empty.

3

VLSucg_INVALID_INT_TYPE

Expected an integer value, found “XXX”

4

VLSucg_EXCEEDS_MAX_ VALUE

Value entered is greater than the maximum ed value.

5

VLSucg_LESS_THAN_MIN_ VALUE

Value entered is less than the minimum ed value.

6

VLSucg_EXCEEDS_MAX_ STRLEN

Length of is greater than .

7

VLSucg_NOT_MULTIPLE

Value should be a multiple of “XXX”.

11

VLSucg_INVALID_HEX_TYPE

Wrong value entered. (Should be hexadecimal)

14

VLSucg_RESERV_STR_ERROR

is a reserved string.

16

VLSucg_INVALID_CHARS

Invalid characters.

20

VLSucg_DECRYPT_FAIL

Decryption failed for license code.

22

VLSucg_INVALID_CHKSUM

Checksum validation failed for license code. Please the license code.

26

VLSucg_MALLOC_FAILURE

Out of heap memory.

27

VLSucg_INTERNAL_ERROR

Internal error.

30

VLSucg_INVALID_INPUT

Invalid input.

31

VLSucg_MAX_LIMIT_ CROSSED

Maximum limit crossed.

32

VLSucg_NO_RESOURCES

No resources left.

33

VLSucg_BAD_HANDLE

Bad file handle.

34

VLSucg_FAIL

Operation failed.

35

VLSucg_INVALID_VENDOR_ CODE

Invalid Vendor Code. Please your Sentinel RMS Development Kit distributor.

36

VLSucg_VENDOR_ENCRYPTION_FAIL

Vendor-customized encryption failed.

40

VLSucg_LICMETER_EXCEPTION

Unknown exception in accessing Sentinel RMS Development Kit license meter(s).

41

VLSucg_LICMETER_DECREMENT_OK

Your license meter(s) have been decremented by units. You now have units left out of an initial count of units.

42

VLSucg_LICMETER_ACCESS_ ERROR

Error in accessing the license meter(s). Please

511

512

Appendix A: Status Codes

Error# Return Code

Default Message make sure the Sentinel System Driver is properly installed and a license meter is attached to the parallel port or USB port.

44

VLSucg_LICMETER_CORRUPT Your license meter(s) are corrupted.

45

VLSucg_LICMETER_VERSION_ Your license meter has an invalid version. MISMATCH

46

VLSucg_LICMETER_EMPTY

All units of your license meter(s) have been used up. License generation will fail.

52

VLSucg_INVALID_LICTYPE

Invalid License Type.

59

VLSucg_VI18N_INITIALIZE_ FAIL

Error in updating locale.

61

VLSucg_NO_CAPACITY_ AUTHORIZATION

Your license meter(s) have no authorization to generate Capacity Licenses.

62

VLSucg_NO_UPGRADE_ AUTHORIZATION

Your license meter(s) have no authorization to generate Upgrade Licenses.

63

VLSucg_NO_UPGRADE_CODE Upgrade Code must be specified. It cannot be empty.

64

VLSucg_INVALID_BASE_LIC_ INFO

65

VLSucg_CAPACITY_UPD_NOT_ Capacity upgrade is not allowed, as the base lic is a ALLOWED non-capacity license.

66

VLSucg_INVALID_UPGRADE_ CODE

Invalid upgrade code.

67

VLSucg_LICMETER_ COUNTER_TOOLOW

Too few units (Normal License Count=%d) left in your license meter(s) to generate requested license. %d units required.

69

VLSucg_LICMETER_NOT_SUP- Your license meter is not ed. PORTED

The information-feature name, version and vendor code, provided for base license is incorrect.

A.4. System Initialization Error Codes

513

A.4. System Initialization Error Codes  The LSINIT functions will return the ORed value of the [first-level status code] and [second-level status code]. For example, for first-level status code 0x10000000 and second-level status code - 0x00001000, the ORed value returned will be 0x10001000. This indicates initialization failure for a time tampering enabled license because the file could not be written. You can decipher these status codes as described below: Hexadecimal Code

Status Code Description First Level Status Codes

0x10000000

ERR_TIME_ TAMPER_INIT_ FAIL

0x20000000

ERR_COMMUTER_ Commuter Initialization Failure PRS_INIT_FAIL

0x40000000

ERR_GRACE_PRS_ Grace License Initialization FailINIT_FAIL ure

0x80000000

ERR_TRIAL_INIT_ FAIL

Trial License Initialization Failure

0xF0000000

ERR_STDRVK_ INIT_FAIL

Standalone Revocation Initialization Failure

0x01000000

ERR_CONSUME_ INIT_FAIL

VTL Initialization Failure

Time Tamper Initialization Failure

Second Level Status Codes 0x00000000

ERR_KEY_INFO_ SUCCESS

Success

0x00000001

ERR_INVALID_ INPUT

Invalid Input

0x00000002

ERR_INIT_LIB_FAIL Library Initialization Failure

0x00000008

ERR_INIT_INFO_ EXISTS

Already Initialized

0x00000010

ERR_INIT_SEC_ FAIL

Permissions failure on secure information

0x00000020

ERR_INIT_KEY_ FAIL

Failed to create registry information (only for Windows)

0x00000040

ERR_INIT_KEY_ SEC_FAIL

Permission failure for secure registry (only for Windows)

0x00000080

ERR_INIT_OPEN_ KEY_FAIL

Registry open failure (only for Windows)

0x00000100

ERR_INIT_SET_

Write failure on secure registry

514

Appendix A: Status Codes

Hexadecimal Code

Status Code VALUE_FAIL

Description (only for Windows)

0x00000200

ERR_INIT_QUERY_ Read failure on secure registry FAIL (only for Windows)

0x00000400

ERR_INIT_FILE_ FAIL

File creation failure

0x00000800

ERR_INIT_FILE_ OPEN_FAIL

File open failure

0x00001000

ERR_INIT_FILE_ WRITE_FAIL

Write failure on secure file

0x00002000

ERR_INIT_FILE_ SEC_FAIL

Permissions failure on secure file

0x00004000

ERR_EXCEPTION_ OCCURED

An exception occurred during execution

0x00008000

ERR_INIT_FILE_ INFO_EXISTS

Initialization file information exits

0x00010000

ERR_INTERNAL_ FAIL

Internal error

0x00020000

ERR_INSUFFICIENT_PERMISIONS

Access denied for read or write secure data

0x00040000

ERR_TAMPER_ DETECTED

Secure data is tampered

0x00080000

ERR_INIT_PATH_ FAILED

Error retrieving persistence database location

0x00100000

ERR_INIT_FILE_ READ_FAIL

Error encountered in reading persistence file(s)

0x00200000

ERR_NORESOURCES

Failure in obtaining system resources

0x00400000

ERR_LOCK_ERROR Resource lock failure

0x00800000

ERR_INIT_CONFIG_FAIL

Error encountered in setting trial persistence file location

A.5. Persistence Cleaning Error Codes

515

A.5. Persistence Cleaning Error Codes The persistence cleaning API can return any of the following error codes: Hexadecimal Code 0xC8010001

Status Code VLScl_ILLEGAL_VENDOR_ID

The library does not have a valid serial number information.

0xC8010002

VLScl_INSUFFICIENT_PERMISIONS

If the application calling the API is run in non mode.

0xC8010003

VLScl_INVALID_ARGUMENTS

If a wrong value or combination of arguments is ed.

0xC8010004

VLScl_NO_TRIAL_FEATURE_IN_USE

If the trial information of the given feature-version is not found.

0xC8010005

VLScl_NO_COMMUTER_FEATURE_IN_USE If the commuter information of the given feature-version is not found. VLScl_NO_GRACE_INFORMATION_ If the grace information of the given FOUND feature-version is not found.

0xC8010006

Description

0xC8010007

VLScl_NO_REVOKE_INFORMATION_ FOUND

The revocation information of the given feature-version is not found.

0xC8010008

VLScl_NORESOURCES

A memory related error (malloc, etc.) has occurred.

0xC8010010

VLScl_RESOURCE_LOCK_FAILURE

Failed to acquire an API lock. The API should be recalled on receiving this error.

0xC8010009

VLScl_INTERNAL_ERROR

An internal error.

0xC8010011

VLScl_NO_COMMUTER_INFO_FOUND

No commuter persistence information is found for the given featureversion. Probably, no commuter tokens are checked out for this feature-version, or when there are commuter check outs for other featureversion(s).

B Appendix B: Customization Features Sentinel RMS provides a number of libraries to enable you to re-build the license server, code generator executable, and override certain predefined features. In addition, few files and APIs are also provided to allow customizations. The table below lists the various customization features available in stand-alone or network licensing or both:

Customization Vendor-specified license server initialization Vendor-specified license server identification string Changing the default port of the license server Installing hooks on pre/post request and pre/post release events Protection against time tampering Encrypting the License Codes Encrypting the Upgrade License Codes Encrypting License Server Messages Vendor-specified 4-byte custom fingerprint of a system Vendor-specified custom extended fingerprint of a system Customizing the stand-alone license file names Configuration file to customize the standard custom fingerprint caching Setting custom client information (name and hostname)

Network Licensing

Stand-alone Licensing

518

Appendix B: Customization Features

For customization on non-Windows platforms, a makefile is provided in the examples directory of your SDK installation.

B.1. Architecture of Overriding the Functions

519

B.1. Architecture of Overriding the Functions RMS provides static libraries for all the customizable modules. The customizable functions are predefined in these libraries. To override the default functions, you need to define the customizable functions and rebuild the executables using the static libraries. The resultant executables will contain the functions defined by you and the RMS component will call your defined function automatically. An example is shown below, in which the VLSdecryptLicense function in lservnt.lib is overridden by the VLSdecryptLicense function in lic_decrypt.obj.

An Example Showing a Customized Implementation of License Decryption

520

Appendix B: Customization Features

B.2. Vendor-specified License Server Initialization Using the VLSserverVendorInitialize function, you can the following: n n n n

The license server hooks The custom Host ID lock function The custom extended lock function Or, any additional task that you want to perform at the time of the license server initialization.

B.2.1. Description The VLSserverVendorInitialize function is called while initializing the license server. You can perform vendor-specific initialization using this function while starting the license server.

B.2.2. Function Prototype  LSERV_STATUS VLSserverVendorInitialize(void);

B.2.3. Returns Returns LS_SUCCESS(0) on success. Returns non-zero on failure.

B.2.4. Steps to Perform 1. Create the VLSserverVendorInitialize function. 2. Update the SRV_VENDOR_INIT_OBJS variable in the custom32.mak file. 3. Follow the build procedure specified in Build Procedure.

B.2.5. Code Snippet LSERV_STATUS VLSserverVendorInitialize(void) { /* TODO: hook functions (if any) */ /* TODO: custom host ID function (if any) */ /* TODO: extended custom value function (if any)*/ /* TODO: add vendor specific initialization */ return LS_SUCCESS; }

B.3. Vendor-specified License Server Identification String

521

B.3. Vendor-specified License Server Identification String To uniquely identify the license server, you can set unique license server information—a string consisting of up to 50 characters. In case of stand-alone licensing, since the license server module is part of the licensing library itself, there is no need to uniquely identify the license server by setting the license server information.

B.3.1. Executables to Rebuild The license server (lservnt.exe) needs to be rebuild. Please refer to the Build Procedure

B.3.2. Description  A customizable API function, VLSsetServerInfo, is provided to allow you to customize the license server by setting the vendor -specific information in the license server. This information can be returned to the client using the VLSgetServInfo function.

B.3.3. Function Prototype LSERV_STATUS VLSsetServerInfo ( char **vendorInfo );

B.3.4. Returns n

Returns LSERV_STATUS_SUCCESS on success.

n

Returns non-zero on failure.

Parameter

Description

vendorInfo

An OUT parameter. A pointer to string of up to 50 characters to write to license server as identification.

B.3.5. Steps to Perform  1. Create the VLSsetServerInfo function. 2. Update the VENDOR_INFO_OBJS variable in the custom32.mak file. Follow the build procedure specified in Build Procedure.

522

Appendix B: Customization Features

B.3.6. Code Snippet LSERV_STATUS VLSsetServerInfo ( char **vendorInfo /* OUT */ ) { static char* vendor_info_str = /* TODO: add the server identification string here */; if (vendorInfo == NULL) { return 1; /* failure */ } *vendorInfo = vendor_info_str; return LSERV_STATUS_SUCCESS; }

B.4. Changing the Default Port of the License Server

B.4. Changing the Default Port of the License Server By default, the license server communicates at port number 5093. If required, you can set it to any other available port using the information provided in this topic. In case of stand-alone licensing, since the license server module is part of the licensing library itself, the default port of the license server need not be changed.

B.4.1. Executables to Rebuild n

The license server (lservnt.exe) needs to be rebuild.

n

The client application.

B.4.2. Description Sets a new port number for the client-server communication.

B.4.3. Function Prototype int VLSchangePortNumber ( int currentPort );

B.4.4. Returns Returns the new port number set for the client-server communication. Parameter

Description

currentPort

An IN parameter. The current port number used for communication.

B.4.5. Steps to Perform  1. Create the VLSchangePortNumber function. 2. Update the CHANGE_PORT_OBJS variable in the custom32.mak file. 3. Call VLSsetServerPort in the client application. You can use the VLSgetServerPort function to obtain the current port number. 4. Follow the procedure described in Build Procedure.

523

524

Appendix B: Customization Features

B.4.6. Code Snippet  The VLSchangePortNumber Function int VLSchangePortNumber ( int currentPort /* IN - Currently configured port number */ ) { int newPort = /* TODO: add new ed port number here */; return newPort; }

The Client Application int main(int argc, char* argv[]) { VLSsetServerPort(6000/*dummy port number*/); VLSinitialize(); /* application code here */ return 0; }

B.4.7. Modifying the Default Port of RMS Utilities If the default communication port of the license server is modified, the following RMS utilities (meant for redistribution) must also be modified to reflect this change: n

lsmon

n

lslic

n

lswhere

There are two ways to do this: n

You can edit the default port using the VLSsetServerPort API and rebuild the utilities.

The source code of these utilities is provided in the \MsvcDev\Samples\API directory.

n

You may instead remove the corresponding line (for example, VLSsetServerPort(SERVER_ PORT) from the lsmon.c file) from the source code files of these utilities. And, your customers can set the port using the LSPORT environment variable. However, that the port set in the source code overrides the one set using the environment variable.

B.5. Installing Hooks on Pre/Post Request and Release Events

525

B.5. Installing Hooks on Pre/Post Request and Release Events You can add hooks on the following events: n

Pre-request

n

Post-request

n

Pre-release

n

Post-release

In the "pre" hook, you can decide on the licensing action, such as looking up the external information before granting a request. In the post hook, you cannot change the license decision but can provide custom information to the client.

B.5.1. Executables to Rebuild n

n

In case of stand-alone licensing (application linked to the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild.

B.5.2. Description Hooks are based on events. For each event, there is a pre-event hook and a post-event hook. Currently, the only events with hooks are license request and license release. So, you can have a hook function BEFORE the license server processes a license request or AFTER a request is processed.

B.5.3. Function Prototype (to Callback Function) LSERV_STATUS VLSeventAddHook ( int eventName, int (*handlerFuntr)(VLShandlerStruct *, char *, char *, int), char* identifier );

B.5.4. Returns Returns LSERV_STATUS_SUCCESS on success. Returns non-zero on failure.

526

Appendix B: Customization Features

Parameter

Description

eventName

An IN parameter. Specifies the type of event: n

n

n

n

LS_REQ_PRE - The handler function will be called right before the license server processes the license request. LS_REQ_POST - The handler function will be called right after the license server processes the license request. LS_REL_PRE - The handler function will be called right before the license server processes the license release. LS_REL_POST - The handler function will be called right after the license server processes the license release.

handlerFuntr

An IN parameter. The callback function for specified event.

identifier

An IN parameter. The client identifier to match.

B.5.5. Function Prototype (of the Callback Function)  int HandlerFunc ( VLShandlerStruct* pHandlerStruct, /* IN */ char* inBuf /* IN */ char* outBuf /* OUT */ int outBufSz /* IN */ );

B.5.6. Returns n

Returns LSERV_STATUS_SUCCESS on success.

n

Returns LSERV_STATUS_DENY on failure.

Parameter

Description

pHandlerStruct

A pointer to VLShandletStruct containing client information, feature information, various file information and miscellaneous information.

inBuf

The null-terminated string containing the input message.

outBuf

A pointer to buffer that receives the output message.

outBufSz

The size of the buffer pointer by outBufSz.

B.5.7. Steps to Perform  1. Create the hook functions. For example, LSReqPreHook, LSReqPostHook, LSRelPreHook and LSRelPostHook. 2. Update the SERVER_HOOK_OBJS variable in the custom32.mak file.

B.5. Installing Hooks on Pre/Post Request and Release Events

3. the hook functions in the license server. 4. Follow the build procedure specified in Build Procedure.

B.5.8. Code Snippets Create the Hook Functions int LSReqPreHook ( VLShandlerStruct* pHandlerStruct, /* IN */ char* inBuf /* IN */ char* outBuf /* OUT */ int outBufSz /* IN */ ) { if ((inBuf == NULL) || (outBuf == NULL) || (outBufSz == 0)) { return LSERV_STATUS_DENY; } /* TODO: add the pre-request handler code here */ return LSERV_STATUS_SUCCESS; }

the Hook Functions in the License Server extern int LSReqPreHook(VLShandlerStruct* pHandlerStruct, char* inBuf, char* outBuf, int outBufSz); LSERV_STATUS VLSserverVendorInitialize(void) { VLSeventAddHook(LS_REQ_PRE, &GetCustomExValue, "Hook1"); return LSERV_STATUS_SUCCESS; }

527

528

Appendix B: Customization Features

B.6. Protection Against Time Tampering To configure or override the built-in time tampering detection function, you can use the information provided in this section.

B.6.1. Executables to Rebuild n

n

In case of stand-alone licensing (application linked to the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild.

Please refer to Build Procedure.

B.6.2. Description Following are some of the configurable properties used by the built-in time tampering detection function of RMS. n

The action taken on time tampering detection

n

The method of time tampering detection

n

The default grace period

n

The number or percentage of system files found to be tampered before concluding the system clock is tampered (for UNIX only).

Using the VLSconfigureTimeTamper API function you can modify the configurable properties.

B.6.3. Function Prototype void VLSconfigureTimeTamper ( VLSactionOnTmTamper* actionOnTmTamper, /* OUT */ VLStmTamperMethod* tmTamperMethod, /* OUT */ int* gracePeriod, /* OUT */ int* percentViolations, /* OUT */ int* numViolationsForError /* OUT */ );

B.6.4. Enumeration Data Type  typedef enum { VLS_CONT_AFTER_TM_TAMPER, VLS_EXIT_AFTER_TM_TAMPER }VLSactionOnTmTamper;

B.6. Protection Against Time Tampering

typedef enum { VLS_ENABLE_DEFAULT_TM_TAMPER, VLS_DISABLE_DEFAULT_TM_TAMPER }VLStmTamperMethod; Parameter

Description

actionOnTmTamper

An OUT parameter. Whether to exit from the license server (or your application, in case of stand-alone licensing) once the system clock tampering is detected. [Default: VLS_CONT_AFTER_TM_TAMPER]

tmTamperMethod

An OUT parameter. Whether to use the built-in system clock tampering detection function, or use the one provided by you. [Default: VLS_ENABLE_DEFAULT_TM_TAMPER]

gracePeriod

An OUT parameter. Useful only in case tmTamperMethod is VLS_ENABLE_DEFAULT_TM_ TAMPER. If RMS finds the system clock has been set back by less than the gracePeriod seconds, it will not count the offending system file as a violation. [Default: 86,400 seconds (1 day)]

percentViolations

An OUT parameter. The percentage of the system files that must be found in violation of the grace period before concluding that the system clock has been set back. the value of 0 for this parameter to ignore the functionality. Applicable only to UNIX systems. [Default: 1% of the files to violate grace period]

numViolationsForError

An OUT parameter. The number of system files that must be found in violation of the grace period, before concluding that the system clock has been set back. Applicable only to UNIX systems.

If both percentViolations and numViolationsForError are used, the lower evaluated value will be used.

If the tmTamperMethod parameter is returned as VLS_DISABLE_DEFAULT_TM_TAMPER, then you must override the VLSisClockSetBack function.

B.6.5. Function Prototype  int VLSisClockSetBack(void);

B.6.6. Returns n

Returns 0 (zero) if the clock is found in non-tampered state.

n

Returns non-zero if the clock is found in tampered state.

529

530

Appendix B: Customization Features

B.6.7. Steps to Perform 1. Create the VLSconfigureTimeTamper function. 2. If the tmTamperMethod parameter is returned as VLS_DISABLE_DEFAULT_TM_TAMPER, then create the VLSisClockSetBack function. 3. Update the TIME_TAMPER_OBJS in the custom32.mak file. 4. Follow the build procedure specified in "Build Procedure" section.

B.6.8. Code Snippets VLSconfigureTimeTamper: void VLSconfigureTimeTamper ( VLSactionOnTmTamper* actionOnTmTamper, /* OUT */ VLStmTamperMethod* tmTamperMethod, /* OUT */ int* gracePeriod, /* OUT */ int* percentViolationAllowed, /* OUT */ int* numViolationForError /* OUT */ ) { if (actionOnTmTamper != NULL) { *actionOnTmTamper = /* TODO: add value here */; } if (tmTamperMethod != NULL) { *tmTamperMethod = /* TODO: add method type here */; } if (gracePeriod != NULL) { *gracePeriod = /* TODO: add grace period in seconds here */; } if (percentViolationAllowed != NULL) { *percentViolationAllowed = /* TODO: add percentage of violations here */; } if (numViolationForError != NULL) { *numViolationForError = /* TODO: add number of violations here */; } } /* VLSconfigureTimeTamper() */

VLSisClockSetBack int VLSisClockSetBack(void) { /* TODO: add the system clock tamper detection code here */ return 0; /* no clock tamper detection */ } /* VLSisClockSetBack() */

B.7. Encrypting the License Codes

531

B.7. Encrypting the License Codes For enhanced security, you can add an additional layer of encryption while generating licenses. Make sure that post-modification, your encrypted short-numeric licenses consist of numbers only. Else, the license generation will fail.

B.7.1. Executables to Rebuild n

n

In case of stand-alone licensing (application linked to the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild. n

lscgen.exe

n

lsdecode.exe

n

wlscgen.dll

B.7.2. Description Provides the vendor-specified an extra layer of encryption and decryption for the license codes.

B.7.3. Encryption Function Prototype int VLSencryptLicense ( char *decrypted_mesg, char *encrypted_mesg, int size );

B.7.4. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

decrypted_mesg

An IN parameter. The original license code.

encrypted_mesg

An OUT parameter. The encrypted license code.

size

An IN parameter.

532

Appendix B: Customization Features

Parameter

Description The size of the encrypted_mesg buffer.

Please note that the encrypted licenses code must not contain following characters: Character

Hex Value

Description

\t

0x09

The tab character

\n

0x0A

The new-line character

#

0x23

The pound sign or number sign or hash mark

(

0x28

The opening round parentheses

)

0x29

The closing round parentheses

,

0x2C

The comma mark

-

0x2D

The hyphen or dash or minus sign

B.7.5. Decryption Function Prototype int VLSdecryptLicense ( char *encrypted_mesg, char *decrypted_mesg, int size );

B.7.6. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

 encrypted_mesg

An IN parameter. The encrypted license code.

decrypted_mesg

An OUT parameter. The original license code.

size

An IN parameter. The size of the decrypted_mesg buffer.

B.7.7. Steps to Perform 1. Create the VLSencryptLicense function. 2. Create the VLSdecryptLicense function. 3. Update the ENCRYPT_LIC_OBJS variable in the custom32.mak file.

B.7. Encrypting the License Codes

4. Update the DECRYPT_LIC_OBJS variable in the custom32.mak file. 5. Follow the build procedure specified in Build Procedure.

B.7.8. Code Snippets The VLSencryptLicense Function int VLSencryptLicense ( char *decrypted_mesg, /* IN */ char *encrypted_mesg, /* OUT */ int size /* IN */ ) { if (decrypted_mesg == NULL) { return 1; /* non-zero to mark failure */ } if (encrypted_mesg == NULL) { return 1; /* non-zero to mark failure */ } if (size == 0) { return 1; /* non-zero to mark failure */ } /* TODO: add the encryption code here */ return 0; /* successful encryption */ }

The VLSdecryptLicense Function int VLSdecryptLicense

533

534

Appendix B: Customization Features

( char *encrypted_mesg, /* IN */ char *decrypted_mesg, /* OUT */ int size /* IN */ ) { if (encrypted_mesg == NULL) { return 1; /* non-zero to mark failure */ } if (decrypted_mesg == NULL) { return 1; /* non-zero to mark failure */ } if (size == 0) { return 1; /* non-zero to mark failure */ /* TODO: add the decryption code here */ return 0; /* successful decryption */ } }

B.8. Encrypting the Upgrade License Codes

535

B.8. Encrypting the Upgrade License Codes The upgrade licenses generated using RMS are encrypted using proprietary encryption algorithm. However, for enhanced security, you can add an additional layer of encryption while generating upgrade licenses.

B.8.1. Executables to Rebuild n

n

In case of stand-alone licensing (application linked to the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild. n

ulscgen.exe

n

ulsdcod.exe

B.8.2. Description Provides the vendor-specified extra layer of encryption and decryption for communication between a client and the license server.

B.8.3. Function Prototype int VLSencryptUpgradeLicense ( char *decrypted_mesg, char *encrypted_mesg, int size );

B.8.4. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

decrypted_mesg

An IN parameter. The original upgrade license code.

encrypted_mesg

An OUT parameter. The encrypted upgrade license code.

size

An IN parameter. The size of the encrypted_mesg buffer.

536

Appendix B: Customization Features

B.8.5. Function Prototype  int VLSdecryptUpgradeLicense ( char *encrypted_mesg, char *decrypted_mesg, int size );

B.8.6. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

encrypted_mesg

An IN parameter. The encrypted upgrade license code.

decrypted_mesg

An OUT parameter. The original upgrade license code.

size

An IN parameter. The size of the decrypted_mesg buffer.

B.8.7. Steps to Perform 1. Create the VLSencryptUpgradeLicense function. 2. Create the VLSdecryptUpgradeLicense function. 3. Update the ENCRYPT_UPG_LIC_OBJS variable in the custom32.mak file. 4. Update the DECRYPT_UPG_LIC_OBJS variable in the custom32.mak file. 5. Follow the build procedure specified in Build Procedure.

B.8.8. Code Snippets Refer to the code snippets of VLSencryptLicense and VLSdecryptLicense.

B.9. Encrypting License Server Messages

537

B.9. Encrypting License Server Messages In RMS, the entire network communication is encrypted. However, you can add an additional layer of encryption and decryption for enhanced security. This customization requires changes in the license server as well as the client application. In case of stand-alone licensing, since the license server module is part of the client library itself, this extra layer of encryption is not required.

B.9.1.  Executables Need to be Rebuild n

The license server (lservnt.exe).

n

The client application.

Please refer to Build Procedure.

B.9.2. Description Provides the vendor-specified extra layer of encryption and decryption for communication between a client and the license server.

B.9.3. Function Prototype int VLSencryptMsg ( char *decrypted_mesg, char *encrypted_mesg, int size );

B.9.4. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

decrypted_mesg

An IN parameter. The original network message.

encrypted_mesg

An OUT parameter. The encrypted network message.

size

An IN parameter. The size of the encrypted_mesg buffer.

538

Appendix B: Customization Features

B.9.5. Function Prototype int VLSdecryptMsg ( char *encrypted_mesg, char *decrypted_mesg, int size );

B.9.6. Returns n

Returns 0 (zero) on success.

n

Returns non-zero on failure.

Parameter

Description

encrypted_mesg

An IN parameter. The encrypted network message.

decrypted_mesg

An OUT parameter. The original network message.

size

An IN parameter. The size of the decrypted_mesg buffer.

B.9.7. Steps to Perform 1. Create the VLSencryptMsg function. 2. Create the VLSdecryptMsg function. 3. Update the ENCRYPT_MSG_OBJS variable in the custom32.mak file. 4. Update the DECRYPT_MSG_OBJS variable in the custom32.mak file. 5. Follow the build procedure specified in Build Procedure.

B.9.8. Code Snippets Refer to the code snippets of VLSencryptLicense and VLSdecryptLicense.

B.10. Vendor-specified 4-Byte Custom Fingerprint of a System

539

B.10. Vendor-specified 4-Byte Custom Fingerprint of a System RMS provides you the capability to have a vendor specified customized 4-byte fingerprint along with the standard fingerprints of a system.

B.10.1. Executables Need to be Rebuild n

n

In case of stand-alone licensing (application linked to the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild only if the licenses are server-locked and the client application needs to be rebuild only if the licenses are client-locked.

n

echoid.exe

n

wechoid.exe

B.10.2. Description  For the server-locked licenses, locking is verified at the time of loading/adding licenses. For the clientlocked licenses, locking is verified at the time of license request. Apart from the standard fingerprints of a system, you can lock licenses to a hardware device (dongle) or a software-based implementation to generate a unique 4-byte value. You have to implement a customized Host ID function that needs to be ed using the VLSsetHostIdFunc function. This function must return an unsigned long value based on the customized logic that is unique for each system.

B.10.3. Function Prototype (of the Callback Function) unsigned long GetCustomValue(void);

B.10.4. Steps to Perform 1. Create the custom host ID function, say GetCustomValue. 2. Update the CUSTOM_LOCK_OBJS variable in the custom32.mak file. 3. the custom host ID function on the server. 4. the custom host ID function on the client. 5. If the custom host ID function name is different from GetCustomValue, then update the function name in \MsvcDev\Samples\API\echomain.c. Search for the call of VLSsetHostIdFunc.

540

Appendix B: Customization Features

6. If the custom host ID function name is different from “GetCustomValue”, then update the function name in \MsvcDev\Samples\API\ wechoiddlg.p. Search for the call of VLSsetHostIdFunc. 7. Follow the build procedure specified in Build Procedure.

B.10.5. Code Snippets  Create the Custom Host ID Function unsigned long GetCustomValue(void) { unsigned long customValue = 0; /* TODO: add the customized logic for generating unique 4-byte custom host id value or read from some dongle */ return customValue; }

the Custom Host ID Function on the License Server

VLSsetHostIdFunc is used to the function with the license server. This registration needs to be done in the VLSserverVendorInitialize function. #include "lserv.h" extern unsigned long GetCustomValue(); LSERV_STATUS VLSserverVendorInitialize(void) { VLSsetHostIDFunc(&GetCustomValue); return LSERV_STATUS_SUCCESS; }

the Custom Host ID Function on the Client

Here you need to call VLSsetHostIDFunc in the client application, in the similar way it was done in VLSserverVendorInitialize. #include "lserv.h" extern unsigned long GetCustomValue(); int main(int argc, char* argv[]) { VLSinitialize(); VLSsetHostIDFunc(&GetCustomValue); /* here client application code */ return 0; }

B.11. Vendor-specified Custom Extended Fingerprint of a System

541

B.11. Vendor-specified Custom Extended Fingerprint of a System RMS provides you the capability to have a vendor specified extended 64-byte fingerprint along with the standard fingerprints of machine.

B.11.1. Executables Need to be Rebuild n

n

In case of stand-alone licensing (application linked with the stand-alone library or the integrated library), the client application needs to be rebuild. In case of network licensing, the license server (lservnt.exe) needs to be rebuild only if the licenses are server-locked and the client application needs to be rebuild only if the licenses are client-locked.

n

echoid.exe

n

wechoid.exe

B.11.2. Description For server locked licenses, locking is verified at the time of loading/adding licenses to server, while for client locked licenses, locking is verified at the time of request. Apart from the standard fingerprint of machine, you can lock licenses on some kind of hardware device (dongle) or software based implementation to generate a unique extended custom value for each machine. You have to implement a function that will be used for generating the customized fingerprint in extended format (64-byte value) and that needs to be ed using the VLSsetCustomExFunc function.

B.11.3. Function Prototype (of Extended Custom Lock Function)  long myGetCustExTableFunc ( VLScustomEx* pCustomExTable, unsigned long* pulCount ); This function can define multiple extended custom locking value and store it in individual element of VLScustomEx array. The maximum number allowed is VLS_MAX_CUSTOMEX_COUNT. Please refer lserv.h for its value. Parameter

Description

pCustomExTable

An OUT parameter. A pointer to the array of the VLScustomEx structure. If ed as NULL, then as an output pulCount will contain the required number of elements in array pointed by this parameter.

pulCount

An IN/OUT parameter. A pointer to unsigned long that specifies the number of elements in the

542

Appendix B: Customization Features

Parameter

Description array pointed by the pCustomExTable parameter.

On input, the pulCount parameter of the extended custom function should specify the count of the VLScustomEx array pointed to by the pCustomExTable parameter. If the buffer is not large enough to hold the returned customEx fingerprint table, the function should set this parameter equal to the required count. On output, the function should update the pulCount parameter value to specify the actual count of the VLScustomEx objects that are received through this custom function.

B.11.4. Returns  n

Returns LS_SUCCESS(0) on success.

n

Returns non-zero on failure.

B.11.5. Steps to Perform 1. Create the extended custom lock function (for example, GetCustomExValue). 2. Update the CUSTOM_EX_LOCK_OBJS variable in the custom32.mak file. 3. the extended custom lock function on the license server. 4. the extended custom lock function on the client. 5. If the extended custom lock function name is different from “GetCustomExValue”, then update the function name in \MsvcDev\Samples\API\echomain.c. Search for the call of the VLSsetCustomExFunc function. 6. If the extended custom lock function name is different from “GetCustomExValue”, then update the function name in \MsvcDev\Samples\API\ wechoiddlg.p. Search for the call of the VLSsetCustomExFunc function. 7. Follow the build procedure specified in Build Procedure.

B.11.6. Code Snippets Create the Extended Custom Lock Function long GetCustomExValue ( VLScustomEx* pCustomExTable, /* OUT */ unsigned long* pulCount /* IN/OUT */ ) { if (pulCount == NULL) { return 1; /* non-zero to mark failure */ } if ((*pulCount == 0) || (*pulCount > VLS_MAX_CUSTOMEX_COUNT)) {

B.11. Vendor-specified Custom Extended Fingerprint of a System

543

return 1; /* non-zero to mark failure */ } /* TODO: add the customized logic for generating extended custom value(s) or read from some dongle(s) */ return 0; }

the Extended Custom Lock Function on the License Server

VLSsetCustomExFunc is used to the function with the license server. This registration part needs to be done in the VLSserverVendorInitialize function. #include "lserv.h" extern long GetCustomExValue(VLScustomEx* pCustomExTable, unsigned long* pulCount); LSERV_STATUS VLSserverVendorInitialize(void) { VLSsetCustomExFunc(&GetCustomExValue); return LSERV_STATUS_SUCCESS; }

the Extended Custom Lock Function on the Client

Here you need to call VLSsetCustomExFunc in the client application, in the similar way it was done in VLSserverVendorInitialize. #include "lserv.h" extern long GetCustomExValue(VLScustomEx* pCustomExTable, unsigned long* pulCount); int main(int argc, char* argv[]) { VLSinitialize(); VLSsetCustomExFunc(&GetCustomExValue); /* here client application code */ return 0; }

544

Appendix B: Customization Features

B.12. Customizing the Stand-alone License File Names To override the default license file path or the environment variables used to locate the license files.

B.12.1. Executables Need to Rebuild Client application (follow the build procedure specified in Build Procedure).

B.12.2. Description RMS reads a number of files to determine what licenses are available and how the license server should operate. For stand-alone applications, these files are: n

lservrc - The license file, which contains one or more license strings.

n

lservrccnf - The license server configuration file, which contains license server options.

Although you can change the names of these files by using the appropriate environment variable, this can cause a conflict if multiple stand-alone applications from different developers are installed on the same computer since only one environment variable affects the entire computer. If environment variables aren't used, a different developer can overwrite the default license file when a new application is installed. VLSsetFileName should be called before the VLSinitialize function.

B.12.3.  Enumeration Data Type typedef enum { VLS_LSERVRC, VLS_LSERVRCCNF, VLS_ULSERVRC,   VLS_GENERICCONF, }VLS_FILE_TYPE;

B.12.4. Function Prototype LS_STATUS_CODE VLSsetFileName ( VLS_FILE_TYPE filetype, /*IN*/ unsigned char* fileName,/*IN*/ unsigned char* unused1, unsigned long* unused2 );

B.12. Customizing the Stand-alone License File Names

B.12.5. Returns n

Returns LS_SUCCESS(0) on success.

n

Returns non-zero on failure.

Parameter

Description

filetype

An IN parameter. The type of license file (lservrc, lservrccnf, or ULSERVRC) or configuration file you are going to provide a customized location/name.

fileName

An IN parameter. The custom name that you want to use.

unused1

Reserved, Use NULL for this value.

unused2

Reserved, Use NULL for this value.

B.12.6. Steps to Perform 1. Call the VLSsetFileName function in client application before the VLSinitialize function call. 2. Follow the build procedure specified in Build Procedure.

B.12.7. Code Snippet #include "lserv.h" int main(int argc, char* argv[]) { LS_STATUS_CODE statusCode = LS_SUCCESS; statusCode = VLSsetFileName(VLS_LSERVRC, "c:\\s\\app\\lservrc", NULL, NULL); if (statusCode != LS_SUCCESS) { return 1; /* non-zero to mark failure */ } statusCode = VLSinitialize(); if (statusCode != LS_SUCCESS) { return 1; /* non-zero to mark failure */ } /* here client application code */ return 0; }

545

546

Appendix B: Customization Features

B.13. Configuration File to Customize the Standard Custom Fingerprint Caching Since the 8.2.x release, fingerprint caching was allowed to improve the performance while loading stand-alone licenses (it reduced the load time typically when fingerprints—such as IP address, disk ID, host name, Ethernet address, computer ID key, and hard disk serial number—were used). However, this default caching conflicted with the standard custom locking when fingerprint values changed dynamically. To overcome this, since the 8.3.0 release (Windows) and 8.4.1 release (non-Windows), you can use a configuration file to set the standard custom fingerprint caching as ON or OFF. The table below summarizes the default caching settings for the various locking criteria:

Default Fingerprint Caching (ON\OFF)

Caching Customization Option Provided?

ON

No. You cannot disallow the default caching setting.

Standard Custom

ON

Yes. Using the configuration file (as described in this topic). You are recommended to disable caching using the configuration file in case of multiple standard custom criteria or when these change dynamically. For example, if license 1 is locked on UID 1 and license 2 is locked UID 2, you should use the configuration file to disable caching. Else, the first fingerprint retrieved will be cached.

Extended Custom

OFF

No. You can implement your own caching mechanism as described in the custexlock sample (available at: \Samples\Customize components for Windows)

Locking Option n n n n n n n n

IP address Disk ID Host name Ethernet address Computer ID key Hard disk serial number ID PROM Processor ID

B.13. Configuration File to Customize the Standard Custom Fingerprint Caching

547

B.13.1. Configuration File for Customizing Standard Custom The configuration file can have the MACHINEIDCACHE section with the key-value pairs for CustomLockCachingOff. Where, n

n

Setting the value of CustomLockCachingOff key as 1 and 0, turns off and on the caching of extended custom lock fingerprint, respectively. Setting the value other than 0 or 1 turns on the caching.

For example, see a sample configuration file snippet: ---------------------------[MACHINEIDCACHE] CustomLockCachingOff 0 ---------------------------Setting the value 0 above, for the CustomLockCachingOff key, turns on the caching of custom lock fingerprint

B.13.2. Calling the VLSsetFileName API to Integrate the Configuration File The API, VLSsetFileName, is also enhanced to read the configuration file (see Customizing the Standalone License File Names). The new value is VLS_GENERICCONF added to the enum VLS_FILE_TYPE defined in lserv.h. For example, calling the above API as below: VLSsetFileName(VLS_GENERICCONF, "GenericConfig", NULL, NULL); This means that a configuration file named "GenericConfig" is to be read by the client library from the application directory. Notes: The fingerprints will be cached under the following scenarios: n

When the configuration file is not set using the API VLSsetFileName.

n

When the configuration file is set, but does not exist.

n

When the configuration file exists, but the required section is not present.

n

When the configuration file and the required section exist, but the required key is not present in that section.

548

Appendix B: Customization Features

B.14. Setting Custom Client Information You can set custom client information—name and hostname—using a new client side API VLSsetCustomData. This information is ed to the license server when a license request API or its variant is called. It can then be retrieved through the: n

License server usage logs (in the and host name fields of the log file)

n

Query APIs (VLSgetClientInfo and VLSgetHandleInfo)

n

Wlm and lsmon utilities

B.14.1. Function Prototype LS_STATUS_CODE VLSsetCustomData ( VLScustomData *pCustomData /*IN*/ );

B.14.2. Description The API sets the custom client information—name and hostname. It takes a pointer to the structure VLScustomData. To set the custom information, call VLSsetCustomData before the license request API, but after the system initialization API. If the VLSsetCustomData API is not called at all (or not called in the correct sequence), the default and host name is obtained. If the client information is dynamic (for example, it changes for different clients), then you need to call the API individually for each client instance. If the API VLSsetSharedId or VLSsetSharedIdValue is called, it overrides the value set by the VLSsetCustomData API. This is because the former APIs can also set the name or hostname based on the sharedID value.

B.14. Setting Custom Client Information

549

B.14.3. Parameters Parameter

Description

VLScustomData

An IN parameter. Before ing the pointer to this structure, ensure that structSz field of VLScustomData structure is initialized to current size of VLScustomData. typedef struct custom_data_struct { unsigned long structSz; char name[VLS_CUSTOM_DATA_FIELD_SIZE + 1]; char hostname[VLS_CUSTOM_DATA_FIELD_SIZE + 1]; } VLScustomData; n n

The custom information cannot exceed 31 bytes. It cannot contain the following special characters: n `~!@#$^&*()=+[]{}\|;:',/" n Space, tab, and new line

B.14.4. Returns Error

Description

When this API is called before VLSinitialize VLS_LIBRARY_ NOT_INITIALIZED n The name or hostname contain special characters (mentioned above). VLS_CALLING_ n The VLSsetCustomData API is called with NULL as its input parameter. ERROR n VLScustomData structure is ed in the VLSsetCustomData API without initializing the ‘structSz’ field. n Either name or hostname (fields of the VLScsutomData structure) is initialized with empty values and ed in the VLSsetCustomData API.

550

Appendix B: Customization Features

B.15. Build Procedure B.15.1. How to Use the custom32.mak File? The Makefile (custom32.mak), located at \English\MsvcDev\Samples\Customize components>, is used for building the following customized executables: n

lservnt.exe - The license server.

n

lscgen.exe - The command-line license code generator.

n

lsdecode.exe - The command-line license code decoder.

n

ulscgen.exe - The command-line license upgrade code generator.

n

ulsdcod.exe - The command-line license upgrade code decoder.

n

echoid.exe - The command-line utility to obtain the system fingerprint.

n

wechoid.exe - A Windows-based graphical utility to obtain the system fingerprint.

n

wlscgen.dll - A vendor-specified extra layer of encryption the plug-in for wlscgen.exe.

The default location of wlscgen.exe is \English\Tools. lscgen.dll need to be placed with Wlscgen.exe, so that the licenses generated by WlscGen will use the customized license encryption. Move Wlscgen.dll to the directory containing WlscGen.exe.

You have to fill up the value of following variables in the custom32.mak file: n

SRV_VENDOR_INIT_OBJS

n

VENDOR_INFO_OBJS

n

CHANGE_PORT_OBJS

n

SERVER_HOOK_OBJS

n

TIME_TAMPER_OBJS

n

ENCRYPT_LIC_OBJS

n

DECRYPT_LIC_OBJS

n

ENCRYPT_UPG_LIC_OBJS

n

DECRYPT_UPG_LIC_OBJS

n

ENCRYPT_MSG_OBJS

n

DECRYPT_MSG_OBJS

B.15. Build Procedure

n

CUSTOM_LOCK_OBJS

n

CUSTOM_EX_LOCK_OBJS

551

The following tables depicts the relationship between the above-mentioned defines and the executables: Defines in custom32.mak

Network

Stand-alone

SRV_VENDOR_INIT_OBJS

lservnt.exe

The client application

VENDOR_INFO_OBJS

lservnt.exe

NA

CHANGE_PORT_OBJS

n n

lservnt.exe Client application 

NA

SERVER_HOOK_OBJS

lservnt.exe

The client application

TIME_TAMPER_OBJS

lservnt.exe

The client application

ENCRYPT_LIC_OBJS DECRYPT_LIC_OBJS

n n n n

ENCRYPT_UPG_LIC_OBJS DECRYPT_UPG_LIC_OBJS

n n n

ENCRYPT_MSG_OBJS DECRYPT_ MSG_OBJS CUSTOM_LOCK_OBJS

n n n n n n

CUSTOM_EX_LOCK_OBJS

n n n n

lservnt.exe lscgen.exe lsdecode.exe wlscgen.dll

n n n n

lservnt.exe ulscgen.exe ulsdcod.exe lservnt.exe Client Application lservnt.exe Client Application echoid.exe wechoid.exe lservnt.exe Client Application echoid.exe wechoid.exe

n n n

Client Application lscgen.exe lsdecode.exe wlscgen.dll

Client Application ulscgen.exe ulsdcod.exe

NA n n n

n n n

Client Application echoid.exe wechoid.exe Client Application echoid.exe wechoid.exe

Based on the licensing mode, whether stand-alone or network, you need to rebuild your executables.

B.15.2. Stand-alone Licensing Use the following command on the command prompt: If you want to build the samples provided with RMS, use the following command:

552

Appendix B: Customization Features

B.15.3. Network Licensing Use the following command on the command prompt: If you want to build the samples provided with RMS, use the following command: This command will build all the required components based on the variables updated. For example, if you specified the value of TIME_TAMPER_OBJS as "tmtampcf.obj", issue the build command. This command will build only lservnt.exe. In case if you want to build a particular component, then use the following command: For example, if you want to build only echoid.exe, then use the following command:

B.15.4. When and How to Rebuild the Client Application? If you are using stand-alone licensing, your client application must be linked with the new object files before linking with the RMS licensing library. You do not need to build lservnt.exe. If you are using network licensing, then you have to update your client application in following scenarios: n

An extra layer of encryption for communication between the client and the license server.

n

Communication over a vendor-specified license server port.

n

Vendor specified 4-byte custom fingerprint of a system.

n

Vendor specified custom extended fingerprint of a system.

B.15.5. How to Build Your Client Application? 1. Use the same object files that were used while generating the customized executables using the custom32.mak file. 2. Add the object files to the link command of your application. 3. If required, set the callback function using the available API functions. For example. in case of custom host ID, you need to call VLSsetHostIdFunc in client application. While in case of protection against time tampering, you do not need to call any function in the client application. 4. Build the client application.

Index A adding feature licensing information APIs client license code generation upgrade license code generator authenticating the license manager

126, 128 1 307 262 28-29

B basic license code generation functions broadcast intervals retrieving setting

317 57 57

C challenge-response mechanism 28-29 CHALLENGE structure, defined 28 CHALLENGERESPONSE structure, defined 28 checking out remote commuter authorization184 client API 1 client feature information, retrieving 98 client library initializing 8 retrieving information 139 tracing calls 169 client query functions 82 client utility functions 123, 139 code struct field setting functions 311, 387 codeT 307 commuter authorization, remote 184 commuter licensing 175, 182

D deleting feature licensing information destroying the handle for lscgen.h disable auto timer displaying error messages

131 320 81 165, 167

E environment variables LS_MAX_GRP_QLEN LS_MAX_HOLD_SEC LS_MAX_QLEN LS_MAX_WAIT_SEC error codes upgrade license generation functions error handling setting error message display error messages, displaying errors, retrieving

246 246 246 246 511 167 166 167 165 327-328

F feature licensing information adding deleting retrieving feature names, retrieving feature time left information retrieving functions capacity license client query client utility license queuing redundancy

126, 128 131 112 116 119 213, 219 82 123, 139 237 189

554

Index

upgrade license

262

single-call licensing disabling

G get remote computer locking info

182

H host ID setting host names retrieving setting

54 35 32

local license renewal locating the license server LS_LIBVERSION structure, defined LS_MAX_QLEN lscgen.h handle destroying LSGetMessage LSRelease LSRequest

76 123 139 246 320 165 15 9

M I

machine names, retrieving

initializing network system 482 persistence data 480, 482 stand-alone system 480 initializing fields of the machineID 38, 72 initializing the client library 8 initializing the server info 53 installing remote commuter authorization 187

K key time left information retrieving

6

123

P persistence data initializing port numbers retrieving printing errors

480, 482 37 327-328

R 121

L license code generation API 307 license generation function return codes 505 license manager authenticating 28 license revocation 156, 457 license server APIs license code generation

307

locating licenses local vs. remote renewal of releasing requesting

123 75 15, 23 9, 19

redundant license server releasing licenses remote commuter authorization remote renewal time, setting requesting licenses reserved characters retrieving broadcast intervals client feature information client library information errors feature licensing information feature names feature time left information license time left information machine names server host names server port numbers time-out intervals time drift information

189 15, 23 184 80 9, 19 317 57 98 139 327-328 112 116 119 121 123 35 37 60 118

Index

version information revocation

114, 117 156, 457

S Sentinel RMS APIs capacity license client

219

175

license code generation

307

license queuing

237

redundancy

189

upgrade license

261

host names setting broadcast intervals code struct fields error handling host ID remote renewal time server names time-out intervals shared IDs shutting down lserv single-call licensing disabling sntlInitNetworkSystem sntlInitStandaloneSystem structure definitions CHALLENGE CHALLENGERESPONSE LS_LIBVERSION VLSclientInfo

T time-out intervals retrieving setting time drift information retrieving tracing client-library calls

60 59 118 169

1

commuter license

servers retrieving host names retrieving port numbers setting

555

35 37 32 57 311, 387 166 54 80 32 59 63, 65 140 6 482 480 28 28 139 95

U ucodeT Struct 264 ulcCode 293 updating 25 updating licenses 25 Upgrade License Code Generation Return Codes511 using the Sentinel RMS client API 1

V version information retrieving 114, 117 VLSaddFeature 126, 191 VLSaddFeatureToFile 128, 193 VLSaddServerToPool 195 VLSbatchUpdate 25 VLScalculateLicenseHash 70 VLScgAllowAdditive 343-344 VLScgAllowCapacity 396 VLScgAllowCapacityLic 394 VLScgAllowClientLockInfo 382 VLScgAllowClockTamperFlag 385 VLScgAllowCodegenVersion 392 VLScgAllowCommuterLicense 361 VLScgAllowCommuterMaxCheckoutDays 363 VLScgAllowFeatureName 333 VLScgAllowFeatureVersion 335 VLScgAllowGracePeriod 436 VLScgAllowGracePeriodFlag 434 VLScgAllowHeldLic 390 VLScgAllowKeyHoldtime 422 VLScgAllowKeyHoldUnits 420 VLScgAllowKeyLifetime 346 VLScgAllowKeyLifeUnits 418 VLScgAllowKeysPerNode 409

556

Index

VLScgAllowLicBirth VLScgAllowLicenseType VLScgAllowLicExpiration VLScgAllowLocalRequestLockCrit VLScgAllowLocalRequestLockCritFlag VLScgAllowLockMechanism VLScgAllowLockModeQuery VLScgAllowLogEncryptLevel VLScgAllowMajorityRuleFlag VLScgAllowMultiKey VLScgAllowMultipleServerInfo VLScgAllowNetworkFlag VLScgAllowNumKeys VLScgAllowOutLicType VLScgAllowRedundantFlag VLScgAllowSecrets VLScgAllowServerLockInfo VLScgAllowSharedLic VLScgAllowShareLimit VLScgAllowSiteLic VLScgAllowSoftLimit VLScgAllowStandAloneFlag VLScgAllowTeamCriteria VLScgAllowTrialLicFeature VLScgAllowVendorInfo VLScgAllowVendorInfoExt VLScgAllowVmDetection VLScgCleanup VLScgDecodeLicenseExt VLScgDecodeLicenseRevocationTicket VLScgGenerateLicense VLScgGetErrorLength VLScgGetErrorMessage VLScgGetLicenseMeterUnits VLScgGetNumErrors VLScgGetTrialLicenseMeterUnits VLScgInitialize VLScgPrintError VLScgReset VLScgSetAdditive VLScgSetCapacityFlag VLScgSetCapacityUnits VLScgSetClientLockInfo VLScgSetClientLockMechanism VLScgSetClientServerLockMode VLScgSetClockTamperFlag

424 337 428 441 439 380 367 353 371 399 373 349 363-365 387 369 401 375 355 358 411 416 348 355 339 404 406 443 320-321 452 466-467 447, 450 325 326 455 324 456 319 327-328 321 345 395 397 383, 444 381 368 386

VLScgSetCodegenVersion VLScgSetCodeLength VLScgSetCommuterLicense VLScgSetFeatureName VLScgSetFeatureVersion VLScgSetGracePeriodFlag VLScgSetGracePeriodHours VLScgSetHoldingCrit VLScgSetKeyHoldtime VLScgSetKeyHoldtimeUnits VLScgSetKeyLifetime VLScgSetKeyLifetimeUnits VLScgSetKeysPerNode VLScgSetKeyType VLScgSetLicBirthDay VLScgSetLicBirthMonth VLScgSetLicBirthYear VLScgSetLicenseType VLScgSetLicExpirationDay VLScgSetLicExpirationMonth VLScgSetLicExpirationYear VLScgSetLicType VLScgSetLoadSWLicFile VLScgSetLogEncryptLevel VLScgSetMajorityRuleFlag VLScgSetNumClients VlScgSetNumericType VLScgSetNumFeatures VLScgSetNumKeys VLScgSetNumSecrets VLScgSetNumServers VLScgSetOutLicType VLScgSetRedundantFlag VLScgSetSecrets VLScgSetServerLockInfo1 VLScgSetServerLockInfo2 VLScgSetServerLockMechanism1 VLScgSetServerLockMechanism2 VLScgSetSharedLicType VLScgSetShareLimit VLScgSetSiteLicInfo VLScgSetSoftLimit VLScgSetStandAloneFlag VLScgSetTeamCriteria VLScgSetTrialDaysCount VLScgSetTrialHours

393 332 362 334 336 434 438 391 423 421 347 419 410 400 426 425 427 338 430 429 431 389 433 354 372 384 432 413-415 366 403 374 388 370 402 376 379 377 378 356 359 412 417 352 356 340 342

Index

VLScgSetVendorInfo VLScgSetVendorInfoExt VLScgSetVmDetection VLSchangeUsageLogFileName VLSCleanup VLSclientInfo VLSdecodeUpgradelockCode VLSdeleteFeature VLSdeleteFeatureExt VLSdeleteLicenseFromFile VLSdeleteLicenseFromFileExt VLSdelServerFromPool VLSdisableAutoTimer VLSdisableEvents VLSdisableLicense VLSdiscover VLSdiscoverExt VLSenableLocalRenewal VLSerrorHandle VLSgeneratePermissionTicket VLSgeneratePermissionTicketExt VLSgenerateUpgradeLockCode VLSgetActiveHandleList VLSgetBroadcastInterval VLSgetCapacityFromHandle VLSgetCapacityList VLSgetClientInfo VLSgetCommuterCode VLSgetCommuterCode call VLSgetCommuterInfo VLSgetServer VLSgetDistbCrit VLSgetDistbCritToFile VLSgetFeatureFromHandle VLSgetFeatureInfo VLSgetFeatureInfoExt VLSgetFeatureTimeLeftFromHandle VLSgetGraceRequestFlag VLSgetHandleInfo VLSgetHandleStatus VLSgetKeyTimeLeftFromHandle VLSgetLastErrorStatusFromHandle VLSgetLeaderServerName VLSgetLibInfo VLSgetLicenseInfo VLSgetLicenseInfoExt

405 407 444 301 17 95 294 131 231 133 136 197 81 299 6 123 199 76 164 458 459 291 101 57 233 227 98 184 184 179 35 202 204 116 112 225 119 69 100 254 121 102 206 139 89 92

VLSgetLicInUseFromHandle VLSgetLicSharingServerList VLSgetMachineID VLSgetMachineIDString VLSgetPoolServerList VLSgetQueuedClientInfo VLSgetQueuedLicense VLSgetServerList VLSgetServerNameFromHandle VLSgetServerPort VLSgetTimeDriftFromHandle VLSgetTimeoutInterval VLSgetTrialPeriodLeft VLSgetVersionFromHandle VLSgetVersions VLSinitialize VLSinitMachineID VLSinitQueuePreference VLSinitServerInfo VLSinitServerList VLSinstallCommuterCode VLSinstallCommuterCode call VLSisLocalRenewalDisabled VLSisVirtualMachine VLSlicense VLSmachineIDtoLockCode VLSqueuedRequestExt VLSreleaseExt VLSremoveQueue VLSremoveQueuedClient VLSrequestExt VLSrevokeByPermissionTicket VLSrevokeLicense VLSscheduleEvent VLSsetBroadcastInterval VLSsetServer VLSsetCustomExFunc VLSsetGraceRequestFlag VLSsetHoldTime VLSsetLicensePrecedence VLSsetRemoteRenewalTime VLSsetServerLogState VLSsetServerPort VLSsetSharedId VLSsetSharedIdValue VLSsetTeamId

557

103 208 40-42, 45 182 210 248 257 52 50 37 118 60 150 117 114 8 38, 72 259 53 51 187 187 77 72 3 47 244 23 252 250 19 157 156, 160 297-298, 483 57 32 55 67 61, 67 147 80 211 36 63 65 63

558

Index

VLSsetTimeoutInterval 59 VLSsetTraceLevel 169 VLSsetErrorFile 167 VLSshutDown 140 VLSucgAllowUpgradeCapacity 284 VLSucgAllowUpgradeFlag 279 VLSucgAllowUpgradeVersion 282 VLSucgDecodeLicense 295 VLSucgGenerateLicense 288 VLSucgGetErrorLength 270 VLSucgGetLicenseMeterUnits 290 VLSucgInitialize 266 VLSucgPrintError 272 VLSucgReset 268 VLSucgSetBaseFeatureName 274 VLSucgSetBaseFeatureVersion 276 VLSucgSetUpgradeCapacity 286 VLSucgSetUpgradeCode 278 VLSuninstallAndReturnCommuterCode 181 VLSupdateQueuedClient 255 VLSRevocationTicket 461, 463 VM detection 72, 443-444