Document Revision History

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

Revision Action/Change
A B C D E F G H J L Updated for the 8.2.0 Windows release Updated for the 8.2.1 Windows 64-bit release Updated for the enhancements and problems corrected in the 8.2.3 Windows (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.3.0 Windows (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.4.0 Windows (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.4.1 Windows (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.4.1 Linux (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.4.1 Macintosh (32-bit and 64-bit) release Updated for the enhancements and problems corrected in the 8.5.0 Windows (32-bit and 64-bit) release

Date
May 2008 Nov 2008 July 2009 October 2009 May 2010 Oct 2010 Mar 2011 May 2011 July 2011

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

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 registered trademarks of SafeNet, Inc. All other product names referenced herein are trademarks or registered 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 terms 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. VLSsetContactServer 1.14. VLSgetContactServer 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
1.33. VLSgetTimeoutInterval
1.34. VLSsetHoldTime
1.35. VLScontrolRemoteSession
1.36. VLSsetSharedId/ VLSsetTeamId
1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue
1.38. VLSsetGraceRequestFlag
1.39. VLSgetGraceRequestFlag
1.40. VLScalculateLicenseHash
1.41. VLSisVirtualMachine
Local vs. Remote Renewal of License Tokens
1.42. VLSdisableLocalRenewal
1.43. VLSenableLocalRenewal
1.44. VLSisLocalRenewalDisabled
1.45. VLSgetRenewalStatus
1.46. VLSsetRemoteRenewalTime
1.47. VLSdisableAutoTimer
The Client Query Functions
1.48. VLSlicenseInfo (license_info_struct)
1.49. VLSgetLicenseInfo
1.50. VLSgetLicenseInfoExt
1.51. client_info_struct
1.52. VLSgetClientInfo
1.53. VLSgetHandleInfo
1.54. VLSgetActiveHandleList
1.55. VLSgetLastErrorStatusFromHandle
1.56. VLSgetLicInUseFromHandle
The Feature Query Functions
1.57. feature_info_struct (VLSfeatureInfo)
1.58. VLSgetFeatureInfo
1.59. VLSgetVersions
1.60. VLSgetFeatureFromHandle
1.61. VLSgetVersionFromHandle
1.62. VLSgetTimeDriftFromHandle 1.63. VLSgetFeatureTimeLeftFromHandle 1.64. VLSgetKeyTimeLeftFromHandle The Client Utility Functions 1.65. VLSdiscover 1.66. VLSaddFeature 1.67. VLSaddFeatureToFile

59
60
61
62
63
65
67
69
70
72
74
75
76
77
78
80
81
82
83
89
92
95
98
100
101
102
103
104
105
112
114
116
117
118 119 121 122 123 126 128

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. VLSsetUserErrorFile The Trace Licensing Operations 1.87. VLSsetTraceLevel 1.88. VLSsetUserTraceFile 1.89. VLSsetTraceHandler

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

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

175
176 178 179 181 182 184 186 187

Chapter 3: Redundancy API

189

vi

Sentinel RMS SDK API Reference Guide

3.1. VLSaddFeature
3.2. VLSaddFeatureToFile
3.3. VLSaddServerToPool
3.4. VLSdelServerFromPool
3.5. VLSdiscoverExt
3.6. VLSgetDistbCrit
3.7. VLSgetDistbCritToFile
3.8. VLSgetLeaderServerName
3.9. VLSgetLicSharingServerList
3.10. VLSgetPoolServerList
3.11. VLSsetServerLogState

191
193
195
197
199
202
204
206
208
210
211

Chapter 4: Volume Transaction Licensing API

4.1. VLSgetConsumeLimit
4.2. VLSsetConsumeLimit
4.3. VLSgetContextData
4.4. VLSsetContextData

213
214
215
217
218

Chapter 5: Capacity License API

5.1. VLSrequestExt2
5.2. VLSgetFeatureInfoExt
5.3. VLSgetCapacityList
5.4. VLSgetClientInfoExt
5.5. VLSdeleteFeatureExt
5.6. VLSgetCapacityFromHandle
5.7. VLSsetTeamId
5.8. VLSsetTeamIdValue

219
220
225
227
229
231
233
234
235

Chapter 6: License Queuing API

6.1. The License Queuing Example Code
6.2. VLSqueuePreference Struct
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

237
239
240
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

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

261
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

Chapter 8: Utility Functions

8.1. VLSscheduleEvent 8.2. VLSdisableEvents 8.3. VLSeventSleep

297
298 299 300

viii

Sentinel RMS SDK API Reference Guide

Chapter 9: Usage Log Functions

9.1. VLSchangeUsageLogFileName
9.2. VLSgetUsageLogFileName
9.3. VLSUsageAuthenticate
9.4. VLSusageFileDecrypt

301
302
303
304
306

Chapter 10: License Code Generation API

10.1. The License Code Generation Functions
10.2. CodeT Struct
About Reserved Characters and Strings
The Basic Functions
10.3. VLScgInitialize
10.4. VLScgCleanup
10.5. VLScgReset
10.6. VLScgGetLibInfo
Functions Retrieving Errors
10.7. VLScgGetNumErrors
10.8. VLScgGetErrorLength
10.9. VLScgGetErrorMessage
10.10. VLScgPrintError
10.11. VLScgPrintErrorExt
The Functions for Setting the Fields in CodeT Struct
10.12. VLScgSetCodeLength
10.13. VLScgAllowFeatureName
10.14. VLScgSetFeatureName
10.15. VLScgAllowFeatureVersion
10.16. VLScgSetFeatureVersion
10.17. VLScgAllowLicenseType
10.18. VLScgSetLicenseType
10.19. VLScgAllowTrialLicFeature
10.20. VLScgSetTrialDaysCount
10.21. VLScgAllowTrialHours 10.22. VLScgSetTrialHours 10.23. VLScgAllowAdditive 10.24. VLScgAllowAggregateLicense 10.25. VLScgSetAdditive 10.26. VLScgAllowKeyLifetime 10.27. VLScgSetKeyLifetime 10.28. VLScgAllowStandAloneFlag

307
308
311
317
318
319
320
321
322
323
324
325
326
327
328
329
332
333
334
335
336
337
338
339
340
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

Sentinel RMS SDK API Reference Guide

10.69. VLScgSetHoldingCrit
10.70. VLScgAllowCodegenVersion
10.71. VLScgSetCodegenVersion
10.72. VLScgAllowCapacityLic
10.73. VLScgSetCapacityFlag
10.74. VLScgAllowCapacity
10.75. VLScgSetCapacityUnits
10.76. VLScgSetCapacity
10.77. VLScgAllowMultiKey
10.78. VLScgSetKeyType
10.79. VLScgAllowSecrets
10.80. VLScgSetSecrets
10.81. VLScgSetNumSecrets
10.82. VLScgAllowVendorInfo
10.83. VLScgSetVendorInfo
10.84. VLScgAllowVendorInfoExt
10.85. VLScgSetVendorInfoExt
10.86. VLScgAllowKeysPerNode
10.87. VLScgSetKeysPerNode
10.88. VLScgAllowSiteLic
10.89. VLScgSetSiteLicInfo
10.90. VLScgSetNumSubnets
10.91. VLScgAllowMultipleFeature
10.92. VLScgSetNumFeatures
10.93. VLScgAllowSoftLimit
10.94. VLScgSetSoftLimit
10.95. VLScgAllowKeyLifeUnits
10.96. VLScgSetKeyLifetimeUnits
10.97. VLScgAllowKeyHoldUnits
10.98. VLScgSetKeyHoldtimeUnits
10.99. VLScgAllowKeyHoldtime
10.100. VLScgSetKeyHoldtime
10.101. VLScgAllowLicBirth
10.102. VLScgSetLicBirthMonth 10.103. VLScgSetLicBirthDay 10.104. VLScgSetLicBirthYear 10.105. VLScgAllowLicExpiration 10.106. VLScgSetLicExpirationMonth 10.107. VLScgSetLicExpirationDay 10.108. VLScgSetLicExpirationYear

391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
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. VLSverifyRevocationTicket 10.132. VLSverifyRevocationTicketExt 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_VERIFY_ERROR_LINE 10.140. VRT_VERIFY_ERRORS 10.141. VRT_REVOKE_TICKET_LINE 10.142. VRT_REVOKE_TICKET_INFO 10.143. VLSrevocationTicketInfoT

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

Chapter 11: System Initialization API

479

xii

Sentinel RMS SDK API Reference Guide

11.1. sntlInitStandaloneSystem
11.2. sntlInitNetworkSystem

480
482

Chapter 12: Persistence Cleaning API

12.1. VLScleanStandalonePersistenceInfo
12.2. VLScleanNetworkPersistenceInfo

483
484
486

Appendix A: Status Codes

A.1. Licensing Library Error and Result Codes
A.2. License Generation Error Codes
A.3. Upgrade License Error Codes
A.4. System Initialization Error Codes
A.5. Persistence Cleaning Error Codes

491
492
505
511
513
515

Appendix B: Customization Features

B.1. Architecture of Overriding the Functions
B.2. Vendor-specified License Server Initialization
B.3. Vendor-specified License Server Identification String
B.4. Changing the Default Port of the License Server
B.5. Installing Hooks on Pre/Post Request and Release Events
B.6. Protection Against Time Tampering
B.7. Encrypting the License Codes
B.8. Encrypting the Upgrade License Codes
B.9. Encrypting License Server Messages
B.10. Vendor-specified 4-Byte Custom Fingerprint of a System
B.11. Vendor-specified Custom Extended Fingerprint of a System
B.12. Customizing the Stand-alone License File Names
B.13. Configuration File to Customize the Standard Custom Fingerprint Caching
B.14. Setting Custom Client Information
B.15. Build Procedure

517
519
520
521
523
525
528
531
535
537
539
541
544
546
548
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 Courier Italic lettering Denotes keystrokes, menu items, window names or fields. Denotes syntax, prompts, and code examples. Denotes file names and directory names. Else, used for emphasis.

More Documentation Resources Document

Release Notes Sentinel RMS SDK Developers Guide Sentinel RMS API Reference WlscGen Help CodeCover Help

What's in it?
Contains product overview, summary of new features introduced in this release, and product installation Contains the complete product overview, the necessary information for licensing and distributing the applications Contains details about all the API functions, including the licensing library, license code generator, system initialization, and so on

Who Should Read it?

Developers installing the RMS SDK Developers planning and implementing licensing Developers integrating the API functions in the code

Contains details about using the Windows License Gen- Developers generating erator licenses using WlscGen Contains details about using the Windows CodeCover wrapper protection (for executables and DLLs) Contains details about using the system administration and license server configuration options Developers using the CodeCover to license applications System Administrator (on the customer site)

Sentinel RMS SDK System Administrators Help

xiv

Sentinel RMS SDK API Reference Guide

Contacting Technical Support

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

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

Provides access to knowledge base and quick downloads for various products.
E-mail-based Support
[email protected]
Telephone-based Support
United States
France
Germany
United Kingdom
Australia and New Zealand
China
India

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

0825 341000
01803 7246269
0870 7529200, +1 410 931-7520
+1 410 931-7520(Intl)
(86) 10 8851 9191
+1 410 931-7520 (Intl)

SafeNet Sales Offices

Australia +61 2 9906 2988 France +33 1 47 55 74 70 Brazil +55 11 6121 6455 Germany +49 1803 7246269 China Finland +86 10 88519191 +358 20 500 7800 Hong Kong India +852 3157 7111 +91 120 4020797 +91 120 4242958 +91 120 4020555 Korea Mexico +82 31 705 8212 +52 55 5575 1441 Taiwan UK (Camberley) 886-2-2760-3930 +44 0 1276 608000 U.S. (Virginia) U.S. (Irvine, CA) +1 703.279.4500 +1 949.450.7300

Israel +972-3-9781111 Netherlands +31 73 658 1900

Japan (Tokyo) + 81 45 6405733 Singapore +65 6243 9612

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

xv

Documentation Feedback
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 contact us, please include the following information:
n

The title, part number (if applicable), and version of the document you are referring to The version of the Sentinel RMS SDK you are using 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

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 passed 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 Developers Guide, before you begin using these functions.

Chapter 1: Sentinel RMS Licensing Library API

The Quick Client Licensing Functions

This section describes the API functions meant for quick licensingespecially for the applications that require only one license for each instance of the program. Given below is a list of the API functions:

Function
VLSlicense

Description
Initializes contact 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

1.1. VLSlicense
Client Server Static Library DLL

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

1.1.1. Syntax
LS_STATUS_CODE VLSlicense ( unsigned char unsigned char LS_HANDLE *featureName, *version, *lshandle );

Argument featureName
version lshandle (out)

Description 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. 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 Developers 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 passed 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.

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 support 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 Description n featureName is NULL n version is NULL n Both feature and version cannot be NULL at the same time.
n n

VLS_CALLING_ERROR

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

LS_INSUFFICIENTUNITS VLS_NO_SUCH_FEATURE VLS_TRIAL_LIC_EXHAUSTED LS_LICENSE_EXPIRED VLS_APP_NODE_LOCKED VLS_USER_EXCLUDED VLS_VENDORIDMISMATCH

License server does not currently have sufficient licensing units for requested feature to grant a license. License server does not have a license that matches requested feature, version and capacity. Trial license has expired. License has expired. Requested feature is node locked, but request was issued from an unauthorized machine. User or machine excluded from accessing requested feature. 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. License server is non-redundant and therefore cannot support this redundancy-related operation. License server synchronization in process. Feature is inactive on specified license server. Majority rule failure prevents token from being issued. Communication with license server has timed out.

VLS_NON_REDUNDANT_ SRVR VLS_SERVER_SYNC_IN_ PROGRESS VLS_FEATURE_INACTIVE VLS_MAJORITY_RULE_ FAILURE VLS_NO_SERVER_RESPONSE

1.1. VLSlicense

Error Code VLS_BAD_SERVER_ MESSAGE VLS_NO_SERVER_RUNNING VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE LS_NORESOURCES LS_NO_NETWORK

Description Message returned by license server could not be understood. License server on specified host is not available for processing license operation requests. Invalid hostName was specified. The license server has not been set and the client application is unable to determine which license server to use. An error occurred in attempting to allocate memory needed by this function. Failed to initialize Winsock wrapper. (Only applicable if using network-only library.) Generic error indicating network failure. An internal error has occurred in processing.

VLS_INTERNAL_ERROR

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

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 *lshandle );

Argument
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 VLS_ALL_UNITS_RELEASED VLS_RETURN_FAILED VLS_NO_SERVER_RUNNING VLS_HOST_UNKNOWN VLS_NO_SERVER_RESPONSE VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_INTERNAL_ERROR Description lshandle is an ambiguous handle; it is not exclusively active or exclusively queued. All units have already been released. Generic error indicating that the license could not be returned. License server on specified host is not available for processing license operation requests. Invalid hostName is specified. Communication with license server timed out. Message returned by server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. 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
VLSinitialize LSRequest LSUpdate LSRelease VLScleanup

Description
Initializes the licensing library. Requests an authorization license code from the license server. Renews the license by sending an update to the license server. Releases the licenses associated with a handle. Cleans up the licensing library.

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 unsigned char unsigned char unsigned char unsigned long unsigned char LS_CHALLENGE LSHANDLE *licenseSystem, *publisherName, *featureName, *version, *unitsReqd, *logComment, *challenge, *lshandle );

Argument
licenseSystem

Description Unused. Use LS_ANY as the value of this variable. LS_ANY is specified to indicate a match against installed license systems. A string giving 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 the licensing code is requested. May consist of any printable characters and cannot be NULL. 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. 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. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired. Maximum of 100 characters. 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. 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.

publisherName

featureName

version

unitsReqd (IN/OUT)

logComment

challenge

lshandle (OUT)

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 passed 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 VLS_NO_SUCH_ FEATURE LS_INSUFFICIENTUNITS unitsReqd is zero. License server does not have license that matches requested feature and version.
n

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.

LS_LICENSE_EXPIRED

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

11

Error Code VLS_TRIAL_LIC_ EXHAUSTED VLS_APP_NODE_ LOCKED VLS_USER_EXCLUDED VLS_VENDORIDMISMATCH

Description Trial license expired or trial license usage exhausted. Requested feature is node locked, but request was issued from unauthorized machine. User or machine excluded from accessing requested feature. 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. License server synchronization in process. Feature is inactive on specified license server. Majority rule failure prevents token from being issued. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. The license server has not been set and the client application is unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. An internal error has occurred in the processing.

VLS_SERVER_SYNC_IN_PROGRESS VLS_FEATURE_ INACTIVE VLS_MAJORITY_RULE_FAILURE VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_INTERNAL_ERROR

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 VLSsetTimeoutInterval VLSqueuedRequest and VLSqueuedRequestExt

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 unsigned long long unsigned char LS_CHALLENGE lshandle, ulGraceSwitchToNetworkTm, *unused2, *unused3, *challenge );

Argument
lshandle

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

ulGraceSwitchToNetworkTm

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

13

Argument
unused2 unused3 challenge

Description Unused. Use NULL as the value. Use NULL as the value. 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. Generic error indicating that license was not updated. Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed. License server does not have license that matches requested feature, version and capacity. All licenses in use. License has expired. Trial license expired or trial license usage exhausted. Client-locked; locking criteria does not match. Feature is node locked, but the update request was issued from an unauthorized machine. License server has determined that the clients system clock 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 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. The domain of the license server is different from that of client. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified.

VLS_NO_LICENSE_GIVEN LS_LICENSETERMINATED VLS_NO_SUCH_FEATURE LS_NOLICENSESAVAILABLE LS_LICENSE_EXPIRED VLS_TRIAL_LIC_ EXHAUSTED VLS_FINGERPRINT_ MISMATCH VLS_APP_NODE_LOCKED VLS_CLK_TAMP_FOUND

VLS_VENDORIDMISMATCH

VLS_INVALID_DOMAIN VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN

14

Chapter 1: Sentinel RMS Licensing Library API

Error Code VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_RESOURCE_LOCK_FAILURE LS_BADHANDLE

Description Message returned by license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. Failed to fetch the API resource lock. On receiving this error, retry calling this API. 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 VLSsetTimeoutInterval VLSdisableLocalRenewal VLSenableLocalRenewal VLSisLocalRenewalDisabled VLSgetRenewalStatus 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 unsigned long unsigned char lshandle, units_consumed, *log_comment );

Argument lshandle units_consumed

lo g_comment

Description The handle returned by the corresponding LSRequest. The number of units required to be released. A string to be written by the license server to the comment field of the usage log file. Pass 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 VLS_RETURN_FAILED VLS_ALL_UNITS_ RELEASED VLS_NO_SERVER_ RUNNING Description lshandle is an ambiguous handle; it is not exclusively active or exclusively queued. Generic error indicating that the license could not be returned. The function released all the issued units when the client requested to release only few. License server on specified host is not available for processing the license operation requests. Invalid hostName was specified. Generic error indicating that the network is unavailable for servicing the license operation.

VLS_NO_SERVER_ RESPONSE Communication with license server has timed out. VLS_HOST_ UNKNOWN LS_NO_NETWORK VLS_BAD_SERVER_ MESSAGE Message from license server could not be understood.

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

17

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

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
VLSrequestExt VLSrequestExt2 VLSreleaseExt

Description
Requests an authorization with support for license server hooking. Supports capacity and non-capacity requests. Releases an authorization with support for license server hooking.

VLSbatchUpdate Updates several license codes at once.

1.8. VLSrequestExt

19

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 unsigned char unsigned char unsigned char unsigned long unsigned char LS_CHALLENGE LS_HANDLE VLSserverInfo *licenseSystem, *publisherName, *featureName, *version, *unitsReqd, *logComment, *challenge, *lshandle, *serverInfo );

Argument
licenseSystem publisherName featureName

Description Unused. Use LS_ANY as the value of this variable. Unused. Any value specified is ignored. 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 of the feature for which the licensing code is requested. May consist of any printable characters. Limited to 11 characters. 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. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired. 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. 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

version unitsReqd (IN/OUT)

logComment

challenge

lshandle

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. This information is passed to the license server for use in server hook functions.

serverInfo

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

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_LICENSE GIVEN VLS_NO_SUCH_FEATURE LS_NOLICENSESAVAILABLE LS_INSUFFICIENTUNITS LS_LICENSE_EXPIRED VLS_TRIAL_LIC_EXHAUSTED VLS_USER_EXCLUDED VLS_CLK_TAMP_FOUND

n n

License server does not have license that matches requested feature, version and capacity. All licenses in use. License server does not currently have sufficient licensing units for requested feature to grant license. License has expired. Trial license expired or trial license usage exhausted. User or machine excluded from accessing requested feature. License server has determined that the clients system clock 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 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

VLS_VENDORIDMISMATCH

1.8. VLSrequestExt

21

Error Code

Description returned is VLS_NO_SUCH_FEATURE.

VLS_SERVER_SYNC_IN_ PROGRESS VLS_FEATURE_INACTIVE VLS_MAJORITY_RULE_ FAILURE VLS_NO_SERVER_RUNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_INTERNAL_ERROR

License server synchronization in process. Feature is inactive on specified license server. Majority rule failure prevents token from being issued. License server on specified host is not available for processing license operation requests Communication with license server has timed out. Invalid hostName was specified. No license server has been set or the client application is unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. 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.

22

Chapter 1: Sentinel RMS Licensing Library API

1.9. VLSrequestExt2
See VLSrequestExt.

1.10. VLSreleaseExt

23

1.10. VLSreleaseExt
Client

Server

Static Library

DLL

Use VLSreleaseExt when using license server hooks.

LS_STATUS_CODE VLSreleaseExt (
LS_HANDLE unsigned long unsigned char VLSserverInfo lshandle, units_consumed, *logComment, *serverInfo );

Argument
lshandle units_consumed logComment

Description The handle returned by the corresponding LSRequest. An IN parameter. The number of units to be released. An IN parameter. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired. Maximum of 100 characters. An IN parameter. This information is passed to the license server for use in server hook functions. An IN\OUT parameter.

serverInfo

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. Generic message indicating that the license could not be returned. The function released all the issued units when the client requested to release only few. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed

VLS_RETURN_FAILED VLS_ALL_UNITS_RELEASED VLS_NO_SERVER_RUNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES

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 unsigned long long unsigned char LS_CHALLENGE LS_STATUS_CODE numHandles, *lshandle, *unused1, *unused2, *unused3, *unused4, *status );

Argument numHandles lshandle (in) unused1 unused2 unused3 unused4 status (out)

Description Specifies the number of handles. Array of numHandles handles, allocated by caller. Currently ignoredpass in a NULL. Currently ignoredpass in a NULL. Use NULL as the value. Use NULL as the value. 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 VLSsetContactServer calls. This function contacts 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 passed. 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 VLS_CALLING_ERROR VLS_CALLING_ERROR VLS_NO_LICENSE_GIVEN VLS_NO_SUCH_FEATURE LS_LICENSETERMINATED LS_NOLICENSESAVAILABLE LS_LICENSE_EXPIRED VLS_USER_EXCLUDED VLS_APP_NODE_LOCKED VLS_CLK_TAMP_FOUND Description Invalid handle challenge argument is non-NULL, but cannot be understood. License server used for update is not the same one that was used for acquiring the license. Generic error indicating that the license was not updated. License server does not have license that matches requested feature, version and capacity. Cannot update license because license already expired. All licenses in use. License has expired. User or machine are excluded from accessing requested feature. Requested feature is node locked but update request was issued from unauthorized machine. License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied. The vendor identification of the requesting application does not match the vendor identification of the feature for which the license server has a license. License server on specified host is not available for processing license operation requests. Invalid hostName was specified. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in the use of an internal buffer.

VLS_VENDORMISMATCH

VLS_NO_SERVER_RUNNING

VLS_NO_SERVER_RESPONSE Communication with license server has timed out. VLS_HOST_UNKNOWN LS_NO_NETWORK LS_BUFFER_TOO_SMALL VLS_BAD_SERVER_MESSAGE Message from license server could not be understood.

1.11.4. See Also

n

VLSbatchUpdate LSUpdate Challenge Response Mechanism VLSsetTimeoutInterval

1.11. VLSbatchUpdate

27

VLSdisableLocalRenewal VLSenableLocalRenewal VLSisLocalRenewalDisabled VLSsetRemoteRenewalTime

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; ulReserved; ulChallengedSecret; ulChallengeSize; ChallengeData[30]; LS_CHALLENGE; ulResponseSize; ResponseData[16];

Member ulReserved ulChallengedSecret

Description LSAPI requires this to be set to 0. 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. Number of characters in ChallengeData . This value cannot be 0. 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. Number of characters in the response to the challenge. The string of characters representing the actual response.

ulChallengeSize ChallengeData

ulResponseSize ResponseData

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 pass 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
VLSsetContactServer VLSgetContactServer VLSsetServerPort VLSgetServerPort VLSinitMachineID VLSgetMachineID VLSgetMachineIDOld

Description
Sets the license server to be contacted. Retrieves the license servers host name/IP address. Sets the license servers communication port. Obtains the license servers communication port. Sets the fields in machineID to default values. Sets machineID values for the current host. 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. Obtains the CID, Ethernet, and custom extended fingerprint at the specified index location for the current host.

VLSgetNumberedMachineID

VLSgetNumberedMachineIDExt Obtains the CID, Ethernet, and custom extended fingerprint at the specified index location for a specific license server. VLSsetHostIdFunc VLSsetCustomExFunc VLSmachineIDtoLockCode VLSmachineIDtoLockCodeEx VLSinitServerList VLSgetServerList VLSgetServerList VLSinitServerInfo VLSsetBroadcastInterval VLSgetBroadcastInterval VLSsetTimeoutInterval VLSgetTimeoutInterval Register the custom fingerprint mechanism with the client library. Registers the extended custom fingerprint mechanism with the client library. Computes the previous version locking codes. Computes the new version locking codes. Initializes a list of default license servers to search for a license in case of broadcast. Retrieves the default license server list. Retrieves the default license server list. Initializes the license serverInfo data structure to default values. Configures broadcast behavior. Retrieves broadcast behavior parameters. Configures timeout behavior. Retrieves timeout behavior parameters.

VLSgetServerNameFromHandle Retrieves the license servers name based on handle_id.

The Client Configuration Functions

31

Function
VLSsetHoldTime VLSsetSharedIdValue/ VLSsetTeamIdValue VLSsetGraceRequestFlag

Description
Sets license hold time. Registers a customized shared ID value. Sets the behavior if a grace license can be requested or not when the contact server has been set to stand-alone mode (no-net). Obtains the status if the grace license request is enabled or not when the contact server has been set to stand-alone mode (no-net). Calculates the license hash for a given license string. Reports whether the license server is running on a virtual machine or not.

VLSsetSharedId/ VLSsetTeamId Redefines shared ID functions.

VLSgetGraceRequestFlag

VLScalculateLicenseHash VLSisVirtualMachine

32

Chapter 1: Sentinel RMS Licensing Library API

1.13. VLSsetContactServer
Client

Server

Static Library

DLL

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

1.13.1. Syntax
LS_STATUS_CODE VLSsetContactServer (
char *serverName );

Argument
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
VLSsetContactServer 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

Using the VLSsetContactServer 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

The VLSsetContactServer 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 remember the name of the license server host which was contacted 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 VLSsetContactServer calls. The license server name set by VLSsetContactServer will be contacted 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. VLSsetContactServer

33

Linked with

Server Name Valid host name or Null

Meaning Client should communicate with the license server on serverName. If no server name is set, the application will determine serverName using default mechanism (broadcast within the subnet). The VLS_NOT_SUPPORTED_IN_NET_ONLY_MODE error will appear.
NO-NET, NO_NET, no_net, and no-net are synonymous.

Network library

NO-NET

Valid host name or Null

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

Stand-alone library

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. Valid host name
Integrated library

Client should communicate with the license server on serverName. If no server name is set, the application will determine serverName using default mechanism (stand-alone followed by broadcast within the subnet). Communicate with the application (which has the integrated stand-alone license server).

or Null

NO-NET

1.13.4. 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 standalone library. Provided an IPX address as the serverName. An error occurred in attempting to allocate memory needed by function.

VLS_NO_RESOURCES

34

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_RESOURCE_LOCK_FAILURE VLS_NOT_SUPPORTED_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_SUPPORTED_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. VLSgetContactServer

35

1.14. VLSgetContactServer
Client

Server

Static Library

DLL

Retrieves the license server name.

1.14.1. Syntax
LS_STATUS_CODE VLSgetContactServer(
char int *outBuf, outBufSz );

Argument
outBuf (out) outBufSz

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

1.14.2. Description
Returns the name of the license server host that will be contacted, 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 VLS_NO_SERVER_FILE LS_BUFFER_TOO_SMALL Description outBuf is NULL. The license server has not been set and the client application is unable to determine which license server to use. outBuf is not large enough to store license servers name.

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

1.14.4. See Also:

n

VLSsetContactServer

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 contact 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 servers 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
machineID

Description User allocated structure where the machine ID will be maintained.

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 char char char unsigned long unsigned long char VLScustomEx char char char unsigned long } VLSmachineID; id_prom; ip_addr[VLS_MAXLEN]; disk_id; host_name[VLS_MAXLEN]; ethernet[VLS_MAXLEN]; portserv_addr[VLS_MAXLEN]; custom; reserved; cpu_id; customEx; hard_disk_serial[VLS_MAXLEN]; cpu_info[VLS_MAX_CPU_INFO_LEN + 1]; uuid[VLS_MAX_UUID_LEN + 1]; unused2;

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 #define VLS_LOCK_IP_ADDR #define VLS_LOCK_DISK_ID #define VLS_LOCK_HOSTNAME #define VLS_LOCK_ETHERNET #define VLS_LOCK_NW_SERIAL #define VLS_LOCK_PORTABLE_SERV #define VLS_LOCK_CUSTOM #define VLS_LOCK_PROCESSOR_ID #define VLS_LOCK_CUSTOM_EX #define VLS_LOCK_HARD_DISK_SERIAL 0x1 0x2 0x4 0x8 0x10 0x40 0x80 0x100 0x200 0x400 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 } VLScustomEx; customEx[VLS_CUSTOMEX_SIZE]; len;

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 VLS_RESOURCE_LOCK_FAILURE Description machineID is NULL. 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 machineID lock_selector_out

Description User provided mask specifying locking criteria to be read. The new stylemachine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses. 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 lock_selector_in, *machineID, *lock_selector_out );

Argument
lock_selector_in machineID lock_selector_out

Description User provided mask specifying locking criteria to be read. The old stylemachine ID returned for the applicable lock selectors. The old style machine ID is for licenses earlier than version 11. 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 machineID lock_selector_out flag

Description User provided mask specifying locking criteria to be read. The new stylemachine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses. Mask returned specifying which locking criteria were read.
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.

index

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.20.2. Description
This function:
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 Cascaded multiple CID keys

1.20. VLSgetNumberedMachineID

43

Multiple custom locking devices Multiple disk IDs

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 pass 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 passing 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

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.

VLS_ERROR_FINGERPRINT_ VALUE_NOT_FOUND

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 VLS_LIBRARY_NOT_INITIALIZED VLS_NO_SERVER_FILE VLS_NOT_SUPPORTED The API function fails to obtain the fingerprint information for all the input lock selectors. The licensing library is not in initialized state. Call VLSinitialize. The license server has not been set and the client application is unable to determine which license server to use. 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 contacted for setting the machineID struct. If not set, the current host (set in the VLSsetContactServer API or the LSFORCEHOST environment variable) is assumed. If nothing is set in the VLSsetContactServer API or the LSFORCEHOST environment variable, error 4 (VLS_NO_SERVER_FILE) is returned. User provided mask specifying locking criteria to be read. The new stylemachine ID returned for the applicable lock selectors. The new style machine ID is for version 11 and later licenses. Mask returned specifying which locking criteria were read.
n n n n

lock_selector_in machineID lock_selector_out flag

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.

index

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

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.

VLS_ERROR_FINGERPRINT_ VALUE_NOT_FOUND

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 VLS_LIBRARY_NOT_INITIALIZED VLS_NO_SERVER_FILE VLS_NOT_SUPPORTED The API function fails to obtain the fingerprint information for all the input lock selectors. The licensing library is not in initialized state. Call VLSinitialize. The license server has not been set and the client application is unable to determine which license server to use. 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 unsigned long unsigned long *machineID, lock_selector, *lockCode );

Argument
machineID lock_selector lockCode

Description Machine ID used to generate lock code. Bit mask defining the different lock criteria to retrieve 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 pass 0x2 into the lock_selector parameter. If you pass 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 int int *machineID, lock_selector, *lockCode, lockCodeLen, unused );

Argument
machineID lock_selector lockCode

Description The machine ID used to generate lock code. The bit mask defining the different lock criteria to retrieve. 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. The size of the buffer pointed by the lockCode argument. The size should be greater than or equal to VLS_LOCK_CODE_SIZE. Not used.

lockCodeLen unused

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 VLS_CALLING_ERROR The specified lock selector is invalid. Argument specified is not correct, that is, MachineID or lockCode is NULL. If the lockCodeLen is less than VLS_LOCK_CODE_SIZE. Failed to fetch the API resource lock. On receiving this error, please retry calling this API.

VLS_RESOURCE_LOCK_FAILURE

1.23. VLSmachineIDToLockCodeEx

49

Error Code

VLS_LOCK_CODE_NOT_SUPPORT LS_NO_RESOURCES

Description The specified lock code is currently not supported. Error occurred in allocating resources needed by this API.

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 outBuf (OUT) outBufSz

Description The handle returned by LSRequest or VLSrequestExt User allocated buffer to receive license server name 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 contacted 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 LS_BADHANDLE LS_BUFFER_TOO_SMALL

Description outBuf is NULL. Invalid handle. outBuf is smaller than license servers 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 *serverList, optionFlag );

Argument
serverList optionFlag

Description Caller allocated array of license server names or the IP addresses. 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 VLSsetContactServer function is called, the VLSinitServerList settings will be overridden. Using this API is equivalent to setting the LSHOST environment variable. If the contact server is not set (using the VLSsetContactServer 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 *outBuf, outBufSz );

Argument
outBuf (OUT) outBufSz

Description User allocated buffer to receive license server name 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 LS_BUFFER_TOO_SMALL VLS_NO_SERVER_FILE

Description outBuf is NULL. outBuf is smaller than license servers name that will be returned. 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

53

1.27. VLSinitServerInfo
Client Server Static Library DLL

1.27.1. Syntax
LS_STATUS_CODE VLSinitServerInfo ( VLSserverInfo *serverInfo );

Argument
serverInfo

Description User 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.

54

Chapter 1: Sentinel RMS Licensing Library API

1.28. VLSsetHostIdFunc
Client Sets the host ID function. Server Static Library DLL

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

Registers 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* (*pmyGetCustExTableFunc) pCustomExTable, pulCount) );

Argument
pCustomExTable

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:
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).
pulCount

An IN/OUT parameter.
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 VLS_RESOURCE_LOCK_FAILURE Description An error occurred while allocating memory to the function. 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 interval );

Argument
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 interval );

Argument
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 char int *featureName, *version, timeInSecs );

Argument
featureName version timeInSecs

Description Name of the feature. Version of the feature. 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 VLS_CALLING_ERROR

An error occurred in attempting to allocate memory needed by function. 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. 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 VLS_RESOURCE_LOCK_FAILURE VLS_NOT_SUPPORTED_IN_NET_ONLY_ MODE

Description If the input parameter is other than VLS_ON or VLS_OFF. Failed to fetch the API resource lock. On receiving this error, retry calling this API. 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 teamId, (*mySharedIdFunc) (char * value) );

Argument
sharedId/ teamId

Description Must be one of the following values:

n n n n

VLS_CLIENT_HOST_NAME_ID VLS_USER_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

mySharedIdFunc

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 register a customized sharedID/teamID function with the licensing library. The value of the sharedID must be passed 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 user 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

User-name based sharing Hostname based sharing X-display based sharing 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 user 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 User/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 user. Internally, VLSrequestExt function, while sending a License Issue Request Message to the license server, passes on the information regarding its user-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 user/host/x-display. By default, Sentinel RMS Development Kit has default functions to get these values (i.e. user 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 passed 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 teamId, *teamIdValue );

Argument
sharedId/ teamId

Description Must be one of the following values:

n n n n

VLS_CLIENT_HOST_NAME_ID VLS_USER_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

sharedIdValue

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 register 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 passed 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 passed 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

67

1.38. VLSsetGraceRequestFlag
Client

Server

Static Library

DLL

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

1.38.1. Syntax
LS_STATUS_CODE VLSsetGraceRequestFlag ( int state );

Argument Direction Data Type

state

Description The flag can have any of the following value:

n

IN

int

VLS_ON: This enforces the behavior that existed before this API is introduced in the v8.4.0. Which means that the when the contact 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 contact 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.

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 contact 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 contact 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 pcLicenseString pucLicenseHash

Direction Data Type

IN OUT char

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

unsigned char A pointer to the location where the license hash is to be stored. If the value passed is NULL, the required length for this buffer is returned to the third argument piLicenseHashLength. int The length of the hash buffer. User needs to allocate memory.

piLicenseHashLength IN/OUT

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

Tip
M ake sure you pass 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 VLS_CALLING_ERROR LS_BUFFER_TOO_SMALL Description When pcLicenseString and/or piLicenseHashLength are passed NULL. When piLicenseHashLength is less than VLS_MAX_LICENSE_ HASH_LEN.

1.40. VLScalculateLicenseHash

71

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

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
vm_info

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

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 } VLSVMInfo; structSz; isVirtualMachine;

Virtualization detection is not supported in RMS SDK for MAC (as OS X cannot be virtualized). The API throws error VLS_NOT_SUPPORTED 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
VLS_LIBRARY_NOT_INITIALIZED VLS_RESOURCE_LOCK_FAILURE VLS_CALLING_ERROR VLS_NO_SERVER_FILE

Description
The licensing library is not initialized. To initialize, call VLSinitialize. Failed to fetch the API resource lock. On receiving this error, retry calling this API. The input parameter is NULL. The license server has not been set and the client application is unable to determine which license server to use.

1.41. VLSisVirtualMachine

73

Error Code
VLS_NOT_SUPPORTED

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

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
VLSdisableLocalRenewal VLSenableLocalRenewal VLSgetRenewalStatus VLSdisableAutoTimer

Description
Disables local license renewal. Resets local license renewal. Returns renewal status. Disables automatic renewal of one feature.

VLSisLocalRenewalDisabled Informs you whether or not local updates are enabled. VLSsetRemoteRenewalTime Sets the remote renewal period.

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 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 contacted 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 VLSdisableLocalRenewal

1.44. VLSisLocalRenewalDisabled

77

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.

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 contacting the license server, this function returns VLS_REMOTE_UPDATE. If the last operation that successfully renewed a license did not involve contacting 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 LS_LICENSETERMINATED VLS_NO_SUCH_FEATURE LS_NOLICENSESAVAILABLE LS_LICENSE_EXPIRED VLS_TRIAL_LIC_EXHAUSTED VLS_FINGERPRINT_MISMATCH VLS_APP_NODE_LOCKED VLS_CLK_TAMP_FOUND Description Generic error indicating that license was not updated. Cannot update the license because the license has already expired. License server does not have license that matches requested feature, version and capacity. All licenses in use. License has expired. Trial license expired or trial license usage exhausted. Client-locked; locking criteria does not match. Feature is node locked, but the update request was issued from an unauthorized machine. License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

1.45. VLSgetRenewalStatus

79

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. The domain of the license server is different from that of client. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. Message returned by license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. No updates have been made. Specifies the initial value. During the most recent update, the license was valid and did not need to be renewed. During the most recent update, the license was invalid and required update from the license server.

VLS_INVALID_DOMAIN VLS_NO_SERVER_RUNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_NO_UPDATES_SO_FAR VLS_LOCAL_UPDATE VLS_REMOTE_UPDATE

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 char int *featureName, *version, timeInSecs );

Argument
featureName version timeInSecs

Description Name of the feature. Version of the feature. 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 VLS_CALLING ERROR An error occurred in attempting to allocate memory needed by function. 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 lshandle, state );

Argument
lshandle state

Description The handle returned by LSRequest or VLSrequestExt 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 LS_BADHANDLE Description Invalid state. Needs to be either VLS_ON or VLS_OFF 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
VLSgetLicenseInfo VLSgetLicenseInfoExt VLSgetClientInfo VLSgetHandleInfo VLSgetActiveHandleList

Description
Retrieves information about non-capacity licenses available in the license server. Retrieves information for both capacity and non-capacity licenses available in license server. Returns information about a client using a non-capacity license loaded in the license server. Returns information about a client given a handle. 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)

83

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;

84

Chapter 1: Sentinel RMS Licensing Library API

long overdraft_users; 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 Size of VLSlicenseInfo structure. long feature name is supported.

structSz

feature_name The name of the feature whose information is retrieved. Currently, a 24 characters version lic_type trial_days_ count birth_day death_day num_licenses is_node_ locked

Feature version. Maximum 11 characters. The type of license, either trial or normal. The number of trial days. The day of the license start date. The time when the feature expires. The constant, VLS_NO_EXPIRATION, is returned if the license does not have any expiration date. The total number of licenses the license server is authorized to issue. 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 sharing_crit

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

VLS_NO_SHARING VLS_USER_NAME_ID VLS_CLIENT_HOST_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

1.48. VLSlicenseInfo (license_info_struct)

85

Member

Description 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

locking_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_CPU VLS_LOCK_HARD_DISK_SERIAL VLS_LOCK_CPU_INFO VLS_LOCK_UUID

holding_crit

The license holding criteria, which can be one of the following constants:
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 site_license_ info hold_time vendor_info cl_lock_info

The number of subnet specifications provided for the site. A space-separated list of subnet wildcard specifications. The holdtime specified for licenses issued for this feature. The vendor-defined information string. The maximum length of the string can be 2000 characters. 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#). The license lifetime for this feature (in seconds). The limit on how many copies can share the same license. The soft limit (for alerts) on the number of concurrent users of this feature. The license type as any of the following:
n n n

key_life_time sharing_limit soft_num_ licenses is_standalone

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 is_additive

Returns VLS_TRUE if this feature is time tamper proof or VLS_FALSE if not time tamper proof. 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 majority_rule num_servers isCommuter log_encrypt_ level conversion_ time server_locking_info capacity_flag

Validates if the license is actually redundant. Checks whether majority rule is on or off. The number of redundant license servers. Checks whether commuter licenses are allowed or not. The encryption level in the network license for the license server's usage log file.

elan_key_flag Unused.

Unused. Stores the server locking information. 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 commuter_ max_checkout_days

The total capacity of the license. 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 supported. overdraft_ hours overdraft_ users Overdraft_ users_in_use

Not supported. Not supported. The number of overdraft users 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)

87

Member

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 license_storage license_state license_precedence

The license hash identifier for a license code. The file location where the license is stored. Indicates whether this license is a part of the license table node or not. 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 version feature_index license_hash license_hash_len license_index license_info

Description The feature name identifier for the license code. The version identifier for the license code. Used to specify a particular feature-version combination. The license hash identifier for a specific license code. The license hash length. Used to specify index of a particular license for a specific feature-version combination. 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
VLS_NO_MORE_FEATURES VLS_NO_MORE_LICENSES

Description
Finished retrieving all the features added. 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

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.

VLS_CALLING_ERROR

Argument specified is not correct, that is, one of the following reasons exist:
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 VLS_MULTIPLE_VENDORID_FOUND

License with passed feature-version combination not 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. Failed to fetch the API resource lock. On receiving this error, retry calling this API. Error occurred in allocating resources needed by this API. License with passed feature-version-license hash combination not found. Generic error indicating that the network is unavailable for servicing the license operation. License server on specified host is not available for processing license operation requests. Message from license server could not be understood. The function is called for a capacity license. It can only be called for non-capacity licenses. For capacity licenses, call VLSgetLicenseInfoExt.

VLS_RESOURCE_LOCK_FAILURE VLS_NORESOURCES VLS_NO_SUCH_LICENSE LS_NO_NETWORK VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESS AGE VLS_CAPACITY_MISMATCH

1.49. VLSgetLicenseInfo

91

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.

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 unsigned char unsigned long int unsigned char int int VLSlicenseInfo *license_info ); *feature_name, *version, *capacity feature_index, *license_hash, license_hash_len, license_index,

Argument
feature_name version capacity feature_index license_hash license_hash_len license_index license_info

Description The feature name identifier for the license code. The version identifier for the license code. The capacity value for the license code. Used to specify a particular feature-version combination. The license hash identifier for a specific license code. The license hash length. Used to specify index of a particular license for a specific feature-version combination. 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 passed as NULL and the feature_name and version parameters are passed 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 passed as NULL, and the feature_index parameter should be used in a loop in combination with license_index.

1.50. VLSgetLicenseInfoExt

93

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

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.

VLS_CALLING_ERROR

Argument specified is not correct, that is, one of the following reasons exist:
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 VLS_MULTIPLE_VENDORID_FOUND

License with passed feature-version combination not 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. Failed to fetch the API resource lock. On receiving this error, retry calling this API. Error occurred in allocating resources needed by this API. License with passed feature-version-license hash combination not found. Generic error indicating that the network is unavailable for servicing the license operation.

VLS_RESOURCE_LOCK_FAILURE VLS_NORESOURCES VLS_NO_SUCH_LICENSE LS_NO_NETWORK

94

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESSAGE VLS_NOT_SUPPORTED_IN_NONET_ MODE VLS_NO_SERVER_FILE

Description License server on specified host is not available for processing license operation requests. Message from license server could not be understood. When the function is called for retrieving information about the capacity licenses with the stand-alone library. 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 char unsigned long char long long long long char char char int int int int int long unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long int int int } VLSclientInfo; client_info_struct { user_name[VLS_MAXLEN]; host_id; group[VLS_MAXLEN]; start_time; hold_time; end_time; key_id; host_name[VLS_MAXLEN]; x_display_name[VLS_MAXLEN]; shared_id_name[VLS_MAXLEN]; num_units; q_wait_time; is_holding; is_sharing; is_commuted; structSz; team_capacity; total_resv_team_capacity; reserved_team_capacity_in_use; unreserved_team_capacity_in_use; user_capacity_from_reserved; user_capacity_from_unreserved; total_team_tokens_resv; reserved_team_tokens_in_use; unreserved_team_tokens_in_use;

Member user_name

Description The login name of the user 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. The host ID of the computer on which the user is working. This can be changed using the VLSsetHostIdFunc call. Name of the reserved group to which the user belongs, where MAX-

host_id group

96

Chapter 1: Sentinel RMS Licensing Library API

Member

Description LEN is set to 64 characters. If the user does not belong to an explicitly named group, DefaultGrp is returned. The time at which the current license code was issued by the license server. Specifies the hold time, in seconds, if any. The time at which the users current license will expire if not renewed. The internal ID of the license currently issued to the users application. After starting up, the license server issues licenses with unique IDs until it is restarted. Name of the host/computer where the user 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. Name of the X display where the user 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. 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 registering a custom function using the VLSsetSharedId API call. If you plan to use this ID, you should register 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. Number of units consumed by the client so far. Unused. Has the value, VLS_TRUE, if the users current license is being held after its expiration. Otherwise, the value is VLS_FALSE. Total number of clients sharing this particular license, including the current client being queried. If sharing is disabled, is_sharing will be 0. Total number of clients that have checked out a license from the network. Size of VLSclientInfo structure. Total capacity of the team.

start_time hold_time end_time key_id

host_name

x_display_ name

shared_id_ name

num_units q_wait_time is_holding is_sharing

is_commuted structSz team_capacity

total_resv_team_capacity Total capacity reserved for the team.

1.51. client_info_struct

97

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 users from reserved capacity. user_capacity_from_ reserved user_capacity_from_unre- Capacity given to users from unreserved capacity. served total_team_tokens_resv Total reserved units. reserved_team_tokens_ in_ use unreserved_team_ tokens_in_use Units given to teams from reserved pool. Units given to teams from unreserved pool.

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 char int char VLSclientInfo *featureName, *version, index, *unused1, *clientInfo );

Argument
featureName version index unused1 clientInfo (out)

Description Name of the feature. An IN parameter. Version of the feature. An IN parameter. Used to specify a particular client. An IN parameter. Use NULL as the value. 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 Description n featureName is NULL n version is NULL n Both feature name and version cannot be NULL at the same time.
n

VLS_CALLING_ERROR

clientInfo parameter is NULL

1.52. VLSgetClientInfo

99

Error Code

Description n index is negative. n Attempted to use stand-alone mode with networkonly library, or network mode with stand-alone library. Finished retrieving client information for all clients. License server does not have a license that matches requested feature and version. The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. The license server has not been set and the client application is unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function.

VLS_NO_MORE_CLIENTS VLS_NO_SUCH_FEATURE VLS_MULTIPLE_VENDORID_ FOUND

VLS_NO_SERVER_UNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

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

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 lshandle, *clientInfo );

Argument
lshandle clientInfo (out)

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 *out_handle_buf, * num_handle );

Argument
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 passed 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 VLS_CALLING_ERROR LS_BUFFER_TOO_SMALL VLS_RESOURCE_LOCK_FAILURE VLS_NORESOURCES Description This indicates that no active client handles exist. The argument specified is not correct, that is, num_handle is NULL. This error code indicates that the allocated buffer is insufficient to store the list of active client handles. Failed to fetch the API resource lock. On receiving this error, retry calling this API. 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 status

Description The client handle identifier. 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 LS_NO_RESOURCES Description If the error_status parameter is specified as NULL. 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 passed 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. in_use_ p parameter is NULL.

LS_BUFFER_TOO_SMALL

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
VLSgetFeatureInfo VLSgetVersions VLSgetFeatureFromHandle VLSgetVersionFromHandle VLSgetTimeDriftFromHandle

Description
Retrieves feature licensing information when a non-capacity licensed is currently serving the license requests. Retrieves licensed version information for a feature. Returns the feature name corresponding to the handle. Returns the version corresponding to the handle. 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)

107

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_users; long overdraft_users_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 version lic_type trial_days_ count birth_day death_day

Description Size of VLSfeatureInfo structure. Feature version . Maximum 11 characters. Type of license either trial or normal. Number of trial days. Day of the license start date. The constant VLS_NO_EXPIRATION is returned for licenses with no limit set on birth date. The time when the feature expires. The constant VLS_NO_EXPIRATION is returned if the license does not have any expiration date.

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

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.

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 sharing_crit

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

VLS_NO_SHARING VLS_USER_NAME_ID VLS_CLIENT_HOST_NAME_ID VLS_X_DISPLAY_NAME_ID VLS_VENDOR_SHARED_ID

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

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_CPU VLS_LOCK_HARD_DISK_SERIAL VLS_LOCK_CPU_INFO VLS_LOCK_UUID

holding_crit

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

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

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 cl_lock_info The vendor-defined information string. The maximum length of vendor_info string can be up to 2000 characters. Locking information about clients in a space-separated string of host IDs and/or IP addresses.

1.57. feature_info_struct (VLSfeatureInfo)

109

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 users 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 is_additive

Returns VLS_TRUE if this feature is time tamper proof or VLS_FALSE if not time tamper proof. 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

VLS_ADDITIVE - for an additive license 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 Number of redundant license servers. isCommuter log_encrypt_ level avg_queue_ time Commuter licenses. Encryption level in the network license for the license servers usage log file. 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 commuter_ keys_left server_locking_info capacity_flag Number of commuter keys that have been checked out. Number of computer keys left. Stores the server locking information. 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

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 supported. overdraft_ hours overdraft_ users overdraft_ users_in_use Not supported. Not supported. Not supported.

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)

111

Member

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

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

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

plain_vendor_info

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 trial_calendar_ period_left The maximum limit of the executions count of a trial license.

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.

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 char int char VLSfeatureInfo *name, *version, index, *unused1, *featureInfo );

Argument
name version index unused1 featureInfo (out)

Description Name of the feature. Maximum of 64 characters, including NULL termination character. Version of the feature. Used to specify a particular client. Use NULL as the value. 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 passed 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. version is NULL when name is non_NULL. Finished retrieving feature information for all features on license server. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. No license server has been set and unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function.

VLS_APP_UNNAMED VLS_NO_MORE_FEATURES VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER-FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

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 int char char *featureName, bufferSize, *versionList, *unused1 );

Argument
featureName bufferSize versionList (out) unused1

Description Name of the feature. Specifies the size of versionList. An array containing the version list. Space should be allocated by the caller. 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 VLS_APP_UNNAMED VLS_CALLING_ERROR

Description License server does not have a license that matches the requested feature, version and capacity. featureName is NULL. 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 VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE Communication with license server has timed out. Invalid hostName was specified. The license server has not been set and the client application is unable to determine which license server to use.

1.59. VLSgetVersions

115

Error Code

Description VLS_BAD_SERVER_ MES- Message from license server could not be understood. SAGE LS_NO_NETWORK LS_BUFFER_TOO_ SMALL LS_NORESOURCES Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in the use of an internal buffer. 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.

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 LS_HANDLE char int VLSgetFeatureFromHandle ( handle, *buffer, bufferSize );

Argument
handle buffer (out) bufferSize

Description Handle returned by license request API. Buffer to hold the feature name. Space allocated by caller. 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 passed 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 handle, *buffer, bufferSize );

Argument
handle buffer (OUT) bufferSize

Description Handle returned by LSRequest or VLSrequestExt. Buffer to hold the feature version. Space allocated by caller. 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 passed 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 LS_BUFFER_TOO_SMALL

Description Invalid handle. 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 secondsUntilTheFeature Expires

Description Handle returned by LSRequest or VLSrequestExt. 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 VLS_NO_SUCH_FEATURE LS_BUFFER_TOO_SMALL VLS_NO_SERVER_RUNNING

Description Invalid handle. License server does not have a license that matches the requested feature, version and capacity. secondsUntilTheFeatureExpires is NULL. License server on specified host is not available for processing the license operation requests. Invalid hostName was specified.

VLS_NO_SERVER_RESPONSE Communication with the license server has timed out. VLS_HOST_UNKNOWN

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. Generic error indicating that the network is unavailable for licensing. An error occurred in attempting to allocate memory needed.

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

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 LS_BUFFER_TOO_SMALL

Description Invalid handle. 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
VLSdiscover

Description
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. Adds licensing information to the license servers internal tables. Adds licensing information about a feature to both the license file and license servers internal tables. Removes licensing information from the license servers internal tables. Deletes a non-capacity license from the license server's memory and file.

VLSaddFeature VLSaddFeatureToFile VLSdeleteFeature VLSdeleteLicenseFromFile

VLSdeleteLicenseFromFileExt Deletes both capacity and non-capacity licenses from the license server's memory and file. VLSgetLibInfo VLSshutDown Retrieves information about the Sentinel RMS client library. 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 unsigned char unsigned char int char int char *feature_name, *version, *reserved1, server_list_len, *server_list, optionFlag, *query_list );

Argument
feature_name version reserved1 server_list_len server_list (OUT) optionFlag query_list

Description Name of the feature. Version of the feature. Use any value. Specifies the size of server_list. Space separated list of license server names. A three bit flag which guides the behavior of VLSdiscover in finding the license servers. Details are discussed later. 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

VLS_DISC_NO_USERLIST - Does not check the host list specified by the user. By default, it first checks the LSFORCEHOST environment variable. If LSFORCEHOST doesnt exist, it reads the list specified by the user in the environment variable, LSHOST, and the file, LSHOST/lshost. (The content of these lists are joined 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 contacts 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 LS_NO_SUCCESS LS_NORESOURCES

Description No license servers have responded. Failed to retrieve computer names on local subnet. 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

125

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]; strcpy(query_list, "troilus.soft.net:123.23.234.1"); VLSdiscover("DOTS", "1.0", NULL, MAX_BUF, server_list, VLS_DISC_PRIORITIZED_LIST, query_list);

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 unsigned char LS_CHALLENGE *licenseString, *unused1, *unused2 );

Argument licenseString unused1 unused2

Description String containing licensing information. Use NULL as the value. Use NULL as the value.

1.66.2. Description
Dynamically adds the license code, licenseString , to the license servers internal tables. If licensing information for this feature and version already exists in the license servers 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 LS_NO_SUCCESS VLS_ADD_LIC_FAILED VLS_NO_SERVER_RUNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. licenseString is NULL. Generic error indicating the feature has not been added. License server on specified host is not available for processing the license operation requests. Communication with license server has timed out. Invalid hostName was specified. 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 LS_NO_NETWORK LS_NORESOURCES

Description Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in servicing the 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.

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 unsigned char unsigned char LS_CHALLENGE *licenseString, *unused1, *unused2, *unused3 );

Argument
licenseString unused1 unused2 unused3

Description String containing licensing information. Use NULL as the value. Use NULL as the value. Use NULL as the value.

1.67.2. Description
Dynamically adds licensing information about a feature to the license servers internal tables. If licensing information for this feature already exists in the license servers 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 LS_NO_SUCCESS VLS_ADD_LIC_FAILED Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. licenseString is NULL. 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 VLS_NO_SERVER_FILE Invalid hostName was specified. The license server has not been set and the client application is unable to determine which license server to use.

1.67. VLSaddFeatureToFile

129

Error Code Description VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be understood. LS_NO_NETWORK LS_NORESOURCES Generic error indicating that the network is unavailable in servicing the license operation. 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.

130

Chapter 1: Sentinel RMS Licensing Library API

1.68. VLSdeleteFeature
Client Server Static Library DLL

Deletes licensing information about a feature.

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 version unused2 unused3

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

1.69.1. Description
Deletes licensing information from the license servers 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. Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. License server does not have a license that matches requested feature, version and capacity. Generic error indicating the feature has not been deleted. 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. The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested. License server on specified host is not available for processing the license operation requests.

VLS_CALLING_ERROR VLS_NO_SUCH_FEATURE VLS_DELETE_LIC_FAILED VLS_VENDORIDMISMATCH

VLS_MULTIPLE_VENDORID_ FOUND

VLS_NO_SERVER_RUNNING

132

Chapter 1: Sentinel RMS Licensing Library API

Error Code

VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES

Description Communication with license server has timed out. Invalid hostName is specified. The license server has not been set and the client application is unable to determine which license server to use. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the 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.

1.70. VLSdeleteLicenseFromFile

133

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 unsigned char unsigned char int unsigned char int void int *feature_name, *version, *license_hash, license_hash_len, *license_string, *license_string_bufsize, *unused1, unused2 );

Argument
feature_name version license_hash license_hash_len, license_string license_string_bufsize

Description The feature name identifier of the license code. The version identifier of the license code. The license hash to identify a specific license code. The allocated size for the license hash, passed as input. An OUT parameter. The deleted license code returned by the license server. An IN/OUT parameter. Allocated size for the license code passed as input. Returns the actual size of the deleted license string.
This buffer size must be equal to macro VLS_MAX_LICENSE_SIZE.

unused1 unused2

An unused variable. 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.

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 passed 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 passed 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

If license_hash_len < 1 or license_hash_len > VLS_ MAX_LICENSE_HASH_LEN. If license_hash is passed 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 passed 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'. License with passed feature-version combination not found. License with passed feature-version-license hash combination not found. This indicates an error that the allocated buffer is insufficient to store the deleted license string. This indicates an error that the license to be deleted is currently in use. This means that the specified license has some active clients. This indicates failure in accessing the license file.

VLS_NO_SUCH_FEATURE VLS_NO_SUCH_LICENSE LS_BUFFER_TOO_SMALL VLS_LICENSE_IN_USE

VLS_STORE_ACCESS_ERROR

VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API. LS_NORESOURCES VLS_DELETE_LIC_FAILED VLS_MULTIPLE_VENDORID_ FOUND Error occurred in allocating resources needed by this API. This indicates a generic error that the license deletion process has failed. This occurs when more than one licenses for the specified Feature/Version is available on the License server, but the

1.70. VLSdeleteLicenseFromFile

135

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 VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESSAGE VLS_CAPACITY_MISMATCH Generic error indicating that the network is unavailable for servicing the license operation. License server on specified host is not available for processing license operation requests. Message from license server could not be understood. 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.

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 unsigned char unsigned long unsigned char int unsigned char int void int *feature_name, *version, *capacity, *license_hash, license_hash_len, *license_string *license_string_bufsize, *unused1, unused2 );

Argument
feature_name version capacity license_hash license_hash_len license_string license_string_bufsize unused1 unused2

Description The feature name identifier of the license string. The version identifier of the license string. The capacity identifier of the license string. The license hash to identify a specific license string. The allocated size for License hash passed as input. An OUT parameter. The deleted license string returned by the license server. An IN/OUT parameter. The allocated size for license string passed as input, will return the actual size of the deleted license string. An unused variable. 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 passed in the capacity parameter.

1.71. VLSdeleteLicenseFromFileExt

137

If the license to be deleted is a non-capacity license, then, the capacity parameter needs to be passed 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

If license_hash_len < 1. If license_hash is passed 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 passed is more than VLS_ MAX_LICENSE_HASH_LEN. If length of license_hash passed is more than VLS_ MAX_LICENSE_HASH_LEN.

VLS_APP_UNNAMED VLS_NO_SUCH_FEATURE VLS_NO_SUCH_LICENSE LS_BUFFER_TOO_SMALL VLS_LICENSE_IN_USE

When feature_name or version parameter is NULL. Or, feature_name contains only the NULL character i.e '\0'. License with passed feature-version combination not found. License with passed feature-version-license hash combination not found. This indicates an error that the allocated buffer is insufficient to store the deleted license string. This indicates an error that the license to be deleted is currently in use. This means that the specified license has some active clients. This indicates failure in accessing the license file. Failed to fetch the API resource lock. On receiving this error, retry calling this API. Error occurred in allocating resources needed by this API. This indicates a generic error that the license deletion process has failed. 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. This indicates failure that occurs in internal message construction and splitting while processing the API.

VLS_STORE_ACCESS_ERROR VLS_RESOURCE_LOCK_FAILURE LS_NORESOURCES VLS_DELETE_LIC_FAILED VLS_MULTIPLE_VENDORID_FOUND

VLS_SEVERE_INTERNAL_ERROR

138

Chapter 1: Sentinel RMS Licensing Library API

Error Code

LS_NO_NETWORK VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESSAGE VLS_CAPACITY_MISMATCH

Description Generic error indicating that the network is unavailable for servicing the license operation. License server on specified host is not available for processing license operation requests. Message from license server could not be understood. Error indicating that NULL is passed as capacity argument for deleting a capacity license or vice-a-versa. Incorrect capacity value is passed 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

139

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 typedef struct { unsigned long char char char char char } LS_LIBVERSION ulInfoCode; szVersion [LIBINFOLEN]; szProtocol [LIBINFOLEN]; szPlatform [LIBINFOLEN]; szLocale szUnused2 [LIBINFOLEN]; [VERSTRLEN]; VLSgetLibInfo(LS_LIBVERSION *pInfo)

Member
ulInfoCode szVersion szProtocol szPlatform szLocale szUnused2

Description Unused. The version of the licensing library. The communication protocol being used for application/license server communication. The platform of the client application. The locale of the client system. 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.

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

The client and license server must be running on the same network domain name. User identification of the license server process should match the client, or client must be run by superuser (root) as shown in the following table: Windows UNIX 2000/XP/2003/Vista/7/2008 (non(Admin) root) UNIX (root)

Server Operating System

UNIX (non-root)
Client

Same User- Name or UserId Yes Yes

Windows Yes 2000/XP/2003/Vista/7/2008 (Admin) 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

141

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 VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK Communication with license server has timed out.

VLS_HOST_UNKNOWN Invalid hostName is specified. Message returned by the license server could not be understood. 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.

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
VLSgetTrialUsageInfo VLSgetTrialPeriodLeft

Description
Retrieves the usage information for a trial license. Returns the remaining time left in a trial license.

VLSsetLicensePrecedence Sets the precedence value for a trial license.

1.74. VLStrialUsageInfo

143

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

1.74.1. Syntax
typedef struct long char char int int int int int int }VLStrialUsageInfo; trial_usage_info_struct { structSz; feature_name[VLS_MAXFEALEN + 1]; version[VLS_MAXFEALEN + 1]; cumulative_trial_calendar_period; cumulative_trial_elapsed_hours; cumulative_trial_execution_count; cumulative_trial_calendar_period_left; cumulative_trial_elapsed_period_left; cumulative_trial_executions_left;

Member structSz feature_name

Description Size of VLStrialUsageInfo structure. Name of the feature whose information is retrieved.Space is allocated for 64 characters, but currently maximum 24 characters long feature name is supported. Feature version. Maximum 11 characters. Total trial days of all the trial licenses added. Total trial hours of all the trial licenses added. Total trial execution count of all the trial licenses added.
11

version Cumulative_trial_calendar_period Cumulative_trial_elapsed_hours Cumulative_trial_execution_count

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 supported 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 unsigned char int VLStrialUsageInfo *trial_usage_info ); *feature_name, *version, feature_index,

Argument feature_name version feature_index trial_usage_info

Description The feature name identifier for the license code. Version of the feature. Must be unique. Used to specify a particular feature-version combination. 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

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

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.

10.

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 Additive Trial Additive Trial Additive Trial Exclusive Trial Exclusive Trial Exclusive Trial Aggregate Trial AggregateTrial AggregateTrial License 2 Additive Trial Exclusive Trial Aggregate Trial Additive Trial Aggregate Trial Exclusive Trial AggregateTrial Exclusive Trial Additive Trial Cumulative Usage License 1 + License 2 License 1 + License 2 License 1 + License 2 License 1 License 1 License 1 License 1 + License 2 License 1 + License 2 License 1 Error Return Error Return

Normal (Additive/Exclusive) Additive Trial Normal (Additive/Exclusive) Exclusive Trial

Case 2 - Precedence of License 1 is set as -1 and License 2 is set as any positive value License 1 Additive Trial Additive Trial Additive Trial Exclusive Trial Exclusive Trial Exclusive Trial Aggregate Trial Aggregate Trial Aggregate Trial Additive Trial Aggregate Trial Exclusive Trial License 2 Additive Trial Exclusive Trial Aggregate Trial Additive Trial Aggregate Trial Exclusive Trial Aggregate Trial Additive Trial Exclusive Trial Normal (Additive/Exclusive/Aggregate) Normal (Additive/Exclusive/Aggregate) Normal (Additive/Exclusive/Aggregate) Cumulative Usage License 1 + License 2 License 1 + License 2 License 1 + License 2 License 1 License 1 License 1 License 1 + License 2 License 1 License 1 + License 2 License 1 License 1 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
VLS_NO_MORE_FEATURES

Description
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
VLS_APP_UNNAMED

Description
If:
n

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.

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 VLS_MULTIPLE_VENDORID_FOUND

License with specified feature-version combination is not 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. Failed to fetch the API resource lock. On receiving this error, retry calling this API. Error occurred in allocating resources needed by this API. This indicates that the specified feature is not a trial license. For ex, if the specified feature node contains a normal license. Inactive trial license is queried. The specified feature has an exhausted trial license. Generic error indicating that the network is unavailable for servicing the license operation. License server on specified host is not available for processing license operation requests. Message from license server could not be understood.

VLS_RESOURCE_LOCK_FAILURE VLS_NORESOURCES VLS_NON_TRIAL_LICENSE

VLS_TRIAL_LIC_NOT_ACTIVATED VLS_TRIAL_LIC_EXHAUSTED LS_NO_NETWORK VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESSAGE

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 ( unsigned char unsigned char unsigned char int int void int *feature_name, *version, *license_hash, license_hash_len, precedence_level, *ununsed1, ununsed2 );

Argument
feature_name version license_hash license_hash_len precedence_level unused1 unused2

Description Name of the feature. Version of the feature. Must be unique. The license hash for the license code (to identify a specific license). The length of the license hash. Used to specify the precedence level that needs to set for the trial license. Unused variable. Unused variable.

1.76.2. Description
The API sets the precedence level of a trial license. The precedence level passed as argument can be one of the following:
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

VLS_PRECEDENCE_TRIAL_OVERRIDE_NORMAL (-1) VLS_PRECEDENCE_DISABLE (0) 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". 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. The license with feature-version combination passed as an argument not found. The license with feature-version-license hash combination passed as an argument not found. Failed to obtain the API resource lock. On receiving this error, retry calling this API. Error occurred in allocating resources needed by this API. Failed in setting the license precedence. Failed to set the precedence of a trial license due to the corrupted persistence. Recoverable error is occurred while setting the precedence of a trial license. 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. Generic error indicating that the network is unavailable for servicing the license operation. License server on specified host is not available for processing license operation requests. Message from license server could not be understood.

VLS_CALLING_ERROR

VLS_NO_SUCH_FEATURE VLS_NO_SUCH_LICENSE VLS_RESOURCE_LOCK_FAILURE VLS_NORESOURCES VLS_SET_LICENSE_PRECEDENCE_ FAILED VLS_TRIAL_LIC_DATA_INCONSISTENT VLS_TRIAL_LIC_DATA_ACCESS_ERROR VLS_MULTIPLE_VENDORID_FOUND

LS_NO_NETWORK VLS_NO_SERVER_RUNNING VLS_BAD_SERVER_MESSAGE

1.76. VLSsetLicensePrecedence

149

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.

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 version trialperiod (OUT) unused1

Description Name of the feature. Version of the feature. Must be unique. Number of seconds left in the trial license. Points to integer in the trialperiod parameter. 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 VLS_NO_SERVER_ RUNNING VLS_HOST_UNKNOWN LS_NO_NETWORK

An Irrecoverable internal error has occurred in processing. License server on specified host is not available for processing license operation request. Invalid hostname was specified. Generic error indicating that the network is unavailable for servicing the licensing operation.

1.77. VLSgetTrialPeriodLeft

151

Error Code
VLS_NO_SERVER_ RESPONSE VLS_BAD_SERVER_ MESSAGE VLS_INTERNAL_ERROR VLS_NO_TRIAL_INFO VLS_TRIAL_LIC_ EXHAUSTED VLS_TRIAL_INFO_ FAILED VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE

Description
Communication with license server has timed out. Message from license server could not be understood. An internal error has occurred in processing. No Trial usage info. Trial license expired or trial license usage exhausted. Trial usage query failed The license server has not been set and the client application is unable to determine which license server to use. 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.

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 customers 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

153

1.78. VLSservInfo Struct

typedef struct { long int int int int unsigned char unsigned char unsigned char unsigned long unsigned char long VLStimeTamperInfo VLSmachineID } VLSservInfo; structSz; major_no; minor_no; revision_no; build_no; locale[VLS_SERV_LOCALE_STR_LEN]; vendor_info[VLS_SERV_VNDINFO_STR_LEN]; platform[VLS_SERV_PLATFORM_STR_LEN]; lock_mask; unused1[VLS_SERV_UNUSED1_STR_LEN]; unused2; tmtmpr_info; machine_id;

Argument
structSz major_no minor_no revision_no build_no locale vendor_info platform lock_mask unused1 unused2 tmtmpr_info machine_id

Description Size of the structure. Must be set by the user. The major number of the server. The minor number of the server. The revision number of the server. The build number of the server. The locale for which the server was built. Vendor specified license server identification. This can be customized through VLSsetServInfo API. Default is null string The platform for which the server was built. Lock selector used in computing the machine ID of the server machine. Reserved. Uses NULL as the value. Reserved. Uses NULL as the value. Contains the time tampering related information on the server machine. 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.

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 long time_t time_t long int int int int unsigned long } VLStimeTamperInfo; timetampering_info_struct { structSz; lastTime; currTime; grace_period; percentViolationAllowed; numViolationForError; numViolationFound; percentViolationFound; clkSetBackTime;

Argument structSz lastTime currTime grace_period

Description Size of the structure. Must be set by the user. The last known good time when no clock tampering was detected. Current time on the server. 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. 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. 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. Actual number of system files found in violation of the grace period. Used on UNIX systems only. Percentage of system files found in violation of the grace period. Used on UNIX systems only. The actual amount of time by which the clock has been set back. This value is zero if no time tampering has been detected.

percentViolation Allowed

numViolationFor Error

numViolationFound percentViolation Found clkSetBackTime

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 unsigned char unsigned long *server_name, *srv_info, *unused1, *unused2 );

Argument
server_name

Description The name of the server you would like to retrieve information from. You can pass this as NULL if you want this API call to pick up the server name if previously set by VLSsetContactServer 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 VLSsetContactServer 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.

srv_info

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_SUPPORTED. 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 *pucPassword, unsigned char *pucPermissionTicket, 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 VLSsetContactServer API or the LSFORCEHOST environment variable) In case of stand-alone license revocation, a separate call VLSsetContactServer("no-net") is required.

pucPassword pucPermissionTicket ui16PermissionTicketLength pucRevocationTicket

Specify NULL. An IN parameter. A pointer to the permission ticket. An IN parameter. The length of the permission ticket. 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 passed, the buffer length is returned. 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.

pui16RevocationTicketLength

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

158

Chapter 1: Sentinel RMS Licensing Library API

The VLSrevokeByPermissionTicketAPI does the following activities before generating a license revocation ticket:
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 passed as NULL, the function does the following:
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 VLS_REHOST_PARAMETERS_ERROR VLS_REHOST_INVALID_DATA_FORMAT VLS_REHOST_UNSUPPORTED_OPERATION_TYPE

Description Allocated memory is not enough. Invalid rehost parameters. Permission ticket is invalid; either corrupt or not in TLV format. Operation type is not 'A', 'R', or 'P'.

VLS_REHOST_ALLOCATE_MEMORY_FAIL- Failure in memory allocation. URE VLS_REHOST_DIFFERENT_LOCK_INFO VLS_REHOST_LICENSE_IN_USE VLS_REHOST_HAVE_BEEN_REVOKED_ BEFORE VLS_REHOST_CANCELED_BY_USER VLS_REHOST_LICENSE_EXIST VLS_REHOST_REVOKE_OVER_TOTAL Lock code mismatch. License to be revoked is in use; can not be revoked. License has already been revoked; can not be revoked again. Revoke option was canceled by the user. The license already exists. When the revocation request exceeds the available limit.

1.81. VLSrevokeByPermissionTicket

159

Error Codes

VLS_REHOST_TAG_NOT_FOUND VLS_REHOST_INVALID_REQUEST_DATA VLS_INVALID_LICENSE

Description A tag not found in the TLV. The requested data is invalid. 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 supported GLE_PT length. Decrease the number of operations from PT. VLS_PT_ALREADY_EXECUTED_FOR_ THIS_OPERATION VLS_PT_VENDOR_ID_MISMATCH VLS_REVOKE_EXPIRED_LIC_FOUND The permission ticket operation already executed on the license server. Vendor ID mismatch. The permission ticket cannot be used for revoking licenses of other vendors. An expired license can neither be added nor revoked.

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 unsigned char unsigned char unsigned char unsigned long unsigned char int unsigned long unsigned char int unsigned char unsigned long unsigned char VLSrevokeLicense( *server_name, *feature_name, *feature_version, capacity, *password, *units_to_revoke, *capacity_to_revoke, *rvk_ticket, *length_of_rvk_ticket, *log_comment, *reserved1, *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. A pointer to the feature name of the license to be revoked. A pointer to the feature version of the license to be revoked. Not supported. A pointer to the password used for authenticating the client. A pointer to the number of tokens to be revoked. Pass 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. A pointer to the capacity units to be revoked. However, revocation of a capacity license is not supported in this release of Sentinel RMS Development Kit. Make the value of this parameter as 0 or pass NULL. 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. A pointer to the size of the license revocation ticket. A string that is written by the license manager to the comment field of

feature_name feature_version capacity password units_to_revoke

capacity_to_revoke

rvk_ticket

length_of_rvk_ticket log_comment

1.82. VLSrevokeLicense

161

Argument
reserved1 reserved2

Description the usage log file. Reserved for future use. You need to pass null in order to use this function currently. Reserved for future use. You need to pass null in order to use this function currently.

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 VLS_REVOKE_ERR_CORRUPT_MESSAGE VLS_REVOKE_ERR_OUT_VALID_RANGE VLS_REVOKE_ERR_MD5_PLUGIN_LOAD_ FAIL VLS_REVOKE_ERR_MD5_PLUGIN_EXEC_ FAIL VLS_REVOKE_ERR_INSUFFICIENT_FEATURE_LICENSES VLS_REVOKE_ERR_INSUFFICIENT_ DEFAULT_GROUP

Description License with the given feature/version does not exist on the license server. The message received by the license server was corrupted. The revocation request was beyond the range. An error was encountered while loading the MD5 plug-in DLL at the license server. An error was encountered in executing the authentication plug-in. The feature has less number of total licenses. The default group does not have sufficient licenses. You can reconfigure your user 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 VLS_REVOKE_ERR_INVALID_PASSWORD VLS_REVOKE_ERR_INTERNAL_SERVER VLS_REVOKE_ERR_INFINITE_GRP_DIST VLS_REVOKE_ERR_INFINITE_LIC_IN_USE VLS_REVOKE_ERR_INFINITE_LIC_FINITE_ REQ VLS_REVOKE_ERR_TICKET_GENERATION VLS_REVOKE_ERR_CODGEN_VERSION_ UNSUPPORTED VLS_REVOKE_ERR_RDNT_LIC_UNSUPPORED VLS_REVOKE_ERR_CAPACITY_LIC_UNSUPPORED VLS_REVOKE_ERR_UNEXPECTED_AUTH_ CHLG_PKT VLS_REVOKE_ERR_TRIAL_LIC_UNSUPPORED

Description An invalid session ID was sent by the client in packet. The password supplied for revocation was invalid. Revocation Failed! - Internal Server Error. It is not possible to revoke infinite licenses with group distribution enabled. All licenses must be free for infinite revocation. The license has infinite keys. Only infinite revocation request allowed. Failed to generate the revocation ticket. License revocation is not supported on the older versions of the License Code Generator. License revocation is not supported for redundant licenses. License revocation is not supported for capacity licenses. Unexpected error! The challenge packet was received from the license server. License revocation is not supported 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
VLSerrorHandle LSGetMessage

Description
Toggles default error handling ON or OFF. Prints licensing library-defined error messages corresponding to specified error code.

VLSsetErrorHandler Registers custom error handlers. VLSsetUserErrorFile 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 unsigned char unsigned long lshandle, Value, *buffer, bufferSize );

Argument lshandle value buffer (out)

Description Handle returned by LSRequest or VLSrequestExt. Error code. 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. Size of the buffer.

bufferSize

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 LS_STATUS_CODE char myErrorHandler, errorCode, *featureName;

Argument
errorCode featureName

Description The error code to be handled. 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. VLSsetUserErrorFile

167

1.86. VLSsetUserErrorFile
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 VLSsetUserErrorFile(

VLS_ERR_FILE msgFile, char LSFAP *filePath

);

1.86.2. Description
This function configures the displaying of error messages to the user 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 Could not open msgFile.

VLS_CALLING_ERROR

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
VLSsetTraceLevel

Description
Sets the location for storing the tracing output.

VLSsetUserTraceFile Sets the tracing level. VLSsetTraceHandler Allows defining custom trace handler function.

1.87. VLSsetTraceLevel

169

1.87. VLSsetTraceLevel
Client Sets the tracing level. Server Static Library DLL

1.87.1. Description
This function sets the following trace levels:

1.87.2. Syntax
LS_STATUS_CODE VLSsetTraceLevel ( int traceLevel );

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

170

Chapter 1: Sentinel RMS Licensing Library API

1.88. VLSsetUserTraceFile
Client Server Static Library DLL

Sets the location of the trace file.

1.88.1. Syntax
LS_STATUS_CODE VLSsetUserTraceFile ( 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

VLS_NULL VLS_STDERR VLS_STDOUT

filePath

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 passed. In case, if value for only one of the argument is passed, the other should be passed as VLS_NULL. However, if values for both the arguments are passed, then preference is given to the msgFile parameter. If both the arguments are passed 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 registered, a file can be unregistered by calling VLSsetUserTraceFile 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 passed 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. VLSsetUserTraceFile

171

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

172

Chapter 1: Sentinel RMS Licensing Library API

1.89. VLSsetTraceHandler
Client Server Static Library DLL

Registers 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 register 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

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 passed depend on the the level set. bufferSize is to store the size of the buffer argument passed. If a handler is already registered and a new handler is passed as myTraceHandler argument, the API un-registers the existing handler and registers the new one. Also, once registered, a handler cannot be unregistered 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

173

Error Code

Description please retry calling this API function.

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

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 VLSgetCommuterInfo Description Commuter information structure 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 VLSgetMachineIDString VLSgetCommuterCode VLSinstallCommuterCode Removes the commuter authorization from the client side persistence database and returns the token to the license server. Obtains commuter locking code from a remote computer. Checks out a commuter authorization for a remote computer. Install a commuter authorization on a remote computer.

VLScleanExpiredCommuterCode Cleans the expired commuter authorization on a client.

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 feature_name feature_version birth_day birth_month birth_year death_day death_month death_year num_of_licenses locking_crit lock_info vendor_info

Version of the code generator used Name of the feature Version of the feature Start day (1-31) Start month (1-12) Start year End day (1-31) End month (1-12) End year Number of licenses Locking criteria of the client Locking information of the client The vendor-defined information string. Maximum length of this string can be 2000 characters.

2.1. VLScommuterInfo

177

Argument
issuing_server key_life_time protocol_type status

Description License checked out from <servername> The license lifetime for this feature (in seconds). Type of protocol used
n n

1 - Active 0 - Inactive

178

Chapter 2: Commuter License API

2.2. VLSgetCommuterInfo
2.2.1. Syntax
int VLSgetCommuterInfo ( unsigned char unsigned char int VLScommuterInfo *feature_name, *version, index, *commuter_info );

Argument
feature_name version index

Description Name of the feature. Version of the feature. 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. The structure, which returns the information about the checked-out license. Space must be allocated by the caller.

commuter_info

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

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. Version of the feature. 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. 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 systems time and not that of the license server.

feature_version
units_reqd

duration

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. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired. The challenge-response for this operation. Pointer to a challenge structure. The challenge-response will also be returned in this structure.

log_comment challenge

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 supported lock masks, which are passed 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

duration is NULL lock_mask is NULL unitsReqd is NULL

VLS_UNABLE_TO_INSTALL_COMMUTER_CODE

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 unsigned char unsigned char *feature_name, *feature_version, *log_comment );

Argument
feature_name feature_version log_comment

Description Name of the feature. Version of the feature. A string to be written by the license server to the comment field of the usage log file. Pass 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 user to prevent the remote user 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 passes 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 user, 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 unsigned char unsigned long *lock_selector, *machineIDString, *bufSz );

Argument lock_selector

Description 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 machines locking information. This will be passed on to VLSgetCommuterCode on a computer that can actually check out a commuter authorization from the license server. bufSz Returns the buffer size of the machineIDString parameter if machineIDString is NULL. Otherwise, specifies the size of the machineIDString parameter.

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 passed 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 VLS_LOCK_IP_ADDR VLS_LOCK_DISK_ID VLS_LOCK_HOSTNAME VLS_LOCK_ETHERNET VLS_LOCK_PORTABLE_SERV VLS_LOCK_CUSTOM VLS_LOCK_CPU VLS_LOCK_CUSTOMEX VLS_LOCK_HARD_DISK_SERIAL VLS_LOCK_CPU_INFO VLS_LOCK_UUID VLS_LOCK_ALL 0x1 0x2 0x4 0x8 0x10 0x80 0x100 0x200 0x400 0x800 0x1000 0x2000 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 passed 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 passed 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 unsigned char unsigned long unsigned long unsigned long unsigned char unsigned char unsigned char LS_CHALLENGE VLSserverInfo VLSserverInfo unsigned long *feature_name, *feature_version, *units_rqd, *duration, *lock_mask, *log_comment, *machineIDString, *commuter_code, *challenge, *requestInfo, *commuterInfo, *extension_in_duration );

Argument
feature_name feature_version units_reqd duration lock_mask

Description The feature name of the license to check out from the license server. The feature version of the license to check out from the license server. Number of units required for the license. Number of days the commuter authorization will last. This value may be superseded by the maximum limit allowed by the license. 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. A comment which will be placed inside the log file on the license server. Machine ID string generated by the remote computer desiring the commuter authorization. The actual commuter authorization code. This string should be passed on to the remote computer desiring the commuter authorization for

log_comment machineIDString commuter_code

2.6. VLSgetCommuterCode

185

Argument
challenge requestInfo commuterInfo extension_in_duration

Description installation. A challenge and response for the given license on the license server. Set to NULL if you are not using this feature. Reserved. Use NULL for this value. To be used in future for hooks. 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, pass this as NULL under the following scenarios:
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 unsigned char unsigned char unsigned long *feature_name, *feature_version, *log_comment *unused );

Argument
feature_name feature_version log_comment unused

Description Name of the feature. Version of the feature. 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 passed 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 init simply expires.

2.8.1. Syntax
LS_STATUS_CODE VLSinstallCommuterCode ( unsigned char *commuter_code, unsigned char *reserved1, unsigned long *reserved2 );

Argument
commuter_code reserved1 reserved2

Description The commuter authorization that was generated by a computer with network access to the license server. Reserved. Use NULL for this value. 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 Developers Guide and the Sentinel RMS SDK System Administrators 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_SUPPORTED error code.

Given below is the list of the API functions: Function VLSaddFeature Description Dynamically adds licensing information about a feature into the license servers internal tables. If licensing information for this feature and version already exists in the license servers 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. Dynamically adds licensing information to the license servers internal tables and normal or redundant license file. 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. Removes a license servers name from the pool. This API will actually modify the license redundant file in order to delete the given license server from the pool. 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. Returns the current token distribution status for the given license feature and version.

VLSaddFeatureToFile VLSaddServerToPool

VLSdelServerFromPool

VLSdiscoverExt

VLSgetDistbCrit

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. Returns the current leader license servers name by contacting any license server. So a license servers name must be set before a call is made to this function. 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). Returns a list of redundant license servers and their status. Turns logging on/off for the given event.

VLSgetLeaderServerName

VLSgetLicSharingServerList

VLSgetPoolServerList VLSsetServerLogState

3.1. VLSaddFeature

191

3.1. VLSaddFeature
3.1.1. Syntax
int VLSaddFeature ( unsigned char unsigned char LS_CHALLENGE *licenseStr, *unused1, *unused2 );

Argument licenseStr unused1 unused2

Description The license string that will be added. Should be NULL. 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 servers internal tables. If licensing information for this feature and version already exists in the license servers 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 LS_NO_SUCCESS VLS_ADD_LIC_FAILED VLS_CLK_TAMP_FOUND Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. licenseString is NULL Generic error indicating the feature has not been added. License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied. License server on specified host is not available for processing the license operation requests. Communication with license server has timed out. Invalid hostName was specified. License server has not been set and is unable to determine which license server to use.

VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE

192

Chapter 3: Redundancy API

Error Code VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

Description Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in servicing the 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.2. VLSaddFeatureToFile

193

3.2. VLSaddFeatureToFile
3.2.1. Syntax
int VLSaddFeatureToFile ( unsigned char unsigned char unsigned char unsigned char *licenseString, *unused1, *unused2, *unused3 );

Argument licenseString unused1 unused2 unused3

Description The license_string character. Should be NULL. Should be NULL. 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 LS_NO_SUCCESS VLS_ADD_LIC_FAILED VLS_CLK_TAMP_FOUND Description Attempted to use stand-alone mode with network only library, or network mode with stand-alone library. licenseString is NULL Generic error indicating the feature has not been added. License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied. License server on specified host is not available for processing the license operation requests. Communication with license server has timed out. Invalid hostName is specified. License server has not been set and is unable to determine which license server to use. Message returned by the license server could not be understood.

VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE

194

Chapter 3: Redundancy API

Error Code LS_NO_NETWORK LS_NORESOURCES

Description Generic error indicating that the network is unavailable in servicing the 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.3. VLSaddServerToPool

195

3.3. VLSaddServerToPool
3.3.1. Syntax
int VLSaddServerToPool ( char char *server_name, *server_addr );

Argument server_name server_addr

Description Name of the license server to add to the pool. 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. Generic error indicating that the license server could not be added to the pool. License server is non-redundant and therefore cannot support this redundancy-related operation. Attempted to add a license server that is already in the pool. Pool already has maximum number of license servers. No more license servers can be added. hostName is not valid. Invalid user. License server synchronization in process. Error in configuration file. License server on specified host is not available for processing the license operation requests. Invalid hostName is specified.

LS_NO_SUCCESS VLS_NON_REDUNDANT_SRVR VLS_SERVER_ALREADY_ PRESENT VLS_POOL_FULL VLS_BAD_HOSTNAME VLS_NOT_AUTHORIZED VLS_SERVER_SYNC_IN_ PROGRESS VLS_CONF_FILE_ERROR VLS_NO_SERVER_ RUNNING VLS_HOST_UNKNOWN

196

Chapter 3: Redundancy API

Error Code VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES

Description Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in 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.4. VLSdelServerFromPool

197

3.4. VLSdelServerFromPool
3.4.1. Syntax
int VLSdelServerFromPool ( char char *server_name, *server_addr );

Argument
server_name server_addr

Description Name of the license server to delete from the pool. IP address of license server.

3.4.2. Description
Removes a license servers 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. Generic error indicating that the license server could not be deleted from the pool. License server is non-redundant and therefore cannot support this redundancy-related operation. Attempted to delete a license server that is not in the pool. Cannot remove the last license server from the pool. License server on specified host is not available for processing the license operation requests. hostName is not valid. Invalid user. Error in configuration file. Invalid hostName is specified. Message returned by the license server could not be understood.

LS_NO_SUCCESS VLS_NON_REDUNDANT_ SRVR VLS_SERVER_NOT_PRESENT VLS_ONLY_SERVER VLS_NO_SERVER_RUNNING VLS_BAD_HOSTNAME VLS_NOT_AUTHORIZED VLS_CONF_FILE_ERROR VLS_HOST_UNKNOWN VLS_BAD_SERVER_ MESSAGE

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization in process.

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 unsigned char unsigned char int VLSdiscoverInfo int int char *feature name, *version, *unused1, *num_servers, *discoverInfo, option_Flag, sharing_crit, *vendor_list );

Argument
feature_name version unused1 num_servers discoverInfo

Description Name of the feature. Version of the feature. Must be unique. Should be NULL. Number of license servers for which discoverInfo array is allocated. The core function that receives the broadcast message, splits and puts the license servers name in array format. VLSdiscoverInfo struct that will contain requested information. The option flag is allowed to be logically ORed with other flags. However, this flag will have first priority. Valid flags are:
n

option_Flag

VLS_DISC_NO_USERLIST Do not check the host list specified by the user. 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 contacted license server in the server_ list, as soon as it is contacted by any of the license servers. Otherwise, it returns the name of the first contacted 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
sharing_crit

Description to specify. The license server will match clients internal information with the keys it is already granted. Values are:
n n n n n

VLScg_NO_SHARING VLScg_USER_SHARING VLScg_HOSTNAME_SHARING VLScg_XDISPLAY_SHARING VLScg_VENDOR_SHARING

vendor_list

Consists of server names. These license serves will be contacted. 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 contacted 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 supported Total number of clients connected to the license server Server IP address Number of units/tokens available 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 LS_NORESOURCES LS_BAD_PARAMETER Generic error indicating the license servers characteristic information could not be retrieved. An error occurred in attempting to allocate memory needed by this function. License servers name is NULL or an empty string.

3.5. VLSdiscoverExt

201

Error Code

LS_SERVER_DOES_NOT_ EXIST LS_LEADER_NOT_KNOWN LS_NON_REDUNDANT_ SERVER_ CONTACTED VLS_LEADER_NOT_ PRESENT VLS_NON_REDUNDANT_ SERVER

Description Named license server does not exist. Leader name is not known. The license server contacted is non-redundant, and does not support this function. Leader name is not known. The license server contacted is non-redundant, and therefore does not support this function.

LS_UNRESOLVED_SERVER_NAME License servers name is not resolvable.

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

202

Chapter 3: Redundancy API

3.6. VLSgetDistbCrit
3.6.1. Syntax
int VLSgetDistbCrit ( char char char int *feature_name, *feature_version, *dist_crit, *distcrit_buflen );

Argument
feature_name feature_version dist_crit (OUT)

Description Name of the feature. Version of the feature. Must be unique. 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. Size of memory allocated for dist_crit.

distcrit_buflen

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. License server does not have a license that matches requested feature, version and capacity. dist_crit buffer not large enough to store information. License server is non-redundant and therefore cannot support this redundancy-related operation. Feature is inactive on specified license server. License server synchronization in process.

VLS_NO_SUCH_FEATURE LS_BUFFER_TOO_SMALL VLS_NON_REDUNDANT_ SRVR VLS_FEATURE_INACTIVE VLS_SERVER_SYNC_IN_ PROGRESS

3.6. VLSgetDistbCrit

203

Error Codes

VLS_NON_REDUNDANT_ FEATURE VLS_DIFF_LIB_VER VLS_VENDORIDMISMATCH

Description Feature is non-redundant and thus cannot be used in this redundancy-related operation. Version mismatch between license server API and client API. 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. License server on specified host is not available for processing the license operation requests. Invalid hostName is specified. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in servicing license operation. An error occurred in attempting to allocate memory needed by this function.

VLS_NO_SERVER_RUNNING VLS_HOST_UNKNOWN VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

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 feature_version file_name

Description Name of the feature. Version of the feature. 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. License server does not have a license that matches requested feature, version and capacity. An error occurred opening the file. License server is non-redundant and therefore cannot support this redundancy-related operation. Feature is non-redundant and thus cannot be used in this redundancy-related operation. Version mismatch between license server API and client API. License server on specified host is not available for processing license operation requests. Invalid hostName is specified.

VLS_NO_SUCH_FEATURE VLS_FILE_OPEN_ERROR VLS_NON_REDUNDANT_ SRVR VLS_NON_REDUNDANT_ FEATURE VLS_DIFF_LIB_VER

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization process. VLS_NO_SERVER_ RUNNING VLS_HOST_UNKNOWN

3.7. VLSgetDistbCritToFile

205

Error Code

VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES LS_BAD_PARAMETER LS_BUFFER_TOO_SMALL LS_NO_SUCH_FEATURE LS_NON_REDUNDANT_ SERVER_ CONTACTED VLS_CALLING_ERROR VLS_LEADER_NOT_ PRESENT VLS_NON_REDUNDANT_ SRVR

Description Message returned by license server could not be understood. Generic error indicating that the network is unavailable in servicing license operation. An error occurred in attempting to allocate memory needed by this function. License servers name is NULL or an empty string. Buffer provided is too small. feature_version is non-existent. LSHOST is set to non-redundant license server. License servers name is NULL or an empty string. Leader name is not known. Sets LSHOST to non-redundant license server.

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

206

Chapter 3: Redundancy API

3.8. VLSgetLeaderServerName
3.8.1. Syntax
int VLSgetLeaderServerName ( char int *leader_name, leader_name_len );

Argument
leader_name

Description Current lead license servers IP address. Space to be allocated by the caller. Size of leader_name.

leader_name_len

3.8.2. Description
Returns the IP address of the contacted 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 contacted is selected by the VLSgetContactServer call. So, the VLSgetContactServer 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 LS_BUFFER_TOO_SMALL VLS_NON_REDUNDANT_SRVR VLS_LEADER_NOT_PRESENT VLS_SERVER_SYNC_IN_ PROGRESS VLS_NON_REDUNDANT_ FEATURE VLS_DIFF_LIB_VER VLS_NO_SERVER_RUNNING VLS_HOST_UNKNOWN

Description n leader_name is NULL n leadername_len is NULL. leadername_len is smaller than the license server name that will be returned. License server is non-redundant and therefore cannot support this redundancy-related operation. Unknown leader. License server synchronization in process. Feature is non-redundant and thus cannot be used in this redundancy-related operation. Version mismatch between license server API and client API. License server on specified host is not available for processing the license operation requests. Invalid hostName is specified.

3.8. VLSgetLeaderServerName

207

Error Code

VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES LS_UNRESOLVED_IP_ADDRESS LS_BAD_PARAMETER LS_BUFFER_TOO_SMALL VLS_CALLING_ERROR VLS_LEADER_NOT_PRESENT VLS_NON_REDUNDANT_SRVR

Description Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in servicing license operation. An error occurred in attempting to allocate memory needed by this function. IP address given is not correct. License servers name is NULL or an empty string. Buffer provided is too small. License servers name is NULL or an empty string. Leader name is not known. The license server is non-redundant, and therefore does not support this operation.

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

208

Chapter 3: Redundancy API

3.9. VLSgetLicSharingServerList
3.9.1. Syntax
int VLSgetLicSharingServerList ( char char char int int *feature_name, *feature_version, *server_list_len, *server_list, *num_servers );

Argument
feature_name feature_version server_list server_list_len num_servers

Description Name of the feature. Version of the feature. A list that contains the license servers names (hostNames or IP addresses). License server will retrieve all the license servers names. If the list is larger than the specified limit, it will be truncated. 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 servers name is NULL or an empty string. n Both feature name and version cannot be NULL at the same time. server_list_len is smaller than license server name that will be returned. License server does not have a license that matches the requested feature, version and capacity. Feature is inactive on specified license server. License server synchronization in process.

LS_BUFFER_TOO_SMALL VLS_NO_SUCH_FEATURE VLS_FEATURE_INACTIVE VLS_SERVER_SYNC_IN_ PROGRESS

3.9. VLSgetLicSharingServerList

209

Error Code

VLS_NON_REDUNDANT_ FEATURE VLS_DIFF_LIB_VER VLS_NO_SERVER_RUNNING VLS_HOST_UNKNOWN VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_UNRESOLVED_HOSTNAME LS_BAD_PARAMETER VLS_NON_REDUNDANT_SRVR

Description Feature is non-redundant and thus cannot be used in this redundancy-related operation. Version mismatch between license server API and client API. License server on specified host is not available for processing the license operation requests. Invalid hostName is specified. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable in servicing license operation. Host name given is not correct. License servers name is NULL or an empty string. The license server is non-redundant, and therefore does not support 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 *outBuf, outBufSz );

Argument
outBuf (OUT) outBufSz

Description Output buffer. 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 contacted 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 contacted, the VLS_NON_REDUNDANT_SRVR error code is returned. The license server to be contacted is selected by VLSgetContactServer, so you must set the license servers 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 LS_BUFFER_TOO_SMALL VLS_SERVER_SYNC_IN_PROGRESS VLS_DIFF_LIB_VER LS_NORESOURCES VLS_NON_REDUNDANT_SRVR VLS_ LEADER_NOT_PRESENT

Description License servers name is NULL or an empty string. The output buffer is too small. License server synchronization in process. Version mismatch between license server API and client API. Insufficient resources (such as memory) as available to complete the request. The license server is non-redundant, and therefore does not support this operation. 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 ( int int event, state );

Argument
event

Description The event you want to log. Event may be:

n n n n n n n

n n n

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)

state

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 contacted is selected by VLSgetContactServer, so you must set the license servers 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 VLS_DIFF_LIB_VER VLS_FEATURE_INACTIVE VLS_MSG_TO_LEADER VLS_NOT_AUTHORIZED VLS_BAD_SERVER_ MESSAGE

Description License servers name is NULL or an empty string. Version mismatch between license server API and client API. The given feature is inactive on the specified license server. The request has been sent to the leader license server. The user making the request is invalid. 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 Developers 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 VLSsetContextData Returns the current context data stored. Sets the current context data with the data passed in context_buff.

214

Chapter 4: Volume Transaction Licensing API

4.1. VLSgetConsumeLimit
4.1.1. Syntax
LS_STATUS_CODE LS_HANDLE CONSUME_LIMIT_TYPE long LS_CHALLENGE VMSWINAPI VLSgetConsumeLimit ( lshandle, consume_type, LSFAR *consume_value, LSFAR *challenge );

Parameter
lshandle

Direction Data Type IN LS_HANDLE

Description The license handle. A valid license handle is returned by the RMS license server when the license request is successful. Specifies the type of the limit whose current value is to be obtained. It can be either of the following:
n

consume_type

IN

CONSUME_LIMIT_TYPE

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 user allocated memory, which is filled by the API function with the current limit on its return. Currently unused. Use NULL.

challenge

UNUSED

LS_CHALLENGE

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 VLS_NOT_SUPPORTED VLS_NO_RECORDS_FOUND VLS_OPERATION_NOT_SUCCESSFUL

An invalid handle. If the API is called with a handle corresponding to a queued client or a capacity token. No records for the limit in the database. The requested operation failed for any other reason.

4.2. VLSsetConsumeLimit

215

4.2. VLSsetConsumeLimit
4.2.1. Syntax
LS_STATUS_CODE LS_HANDLE CONSUME_LIMIT_TYPE CONSUME_OPERATION_TYPE long LS_CHALLENGE VMSWINAPI VLSsetConsumeLimit ( lshandle, consume_type, consume_op_type, LSFAR *consume_value, LSFAR *challenge );

Parameter
lshandle

Direction Data Type IN LS_HANDLE

Description 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

VLS_LIMIT_TYPE_VOLUME - Sets the number of transactionbased limit. VLS_LIMIT_TYPE_DURATION Sets the duration-based limit.

consume_op_type

IN

CONSUME_OPERATION_TYPE

Specifies the type of the operation to be performed. It can be either of the following:
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 challenge

IN/OUT UNUSED

long LS_CHALLENGE

A pointer to a user allocated memory filled by the value (limit) to set or reset. 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

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 VLS_NOT_SUPPORTED VLS_NEW_RECORD_FOUND

An invalid handle. If the API is called with a handle corresponding to a queued client or a capacity token. 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. The requested operation failed for any other reason.

VLS_OPERATION_NOT_SUCCESSFUL

4.3. VLSgetContextData

217

4.3. VLSgetContextData
4.3.1. Syntax
LS_STATUS_CODE LS_HANDLE unsigned char unsigned long LS_CHALLENGE VMSWINAPI VLSgetContextData ( lshandle, LSFAR *context_buff, buff_len, LSFAR *challenge );

Parameter
lshandle

Direction IN

Data Type LS_HANDLE

Description The license handle. A valid license handle is returned by the license server when the license request is successful. A pointer to a user allocated memory to be filled by the API with the current context data on its return. Contains the length of the allocated buffer. Currently unused. Use NULL.

context_buff

OUT

unsigned char

buff_len challenge

IN UNUSED

unsigned long LS_CHALLENGE

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 VLS_NOT_SUPPORTED

An invalid handle. If the API is called with a handle corresponding to a queued client or a capacity token. No records for the context in the database.

VLS_NO_RECORDS_FOUND

218

Chapter 4: Volume Transaction Licensing API

4.4. VLSsetContextData
4.4.1. Syntax
LS_STATUS_CODE VMSWINAPI VLSsetContextData ( LS_HANDLE unsigned char unsigned long LS_CHALLENGE lshandle, LSFAR *context_buff, buff_len, LSFAR *challenge );

Parameter
lshandle

Direction IN

Data Type LS_HANDLE

Description The license handle. A valid license handle is returned by the license server when the license request is successful. Contains a pointer to a user allocated memory having the context data to be written in the consume database. Contains the length of the allocated buffer. Currently unused. Use NULL.

context_buff

IN

unsigned char

buff_len challenge

IN UNUSED

unsigned long LS_CHALLENGE

4.4.2. Description
Sets the current context data with the data passed 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

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_SUPPORTED 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 supported by the Sentinel RMS Shell.

Given below is the list of the API functions: Function VLSrequestExt2 VLSgetFeatureInfoExt VLSgetCapacityList VLSgetClientInfoExt VLSdeleteFeatureExt VLSgetCapacityFrom Handle VLSsetTeamId VLSsetTeamIdValue Description Supports capacity and non-capacity requests Tracks the features available on the server Returns the list of all the capacity for particular feature and version. Returns the list of all clients running for a particular feature, version, and capacity Deletes a license from the server based on feature, version and capacity Returns the team capacity and user capacity allocated to a handle Redefines team ID functions Registers a customized team ID value

220

Chapter 5: Capacity License API

5.1. VLSrequestExt2
5.1.1. Syntax
VLSrequestExt2 ( unsigned char unsigned char unsigned char unsigned char unsigned long unsigned char LS_CHALLENGE LS_HANDLE VLSserverInfo unsigned long unsigned long unsigned char unsigned long *license_system, *publisher_name, *product_name, *version, *units_reqd, *log_comment, *challenge, *lshandle, *serverInfo, *team_capacity_reqd, *capacity_reqd, *unused1, *special_flag );

Argument
license_system

Description Unused.
n 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

publisher_name

product_name

n n n

version

n n

units_reqd

log_comment

5.1. VLSrequestExt2

221

Argument

Description field of the usage log file. n Pass a NULL value for this argument if no log comment is desired.
n

challenge

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 passed 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 passed as NULL. Required user capacity If the server does not have the requested user capacity, this field will return the user capacity available with the server for this feature and version. If the request is made for a non-capacity license this must be passed as NULL.

lshandle

n n

serverInfo

team_capacity_reqd

n n

capacity_reqd

n n

unused1 special_flag

Reserved for future use. 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
Supports capacity as well as non-capacity requests.

If the request is denied due to either insufficient team capacity or user capacity then accordingly the capacity_reqd or team_capacity_reqd field should contain the available capacity. VLSrequestExt2 must be used whenever the user 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 user information passed to the license server, he would be using the VLSsetTeamId/ VLSsetTeamIdValue APIs. The following information is sent by the licensing library as user identification information:
n n n n

User 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 pass the correct information about the user 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 username information */ int units_reqd = 1; /* Should always be 1 if using capacity request*/ unsigned long team_capacity = 1000; /* Say*/ unsigned long user_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 pass SENTINEL as the user name. So even if the user has logged into the client machine with say "XYZ" user name, the license server would see the request as if it is coming from user "SENTINEL". Now

5.1. VLSrequestExt2

223

ret_val = VLSrequestExt2(featureName, version,&units_reqd, &team_ capacity, &user_capacity); if(ret_val == LS_SUCCESS){ // Succesfully got the requested token as well as team and user 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 User capacity has been exhausted 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

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_LICENSE_GIVEN VLS_NO_SUCH_FEATURE LS_NOLICENSESAVAILABLE LS_INSUFFICIENTUNITS LS_LICENSE_EXPIRED VLS_TRIAL_LIC_EXHAUSTED VLS_USER_EXCLUDED VLS_CLK_TAMP_FOUND

n n

License server does not have license that matches requested feature, version and capacity. All licenses are in use. License server does not have sufficient licensing units for requested feature to grant license. License has expired. Trial license expired or trial license usage exhausted. User or machine excluded from accessing requested feature.
n

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.

VLS_VENDORIDMISMATCH

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. License server synchronization in process. Feature is inactive on specified license server. Majority rule failure prevents token from being issued. License server on specified host is not available for processing license operation request. Communication with license server has timed out. Invalid hostName was specified.
n n

VLS_SERVER_SYNC_IN_ PROGRESS VLS_FEATURE_INACTIVE VLS_MAJORITY_RULE_ FAILURE VLS_NO_SERVER_RUNNING VLS_NO_SERVER_RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_INTERNAL_ERROR

No license server has been set Unable to determine which license server to use.

Message from the license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. 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_USER_ CAPACITY License server does not currently have sufficient user 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 version capacity index unused1 unused2 feature_info

Description Name of the feature. Version of the feature. Capacity of the feature. Used to specify a particular feature. Use NULL as value. Use NULL as value. 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

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 passed 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 VLS_NO_MORE_ FEATURES VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_NO_SUCH_ FEATURE

Description Version is NULL when name is non_NULL Finished retrieving feature information for all features on license server. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. No license server has been set and unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by function. 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 unsigned char int unsigned long char char unsigned long #endif ); LSFAR *feature_name, LSFAR *feature_version, LSFAR *index, LSFAR *bufferSize, LSFAR *capacityList, LSFAR *log_comment, LSFAR *unused2

Argument
feature_name feature_version index bufferSize capacityList log_comment unused1

Description Name of the feature. Version of the feature. Returns the index of the license up to which the capacity has been retrieved based on the bufferSize Specifies the size of 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. Use NULL as value. 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 passed 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 Feature F1, version V1, capacity 1000 Feature F1, version V1, capacity 1500 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 VLS_APP_UNNAMED VLS_CALLING_ERROR VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_BUFFER_TOO_SMALL LS_NORESOURCES Description License server does not have a license that matches the request feature, version and capacity. featureName is NULL. Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. No license server has been set and unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in the use of an internal buffer. 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 unsigned char unsigned long int char VLSclientInfo *client_info ); *feature_name, *version, *capacity, index, *log_comment,

Argument
feature_name version capacity index log_comment client_info

Description Name of the feature. Version of the feature. Capacity of the feature. Used to specify a particular client. Comment. 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 VLS_NO_SUCH_FEATURE VLS_MULTIPLE_VENDORID_ FOUND VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

Description Finished retrieving client information for all clients. License server does not have a license that matches requested feature, version and capacity. The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested. License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. No license server has been set and unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. 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 unsigned char unsigned long unsigned char LS_CHALLENGE unsigned char unsigned char *feature_name, *version, *capacity, *log_comment, *challenge, *unused1, *unused2 );

Argument
feature_name version capacity log_comment challenge

Description Name of the feature. Version of the feature. Capacity of the feature. Unused. Use NULL as value. Unused. Use NULL as value. Use NULL as value. Use NULL as value.

unused1 unused2

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 VLS_NO_SUCH_FEATURE VLS_DELETE_LIC_FAILED Attempted to use stand-alone mode with network-only library, or network mode with stand-alone library. License server does not have a license that matches requested feature, version and capacity. 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 VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. No license server has been set and unable to determine which license server to use. Message from license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. 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

233

5.6. VLSgetCapacityFromHandle
5.6.1. Syntax
VLSgetCapacityFromHandle ( LS_HANDLE unsigned long unsigned long unsigned long lshandle, LSFAR *team_capacity, LSFAR *user_capacity LSFAR *license_capacity );

Argument
handle team_capacity user_capacity license_capcity

Description Handle Team capacity allocated to the handle and issued by the server User capacity allocated to the handle and issued by the server License capacity allocated to the handle

5.6.2. Description
VLSgetCapacityFromHandle returns the team capacity and user 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.

234

Chapter 5: Capacity License API

5.7. VLSsetTeamId
See VLSsetSharedId/ VLSsetTeamId.

5.8. VLSsetTeamIdValue

235

5.8. VLSsetTeamIdValue
See VLSsetSharedIdValue/ VLSsetTeamIdValue.

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 VLSserverInfo Struct VLSgetQueuedClientInfo Struct VLSqueuedRequest VLSqueuedRequestExt Description Specifies the clients preference for how it wishes to be placed in the queue. Stores information about the server. Returns client information. An integrated request for an authorized license code from the license server. Use this API to:
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. Removes a queued client from the queue. Deletes the entire queue. Reports the current status of the handle. 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. 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.

VLSremoveQueuedClient VLSremoveQueue VLSgetHandleStatus VLSupdateQueuedClient

VLSgetQueuedLicense

238

Chapter 6: License Queuing API

Function VLSqueuePreference Struct VLSinitQueuePreference

Description Specifies the client preference for getting into the queue. 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 &amp; 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,&amp;expiration_time,(unsigned char LSFAR *) NULL,(LS_CHALLENGE LSFAR *) NULL);/* Is the queued license available*/ if (returnCode == LS_SUCCESS &amp;&amp; expiration_time &gt; 0 ) { if ((returnCode =VLSgetQueuedLicense(ls_handle,(unsigned char LSFAR *) NULL,(LS_CHALLENGE LSFAR *) NULL))== LS_SUCCESS) { /*Disable the applications 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 hold_time priority_num absPosition grpPosition

Description Maximum time, the client can be in queue. After allotment, the maximum time interval for which the server will keep the requested units reserved for this client. Priority vis-a-vis other clients, as decided by the client application. For use in future. Not implemented in SLM7.0. The maximum position within the queue, before which the client can be queued. 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

241

6.3. VLSserverInfo Struct

typedef struct { char char char } VLSserverInfo; identifier[VLS_MAX_NAME_LEN]; inBuf[VLS_MAX_BUF_LEN]; outBuf[VLS_MAX_BUF_LEN];

Member

identifier inBuf outBuf

Description The name of the server hook which the user wants to call. String passed to the server. String returned by the server.

242

Chapter 6: License Queuing API

6.4. VLSQueuedClientInfo Struct

typedef struct char char char char char unsigned long long long unsigned long int int int long long int long long long } VLSqueuedClientInfo; queued_client_info_struct { user_name[VLS_MAXLEN]; host_name[VLS_MAXLEN]; x_display_name[VLS_MAXLEN]; shared_id_name[VLS_MAXLEN]; group_name[VLS_MAXLEN]; host_id; server_start_time; server_end_time; qkey_id; num_units; num_resvd_default; num_resvd_native; wait_time; hold_time; priority_num; absPosition; grpPosition; availabilityTime;

Member

user_name host_name x_display_name

Description The login name of the user using the application, where MAXLEN is set to 64 characters. Name of the host/computer where the user is running the application, where MAXLEN is set to 64 characters. Name of the X display where the user is displaying the application, where MAXLEN is set to 64 characters. 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 registering a custom function using the VLSsetSharedId API call. The maximum length of the string is set to 64 characters. Name of the reserved group to which the user belongs, where MAXLEN is set to 64 characters. If the user does not belong to an explicitly named group, DefaultGrp is returned. The host ID of the computer on which the user is working. server_start_time is the start time of the license token. 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. Identifier of the client queue.

shared_id_name

group_name

host_id server_start_time server_end_time

qkey_id

6.4. VLSQueuedClientInfo Struct

243

Member

num_units num_resvd_default num_resvd_native wait_time hold_time priority_num absPosition grpPosition

Description Number of units consumed by the client so far. The number of tokens given to this queued token from default pool, that is from the unreserved tokens. The number of tokens given to this queued token from its reservation group. Maximum time (in seconds), the client can be in queue. After allotment, the maximum time interval (in seconds) for which the server will keep the requested units reserved for this client. Priority vis-a-vis other clients, as decided by the client application. For use in future. Not implemented in SLM7.0. The maximum position within the queue, before which the client can be queued. Current position within the queue, considering only those queued clients that belong to the same group to which this client belongs to.

244

Chapter 6: License Queuing API

6.5. VLSqueuedRequest and VLSqueuedRequestExt

6.5.1. Syntax
int unsigned char unsigned char unsigned char unsigned char) unsigned long unsigned char LS_CHALLENGE LS_HANDLE VLSqueuePreference int int unsigned char unsigned char unsigned char unsigned char) unsigned long unsigned char LS_CHALLENGE LS_HANDLE VLSqueuePreference int VLSserverInfo server_info ); VLSqueuedRequest( *license_system, *publisher_name, *product_name, *version, *units_reqd, *log_comment, *challenge, *lshandle, *qPreference, requestFlag); VLSqueuedRequestExt( *license_system, *publisher_name, *product_name, *version, *units_reqd, *log_comment, *challenge, *lshandle, *qPreference, requestFlag,

Argument
license_system publisher_name

Description A license requested in the system. Pointer to the string which uniquely identifies a particular license system. 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. Feature name. The name of the product requesting licensing resources. Cannot be NULL and must be unique. Version for which licenses are requested. Must be unique for the associated feature 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 passed.

product_name version units_reqd

6.5. VLSqueuedRequest and VLSqueuedRequestExt

245

Argument
log_comment challenge lshandle

Description A string that is written by the license manager to the comment field of the usage log file. Pointer to a challenge structure. The challenge-response will also be returned. Handle to the license which the user has requested. If the user 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. Pointer to the VLSqueuePreference structure, which is used to specify the clients 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. Valid values are:
n

qPreference

requestFlag

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 pass the following information to the license server:
n

Time in seconds for the client to wait in the queue for the license. Time in seconds for the server to hold the license once it becomes available. Priority relative to other clients. The maximum position within the queue before which the client can be queued. 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 enduser 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. LS_MAX_QLEN = -1. Client preference is ignored and the client is always queued. LS_MAX_QLEN = 0. Queue is disabled and no clients will be put in the queue. LS_MAX_QLEN > 0. Overrides the clients 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

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_APP_UNNAMED VLS_NO_LICENSE_GIVEN

product_name is NULL version is NULL units_reqd is zero. Invalid handle specified. Generic error indicating that the license is not granted.

n n n

LS_NOLICENSESAVAILABLE LS_INSUFFICIENTUNITS VLS_NO_SUCH_FEATURE LS_LICENSE_EXPIRED VLS_NOMORE_QUEUE_ RESOURCES VLS_APP_NODE_LOCKED VLS_USER_EXCLUDED

All licenses in use. License server does not currently have sufficient licensing units for the requested feature to grant a license. License server does not have a license that matches requested feature, version and capacity. License has expired. Queue is full. Requested feature is node locked, but request was issued from an unauthorized machine. User or machine excluded from accessing requested feature.

6.5. VLSqueuedRequest and VLSqueuedRequestExt

247

Error Code

VLS_CLK_TAMP_FOUND

Description License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied. 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. Trial license has expired. License server on specified host is not available for processing license operation requests. Invalid hostName is specified. The license server has not been set and is unable to determine which license server to use. Generic error indicating that the network is unavailable for servicing the license operation. License server is non-redundant and therefore cannot support this redundancy-related operation. License server synchronization in process. Feature is inactive on specified license server.

VLS_VENDORIDMISMATCH

VLS_TRIAL_LIC_EXHAUSTED VLS_NO_SERVER_RUNNING

VLS_NO_SERVER_RESPONSE Communication with license server has timed out. VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE

VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be understood. LS_NO_NETWORK VLS_NON_REDUNDANT_ SRVR VLS_SERVER_SYNC_IN_ PROGRESS VLS_FEATURE_INACTIVE

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.

248

Chapter 6: License Queuing API

6.6. VLSgetQueuedClientInfo
6.6.1. Syntax
int VLSgetQueuedClientInfo ( unsigned char unsigned char int char VLSqueuedClientInfo *feature name, *version, index, LSFAR *unused1, *client_info );

Argument
feature_name version index client_info

Description Feature name of the client for which we are requesting information. An IN parameter. Version for which licenses are requested. Must be unique, for the associated feature. An IN parameter. Index of the client with the license server, for a particular feature. An IN parameter. 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

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

VLS_APP_UNNAMED

feature_name is NULL version is NULL

Both feature and version cannot be NULL VLS_NO_LICENSE_GIVEN VLS_NO_SUCH_FEATURE VLS_MULTIPLE_ VENDORID_FOUND Finished retrieving client information for all the clients. License server does not have a license that matches requested feature, version and capacity. The license server has licenses for the same feature and version from multiple vendors. It is ambiguous which feature is requested.

6.6. VLSgetQueuedClientInfo

249

Error Code

VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

Description License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. The license server has not been set and is unable to determine which license server to use. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the 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.

250

Chapter 6: License Queuing API

6.7. VLSremoveQueuedClient
6.7.1. Syntax
int VLSremoveQueuedClient ( unsigned char unsigned char int char *feature name, *version, qkey_id, *log_comment );

Argument
feature_name version qkey_id

Description Feature name of the client for which we are requesting information. Version for which licenses are requested. Identifier of the client queue, which needs to be removed. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired.

log_comment

6.7.2. Description
This API provides an administrative mechanism to remove a queued client. VLSremoveQueuedClient will be available to:
n

The user who started the license server, which actually signifies when the client was put in the queue. The root/administrator account. The user-account 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

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

VLS_APP_UNNAMED

feature_name is NULL version is NULL

Both feature name and version cannot be NULL. VLS_NO_SUCH_CLIENT VLS_CLIENT_NOT_ License server does not have the specified client. Client is not authorized to make the specified request.

6.7. VLSremoveQueuedClient

251

Error Code

Description License server on specified host is not available for processing license operation requests. Communication with license server has timed out. Invalid hostName was specified. The license server has not been set and is unable to determine which license server to use. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by this function. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the license operation. An error occurred in attempting to allocate memory needed by this function.

AUTHORIZED VLS_NO_SERVER_ RUNNING VLS_NO_SERVER_ RESPONSE VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES

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

252

Chapter 6: License Queuing API

6.8. VLSremoveQueue
6.8.1. Syntax
int VLSremoveQueue ( unsigned char unsigned char char *feature name, *version, *log_comment );

Argument
feature_name version

Description Identifies the license whose queue needs to be removed. Version for which licenses are requested. Must be unique. A string to be written by the license server to the comment field of the usage log file. Pass a NULL value for this argument if no log comment is desired.

log_comment

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

The user-account who started the license server, which actually signifies when the client was put in the queue. The root/administrator account.

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 VLS_NO_SERVER_ RUNNING VLS_HOST_UNKNOWN VLS_NO_SERVER_FILE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK Client not authorized to remove queue. License server on specified host is not available for processing license operation requests. Invalid hostName was specified. The license server has not been set and is unable to determine which license server to use. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for

6.8. VLSremoveQueue

253

Error Code

Description servicing the license operation. An error occurred in attempting to allocate memory needed by this function.

LS_NORESOURCES

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

254

Chapter 6: License Queuing API

6.9. VLSgetHandleStatus
6.9.1. Syntax
int VLSgetHandleStatus ( LS_Handle lshandle );

Argument
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 LS_NORESOURCES VLS_AMBIGUOUS_ HANDLE VLS_ACTIVE_HANDLE VLS_QUEUED_HANDLE

Description Invalid handle. Handle is already released and destroyed from previous license operations. An error occurred in attempting to allocate memory needed by this function. lshandle is an ambiguous handle; it is not exclusively active or exclusively queued. lshandle is an active 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 lshandle, *absExpiryTime, *unused1, *unused2 );

Argument
lshandle absExpiryTime

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

Zero = license is not available. Non-zero = license is available and will stop calling the API.

unused1 unused2

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. Invalid handle. Cannot update license because license has already expired. License server does not have a license that matches requested feature, version and capacity. All licenses are in use. License has expired. User or machine excluded from accessing requested feature. User or machine excluded from accessing the requested feature. Feature is node locked, but update request was issued from an unauthorized machine. License server has determined that the clients system clock has been modified. The license for this feature has time-tampering protection enabled, so the license operation is denied.

LS_BADHANDLE LS_LICENSETERMINATED VLS_NO_SUCH_FEATURE LS_NOLICENSESAVAILABLE LS_LICENSE_EXPIRED VLS_USER_EXCLUDED VLS_FINGERPRINT_ MISMATCH VLS_APP_NODE_LOCKED VLS_CLK_TAMP_FOUND

VLS_TRIAL_LIC_EXHAUSTED Trial license has expired.

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 VLS_NO_SERVER_ RESPONSE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES The domain of the license server is different from that of the client. Communication with license server has timed out. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the 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.

6.11. VLSgetQueuedLicense

257

6.11. VLSgetQueuedLicense
6.11.1. Syntax
int VLSgetQueuedLicense ( LS_HANDLE unsigned char LS_CHALLENGE lshandle, *log_comment, *challenge );

Argument
lshandle

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. A string that is written by the license manager to the comment field of the usage log file. The challenge-response for this operation. Pointer to a challenge structure. The challenge-response will also be returned.

log_comment challenge

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 passed 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 LS_BADHANDLE LS_BUFFER_TOO_SMALL VLS_NO_LICENSE_GIVEN VLS_NO_SUCH_FEATURE LS_LICENSE_EXPIRED LS_NOLICENSESAVAILABLE VLS_USER_EXCLUDED VLS_FINGERPRINT_ MIS-

Description challenge argument is non-NULL, but cannot be understood. Invalid handle. An error occurred in the use of an internal buffer. Generic error indicating that the license is not granted. License server does not have a license that matches requested feature, version and capacity. License has expired. All licenses are in use. User or machine excluded from accessing requested feature. Client-locked. Locking criteria does not match.

VLS_TRIAL_LIC_EXHAUSTED Trial license has expired.

258

Chapter 6: License Queuing API

Error Code

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

MATCH VLS_APP_NODE_LOCKED

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 VLS_NO_SERVER_ RESPONSE VLS_BAD_SERVER_ MESSAGE LS_NO_NETWORK LS_NORESOURCES The domain of the license server is different from that of the client. Communication with license server has timed out. Message returned by the license server could not be understood. Generic error indicating that the network is unavailable for servicing the 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.

6.12. VLSinitQueuePreference

259

6.12. VLSinitQueuePreference
6.12.1. Syntax
int VLSinitQueuePreference ( VLSqueuePreference *qPreference );

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

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 VLSucgInitialize VLSucgCleanup VLSucgReset VLSucgGetNumErrors VLSucgGetError Length VLSucgGetError Message VLSucgPrintError VLSucgAllowBase FeatureName VLSucgSetBaseFeatureName Description Contains the values for the upgrade license. Initializes the upgrade codegen library Destroys the handle created using VLSucgInitialize Sets all the fields of ucodeT to their default values Identifies the total number of messages recorded in the handle Returns the length of error message identified by msgNum and recorded in the handle Returns the earliest error from the handle up to bufLen characters Prints the complete info of all the error messages stored in the handle to a file. Identifies whether the corresponding VLSucgSetBaseFeatureName should be called or not Sets the value of base_feature_name in the ucodeT struct.

VLSucgAllowBase FeatureVersion Identifies whether the corresponding VLSucgSetBaseFeatureVersion should be called or not. VLSucgSetBaseFeatureVersion VLSucgAllowUpgradeCode VLSucgSetUpgrade Code VLSucgAllowUpgradeFlag VLSucgSetUpgrade Flag VLSucgAllowUpgradeVersion VLSucgSetUpgrade Version VLSucgAllowUpgradeCapacity Sets the value of base_feature_version in the ucodeT struct. Identifies whether the corresponding VLSucgSetUpgradeCode API should be called or not Sets the value of base_lock_code in the ucodeT struct to the value in the upgrade_code Identifies whether the corresponding VLSucgSetUpgradeFlag should be called or not Sets the value of upd_flags in the ucodeT struct. Identifies whether the corresponding VLSucgSetUpgradeVersion should be called or not Sets the value of upd_version in the ucodeT struct. Identifies whether the corresponding VLSucgSetUpgradeCapacityUnits and VLSucgSetUpgradeCapacity should be called or not Sets the value of capacity_increment in the ucodeT struct. Generates the upgrade license string for the given ucodeT struct Returns the number of license generation units available in the attached dongle Allows the user to generate a unique upgrade code for the base

VLSucgSetUpgrade CapacityUnits Sets the value of capacity_units in the ucodeT struct. VLSucgSetUpgrade Capacity VLSucgGenerate License VLSucgGetLicense MeterUnits VLSGenerateUpgrade LockCode

The Upgrade License Code Generator API

263

Function

Description license.

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 Vendor_code version_num base_feature_name base_feature_version lock_code generation_time generation_sequence

Description Size of the structure. Internal use Upgrade license code generation library version Feature Name of the base license that needs to be upgraded Feature Version of the base license that needs to be upgraded A unique code to identify base licenses which needs to be upgraded. This value shall be set automatically during the license generation time in GMT. It details about the time of license generation. 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. Bit-wise flag. Controls what will be updated:
n n n

upd_flags

VLSucg_UPGRADE_VERSION VLSucg_UPGRADE_CAPACITY VLSucg_UPGRADE_ALL

7.1. ucodeT Struct

265

Member upd_version capacity_units capacity_increment Unused Unused

Description New version for this feature. Flag which determines capacity least count Capacity increment for this feature. For future use. For future use.

266

Chapter 7: Upgrade License API

7.2. VLSucgInitialize
7.2.1. Syntax
int VLSucgInitialize ( VLSucg_HANDLE *iHandle );

Argument
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 supPORTED 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 *iHandle );

Argument
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 passed 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 iHandle, *ucodeP );

Argument
iHandle ucodeP

Description Instance handle for this library 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 passed 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 iHandle, *numMsgsP );

Argument
iHandle numMsgsP

Description Instance handle for this library 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 VLSucg_NO_RESOURCES VLSucg_FAIL Description If the handle passed is not a valid handle. If no resources are available. 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 int int iHandle, msgNum, *errLenP );

Argument
iHandle msgNum errLenP

Description Instance handle for this library The number of the message whose length is to be queried, starts from 0. 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 VLSucg_NO_RESOURCES VLSucg_FAIL Description If the handle passed is not a valid handle. If no resources are available. 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 ( VLSucg_HANDLE char int iHandle, *msgBuf, bufLen );

Argument
iHandle msgBuf bufLen

Description Instance handle for this library A user allocated buffer into which the reference message will be copied 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. 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 VLSucg_NO_RESOURCES VLSucg_FAIL Description If the handle passed is not a valid handle. If no resources are available. 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 ( VLSucg_HANDLE FILE iHandle, *file );

Argument
iHandle file

Description Instance handle for this library 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 VLSucg_NO_RESOURCES VLSucg_FAIL Description If the handle passed is not a valid handle. If no resources are available. 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 iHandle, *ucodeP );

Argument
iHandle ucodeP

Description Instance handle for this library 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 iHandle, *ucodeP, *feature_name );

Argument
iHandle ucodeP feature_name

Description Instance handle for this library The pointer to ucodeT struct 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 VLSucg_NO_FEATURE_NAME VLSucg_RESERV_STR_ERROR VLSucg_EXCEEDS_MAX_ VALUE Description Invalid characters in feature_name. If feature_name is NULL. If the feature_name is a reserved string. 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 ucodeP

Description Instance handle for this library 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 0 Description VLSucgSetBaseFeatureVersion is allowed. 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 ucodeT char iHandle, *ucodeP, *feature_version );

Argument
iHandle ucodeP feature_version

Description Instance handle for this library The pointer to ucodeT struct 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 VLSucg_EXCEEDS_MAX_ VALUE Description If feature_version characters are not printable. If the length of feature_version string exceeds maximum allowed length(11 char).

VLSucg_RESERV_STR_ERROR If the feature_version is a reserved string.

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 ucodeP

Description Instance handle for this library 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 0 Description VLSucgSetUpgradeCode is allowed. 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 ucodeT char iHandle, *ucodeP, *upgrade_code );

Argument
iHandle ucodeP upgrade_code

Description Instance handle for this library. The pointer to ucodeT struct. 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 passed as NULL. VLSucg_NO_UPGRADE_ If the upgrade_code is passed 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 ucodeP

Description Instance handle for this library. 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 0 Description Capacity Upgrade is allowed. 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 ucodeP flag

Description Instance handle for this library. The pointer to ucodeT struct. 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

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 VLSucg_INVALID_INPUT VLSucg_INVALID_INT_TYPE VLSucg_EXCEEDS_MAX_ VALUE VLSucg_LESS_THAN_MIN_ VALUE Description If the handle passed is not a valid handle. If the either the ucodeP or upd_flags is passed as NULL. Also if the upd_flags is passed as an empty string. If value of upd_flags is not numeric. If value of upd_flags exceeds VLSucg_UPGRADE_ALL If value is lower than VLSucg_UPGRADE_VERSION.

7.16. VLSucgSetUpgradeFlag

281

For a complete list of the error codes, see Upgrade License Error Codes.

282

Chapter 7: Upgrade License API

7.17. VLSucgAllowUpgradeVersion
7.17.1. Syntax
int VLSucgAllowUpgradeVersion ( VLSucg_HANDLE ucodeT iHandle, *ucodeP );

Argument
iHandle ucodeP

Description Instance handle for this library. The pointer to ucodeT struct.

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 0 Description VLSucgSetUpgradeVersion is allowed 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 ucodeT char iHandle, *ucodeP, *upgrade_version );

Argument
iHandle ucodeP

Description Instance handle for this library. 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 VLSucg_INVALID_CHARS VLSucg_RESERV_STR_ ERROR VLSucg_EXCEEDS_MAX_ VALUE Description If the either the ucodeP or upgrade_version is passed as NULL. Also if the upgrade _version does not contain a valid string. If upgrade_version characters are not printable. If the upgrade_version is a reserved string. 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 ucodeP

Description Instance handle for this library. 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 0 Description VLSucgSetUpgradeCapacity is allowed 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 ucodeP cap_units

Description Instance handle for this library. The pointer to ucodeT struct. Capacity specification units: from 0 to 4. The values are:
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 passed as NULL. Also if the cap_units is passed as an empty string. If the value of cap_units exceeds VLScg_CAPACITY_UNITS_MAX_ VALUE If the value is lower than VLScg_CAPACITY_UNITS_MIN_VALUE.

VLSucg_INVALID_INT_TYPE If value of cap_units is not numeric. VLSucg_EXCEEDS_MAX_ VALUE VLSucg_LESS_THAN_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 ucodeT char iHandle, *ucodeP, *cap_increment );

Argument
iHandle ucodeP cap_ increment

Description Instance handle for this library. The pointer to ucodeT struct. Controls the capacity.
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 VLSucg_INVALID_INPUT VLSucg_NOT_MULTIPLE VLSucg_EXCEEDS_MAX_ VALUE VLSucg_LESS_THAN_MIN_ Description If the handle passed is not a valid handle. If the either the ucodeP or cap_increment is passed as NULL. Also if the cap_increment is passed as an empty string. If value is not a correct multiple. If the value of cap_increment exceeds maximum allowed. If the value is lower than minimum allowed.

VLSucg_INVALID_INT_TYPE If value of cap_increment is not numeric.

7.21. VLSucgSetUpgradeCapacity

287

Error Code VALUE

Description

For a complete list of the error codes, see Upgrade License Error Codes.

288

Chapter 7: Upgrade License API

7.22. VLSucgGenerateLicense
7.22.1. Syntax
int VLSucgGenerateLicense ( VLSucg_HANDLE ucodeT char char VLSucg_HANDLE *ucodeP, *upgrade_code, **result );

Argument
iHandle ucodeP upgrade_code result

Description Instance handle for this library. The pointer to ucodeT struct. Upgrade code of base license 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

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 passed 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

289

Error Code AUTHORIZATION VLSucg_LICMETER_ COUNTER_TOOLOW VLSucg_NO_CAPACITY_ AUTHORIZATION VLSucg_NO_UPGRADE_ AUTHORIZATION VLSucg_INTERNAL_ERROR VLSucg_INVALID_BASE_ LIC_INFO VLSucg_CAPACITY_UPD_ NOT_ALLOWED VLSucg_INVALID_ UPGRADE_CODE VLSucg_LICMETER_NOT_ SUPPORTED

Description If license meter count is less than the expected decrement count. If not authorized to generate capacity licenses. If not authorized to generate upgrade licenses. If any internal error occur while generating the license string. The information-feature name, version vendor code provided for base license is incorrect. Capacity upgrade is not allowed, as the base lic is a non-capacity license. The specified upgrade code is invalid. Your Sentinel RMS Development Kit License Meter is not supported.

For a complete list of the error codes, see Upgrade License Error Codes.

290

Chapter 7: Upgrade License API

7.23. VLSucgGetLicenseMeterUnits
7.23.1. Syntax
int VLSucgGetLicenseMeterUnits ( VLSucg_HANDLE long long int iHandle, *initialUnitsP, *unitsLeftP, ucodegen_version );

Argument
iHandle initialUnitsP unitsLeftP ucodegen_version

Description Instance handle for this library. User provided license string to be decoded. User allocated buffer to receive decoded license string. 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 VLSucg_FAIL VLSucg_LICMETER_NOT_ SUPPORTED If error occur while allocating internal memory for ucodeT struct On Failure. Your Sentinel RMS Development Kit License Meter is not supported.

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 ( unsigned char unsigned char unsigned long *lic_string, *upgrade_lock_code, *buffer_size );

Argument
lic_string

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 passed instead of buffer, then this will return buffer size required for the generated upgrade lock code.

7.24.2. Description
VLSgenerateUpgradeLockCode allows the user 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 user/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 VLS_CALLING_ERROR LS_NO_SUCCESS VLS_VENDORIDMISMATCH Description Unable to allocate memory required to decode the passed license string and to generate upgrade code. If called with invalid arguments. If unable to generate upgrade code. If license string with invalid vendor code is passed. This error occurs only when client is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE. 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. buffer parameter is NULL. Size of upgrade lock code exceeds buffer_size parameter.

VLS_UPGRADE_NOT_ALLOWED

LS_BUFFER_TOO_SMALL

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 VLSdecodeUpgrade lockCode VLSucgDecodeLicense Description Stores information required to decode upgrade lock code. Decodes the upgrade lock code. 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 hash_vendor_ string capacity_flag standalone_flag num_keys birth_day birth_month birth_year death_day death_month death_year client_server_lock_mode base_lock_code base_feature_ name base_feature_ version capacity Description Number maintaining the version of the structure A numeric value representing the feature and version of the license. The value of capacity flag. The value of standalone flag. The number of keys. The starting day of the license. The starting month of the license. The starting year of the license. The expiration day of the license. The expiration month of the license. The expiration year of the license. The locking mode Base lock code Base feature name Base feature version Capacity of the license.

294

Chapter 7: Upgrade License API

7.26. VLSdecodeUpgradelockCode
7.26.1. Syntax
int VLSdecodeUpgradelockCode ( char char int ulcCode *upgrade_lock_code, *compacted_upd_lock_code, length, **ulcCodePP );

Argument
upgrade_lock_ code compacted_upd_ lock_code length ulcCodePP

Description Upgrade lock code to be decoded. Upgrade lock code string after removing comment chars and white spaces. This can also be set as null. Length of compacted_upd_lock_code in case it is not null. 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 LS_NO_SUCCESS VLS_INTERNAL_ERROR Description If vendor identification is illegal. Failed to decrypt the license 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 char int ucodeT iHandle, *AnyLicenseString, *lic_string, lic_string_length, **ucodePP );

Argument
iHandle Lic_string ucodePP

Description Instance handle for this library. User allocated buffer to receive decoded license string. Address of pointer to ucodeT struct. Contains input license string.

AnyLicenseString User provided license string to be decoded. Lic_string_length Length of decoded license string returned.

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 VLSucg_MALLOC_FAILURE VLSucg_FAIL If vendor-customized encryption fails

If error occur while allocating internal memory for ucodeT struct 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 VLSdisableEvents Description Schedules eventhandler to be awakened after so many seconds. It handles only SIGALRM signal. Disables the events scheduled. To disable a particular event pass the event handler function name as the argument. To disable all the events pass NULL as argument. Disables the feature for an allotted time.

VLSeventSleep

298

Chapter 8: Utility Functions

8.1. VLSscheduleEvent
8.1.1. Syntax
int VLSscheduleEvent ( unsigned long void long seconds, *eventHandler, repeat_event );

Argument
seconds eventHandler repeat_event

Description Time interval in seconds. Signal handler. 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 *eventHandler );

Argument
eventHandler

Description Signal handler.

8.2.2. Description
This function is called for disabling the events scheduled. To disable a particular event, pass the event handler function name as the argument. To disable all the events, pass 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
seconds

Description Time in seconds to sleep.

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 VLSgetUsageLogFileName VLSUsageAuthenticate VLSusageFileDecrypt Description This API changes the name of the existing usage log file. This change can be done while the file is being used. API determines the name of the existing usage log file. Verifies whether the usage log file is tampered or not? Decrypts the usage log file in a readable format.

302

Chapter 9: Usage Log Functions

9.1. VLSchangeUsageLogFileName
9.1.1. Syntax
int VLSchangeUsageLogFileName( char char *hostName, *newFileName);

Argument
hostName newFileName

Description The host name or IP address of the computer hosting the license server that is using the log file. The new name you want to use for the log file.

9.1.2. Description
This API passes 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( char char *hostName, *fileName );

Argument
hostName fileName

Description The host name or IP address of the computer hosting the license server that is using the log file. 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 *file_name, *len, *Output_Message);

Argument
file_name len

Description The name of the input usage log file. 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 pass the return (len ) value received from the first VLSUsageAuthenticate call and Output_Message to get a detailed description about the tampered lines. 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.

Output_Message

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

305

Codes.
The API allocates (len* sizeof(error_Msg)) memory for the Output_Message pointer. You should free the allocated memory after calling this API.

306

Chapter 9: Usage Log Functions

9.4. VLSusageFileDecrypt
9.4.1. Syntax
int VLSusageFileDecrypt ( unsigned char unsigned char unsigned char *file_name, *Option_field, *Output_file_name);

Argument
file_name len

Description The name of the input usage log file. 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 pass 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

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 user 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. After all inputs have been received, call VLScgGenerateLicense to create the license string. 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 Basic functions Functions which retrieve or print errors Functions which set flags and data fields of codeT struct License generation function(s) License meter related functions License Hash and Decode Functions License revocation functions

An example is shown below:

................... #include &lt;stdio.h&gt; /* 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 user 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

309

/* Code generator library handle. */ VLScg_HANDLE iHandle; /* Code generator APIs license code structure. */ codeT licCode; /* Expiration date information: acquired from user. */ 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(&amp;iHandle))!= VLScg_SUCCESS){ (void) VLSPrintErrors(&amp;iHandle, retCode); fprintf(stderr, "\nERROR: Code generator library initialization failed.\n"); return retCode; } /* if (!VLScgInitialize()) */ /* Initialize the license code structure. */ if((retCode=VLScgReset(iHandle,&amp;licCode))!= VLScg_SUCCESS) return VLSPrintErrors(&amp;iHandle, retCode); /* Specify that we want to generate a long code. */ if ((retCode = VLScgSetCodeLength(iHandle, &amp;licCode, VLS_LONG_CODE_TYPE_STR)) != VLScg_SUCCESS) return VLSPrintErrors(&amp;iHandle, retCode); /* Set the feature name. */ if (VLScgAllowFeatureName(iHandle, &amp;licCode) == 0) return VLSPrintErrors(&amp;iHandle, VLScg_FAIL); if ((retCode = VLScgSetFeatureName(iHandle, &amp;licCode, VLS_CGENXMPL_FEATURE_NAME)) != VLScg_SUCCESS) return VLSPrintErrors(&amp;iHandle, retCode); /* * Prompt for and acquire the expiration date from the user.*/ printf("License Expiration Month [1-12] : "); scanf("%d", &amp;expMonthInt); printf("License Expiration Day [1-31] : "); scanf("%d", &amp;expDayInt); printf("License Expiration Year : "); scanf("%d", &amp;expYearInt); /* Convert expiration date information to strings. */ sprintf(expMonth, "%d", expMonthInt);

310

Chapter 10: License Code Generation API

sprintf(expDay, sprintf(expYear,

"%d", expDayInt); "%d", expYearInt);

/* Set the expiration date. */ if (VLScgAllowLicExpiration(iHandle, &amp;licCode) == 0) return VLSPrintErrors(&amp;iHandle, VLScg_FAIL); if (((retCode = VLScgSetLicExpirationMonth(iHandle, &amp;licCode,expMonth)) != VLScg_SUCCESS) || ((retCode = VLScgSetLicExpirationDay(iHandle, &amp;licCode,expDay)) != VLScg_SUCCESS) || ((retCode = VLScgSetLicExpirationYear(iHandle, &amp;licCode,expYear)) != VLScg_SUCCESS)) return VLSPrintErrors(&amp;iHandle, retCode); /* Generate the license: memory for license string is allocated by library. */ if ((retCode = VLScgGenerateLicense(iHandle, &amp;licCode, &amp;licStr)) != VLScg_SUCCESS) return VLSPrintErrors(&amp;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(&amp;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 passes 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_users; int overdraft_users_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 additive Description Pointer to CodeT struct Can be set to:
n n n

VLScg_ADDITIVE- Additive license VLScg_EXCLUSIVE - Exclusive license VLScg_AGGREGATE_LICENSE - Aggregate license

client_server_lock_mode

Locking mode can be:

n n n n

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

holding_crit

Criterion for held licenses can be:

n n n

VLScg_HOLD_NONE VLScg_HOLD_VENDOR VLScg_HOLD_CODE

sharing_crit

Criterion for sharing of non-capacity licenses, can be:

n n n n n

VLScg_NO_SHARING VLScg_USER_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_USER_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 client_locking_crit standalone_flag out_lic_type

Description n Server lock selector/criterion (group 1) n Allows 2 hostid's per server

n n n n

Server lock selector/criterion (group 2) Allow 2 hostid's per server Client lock selector/criterion Allow 1 hostid per client

Specifies if the license is stand-alone, network, or repository. Specifies if the license is

n n n

Encrypted Expanded readable Concise readable

clock_tamper_flag feature_name feature_version birth_day birth_month birth_year death_day death_month death_year num_servers

If set then the license does not allow time tampering Name of the feature Version of the feature day of the month (1-31) 1 - 12 or JAN - DEC 2003 to...; minimum birth year can be 2003. max day of the month (1-31) 1 - 12 or JAN - DEC 2003 to... ; minimum death year can be 2003. Identifies the number of license servers. 1serverallowed for single server application and maximum 11 servers allowed for redundant server application. Stores information in ASCII. Stores information in ASCII. Number of node-locked clients, maximum of 7 node-locked clients allowed. Stores information in ASCII. Number of concurrent keys. 0 to num_keys. Number of keys alloted to each client for a network mode license. The number of subnet specifications provided for the site. Stores information in binary.
n n

server_lock_info1 server_lock_info2 num_nl_clients nl_client_lock_info num_keys soft_limit keys_per_node num_subnets site_lic_info share_limit/team-limit key_life_units long key_lifetime key_hold_units key_holdtime num_secrets

Number of clients/users who can share a single license key. Used as team limit in case of capacity license.

Determines lifetime least count. Absolute value in minutes. Flag which determines holdtime least count. Absolute value in minutes . Number of Challenge response secrets.

10.2. CodeT Struct

315

Member secrets vendor_info licType trialDaysCount use_auth_code numeric_type

Description Stores information in ASCII. The vendor-defined information string. The maximum length of the string can be up to 2000 characters. Trial or Normal license type. Life of trial license. For multi-keys or short numeric codes 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 majority_rule isCommuter commuter_max_checkout_ days

Validates if the license is actually redundant. Checks whether majority rule is on or off. Commuter licenses. 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 vendor_code version_num meter_value num_features key_type capacity_flag

For encryption level in the license code. Vendor identification code. The license version number, like version 11, 12, 13, and 14 licenses, in mapping with the RMS SDK versions. Fields for multi_key for short numeric codegen version >=2. Number of features in case of multi key. Single key/Multi key for short numeric only. 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 long capacity grace_period_flag

Flag which determines capacity least count. The capacity of this license. 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

VLScg_NO_GRACE_PERIOD - grace period not allowed (default) VLScg_STANDARD_GRACE_PERIOD - grace period allowed

grace_period_calendar_days

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 overdraft_flag overdraft_hours overdraft_users overdraft_users_isPercent local_request_lockcrit_flag

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. Not supported. Not supported. Not supported. Not supported. The flag that sets the local license request locking criteria as:
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 user-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 local_request_lockcrit_min_ num The desired number of locking criteria that must be met for making the licenses available to a local client. 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. The trial hours specified for a trial license. The public vendor information. The maximum length of the string can be up to 395 characters. 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

trial_elapsed_hours plain_vendor_info vm_detection

VLScg_VM_DISALLOWED_STRING - Denies the grant of a license. VLScg_VM_ALLOWED_STRING - Allows the grant of a license.

structSz

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. Space is not an acceptable character in the vendor information (both public and private). 011 and oil are reserved strings and cannot be used in feature name and feature version. 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 VLScgCleanup VLScgReset Description Initializes the handle. Destroys the created handle. 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 VLScg_BAD_HANDLE VLScg_LICMETER_NOT_ SUPPORTED

Description No more handles left. Call VLScgCleanup to free the resources associated with invalid handle. Your Sentinel RMS license meter is not supported.

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 codeP

Description The instance handle for this library. 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 typedef struct { long char } LS_CGLIBVERSION structSz; szVersion [LIBINFOLEN]; VLScgGetLibInfo (VLScg_LIBVERSION *pStruct )

Member Description structSz The user must allocate a buffer prior to calling this API. It must be filled by the user. 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 VLScgGetErrorLength VLScgPrintError VLScgPrintErrorExt Description Retrieves number of error messages recorded. Retrieves the length of a error message. Writes the error struct to a file.

VLScgGetErrorMessage Retrieves the earliest error from the handle.

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 VLScg_FAIL

Description If no resources are available. 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 int int iHandle, msgNum, errLenP );

Argument
iHandle msgNum errLenP

Description The instance handle for this library. The number of the message whose length is to be queried. 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 VLScg_FAIL

Description If no resources are available. 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( VLScg_HANDLE char int iHandle, *msgBuf, bufLen );

Argument
iHandle msgBuf (OUT) bufLen

Description The instance handle for this library. A user allocated buffer into which the reference message will be copied. 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 user 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 VLScg_FAIL

Description If no resources are available. 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 ( VLScg_HANDLE FILE iHandle, *file );

Argument iHandle file

Description The instance handle for this library. 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 VLScg_FAIL Description If no resources are available. 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 iHandle, *fileName );

Argument
iHandle fileName

Description The instance handle for this library. 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 VLScg_FAIL Description If no resources are available. 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
VLScgSetCodeLength VLScgAllowFeatureName VLScgSetFeatureName VLScgAllowFeatureVersion VLScgSetFeatureVersion VLScgAllowLicenseType VLScgSetLicenseType VLScgAllowTrialLicFeature VLScgSetTrialDaysCount VLScgAllowAdditive VLScgAllowAggregateLicense VLScgSetAdditive VLScgAllowKeyLifeUnits VLScgSetKeyLifetimeUnits VLScgAllowStandAloneFlag VLScgAllowNetworkFlag VLScgAllowRepositoryFlag VLScgSetStandAloneFlag VLScgAllowLogEncryptLevel VLScgSetLogEncryptLevel VLScgAllowSharedLic/ VLScgAllowTeamCriteria VLScgSetSharedLicType/ VLScgSetTeamCriteria

Description
Sets the license code length. Sets the name of the` feature to be licensed. Sets the version number to be licensed. Controls the license type. Sets the number of trial days. Sets the license to additive, exclusive, or aggregate. Sets unit of time used to specify time between license renewals. Sets whether the license will be stand-alone, network, or repository.

Controls the network license encryption level for the license servers usage log file. Enables shared licenses and sets sharing criteria for non-capacity license. Enables team licenses and sets team criteria for capacity license. Sets the number of users that can share a noncapacity license. Sets the number of team members that can share a token in case of capacity license. Enables commuter licenses to be checked out. Sets the number of concurrent licenses allowed.

VLScgAllowShareLimit/ VLScgAllowTeamLimit VLScgSetShareLimit/ VLScgSetTeamLimit

VLScgAllowCommuterLicense VLScgSetCommuterLicense VLScgAllowNumKeys VLScgSetNumKeys

330

Chapter 10: License Code Generation API

Function
VLScgAllowLockModeQuery VLScgSetClientServerLockMode VLScgAllowRedundantFlag VLScgSetRedundantFlag VLScgAllowMajorityRuleFlag VLScgSetMajorityRuleFlag VLScgAllowServerLockInfo VLScgSetServerLockInfo1 VLScgSetServerLock Mechanism1 VLScgSetServerLock Mechanism2 VLScgSetServerLockInfo2 VLScgAllowLockMechanism VLScgSetClientLockMechanism VLScgAllowClientLockInfo VLScgSetClientLockInfo VLScgSetNumClients VLScgAllowClockTamperFlag VLScgSetClockTamperFlag VLScgAllowOutLicType VLScgSetOutLicType VLScgSetLicType VLScgAllowHeldLic VLScgSetHoldingCrit VLScgAllowCodegenVersion VLScgSetCodegenVersion VLScgAllowMultiKey VLScgSetKeyType VLScgAllowSecrets VLScgSetSecrets VLScgSetNumSecrets VLScgAllowVendorInfo VLScgSetVendorInfo

Description
Sets locking mode for the license server computer. Installs client server lock mode in codeP. Controls whether the license will be used with redundant license servers. Controls whether the majority of redundant license servers must be running. Sets license server primary locking code. Installs license server lock code in primary lock. Sets license server primary fingerprint criteria. Installs license server's fingerprint criteria in primary lock. Sets license server secondary fingerprint criteria. Installs license server's fingerprint criteria in secondary lock. Sets license server secondary locking code. Installs server lock code in secondary lock. Sets clients fingerprint criteria. Sets the client locking code. Sets the number of client locking codes to be specified. Controls action on detection of clock being set back on the machine. Sets the license output format. Sets the license type. Enables/disables license hold time and determines where that hold time is specified. Sets the version of license codes to generate. Checks if the current license code setting allows multiple features. Controls whether a license will be single or multifeature. Sets the value of the specified challenge-response secrets. Sets the total number of secrets for the challengeresponse. Sets vendor-defined information in the license.

VLScgAllowMultipleServerInfoVLScgSetNumServers Fields for information on various license servers.

The Functions for Setting the Fields in CodeT Struct

331

Function
VLScgAllowKeysPerNode VLScgSetKeysPerNode VLScgAllowSiteLic VLScgSetSiteLicInfo VLScgSetNumSubnets VLScgAllowMultipleFeature VLScgSetNumFeatures VLScgAllowSoftLimit VLScgSetSoftLimit VLScgAllowKeyHoldUnits VLScgSetKeyHoldtimeUnits VLScgAllowKeyLifetime VLScgSetKeyLifetime VLScgAllowKeyHoldtime VLScgSetKeyHoldtime VLScgAllowLicBirth VLScgSetLicBirthMonth VLScgSetLicBirthDay VLScgSetLicBirthYear VLScgAllowLicExpiration VLScgSetLicExpirationMonth VLScgSetLicExpirationDay VLScgSetLicExpirationYear VLScgSetNumericType VLScgSetLoadSWLicFile VLScgAllowGracePeriodFlag VLScgSetGracePeriodFlag VLScgAllowGracePeriod VLScgSetGracePeriodDays VLScgSetGracePeriodHours VLScgAllowVmDetection VLScgSetVmDetection

Description
Sets the number of license tokens per node for the specified number of clients. Sets address of subnets licensed application will be restricted to. Sets the number of subnets the licensed application is restricted to. Sets the number of features. Sets soft limit number. Sets units of time to be used to specify license hold time. Sets time between license renewals. Sets the time a license will be held. 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. 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. Sets the value of numeric type. Sets and loads the software license file (lscgen.lic). Set the grace period for the commuter license.

Sets the action on detection of a virtual machinewhether 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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

Short codes contain less information than the long code and cannot support certain licensing option. However, they have the advantage of being easier to generate and easier to communicate to end users. Long codes contain as many characters as needed. Short, numeric codes generate numeric strings only and requires minimal information from the user. 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 VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description If either codeP or flag are NULL. Value is not numeric. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_RESERV_STR_ERROR VLScg_INVALID_CHARS

Description If the name is NULL. If the string is a reserved string. If the string characters are not printable.

VLScg_EXCEEDS_MAX_VALUE Returned if the length of string passed 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. Any printable ASCII text. Maximum of 11 characters for long licenses. Not supported for short license codes. The Basic Functions

10.16.2. Description
Version number is optional. Not supported 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 VLScg_INVALID_CHARS VLScg_EXCEEDS_ MAX_ VALUE

Description If the string is a reserved string. If the string characters are not printable. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP daysStr

Description The instance handle for this library. The pointer to the codeT struct. 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 supported only for version 11 (and later) long licenses.

10.21.1. Syntax
int VLScgAllowTrialHours ( VLScg_HANDLE codeT iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *trialHourStr );

Argument
iHandle codeP trialHourStr

Description The instance handle for this library. The pointer to the codeT struct. 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

codeP is NULL TrialHourStr is NULL.

VLScg_INVALID_TRIALHOURS

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 codeP

Description The instance handle for this library. 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

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. Description The instance handle for this library. The pointer to the codeT struct.

Argument iHandle codeP

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 codeT char iHandle, *codeP, *flag );

Argument iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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

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
VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description
If value is not numeric. 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 codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_NOT_MULTIPLE VLScg_EXCEEDS_MAX_VALUE

Description If information is a non-negative integer. If value is not a correct multiple. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP

Description The instance handle for this library. 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 codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE Description If value is not numeric. 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
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 servers 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 VLScg_LESS_THAN_MIN_ VALUE

Description If value is not a decimal number. If value is lower than VLScg_NO_ENCRYPTION.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAX_ENCRYPTION_LEVEL.

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 *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. This flag enables shared licenses and specifies the sharing criteria. Legal values are:
n n n n n

VLScg_NO_SHARING_STRING = 0 VLScg_USER_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 user 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 user to share a license already granted to an existing user: user 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. 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 *codeP ); iHandle,

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *decimalNUM );

In case of capacity license:

int VLScgSetTeamLimit ( VLScg_HANDLE codeT char iHandle, *codeP, *decimalNUM );

Argument
iHandle codeP decimalNUM

Description The instance handle for this library. The pointer to the codeT struct. Controls the number of users/clients who can share a single license. Use a decimal numeric value setting to control the number of users that can share a license. VLScg_NOLIMIT_STRING for unlimited.

10.38.2. Description
If sharing is set, multiple users or a single user 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 VLScg_EXCEEDS_MAX_VALUE VLScg_LESS_THAN_MIN_VALUE

Description If value is not numeric. If value exceeds maximum. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 users 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 VLScg_LESS_THAN_MIN_ VALUE

Description If value is not numeric. If value is lower than VLScg_NOT_ISSUE_COMMUTER_CODES_ STRING.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. The pointer to the codeT struct.

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 iHandle, *codeP, * dayStr );

Argument
iHandle codeP daysStr

Description The instance handle for this library. The pointer to the codeT struct.

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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP info num

Description The instance handle for this library. The pointer to the codeT struct. Sets the number of concurrent licenses: should be from 0 to VLScg_NOLIMIT_ STRING for no limit. 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not a non-negative integer. 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. If value of info is less than 0.

VLScg_LESS_THAN_MIN_VALUE

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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 codeP

Description The instance handle for this library. 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 flag

The pointer to the codeT struct. 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 codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP *str );

Argument
iHandle codeP str

Description The instance handle for this library. The pointer to the codeT struct. 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
iHandle codeP

Description The instance handle for this library. 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 codeP lockCode num

Description The instance handle for this library. The pointer to the codeT struct. 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). 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 codeP criterion server

Description The instance handle for this library. The pointer to the codeT struct. The lock code to install. Value should be in hex format. 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 servers 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 servers fingerprint at the end-user 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 server );

Argument
iHandle codeP criterion server

Description The instance handle for this library. The pointer to the codeT struct. The lock code to install (in hex). 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 servers 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 servers fingerprint at the end-user 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 codeP lockCode num

Description The instance handle for this library. The pointer to the codeT struct. 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. 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 codeP

Description The instance handle for this library. 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 codeP criterion client_num

Description The instance handle for this library. The pointer to the codeT struct. Mask defining which fields of machineID are to be used for locking. Value should be in hex format. 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 clients 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 iHandle, *codeP, *lockCode, num );

Argument
iHandle codeP lockCode num

Description The instance handle for this library. The pointer to the codeT struct. This buffer is used to set the lock code information for clients. 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. If value is not in dot format. If the locking criteria is unknown.

VLScg_LESS_THAN_MIN_VALUE If number is less than 0. VLScg_INVALID_IP_TYPE VLScg_UNKNOWN_LOCK

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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If input is not a non-negative integer. 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 codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_INVALID_RANGE

Description If value is not a decimal number. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 users 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 user. 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 VLScg_INVALID_RANGE

Description If value is not a decimal number. 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 iHandle, *codeP, *lictype );

Argument
iHandle codeP lictype

Description The instance handle for this library. The pointer to the codeT struct. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. 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 iHandle codeP

Description The instance handle for this library. 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 1 Description Capacity licensing is not allowed. 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
iHandle codeP Flag

Description The instance handle for this library. The pointer to the codeT struct. 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 A network license and not a stand-alone license Not a held license Not a redundant license Not a commuter license 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 VLScg_INVALID_INT_TYPE VLScg_LESS_THAN_MIN_ VALUE

Description Success If value is not numeric If value is lower than VLScg_CAPACITY_NONE

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_CAPACITY_POOLED

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 iHandle codeP

Description The instance handle for this library. 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 1

Description It is a non-capacity license. 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
iHandle codeP units

Description The instance handle for this library. The pointer to the codeT struct. Capacity specification units from 0 to 4. The values are:
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 VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE

Description Success. If value is not numeric. 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
iHandle codeP capacity

Description The instance handle for this library. The pointer to the codeT struct. Controls the capacity
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 VLScg_NOT_MULTIPLE VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. If value is not a correct multiple. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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

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 VLScg_LESS_THAN_MIN_ VALUE

Description If value is not a decimal number. If value is lower than VLScg_SINGLE_KEY_STRING.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MULTI_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 codeP

Description The instance handle for this library. 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 codeT char int iHandle, *codeP, *valu, num );

Argument
iHandle codeP valu num

Description The instance handle for this library. The pointer to the codeT struct. Any printable ASCII text. 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 passed 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 passed back to the client application as the response to the challenge. The purpose of the challenge is to verify 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 codeT char iHandle, *codeP, *valu );

Argument
iHandle codeP valu

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If value is not numeric. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 iHandle, *codeP, *pcPrivateVendorInfo );

Argument
iHandle codeP pcPrivateVendorInfo

Description The instance handle for this library. The pointer to the codeT struct. 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 providedin 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 VLScg_EXCEEDS_MAX_VALUE VLScg_LESS_THAN_MIN_VALUE VLScg_RESERV_STR_ERROR

Description If string is not valid. If value exceeds maximum. If the value is lower than minimum. 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 supported 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 char char iHandle, *codeP, *pcPrivateVendorInfo, *pcPublicVendorInfo );

Argument
iHandle codeP pcPrivateVendorInfo pcPublicVendorInfo

Description The instance handle for this library. The pointer to the codeT struct. Any printable ASCII text. Maximum of 2000 characters. This value appears as encrypted string in the license code. 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, passed as pcPrivateVendorInfo and pcPublicVendorInfo are set in the vendor_info and plain_vendor_info members, respectively, of the passed 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 PcPrivateVendorInfo or pcPublicVendorInfo is NULL. n If the API is called for licenses earlier than version 11. Length of the input string exceeds the maximum limit. The input string is a reserved word. The input string is invalid. If the string is a reserved string.

VLScg_EXCEEDS_MAX_STRLEN VLScg_RESERV_STR_ERR VLScg_INVALID_CHARS VLScg_RESERV_STR_ERROR

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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP keys num

Description The instance handle for this library. The pointer to the codeT struct. Used to set the number of keys per node. Give any decimal value. Should be from 0. Give VLScg_NOLIMIT_STRING for no limit. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char int iHandle, *codeP, *info, num );

Argument
iHandle codeP info num

Description The instance handle for this library. The pointer to the codeT struct. Set the subnet address. You can use wildcard (e.g., *.123.*.28) to specify a range. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If input is not a non-negative integer. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If input is not a decimal number. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 users (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 codeP

Description The instance handle for this library. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If information is a non-negative integer. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 user. 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 VLScg_EXCEEDS_MAX_VALUE

Description If information is a non-negative integer. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 user. During that time only that user 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 user 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 VLScg_NOT_MULTIPLE VLScg_EXCEEDS_MAX_VALUE

Description If information is a non-negative integer. If value is not a correct multiple. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If not a valid string. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_INVALID_DATE VLScg_EXCEEDS_MAX_VALUE

Description If value is not a non-negative integer. If value is not valid for the month. 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 codeT char iHandle, *codeP, *info );

Argument
iHandle codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_INVALID_YEAR VLScg_INVALID_BIRTH_YEAR VLScg_EXCEEDS_MAX_VALUE

Description If value is not a non-negative integer. If year is invalid. If year is less than 2003. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_EXCEEDS_MAX_VALUE

Description If not a valid string. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_INVALID_DATE VLScg_EXCEEDS_MAX_VALUE

Description If value is not a non-negative integer. If value is not valid for the month. 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 codeP info

Description The instance handle for this library. The pointer to the codeT struct. 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 VLScg_INVALID_YEAR VLScg_INVALID_DEATH_YEAR

Description If value is not a non-negative integer. If the year is invalid. 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 iHandle, *codeP, num );

Argument
iHandle codeP num

Description The instance handle for this library. The pointer to the codeT struct. 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 user 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 VLScg_INVALID_INT_TYPE

Description Value exceeds the maximum value of 3. If the value is not a non-negative integer.

VLScg_LESS_THAN_MIN_VALUE If value is less than 0. 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 iHandle, *filename );

Argument
iHandle filename

Description The instance handle for this library. 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 iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *flag );

Argument
iHandle codeP flag

Description The instance handle for this library. A pointer to the codeT structure. 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

iHandle, *codeP );

Argument iHandle codeP

Description The instance handle for this library. 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 iHandle, *codeP, *calendar_daysStr );

Argument
iHandle codeP calendar_daysStr

Description The instance handle for this library. The pointer to the codeT struct. 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 iHandle, *codeP, *elapsed_hoursStr );

Argument
iHandle codeP elapsed_hoursStr

Description The instance handle for this library. The pointer to the codeT struct. 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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. The pointer to the codeT struct.

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 codeT char iHandle, *codeP, *str );

Argument
iHandle codeP str

Description The instance handle for this library. The pointer to the codeT struct. The locking criteria, which can have any of the following values:
n

VLScg_LOCAL_REQUEST_LOCKCRIT_USEDEFAULT_STRING: Refers to the default criteria. VLScg_LOCAL_REQUEST_LOCKCRIT_DEFINED_STRING: Refers to a userdefined criteria.

10.117.2. Description
Sets the locking criteria as default or user-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 iHandle, *codeP );

Argument
iHandle codeP

Description The instance handle for this library. 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 codeT char iHandle, *codeP, *str );

Argument
iHandle codeP str

Description The instance handle for this library. The pointer to the codeT struct. 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 codeP

Description The instance handle for this library. 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 iHandle, *codeP, *vmDetectionStr );

Argument
iHandle codeP

Direction
IN IN

Data Type

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

vmDetectionStr IN

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 machinewhether 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 If value is not any one of the above defined flags.

VLScg_ INVALID_ INPUT

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 codeT iHandle, *codeP);

Argument
iHandle codeP

Description
The instance handle for this library. 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 iHandle, *codeP, **result );

Argument
iHandle codeP result

Description The instance handle for this library. The pointer to the codeT struct. 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 passed 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 VLScg_VENDOR_ENCRYPTION_ FAIL VLScg_LICMETER_NOT_ SUPPORTED

Description If vendor identification is illegal. If vendor-customized encryption fails. Your Sentinel RMS Development Kit License Meter is not supported.

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 VLScgCalculateLicenseHash VLScgDecodeLicense VLScgDecodeLicenseExt Description Calculates the license hash. Decodes the license string. Decodes the license string. The user needs to allocate memory.

10.124. VLScgCalculateLicenseHash

449

10.124. VLScgCalculateLicenseHash
10.124.1. Syntax
int VLScgCalculateLicenseHash ( char *pcLicenseString, unsigned char *pucLicenseHash, int *piLicenseHashLength );

Argument
pcLicenseString pucLicenseHash

Direction
IN OUT

Data Type
char

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

unsigned A pointer to the location where the license hash is to be stored. char If the value passed is NULL, the required length for this buffer is returned to the third argument piLicenseHashLength. int The length of the hash buffer. User needs to allocate memory.

piLicenseHashLength IN/OUT

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

Tip
Make sur e you pass 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 VLScg_INVALID_INPUT VLScg_BUFFER_TOO_SMALL Description One or more input parameters are invalid. 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 char int codeT iHandle, *AnyLicenseString, *lic_string, lic_string_length, **codeP );

Argument
iHandle any_license_string license_string license_string_buflen codeP

Description The instance handle for this library. User-provided license string to be decoded. User allocated buffer to receive decoded license string. An OUT parameter. Length of decoded license string returned. 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 passed 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 secretsinstead 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 VLScg_INVALID_VENDOR_CODE VLScg_VENDOR_ENCRYPTION_ FAIL Description If vendor identification is illegal. If vendor-customized encryption fails.

10.125. VLScgDecodeLicense

451

Error Code VLScg_MALLOC_FAILURE VLScg_SHORT_STRING VLScg_PREMATURE_TERM VLScg_INVALID_CHARS VLScg_EXCEEDS_MAX_STRING VLScg_REMAP_DEFAULT VLScg_DECRYPT_FAIL VLScg_INVALID_CHKSUM VLScg_FIXED_STR_ERROR VLScg_INVALID_RANGE VLScg_INVALID_INPUT VLScg_INVALID_INT_TYPE VLScg_LESS_THAN_MIN_VALUE VLScg_LESS_THAN_MAX_VALUE VLScg_INVALID_HEX_TYPE

Description Out of heap memory. License string too small to parse. Premature termination of license string. Please check. String is not valid. Length of the string is greater than the defined limit. Failed to remap default strings from configuration file for license. Decryption failed for license code. Checksum validation failed for license string. Default fixed string error. Value violates the valid range of input. Invalid input. Value is not numeric. Value entered is less than the minimum supported value. Value entered is greater than the maximum supported value. Wrong value entered. (Should be hexadecimal).

VLScg_SECRET_DECRYPT_FAILURE Decryption failed for secrets. Verify 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.

452

Chapter 10: License Code Generation API

10.126. VLScgDecodeLicenseExt
10.126.1. Syntax
LS_STATUS_CODE VLScgDecodeLicenseExt ( VLScg_HANDLE char char int codeT handle, *any_license_string, *license_string, *license_string_buflen, *codeP );

Argument
iHandle any_license_string license_string license_string_buflen codeP

Description The instance handle for this library. User-provided license string to be decoded. User allocated buffer to receive decoded license string. An OUT parameter. Length of decoded license string returned. 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 passed 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 secretsinstead 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 VLScg_INVALID_INPUT Description 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

453

Error Code

Description
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 passed along with the license string. The argument specified is not correct. Error occurred in allocating resources needed by this API. Allocated buffer is insufficient for this API. Error occurs if vendor-customized encryption fails. Out of heap memory. Error occurs when the license code too small to parse. Premature termination of license code. String is not valid. Default fixed string error. Value violates the valid range of input. Error in license code.

VLS_CALLING_ERROR LS_NO_RESOURCES LS_BUFFER_TOO_SMALL VLScg_VENDOR_ENCRYPTION_ FAIL VLScg_MALLOC_FAILURE VlsCG_SHORT_STRING VLScg_PREMATURE_TERM VLScg_INVALID_CHARS VLScg_FIXED_STR_ERROR VLScg_INVALID_RANGE VLScg_SIMPLE_ERROR

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 VLScgGetLicenseMeterUnits VLScgGetTrialLicenseMeterUnits Description Returns the number of license generation units. Returns the number of trial license generation units.

10.127. VLScgGetLicenseMeterUnits

455

10.127. VLScgGetLicenseMeterUnits
10.127.1. Syntax
int VLScgGetLicenseMeterUnits ( VLScg_HANDLE long long int iHandle, *initialUnitsP, *unitsLeftP, codegen_version );

Argument
iHandle initialUnitsP unitsLeftP codegen_version

Description The instance handle for this library. The number of units that were initially available. The number of units remaining. 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 VLScg_LICMETER_EXCEPTION VLScg_LICMETER_ACCESS_ ERROR VLScg_LICMETER_CORRUPT Description Unknown value in accessing the license meter. Error accessing the license meter. License meter is corrupted.

VLScg_LICMETER_VERSION_ MIS- License meter has an invalid version. MATCH VLScg_LICMETER_NOT_ SUPPORTED Your Sentinel RMS Development Kit License Meter is not supported.

For a complete list of the error codes, see License Generation Error Codes.
On platforms that do not support 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 int int iHandle, units, codegen_version );

Argument
iHandle units codegen_version

Description The instance handle for this library. The number of licenses available. 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 VLSgeneratePermissionTicket VLSgeneratePermissionTicketExt VLSverifyRevocationTicket VLSverifyRevocationTicketExt Description Generates a permission ticket for stand-alone licenses only. Generates a permission ticket for stand-alone and network licenses. Verifies the returned revocation ticket with the original request for stand-alone licenses only. Verifies the returned revocation ticket with the permission ticket (whether passed as a request structure or as binary data) for stand-alone and network licenses. Decodes the license revocation ticket (LRT) generated the pre 8.4.1 network revocation workflow. Decodes all types of revocation tickets.

VLScgDecodeLicenseRevocationTicket VLScgDecodeLicenseRevocationTicketExt

458

Chapter 10: License Code Generation API

10.129. VLSgeneratePermissionTicket
10.129.1. Syntax
LS_STATUS_CODE PVPT_REQUEST unsigned char unsigned int VLSgeneratePermissionTicket ( pvRequest, *pucPermissionTicket, *pui16PermissionTicketLength );

Argument
pvRequest pucPermissionTicket pui16PermissionTicketLength

Description An IN parameter. A pointer to the structure containing request data. An OUT parameter. A pointer to the generated permission ticket. The memory needs to be allocated by the caller. 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 pucPermissionTicket argument is passed 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 VLScg_RT_UNSUPPORTED_OPERATION_TYPE VLScg_RT_BUFFER_TOO_SMALL VLScg_RT_PARAMETERS_ERROR VLScg_RT_ALLOCATE_MEMORY_FAILURE

Description The requested data is invalid. The operation type is not 'A' or 'R'. The allocated memory is not enough. Invalid rehost parameters. Failure in memory allocation.

10.130. VLSgeneratePermissionTicketExt

459

10.130. VLSgeneratePermissionTicketExt
10.130.1. Syntax
LS_STATUS_CODE PVPT_REQUEST unsigned char unsigned int PVPT_REQUEST_EXT VLSgeneratePermissionTicketExt ( pvRequest, *pucPermissionTicket, *pui16PermissionTicketLength, pvRequestExt );

Argument
pvRequest pucPermissionTicket pui16PermissionTicketLength

Description An IN parameter. A pointer to the structure containing request data. An OUT parameter. A pointer to the generated permission ticket. The memory needs to be allocated by the caller. An IN/OUT parameter. The length of the generated permission ticket. An IN parameter. A pointer to the structure containing request data.

pvRequestExt

10.130.2. Description
This function is used to generate a permission ticket for:
n

Network license revocation for processing on the license server. 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 pucPermissionTicket argument is passed 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_UNSUPPORTED_OPERATION_TYPE

Description The requested data is invalid.

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 VLScg_RT_PARAMETERS_ERROR

The allocated memory is not enough. Invalid rehost parameters.

460

Chapter 10: License Code Generation API

Error Codes

VLScg_RT_ALLOCATE_MEMORY_FAILURE VLScg_RT_INSUFFICIENT_TOKENS_TO_REVOKE

Description Failure in memory allocation. The license tokens available for revocation are less than the number specified in the request structure. You cannot revoke stand-alone and network licenses using a single permission ticket. Network licenses with infinite tokens cannot be partially revoked. Full revocation is required. The permission ticket cannot be generated for redundant licenses.

VLScg_RT_MIXED_OPERATION_TYPE_UNSUPPORTED VLScg_RT_INFINITE_LIC_FINITE_REQ

VLScg_RT_RDNT_LIC_UNSUPPORED

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. The permission ticket generation not supported for licenses earlier than version 11.

VLScg_CODGEN_VERSION_UNSUPPORTED

10.131. VLSverifyRevocationTicket

461

10.131. VLSverifyRevocationTicket
10.131.1. Syntax
LS_STATUS_CODE VLSverifyRevocationTicket ( PVPT_REQUEST pvOriginalRequest, unsigned char *pucRevocationTicket, unsigned long ulRevocationTicketLength, PVRT_VERIFY_ERRORS pvErrorInfo, unsigned long *pulErrorInfoTotalLength );

Argument
pvOriginalRequest pucRevocationTicket ulRevocationTicketLength pvErrorInfo

Description An IN parameter. A pointer to the structure containing data for the original request. An IN parameter. A pointer to the returned revocation ticket. An IN parameter. The length of the revocation ticket. An OUT parameter. A pointer to the structure to store the error report. The memory needs to be allocated by the caller. An IN/OUT parameter. The size of the pvErrorInfo argument.

pulErrorInfoTotalLength

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 passed 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 verify 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 VLScg_RT_ALLOCATE_MEMORY_FAILURE

Description Invalid rehost parameters. Failure in memory allocation.

462

Chapter 10: License Code Generation API

Error Codes

VLScg_RT_VERSION_MISMATCH VLScg_RT_REHOST_LINE_CORRUPT VLScg_RT_TRANSACTION_ID_MISMATCH VLScg_RT_LOCK_CODE_MISMATCH VLScg_RT_REQUESTED_ACTION_NOT_PERFORMED VLScg_RT_NON_REQUESTED_ACTION_PERFORMED VLScg_RT_ACTION_STATUS_NOT_SUCCESS VLScg_RT_REQUEST_EMPTY VLScg_RT_REQUEST_LINE_INVALID VLScg_RT_REHOST_TICKET_INVALID_TLV_ STRUCT VLScg_RT_REHOST_TAG_MISSING VLScg_RT_VERSION_TAG_MISSING VLScg_RT_TRANSACTION_ID_TAG_MISSING VLScg_RT_LOCK_SELECTOR_TAG_MISSING VLScg_RT_LOCK_SELECTOR_MISMATCH VLScg_RT_LOCK_CODE_TAG_MISSING VLScg_RT_HASH_TAG_MISSING VLScg_RT_VERIFY_SINGLE_ERROR VLScg_RT_VERIFY_MULTIPLE_ERRORS VLScg_RT_TIME_STAMP_MISMATCH VLScg_RT_TIME_STAMP_TAG_MISSING

Description Rehost ticket version mismatch. Rehost ticket line is corrupt. Transaction Id in rehost ticket is different from in request. Lock code in rehost ticket is different from in request. Actions requested are not performed. Action performed was not requested. Requested action failed. Request is empty. Requested line is invalid. Rehost ticket is an invalid TLV (Tag-Length-Value) structure. Rehost tag is missing in the rehost ticket. Version tag is missing in the rehost ticket. Transaction Id tag is missing in the rehost ticket. Lock selector tag is missing in the rehost ticket. Lock selector is different from in request. Lock code is different from in request. Hash tag is missing in the rehost ticket. Only one error in rehost ticket. Verify if the operation type is specified as NULL. Multiple errors in rehost ticket. Mismatch in time stamp. Mismatch in time stamp tag.

10.132. VLSverifyRevocationTicketExt

463

10.132. VLSverifyRevocationTicketExt
10.132.1. Syntax
LS_STATUS_CODE VLSverifyRevocationTicketExt ( PVPT_REQUEST_EXT pvOriginalRequestExt, unsigned char *pucPermissionTicket, unsigned long ulPermissionTicketLength, unsigned char *pucRevocationTicket, unsigned long ulRevocationTicketLength, PVRT_VERIFY_ERRORS pvErrorInfo, unsigned long *pulErrorInfoTotalLength, unsigned long *unused );

Argument
pvOriginalRequestExt

Description An IN parameter. A pointer to the structure containing data for the original request. Specify NULL if passing permission ticket in binary format. An IN parameter. A pointer to the permission ticket (in binary format). Specify NULL if passing permission ticket as a structure. An IN parameter. The length of the permission ticket. Specify 0 if the permission ticket request structure is passed. An IN parameter. A pointer to the returned revocation ticket. An IN parameter. The length of the revocation ticket. An OUT parameter. A pointer to the structure to store the error report. The memory needs to be allocated by the caller. An IN/OUT parameter. The size of the pvErrorInfo argument. Reserved for future use.

pucPermissionTicket

ulPermissionTicketLength
pucRevocationTicket ulRevocationTicketLength pvErrorInfo

pulErrorInfoTotalLength

unused

10.132.2. Description
This function is an extended version of VLSverifyRevocationTicket. The VLSverifyRevocationTicketExt 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 pass the permission ticket as a structure (similar to VLSverifyRevocationTicket) or directly in the format it is generated (binary format). In case, the revocation ticket contains any statusother than successthen the field pucLicenseLine of structure PVRT_VERIFY_ERROR_LINE will contain a license line only if:

464

Chapter 10: License Code Generation API

A stand-alone revocation ticket was passed. 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 passed 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 verify the information contained in pucVendorDefined (the custom information that you can specify for each operation). However, it does verify 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 VLScg_RT_ALLOCATE_MEMORY_FAILURE VLScg_RT_VERSION_MISMATCH VLScg_RT_REHOST_LINE_CORRUPT VLScg_RT_TRANSACTION_ID_MISMATCH VLScg_RT_LOCK_CODE_MISMATCH VLScg_RT_REQUESTED_ACTION_NOT_PERFORMED VLScg_RT_NON_REQUESTED_ACTION_PERFORMED VLScg_RT_ACTION_STATUS_NOT_SUCCESS VLScg_RT_REQUEST_EMPTY VLScg_RT_REQUEST_LINE_INVALID VLScg_RT_REHOST_TICKET_INVALID_TLV_ STRUCT VLScg_RT_REHOST_TAG_MISSING VLScg_RT_VERSION_TAG_MISSING VLScg_RT_TRANSACTION_ID_TAG_MISSING

Description Invalid rehost parameters. Failure in memory allocation. Revocation ticket version mismatch. Revocation ticket line is corrupt. Transaction ID in revocation ticket is different from in request. Lock code in revocation ticket is different from in request. Actions requested are not performed. Action performed was not requested. Requested action failed. Request is empty. Requested line is invalid. Revocation ticket is an invalid TLV (Tag-LengthValue) structure. Rehost tag is missing in the revocation ticket. Version tag is missing in the revocation ticket. Transaction ID tag is missing in the revocation ticket.

10.132. VLSverifyRevocationTicketExt

465

Error Codes

VLScg_RT_LOCK_SELECTOR_TAG_MISSING VLScg_RT_LOCK_SELECTOR_MISMATCH VLScg_RT_LOCK_CODE_TAG_MISSING VLScg_RT_HASH_TAG_MISSING VLScg_RT_VERIFY_SINGLE_ERROR VLScg_RT_VERIFY_MULTIPLE_ERRORS VLScg_RT_TIME_STAMP_MISMATCH VLScg_RT_TIME_STAMP_TAG_MISSING VLScg_RT_CORRUPT_ORIG_REQ VLScg_RT_CUSTOM_DATA_TAG_MISSING VLScg_RT_CUSTOM_DATA_MISMATCH

Description Lock selector tag is missing in the revocation ticket. Lock selector is different from in request. Lock code is different from in request. Hash tag is missing in the revocation ticket. Only one error in revocation ticket. Verify if the operation type is specified as NULL. Multiple errors in revocation ticket. Mismatch in time stamp. Mismatch in time stamp tag. The permission ticket provided for verification is corrupt. The custom defined data tag is not found in the revocation ticket. The custom defined data included in the permission ticket and revocation ticket does not match. Either standalone revoke request is provided to verify with a network revocation ticket, or vice versa.

VLScg_RT_REVOCATION_TYPE_MISMATCH

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
license_revocation_ticket_buffer

Description An IN parameter. A buffer that holds the string data returned by the VLSrevokeLicense API function. 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. An IN parameter. The length of the secret key. An OUT parameter. The VLSrevocationTicketInfoT structure.

license_revocation_ticket_buffer_size An IN parameter. A buffer that defines the size of the ticket. secret_key

secret_key_length revocation_ticket

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 char int unsigned char unsigned long char int VLSrevocationTicketInfoT PVRT_REVOKE_TICKET_INFO unsigned long unsigned long VLScgDecodeLicenseRevocationTicketExt ( *license_revocation_ticket_buffer_old, license_revocation_ticket_buffer_old_size, revocation_ticket_buffer, revocation_ticket_buffer_size, *secret_key, secret_key_length, *license_revocation_ticket_old, revocation_ticket, *pulRevocation_ticket_size, *unused );

Argument
license_revocation_ticket_buffer_old

Description 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. 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. An IN parameter. A buffer that defines the size of the ticket returned by the VLSrevokeByPermissionTicket API function. 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.

license_revocation_ticket_buffer_old_size

revocation_ticket_buffer

revocation_ticket_buffer_size,

secret_key

468

Chapter 10: License Code Generation API

Argument secret_key_length license_revocation_ticket_old revocation_ticket pulRevocation_ticket_size

Description An IN parameter. The length of the secret key. An OUT parameter. The VLSrevocationTicketInfoT structure. An OUT parameter. The VRT_REVOKE_TICKET_ INFO structure. An OUT parameter. A buffer that defines the size of the revocation ticket. If the VRT_REVOKE_TICKET_ INFO structure is passed as NULL, then it will return the length in the pulRevocation_ticket_size parameter. Reserved for future use.

unused

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. The stand-alone revocation tickets (which can also be decoded using VLScgDecodeLicense). 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

469

10.135. VPT_REQUEST_LINE
10.135.1. Syntax
typedef struct _VPT_REQUEST_LINE { unsigned char unsigned char unsigned long unsigned char unsigned long } VPT_REQUEST_LINE, *PVPT_REQUEST_ ucOperation; *pucVendorDefined; ulVendorDefinedLength; *pucLicenseLine; ulLicenseLineLength; LINE;

Member
ucOperation

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. The length of the vendor defined data. The license string to be added or revoked. The length of license string to be added or revoked.

ulVendorDefinedLength pucLicenseLine ulLicenseLineLength

470

Chapter 10: License Code Generation API

10.136. VPT_REQUEST
10.136.1. Syntax
typedef struct _VPT_REQUEST { unsigned char unsigned long unsigned char unsigned long unsigned long PVPT_REQUEST_LINE } VPT_REQUEST, *PVPT_REQUEST; *pucTransactionId; ulLockCodeSelector; * pucLockInfo; ulTimeStamp; ulRequestArraySize; pvRequestArray;

Member
pucTransactionId ulLockCodeSelector pucLockInfo ulTimeStamp ulRequestArraySize pvRequestArray

Description The transaction ID to uniquely identify a permission ticket to be generated. The lock code selector. The locking information of the target lock selector. The time stamp of the permission ticket to be generated. The number of requests. A pointer to an array of structures for the requested operations and licenses.

10.137. VPT_REQUEST_LINE_EXT

471

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 struct_size ucOperation

Description The size of the structure. The requested operation. The possible values for stand-alone licenses are:
n n

A: Adds a new license. R: Completely revokes a license.

The possible values for network licenses are:

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. 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. The length of the vendor defined data. The license string to be added or revoked. The length of license string to be added or revoked.

pucVendorDefined

ulVendorDefinedLength pucLicenseLine ulLicenseLineLength

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 struct_size pucTransactionId ulLockCodeSelector pucLockInfo ulTimeStamp pucCustomDefined

Description The size of the structure. The transaction ID to uniquely identify a permission ticket to be generated. The lock code selector. The locking information of the target lock selector. 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. The length of the vendor defined custom data. The number of requests. A pointer to an array of structures for the requested operations and licenses.

ulCustomDefinedLength ulRequestArraySize pvRequestArrayExt

10.139. VRT_VERIFY_ERROR_LINE

473

10.139. VRT_VERIFY_ERROR_LINE
10.139.1. Syntax
typedef struct unsigned long unsigned char unsigned long unsigned char unsigned long unsigned long unsigned long } VRT_VERIFY _VRT_VERIFY_ERROR_LINE { ulErrorCode; ucOperation; ulStatus; pucLicenseLine[VLS_MAX_CUSTOM_LICENSE_SIZE]; ulLicenseLineLength; ulCapacityRevoked; ulNumberOfLicensesRevoked; _ERROR_LINE, *PVRT_VERIFY_ERROR_LINE;

Member
ulErrorCode

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

ucOperation

A: add a new license R: completely revoke a license P: partially revoke a license

ulStatus

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.

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 successthen pucLicenseLine will contain a license line only if:
n n

A stand-alone revocation ticket was passed. Or, a network revocation ticket was verified against the original structure of a permission ticket.

ulLicenseLineLength ulCapacityRevoked

The length of the license line. The capacity revoked. Unused.

ulNumberOfLicensesRevoked The number of licenses revoked.

10.140. VRT_VERIFY_ERRORS

475

10.140. VRT_VERIFY_ERRORS
typedef struct _VRT_VERIFY_ERRORS { unsigned long VRT_VERIFY_ERROR_LINE } VRT_VERIFY_ERRORS, ulNumOfErrors; *pvRTErrorArray; *PVRT_VERIFY_ERRORS;

Member
ulNumOfErrors pvRTErrorArray

Description The number of errors stored in the array structure. A pointer to an array of structures for reporting errors.

476

Chapter 10: License Code Generation API

10.141. VRT_REVOKE_TICKET_LINE
10.141.1. Syntax
typedef struct unsigned long unsigned char unsigned char unsigned char unsigned char unsigned long unsigned char unsigned int unsigned int unsigned int unsigned long unsigned int } VRT_REVOKE_TICKET_LINE, _VRT_REVOKE_TICKET_LINE { struct_size; feature_name[VLS_MAXFEALEN]; feature_version[VLS_MAXFEALEN]; *pucLicenseHash; *pucLicenseLine; ulLicenseLineLength; ucOperation; base_license_hard_limit; number_licenses_revoked; status; *unused1; unused2; *PVRT_VERIFY_ERROR_LINE;

Member
struct_size feature_name feature_version pucLicenseHash pucLicenseLine ulLicenseLineLength ucOperation

Description The size of the structure. The feature name for which the revocation ticket (RT) was generated. Required for network license revocation only. The feature version for which the revocation ticket (RT) was generated. Required for network license revocation only. A pointer to the license hash. For network revocation only. A pointer to the license string. For stand-alone revocation only. The length of the license string. For stand-alone revocation only. The operation type (add, full revocation, or partial revocation). The hard limit of the license. For network revocation only. The number of license tokens revoked. For network revocation only. Status corresponding to the operations executed. Reserved for future use. Reserved for future use.

base_license_hard_limit number_licenses_revoked status unused1 unused2

10.142. VRT_REVOKE_TICKET_INFO

477

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 pucTransactionId

Description The size of the structure. A pointer to the transaction ID (uniquely identifies a permission ticket). The locking criteria of the target system. The locking information of the target system. The time stamp as specified while generating the permission ticket. A pointer to the vendor defined custom data as specified while generating the permission ticket. The length of the vendor defined custom data. A pointer to the array containing the revocation information. A size of the pvRevokeInfoArray array. Reserved for future use. Reserved for future use.

locking_criteria locking_info time_stamp pucCustomDefined ulCustomDefinedLength pvRevokeInfoArray ulRevokeInfoArraySize unused1 unused2

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 unsigned long unsigned char unsigned char unsigned long unsigned int unsigned int unsigned int unsigned long unsigned long unsigned char } VLSrevocationTicketInfoT; struct_size; time_stamp; feature_name[VLS_MAXFEALEN]; feature_version[VLS_MAXFEALEN]; capacity; base_license_hard_limit; number_licenses_revoked; total_number_licenses_revoked; capacity_revoked; server_locking_criteria; server_locking_info[VLS_MAXSRVLOCKLEN];

Member
struct_size

Description The size of the structure. The time when the license revocation ticket was generated. The feature name for which the license revocation ticket was generated. The feature version for which the license revocation ticket was generated. The capacity of the feature whose license revocation ticket was generated. The hard limit of the feature whose license revocation ticket was generated. The number of licenses revoked. The total number of licenses revoked for a feature. The capacity of the feature revoked. The locking criteria of the license server on which the revocation was executed.

time_stamp feature_name feature_version capacity base_license_hard_limit number_licenses_revoked total_number_licenses_revoked capacity_revoked server_locking_criteria

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 Developers 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 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 admin mode before running any local request application or checking out a token for normal user.

11.1.4. Syntax
int char char char sntlInitStandaloneSystem ( *GUID, *featureName, *featureVersion );

Argument GUID featureName

Description The application installer's GUID. The application feature name.

The application feature version. featureVersion Stands for Global Unique Identifiera 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 user.

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 passed 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 <installdir>\English\MsvcDev\Samples\API. For UNIX, it is installed at <installdir>/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 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 <installdir>\English\MsvcDev\Samples\API. For UNIX, it is installed at <installdir>/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 Developers 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) Commuter license (VLS_COMMUTER_STORE) Time tampered license (VLS_TIME_TAMPER_STORE) License revocation (VLS_REVOKE_STORE) Grace license (VLS_GRACE_STORE) 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 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

Stand-alone Persistence Type Trial Commuter Time-tamper Grace Revocation Volume Transaction

8.1.0 or later 8.0.x

(Repairing only) (Repairing only) (Repairing only) NA NA

7.3.x
NA NA NA

7.2.x
NA NA NA

12.1.3. Syntax
LS_STATUS_CODE int int char* char* char* int VLScleanStandalonePersistenceInfo ( clientLibVersion, persistenceType, featureName, featureVersion, unused1, unused2 );

Argument

Direction

Data Description Type

int The licensing library's version. Specify any of the following:
n

clientLibVersion IN

7 - For the licensing library version 7.2.x and

12.1. VLScleanStandalonePersistenceInfo

485

Argument

Direction

Data Description Type

n n

n n

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

persistenceType IN

int

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 featureVersion

IN IN

char* The feature name of the license. Should not be of zero length and must not exceed 24 characters. 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 passed to the arguments that are not applicable to a particular scenario. For example, feature name and version must be passed as NULL for repairing the:
n

Trial license persistence (version 8.1.x or higher) Stand-alone revocation persistence (version 8.2.x or higher) 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 pass 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 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 Trial Commuter Time-tamper Revocation Volume Transaction

8.4.x - 8.5.x
NA NA NA NA

8.1.x - 8.3.x
(Repairing only) (Repairing only) (Repairing only)

8.0.x
NA

7.2.x - 7.3.x
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
IN

Data Type
int

Description The license server version. Specify any of the following:

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

487

Argument

Direction

Data Type

Description
n

n n

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

persistenceType IN

int

The persistence type. Specify any of the following:

n n n n n n

featureName

IN

char*

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 hostName

IN IN

char* char*

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

unused1 operationType

IN IN

char* int

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 pass 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 passed to the arguments that are not applicable to a particular scenario. For example, host name, feature name, and version must be passed as NULL for repairing the:
n

Trial license persistence (version 8.1.x or higher) 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 passe 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 passe d is gr e ate r than 24 c har ac te r s. Whe n the fe atur e ve r sion passe d is gr e ate r than 11 c har ac te r s. Whe n the host nam e passe 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 License generation APIs Upgrade license APIs System initialization APIs 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 # 0x0 0xC8001001 0xC8001002 0xC8001003 0xC8001004 Error/Status Codes LS_SUCCESS LS_BADHANDLE LS_INSUFFICIENTUNITS LS_LICENSESYSNOTAVAILABLE LS_LICENSETERMINATED Description Successful operation. The client handle refers to an invalid licensing system context. Could not locate enough licensing resources to license this feature. The licensing system is not available. Default error. Cannot update license because the key lifetime has expired and re-request of the license has failed. No license code is available for this feature on the specified host. All licensing tokens with the server for this feature are already in use. Insufficient system resources are available to complete the request. Unable to talk to this host. Unknown error code, cannot print the error message. Unknown error code, cannot print the error message. Bad index. No additional units are available for this feature. The feature cannot run anymore because the license expiration date has reached. Check your machine's date and contact your vendor. Input buffer too small, string may be truncated. Failed in performing the requisite operation. The feature cannot run as the total number of days allowed in the grace period have been consumed. This feature cannot run as an unexpected state of grace period is found.

0xC8001005 0xC8001006 0xC8001007 0xC8001008 0xC8001009 0xC800100A 0xC800100B 0xC800100C 0xC800100D

LS_NOAUTHORIZATIONAVAILABLE LS_NOLICENSESAVAILABLE LS_NORESOURCES LS_NO_NETWORK LS_NO_MSG_TEXT LS_UNKNOWN_STATUS LS_BAD_INDEX LS_NO_MORE_UNITS LS_LICENSE_EXPIRED

0xC800100E 0xC800100F 0xC8001010 0xC8001011 0xC8001012 1 2 3

LS_BUFFER_TOO_SMALL LS_NO_SUCCESS LS_GRACE_EXPIRED LS_GRACE_INVALID_STATE

LS_GRACE_HOURS_EXHAUSTED The feature cannot run as the total number of hours allowed in the grace period have been consumed. VLS_NO_LICENSE_GIVEN VLS_APP_UNNAMED VLS_HOST_UNKNOWN Unable to obtain licensing token for this feature. Feature name or version cannot be NULL. Failed to resolve the specified server host.

A.1. Licensing Library Error and Result Codes

493

Error # 4

Error/Status Codes VLS_NO_SERVER_FILE

Description Failed to figure out the license server correctly. Set the environment variable LSHOST to name(s) of server(s). Cannot talk to the license server on the specified host. The license server is not running. 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. Attempt to return a non-existent token by the client application. Failed to return the token issued for the specified feature. No more clients exists for this feature. No more features available on license server. Error in calling the API function. Check the calling parameters.

5 6

VLS_NO_SERVER_RUNNING VLS_APP_NODE_LOCKED

7 8 9 10 11

VLS_NO_KEY_TO_RETURN VLS_RETURN_FAILED VLS_NO_MORE_CLIENTS VLS_NO_MORE_FEATURES VLS_CALLING_ERROR

494

Appendix A: Status Codes

Error # 12

Error/Status Codes VLS_INTERNAL_ERROR

Description The possible causes are:

n

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. 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 verify the encryption logic again.

13

VLS_SEVERE_INTERNAL_ERROR The possible causes are:

n n

14 15 16 17 18

VLS_NO_SERVER_RESPONSE VLS_USER_EXCLUDED VLS_UNKNOWN_SHARED_ID VLS_NO_RESPONSE_TO_ BROADCAST VLS_NO_SUCH_FEATURE

The license server on the specified host is not responding. This user/machine has been excluded from accessing the specified feature. Unknown shared ID given for the specified feature. Probably no servers are running on this subnet. No license code is available for the specified feature

A.1. Licensing Library Error and Result Codes

495

Error # 19 20 21 22 23 24 25

Error/Status Codes VLS_ADD_LIC_FAILED VLS_DELETE_LIC_FAILED VLS_LOCAL_UPDATE VLS_REMOTE_UPDATE VLS_VENDORIDMISMATCH VLS_MULTIPLE_VENDORID_ FOUND VLS_BAD_SERVER_MESSAGE

Description on this host. The given license code could not be added to the specified license server. Failed to delete the specified feature from the license server on host. Last update was done locally. Last update was done by the license server. The specified feature is licensed by a different vendor. The specified feature is licensed by multiple vendors other than your vendor. Could not understand the message received from the license server on the specified host. Client-server version mismatch. The following scenarios are possible: Scenario A:
n

26

VLS_CLK_TAMP_FOUND

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 # 28 34 35

Error/Status Codes VLS_INVALID_DOMAIN VLS_LOG_FILE_NAME_NOT_ FOUND VLS_LOG_FILE_NAME_NOT_ CHANGED

Description Cannot perform this operation on the domain name specified. The specified log filename not found on the specified license server host. Cannot change the specified log filename on the specified license server host. The duration of the specified trial license is exhausted. No updates have taken place for this feature so far. Returned all the tokens for this feature. The specified client handle is associated with a queued request. The specified client handle is associated with an active request. Ambiguous client handle! The specified client handle is not associated with any request. Queued request denied for this application since the queue is already full. Could not find the specified client for this feature.

36 37 38 39 40 41 42 43 44 45 47 48 49 50 51 52 53 54 55 56

VLS_FINGERPRINT_MISMATCH Machine's fingerprint mismatch for this feature. VLS_TRIAL_LIC_EXHAUSTED VLS_NO_UPDATES_SO_FAR VLS_ALL_UNITS_RELEASED VLS_QUEUED_HANDLE VLS_ACTIVE_HANDLE VLS_AMBIGUOUS_HANDLE VLS_NOMORE_QUEUE_ RESOURCES VLS_NO_SUCH_CLIENT

VLS_CLIENT_NOT_AUTHORIZED Client not authorized for the specified action for this feature. VLS_LEADER_NOT_PRESENT VLS_SERVER_ALREADY_ PRESENT VLS_SERVER_NOT_PRESENT VLS_FILE_OPEN_ERROR VLS_BAD_HOSTNAME VLS_DIFF_LIB_VER VLS_NON_REDUNDANT_SRVR VLS_MSG_TO_LEADER VLS_CONTACT_FAILOVER_ SERVER Processing not done because current leader is not known. Server already exists in the redundant server pool. The given server name does not exist in the redundant server pool. File open error. The specified host name is either not valid or cannot be resolved. The server fails to identify the client application version. A non-redundant server contacted for redundant server related information Message forwarded to the leader server. Update Failure. Contact another fail-over server.

VLS_UNRESOLVED_IP_ADDRESS IP address given cannot be resolved.

A.1. Licensing Library Error and Result Codes

497

Error # 57 58 59 60

Error/Status Codes VLS_INVALID_IP_ADDRESS VLS_SERVER_FILE_SYNC VLS_POOL_FULL

Description Invalid IP address format. Server is synchronizing the distribution table The redundant server pool already has the maximum number of servers. No more servers can be added. The redundant server pool has only one server. It cannot be deleted. This feature is either unavailable on the server or server is non-redundant. The token for this feature cannot be issued because of the majority rule failure. Configuration file modifications failed. Check the given parameters. A non-redundant feature given for redundant feature related operation Cannot find trial license information for given feature. Failure in retrieving the trial usage information for the given feature. Application is not linked with integrated library. The commuter code for this feature does not exist on the client system. No more checked-out commuter code exists on the client. Failed to get client commuter info on this server. Unable to uninstall the client commuter license. The possible causes are:
n

VLS_UNRESOLVED_HOSTNAME Hostname given is unresolved.

61 62 63 64 65 66 67 69 70 72 73 74 75

VLS_ONLY_SERVER VLS_FEATURE_INACTIVE VLS_MAJORITY_RULE_FAILURE VLS_CONF_FILE_ERROR VLS_NON_REDUNDANT_FEATURE VLS_NO_TRIAL_INFO VLS_TRIAL_INFO_FAILED VLS_NOT_LINKED_TO_INTEGRATED_LIBRARY VLS_CLIENT_COMMUTER_ CODE_DOES_NOT_EXIST VLS_NO_MORE_COMMUTER_ CODE VLS_GET_COMMUTER_INFO_ FAILED VLS_UNABLE_TO_UNINSTALL_ CLIENT_COMMUTER_CODE VLS_ISSUE_COMMUTER_ CODE_FAILED

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.

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 78 79 81 82

VLS_NOT_ENOUGH_COMMUTER_KEYS_AVAILABLE VLS_INVALID_INFO_FROM_ CLIENT VLS_CLIENT_ALREADY_EXIST VLS_COMMUTER_CODE_ ALREADY_EXIST VLS_SERVER_SYNC_IN_PROGRESS

Not enough commuter tokens are available on this server. Invalid commuter info from the client. The client already exists on this server. The client commuter license already exists on this system. Error specific to the redundant server pool setup. Occurs under the following scenarios:
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 # 83 84 85 86 87 88 89

Error/Status Codes VLS_REMOTE_CHECKOUT VLS_UNABLE_TO_INSTALL_ COMMUTER_CODE VLS_UNABLE_TO_GET_ MACHINE_ID_STRING VLS_INVALID_MACHINEID_STR VLS_EXCEEDS_LICENSE_LIFE VLS_TERMINAL_SERVER_ FOUND

Description This commuter license is checked out remotely, so it cant be checked-in. Error in installing the commuter authorization code. Error getting the locking information for the client. Invalid remote locking code string. Cannot issue commuter code. License expiration is less than the requested days for commuter code. Operating in stand-alone mode using terminal client. This is not allowed by the vendor.

VLS_NOT_SUPPORTED_IN_NET_ Feature is not supported in Network-only mode of ONLY_MODE library.

The VLS_NOT_APPROPRIATE_LIBRARY error code has been deprecated. Use VLS_NOT_ SUPPORTED_IN_NET_ONLY_MODE instead.

90 91 92 93 94 95 96 97 98 99 101

VLS_INVALID_FILETYPE VLS_NOT_SUPPORTED VLS_INVALID_LICENSE VLS_DUPLICATE_LICENSE VLS_INSUFFICIENT_USER_ CAPACITY VLS_TEAM_LIMIT_EXHAUSTED VLS_INSUFFICIENT_TEAM_ CAPACITY VLS_CANNOT_DELETE_ UPGRADED_LIC

The specified file type is not supported. The client application is communicating with an old license server. The given license code is invalid. Hence, it could not be added to this license server. The given license code is already added to the specified license server. Insufficient user capacity available. Team limit exhausted. Insufficient team capacity available. Deletion of upgraded feature/license is not allowed.

VLS_UPGRADE_NOT_ALLOWED License upgrade feature is not allowed for redundant licenses, commuter licenses and trial licenses. VLS_FEATURE_MARKED_FOR_ DELETION VLS_TEAM_EXCLUDED The specified feature exists on this machine and it is already marked for check-in. This team has been excluded from accessing this feature.

500

Appendix A: Status Codes

Error # 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122

Error/Status Codes VLS_NETWORK_SRVR VLS_PERPETUAL_LICENSE VLS_COMMUTER_CHECKOUT VLS_REVOKE_ERR_NO_FEATURE VLS_REVOKE_ERR_CORRUPT_ MESSAGE

Description A network server is contacted for standalone related information. The contacted feature is a repository license. A commuter token has already been checked out for this license. License with given feature/version is either not available on the server or belongs to a different vendor.

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. VLS_REVOKE_ERR_MD5_PLUGIN_LOAD_FAIL VLS_REVOKE_ERR_MD5_PLUGIN_EXEC_FAIL VLS_REVOKE_ERR_INSUFFICIENT_FEATURE_LICENSES VLS_REVOKE_ERR_INSUFFICIENT_DEFAULT_GROUP VLS_REVOKE_ERR_INSUFFICIENT_FREE_IN_DEFAULT Error loading the MD5 plug-in dll at the server. Error in executing the authentication plug-in. This feature has less number of total licenses. Default group does not has sufficient licenses, reconfigure your user reservation file. Currently required number of licenses are not free for revocation in the default group.

VLS_REVOKE_ERR_INVALID_SES- Invalid session id received from the client. SION_ID VLS_REVOKE_ERR_INVALID_ PASSWORD VLS_REVOKE_ERR_INTERNAL_ SERVER VLS_REVOKE_ERR_INFINITE_ GRP_DIST VLS_REVOKE_ERR_INFINITE_ LIC_IN_USE VLS_REVOKE_ERR_INFINITE_ LIC_FINITE_REQ Invalid password for revocation. Revocation failed due to internal server error. Infinite revocation not possible with enabled group distribution. All licenses must be free for infinite revocation. License has infinite keys. Only infinite license revocation request is allowed for this license.

VLS_REVOKE_ERR_TICKET_GEN- Revocation feature is not supported for redundant ERATION licenses. VLS_REVOKE_ERR_CODGEN_ Revocation feature is not supported for the given VERSION_UNSUPPORTED license version. VLS_REVOKE_ERR_RDNT_LIC_ UNSUPPORED VLS_REVOKE_ERR_CAPACITY_ LIC_UNSUPPORED Revocation feature is not supported for capacity licenses.

A.1. Licensing Library Error and Result Codes

501

Error # 123 124 125 126 127

Error/Status Codes

Description

VLS_REVOKE_ERR_ Failure occurred due to unexpected challenge UNEXPECTED_AUTH_CHLG_PKT packet received from server. VLS_REVOKE_ERR_TRIAL_LIC_ UNSUPPORED VLS_REQUIRED_LOCK_FIELDS_ NOT_FOUND VLS_NOT_ENOUGH_LOCK_ FIELDS VLS_REMOTE_CHECKOUT_ NOT_ALLOWED_FOR_PERPETUAL VLS_GRACE_LIC_INSTALL_FAIL VLS_NOT_SUPPORTED_IN_ NONET_MODE Revocation feature is not supported for trial licenses. Required locking criteria for local request is not available on your machine. Minimum number of locking criteria for local request is not found. Remote checkout is not available for a repository license. This feature cannot run as installation of grace license is failed. The feature is not supported in no-net (stand-alone) mode.

128 129

The VLS_NOT_SUPPORTED_IN_NONET_ LIBRARY error code has been deprecated. Use VLS_NOT_SUPPORTED_IN_NONET_MODE instead.

130 131 132 133 139 140 141 142 143 147 148

VLS_NO_ACTIVE_HANDLE

No active client handle exists.

VLS_LIBRARY_NOT_INITIALIZED The licensing library is not initialized. To initialize, call VLSinitialize. VLS_LIBRARY_ALREADY_INITIAL- The licensing library is already in initialized state. IZED VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receiving this error, retry calling this API. VLS_NO_MORE_LICENSES VLS_NO_SUCH_LICENSE VLS_LICENSE_IN_USE VLS_SET_LICENSE_PRECEDENCE_FAILED VLS_STORE_ACCESS_ERROR VLS_LOCK_SELECTOR_INVALID VLS_LOCK_CODE_NOT_SUPPORTED No more licenses. No license found with the specified feature/version/hash. Specified feature/license has active client(s). Failure in setting precedence for specified trial license. Failure in accessing the license file. The specified lock selector is not valid. The specified lock code is not supported by the library/server.

502

Appendix A: Status Codes

Error # 149 150 151 152 153 154 155 156 165 184 188 210 211

Error/Status Codes

Description

VLS_LOCK_CODE_VER_INVALID Invalid lock code version. VLS_LOCK_CODE_INVALID The specified lock code is invalid. VLS_NO_AVAILABLE_MACHINE_ No available machine id for specified lock selector. ID VLS_CODE_GENERATOR_ LIBRARY_FAILED Failure in initializing code generator library.

VLS_TRIAL_LIC_DATA_ACCESS_ The specified trial feature is not accessible. ERROR VLS_TRIAL_LIC_DATA_INCONSISTENT VLS_TRIAL_LIC_DATE_ RESTRICTED VLS_TRIAL_LIC_NOT_ACTIVATED VLS_NONET_LIBRARY VLS_NON_TRIAL_LICENSE VLS_LICENSE_START_DATE_ NOT_REACHED VLS_GRACE_CODE_LENGTH_ OVERFLOW_ERROR VLS_ERROR_NO_MORE_FINGERPRINT_VALUE Trial License data inconsistent for this feature. Trial license date restriction error for this feature. The trial licensing for this feature is disabled. A network request is made to the standalone library. Active feature on the server is not a trial license. License start date not yet reached. Grace code length exceeds maximum limit. No more fingerprint information is available.

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 # 213

Error/Status Codes VLS_LICENSE_DELETION_NOT_ ALLOWED

Description License deletion is not supported for the following licenses:

n

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)

214

VLS_CAPACITY_MISMATCH

The capacity value does not match, or an operation related to capacity licensing is requested for a noncapacity license (or vice-versa).

215 216 217

VLS_EXPIRED_COMMUTER_ CODE

Error installing the commuter code, as the code is expired. VLS_COMMUTER_CODE_DATE_ Commuter code start date not yet reached. RESTRICTED 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. No records for the limit in the database. The requested operation failed for any other reason.

218 219 220

VLS_NO_RECORDS_FOUND VLS_OPERATION_NOT_SUCCESSFUL

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. VLS_CHECKOUT_NOT_ ALLOWED_FROM_NONPRIMARY_LEADER VLS_REHOST_LIC_VERSION_ NOT_SUPPORTED An attempt is made to check out an authorization from a non-primary server. The stand-alone revocation feature is supported 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_SUPPORTED as status in the revocation ticket. The usage log file is tampered. One or more records are either modified or missing from the usage log file. The matching record is not found in the usage log file.

221

222

223

VLS_USAGE_FILE_TAMPERED

224

VLS_NO_MATCH_FOUND

504

Appendix A: Status Codes

Error # 225

Error/Status Codes VLS_INVALID_TCPIP_VERSION

Description TCP\IP protocol version specified for licensing library is incorrect. Verify if the client and server protocols are incompatible. The license server is being run on a virtual machine. The system initialization failed for a grace license.

226 227 228 229

VLS_VIRTUAL_MACHINE_IS_ DETECTED VLS_GRACE_LIC_TIME_ TAMPER_INIT_FAIL

VLS_REVOKE_LIC_DATA_INCON- The license persistence data is either corrupt or does SISTENT not exist. VLS_TOO_MANY_OPERATIONS_ The permission ticket size is more than the length IN_SINGLE_PT supported 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. Contact Technical Support for more troubleshooting. VLS_PT_ALREADY_EXECUTED_ FOR_THIS_OPERATION VLS_PT_VENDOR_ID_MISMATCH VLS_REVOKE_EXPIRED_LIC_ FOUND VLS_COMMUTER_CHECKOUT_ NOT_ALLOWED The permission ticket operation already executed on the license server. Vendor ID mismatch. The permission ticket cannot be used for revoking licenses of other vendors. An expired license can neither be added nor revoked. The commuter token checkout not allowed for this feature.

230 231 232 233

A.2. License Generation Error Codes

505

A.2. License Generation Error Codes

The following table lists the RMS license code generation return codes and their default messages:

Error Return Code #

0 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 VLScg_SUCCESS VLScg_NO_FEATURE_NAME VLScg_INVALID_INT_TYPE VLScg_EXCEEDS_MAX_VALUE VLScg_LESS_THAN_MIN_VALUE VLScg_EXCEEDS_MAX_STRLEN VLScg_NOT_MULTIPLE VLScg_INVALID_DEATH_YEAR VLScg_INVALID_BIRTH_YEAR VLScg_INVALID_DATE VLScg_INVALID_HEX_TYPE VLScg_INVALID_IP_TYPE VLScg_INVALID_YEAR VLScg_RESERV_STR_ERR VLScg_INVALID_RANGE VLScg_INVALID_CHARS VLScg_SHORT_STRING VLScg_PREMATURE_TERM VLScg_REMAP_DEFAULT VLScg_DECRYPT_FAIL VLScg_DYNAMIC_DECRYPT_FAILURE VLScg_INVALID_CHKSUM VLScg_FIXED_STR_ERROR VLScg_SECRET_DECRYPT_FAILURE VLScg_SIMPLE_ERROR

Default Message
Success Feature Name must be specified. It cannot be empty. Expected an integer value, found XXX Value entered is greater than the maximum supported value. Value entered is less than the minimum supported value. Length of <value> is greater than <value>. Value should be a multiple of XXX. Expiration date cannot be less than XXX. Start year cannot be less than XXX. Date is not valid. Wrong value entered. (Should be hexadecimal) Wrong value entered. IP address should be specified in dot form. Invalid year entered. The string is a reserved string. Value violates the valid range of input. Invalid characters. License string \<value>\ too small to parse. Premature termination of license code. Please check. Failed to remap default strings from configuration file for license \<value>\. Decryption failed for license code. Decryption failed for dynamically added license code. Checksum validation failed for license code. Please verify the license code. Default fixed string error. Decryption failed for secrets. Verify the configuration file for readable licenses. Error in license code. Please check.

506

Appendix A: Status Codes

Error Return Code #

26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 VLScg_MALLOC_FAILURE VLScg_INTERNAL_ERROR VLScg_UNKNOWN_LOCK VLScg_VALUE_LARGE VLScg_INVALID_INPUT VLScg_MAX_LIMIT_ CROSSED VLScg_NO_RESOURCES VLScg_BAD_HANDLE VLScg_FAIL VLScg_INVALID_VENDOR_CODE VLScg_VENDOR_ENCRYPTION_FAIL VLScg_INVALID_EXP_DATE VLScg_INVALID_EXP_YEAR VLScg_INVALID_EXP_MONTH VLScg_LICMETER_EXCEPTION VLScg_LICMETER_DECREMENT_OK

Default Message
Out of heap memory. Internal error. Unknown lock mechanism. Value: <value> too large Invalid input. Maximum limit crossed. No resources left. Bad file handle. Operation failed. Invalid Vendor Code. Please contact your Sentinel RMS Development Kit distributor. Vendor-customized encryption failed. License Expiration Date must be greater than Start Date. License Expiration Year must be greater than Start Year. License Expiration Month must be greater than Start Month. Unknown exception in accessing Sentinel RMS license meter(s). Your license meter(s) have been decremented by <value> units. You now have <value> units left out of an initial count of <value> units. 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.

42

VLScg_LICMETER_ACCESS_ERROR

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. VLScg_LICMETER_CORRUPT VLScg_LICMETER_VERSION_MISMATCH VLScg_LICMETER_EMPTY Your Sentinel RMS license meter(s) are corrupted. Your Sentinel RMS Development Kit license meter has an invalid version. All <value> units of your Sentinel RMS Development Kit license meter(s) have been used up. License generation will fail.

44 45 46

A.2. License Generation Error Codes

507

Error Return Code #

47 48 49 VLScg_PORTSERV_ EXCEPTION VLScg_PORTSERV_ ACCESS_ERROR VLScg_PORTSERV_VERSION_MISMATCH VLScg_PORTSERV_CORRUPT VLScg_EXPIRED_LICENSE VLScg_INVALID_LICTYPE VLScg_INVALID_TRIALDAYS VLScg_INVALID_TRIAL_COUNT VLScg_TRIALMETER_EMPTY

Default Message
Unknown exception (<value>) in accessing Sentinel RMS Development Kit portable server(s). Error accessing Sentinel RMS portable server(s). Please make sure one is attached. Your Sentinel RMS license server has an invalid version (<value>.<value>) for commuter licenses. Expected <value>.<value>. Your Sentinel RMS Development Kit portable server(s) are corrupted. Your software license has expired. Invalid License Type. Invalid Trial Days. Invalid Trial License Count. All <value> units of your Sentinel RMS Development Kit Trial license meter(s) have been used up. Your trial license meter(s) have been decremented by <value> units. You now have <value> units left. Your Sentinel RMS Development Kit license meter(s) have No authorization to generate Network Licenses. No feature is enabled. Error in updating locale. Invalid number of servers.

50 51 52 53 54 55

56

VLScg_TRIAL_SUCCESS

57

VLScg_NO_NETWORK_AUTHORIZATION VLScg_NO_ENABLE_FEATURE VLScg_VI18N_INITIALIZE_FAIL VLScg_INVALID_NUM_SERVERS

58 59 60 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. Your license meter is not supported. The base feature is too high for supporting desired number of multi-features. License code encryption failed. Invalid capacity setting done in code structure. License expiration date is set before the license start date. Invalid trial elapsed hours. Process lock request failed.

70 71 72 73 74 75 77

VLScg_LICMETER_NOT_SUPPORTED VLScg_INCORRECT_BASE_FEATURE_ VAL VLScg_ENCRYPTION_FAIL VLScg_INVALID_CAPACITY_SETTINGS VLScg_EXP_DATE_BEFORE_START_ DATE VLScg_INVALID_TRIALHOURS VLScg_GETLOCK_FAIL

508

Appendix A: Status Codes

Error Return Code #

78 79 80 VLScg_GETLOCK_TIMEOUT VLScg_VENDOR_DECRYPTION_FAIL VLScg_RT_VERSION_MISMATCH

Default Message
Process lock request timeout. Vendor decryption failed. Version value found in the revocation ticket does not match with that specified in request structure. One or more operation-specific information in the revocation ticket is invalid. The transaction ID value found in the revocation ticket does not match with that specified in request structure. The lock code value found in the revocation ticket does not match with that specified in the request structure.

81 82

VLScg_RT_REHOST_LINE_CORRUPT VLScg_RT_TRANSACTION_ID_MISMATCH VLScg_RT_LOCK_CODE_MISMATCH

83

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. 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. VLScg_RT_ACTION_STATUS_NOT_SUC- The requested operation is not successfully perCESS formed at the client-end. VLScg_RT_REQUEST_EMPTY VLScg_RT_REQUEST_LINE_INVALID VLScg_RT_REHOST_TICKET_INVALID_ TLV_STRUCT VLScg_RT_REHOST_TAG_MISSING VLScg_RT_VERSION_TAG_MISSING VLScg_RT_TRANSACTION_ID_TAG_ MISSING The request struture does not specify any operation. The request structure specified an invalid operation. The revocation ticket is invalid. The rehost tag is not found in the revocation ticket. The version tag is not found in the revocation ticket. The transaction ID tag is not found in the revocation ticket.

85

86 87 88 89 90 91 92 93 94

VLScg_RT_LOCK_SELECTOR_TAG_MISS- The lock selector tag is not found in the revING ocation ticket. 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

509

Error Return Code #

95 96 97 98

Default Message

VLScg_RT_LOCK_CODE_TAG_MISSING The lock code tag is not found in the revocation ticket. VLScg_RT_REHOST_LINE_TAG_MISSING VLScg_RT_HASH_TAG_MISSING VLScg_RT_TIME_STAMP_MISMATCH The rehost line tag is not found in the revocation ticket. The hash tag is not found in the revocation ticket. The time stamp value found in the revocation ticket does not match with that specified in the request structure. The time stamp tag is not found in the revocation ticket. The revocation ticket reported a single error. The buffer is too small. A parameters-related error is encountered.

99 100 101 102 103 104 105 106 107 108 109

VLScg_RT_TIME_STAMP_TAG_MISSING VLScg_RT_VERIFY_SINGLE_ERROR VLScg_RT_BUFFER_TOO_SMALL VLScg_RT_PARAMETERS_ERROR

VLScg_RT_VERIFY_MULTIPLE_ERRORS The revocation ticket reported multiple errors.

VLScg_RT_ALLOCATE_MEMORY_FAIL- A memory allocation failure. URE VLScg_RT_UNSUPPORTED_OPERATION_TYPE VLScg_RT_INVALID_REQUEST_DATA VLScg_RT_TAG_NOT_FOUND VLScg_BUFFER_TOO_SMALL The operation type is not supported. An invalid rehost request data. The tag cannot be found in TLV. The buffer is too small.

VLScg_RT_INSUFFICIENT_TOKENS_TO_ The license tokens available for revocation are REVOKE less than the number specified in the permission ticket. VLScg_RT_MIXED_OPERATION_TYPE_ You cannot revoke stand-alone and network UNSUPPORTED licenses using a single permission ticket. VLScg_RT_INFINITE_LIC_FINITE_REQ VLScg_RT_RDNT_LIC_UNSUPPORED VLScg_RT_CORRUPT_ORIG_REQ Network licenses with infinite tokens cannot be partially revoked. Full revocation is required. The permission ticket cannot be generated for redundant licenses. The permission ticket provided for verification is corrupt.

110 111 112 113 114 115

VLScg_RT_CUSTOM_DATA_TAG_MISS- The custom defined data tag is not found in the ING 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

116

510

Appendix A: Status Codes

Error Return Code #

Default Message
verify 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. Vendor ID mismatch. The permission ticket cannot be generated for licenses of other vendors. The permission ticket generation not supported for licenses earlier than version 11. The reserved characters are used. See About Reserved Characters and Strings. The string length is lower than the minimum allowed.

118 119 130 131

VLScg_VENDOR_ID_MISMATCH VLScg_CODGEN_VERSION_UNSUPPORTED VLScg_RESERV_CHAR_ERR VLScg_LOWER_THAN_MIN_STRLEN

A.3. Upgrade License Error Codes

511

A.3. Upgrade License Error Codes

The following table lists upgrade license code generation return codes and their default messages:

Error# Return Code

0 2 3 4 5 6 7 11 14 16 20 22 26 27 30 31 32 33 34 35 36 40 41 VLScg_SUCCESS VLSucg_NO_FEATURE_NAME VLSucg_INVALID_INT_TYPE VLSucg_EXCEEDS_MAX_ VALUE VLSucg_LESS_THAN_MIN_ VALUE VLSucg_EXCEEDS_MAX_ STRLEN VLSucg_NOT_MULTIPLE VLSucg_INVALID_HEX_TYPE VLSucg_RESERV_STR_ERROR VLSucg_INVALID_CHARS VLSucg_DECRYPT_FAIL VLSucg_INVALID_CHKSUM VLSucg_MALLOC_FAILURE VLSucg_INTERNAL_ERROR VLSucg_INVALID_INPUT VLSucg_MAX_LIMIT_ CROSSED VLSucg_NO_RESOURCES VLSucg_BAD_HANDLE VLSucg_FAIL VLSucg_INVALID_VENDOR_ CODE VLSucg_VENDOR_ENCRYPTION_FAIL VLSucg_LICMETER_EXCEPTION VLSucg_LICMETER_DECREMENT_OK VLSucg_LICMETER_ACCESS_ ERROR

Default Message
Success Feature Name must be specified. It cannot be empty. Expected an integer value, found XXX Value entered is greater than the maximum supported value. Value entered is less than the minimum supported value. Length of <value> is greater than <value>. Value should be a multiple of XXX. Wrong value entered. (Should be hexadecimal) <Value> is a reserved string. Invalid characters. Decryption failed for license code. Checksum validation failed for license code. Please verify the license code. Out of heap memory. Internal error. Invalid input. Maximum limit crossed. No resources left. Bad file handle. Operation failed. Invalid Vendor Code. Please contact your Sentinel RMS Development Kit distributor. Vendor-customized encryption failed. Unknown exception in accessing Sentinel RMS Development Kit license meter(s). Your license meter(s) have been decremented by <value> units. You now have <value> units left out of an initial count of <value> units. Error in accessing the license meter(s). Please

42

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 45 46 52 59 61 62 63 64 65 66 67

VLSucg_LICMETER_CORRUPT Your license meter(s) are corrupted. VLSucg_LICMETER_VERSION_ Your license meter has an invalid version. MISMATCH VLSucg_LICMETER_EMPTY VLSucg_INVALID_LICTYPE VLSucg_VI18N_INITIALIZE_ FAIL VLSucg_NO_CAPACITY_ AUTHORIZATION VLSucg_NO_UPGRADE_ AUTHORIZATION All <value> units of your license meter(s) have been used up. License generation will fail. Invalid License Type. Error in updating locale. Your license meter(s) have no authorization to generate Capacity Licenses. Your license meter(s) have no authorization to generate Upgrade Licenses.

VLSucg_NO_UPGRADE_CODE Upgrade Code must be specified. It cannot be empty. VLSucg_INVALID_BASE_LIC_ INFO The information-feature name, version and vendor code, provided for base license is incorrect.

VLSucg_CAPACITY_UPD_NOT_ Capacity upgrade is not allowed, as the base lic is a ALLOWED non-capacity license. VLSucg_INVALID_UPGRADE_ CODE VLSucg_LICMETER_ COUNTER_TOOLOW Invalid upgrade code. 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 supported. PORTED

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 0x10000000 Status Code Description First Level Status Codes ERR_TIME_ TAMPER_INIT_ FAIL Time Tamper Initialization Failure

0x20000000 0x40000000 0x80000000 0xF0000000 0x01000000

ERR_COMMUTER_ Commuter Initialization Failure PRS_INIT_FAIL ERR_GRACE_PRS_ Grace License Initialization FailINIT_FAIL ure ERR_TRIAL_INIT_ FAIL ERR_STDRVK_ INIT_FAIL ERR_CONSUME_ INIT_FAIL ERR_KEY_INFO_ SUCCESS ERR_INVALID_ INPUT ERR_INIT_INFO_ EXISTS ERR_INIT_SEC_ FAIL ERR_INIT_KEY_ FAIL ERR_INIT_KEY_ SEC_FAIL ERR_INIT_OPEN_ KEY_FAIL ERR_INIT_SET_ Trial License Initialization Failure Standalone Revocation Initialization Failure VTL Initialization Failure

Second Level Status Codes 0x00000000 0x00000001 0x00000002 0x00000008 0x00000010 0x00000020 0x00000040 0x00000080 0x00000100 Success Invalid Input

ERR_INIT_LIB_FAIL Library Initialization Failure Already Initialized Permissions failure on secure information Failed to create registry information (only for Windows) Permission failure for secure registry (only for Windows) Registry open failure (only for Windows) Write failure on secure registry

514

Appendix A: Status Codes

Hexadecimal Code 0x00000200 0x00000400 0x00000800 0x00001000 0x00002000 0x00004000 0x00008000 0x00010000 0x00020000

Status Code VALUE_FAIL

Description (only for Windows)

ERR_INIT_QUERY_ Read failure on secure registry FAIL (only for Windows) ERR_INIT_FILE_ FAIL ERR_INIT_FILE_ OPEN_FAIL ERR_INIT_FILE_ WRITE_FAIL ERR_INIT_FILE_ SEC_FAIL ERR_EXCEPTION_ OCCURED ERR_INIT_FILE_ INFO_EXISTS ERR_INTERNAL_ FAIL ERR_INSUFFICIENT_PERMISIONS ERR_TAMPER_ DETECTED ERR_INIT_PATH_ FAILED ERR_INIT_FILE_ READ_FAIL ERR_NORESOURCES ERR_INIT_CONFIG_FAIL File creation failure File open failure Write failure on secure file Permissions failure on secure file An exception occurred during execution Initialization file information exits Internal error Access denied for read or write secure data Secure data is tampered Error retrieving persistence database location Error encountered in reading persistence file(s) Failure in obtaining system resources Error encountered in setting trial persistence file location

0x00040000 0x00080000 0x00100000 0x00200000 0x00400000 0x00800000

ERR_LOCK_ERROR Resource lock failure

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 0xC8010002 0xC8010003 0xC8010004 0xC8010005 0xC8010006 0xC8010007 0xC8010008 0xC8010010 Status Code VLScl_ILLEGAL_VENDOR_ID VLScl_INSUFFICIENT_PERMISIONS VLScl_INVALID_ARGUMENTS VLScl_NO_TRIAL_FEATURE_IN_USE

Description
The library does not have a valid serial number information. If the application calling the API is run in non administrator user mode. If a wrong value or combination of arguments is passed. If the trial information of the given feature-version is not found.

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. VLScl_NO_REVOKE_INFORMATION_ FOUND VLScl_NORESOURCES VLScl_RESOURCE_LOCK_FAILURE The revocation information of the given feature-version is not found. A memory related error (malloc, etc.) has occurred. Failed to acquire an API lock. The API should be recalled on receiving this error. An internal error. 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).

0xC8010009 0xC8010011

VLScl_INTERNAL_ERROR VLScl_NO_COMMUTER_INFO_FOUND

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 (username 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 register 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: Register hook functions (if any) */ /* TODO: Register custom host ID function (if any) */ /* TODO: Register 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 informationa 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. Returns non-zero on failure. Description An OUT parameter. A pointer to string of up to 50 characters to write to license server as identification.

Parameter vendorInfo

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

523

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

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

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 registered 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 lslic 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.

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, remember 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 Post-request Pre-release 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

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 Register Callback Function)

LSERV_STATUS VLSeventAddHook ( int eventName, int (*handlerFuncPtr)(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 eventName

Description An IN parameter. Specifies the type of event:

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.

handlerFuncPtr identifier

An IN parameter. The callback function for specified event. 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. Returns LSERV_STATUS_DENY on failure. Description A pointer to VLShandletStruct containing client information, feature information, various file information and miscellaneous information. The null-terminated string containing the input message. A pointer to buffer that receives the output message. The size of the buffer pointer by outBufSz.

Parameter pHandlerStruct inBuf outBuf 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

527

3. Register 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; }

Register 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, &amp;GetCustomExValue, "Hook1"); return LSERV_STATUS_SUCCESS; }

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

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 The method of time tampering detection The default grace period 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

529

typedef enum { VLS_ENABLE_DEFAULT_TM_TAMPER, VLS_DISABLE_DEFAULT_TM_TAMPER }VLStmTamperMethod; Parameter actionOnTmTamper Description 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] 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] 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)] 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. Pass 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] 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.

tmTamperMethod

gracePeriod

percentViolations

numViolationsForError

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. Returns non-zero if the clock is found in tampered state.

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

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 lsdecode.exe 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. Returns non-zero on failure. Description An IN parameter. The original license code. An OUT parameter. The encrypted license code. An IN parameter.

Parameter
decrypted_mesg encrypted_mesg size

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 \t \n # ( ) , Hex Value 0x09 0x0A 0x23 0x28 0x29 0x2C 0x2D Description The tab character The new-line character The pound sign or number sign or hash mark The opening round parentheses The closing round parentheses The comma mark 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. Returns non-zero on failure. Description An IN parameter. The encrypted license code. An OUT parameter. The original license code. An IN parameter. The size of the decrypted_mesg buffer.

Parameter
encrypted_mesg
decrypted_mesg

size

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

533

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

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

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 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. Returns non-zero on failure. Description An IN parameter. The original upgrade license code. An OUT parameter. The encrypted upgrade license code. An IN parameter. The size of the encrypted_mesg buffer.

Parameter
decrypted_mesg encrypted_mesg size

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. Returns non-zero on failure. Description An IN parameter. The encrypted upgrade license code. An OUT parameter. The original upgrade license code. An IN parameter. The size of the decrypted_mesg buffer.

Parameter encrypted_mesg decrypted_mesg size

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). 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. Returns non-zero on failure. Description An IN parameter. The original network message. An OUT parameter. The encrypted network message. An IN parameter. The size of the encrypted_mesg buffer.

Parameter
decrypted_mesg encrypted_mesg size

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. Returns non-zero on failure. Description An IN parameter. The encrypted network message. An OUT parameter. The original network message. An IN parameter. The size of the decrypted_mesg buffer.

Parameter encrypted_mesg decrypted_mesg size

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

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. echoid.exe 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 registered 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. Register the custom host ID function on the server. 4. Register 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 <installdir>\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 <installdir>\MsvcDev\Samples\API\ wechoiddlg.cpp. 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; }

Register the Custom Host ID Function on the License Server

VLSsetHostIdFunc is used to register 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(&amp;GetCustomValue); return LSERV_STATUS_SUCCESS; }

Register 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(&amp;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

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. echoid.exe 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 registered 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
pCustomExTable

Description An OUT parameter. A pointer to the array of the VLScustomEx structure. If passed as NULL, then as an output pulCount will contain the required number of elements in array pointed by this parameter. An IN/OUT parameter. A pointer to unsigned long that specifies the number of elements in the

pulCount

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. 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. Register the extended custom lock function on the license server. 4. Register 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 <installdir>\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 <installdir>\MsvcDev\Samples\API\ wechoiddlg.cpp. 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 &gt; 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; }

Register the Extended Custom Lock Function on the License Server

VLSsetCustomExFunc is used to register 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(&amp;GetCustomExValue); return LSERV_STATUS_SUCCESS; }

Register 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(&amp;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. 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

545

B.12.5. Returns
n

Returns LS_SUCCESS(0) on success. Returns non-zero on failure. Description An IN parameter. The type of license file (lservrc, lservrccnf, or ULSERVRC) or configuration file you are going to provide a customized location/name. An IN parameter. The custom name that you want to use. Reserved, Use NULL for this value. Reserved, Use NULL for this value.

Parameter filetype

fileName unused1 unused2

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:\\users\\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; }

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 fingerprintssuch as IP address, disk ID, host name, Ethernet address, computer ID key, and hard disk serial numberwere 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:

Locking Option
n n n n n n n n

Default Fingerprint Caching (ON\OFF)

ON

Caching Customization Option Provided?

No. You cannot disallow the default caching setting.

IP address Disk ID Host name Ethernet address Computer ID key Hard disk serial number ID PROM Processor ID

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. No. You can implement your own caching mechanism as described in the custexlock sample (available at: <installdir>\Samples\Customize components for Windows)

Extended Custom

OFF

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

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. When the configuration file is set, but does not exist. When the configuration file exists, but the required section is not present. 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 informationusername and hostnameusing a new client side API VLSsetCustomData. This information is passed 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 user and host name fields of the log file) Query APIs (VLSgetClientInfo and VLSgetHandleInfo) WlmAdmin 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 informationusername and hostname. It takes a pointer to the structure VLScustomData. To set the custom user 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 user 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 username or hostname based on the sharedID value.

B.14. Setting Custom Client Information

549

B.14.3. Parameters
Parameter VLScustomData Description An IN parameter. Before passing 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 username[VLS_CUSTOM_DATA_FIELD_SIZE + 1]; char hostname[VLS_CUSTOM_DATA_FIELD_SIZE + 1]; } VLScustomData;
n n

The custom user 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 username 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 passed in the VLSsetCustomData API without initializing the structSz field. n Either username or hostname (fields of the VLScsutomData structure) is initialized with empty values and passed 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 <installdir>\English\MsvcDev\Samples\Customize components>, is used for building the following customized executables:
n

lservnt.exe - The license server. lscgen.exe - The command-line license code generator. lsdecode.exe - The command-line license code decoder. ulscgen.exe - The command-line license upgrade code generator. ulsdcod.exe - The command-line license upgrade code decoder. echoid.exe - The command-line utility to obtain the system fingerprint. wechoid.exe - A Windows-based graphical utility to obtain the system fingerprint. wlscgen.dll - A vendor-specified extra layer of encryption the plug-in for wlscgen.exe.

The default location of wlscgen.exe is <installDir>\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 VENDOR_INFO_OBJS CHANGE_PORT_OBJS SERVER_HOOK_OBJS TIME_TAMPER_OBJS ENCRYPT_LIC_OBJS DECRYPT_LIC_OBJS ENCRYPT_UPG_LIC_OBJS DECRYPT_UPG_LIC_OBJS ENCRYPT_MSG_OBJS DECRYPT_MSG_OBJS

B.15. Build Procedure

551

CUSTOM_LOCK_OBJS CUSTOM_EX_LOCK_OBJS

The following tables depicts the relationship between the above-mentioned defines and the executables: Defines in custom32.mak SRV_VENDOR_INIT_OBJS VENDOR_INFO_OBJS CHANGE_PORT_OBJS SERVER_HOOK_OBJS TIME_TAMPER_OBJS ENCRYPT_LIC_OBJS DECRYPT_LIC_OBJS Network
lservnt.exe lservnt.exe
n n

Stand-alone The client application NA NA The client application The client application
n n n n

lservnt.exe Client application

lservnt.exe lservnt.exe
n n n n

lservnt.exe lscgen.exe lsdecode.exe wlscgen.dll

Client Application lscgen.exe lsdecode.exe wlscgen.dll

ENCRYPT_UPG_LIC_OBJS DECRYPT_UPG_LIC_OBJS ENCRYPT_MSG_OBJS DECRYPT_ MSG_OBJS CUSTOM_LOCK_OBJS

n n n n n 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 NA

n n n

Client Application ulscgen.exe ulsdcod.exe

n n n

Client Application echoid.exe wechoid.exe Client Application echoid.exe wechoid.exe

CUSTOM_EX_LOCK_OBJS

n n n n

n n n

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: <nmake -f custom32.mak _V_STANDALONE=1 all> If you want to build the samples provided with RMS, use the following command: <nmake -f custom32.mak _V_SAMPLE_BUILD_=1 _V_STANDALONE_=1 all>

552

Appendix B: Customization Features

B.15.3. Network Licensing

Use the following command on the command prompt: <nmake -f custom32.mak all> If you want to build the samples provided with RMS, use the following command: <nmake -f custom32.mak _V_SAMPLE_BUILD_=1 all> 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: <nmake -f custom32.mak 'utility name'> For example, if you want to build only echoid.exe, then use the following command: <nmake -f custom32.mak echoid.exe>

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. Communication over a vendor-specified license server port. Vendor specified 4-byte custom fingerprint of a system. 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

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

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

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 6 76 123 139 246 320 165 15 9

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

I
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

M
machine names, retrieving 123

P
persistence data initializing port numbers retrieving printing errors 480, 482 37 327-328

K
key time left information retrieving 121

R
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

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 locating licenses local vs. remote renewal of releasing requesting 307 123 75 15, 23 9, 19

Index

555

version information revocation

114, 117 156, 457

T
time-out intervals retrieving setting time drift information retrieving tracing client-library calls 60 59 118 169

S
Sentinel RMS APIs capacity license client commuter license license code generation license queuing redundancy upgrade license servers retrieving host names retrieving port numbers setting 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 219 1 175 307 237 189 261 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

557

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 VLSgetContactServer 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 VLSsetContactServer VLSsetCustomExFunc VLSsetGraceRequestFlag VLSsetHoldTime VLSsetLicensePrecedence VLSsetRemoteRenewalTime VLSsetServerLogState VLSsetServerPort VLSsetSharedId VLSsetSharedIdValue VLSsetTeamId

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 VLSsetUserErrorFile 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 VLSverifyRevocationTicket 461, 463 VM detection 72, 443-444