manual sentinel rms

Document Revision History

Part Number 007-002737-002, Revision L

Software versions 8.5.0 and later.

Revision Action/Change Date

A Updated for the 8.2.0Windows release May 2008

B Updated for the 8.2.1Windows 64-bit release Nov 2008

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

D Updated for the enhancements and problems correctedin the 8.2.3Windows (32-bit and 64-bit) release

July 2009

E Updated for the enhancements and problems correctedin the 8.3.0Windows (32-bit and 64-bit) release

October 2009

F Updated for the enhancements and problems correctedin the 8.4.0Windows (32-bit and 64-bit) release

May 2010

G Updated for the enhancements and problems correctedin the 8.4.1Windows (32-bit and 64-bit) release

Oct 2010

H Updated for the enhancements and problems correctedin the 8.4.1 Linux (32-bit and 64-bit) release

Mar 2011

J Updated for the enhancements and problems correctedin the 8.4.1Macintosh (32-bit and 64-bit) release

May 2011

L Updated for the enhancements and problems correctedin the 8.5.0Windows (32-bit and 64-bit) release

July 2011

Disclaimer and Copyrights

Copyright © 2011, SafeNet, Inc. All rights reserved.

http://www.safenet-inc.com/

We have attempted to make these documents complete, accurate, and useful, but we cannot guar-antee them to be perfect. When we discover errors or omissions, or they are brought to our atten-tion, we endeavor to correct them in succeeding releases of the product. SafeNet® and Sentinel® areregistered trademarks of SafeNet, Inc. All other product names referenced herein are trademarks orregistered trademarks of their respectivemanufacturers.

Third Party Software Acknowledgements

Sentinel RMS Linux SDK makes use of the DMI Decode utility, a free software. You can redistribute itand/or modify it under the terms of the GNUGeneral Public License as published by the Free SoftwareFoundation.



http://www.gnu.org/licenses/gpl.html




Contents

Chapter 1: Sentinel RMS Licensing Library API 1

The Quick Client Licensing Functions 2

1.1. VLSlicense 3

1.2. VLSdisableLicense 6

The Standard Client Licensing Functions 7

1.3. VLSinitialize 8

1.4. LSRequest 9

1.5. LSUpdate 12

1.6. LSRelease 15

1.7. VLScleanup 17

The Advanced Client Licensing Functions 18

1.8. VLSrequestExt 19

1.9. VLSrequestExt2 22

1.10. VLSreleaseExt 23

1.11. VLSbatchUpdate 25

1.12. Challenge-responseMechanism 28

The Client Configuration Functions 30

1.13. VLSsetContactServer 32

1.14. VLSgetContactServer 35

1.15. VLSsetServerPort 36

1.16. VLSgetServerPort 37

1.17. VLSinitMachineID 38

1.18. VLSgetMachineID 40

1.19. VLSgetMachineIDOld 41

1.20. VLSgetNumberedMachineID 42

1.21. VLSgetNumberedMachineIDExt 45

1.22. VLSmachineIDtoLockCode 47

1.23. VLSmachineIDToLockCodeEx 48

1.24. VLSgetServerNameFromHandle 50

1.25. VLSinitServerList 51

1.26. VLSgetServerList 52

1.27. VLSinitServerInfo 53

1.28. VLSsetHostIdFunc 54

1.29. VLSsetCustomExFunc 55

1.30. VLSsetBroadcastInterval 57

1.31. VLSgetBroadcastInterval 58

iv Sentinel RMS SDK API Reference Guide

1.32. VLSsetTimeoutInterval 59

1.33. VLSgetTimeoutInterval 60

1.34. VLSsetHoldTime 61

1.35. VLScontrolRemoteSession 62

1.36. VLSsetSharedId/ VLSsetTeamId 63

1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue 65

1.38. VLSsetGraceRequestFlag 67

1.39. VLSgetGraceRequestFlag 69

1.40. VLScalculateLicenseHash 70

1.41. VLSisVirtualMachine 72

Local vs. Remote Renewal of License Tokens 74

1.42. VLSdisableLocalRenewal 75

1.43. VLSenableLocalRenewal 76

1.44. VLSisLocalRenewalDisabled 77

1.45. VLSgetRenewalStatus 78

1.46. VLSsetRemoteRenewalTime 80

1.47. VLSdisableAutoTimer 81

The Client Query Functions 82

1.48. VLSlicenseInfo (license_info_struct) 83

1.49. VLSgetLicenseInfo 89

1.50. VLSgetLicenseInfoExt 92

1.51. client_info_struct 95

1.52. VLSgetClientInfo 98

1.53. VLSgetHandleInfo 100

1.54. VLSgetActiveHandleList 101

1.55. VLSgetLastErrorStatusFromHandle 102

1.56. VLSgetLicInUseFromHandle 103

The Feature Query Functions 104

1.57. feature_info_struct (VLSfeatureInfo) 105

1.58. VLSgetFeatureInfo 112

1.59. VLSgetVersions 114

1.60. VLSgetFeatureFromHandle 116

1.61. VLSgetVersionFromHandle 117

1.62. VLSgetTimeDriftFromHandle 118

1.63. VLSgetFeatureTimeLeftFromHandle 119

1.64. VLSgetKeyTimeLeftFromHandle 121

The Client Utility Functions 122

1.65. VLSdiscover 123

1.66. VLSaddFeature 126

1.67. VLSaddFeatureToFile 128

v

1.68. VLSdeleteFeature 130

1.69. Syntax 131

1.70. VLSdeleteLicenseFromFile 133

1.71. VLSdeleteLicenseFromFileExt 136

1.72. VLSgetLibInfo 139

1.73. VLSshutDown 140

The Trial License Related Functions 142

1.74. VLStrialUsageInfo 143

1.75. VLSgetTrialUsageInfo 144

1.76. VLSsetLicensePrecedence 147

1.77. VLSgetTrialPeriodLeft 150

Getting the License Server Information 152

1.78. VLSservInfo Struct 153

1.79. VLStimeTamperInfo Struct 154

1.80. VLSgetServInfo 155

The License Revocation Functions 156

1.81. VLSrevokeByPermissionTicket 157

1.82. VLSrevokeLicense 160

Error Handling 163

1.83. VLSerrorHandle 164

1.84. LSGetMessage 165

1.85. VLSsetErrorHandler 166

1.86. VLSsetUserErrorFile 167

The Trace Licensing Operations 168

1.87. VLSsetTraceLevel 169

1.88. VLSsetUserTraceFile 170

1.89. VLSsetTraceHandler 172

Chapter 2: Commuter License API 175

2.1. VLScommuterInfo 176

2.2. VLSgetCommuterInfo 178

2.3. VLSgetAndInstallCommuterCode 179

2.4. VLSuninstallAndReturnCommuterCode 181

2.5. VLSgetMachineIDString 182

2.6. VLSgetCommuterCode 184

2.7. VLScleanExpiredCommuterCode 186

2.8. VLSinstallCommuterCode 187

Chapter 3: Redundancy API 189

vi Sentinel RMS SDK API Reference Guide



3.3. VLSaddServerToPool 195

3.4. VLSdelServerFromPool 197

3.5. VLSdiscoverExt 199

3.6. VLSgetDistbCrit 202

3.7. VLSgetDistbCritToFile 204

3.8. VLSgetLeaderServerName 206

3.9. VLSgetLicSharingServerList 208

3.10. VLSgetPoolServerList 210

3.11. VLSsetServerLogState 211

Chapter 4: Volume Transaction Licensing API 213

4.1. VLSgetConsumeLimit 214

4.2. VLSsetConsumeLimit 215

4.3. VLSgetContextData 217

4.4. VLSsetContextData 218

Chapter 5: Capacity License API 219


5.2. VLSgetFeatureInfoExt 225

5.3. VLSgetCapacityList 227

5.4. VLSgetClientInfoExt 229

5.5. VLSdeleteFeatureExt 231

5.6. VLSgetCapacityFromHandle 233

5.7. VLSsetTeamId 234

5.8. VLSsetTeamIdValue 235

Chapter 6: License Queuing API 237

6.1. The License Queuing Example Code 239

6.2. VLSqueuePreference Struct 240

6.3. VLSserverInfo Struct 241

6.4. VLSQueuedClientInfo Struct 242

6.5. VLSqueuedRequest and VLSqueuedRequestExt 244

6.6. VLSgetQueuedClientInfo 248

6.7. VLSremoveQueuedClient 250

6.8. VLSremoveQueue 252

6.9. VLSgetHandleStatus 254

vii

6.10. VLSupdateQueuedClient 255

6.11. VLSgetQueuedLicense 257

6.12. VLSinitQueuePreference 259

Chapter 7: Upgrade License API 261

The Upgrade License Code Generator API 262

7.1. ucodeT Struct 264

7.2. VLSucgInitialize 266

7.3. VLSucgCleanup 267

7.4. VLSucgReset 268

7.5. VLSucgGetNumErrors 269

7.6. VLSucgGetErrorLength 270

7.7. VLSucgGetErrorMessage 271

7.8. VLSucgPrintError 272

7.9. VLSucgAllowBaseFeatureName 273

7.10. VLSucgSetBaseFeatureName 274

7.11. VLSucgAllowBaseFeatureVersion 275

7.12. VLSucgSetBaseFeatureVersion 276

7.13. VLSucgAllowUpgradeCode 277

7.14. VLSucgSetUpgradeCode 278

7.15. VLSucgAllowUpgradeFlag 279

7.16. VLSucgSetUpgradeFlag 280

7.17. VLSucgAllowUpgradeVersion 282

7.18. VLSucgSetUpgradeVersion 283

7.19. VLSucgAllowUpgradeCapacity 284

7.20. VLSucgSetUpgradeCapacityUnits 285

7.21. VLSucgSetUpgradeCapacity 286

7.22. VLSucgGenerateLicense 288

7.23. VLSucgGetLicenseMeterUnits 290

7.24. VLSgenerateUpgradeLockCode 291

The Upgrade License Decode API 292

7.25. ulcCode Struct 293

7.26. VLSdecodeUpgradelockCode 294

7.27. VLSucgDecodeLicense 295

Chapter 8: Utility Functions 297

8.1. VLSscheduleEvent 298

8.2. VLSdisableEvents 299

8.3. VLSeventSleep 300

viii Sentinel RMS SDK API Reference Guide

Chapter 9: Usage Log Functions 301

9.1. VLSchangeUsageLogFileName 302

9.2. VLSgetUsageLogFileName 303

9.3. VLSUsageAuthenticate 304

9.4. VLSusageFileDecrypt 306

Chapter 10: License Code Generation API 307

10.1. The License Code Generation Functions 308

10.2. CodeT Struct 311

About Reserved Characters and Strings 317

The Basic Functions 318

10.3. VLScgInitialize 319

10.4. VLScgCleanup 320

10.5. VLScgReset 321

10.6. VLScgGetLibInfo 322

Functions Retrieving Errors 323

10.7. VLScgGetNumErrors 324

10.8. VLScgGetErrorLength 325

10.9. VLScgGetErrorMessage 326

10.10. VLScgPrintError 327

10.11. VLScgPrintErrorExt 328

The Functions for Setting the Fields in CodeT Struct 329

10.12. VLScgSetCodeLength 332

10.13. VLScgAllowFeatureName 333

10.14. VLScgSetFeatureName 334

10.15. VLScgAllowFeatureVersion 335

10.16. VLScgSetFeatureVersion 336

10.17. VLScgAllowLicenseType 337

10.18. VLScgSetLicenseType 338

10.19. VLScgAllowTrialLicFeature 339

10.20. VLScgSetTrialDaysCount 340

10.21. VLScgAllowTrialHours 341

10.22. VLScgSetTrialHours 342

10.23. VLScgAllowAdditive 343

10.24. VLScgAllowAggregateLicense 344

10.25. VLScgSetAdditive 345

10.26. VLScgAllowKeyLifetime 346

10.27. VLScgSetKeyLifetime 347

10.28. VLScgAllowStandAloneFlag 348

ix

10.29. VLScgAllowNetworkFlag 349

10.30. VLScgAllowPerpetualFlag 350

10.31. VLScgAllowRepositoryFlag 351

10.32. VLScgSetStandAloneFlag 352

10.33. VLScgAllowLogEncryptLevel 353

10.34. VLScgSetLogEncryptLevel 354

10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria 355

10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria 356

10.37. VLScgAllowShareLimit/ VLScgAllowTeamLimit 358

10.38. VLScgSetShareLimit and VLScgSetTeamLimit 359

10.39. VLScgAllowCommuterLicense 361

10.40. VLScgSetCommuterLicense 362

10.41. VLScgAllowCommuterMaxCheckoutDays 363

10.42. VLScgSetCommuterMaxCheckoutDays 364

10.43. VLScgAllowNumKeys 365

10.44. VLScgSetNumKeys 366

10.45. VLScgAllowLockModeQuery 367

10.46. VLScgSetClientServerLockMode 368

10.47. VLScgAllowRedundantFlag 369

10.48. VLScgSetRedundantFlag 370

10.49. VLScgAllowMajorityRuleFlag 371

10.50. VLScgSetMajorityRuleFlag 372

10.51. VLScgAllowMultipleServerInfo 373

10.52. VLScgSetNumServers 374

10.53. VLScgAllowServerLockInfo 375

10.54. VLScgSetServerLockInfo1 376

10.55. VLScgSetServerLockMechanism1 377



10.58. VLScgAllowLockMechanism 380

10.59. VLScgSetClientLockMechanism 381

10.60. VLScgAllowClientLockInfo 382

10.61. VLScgSetClientLockInfo 383

10.62. VLScgSetNumClients 384

10.63. VLScgAllowClockTamperFlag 385

10.64. VLScgSetClockTamperFlag 386

10.65. VLScgAllowOutLicType 387

10.66. VLScgSetOutLicType 388

10.67. VLScgSetLicType 389

10.68. VLScgAllowHeldLic 390

x Sentinel RMS SDK API Reference Guide

10.69. VLScgSetHoldingCrit 391

10.70. VLScgAllowCodegenVersion 392

10.71. VLScgSetCodegenVersion 393

10.72. VLScgAllowCapacityLic 394

10.73. VLScgSetCapacityFlag 395

10.74. VLScgAllowCapacity 396

10.75. VLScgSetCapacityUnits 397

10.76. VLScgSetCapacity 398

10.77. VLScgAllowMultiKey 399

10.78. VLScgSetKeyType 400

10.79. VLScgAllowSecrets 401

10.80. VLScgSetSecrets 402

10.81. VLScgSetNumSecrets 403

10.82. VLScgAllowVendorInfo 404

10.83. VLScgSetVendorInfo 405

10.84. VLScgAllowVendorInfoExt 406

10.85. VLScgSetVendorInfoExt 407

10.86. VLScgAllowKeysPerNode 409

10.87. VLScgSetKeysPerNode 410

10.88. VLScgAllowSiteLic 411

10.89. VLScgSetSiteLicInfo 412

10.90. VLScgSetNumSubnets 413

10.91. VLScgAllowMultipleFeature 414

10.92. VLScgSetNumFeatures 415

10.93. VLScgAllowSoftLimit 416

10.94. VLScgSetSoftLimit 417

10.95. VLScgAllowKeyLifeUnits 418

10.96. VLScgSetKeyLifetimeUnits 419

10.97. VLScgAllowKeyHoldUnits 420

10.98. VLScgSetKeyHoldtimeUnits 421

10.99. VLScgAllowKeyHoldtime 422

10.100. VLScgSetKeyHoldtime 423

10.101. VLScgAllowLicBirth 424

10.102. VLScgSetLicBirthMonth 425

10.103. VLScgSetLicBirthDay 426

10.104. VLScgSetLicBirthYear 427

10.105. VLScgAllowLicExpiration 428

10.106. VLScgSetLicExpirationMonth 429

10.107. VLScgSetLicExpirationDay 430

10.108. VLScgSetLicExpirationYear 431

xi

10.109. VLScgSetNumericType 432

10.110. VLScgSetLoadSWLicFile 433

10.111. VLScgAllowGracePeriodFlag 434

10.112. VLScgSetGracePeriodFlag 435

10.113. VLScgAllowGracePeriod 436

10.114. VLScgSetGracePeriodDays 437

10.115. VLScgSetGracePeriodHours 438

10.116. VLScgAllowLocalRequestLockCritFlag 439

10.117. VLScgSetLocalRequestLockCritFlag 440

10.118. VLScgAllowLocalRequestLockCrit 441

10.119. VLScgSetLocalRequestLockCrit 442

10.120. VLScgAllowVmDetection 443

10.121. VLScgSetVmDetection 444

10.122. VLScgValidateCodeT 445

The License Generation Function 446

10.123. VLScgGenerateLicense 447

License Hash and Decode Functions 448

10.124. VLScgCalculateLicenseHash 449

10.125. VLScgDecodeLicense 450

10.126. VLScgDecodeLicenseExt 452

LicenseMeter Related Functions 454

10.127. VLScgGetLicenseMeterUnits 455

10.128. VLScgGetTrialLicenseMeterUnits 456

License Revocation Functions 457

10.129. VLSgeneratePermissionTicket 458

10.130. VLSgeneratePermissionTicketExt 459

10.131. VLSverifyRevocationTicket 461

10.132. VLSverifyRevocationTicketExt 463

10.133. VLScgDecodeLicenseRevocationTicket 466

10.134. VLScgDecodeLicenseRevocationTicketExt 467

10.135. VPT_REQUEST_LINE 469

10.136. VPT_REQUEST 470

10.137. VPT_REQUEST_LINE_EXT 471

10.138. VPT_REQUEST_EXT 472

10.139. VRT_VERIFY_ERROR_LINE 473

10.140. VRT_VERIFY_ERRORS 475

10.141. VRT_REVOKE_TICKET_LINE 476

10.142. VRT_REVOKE_TICKET_INFO 477

10.143. VLSrevocationTicketInfoT 478

Chapter 11: System Initialization API 479

xii Sentinel RMS SDK API Reference Guide

11.1. sntlInitStandaloneSystem 480

11.2. sntlInitNetworkSystem 482

Chapter 12: Persistence Cleaning API 483

12.1. VLScleanStandalonePersistenceInfo 484

12.2. VLScleanNetworkPersistenceInfo 486

Appendix A: Status Codes 491

A.1. Licensing Library Error and Result Codes 492

A.2. License Generation Error Codes 505

A.3. Upgrade License Error Codes 511

A.4. System Initialization Error Codes 513

A.5. Persistence Cleaning Error Codes 515

Appendix B: Customization Features 517

B.1. Architecture of Overriding the Functions 519

B.2. Vendor-specified License Server Initialization 520

B.3. Vendor-specified License Server Identification String 521

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

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

B.6. Protection Against Time Tampering 528

B.7. Encrypting the License Codes 531

B.8. Encrypting the Upgrade License Codes 535

B.9. Encrypting License Server Messages 537

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

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

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

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

B.14. Setting Custom Client Information 548

B.15. Build Procedure 550

PrefaceWhat Does This Document Contain?

This guide contains information about integrating the Sentinel RMS based licensing with your appli-cations.

Conventions Used in This Document

Convention Description

Bold let-tering

Denotes keystrokes, menu items, window names or fields.

Courier Denotes syntax, prompts, and code examples.

Italic let-tering

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

More Documentation Resources

Document What's in it?Who Should Readit?

Release Notes Contains product overview, summary of new featuresintroduced in this release, and product installation

Developers installingthe RMS SDK

Sentinel RMS SDKDeveloper’s Guide

Contains the complete product overview, the nec-essary information for licensing and distributing theapplications

Developers planningand implementinglicensing

Sentinel RMS APIReference

Contains details about all the API functions, includingthe licensing library, license code generator, systeminitialization, and so on

Developers integratingthe API functions inthe code

WlscGen Help Contains details about using theWindows License Gen-erator

Developers generatinglicenses using WlscGen

CodeCover Help Contains details about using theWindows CodeCoverwrapper protection (for executables and DLLs)

Developers using theCodeCover to licenseapplications

Sentinel RMS SDKSystem Admin-istrator’s Help

Contains details about using the system admin-istration and license server configuration options

System Administrator(on the customer site)

xiv Sentinel RMS SDK API Reference Guide

Contacting Technical Support

Customer Connection Center (C3)

http://c3.safenet-inc.comExisting customers with a Customer Connection Center account can log in to man-age incidents, get latest software upgrades and access the complete SafeNet Knowl-edge Base repository.

Support and Downloads

http://www.safenet-inc.com/SupportProvides access to knowledge base and quick downloads for various products.

E-mail-based Support

[email protected]

Telephone-based Support

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

France 0825 341000

Germany 01803 7246269

United Kingdom 0870 7529200, +1 410 931-7520

Australia and New Zealand +1 410 931-7520(Intl)

China (86) 10 8851 9191

India +1 410 931-7520 (Intl)

SafeNet Sales Offices

Australia+61 2 9906 2988

Brazil+55 11 6121 6455

China+86 10 88519191

Finland+358 20 500 7800

France+33 1 47 55 74 70

Germany+49 1803 7246269

Hong Kong+852 3157 7111

India+91 120 4020797+91 120 4242958+91 120 4020555

Israel+972-3-9781111

Japan (Tokyo)+ 81 45 6405733

Korea+82 31 705 8212

Mexico+52 55 5575 1441

Netherlands+31 73 658 1900

Singapore+65 6243 9612

Taiwan886-2-2760-3930

UK (Camberley)+44 0 1276 608000

U.S. (Massachusetts)+1 978.539.4800

U.S. (New Jersey)+1 201.333.3400

U.S. (Virginia)+1 703.279.4500

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

U.S. (San Jose, CA)+ (408) 452 7651

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

http://c3.safenet-inc.com/




xv

Documentation Feedback

To help us improve future versions of Sentinel RMS SDK documentation, wewant to know about anycorrections, clarifications or further information you would find useful. When you contact us, pleaseinclude the following information:

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

n The version of the Sentinel RMS SDK you are using

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

Send us e-mail at: [email protected]

Chapter 1:Sentinel RMS Licensing Library API

This section describes the Sentinel RMS licensing function calls. Please note the following pointsbefore you use these API functions:

n Multiple authorizations can be requested within an application for a feature and feature ver-sion. Each authorization must be released and updated separately as the license server treatsthese authorizations as separate clients.

n A handle that uniquely identifies an authorization will be returned for each LSRequest callusing the parameter, lshandle. This handle is also used in other function calls.

n The RMS licensing library is thread-safe. The licensing functions can be called from multiplethreads of a licensed application. However, the license handles may not be shared or passedfrom one thread to another. We recommend spawning a thread (or using themain appli-cation thread) and performing all licensing functions for that handle in the single thread.

n All function calls, return codes, and data types that begin with the LS prefix are part of theLSAPI standard. The APIs that begin with the VLS prefix are the extensions that make licensingeasier and more powerful.

n All function calls return the status code LS_SUCCESS if successful or a specific error code indi-cating the reason for failure otherwise.

We also recommend going through "Chapter 5 - Licensing Applications Using API Functions" of the Sen-

tinel RMS SDK Developer’s Guide, before you begin using these functions.

1

2 Chapter 1: Sentinel RMS Licensing Library API

The Quick Client Licensing FunctionsThis section describes the API functions meant for quick licensing—especially for the applications thatrequire only one license for each instance of the program.

Given below is a list of the API functions:

Function Description

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

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

1.1. VLSlicenseClient Server Static Library DLL

√ √ √

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

1.1.1. SyntaxLS_STATUS_CODE VLSlicense (

unsigned char *featureName,

unsigned char *version,

LS_HANDLE *lshandle );

Argument Description

featureName Name of the feature for which the licensing code is requested. May consistof any printable characters. Limited to 24 characters.

version Version of the feature for which the licensing code is requested. May con-sist of any printable characters. Limited to 11 characters.

lshandle (out) This handlemust be used to release this license code by calling VLSdis-ableLicense. Spacemust be allocated by the caller.

Length limitations exist on feature name and version depending on the type of license you want to issue

to your customer. See the Sentinel RMS SDK Developer’s Guide for details.

1.1.2. Description

This function obtains a license using LSRequest and then automatically updates the license after 80%of the license lifetime has passed using the LSUpdate function. This function uses timers (SIGALRM onUNIX) to update a license periodically for Win32 GUI-based applications and UNIX applications. Youshould 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 func-tion VLSdisableLicense, which removes the timer and releases the license. If you release the licenseusing LSRelease and your application continues to run, the timer will keep trying to renew an invalidlicense since it does not know that you have released the license yourself.

1.1. VLSlicense 3


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

taneous uses of a single timer, the Sentinel RMS API provides a generalized version of the timer func-

tions.

This function is available on most UNIX platforms. This function may not be available on platformsthat 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 errorcodes:

Error Code Description

VLS_APP_UNNAMED n featureName is NULLn version is NULLn Both feature and version cannot be NULL at the

same time.

VLS_CALLING_ERROR n lshandle is NULL.n Attempted to use stand-alonemodewith network

only library, or network modewith stand-alonelibrary.

LS_INSUFFICIENTUNITS License server does not currently have sufficient licensingunits for requested feature to grant a license.

VLS_NO_SUCH_FEATURE License server does not have a license that matchesrequested feature, version and capacity.

VLS_TRIAL_LIC_EXHAUSTED Trial license has expired.

LS_LICENSE_EXPIRED License has expired.

VLS_APP_NODE_LOCKED Requested feature is node locked, but request was issuedfrom an unauthorized machine.

VLS_USER_EXCLUDED User or machine excluded from accessing requested fea-ture.

VLS_VENDORIDMISMATCH The vendor identification of the requesting applicationdoes not match the vendor identification of the feature forwhich the license server has the license. This error occursonly when client is older than version 6.3 else the errorreturned is VLS_NO_SUCH_FEATURE.

VLS_NON_REDUNDANT_ SRVR License server is non-redundant and therefore cannot sup-port this redundancy-related operation.

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization in process.

VLS_FEATURE_INACTIVE Feature is inactive on specified license server.

VLS_MAJORITY_RULE_ FAILURE Majority rule failure prevents token from being issued.

VLS_NO_SERVER_RESPONSE Communication with license server has timed out.


VLS_BAD_SERVER_MESSAGE Message returned by license server could not be under-stood.

VLS_NO_SERVER_RUNNING License server on specified host is not available for proc-essing license operation requests.

VLS_HOST_UNKNOWN Invalid hostNamewas specified.

VLS_NO_SERVER_FILE The license server has not been set and the client appli-cation is unable to determine which license server to use.

LS_NORESOURCES An error occurred in attempting to allocatememoryneeded by this function.

LS_NO_NETWORK Failed to initializeWinsock wrapper. (Only applicable ifusing network-only library.) Generic error indicating net-work failure.

VLS_INTERNAL_ERROR An internal error has occurred in processing.

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

1.1. VLSlicense 5


1.2. VLSdisableLicenseClient Server Static Library DLL

√ √ √

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

1.2.1. SyntaxLS_STATUS_CODE VLSdisableLicense (

LS_HANDLE *lshandle );


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

1.2.2. Returns



VLS_CALLING ERROR lshandle is an ambiguous handle; it is not exclusivelyactive or exclusively queued.

VLS_ALL_UNITS_RELEASED All units have already been released.

VLS_RETURN_FAILED Generic error indicating that the license could not bereturned.


VLS_HOST_UNKNOWN Invalid hostName is specified.

VLS_NO_SERVER_RESPONSE Communication with license server timed out.

VLS_BAD_SERVER_MESSAGE Message returned by server could not be understood.

LS_NO_NETWORK Generic error indicating that the network is unavailablefor servicing the license operation.

LS_NORESOURCES An error occurred in attempting to allocatememoryneeded by function.

VLS_INTERNAL_ERROR An error occurred with respect to the serial-ization/customization of Sentinel RMS Development Kitfiles.


The Standard Client Licensing FunctionsThis 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:


VLSinitialize Initializes the licensing library.

LSRequest Requests an authorization license code from the license server.

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

LSRelease Releases the licenses associated with a handle.

VLScleanup Cleans up the licensing library.

The Standard Client Licensing Functions 7


1.3. VLSinitializeClient Server Static Library DLL

√ √ √

Initializes the licensing library.

1.3.1. SyntaxLS_STATUS_CODE VLSinitialize(void);

This function has no arguments.

1.3.2. Description

This call must bemade before any RMS licensing library function can be called. It initializes and allo-cates 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 nec-

essary 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



LS_NORESOURCES An error occurred in attempting to allocatememory needed by function.

LS_NO_NETWORK Failed to initializeWinsock wrapper. (Only applicable if using network-onlylibrary.)


1.4. LSRequestClient Server Static Library DLL

√ √ √

Requests an authorization license code from the license server.

1.4.1. SyntaxLS_STATUS_CODE LSRequest (

unsigned char *licenseSystem,

unsigned char *publisherName,



unsigned long *unitsReqd,

unsigned char *logComment,

LS_CHALLENGE *challenge,

LSHANDLE *lshandle );

Argument DescriptionlicenseSystem Unused. Use LS_ANY as the value of this variable. LS_ANY is specified to indi-

cate a match against installed license systems.

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

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

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

unitsReqd (IN/OUT) The number of licenses required. The license server verifies that the requestednumber of units exist and may reserve those units. The number of units avail-able is returned.If the number of licenses available with the license server is less than therequested number, the number of available licenses will be returned using unit-sReqd. If unitsReqd is NULL, a value of 1 unit is assumed.

logComment A string to be written by the license server to the comment field of the usagelog file. Pass a NULL value for this argument if no log comment is desired. Max-imum of 100 characters.

challenge The challenge structure. If the challenge-responsemechanism is not beingused, this pointermust be NULL. The space for this structuremust be allocatedby the calling function. The response to the challenge is provided in the samestructure, provided a license was issued, i.e., provided the function LSRequestreturned LS_SUCCESS.

lshandle (OUT) The handle for this request is returned in lshandle. This handlemust be usedto later update and release this license code. A client can havemore than onehandle active at a time. Space for lshandlemust be allocated by the caller.

1.4. LSRequest 9


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 isreturned. The challenge-response is computed if a non-NULL value is passed for the challenge argu-ment. 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 notgrant the license.

Every client should complete this call successfully before commencing execution of the application orthe feature.

If the default error handler is not used, the client application must check the code returned by theLSRequest call and should continue only if LS_SUCCESS is returned. The default error handler will exitthe application on error.

If queuing is desired, you must use VLSqueuedRequest instead of LSRequest.

1.4.3. Returns



VLS_CALLING_ERROR n lshandle is NULL.n challenge argument is non-NULL, but cannot be under-

stood.

Attempted to use stand-alonemodewith network-only library,or network modewith stand-alone library.

VLS_APP_UNNAMED n featureName is NULLn version is NULL.

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

VLS_NO_LICENSE_ GIVEN unitsReqd is zero.

VLS_NO_SUCH_ FEATURE License server does not have license that matches requested fea-ture and version.

LS_INSUFFICIENTUNITS n License server does not currently have sufficient licensingunits for requested feature to grant license.

n The units_reqd parameter of the call contains the hardlimit of the feature for which authorization was requestedif 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 per-sistence data is corrupted.


VLS_TRIAL_LIC_ EXHAUSTED Trial license expired or trial license usage exhausted.

VLS_APP_NODE_ LOCKED Requested feature is node locked, but request was issued fromunauthorized machine.

VLS_USER_EXCLUDED User or machine excluded from accessing requested feature.

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

VLS_SERVER_SYNC_IN_PROG-RESS

License server synchronization in process.

VLS_FEATURE_ INACTIVE Feature is inactive on specified license server.

VLS_MAJORITY_RULE_FAILURE Majority rule failure prevents token from being issued.

VLS_NO_SERVER_ RUNNING License server on specified host is not available for processinglicense operation requests.

VLS_NO_SERVER_ RESPONSE Communication with license server has timed out.


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

VLS_BAD_SERVER_MESSAGE Message from license server could not be understood.

LS_NO_NETWORK Generic error indicating that the network is unavailable for serv-icing the license operation.

LS_NORESOURCES An error occurred in attempting to allocatememory needed byfunction.

VLS_INTERNAL_ERROR An internal error has occurred in the processing.

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


1.4.4. See Also:

n Challenge ResponseMechanism

n VLSsetTimeoutInterval

n VLSqueuedRequest and VLSqueuedRequestExt

1.4. LSRequest 11


1.5. LSUpdateClient Server Static Library DLL

√ √ √

Once an authorization license has been received, the client must call LSUpdate periodically to renewits 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. SyntaxLS_STATUS_CODE LSUpdate (

LS_HANDLE lshandle,

unsigned long ulGraceSwitchToNetworkTm,

long *unused2,

unsigned char *unused3,

LS_CHALLENGE *challenge );


lshandle This must be the handle previously returned by the correspondingLSRequest call.

ulGraceSwitchToNetworkTm Unused till version 8.3.0.Since version 8.4.0, this parameter can be used to switch from a gracelicense to a network license (by sending periodic updates to the licenseserver , the API checks for the availability of the corresponding licensetoken). Accordingly, the parameter can have the following values:

n A numeric value between 1 to 54,000, which is the time in seconds.n VLS_GRACE_REMAIN_ON_NONET: When you do not want to allow

switching from a grace license to network license (functionality sofar).

n LS_DEFAULT_UNITS: The default value of 10minutes. This meansthat after every 10minutes, the LSUpdate call checks for an avail-able 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.


unused2 Unused. Use NULL as the value.

unused3 Use NULL as the value.

challenge The challenge structure.

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

1.5.2. Returns



VLS_CALLING_ERROR n lshandle is a queued handle. Cannot use LSUpdate toupdate a queued handle.

n challenge argument is non-NULL, but cannot beunderstood.

VLS_NO_LICENSE_GIVEN Generic error indicating that license was not updated.

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

VLS_NO_SUCH_FEATURE License server does not have license that matches requestedfeature, version and capacity.

LS_NOLICENSESAVAILABLE All licenses in use.



VLS_FINGERPRINT_MISMATCH Client-locked; locking criteria does not match.

VLS_APP_NODE_LOCKED Feature is node locked, but the update request was issuedfrom an unauthorized machine.

VLS_CLK_TAMP_FOUND License server has determined that the client’s system clockhas been modified. The license for this feature has time-tam-pering protection enabled, so the license operation isdenied.

VLS_VENDORIDMISMATCH The vendor identification of requesting application does notmatch the vendor identification of the feature for which thelicense server has a license. This error occurs only whenclient is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

VLS_INVALID_DOMAIN The domain of the license server is different from that ofclient.

VLS_NO_SERVER_ RUNNING License server on specified host is not available for proc-essing license operation requests.



1.5. LSUpdate 13




LS_NO_NETWORK Generic error indicating that the network is unavailable forservicing the license operation.

LS_NORESOURCES An error occurred in attempting to allocatememory neededby function.


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


1.5.3. See Also

n VLSbatchUpdate


n VLSdisableLocalRenewal

n VLSenableLocalRenewal

n VLSisLocalRenewalDisabled

n VLSgetRenewalStatus

n VLSsetRemoteRenewalTime

1.6. LSReleaseClient Server Static Library DLL

√ √ √

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

1.6.1. SyntaxLS_STATUS_CODE LSRelease (

LS_HANDLE lshandle,

unsigned long units_consumed,

unsigned char *log_comment );


lshandle The handle returned by the corresponding LSRequest.

units_consumed The number of units required to be released.

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

1.6.2. Description

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

1.6.3. Returns



VLS_CALLING_ERROR lshandle is an ambiguous handle; it is not exclusively active orexclusively queued.

VLS_RETURN_FAILED Generic error indicating that the license could not be returned.

VLS_ALL_UNITS_ RELEASED The function released all the issued units when the clientrequested to release only few.

VLS_NO_SERVER_ RUNNING License server on specified host is not available for processing thelicense operation requests.


VLS_HOST_ UNKNOWN Invalid hostNamewas specified.



1.6. LSRelease 15




VLS_RESOURCE_LOCK_FAIL-URE

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


1.7. VLScleanupClient Server Static Library DLL

√ √ √

Cleans up the licensing library.

1.7.1. SyntaxLS_STATUS_CODE VLScleanup(void);


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. CallingVLScleanup 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 LicensingLibrary Error and Result Codes.

1.7.4. See Also:

n VLSinitialize

1.7. VLScleanup 17


The Advanced Client Licensing FunctionsThis section describes the API functions used for performing advanced licensing operations.



VLSrequestExt Requests an authorization with support for license server hooking.

VLSrequestExt2 Supports capacity and non-capacity requests.

VLSreleaseExt Releases an authorization with support for license server hooking.

VLSbatchUpdate Updates several license codes at once.

1.8. VLSrequestExtClient Server Static Library DLL

√ √ √

Use VLSrequestExt when using license server hooks.

1.8.1. SyntaxLS_STATUS_CODE VLSrequestExt (

unsigned char *licenseSystem,

unsigned char *publisherName,



unsigned long *unitsReqd,



LS_HANDLE *lshandle,

VLSserverInfo *serverInfo );


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

publisherName Unused. Any value specified is ignored.

featureName Name of the feature for which the licensing code is requested. May consistof any printable characters. Limited to 64 characters, including a NULL ter-mination character.

version Version of the feature for which the licensing code is requested. May con-sist of any printable characters. Limited to 11 characters.

unitsReqd (IN/OUT) The number of licenses required. If the number of licenses available withthe license server is less than the requested number, the number of avail-able licenses will be returned using unitsReqd. If unitsReqd is NULL, a valueof 1 unit is assumed.

logComment A string to be written by the license server to the comment field of theusage log file. Pass a NULL value for this argument if no log comment isdesired.

challenge The challenge structure. If the challenge-responsemechanism is not beingused, this pointermust be NULL. The space for this structuremust be allo-cated by the calling function. The response to the challenge is provided inthe same structure, provided a license code was issued, i.e., provided thefunction LSRequest returned LS_SUCCESS.

lshandle The handle for this request is returned in lshandle. This handlemust beused to later update and release this license. A client can havemore than




one handle active at a time. Space for lshandlemust be allocated by thecaller.

serverInfo This information is passed to the license server for use in server hook func-tions.

1.8.2. Description

Before calling VLSrequestExt, you must call VLSinitServerInfo.

1.8.3. Returns



VLS_APP_UNNAMED n featureName is NULLn version is NULL

Both feature name and version cannot be Null at the sametime.

VLS_CALLING_ERROR n lshandle is NULLn challenge argument is non-NULLn Attempted to use stand-alonemodewith network-


n When max feature name length exceeds 64 char-acters.

VLS_NO_LICENSE GIVEN n unitsReqd is zeron License request is denied due to server hook failure.

VLS_NO_SUCH_FEATURE License server does not have license that matchesrequested feature, version and capacity.


LS_INSUFFICIENTUNITS License server does not currently have sufficient licensingunits for requested feature to grant license.


VLS_TRIAL_LIC_EXHAUSTED Trial license expired or trial license usage exhausted.


VLS_CLK_TAMP_FOUND License server has determined that the client’s systemclock has been modified. The license for this feature hastime-tampering protection enabled, so the license oper-ation is denied.

VLS_VENDORIDMISMATCH The vendor identification of requesting application doesnot match the vendor identification of the feature forwhich the license server has the license. This error occursonly when client is older than version 6.3 else the error


returned is VLS_NO_SUCH_FEATURE.




VLS_NO_SERVER_RUNNING License server on specified host is not available for proc-essing license operation requests



VLS_NO_SERVER_FILE No license server has been set or the client application isunable to determine which license server to use.




VLS_INTERNAL_ERROR Failure occurred in setting timer. (Timer is only attemptedto be set if timer is available for platform and if licenserequires timer for updates.)




1.9. VLSrequestExt2See VLSrequestExt.

1.10. VLSreleaseExtClient Server Static Library DLL

√ √ √

Use VLSreleaseExt when using license server hooks.

LS_STATUS_CODE VLSreleaseExt (

LS_HANDLE lshandle,

unsigned long units_consumed,




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

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

logComment A string to be written by the license server to the comment field of the usagelog file. Pass a NULL value for this argument if no log comment is desired. Max-imum of 100 characters. An IN parameter.

serverInfo This information is passed to the license server for use in server hook func-tions. An IN\OUT parameter.

1.10.1. Returns



VLS_CALLING_ERROR lshandle is ambiguous handle; it is not exclusively active orexclusively queued.

VLS_RETURN_FAILED Generic message indicating that the license could not bereturned.

VLS_ALL_UNITS_RELEASED The function released all the issued units when the clientrequested to release only few.

VLS_NO_SERVER_RUNNING License server on specified host is not available for processinglicense operation requests.





LS_NORESOURCES An error occurred in attempting to allocatememory needed

1.10. VLSreleaseExt 23



by function.


1.11. VLSbatchUpdateClient 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 author-

izations and queued handles.

1.11.1. SyntaxLS_STATUS_CODE VLSbatchUpdate (

int numHandles,


unsigned long *unused1,

long *unused2,


LS_CHALLENGE *unused4,

LS_STATUS_CODE *status );


numHandles Specifies the number of handles.

lshandle (in) Array of numHandles handles, allocated by caller.

unused1 Currently ignored—pass in a NULL.

unused2 Currently ignored—pass in a NULL.



status (out) Array of numHandles status codes, allocated by caller.

1.11.2. Description

API function interface for updating several licenses. It handles properly the fact that some of thelicenses may need to be updated locally, and some remotely. In case the handles need to be updatedon 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 errorhandlers at all. There is no limit on the number of handles passed. A handle obtained in one threadcan be used in remaining threads as well to update a specific token.



1.11.3. Returns

If everything fails, this function will return a non-LS_SUCCESS code. For failures in individual updates oflicense codes, this function will return LS_SUCCESS, but the value of the corresponding status elementwill be set to the error code. Otherwise, it will return the following error codes:


LS_BADHANDLE Invalid handle

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

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

VLS_NO_LICENSE_GIVEN Generic error indicating that the license was not updated.

VLS_NO_SUCH_FEATURE License server does not have license that matches requested fea-ture, version and capacity.

LS_LICENSETERMINATED Cannot update license because license already expired.



VLS_USER_EXCLUDED User or machine are excluded from accessing requested feature.

VLS_APP_NODE_LOCKED Requested feature is node locked but update request was issuedfrom unauthorized machine.

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

VLS_VENDORMISMATCH The vendor identification of the requesting application does notmatch the vendor identification of the feature for which thelicense server has a license.






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

1.11.4. See Also

n VLSbatchUpdate

n LSUpdate

n Challenge ResponseMechanism




n VLSisLocalRenewalDisabled

n VLSsetRemoteRenewalTime



1.12. Challenge-response MechanismThe challenge-responsemechanism can be used by a licensed application to authenticate the licenseserver.

1.12.1. Syntaxtypedef struct {

unsigned long ulReserved;

unsigned long ulChallengedSecret;

unsigned long ulChallengeSize;

unsigned char ChallengeData[30];

} CHALLENGE;

typedef CHALLENGE LS_CHALLENGE;

typedef struct {

unsigned long ulResponseSize;

unsigned char ResponseData[16];

} CHALLENGERESPONSE;

Member Description

ulReserved LSAPI requires this to be set to 0.

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

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

ChallengeData The actual string that is used in challenging the license server. This is astring of at most 30 characters, each of which can have any values, includ-ing 0.

ulResponseSize Number of characters in the response to the challenge.

ResponseData The string of characters representing the actual response.

1.12.2. Description

In challenge-response, the license server associates a secret with a feature, provided by the licensecode. The application also contains this secret. In the license server validation process, an applicationwill “challenge” the license server with a data string. The license server computes a response accordingto some previously arranged algorithm using the values, data and secret, which it returns. The clientapplication locally computes the expected response using data and secret, and verifies that theexpected responsematches the response returned by the license server.

In order for the authentication mechanism to work correctly and securely, both the license server andthe client application must use the same algorithm to compute the response given the values of data

and secret. LSAPI requires the use of the software, “RSA Data Security, Inc. MD4Message Digest Algo-rithm” provided by RSAData Security, Inc. to compute the response.

In practice, to save execution time and space, the client application need not invoke theMD4Mes-sage Digest Algorithm at run time to calculate the response. Challenge-response pairs can instead bemaintained in a pre-computed table.

Sentinel RMS allows for the usage ofmultiple secrets, with secrets indexed starting at 1. Client appli-cations 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 anin/out parameter for the LSRequest and VLSrequestExt function calls and must be properly allocatedand initialized by the calling process. Refer to the sample files, crexamp.c, chalresp.c, andmd4.c foradditional details on using this mechanism.

The parameter used to pass the challenge structure is also used by the library to return the responsestructure. The CHALLENGE pointer must therefore be typecast to CHALLENGERESPONSE * to obtainthe correct response after the function call.

The response to a challengemadewith any function call, for example, LSRequest is valid only if thatfunction call returns LS_SUCCESS. If LS_SUCCESS is not returned, the response to the challenge is unde-fined.

For more information on how to associate secrets with a feature, see VLScgAllowSecrets.

1.12. Challenge-responseMechanism 29


The Client Configuration FunctionsThis section describes the API functions that allow the licensed application to retrieve or overwrite thedefault settings.



VLSsetContactServer Sets the license server to be contacted.

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

VLSsetServerPort Sets the license server’s communication port.

VLSgetServerPort Obtains the license server’s communication port.

VLSinitMachineID Sets the fields in machineID to default values.

VLSgetMachineID Sets machineID values for the current host.

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

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

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

VLSsetHostIdFunc Register the custom fingerprint mechanism with the clientlibrary.

VLSsetCustomExFunc Registers the extended custom fingerprint mechanism with theclient library.

VLSmachineIDtoLockCode Computes the previous version locking codes.

VLSmachineIDtoLockCodeEx Computes the new version locking codes.

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

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

VLSgetServerList Retrieves the default license server list.

VLSgetServerList Retrieves the default license server list.

VLSinitServerInfo Initializes the license serverInfo data structure to defaultvalues.

VLSsetBroadcastInterval Configures broadcast behavior.

VLSgetBroadcastInterval Retrieves broadcast behavior parameters.

VLSsetTimeoutInterval Configures timeout behavior.

VLSgetTimeoutInterval Retrieves timeout behavior parameters.


VLSsetHoldTime Sets license hold time.

VLSsetSharedId/ VLSsetTeamId Redefines shared ID functions.

VLSsetSharedIdValue/ VLSset-TeamIdValue

Registers a customized shared ID value.

VLSsetGraceRequestFlag Sets the behavior if a grace license can be requested or notwhen the contact server has been set to stand-alonemode(no-net).

VLSgetGraceRequestFlag Obtains the status if the grace license request is enabled or notwhen the contact server has been set to stand-alonemode(no-net).

VLScalculateLicenseHash Calculates the license hash for a given license string.

VLSisVirtualMachine Reports whether the license server is running on a virtualmachine or not.

The Client Configuration Functions 31


1.13. VLSsetContactServerClient Server Static Library DLL

√ √ √

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

1.13.1. SyntaxLS_STATUS_CODE VLSsetContactServer (

char *serverName );


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

n Setting the LSHOST environment variable. However, the environment variables are checkedonly at the time of application start-up.

n The lshost file.

1.13.3. Notes:

n The VLSsetContactServer API function will override LSFORCEHOST and the LSHOST envi-ronment variables and the LSHOST file.

n All future transactions will be directed to the host set, regardless of the validity of the hostname or whether a license server is running at that host.

n After a license is successfully requested (via LSRequest or its variants), the application willremember the name of the license server host which was contacted to obtain the license. Inany further client-server communication involving this handle, obtained by the client, theapplication will always communicate with the license server from which it obtained thelicense, regardless of intervening VLSsetContactServer calls. The license server name set byVLSsetContactServerwill be contacted only for operations that do not involve an alreadyvalid handle. Therefore, in case the original license server goes down, you must request afresh license (hence a fresh handle) from the new license server you wish to use, instead ofattempting to send license updatemessages to the new license server, unless redundantlicense servers are in use. When a redundant license server fails, all clients are automaticallyreconnected to one of the other redundant license servers.

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

Linked with Server Name Meaning

Network library

Valid host name Client should communicate with the license server on server-Name.

““ or Null If no server name is set, the application will determine server-Name using default mechanism (broadcast within the sub-net).

NO-NET The VLS_NOT_SUPPORTED_IN_NET_ONLY_MODE error willappear.

NO-NET, NO_NET, no_net, and no-net are synonymous.

Stand-alone

library

Valid host name The VLS_NOT_SUPPORTED_IN_NONET_MODE error willappear.

““ or Null Communicate with the application (which has the integratedstand-alone license server).

If no serverName is specified using VLSset-

ContactServer, the environment variables are ignored

and the application looks for a license on the local sys-

tem.

NO-NET Communicate with the application (which has the integratedstand-alone license server).

LSFORCEHOST orLSHOST

Ignores the settings provided using the environment var-iables.

Integrated

library

Valid host name Client should communicate with the license server on server-Name.

““ or Null If no server name is set, the application will determine server-Name using default mechanism (stand-alone followed bybroadcast within the subnet).

NO-NET Communicate with the application (which has the integratedstand-alone license server).

1.13.4. Returns

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


VLS_CALLING_ERROR Attempted to use stand-alonemodewith net-work-only library, or network modewith stand-alone library.

Provided an IPX address as the serverName.

VLS_NO_RESOURCES An error occurred in attempting to allocatemem-ory needed by function.

1.13. VLSsetContactServer 33



VLS_RESOURCE_LOCK_FAILURE Failed to obtain the API resource lock. Retry by call-ing this API again.

VLS_NOT_SUPPORTED_IN_NONET_MODE When the application is linked to a stand-alonelibrary and the license server specified is otherthan no-net.

VLS_NOT_SUPPORTED_IN_NET_ONLY_MODE When the application is linked to a network onlylibrary and no-net is specified.


1.14. VLSgetContactServerClient Server Static Library DLL

√ √ √

Retrieves the license server name.

1.14.1. SyntaxLS_STATUS_CODE VLSgetContactServer(

char *outBuf,

int outBufSz );


outBuf (out) Contains a single license server name, space allocated by caller.

outBufSz Size of outBuf.

1.14.2. Description

Returns the name of the license server host that will be contacted, in case the client has already setthe license server name. Otherwise this function will fail. If the Sentinel RMS Development Kit library isrunning in stand-alonemode, it returns the string, VLS_STANDALONE.

1.14.3. Returns



VLS_CALLING_ERROR outBuf is NULL.


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


1.14.4. See Also:

n VLSsetContactServer

1.14. VLSgetContactServer 35


1.15. VLSsetServerPortClient Server Static Library DLL

√ √ √

It specifies the port number on which the license server is running. The licensed application will con-tact 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 itmultiple times to reset the port for the same license server.

1.15.1. Syntax

void VLSsetServerPort(int port_number);


port_number The license server port number.

1.15.2. Description

Defines the license server’s communication port.

1.15.3. Returns

Does not return anything.

1.16. VLSgetServerPortClient Server Static Library DLL

√ √ √

Retrieves the port number.

1.16.1. Syntaxint VLSgetServerPort(void);

1.16.2. Description

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

1.16.3. Returns

The currently set license server port number is returned.

1.16. VLSgetServerPort 37


1.17. VLSinitMachineIDClient Server Static Library DLL

√ √ √

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

1.17.1. SyntaxLS_STATUS_CODE VLSinitMachineID (

VLSmachineID *machineID );


machineID User allocated structure where themachine ID will bemaintained.

1.17.2. Description

Sets the fields inmachineID to their default values.

The licensemanager uses the following data structure to define the characteristics of a machine.

typedef struct {

unsigned long id_prom;

char ip_addr[VLS_MAXLEN];

unsigned long disk_id;

char host_name[VLS_MAXLEN];

char ethernet[VLS_MAXLEN];

char portserv_addr[VLS_MAXLEN];

unsigned long custom;

unsigned long reserved;

char cpu_id;

VLScustomEx customEx;

char hard_disk_serial[VLS_MAXLEN];

char cpu_info[VLS_MAX_CPU_INFO_LEN + 1];

char uuid[VLS_MAX_UUID_LEN + 1];

unsigned long unused2;

} VLSmachineID;

The structure is called themachineID, and the contents of the first 11 fields are called the fingerprintfor themachine to which the contents apply. In practice, a developer may choose to use some subsetof 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 elementtype. Each bit designates a locking criterion, and the lock selector represents the fingerprint elementsfor a given machine.

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.

Themasks which define each locking criterion are given below.

Delete this text and replace it with your own content.

#define VLS_LOCK_ID_PROM 0x1

#define VLS_LOCK_IP_ADDR 0x2

#define VLS_LOCK_DISK_ID 0x4

#define VLS_LOCK_HOSTNAME 0x8

#define VLS_LOCK_ETHERNET 0x10

#define VLS_LOCK_NW_SERIAL 0x40

#define VLS_LOCK_PORTABLE_SERV 0x80

#define VLS_LOCK_CUSTOM 0x100

#define VLS_LOCK_PROCESSOR_ID 0x200

#define VLS_LOCK_CUSTOM_EX 0x400

#define VLS_LOCK_HARD_DISK_SERIAL 0x800

Themask 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 cus-tom locking criteria.

typedef struct _vlscustomEx {

unsigned char customEx[VLS_CUSTOMEX_SIZE];

int len;

} VLScustomEx;

Themaximum size of the extended custom locking code can be 64-bytes.

Themachine ID and lock selector are input to the license generator and encrypted to create a lockingcode which then becomes part of the license that authorizes use of an application. When a license isrequested by the application, a fingerprint for themachine is calculated and used to create a lockingcode. This must compare favorably with its counterpart in the license before execution of the appli-cation can be authorized.

1.17.3. Returns

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


VLS_CALLING_ERROR machineID is NULL.

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


1.17. VLSinitMachineID 39


1.18. VLSgetMachineIDClient Server Static Library DLL

√ √ √

1.18.1. SyntaxLS_STATUS_CODE VLSgetMachineID (

unsigned long lock_selector_in,

VLSmachineID *machineID,

unsigned long *lock_selector_out );


lock_selector_in User provided mask specifying locking criteria to be read.

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

lock_selector_out Mask returned specifying for the applicable lock selectors.

1.18.2. Description

Sets the values of themachineID struct for the current host. The input machineID struct should firstbe initialized by calling VLSinitMachineID. Then, calling this function will attempt to read only thoseitems indicated by the lock_selector_in. If lock_selector_out is not NULL, *lock_selector_outwill be setto a bit mask specifying which items were actually read. To try and obtain all possible machineID structitems, set lock_selector_in to VLS_LOCK_ALL. VLSgetMachineID allows you to use an Ethernet addressas 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 LicensingLibrary Error and Result Codes.

1.19. VLSgetMachineIDOldClient Server Static Library DLL

√ √ √

1.19.1. SyntaxLS_STATUS_CODE VLSgetMachineIDOld (



unsigned long *lock_selector_out );



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

lock_selector_out Mask returned specifying for the applicable lock selectors.

1.19.2. Description

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

The VLSgetMachineIDOld API function fills up the machineID structure with the logic used by earlier ver-

sion 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 LicensingLibrary Error and Result Codes.

1.19. VLSgetMachineIDOld 41


1.20. VLSgetNumberedMachineIDClient Server Static Library DLL

√ √ √

1.20.1. SyntaxLS_STATUS_CODE VLSgetNumberedMachineID (



unsigned long *lock_selector_out,

int flag,

int index,

int reserved );




lock_selector_out Mask returned specifying which locking criteria were read.

flag n Specify VLS_GET_ETHERNET for multiple Ethernet.n Specify VLS_GET_CID for cascaded CID keys.n Specify VLS_GET_CUSTOMEX for multiple CustomEx.n 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 themachineID struct for the current host (like VLSgetMachineID)

n Obtains the CID or Ethernet fingerprint at the specified index location. It can be useful in fol-lowing cases:

n Multiple Ethernet cards

n Cascaded multiple CID keys

n Multiple custom locking devices

n 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_FIN-GERPRINT_VALUE status code. This status codemeans that no more fingerprint information is furtheravailable. For a specific index, if the API function is unable to retrieve the fingerprint, it will return theVLS_ERROR_FINGERPRINT_VALUE_NOT_FOUND error code.

In case, the locking information of some other criteria along with a cascaded CID or Ethernet or cus-tom 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 infor-mation 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:


VLS_CALLING_ERROR n The lock mask specified in the lock_selector_in argument doesnot have lock mask corresponding to themask of the flag argu-ment.

n 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 specificindex.

RMS does not consider the following interfaces while calculating Eth-ernet fingerprint:

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

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

1.20. VLSgetNumberedMachineID 43



interface, the API fails to obtain fingerprint information and returnsthis error.

VLS_ERROR_NO_MORE_FIN-GERPRINT_VALUE

No more fingerprint information is further available.

VLS_NO_AVAILABLE_MACHINE_ID

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

VLS_LIBRARY_NOT_INITIAL-IZED

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

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

VLS_NOT_SUPPORTED An earlier version of the license server is being used.

1.21. VLSgetNumberedMachineIDExtClient Server Static Library DLL

√ √ √

1.21.1. SyntaxLS_STATUS_CODE VLSgetNumberedMachineIDExt (

unsigned char *server_name,



unsigned long *lock_selector_out,

int flag,

int index,

int reserved );


server_name The name of the server contacted for setting themachineID struct. Ifnot set, the current host (set in the VLSsetContactServer API or theLSFORCEHOST environment variable) is assumed.

If nothing is set in the VLSsetContactServer API or the LSFORCEHOSTenvironment variable, error 4 (VLS_NO_SERVER_FILE) is returned.



lock_selector_out Mask returned specifying which locking criteria were read.

flag n Specify VLS_GET_ETHERNET for multiple Ethernet.n Specify VLS_GET_CID for cascaded CID keys.n Specify VLS_GET_CUSTOMEX for multiple CustomEx.n 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 aspecific license server (such as a remotemachine in the network).

1.21. VLSgetNumberedMachineIDExt 45


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:


VLS_CALLING_ERROR n The lock mask specified in the lock_selector_in argument doesnot have lock mask corresponding to themask of the flag argu-ment.

n 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 specificindex.

RMS does not consider the following interfaces while calculating Eth-ernet fingerprint:

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

Thus, if the index is already occupied by a device other than Ethernetinterface, the API fails to obtain fingerprint information and returnsthis error.

VLS_ERROR_NO_MORE_FIN-GERPRINT_VALUE

No more fingerprint information is further available.

VLS_NO_AVAILABLE_MACHINE_ID

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

VLS_LIBRARY_NOT_INITIAL-IZED

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



1.22. VLSmachineIDtoLockCodeClient Server Static Library DLL

√ √ √

1.22.1. SyntaxLS_STATUS_CODE VLSmachineIDtoLockCode (


unsigned long lock_selector,

unsigned long *lockCode );


machineID Machine ID used to generate lock code.

lock_selector Bit mask defining the different lock criteria to retrieve

lockCode Lock code string generated from lock selector. lockCode is an OUT param-eter.

1.22.2. Description

This function computes the locking code from themachineID based on the lock selector. Note thatevery bit in lock_selector is significant. For instance, if you have a machineID that has valid infor-mation only for the IP address (lock selector is 0x2), then you should pass 0x2 into the lock_selectorparameter. If you pass in any other lock_selector value, a different lockCodewill result.

1.22.3. Returns

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

1.22. VLSmachineIDtoLockCode 47


1.23. VLSmachineIDToLockCodeExClient Server Static Library DLL

√ √ √

Computes the new version lock code.

1.23.1. SyntaxLS_STATUS_CODE VLSmachineIDToLockCodeEx (


unsigned long lock_selector,

char *lockCode,

int lockCodeLen,

int unused );


machineID Themachine ID used to generate lock code.

lock_selector The bit mask defining the different lock criteria to retrieve.

lockCode A pointer to the buffer that receives the lock code string generated for the spec-ified lock selector. An OUT parameter. The caller needs to allocate the requiredmemory.

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

unused Not used.

1.23.2. Description

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

1.23.3. Returns

The status code, LS_SUCCESS, is returned if successful. For a complete list of the error codes, seeLicensing Library Error and Result Codes.


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

VLS_LOCK_SELECTOR_INVALID The specified lock selector is invalid.

VLS_CALLING_ERROR Argument specified is not correct, that is, MachineID or lock-Code is NULL.

If the lockCodeLen is less than VLS_LOCK_CODE_SIZE.

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


VLS_LOCK_CODE_NOT_SUPPORT The specified lock code is currently not supported.

LS_NO_RESOURCES Error occurred in allocating resources needed by this API.

1.23. VLSmachineIDToLockCodeEx 49


1.24. VLSgetServerNameFromHandleClient Server Static Library DLL

√ √ √

1.24.1. SyntaxLS_STATUS_CODE VLSgetServerNameFromHandle (

LS_HANDLE handle_id,

char *outBuf,

int outBufSz );


handle_id The handle returned by LSRequest or VLSrequestExt

outBuf (OUT) User allocated buffer to receive license server name

outBufSz Size of buffer in bytes

1.24.2. Description

This function retrieves the name of license server based on handle_id. A valid handle_id is alwaysobtained as a product of a successful license request. This handle is associated with the license serverthat was contacted for the license request. VLSgetServerNameFromHandle can be used to retrieve thename of the license server which granted the license.

1.24.3. Returns




LS_BADHANDLE Invalid handle.

LS_BUFFER_TOO_SMALL outBuf is smaller than license server’s name that will bereturned.


1.25. VLSinitServerListClient Server Static Library DLL

√ √ √

1.25.1. SyntaxLS_STATUS_CODE VLSinitServerList (

char *serverList,

int optionFlag );


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

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

1.25.2. Description

This function initializes the list of license servers specified in the local subnet. However, if the VLSset-ContactServer 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 mech-anism is preferred to find the license server, then you may provide a predefined server list using thisAPI. 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 priorto calling LSRequest or VLSqueuedRequest.

For example,

VLSinitServerList (

“<ServerAddress1>:<ServerAddress2>:....<ServerAdressN>”,

Optionflag

);

ServerAddress could be ip-address or hostname.

1.25.3. Returns





1.25. VLSinitServerList 51


1.26. VLSgetServerListClient Server Static Library DLL

√ √ √

1.26.1. SyntaxLS_STATUS_CODE VLSgetServerList (

char *outBuf,

int outBufSz );


outBuf (OUT) User allocated buffer to receive license server name

outBufSz Size of buffer in bytes

1.26.2. Description

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

1.26.3. Returns




LS_BUFFER_TOO_SMALL outBuf is smaller than license server’s name that will bereturned.



1.27. VLSinitServerInfoClient Server Static Library DLL

√ √ √

1.27.1. Syntax LS_STATUS_CODE VLSinitServerInfo (



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

1.27. VLSinitServerInfo 53


1.28. VLSsetHostIdFuncClient Server Static Library DLL

√ √ √

Sets the host ID function.

1.28.1. SyntaxLS_STATUS_CODE VLSsetHostIdFunc (

long (*myGetHostIdFunc) ());


myGetHostIdFunc The address of the custom host ID function. In Windows, this mustbe the address returned byMakeProcInst.

1.28.2. Description

This function sets the host ID function for the licensing library to be the function pointed to bymyGe-tHostIdFunc. This enables customization of the host ID locking.

1.28.3. Returns





1.29. VLSsetCustomExFuncClient Server Static Library DLL

√ √ √

Registers your extended custom function that enables locking to custom criteria (up to 64-bytes) withthe licensing library.

1.29.1. SyntaxLS_STATUS_CODE VLSsetCustomExFunc (

long (*pmyGetCustExTableFunc)

(VLScustomEx* pCustomExTable,

unsigned long* pulCount) );


pCustomExTable A pointer to a buffer that receives all custom extended locking criteriaas a VLScustomEx array. It is an OUT parameter and the caller shouldallocate thememory. Also note the following:

n When pCustomExTable is NULL, then set the number of customextended elements in the pulCount parameter.

n When pCustomExTable is not-NULL, then fill up both the pCus-tomExTable and pulCount parameters.

For better understanding, refer to the example given in CustomizingHost ID (Extended Custom).

pulCount An IN/OUT parameter.

n On input, it specifies the count of the VLScustomEx entrypointed to by the pCustomExTable argument. If the buffer is notlarge enough to hold the returned customEx feature table, theAPI sets this argument equal to the required count.

n On output, it specifies the actual count of the VLScustomExobjects that are received through this custom API. Themax-imum size is VLS_MAX_CUSTOMEX_COUNT.

1.29.2. Description

This API function sets the custom function to be the function pointed to by pmyGetCustExTableFuncargument. This enables to get the custom extended locking criteria table as a VLScustomEx array. Theprototype of the function pointed by pmyGetCustExTableFunc argument is as follows:

long myGetCustExTableFunc (

VLScustomEx *pCustomExTable,

unsigned long *pulCount );

1.29. VLSsetCustomExFunc 55


1.29.3. Returns



LS_NORESOURCES An error occurred while allocating memory to the function.

VLS_RESOURCE_LOCK_FAIL-URE

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


1.30. VLSsetBroadcastIntervalClient Server Static Library DLL

√ √ √

Sets the broadcast interval.

1.30.1. SyntaxLS_STATUS_CODE VLSsetBroadcastInterval (

long interval );


interval 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 defaultvalue of interval is 9 seconds.

If a licensed application performs a broadcast to establish the presence of a license server on the sub-net, it makes two broadcast attempts, where the length of the second broadcast attempt is slightlylonger than the first.

1.30.3. Returns





1.30. VLSsetBroadcastInterval 57


1.31. VLSgetBroadcastIntervalClient Server Static Library DLL

√ √ √

Retrieves the broadcast interval.

1.31.1. Syntaxlong VLSgetBroadcastInterval (void);

1.31.2. Description

If a licensed application performs a broadcast to establish the presence of a license server on the sub-net, it makes two broadcast attempts, where the length of the second broadcast attempt is slightlylonger than the first.

1.31.3. Returns

VLSgetBroadcastInterval returns the total length of broadcast attempts.

1.32. VLSsetTimeoutIntervalClient Server Static Library DLL

√ √ √

Sets the timeout interval.

1.32.1. SyntaxLS_STATUS_CODE VLSsetTimeoutInterval (

long interval );


interval 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 notrespond, it re-sends themessage a few times. Each time, the length of the timeout interval is slightlylonger than the previous. VLSsetTimeoutInterval sets the total length of a set of attempts to be inter-val seconds. The default value of interval is 30 seconds. Note that these timeouts are different fromthe broadcast timeouts.

1.32.3. Returns





1.32. VLSsetTimeoutInterval 59


1.33. VLSgetTimeoutIntervalClient Server Static Library DLL

√ √ √

Retrieves the timeout interval.

1.33.1. Syntaxlong VLSgetTimeoutInterval ();

1.33.2. Description

When a licensed application sends a request to a license server and the license server does notrespond, it re-sends themessage a few times. Each time, the length of the timeout interval is slightlylonger than the previous one.

1.33.3. Returns

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

1.34. VLSsetHoldTimeClient Server Static Library DLL

√ √ √

Sets the hold time for licenses.

1.34.1. SyntaxLS_STATUS_CODE VLSsetHoldTime (

char *featureName,

char *version,

int timeInSecs );

Argument DescriptionfeatureName Name of the feature.

version Version of the feature.

timeInSecs Time in seconds. Default: 15 seconds.

1.34.2. Description

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

1.34.3. Returns




Both feature name and version cannot be NULL at the same time.


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

1.34. VLSsetHoldTime 61


1.35. VLScontrolRemoteSessionClient Server Static Library DLL

√ √ √

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

1.35.1. SyntaxLS_STATUS_CODE VLScontrolRemoteSession (

int toCheckRemoteSession );


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) forstand-alone environments.

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

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

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

1.35.3. Returns



VLS_CALLING_ERROR If the input parameter is other than VLS_ON orVLS_OFF.

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

VLS_NOT_SUPPORTED_IN_NET_ONLY_MODE

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


1.36. VLSsetSharedId/ VLSsetTeamIdClient Server Static Library DLL

√ √ √

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

1.36.1. Syntax

In case of a normal license:

LS_STATUS_CODE VLSsetSharedId (

int sharedId,

unsigned long (*mySharedIdFunc) (char * value) );

In case of a capacity license:

LS_STATUS_CODE VLSsetTeamId (

int teamId,

unsigned long (*mySharedIdFunc) (char * value) );


sharedId/ teamId Must be one of the following values:

n VLS_CLIENT_HOST_NAME_IDn VLS_USER_NAME_IDn VLS_X_DISPLAY_NAME_IDn VLS_VENDOR_SHARED_ID

mySharedIdFunc Pointer to a function that fills the sharedID value into the value param-eter. The return type ofmySharedIdFunc is ignored.

1.36.2. Description

VLSsetSharedId/VLSsetTeamId must be used to register a customized sharedID/teamID function withthe licensing library. The value of the sharedIDmust be passed back bymySharedIdFunc through thecharacter buffer. All sharedID character buffers will be truncated to 32 bytes. For instance, a cus-tomized function which returns the host name can be used by the licensing library instead of the built-in function to determine eligibility for sharing a license.

VLSsetSharedId should be used in case of normal license and VLSsetTeamId should be used in case ofcapacity 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.

1.36. VLSsetSharedId/ VLSsetTeamId 63


One of themany flexibility provided by LM licensing is the sharing of same license keys, based on thefollowing criteria:

n User-name based sharing

n Hostname based sharing

n X-display based sharing

n Application-defined sharing

This model is often used by software publishers who do not want to count every instance of a runningapplication. They may allowmultiple instances of a running application to share a single licensetoken/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 requestmade by a client is coming from the same User/Host/X-display or not. If it is so, then it checks with thesharing-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 licenseserver, passes on the information regarding its user-name, client-hostname, x-displayname to thelicense server. This information is kept by the license server in its internal tables for future use. Thenext time a license is requested for the same Feature, the saved information is used to determinewhether 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, x-display, etc.). To use your own functions to retrieve these values, use the VLSsetSharedId function tooverride the default functions.

1.36.3. Returns



VLS_CALLING_ERROR mySharedIdFunc is NULL.

VLS_UNKNOWN_SHARED_ID Invalid sharedId/ teamId; is either negative or exceedsmaximum value.


1.37. VLSsetSharedIdValue/ VLSsetTeamIdValueClient 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 sharedId,

char *sharedIdValue );

In case of a capacity license:

LS_STATUS_CODE VLSsetTeamIdValue (

int teamId,

char *teamIdValue );


sharedId/ teamId Must be one of the following values:

n VLS_CLIENT_HOST_NAME_IDn VLS_USER_NAME_IDn VLS_X_DISPLAY_NAME_IDn 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 cus-tomized sharedId/ teamId value with the licensing library. You can explicitly provide the sharedId/ tea-mId itself using this function. The value of the sharedId/ teamIdmust be passed through thecharacter buffer. All sharedId/ teamId character buffers will be truncated to 32 bytes. If you call bothVLSsetSharedId and VLSsetSharedIdValue/ VLSsetTeamId and VLSsetTeamIdValue, VLSsetSharedId/VLSsetTeamId has priority and the value set by VLSsetSharedIdValue/ VLSsetTeamIdValue will beignored.

The same concept applies to VLSsetSharedIdValue/ VLSsetTeamIdValue function as VLSsetSharedId/VLSsetTeamId function. The difference between VLSsetSharedId/ VLSsetTeamId and VLSset-SharedIdValue/ VLSsetTeamIdValue lies in the fact that VLSsetSharedId/ VLSsetTeamId function willmake the VLSrequestExt internally send different IDs as returned by the Developer-Defined functions,whereas VLSsetSharedIdValue/ VLSsetTeamIdValuewill make the VLSrequestExt send the same ID irre-spective of the fact “who is running the client,” “from where the client is being run,” and so on.

1.37. VLSsetSharedIdValue/ VLSsetTeamIdValue 65


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 byVLSsetSharedIdValue/ VLSsetTeamIdValue function. If neither the developer defined function nor thedeveloper 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



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


1.38. VLSsetGraceRequestFlagClient Server Static Library DLL

√ √ √

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

1.38.1. SyntaxLS_STATUS_CODE VLSsetGraceRequestFlag (

int state );

Argument Direction Data Type Description

state IN int The flag can have any of the following value:

n VLS_ON: This enforces the behavior thatexisted before this API is introduced in thev8.4.0. Which means that the when the con-tact server is set to stand-alonemode:

1. The application looks for a license onthe same system.

2. If a license is not found, then appli-cation looks for a grace license on thesame system.

3. If a grace license not found, it returnserror 18.

4. If a grace license is found then it firstensures that no such feature-versionexists on a license server (using net-work broadcast). In case of failure, itreturns error 18. Else, returns successand use the grace license.

n VLS_OFF: This enforces the following behaviorwhen the contact server is set to stand-alonemode:

n The application looks for a license onthe same system.

n If a license is not found, then appli-cation does not look for a grace licenseon the same system and returns error18.

1.38. VLSsetGraceRequestFlag 67


1.38.2. Description

The API sets the behavior if a grace license can be requested or not when the contact server has beenset to stand-alonemode (no-net). If you call the API with VLS_OFF before requesting a grace license forthe first-time, the grace license related system persistence information is not created on the client. Ifthere grace persistence is already present on the client, the request is still denied with error VLS_NO_SUCH_FEATURE.

1.38.3. Returns


1.39. VLSgetGraceRequestFlagClient Server Static Library DLL

√ √ √

Returns the state if the grace request is enabled or disabled when the contact server has been set tostand-alonemode (no-net).

1.39.1. Syntaxint VLSgetGraceRequestFlag (void);

1.39.2. Description

The API is introduced to complement VLSsetGraceRequestFlag.

1.39.3. Returns


1.39. VLSgetGraceRequestFlag 69


1.40. VLScalculateLicenseHashClient Server Static Library DLL

√ √ √

Calculates the license hash for a given license string.

1.40.1. SyntaxLS_STATUS_CODE VLScalculateLicenseHash (

char *pcLicenseString,

unsigned char *pucLicenseHash,

int *piLicenseHashLength );

Argument Direction Data Type Description

pcLicenseString IN char A pointer to the license string whose hash is tobe calculated.

pucLicenseHash OUT unsigned char A pointer to the location where the license hashis to be stored.If the value passed is NULL, the required lengthfor this buffer is returned to the third argumentpiLicenseHashLength.

piLicenseHashLength IN/OUT int The length of the hash buffer. User needs to allo-catememory.

1.40.2. Description

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

Tip

Make sure you pass a valid license string for calculating license hash. The API cal-culates license hash without validating the license string (whatever is givenagainst the license string parameter is treated as license, and hash is generatedaccordingly).

1.40.3. Returns

The status code VLScg_SUCCESS is returned if successful. Otherwise, it will return the following errorcodes:


VLS_CALLING_ERROR When pcLicenseString and/or piLicenseHashLength arepassed NULL.

LS_BUFFER_TOO_SMALL When piLicenseHashLength is less than VLS_MAX_LICENSE_HASH_LEN.


1.40. VLScalculateLicenseHash 71


1.41. VLSisVirtualMachineClient Server Static Library DLL

√ √ √

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

1.41.1. SyntaxLS_STATUS_CODE VLSisVirtualMachine (

VLSVMInfo *vm_info );


vm_info User allocated structure where the information related to the licenseserver virtualization is obtained.

1.41.2. Description

The structure below obtains information about whether the license server is running on a virtualmachine or not? When LS_SUCCESS is returned, the structure obtains information.

typedef struct vm_info_struct {

long structSz;

VLS_VM_DETECTION_STATE isVirtualMachine;

} VLSVMInfo;

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 errorcodes:


VLS_LIBRARY_NOT_INITIALIZED The licensing library is not initialized. To initialize, call VLSin-itialize.


VLS_CALLING_ERROR The input parameter is NULL.





1.41. VLSisVirtualMachine 73


Local vs. Remote Renewal of License TokensThis 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 bycalling LSUpdate within the period of the license lifetime, unless you are using auto-timers (in thatcase, this will be done automatically for you).

The APIs related to enabling/disabling of a local renewal basically change the time at which an updateis sent to the license server. Unless updates are carried out by setting auto-timers, updating thelicense on the license server has to be carried out manually by the client before the expiration of thelicense lifetime.



VLSdisableLocalRenewal Disables local license renewal.

VLSenableLocalRenewal Resets local license renewal.

VLSisLocalRenewalDisabled Informs you whether or not local updates are enabled.

VLSgetRenewalStatus Returns renewal status.

VLSsetRemoteRenewalTime Sets the remote renewal period.

VLSdisableAutoTimer Disables automatic renewal of one feature.

1.42. VLSdisableLocalRenewalClient Server Static Library DLL

√ √ √

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

1.42.1. Syntax

LS_STATUS_CODE VLSdisableLocalRenewal (void);


1.42.2. Description

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

1.42.3. Returns


1.42.4. See Also

n LSUpdate


1.42. VLSdisableLocalRenewal 75


1.43. VLSenableLocalRenewalClient Server Static Library DLL

√ √ √

Resets the license renewal mechanism to the default.

1.43.1. Syntax

LS_STATUS_CODE VLSenableLocalRenewal (void);


1.43.2. Description

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

1.43.3. Returns


Updates until remote renewal timewill not go to the license server. Updates will be returned locally.Only updates sent after the remote renewal timewill be sent to the license server.

1.43.4. See Also

n LSUpdate


1.44. VLSisLocalRenewalDisabledClient Server Static Library DLL

√ √ √

Informs you whether or not local updates are enabled.

1.44.1. Syntax

VLS_LOC_UPD_STAT VLSisLocalRenewalDisabled (void);


1.44.2. Returns

Returns the following error codes:


VLS_LOCAL_UPD_ENABLE Local renewal is enabled. This is the initial status and thestatus after VLSenableLocalRenewal is called.

VLS_LOCAL_UPD_DISABLE Local renewal is disabled. This is the status after VLSdis-ableLocalRenewal is called.

1.44. VLSisLocalRenewalDisabled 77


1.45. VLSgetRenewalStatusClient Server Static Library DLL

√ √ √

Retrieves license renewal status.

1.45.1. Syntax

LS_STATUS_CODE VLSgetRenewalStatus (void);


1.45.2. Description

Returns the renewal status of the last successful license renewal made using LSUpdate. If the last oper-ation that successfully renewed a license involved contacting the license server, this function returnsVLS_REMOTE_UPDATE. If the last operation that successfully renewed a license did not involve con-tacting the license server (was done locally), this function returns the value VLS_LOCAL_UPDATE. If anupdate has not occurred, it returns VLS_NO_UPDATES_SO_FAR.

1.45.3. Returns

Returns the following status codes:


VLS_NO_LICENSE_GIVEN Generic error indicating that license was not updated.

LS_LICENSETERMINATED Cannot update the license because the license hasalready expired.





VLS_FINGERPRINT_MISMATCH Client-locked; locking criteria does not match.

VLS_APP_NODE_LOCKED Feature is node locked, but the update request wasissued from an unauthorized machine.

VLS_CLK_TAMP_FOUND License server has determined that the client’s systemclock has been modified. The license for this feature hastime-tampering protection enabled, so the license oper-ation is denied.


VLS_VENDORIDMISMATCH The vendor identification of requesting applicationdoes not match the vendor identification of the featurefor which the license server has a license. This erroroccurs only when client is older than version 6.3 elsethe error returned is VLS_NO_SUCH_FEATURE.

VLS_INVALID_DOMAIN The domain of the license server is different from thatof client.







VLS_NO_UPDATES_SO_FAR No updates have been made. Specifies the initial value.

VLS_LOCAL_UPDATE During themost recent update, the license was validand did not need to be renewed.

VLS_REMOTE_UPDATE During themost recent update, the license was invalidand required update from the license server.

1.45. VLSgetRenewalStatus 79


1.46. VLSsetRemoteRenewalTimeClient Server Static Library DLL

√ √ √

Sets the remote renewal time period.

1.46.1. SyntaxLS_STATUS_CODE VLSsetRemoteRenewalTime (

char *featureName,

char *version,

int timeInSecs );


featureName Name of the feature.


timeInSecs Time in seconds. Default time is 15 seconds.

1.46.2. Description

Sets the remote renewal period of licenses issued to the feature to timeInSecs seconds. This functioncall must bemade before the first LSRequest call for it to be applicable. Once a license is requestedusing LSRequest, the remote renewal time is set for that application, and VLSsetRemoteRenewalTimewill not change it.

1.46.3. Returns




Both feature name and version cannot be NULL at the sametime.


VLS_CALLING ERROR An error occurred in the use of an internal buffer.


1.47. VLSdisableAutoTimerClient Server Static Library DLL

√ √ √

1.47.1. SyntaxLS_STATUS_CODE VLSdisableAutoTimer (

LS_HANDLE lshandle,

int state );


lshandle The handle returned by LSRequest or VLSrequestExt

state VLS_ON or VLS_OFF

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

1.47.2. Description

Using the handle returned from requesting a license, a call to this function can be used to disable auto-matic renewal of one feature. Calling with an argument of zero handle disables auto renewal of all fea-tures.

On UNIX, call VLSdisableAutoTimer before using sleep or SIGALRM, or there could be a potential con-flict with the timer signal. On Win32, call VLSdisableAutoTimer if thread has no message loop since themessage loop is used to process the timer. If you disable the automatic timer, you must ensure thatthe license key is renewed periodically (before it expires) by calling LSUpdate.

1.47.3. Returns



VLS_CALLING_ERROR Invalid state. Needs to be either VLS_ON or VLS_OFF



1.47. VLSdisableAutoTimer 81


The Client Query FunctionsThis section describes the API functions that return information about licenses, client features andhandles.



VLSgetLicenseInfo Retrieves information about non-capacity licenses available in thelicense server.

VLSgetLicenseInfoExt Retrieves information for both capacity and non-capacity licensesavailable in license server.

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

VLSgetHandleInfo Returns information about a client given a handle.

VLSgetActiveHandleList Retrieves the list of currently active client handles.

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

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

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;



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

structSz Size of VLSlicenseInfo structure.

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

version Feature version. Maximum 11 characters.

lic_type The type of license, either trial or normal.

trial_days_count

The number of trial days.

birth_day The day of the license start date.

death_day The timewhen the feature expires. The constant, VLS_NO_EXPIRATION, is returned ifthe license does not have any expiration date.

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

is_node_locked

Depending on the locking scheme of the feature, this returns one of the following con-stants:

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

concurrency Unused

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

n VLS_NO_SHARINGn VLS_USER_NAME_IDn VLS_CLIENT_HOST_NAME_IDn VLS_X_DISPLAY_NAME_IDn VLS_VENDOR_SHARED_ID

Member Description

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

n VLS_LOCK_ID_PROMn VLS_LOCK_IP_ADDRn VLS_LOCK_DISK_IDn VLS_LOCK_HOSTNAMEn VLS_LOCK_ETHERNETn VLS_LOCK_PORTABLE_SERVn VLS_LOCK_CUSTOMn VLS_LOCK_CUSTOMEXn VLS_LOCK_CPUn VLS_LOCK_HARD_DISK_SERIALn VLS_LOCK_CPU_INFOn VLS_LOCK_UUID

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

n VLS_HOLD_NONE (no held licenses).n VLS_HOLD_VENDOR (the hold time specified through the VLSsetHoldTime func-

tion).n VLS_HOLD_CODE (the license code specifies the hold time).

num_subnets The number of subnet specifications provided for the site.

site_license_info

A space-separated list of subnet wildcard specifications.

hold_time The holdtime specified for licenses issued for this feature.

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

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

key_life_time The license lifetime for this feature (in seconds).

sharing_limit The limit on howmany copies 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 VLS_STANDALONE_MODE - for a stand-alone licensen VLS_NETWORK_MODE - for a network licensen VLS_PERPETUAL_MODE - for a repository license

check_time_tamper

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

is_additive Returns VLS_TRUE if this is an additive license or VLS_FALSE if this is an exclusivelicense.

The license type as any of the following:

n VLS_ADDITIVE - for an additive license



Member Description

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

isRedundant Validates if the license is actually redundant.

majority_rule Checks whether majority rule is on or off.

num_servers The number of redundant license servers.

isCommuter Checks whether commuter licenses are allowed or not.

log_encrypt_level

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

elan_key_flag Unused.

conversion_time

Unused.

server_lock-ing_info

Stores the server locking information.

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

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

capacity The total capacity of the license.

commuter_max_check-out_days

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

grace_period_flag

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

n VLS_NO_GRACE_PERIOD - grace period not allowed (default)n VLS_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 180days.

grace_period_elapsed_hours

The number of hours the grace period will last for. It can be a value between 1 to 1440hours.

overdraft_flag Not supported.

overdraft_hours

Not supported.

overdraft_users

Not supported.

Overdraft_users_in_use

The number of overdraft users currently using the application.

local_request_lockcrit_flag

The flag that sets the local license request locking criteria.

local_request_lockcrit_required

The necessary number of locking license criteria that must bemet for making thelicenses available to a local client.

Member Description

local_request_lockcrit_float

The desired number of locking license criteria that must bemet for making thelicenses available to a local client.

local_request_lockcrit_min_num

Theminimum number of locking license criteria that must bemet for making thelicenses 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" criteriacan be any 2 of the above.

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

license_ver-sion

The Sentinel RMS license version. The possible values are:

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

defined

trial_elapsed_hours

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

trial_execution_count

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

plain_vendor_info

The information that a vendor wants to share with the end-customers.This value willappear unencrypted in readable/ concise readable license code. Themaximum lengthof the string can be up to 395 characters.

license_hash The license hash identifier for a license code.

license_stor-age

The file location where the license is stored.

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

license_prec-edence

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

trial_calendar_period_left

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

trial_elapsed_period_left

The number of seconds left in the trial elapsed time period. Valid only if elapsed timeis being enforced.

trial_executions_left

The number of executions left in the trial license. Valid only if executions are beingmeasured.

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 thetrial period has not yet begun.



Member Description

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

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

1.49. VLSgetLicenseInfoClient Server Static Library DLL

√ √ √

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

1.49.1. SyntaxLS_STATUS_CODE VLSgetLicenseInfo (

unsigned char *feature_name,


int feature_index,

unsigned char *license_hash,

int license_hash_len,

int license_index,

VLSlicenseInfo *license_info);


feature_name The feature name identifier for the license code.

version The version identifier for the license code.

feature_index Used to specify a particular feature-version combination.

license_hash The license hash identifier for a specific license code.

license_hash_len The license hash length.

license_index Used to specify index of a particular license for a specific feature-version com-bination.

license_info The structure in which information fetched will be stored by this API. The callershould allocate thememory for this structure.

1.49.2. Description

This API obtains information of all the licenses, of a specific feature-version combination, loaded in thememory. The license_index argument should be used in a loop to get information of the licenses of aspecific feature-version combination. So long the license_index is valid, the API will return the LS_SUC-CESS status code. Otherwise, it will return the VLS_NO_MORE_LICENSES status code. You can alsoloop 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_indexand 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 returnedare:




VLS_NO_MORE_FEATURES Finished retrieving all the features added.

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

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


VLS_APP_UNNAMED If:

n The feature_name is NULL or feature_name containsonly NULL character i.e '\0' and feature_index is lessthan zero

n The feature_name is not NULL and version is NULL.

VLS_CALLING_ERROR Argument specified is not correct, that is, one of the fol-lowing reasons exist:

n If license_info is NULL.n If license_hash is NULL and license_index is less than

0.n If license_hash is not NULL and license_hash_len < 1.n If license_hash is not NULL and license_hash_len >

VLS_MAX_LICENSE_HASH_LEN.n If feature_name or version buffer size exceeds the

maximum size limit specified as VLS_MAXFEALENand VLS_MAXVERLEN respectively.

n When the structSz field of the VLSlicenseInfo structis not set to the size of VLSlicenseInfo.

VLS_NO_SUCH_FEATURE License with passed feature-version combination notfound.

VLS_MULTIPLE_VENDORID_FOUND This occurs when more than one licenses for the specifiedFeature/Version is available on the License server, but theVendor ID for all these licenses is different from the licens-ing library's Vendor ID.


VLS_NORESOURCES Error occurred in allocating resources needed by this API.

VLS_NO_SUCH_LICENSE License with passed feature-version-license hash com-bination not found.



VLS_BAD_SERVER_MESS AGE Message from license server could not be understood.

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


1.50. VLSgetLicenseInfoExtClient Server Static Library DLL

√ √ √

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

1.50.1. SyntaxLS_STATUS_CODE VLSgetLicenseInfoExt (



unsigned long *capacity

int feature_index,



int license_index,

VLSlicenseInfo *license_info );



version The version identifier for the license code.

capacity The capacity value for the license code.


license_hash The license hash identifier for a specific license code.

license_hash_len The license hash length.

license_index Used to specify index of a particular license for a specific feature-version com-bination.

license_info The structure in which information fetched will be stored by this API. The callershould allocate thememory for this structure.

1.50.2. Description

The API retrieves license information for both capacity and non-capacity licenses that are available onthe license server.

If feature_name, version and capacity parameters are not NULL, then information about the licensesas 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 andthe 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 cor-responding 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.3. Returns



VLS_NO_MORE_FEATURES Finished retrieving all the available features on the license server.

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

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


VLS_APP_UNNAMED If:

n The feature_name is NULL or feature_name containsonly NULL character i.e '\0' and feature_index is lessthan zero

n The feature_name is not NULL and version is NULL.


n If license_info is NULL.n If license_hash is NULL and license_index is less than

0.n If license_hash is not NULL and license_hash_len < 1.n If license_hash is not NULL and license_hash_len >

VLS_MAX_LICENSE_HASH_LEN.n If feature_name or version buffer size exceeds the

maximum size limit specified as VLS_MAXFEALENand VLS_MAXVERLEN respectively.

n When the structSz field of the VLSlicenseInfo structis not set to the size of VLSlicenseInfo.


VLS_MULTIPLE_VENDORID_FOUND This occurs when more than one licenses for the specifiedFeature/Version is available on the License server, but theVendor ID for all these licenses is different from the licens-ing library's Vendor ID.





1.50. VLSgetLicenseInfoExt 93





VLS_NOT_SUPPORTED_IN_NONET_MODE

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


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

1.51.1. Syntaxtypedef struct client_info_struct {

char user_name[VLS_MAXLEN];

unsigned long host_id;

char group[VLS_MAXLEN];

long start_time;

long hold_time;

long end_time;

long key_id;


char x_display_name[VLS_MAXLEN];

char shared_id_name[VLS_MAXLEN];

int num_units;

int q_wait_time;

int is_holding;

int is_sharing;

int is_commuted;

long structSz;

unsigned long team_capacity;

unsigned long total_resv_team_capacity;

unsigned long reserved_team_capacity_in_use;

unsigned long unreserved_team_capacity_in_use;

unsigned long user_capacity_from_reserved;

unsigned long user_capacity_from_unreserved;

int total_team_tokens_resv;

int reserved_team_tokens_in_use;

int unreserved_team_tokens_in_use;

} VLSclientInfo;

Member Description

user_name The login name of the user using the application, whereMAXLEN isset to 64 characters. This information can be changed using theVLSsetSharedId API call.In case of stand-alone licensing, the “default-sharing-ID” string willbe returned.

host_id The host ID of the computer on which the user is working. This canbe changed using the VLSsetHostIdFunc call.

group Name of the reserved group to which the user belongs, whereMAX-



Member Description

LEN is set to 64 characters. If the user does not belong to an explicitlynamed group, DefaultGrp is returned.

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

hold_time Specifies the hold time, in seconds, if any.

end_time The time at which the user’s current license will expire if notrenewed.

key_id The internal ID of the license currently issued to the user’s appli-cation. After starting up, the license server issues licenses withunique IDs until it is restarted.

host_name Name of the host/computer where the user is running the appli-cation, whereMAXLEN is set to 64 characters. This information canbe changed using the VLSsetSharedId API call.In case of stand-alone licensing, the “default-sharing-ID” string willbe returned.

x_display_ name Name of the X display where the user is displaying the application,whereMAXLEN is set to 64 characters. This information can bechanged using the VLSsetSharedId API call.In case of stand-alone licensing, the “default-sharing-ID” string willbe returned.

shared_id_ name A special vendor-defined ID that can be used for license sharing deci-sions. It always has the fixed value, default-sharing-ID, unless it ischanged by registering a custom function using the VLSsetSharedIdAPI call. If you plan to use this ID, you should register your own func-tion from your application, and choose Application-defined sharingwhile running the code generator. Themaximum length of the stringis set to 64 characters.In case of stand-alone licensing, the “default-sharing-ID” string willbe returned.

num_units Number of units consumed by the client so far.

q_wait_time Unused.

is_holding Has the value, VLS_TRUE, if the user’s current license is being heldafter its expiration. Otherwise, the value is VLS_FALSE.

is_sharing Total number of clients sharing this particular license, including thecurrent client being queried. If sharing is disabled, is_sharing will be0.

is_commuted Total number of clients that have “checked out” a license from thenetwork.

structSz Size of VLSclientInfo structure.

team_capacity Total capacity of the team.

total_resv_team_capacity Total capacity reserved for the team.

Member Description

reserved_team_capacity_in_ use

Capacity given to clients from reserved capacity.

ureserved_team_capac-ity_in_use

Capacity given to clients from unreserved capacity.

user_capacity_from_reserved

Capacity given to users from reserved capacity.

user_capacity_from_unre-served

Capacity given to users from unreserved capacity.

total_team_tokens_resv Total reserved units.

reserved_team_tokens_in_ use

Units given to teams from reserved pool.

unreserved_team_tokens_in_use

Units given to teams from unreserved pool.



1.52. VLSgetClientInfoClient Server Static Library DLL

√ √ √

Returns information about a client feature.

1.52.1. SyntaxLS_STATUS_CODE VLSgetClientInfo (

char *featureName,

char *version,

int index,

char *unused1,

VLSclientInfo *clientInfo );


featureName Name of the feature. An IN parameter.

version Version of the feature. An IN parameter.

index Used to specify a particular client. An IN parameter.


clientInfo (out) The structure in which information will be returned. Space allocated bycaller. An OUT parameter.

1.52.2. Description

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

1.52.3. Returns



VLS_APP_UNNAMED n featureName is NULLn version is NULLn Both feature name and version cannot be NULL at

the same time.

VLS_CALLING_ERROR n clientInfo parameter is NULL


n index is negative.n Attempted to use stand-alonemodewith network-


VLS_NO_MORE_CLIENTS Finished retrieving client information for all clients.

VLS_NO_SUCH_FEATURE License server does not have a license that matchesrequested feature and version.

VLS_MULTIPLE_VENDORID_ FOUND The license server has licenses for the same feature and ver-sion from multiple vendors. It is ambiguous which featureis requested.

VLS_NO_SERVER_UNNING License server on specified host is not available for proc-essing license operation requests.








1.52. VLSgetClientInfo 99


1.53. VLSgetHandleInfoClient Server Static Library DLL

√ √ √

Returns information about a client feature.

1.53.1. SyntaxLS_STATUS_CODE VLSgetHandleInfo (

LS_HANDLE lshandle,

VLSclientInfo *clientInfo );


lshandle The handle returned by LSRequest or VLSrequestExt

clientInfo (out) The structure in which information will be returned. Space allocated bycaller.

1.53.2. Description

This function also retrieves client information, except that lshandle replaces the arguments (fea-tureName, version, and index) used in VLSgetClientInfo.

1.53.3. Returns



VLS_BAD_HANDLE Invalid handle. Handlemay have already been released anddestroyed from previous license operations or too many handleshave already been allocated.


1.54. VLSgetActiveHandleListClient Server Static Library DLL

√ √ √

Retrieves the list of currently active client handles.

1.54.1. SyntaxLS_STATUS_CODE VLSgetActiveHandleList (

LS_HANDLE *out_handle_buf,

unsigned long * num_handle );


out_handle_buf The allocated buffer where API will store the handles. The caller mustallocate memory.

num_handle The number of LS_HANDLE elements for which thememory 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_han-dle_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 ele-ment 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 orstatus codes:


VLS_NO_ACTIVE_HANDLE This indicates that no active client handles exist.

VLS_CALLING_ERROR The argument specified is not correct, that is, num_handle isNULL.

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




1.54. VLSgetActiveHandleList 101


1.55. VLSgetLastErrorStatusFromHandleClient Server Static Library DLL

√ √ √

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

1.55.1. SyntaxLS_STATUS_CODE VLSgetLastErrorStatusFromHandle (

LS_HANDLE lshandle,

LS_STATUS_CODE *status );


lshandle The client handle identifier.

status The last return status for the specified handle.

1.55.2. Description

This API function is used to obtain the last error/status code returned for a specified license handle.This may be helpful in following scenarios:

To get information on the license handles whose trial license has exhausted but the license handle isnot yet released by the application.

To retrieve the update status for active client handles when auto-update process is used.

1.55.3. Returns



VLS_CALLING_ERROR If the error_status parameter is specified as NULL.



LS_BADHANDLE This error is returned of if an invalid handle is passed to the APIfunction. The license is invalid if it is already released, or hasnever been initialized/allocated.


1.56. VLSgetLicInUseFromHandleClient Server Static Library DLL

√ √ √

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

1.56.1. SyntaxLS_STATUS_CODE VLSgetLicInUseFromHandle (

LS_HANDLE lshandle,

int *totalKeysIssued );


lshandle The handle returned by any Request API call.

totalKeysIssued The number of licenses issued by the license server. Space should be allo-cated by the caller.

1.56.2. Description

Given a valid handle returned by an LSRequest call or its variants, it returns the total number oflicenses issued by the license server for the feature name and version used to obtain this handle. Theinformation in the handle is not updated subsequently. For more information, useVLSgetFeatureInfo.

1.56.3. Returns



LS_BADHANDLE Invalid handle. Handle has already been released anddestroyed from previous license versions or too many han-dles have been allocated.

LS_BUFFER_TOO_SMALL in_use_ p parameter is NULL.


1.56. VLSgetLicInUseFromHandle 103


The Feature Query FunctionsGiven below is the list of the API functions:


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

VLSgetVersions Retrieves licensed version information for a feature.

VLSgetFeatureFromHandle Returns the feature name corresponding to the handle.

VLSgetVersionFromHandle Returns the version corresponding to the handle.

VLSgetTimeDriftFromHandle Returns the difference in seconds between the estimatedcurrent time on the license server and the estimated timeon the client.

VLSgetFeatureTimeLeftFromHandle Returns the difference in seconds between the estimatedcurrent time on the license server and the estimated fea-ture expiration time on the license server.

VLSgetKeyTimeLeftFromHandle Returns the difference in seconds between the estimatedcurrent time on the license server and the estimatedlicense expiration time on the license server

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



1.57.1. Syntaxtypedef 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 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];

int capacity_flag;


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 isGraceLicense;

int license_version;

char plain_vendor_info;


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 Description

structSz Size of VLSfeatureInfo structure.

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


lic_type Type of license either trial or normal.

trial_days_count

Number of trial days.

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

death_day The timewhen the feature expires. The constant VLS_NO_EXPIRATION isreturned if the license does not have any expiration date.

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

total_resv Number of licenses reserved using group reservations.

lic_from_resv Number of reserved licenses issued to clients.



Member Description

qlic_from_free_pool

Number of unreserved licenses issued to queued clients.

is_node_locked

Depending on the locking scheme of the feature, this returns one of the followingconstants:

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

concurrency Unused.

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

n VLS_NO_SHARINGn VLS_USER_NAME_IDn VLS_CLIENT_HOST_NAME_IDn VLS_X_DISPLAY_NAME_IDn VLS_VENDOR_SHARED_ID

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

n VLS_LOCK_ID_PROMn VLS_LOCK_IP_ADDRn VLS_LOCK_DISK_IDn VLS_LOCK_HOSTNAMEn VLS_LOCK_ETHERNETn VLS_LOCK_PORTABLE_SERVn VLS_LOCK_CUSTOMn VLS_LOCK_CUSTOMEXn VLS_LOCK_CPUn VLS_LOCK_HARD_DISK_SERIALn VLS_LOCK_CPU_INFO n VLS_LOCK_UUID

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

n VLS_HOLD_NONE (no held licenses).n VLS_HOLD_VENDOR (the client specifies the hold time through the func-

tion, VLSsetHoldTime).n VLS_HOLD_CODE (the license code specifies the hold time).

hold_time The hold time specified for licenses issued for this feature.


site_license_info

A space-separated list of subnet wildcard specifications.

meter_value Unused.

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

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

Member Description

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


sharing_limit The limit on howmany copies of the licensed application can share the samelicense.

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 VLS_STANDALONE_MODE - for a stand-alone licensen VLS_NETWORK_MODE - for a network licensen VLS_PERPETUAL_MODE - for a repository license

check_time_tamper

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

is_additive Returns VLS_TRUE if this is an additive license or VLS_FALSE if this is an exclusivelicense.

The license type as any of the following:

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



num_servers Number of redundant license servers.

isCommuter Commuter licenses.

log_encrypt_level

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

avg_queue_time

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

queue_length Length of the queue.

tot_lic_reqd Required number of licenses for all queued clients.

commuted_keys

Number of commuter keys that have been checked out.

commuter_keys_left

Number of computer keys left.

server_lock-ing_info

Stores the server locking information.

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

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



Member Description

capacity Total capacity of the license.

total_resv_capacity

Total reserved capacity.

in_use_capac-ity_from_reserved

Capacity given to clients from reserved capacity.

in_use_capac-ity_from_unre-served

Capacity given to clients from unreserved capacity.

commuter_max_check-out_days

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

grace_period_flag

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

n VLS_NO_GRACE_PERIOD - grace period not allowed (default)n VLS_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 to180 days.

grace_period_elapsed_hours

The number of hours the grace period will last for. It can be a value between 1 to1440 hours.

lic_from_free_pool

Number of unreserved licenses issued to clients.


overdraft_hours

Not supported.

overdraft_users

Not supported.

overdraft_users_in_use

Not supported.

local_request_lock-crit_flag

The flag that sets the local license request locking criteria.

local_request_lock-crit_required

The necessary number of locking license criteria that must bemet for making thelicenses available to a local client.

local_request_lock-crit_float

The desired number of locking license criteria that must bemet for making thelicenses available to a local client

local_request_lock-crit_min_num

Theminimum number of locking license criteria that must bemet for making thelicenses available to a local client.For example, the “required” criteria can be disk ID, the “floating” criteria can beethernet card and CID key, and the “minimum” criteria can be any 2 of the

Member Description

above.

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

license_ver-sion

The Sentinel RMS license version. The possible values are:

n VLS_LICENSE_VERSION_850 - For Sentinel RMS 8.5.0 licensesn VLS_LICENSE_VERSION_840 - For Sentinel RMS 8.4.0 and 8.4.1 licensesn VLS_LICENSE_VERSION_823 - For Sentinel RMS 8.2.3 licensesn VLS_LICENSE_VERSION_810 - For Sentinel RMS 8.1.x, 8.2.0, 8.2.1, 8.2.2

licensesn VLS_LICENSE_VERSION_800 - For Sentinel RMS 8.0.x licensesn VLS_LICENSE_VERSION_7301 - For Sentinel RMS 7.3.0.1 licensesn VLS_LICENSE_VERSION_730 - For Sentinel RMS 7.3.0 licensesn VLS_LICENSE_VERSION_700 - For Sentinel RMS 7.0.0 licensesn VLS_LICENSE_VERSION_TOO_OLD - For licenses older than Sentinel RMS

7.0.0n VLS_LICENSE_VERSION_LATEST - For the latest version of Sentinel RMS

licensesn VLS_LICENSE_VERSION_NOT_DEFINED -When the license version is not

defined

plain_ven-dor_info

The public vendor information included in the license.

trial_elapsed_hours

The number of hours for which the trial license is used so far.

trial_execution_count

Themaximum limit of the executions count of a trial license.

trial_cal-endar_period_left

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

trial_elapsed_period_left

The number of seconds left in the trial elapsed time period. Valid only if elapsedtime is being enforced.

trial_executions_left

The number of executions left in the trial license. Valid only if executions are beingmeasured.

trial_current_status

Can be any of the following:

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

n VLS_TRIAL_ACTIVE - License is requested at least once,but some trialusage 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.



1.58. VLSgetFeatureInfoClient Server Static Library DLL

√ √ √

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

1.58.1. SyntaxLS_STATUS_CODE VLSgetFeatureInfo (

char *name,

char *version,

int index,

char *unused1,

VLSfeatureInfo *featureInfo );


name Name of the feature. Maximum of 64 characters, including NULL terminationcharacter.


index Used to specify a particular client.


featureInfo (out) The structure in which information will be returned. Spacemust be allocatedby caller.

1.58.2. Description

Returns information on all features. You will need to initialize the structSz field of the VLSfeatureInfostructure 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 usedin a loop as described for the function call, VLSgetClientInfo. Refer to the source code of the lsmon.cutility for additional information.

VLSgetFeatureInfo returns the status code, VLS_NO_MORE_FEATURES, when it runs out of featuresto 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



VLS_CALLING_ERROR n featureInfo is NULLn index is negative


n Attempted to use stand-alonemodewith network onlylibrary, or network modewith stand-alone library.

n When max feature name length exceeds 64 characters.

VLS_APP_UNNAMED version is NULL when name is non_NULL.

VLS_NO_MORE_FEATURES Finished retrieving feature information for all features onlicense server.




VLS_NO_SERVER-FILE No license server has been set and unable to determine whichlicense server to use.





1.58. VLSgetFeatureInfo 113


1.59. VLSgetVersionsClient Server Static Library DLL

√ √ √

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

1.59.1. SyntaxLS_STATUS_CODE VLSgetVersions (

char *featureName,

int bufferSize,

char *versionList,

char *unused1 );


featureName Name of the feature.

bufferSize Specifies the size of versionList.

versionList (out) An array containing the version list. Space should be allocated by the caller.


1.59.2. Description

This function returns a list of versions separated by spaces in the array, versionList. Space for thisarray 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 softwareand you wish to implement version-based licensing schemes.

1.59.3. Returns



VLS_NO_SUCH_FEA-TURE

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

VLS_APP_UNNAMED featureName is NULL.

VLS_CALLING_ERROR Attempted to use stand-alonemodewith network only library, or net-work modewith stand-alone library.

VLS_NO_SERVER_ RUN-NING

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

VLS_NO_SERVER_RESPONSE

Communication with license server has timed out.




VLS_BAD_SERVER_MES-SAGE

Message from license server could not be understood.

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

LS_BUFFER_TOO_SMALL

An error occurred in the use of an internal buffer.

LS_NORESOURCES An error occurred in attempting to allocatememory needed by func-tion.


1.59. VLSgetVersions 115


1.60. VLSgetFeatureFromHandleClient Server Static Library DLL

√ √ √

Returns the feature name corresponding to handle.

1.60.1. SyntaxLS_STATUS_CODE VLSgetFeatureFromHandle (

LS_HANDLE handle,

char *buffer,

int bufferSize );


handle Handle returned by license request API.

buffer (out) Buffer to hold the feature name. Space allocated by caller.

bufferSize Size of the buffer.

1.60.2. Description

The feature name is returned in bufferwhich must be allocated by the calling program. The size ofbuffer is passed in the argument bufferSize.

1.60.3. Returns




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


1.61. VLSgetVersionFromHandleClient Server Static Library DLL

√ √ √

Returns the version corresponding to handle.

1.61.1. SyntaxLS_STATUS_CODE VLSgetVersionFromHandle (

LS_HANDLE handle,

char *buffer,

int bufferSize );


handle Handle returned by LSRequest or VLSrequestExt.

buffer (OUT) Buffer to hold the feature version. Space allocated by caller.


1.61.2. Description

The feature version is returned in bufferwhich must be allocated by the calling program. The size ofbuffer is passed in the argument, bufferSize.

1.61.3. Returns




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


1.61. VLSgetVersionFromHandle 117


1.62. VLSgetTimeDriftFromHandleClient Server Static Library DLL

√ √ √

1.62.1. SyntaxLS_STATUS_CODE VLSgetTimeDriftFromHandle (

LS_HANDLE lshandle,

long *secondsServerAheadOfClient );


lshandle Handle returned by LSRequest, VLSrequestExt, or VLSqueued-Request.

secondsServerAheadOf Client Caller allocates memory for *out* data. Function returns the dif-ference 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 returnsthe difference in seconds between the estimated current time on the license server and the estimatedtime 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




LS_BUFFER_TOO_SMALL secondsServerAheadOfClient parameter is NULL.


1.63. VLSgetFeatureTimeLeftFromHandleClient Server Static Library DLL

√ √ √

1.63.1. SyntaxLS_STATUS_CODE VLSgetFeatureTimeLeftFromHandle (

LS_HANDLE lshandle,

unsigned long *secondsUntilTheFeatureExpires );


lshandle Handle returned by LSRequest or VLSrequestExt.

secondsUntilTheFeatureExpires

Caller allocates memory for *out* data. Function returns the numberof 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 returnsthe difference in seconds between the estimated current time on the license server and the estimatedfeature expiration time on the license server.


VLSgetFeatureTimeLeftFromHandle provides the difference between the License Expiration Time andthe 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 willreturn 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




VLS_NO_SUCH_FEATURE License server does not have a license that matches the requestedfeature, version and capacity.

LS_BUFFER_TOO_SMALL secondsUntilTheFeatureExpires is NULL.

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

VLS_NO_SERVER_RESPONSE Communication with the license server has timed out.


1.63. VLSgetFeatureTimeLeftFromHandle 119




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

LS_NO_NETWORK Generic error indicating that the network is unavailable for licens-ing.

LS_NORESOURCES An error occurred in attempting to allocatememory needed.


1.64. VLSgetKeyTimeLeftFromHandleClient Server Static Library DLL

√ √ √

1.64.1. SyntaxLS_STATUS_CODE VLSgetKeyTimeLeftFromHandle (

LS_HANDLE lshandle,

unsigned long *secondsUntilTheKeyExpires );



secondsUntilTheFeature Expires Caller allocates memory for *out* data. Function returns thenumber 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 returnsthe difference in seconds between the estimated current time on the license server and the estimatedlicense expiration time on the license server.


VLSgetkeyTimeLeftFromHandle returns the difference between the timewhen the license token (asissued by the license server to the client) expires (i.e., before this client must do an LSupdate) and thecurrent time. Since the information in the handle is not updated at regular intervals, the valuereturned by this call is in very close proximity to the key lifetimementioned in the license. For exam-ple, if the token lifetimementioned in the license is 2minutes, the value returned by this call will beapproximately 120. Naturally, this value varies with each client.

1.64.3. Returns




LS_BUFFER_TOO_SMALL secondsUntilTheKeyExpires parameter is NULL.


1.64. VLSgetKeyTimeLeftFromHandle 121


The Client Utility FunctionsThis section describes the API functions that provide client library capabilities useful to certain spe-cialized applications.



VLSdiscover Retrieves the names of the computers on the local subnet (orbeyond) running the Sentinel RMS license server which areauthorized to service requests from an application.

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

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

VLSdeleteFeature Removes licensing information from the license server’s internaltables.

VLSdeleteLicenseFromFile Deletes a non-capacity license from the license server's memoryand file.

VLSdeleteLicenseFromFileExt Deletes both capacity and non-capacity licenses from the licenseserver's memory and file.

VLSgetLibInfo Retrieves information about the Sentinel RMS client library.

VLSshutDown Shuts down the license server.

1.65. VLSdiscoverClient Server Static Library DLL

√ √ √

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

1.65.1. SyntaxLS_STATUS_CODE VLSdiscover (



unsigned char *reserved1,

int server_list_len,

char *server_list,

int optionFlag,

char *query_list );


feature_name Name of the feature.


reserved1 Use any value.

server_list_len Specifies the size of server_list.

server_list (OUT) Space separated list of license server names.

optionFlag A three bit flag which guides the behavior ofVLSdiscover in finding thelicense servers. Details are discussed later.

query_list A colon separated list of hostNames to be queried during the search forlicense servers.

1.65.2. Description

feature_name, must be licensed by the same vendor as the library issuing the VLSdiscover call. If ver-sion is NULL, it is treated as a wildcard and all license servers that are authorized to service requests forfeature_namewill respond regardless of version. If feature_name is NULL, version will be ignored andall Sentinel RMS license servers on the local subnet will respond. The space-separated name list of theresponding Sentinel RMS license servers are returned in server_list. The buffer must be allocated priorto 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 thesearch for license servers.

optionFlag is a three-bit flag which can have any of the following values or a combination of them:



n VLS_DISC_NO_USERLIST - Does not check the host list specified by the user. By default, it firstchecks the LSFORCEHOST environment variable. If LSFORCEHOST doesn’t exist, it reads thelist 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 com-bined list are queried during search for license servers.

n VLS_DISC_RET_ON_FIRST - If the combined query list is NULL, this function returns as soon asit contacts a license server and returns the name of this license server in server_list. Other-wise, it returns when it hears from a license server whose name is listed in the combinedquery list. In this case, it returns, in server_list, that particular license server name along withall other license servers which are not on the list, but responded by that time. If this option isnot specified, this function, VLSdiscover, obtains all the names of all the license servers whichresponded.

n VLS_DISC_PRIORITIZED_LIST - Treats the combined query list as a prioritized one, the left-most being the highest priority host. After execution, server_list contains license serverssorted by this priority. If this option is not specified, the combined query list is treated as arandom one.

n VLS_DISC_DEFAULT_OPTIONS/VLS_DISC_NO_OPTIONS - Use these if you do not want to spec-ify any flags.

1.65.3. Returns

The status code LS_SUCCESS is returned if stand-alone library is used. Otherwise, it will return the fol-lowing error codes:


VLS_NO_RESPONSE_ TO_BROADCAST

No license servers have responded.

LS_NO_SUCCESS Failed to retrieve computer names on local subnet.

LS_NORESOURCES An error occurred in attempting to allocatememory needed by thisfunction.

1.65.4. Examples

To get a list of all the Sentinel RMS license servers running on the subnet, the call can bemade 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.

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



1.66. VLSaddFeatureClient Server Static Library DLL

√ √ √

Adds licensing information about a feature.

1.66.1. SyntaxLS_STATUS_CODE VLSaddFeature (

unsigned char *licenseString,


LS_CHALLENGE *unused2 );


licenseString String containing licensing information.



1.66.2. Description

Dynamically adds the license code, licenseString, to the license server’s internal tables. If licensinginformation for this feature and version already exists in the license server’s tables, it may be over-written with the new information.

The feature is not permanently added to the license server, therefore the feature will not be on thelicense server when the license server is shutdown and restarted.

1.66.3. Returns



VLS_CALLING_ERROR Attempted to use stand-alonemodewith network onlylibrary, or network modewith stand-alone library.

LS_NO_SUCCESS licenseString is NULL.

VLS_ADD_LIC_FAILED Generic error indicating the feature has not been added.

VLS_NO_SERVER_RUNNING License server on specified host is not available for proc-essing the license operation requests.





VLS_BAD_SERVER_MESSAGE Message returned by the license server could not be under-stood.

LS_NO_NETWORK Generic error indicating that the network is unavailable inservicing the license operation.





1.67. VLSaddFeatureToFileClient Server Static Library DLL

√ √ √

Adds licensing information about a feature.

1.67.1. SyntaxLS_STATUS_CODE VLSaddFeatureToFile (






licenseString String containing licensing information.




1.67.2. Description

Dynamically adds licensing information about a feature to the license server’s internal tables. If licens-ing information for this feature already exists in the license server’s tables, it may be overwritten withthe new information.

The feature is permanently added to the license server, therefore the feature will be on the licenseserver when the license server is shutdown and restarted.

1.67.3. Returns



VLS_CALLING_ERROR Attempted to use stand-alonemodewith network only library, ornetwork modewith stand-alone library.

LS_NO_SUCCESS licenseString is NULL.


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






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

LS_NORESOURCES An error occurred in allocating memory needed by the function.




1.68. VLSdeleteFeatureClient Server Static Library DLL

√ √ √

Deletes licensing information about a feature.

1.69. SyntaxLS_STATUS_CODE VLSdeleteFeature (






featureName Name of the feature. Maximum of 64 characters, including NULL ter-mination character.


unused2 Unused.

unused3 Unused.

1.69.1. Description

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

1.69.2. Returns



VLS_APP_UNNAMED n featureName is NULLn version is NULL.n Both feature name and version cannot be NULL at

the same time.



VLS_DELETE_LIC_FAILED Generic error indicating the feature has not been deleted.

VLS_VENDORIDMISMATCH The vendor identification of the requesting applicationdoes not match the vendor identification of the featurefor which the license server has a license. This erroroccurs only when client is older than version 6.3 else theerror returned is VLS_NO_SUCH_FEATURE.

VLS_MULTIPLE_VENDORID_ FOUND The license server has licenses for the same feature andversion from multiple vendors. It is ambiguous which fea-ture is requested.


1.69. Syntax 131






VLS_BAD_SERVER_MESSAGE Message returned by the license server could not beunderstood.




1.70. VLSdeleteLicenseFromFileClient Server Static Library DLL

√ √ √

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

1.70.1. SyntaxLS_STATUS_CODE VLSdeleteLicenseFromFile (





unsigned char *license_string,

int *license_string_bufsize,

void *unused1,

int unused2 );


feature_name The feature name identifier of the license code.

version The version identifier of the license code.

license_hash The license hash to identify a specific license code.

license_hash_len, The allocated size for the license hash, passed as input.

license_string An OUT parameter. The deleted license code returned by the licenseserver.

license_string_bufsize 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 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 thelicense file. The license code to be deleted is identified by the feature-version-license hash com-bination.



This API returns the deleted license code back to the caller. The caller needs to allocate the buffer forthe 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_stringback to the caller.

The VLSgetLicenseInfo API can be used to obtain information about licenses installed. It returns astructure containing license hash value to identify a license code.

1.70.3. Returns




n If license_hash_len < 1 or license_hash_len > VLS_MAX_LICENSE_HASH_LEN.

n If license_hash is passed as NULL.n If license_string is not NULL and license_string_buf-

size is NULL.n If feature_name or version buffer size exceeds the

maximum size limit Specified as VLS_MAXFEALEN andVLS_MAXVERLEN respectively.

n If the length of license_hash passed is more thanVLS_MAX_LICENSE_HASH_LEN.

VLS_APP_UNNAMED When any of the following parameters (feature_name, ver-sion, and license hash) is NULL. Or, they contain only theNUL character i.e '\0'.

VLS_NO_SUCH_FEATURE License with passed feature-version combination not found.


LS_BUFFER_TOO_SMALL This indicates an error that the allocated buffer is insufficientto store the deleted license string.

VLS_LICENSE_IN_USE This indicates an error that the license to be deleted is cur-rently in use. This means that the specified license has someactive clients.

VLS_STORE_ACCESS_ERROR This indicates failure in accessing the license file.


LS_NORESOURCES Error occurred in allocating resources needed by this API.

VLS_DELETE_LIC_FAILED This indicates a generic error that the license deletion proc-ess has failed.

VLS_MULTIPLE_VENDORID_FOUND

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


Vendor ID for all these licenses is different from the licensinglibrary's Vendor ID.

VLS_SEVERE_INTERNAL_ERROR This indicates failure that occurs in internal message con-struction and splitting while processing the API.




VLS_CAPACITY_MISMATCH Error indicating that the license to be deleted is a capacitylicense.




1.71. VLSdeleteLicenseFromFileExtClient Server Static Library DLL

√ √ √

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

1.71.1. SyntaxLS_STATUS_CODE VLSdeleteLicenseFromFileExt (



unsigned long *capacity,



unsigned char *license_string

int *license_string_bufsize,

void *unused1,

int unused2 );


feature_name The feature name identifier of the license string.

version The version identifier of the license string.

capacity The capacity identifier of the license string.

license_hash The license hash to identify a specific license string.

license_hash_len The allocated size for License hash passed as input.

license_string An OUT parameter. The deleted license string returned by the licenseserver.

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



1.71.2. Description

Allows deletion of both non-capacity and capacity license code, that is not in use, from the licenseserver's memory and the license file. A license code to be deleted is identified by the feature-version-capacity-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 bepassed in the capacity parameter.

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

1.71.3. Returns




n If license_hash_len < 1.n If license_hash is passed as NULL.n If license_string is not NULL and license_string_buf-

size is NULL.n If feature_name or version buffer size exceeds the

maximum size limit Specified as VLS_MAXFEALENand VLS_MAXVERLEN respectively.

n If length of license_hash passed is more than VLS_MAX_LICENSE_HASH_LEN.

n If length of license_hash passed is more than VLS_MAX_LICENSE_HASH_LEN.

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



LS_BUFFER_TOO_SMALL This indicates an error that the allocated buffer is insuf-ficient to store the deleted license string.

VLS_LICENSE_IN_USE This indicates an error that the license to be deleted is cur-rently in use. This means that the specified license hassome active clients.

VLS_STORE_ACCESS_ERROR This indicates failure in accessing the license file.


LS_NORESOURCES Error occurred in allocating resources needed by this API.

VLS_DELETE_LIC_FAILED This indicates a generic error that the license deletionprocess has failed.

VLS_MULTIPLE_VENDORID_FOUND This occurs when more than one licenses for the specifiedFeature/Version is available on the License server, butthe Vendor ID for all these licenses is different from thelicensing library's Vendor ID.

VLS_SEVERE_INTERNAL_ERROR This indicates failure that occurs in internal message con-struction and splitting while processing the API.

1.71. VLSdeleteLicenseFromFileExt 137






VLS_CAPACITY_MISMATCH Error indicating thatNULL is passed as capacity argument for deleting a capac-ity license or vice-a-versa.

Incorrect capacity value is passed as argument for delet-ing a capacity license.


1.72. VLSgetLibInfoReturns information about the licensing library currently being used in the structure pointed to bypInfo.

1.72.1. SyntaxLS_STATUS_CODE VLSgetLibInfo(LS_LIBVERSION *pInfo)

typedef struct {

unsigned long ulInfoCode;

char szVersion [LIBINFOLEN];

char szProtocol [LIBINFOLEN];

char szPlatform [LIBINFOLEN];

char szLocale [LIBINFOLEN];

char szUnused2 [VERSTRLEN];

} LS_LIBVERSION

Member Description

ulInfoCode Unused.

szVersion The version of the licensing library.

szProtocol The communication protocol being used for application/license server com-munication.

szPlatform The platform of the client application.

szLocale The locale of the client system.

szUnused2 Unused.

1.72.2. Description

Space for pInfomust be allocated by the caller.

1.72.3. Returns


Error Codes Description

LS_NORESOURCES pInfo is NULL.


1.72. VLSgetLibInfo 139


1.73. VLSshutDownClient Server Static Library DLL

√ √ √

Shuts down license server at specified hostname.

1.73.1. SyntaxLS_STATUS_CODE VLSshutDown (

char *hostname );


hostname 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. Onceshut down, there is no automatic way of restarting the license server through any client message. Anyapplications that may be running at that time could stop running after a while, as the license renewalmessages will fail once the license server goes down. The license server does not check for runningapplications 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.

n User identification of the license server process should match the client, or client must be runby superuser (root) as shown in the following table:

Server Operating System Windows

2000/XP/2003/Vista/7/2008(Admin)

UNIX

(non-root)

UNIX(root)

Client

UNIX (non-root) — SameUser-Name orUserId

—

Windows2000/XP/2003/Vista/7/2008(Admin)

Yes Yes Yes

UNIX (root) Yes Yes Yes

1.73.3. Returns



VLS_CALLING_ERROR hostName parameter is NULL.

LS_NORESOURCES An error occurred in attempting to allocatememory needed by func-tion.


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




VLS_BAD_SERVER_MESSAGE

Message returned by the license server could not be understood.

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


1.73. VLSshutDown 141


The Trial License Related FunctionsThis section describes the API functions related to trial licensing.



VLSgetTrialUsageInfo Retrieves the usage information for a trial license.

VLSsetLicensePrecedence Sets the precedence value for a trial license.

VLSgetTrialPeriodLeft Returns the remaining time left in a trial license.

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

1.74.1. Syntaxtypedef struct trial_usage_info_struct {

long structSz;

char feature_name[VLS_MAXFEALEN + 1];

char version[VLS_MAXFEALEN + 1];

int cumulative_trial_calendar_period;

int cumulative_trial_elapsed_hours;

int cumulative_trial_execution_count;

int cumulative_trial_calendar_period_left;

int cumulative_trial_elapsed_period_left;

int cumulative_trial_executions_left;

}VLStrialUsageInfo;

Member Description

structSz Size of VLStrialUsageInfo structure.

feature_name Name of the feature whose information isretrieved.Space is allocated for 64 characters, but cur-rently maximum 24 characters long feature name is sup-ported.


Cumulative_trial_calendar_period Total trial days of all the trial licenses added.

Cumulative_trial_elapsed_hours Total trial hours of all the trial licenses added.

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

Cumulative_trial_calendar_period_left Total trial days left.

Cumulative_trial_elapsed_period_left Total trial usage left (in seconds).

Cumulative_trial_executions_left Total trial execution count left.

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

1.74. VLStrialUsageInfo 143


1.75. VLSgetTrialUsageInfoClient Server Static Library DLL

√ √ √

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

1.75.1. SyntaxLS_STATUS_CODE VLSgetTrialUsageInfo (



int feature_index,

VLStrialUsageInfo *trial_usage_info );



version Version of the feature. Must be unique.


trial_usage_info This API function stores the structure in which the information isobtained. Thememory for this structuremust 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 thislicense only.

n 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 featureexists.

n When trial license precedence is set to run on top of normal license (set to -1), then cumu-lative information is calculated considering trial licenses with negative license precedence.

n Additive trial licenses allow seamless dynamic switching to other license, that is, when anadditive trial license gets exhausted it would switch to another license provided anotherlicense (trial or normal) of the same feature is loaded in thememory.

10. n 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 licenseprovided another license (trial or normal) of the same feature is loaded in thememory.

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

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

License 1 License 2 Cumulative Usage

Additive Trial Additive Trial License 1 + License 2

Additive Trial Exclusive Trial License 1 + License 2

Additive Trial Aggregate Trial License 1 + License 2

Exclusive Trial Additive Trial License 1

Exclusive Trial Aggregate Trial License 1

Exclusive Trial Exclusive Trial License 1

Aggregate Trial AggregateTrial License 1 + License 2

AggregateTrial Exclusive Trial License 1 + License 2

AggregateTrial Additive Trial License 1

Normal (Additive/Exclusive) Additive Trial Error Return

Normal (Additive/Exclusive) Exclusive Trial Error Return

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

License 1 License 2 Cumulative Usage

Additive Trial Additive Trial License 1 + License 2

Additive Trial Exclusive Trial License 1 + License 2

Additive Trial Aggregate Trial License 1 + License 2

Exclusive Trial Additive Trial License 1

Exclusive Trial Aggregate Trial License 1

Exclusive Trial Exclusive Trial License 1

Aggregate Trial Aggregate Trial License 1 + License 2

Aggregate Trial Additive Trial License 1

Aggregate Trial Exclusive Trial License 1 + License 2

Additive Trial Normal (Additive/Exclusive/Aggregate) License 1

Aggregate Trial Normal (Additive/Exclusive/Aggregate) License 1

Exclusive Trial Normal (Additive/Exclusive/Aggregate) License 1

The feature_index argument should be used in a loop to get information of all the features loaded inthememory 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



VLS_NO_MORE_FEATURES Finished retrieving all the features added.

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

1.75. VLSgetTrialUsageInfo 145



VLS_APP_UNNAMED If:

n If feature_name is NULL or feature_name containsonly NULL character i.e '\0' and feature_index isless than zero

n If feature_name is not NULL and version is NULL.


n If trial_usage_info is NULL.

n If feature_name or version buffer size exceedsthemaximum size limit specified as VLS_MAX-FEALEN and VLS_MAXVERLEN, respectively.

VLS_NO_SUCH_FEATURE License with specified feature-version combination is notfound.

VLS_MULTIPLE_VENDORID_FOUND This occurs when more than one licenses for the spec-ified Feature/Version is available on the License server,but the Vendor ID for all these licenses is different fromthe client library's Vendor ID.



VLS_NON_TRIAL_LICENSE This indicates that the specified feature is not a triallicense. For ex, if the specified feature node contains anormal license.

VLS_TRIAL_LIC_NOT_ACTIVATED Inactive trial license is queried.

VLS_TRIAL_LIC_EXHAUSTED The specified feature has an exhausted trial license.





1.76. VLSsetLicensePrecedence

Client Server Static Library DLL

√ √ √

Sets the precedence value for a trial license.

1.76.1. SyntaxLS_STATUS_CODE VLSsetLicensePrecedence (





int precedence_level,

void *ununsed1,

int ununsed2 );




license_hash The license hash for the license code (to identify a specific license).

license_hash_len The length of the license hash.

precedence_level Used to specify the precedence level that needs to set for the trial license.

unused1 Unused variable.

unused2 Unused variable.

1.76.2. Description

The API sets the precedence level of a trial license. The precedence level passed as argument can beone of the following:

n 0: license code is inactive and cannot be consumed.

n -1: license code is active and would take precedence over all the licenses, including permanentlicenses. This is a special precedence level that makes a trial licensemost preferred license irre-spective of license type.

n >= 1: Positive values decide preference order of a trial license, among trial licenses, for a givenfeature. 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 of1.

The following macros related to license precedence are defined in lserv.h header file:



n VLS_PRECEDENCE_TRIAL_OVERRIDE_NORMAL (-1)

n VLS_PRECEDENCE_DISABLE (0)

n VLS_PRECEDENCE_DEFAULT (1)

1.76.3. Returns



VLS_APP_UNNAMED When the feature_nameOR version OR license_hashparameter is NULL.

When the feature_nameOR license_hash contain onlythe NULL character i.e "\0".

VLS_CALLING_ERROR Argument specified is not correct, that is, one of the fol-lowing reasons exist:If license_hash_len is less than -1 or exceeds themax-imum limit i.e VLS_MAX_LICENSE_HASH_LEN.

If feature_name or version buffer size exceeds themax-imum size limit specified as VLS_MAXFEALEN and VLS_MAXVERLEN respectively.

If precedence_level is less than -1.

VLS_NO_SUCH_FEATURE The license with feature-version combination passed asan argument not found.

VLS_NO_SUCH_LICENSE The license with feature-version-license hash com-bination passed as an argument not found.

VLS_RESOURCE_LOCK_FAILURE Failed to obtain the API resource lock. On receiving thiserror, retry calling this API.


VLS_SET_LICENSE_PRECEDENCE_FAILED

Failed in setting the license precedence.

VLS_TRIAL_LIC_DATA_INCONSISTENT Failed to set the precedence of a trial license due to thecorrupted persistence.

VLS_TRIAL_LIC_DATA_ACCESS_ERROR Recoverable error is occurred while setting the prec-edence of a trial license.

VLS_MULTIPLE_VENDORID_FOUND This occurs when more than one licenses for the spec-ified Feature/Version is available on the License server,but the Vendor ID for all these licenses is different fromthe licensing library's vendor ID.





VLS_CAPACITY_MISMATCH The function is called for a capacity license. It can only becalled for non-capacity licenses.




1.77. VLSgetTrialPeriodLeftClient Server Static Library DLL

√ √ √

1.77.1. Syntaxint VLSgetTrialPeriodLeft (



unsigned long *trialperiod,

unsigned long *unused1 );




trialperiod (OUT) Number of seconds left in the trial license. Points to integer in the tri-alperiod parameter.

unused1 Uses NULL as the value.

1.77.2. Description

Returns the remaining time left in a trial license. The usage period for trial licenses does not begin untilthe application is first executed, i.e., not when the application is installed.

1.77.3. Returns



VLS_CALLING_ERROR n feature_name is NULL.n version is NULLn trialperiod is NULLn Both feature name and version cannot be NULL at the

same time.

VLS_SEVERE_INTERNAL_ERROR

An Irrecoverable internal error has occurred in processing.

VLS_NO_SERVER_ RUNNING License server on specified host is not available for processinglicense operation request.

VLS_HOST_UNKNOWN Invalid hostnamewas specified.

LS_NO_NETWORK Generic error indicating that the network is unavailable for serv-icing the licensing operation.




VLS_INTERNAL_ERROR An internal error has occurred in processing.

VLS_NO_TRIAL_INFO No Trial usage info.


VLS_TRIAL_INFO_ FAILED Trial usage query failed


VLS_BAD_SERVER_MESSAGE An error has occurred in decrypting (or decoding) a network mes-sage· Probably an incompatible or unknown server, or a versionmismatch.


1.77. VLSgetTrialPeriodLeft 151


Getting the License Server InformationDevelopers sometimes need to know the details about the license servers running on a customer’scomputer to see if conflicts are occurring between license servers provided by different developers orto detect a specific license server.

The VLSservInfo structure contains the server information. The API call, VLSgetServInfo, provides adata structure into which information about a specific license server can be requested or obtained bya client application.

1.78. VLSservInfo Structtypedef struct {

long structSz;

int major_no;

int minor_no;

int revision_no;

int build_no;

unsigned char locale[VLS_SERV_LOCALE_STR_LEN];

unsigned char vendor_info[VLS_SERV_VNDINFO_STR_LEN];

unsigned char platform[VLS_SERV_PLATFORM_STR_LEN];

unsigned long lock_mask;

unsigned char unused1[VLS_SERV_UNUSED1_STR_LEN];

long unused2;

VLStimeTamperInfo tmtmpr_info;

VLSmachineID machine_id;

} VLSservInfo;


structSz Size of the structure. Must be set by the user.

major_no Themajor number of the server.

minor_no Theminor number of the server.

revision_no The revision number of the server.

build_no The build number of the server.

locale The locale for which the server was built.

vendor_info Vendor specified license server identification. This can be customizedthrough VLSsetServInfo API. Default is null string

platform The platform for which the server was built.

lock_mask Lock selector used in computing themachine ID of the server machine.

unused1 Reserved. Uses NULL as the value.

unused2 Reserved. Uses NULL as the value.

tmtmpr_info Contains the time tampering related information on the server machine.

machine_id Machine ID structure. To be used in conjunction with lock_mask toobtain the locking code of the server machine. See VLSma-chineIDtoLockCode API for details.

1.78. VLSservInfo Struct 153


1.79. VLStimeTamperInfo StructThe Sentinel RMS license server is configured to detect tampering of the system clock. You also havethe option of implementing your own functionality to retrieve the time tamper informationusing theVLStimeTamperInfo struct.

typedef struct timetampering_info_struct {

long structSz;

time_t lastTime;

time_t currTime;

long grace_period;

int percentViolationAllowed;

int numViolationForError;

int numViolationFound;

int percentViolationFound;

unsigned long clkSetBackTime;

} VLStimeTamperInfo;


structSz Size of the structure. Must be set by the user.

lastTime The last known good timewhen no clock tampering was detected.

currTime Current time on the server.

grace_period If Sentinel RMS Development Kit finds the system clock has been setback by less than grace_period seconds, it will not be counted as aviolation.

percentViolation Allowed Percentage of system files that must be found in violation of thegrace period before concluding that the system clock has been setback. Used on UNIX systems only.

numViolationFor Error Number of system files that must be found in violation of the graceperiod before concluding that the system clock has been set back.Used on UNIX systems only.

numViolationFound Actual number of system files found in violation of the grace period.Used on UNIX systems only.

percentViolation Found Percentage of system files found in violation of the grace period.Used on UNIX systems only.

clkSetBackTime The actual amount of time by which the clock has been set back. Thisvalue is zero if no time tampering has been detected.

1.80. VLSgetServInfoReturns information regarding the given license server, including version, locale, platform, and thelocking information of the computer on which the license server is running. After a successful call, theVLSservInfo 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 run-ning. This can be used to generate lock codes as the echoid utility does.

1.80.1. SyntaxLS_STATUS_CODE VLSgetServInfo (


VLSservInfo *srv_info,


unsigned long *unused2 );


server_name The name of the server you would like to retrieve information from. Youcan pass this as NULL if you want this API call to pick up the server name ifpreviously set by VLSsetContactServer or LSFORCEHOST. If set to NULLbut no server name is found, an error code will be returned. If not set toNULL, this value is independent of the LSHOST, LSFORCEHOST, andVLSsetContactServer values.

srv_info This points to the VLSservInfo data structure, which is populated withinformation returned from the server such as platform, locale, build ver-sions, and locking information. You may not set this to NULL.

1.80.2. Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indi-cating the reason for the failure. Possible errors returned by this call include VLS_NOT_SUPPORTED.


1.80. VLSgetServInfo 155


The License Revocation FunctionsThe 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 therelated 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.



VLSrevokeByPermissionTicket Verifies the permission ticket, acts on it, and returns the rev-ocation ticket.

VLSrevokeLicense Revokes network licenses based on the pre 8.4.1 network rev-ocation workflow.

1.81. VLSrevokeByPermissionTicketClient Server Static Library DLL

√ √ √

Revokes stand-alone and network licenses based on the permission and revocation ticket.

1.81.1. SyntaxLS_STATUS_CODE VLSrevokeByPermissionTicket (

unsigned char *pucServerName,

unsigned char *pucPassword,

unsigned char *pucPermissionTicket,

unsigned int ui16PermissionTicketLength,

unsigned char *pucRevocationTicket,

unsigned int *pui16RevocationTicketLength );


pucServerName Specify NULL for stand-alone revocation.

In case of network license revocation, specify the license servername in this parameter (or alternatively set using the VLSset-ContactServer API or the LSFORCEHOST environment variable)

In case of stand-alone license revocation, a separate call VLSset-ContactServer("no-net") is required.

pucPassword Specify NULL.

pucPermissionTicket An IN parameter. A pointer to the permission ticket.

ui16PermissionTicketLength An IN parameter. The length of the permission ticket.

pucRevocationTicket An OUT parameter. A pointer to the license revocation ticket outbuffer. Thememory 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.

pui16RevocationTicketLength An IN/OUT parameter. The size of the buffer allocated for puc-RevocationTicket, as input, and a pointer to the size of the licenserevocation ticket, as output.

This function verifies the permission ticket (PT), acts on it, and returns the revocation ticket (RT) forstand-alone and network licenses. The permission ticket is an approval from you (the developer) toperform a series of license revocation and addition operations that need to be performed on the cus-tomer-end. Whereas, the revocation ticket (also known as the rehost ticket) proves that actionsrequested in the permission ticket were performed.

Refer to Chapter - "License Revocation" in the Sentinel RMS SDK Developer's Guide for more detailsabout these terms.



The VLSrevokeByPermissionTicketAPI does the following activities before generating a license rev-ocation ticket:

n Validates the locking information received against the license server's\system's lock infor-mation.

n Validates the number of tokens specified in the permission ticket against the total number oftokens in the license.

n Checks if enough resources are available, like in the license storage, to carry out all requestedoperations.

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 areenough resources to store revocation information into the persistence data and, if newlicenses are defined, whether there is enough space to add the new licenses into the licensedatabase.

n Returns the size of the revocation ticket, that would be generated, in the pui16R-evocationTicketLength 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 thefollowing error codes:


VLS_REHOST_BUFFER_TOO_SMALL Allocated memory is not enough.

VLS_REHOST_PARAMETERS_ERROR Invalid rehost parameters.

VLS_REHOST_INVALID_DATA_FORMAT Permission ticket is invalid; either corrupt or not in TLVformat.

VLS_REHOST_UNSUPPORTED_OPER-ATION_TYPE

Operation type is not 'A', 'R', or 'P'.

VLS_REHOST_ALLOCATE_MEMORY_FAIL-URE

Failure in memory allocation.

VLS_REHOST_DIFFERENT_LOCK_INFO Lock codemismatch.

VLS_REHOST_LICENSE_IN_USE License to be revoked is in use; can not be revoked.

VLS_REHOST_HAVE_BEEN_REVOKED_BEFORE

License has already been revoked; can not be revokedagain.

VLS_REHOST_CANCELED_BY_USER Revoke option was canceled by the user.

VLS_REHOST_LICENSE_EXIST The license already exists.

VLS_REHOST_REVOKE_OVER_TOTAL When the revocation request exceeds the availablelimit.


VLS_REHOST_TAG_NOT_FOUND A tag not found in the TLV.

VLS_REHOST_INVALID_REQUEST_DATA The requested data is invalid.

VLS_INVALID_LICENSE The given license code/permission ticket is invalid.Hence, revocation by permission ticket is not allowed.

VLS_REVOKE_LIC_DATA_INCONSISTENT The license persistence data is either corrupt or doesnot exist.

VLS_TOO_MANY_OPERATIONS_IN_SIN-GLE_PT

The permission ticket size is more than the supportedlength. Decrease the number of operations from PT.

VLS_PT_ALREADY_EXECUTED_FOR_THIS_OPERATION

The permission ticket operation already executed onthe license server.

VLS_PT_VENDOR_ID_MISMATCH Vendor ID mismatch. The permission ticket cannot beused for revoking licenses of other vendors.

VLS_REVOKE_EXPIRED_LIC_FOUND An expired license can neither be added nor revoked.



1.82. VLSrevokeLicenseClient Server Static Library DLL

√ √ √

Revokes network licenses based on the pre 8.4.1 network revocation workflow.

1.82.1. SyntaxLS_STATUS_CODE VLSrevokeLicense(



unsigned char *feature_version,

unsigned long capacity,

unsigned char *password,

int *units_to_revoke,

unsigned long *capacity_to_revoke,

unsigned char *rvk_ticket,

int *length_of_rvk_ticket,

unsigned char *log_comment,

unsigned long *reserved1,

unsigned char *reserved2 );


server_name A pointer to the name of the license server where the license to berevoked is currently deployed. An error will be returned if an invalidname or a null value is provided.

feature_name A pointer to the feature name of the license to be revoked.

feature_version A pointer to the feature version of the license to be revoked.

capacity Not supported.

password A pointer to the password used for authenticating the client.

units_to_revoke 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 thenumber of licenses available. The number of licenses available for rev-ocation are returned in this parameter.

capacity_to_revoke A pointer to the capacity units to be revoked. However, revocation of acapacity license is not supported in this release of Sentinel RMS Devel-opment Kit. Make the value of this parameter as 0 or pass NULL.

rvk_ticket A pointer to the license revocation ticket out buffer. Thememoryneeds to be allocated and freed by the programmer. The buffer allo-cated should be at least 1024 bytes long.

length_of_rvk_ticket A pointer to the size of the license revocation ticket.

log_comment A string that is written by the licensemanager to the comment field of


the usage log file.

reserved1 Reserved for future use. You need to pass null in order to use this func-tion currently.

reserved2 Reserved for future use. You need to pass null in order to use this func-tion currently.

1.82.2. Description

This function is used for revoking the hard limit or the number of tokens for a network license basedon the pre 8.4.1 network revocation workflow (refer to the Appendix - "Network License RevocationPrior 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 -lrtoption of the lsdecode utility or the VLScgDecodeLicenseRevocationTicket andVLScgDecodeLicenseRevocationTicketExt APIs.

The license revocation ticket is encoded using the secret specified at the time of license creation. Thesame 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 thefollowing error codes:


VLS_REVOKE_ERR_NO_FEATURE License with the given feature/version does notexist on the license server.

VLS_REVOKE_ERR_CORRUPT_MESSAGE Themessage received by the license server was cor-rupted.

VLS_REVOKE_ERR_OUT_VALID_RANGE The revocation request was beyond the range.

VLS_REVOKE_ERR_MD5_PLUGIN_LOAD_FAIL

An error was encountered while loading theMD5plug-in DLL at the license server.

VLS_REVOKE_ERR_MD5_PLUGIN_EXEC_FAIL

An error was encountered in executing the authen-tication plug-in.

VLS_REVOKE_ERR_INSUFFICIENT_FEA-TURE_LICENSES

The feature has less number of total licenses.

VLS_REVOKE_ERR_INSUFFICIENT_DEFAULT_GROUP

The default group does not have sufficient licenses.You can reconfigure your user reservation file.

VLS_REVOKE_ERR_INSUFFICIENT_FREE_IN_DEFAULT

Currently the required number of licenses are notfree for revocation in the default group.

1.82. VLSrevokeLicense 161



VLS_REVOKE_ERR_INVALID_SESSION_ID An invalid session ID was sent by the client inpacket.

VLS_REVOKE_ERR_INVALID_PASSWORD The password supplied for revocation was invalid.

VLS_REVOKE_ERR_INTERNAL_SERVER Revocation Failed! - Internal Server Error.

VLS_REVOKE_ERR_INFINITE_GRP_DIST It is not possible to revoke infinite licenses withgroup distribution enabled.

VLS_REVOKE_ERR_INFINITE_LIC_IN_USE All licenses must be free for infinite revocation.

VLS_REVOKE_ERR_INFINITE_LIC_FINITE_REQ

The license has infinite keys. Only infinite rev-ocation request allowed.

VLS_REVOKE_ERR_TICKET_GENERATION Failed to generate the revocation ticket.

VLS_REVOKE_ERR_CODGEN_VERSION_UNSUPPORTED

License revocation is not supported on the olderversions of the License Code Generator.

VLS_REVOKE_ERR_RDNT_LIC_UNSUP-PORED

License revocation is not supported for redundantlicenses.

VLS_REVOKE_ERR_CAPACITY_LIC_UNSUP-PORED

License revocation is not supported for capacitylicenses.

VLS_REVOKE_ERR_UNEXPECTED_AUTH_CHLG_PKT

Unexpected error! The challenge packet wasreceived from the license server.

VLS_REVOKE_ERR_TRIAL_LIC_UNSUP-PORED

License revocation is not supported for triallicenses.

Error HandlingThis 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 han-dler 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 tasksand display error messages. If an error occurs while processing a function call and the default errorhandlers are unable to correct the situation, the API functions return an error code after displaying anappropriate error message. If the built-in error handlers are able to correct the error-causing con-dition, the function call returns the success code, LS_SUCCESS, as if the error never occurred



VLSerrorHandle Toggles default error handling ON or OFF.

LSGetMessage Prints licensing library-defined error messages corresponding to specifiederror code.

VLSsetErrorHandler Registers custom error handlers.

VLSsetUserErrorFile Configures the display of error messages.

Error Handling 163


1.83. VLSerrorHandleClient Server Static Library DLL

√ √ √

Turns default error handling on or off.

1.83.1. SyntaxLS_STATUS_CODE VLSerrorHandle (

int flag );


flag 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 handlingis disabled. If called with VLS_OFF and LSGetMessage is used, the feature name and version are hid-den. When error handlers are not being used, the client function call returns the status code of thelatest error condition. The caller of the function should therefore check the value returned by the func-tion before proceeding.

IMPORTANT

I f you choose to disable error handling in your licensing implementation, it is rec-ommended that you call the VLSerrorHandle API before calling VLSinitialize.

1.83.3. Returns


1.84. LSGetMessageClient Server Static Library DLL

√ √ √

Prints error messages corresponding to specified error code.

1.84.1. SyntaxLS_STATUS_CODE LSGetMessage (

LS_HANDLE lshandle,

LS_STATUS_CODE Value,

unsigned char *buffer,

unsigned long bufferSize );



value Error code.

buffer (out) Buffer to storemessage.When the handle provided is invalid, the buffer parameter returned con-tains the error code. However, it will show the feature name asUNKNOWN.


1.84.2. Description

Returns in the buffer a text description of the error condition indicated by error code value, for the fea-ture associated with lshandle. The buffermust be allocated by the calling function with its size indi-cated by bufferSize.

1.84.3. Returns



LS_NO_MSG_TEXT n buffer is NULLn bufferSize is zero or negative.


1.84. LSGetMessage 165


1.85. VLSsetErrorHandlerClient Server Static Library DLL

√ √ √

Enables registration of custom error handlers.

1.85.1. SyntaxLS_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 customerror handling routines to replace the default routines. Customized routines should perform actionsthat are functionally similar to the defaults.

myErrorHandlermust point to the error handling function and adhere to the prototype outlinedbelow. LSErrorTypemust indicate the type of the error to be handled. The Sentinel RMS DevelopmentKit default routines continue to handle other errors. The customized function should accept as inputthe error code of the condition that caused it to be called and the name of the feature. The sameerror-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 toset up the provided error handler to handle all errors.

Customized error handlers must adhere to the following prototype:

LS_STATUS_CODE myErrorHandler,

LS_STATUS_CODE errorCode,

char *featureName;


errorCode The error code to be handled.

featureName The name of the feature involved in the error.

1.85.3. Returns



VLS_CALLING_ERROR n myErrorHandler parameter is NULLn LSErrorType is an invalid error type.


1.86. VLSsetUserErrorFileClient Server Static Library DLL

√ √ √

Configures themanner in which error messages are displayed.

1.86.1. Syntaxtypedef 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 han-dlers. 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 aMessage Box. UnixWrite tostderr.

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

1.86.3. Returns



VLS_CALLING_ERROR Could not openmsgFile.


1.86. VLSsetUserErrorFile 167


The Trace Licensing OperationsThe tracing calls are placed in the RMS client library to help diagnose the situations, like errors and fail-ures. You can enable tracing of the internal operations, such as function calls, errors, and invalidlicenses, to log the flow of activities performed.

By default, the tracing operation is disabled for the licensing library.



VLSsetTraceLevel Sets the location for storing the tracing output.

VLSsetUserTraceFile Sets the tracing level.

VLSsetTraceHandler Allows defining custom trace handler function.

1.87. VLSsetTraceLevelClient Server Static Library DLL

√ √ √

Sets the tracing level.

1.87.1. Description

This function sets the following trace levels:

1.87.2. SyntaxLS_STATUS_CODE VLSsetTraceLevel (

int traceLevel );


traceLevel The default value of traceLevel is VLS_NO_TRACE. Other valid values are:

n VLS_TRACE_KEYSn VLS_TRACE_FUNCTIONSn VSL_TRACE_ERRORSn VLS_TRACE_ALL

1.87.3. Returns



VLS_CALLING_ERROR Could not openmsgFile.


1.87. VLSsetTraceLevel 169


1.88. VLSsetUserTraceFileClient Server Static Library DLL

√ √ √

Sets the location of the trace file.

1.88.1. SyntaxLS_STATUS_CODE VLSsetUserTraceFile (

VLS_ERR_FILE msgFile,

char *filePath );


msgFile An IN parameter. Refers to the standard file where tracemessagesare stored as output. It is defined as data type VLS_TRACE_FILE,with the following possible values:

n VLS_NULLn VLS_STDERRn VLS_STDOUT

filePath The path of the file, including the filename, where trace log is to bemaintained. If msgFile is set to VLS_STDERR or VLS_STDOUT, thispath 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, allthe 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 argumentis passed, the other should be passed as VLS_NULL. However, if values for both the arguments arepassed, then preference is given to themsgFile 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 filecan be unregistered by calling VLSsetUserTraceFile with VLS_NULL as argument.

1.88.3. Returns



VLS_CALLING_ERROR The argument specified is not correct, that is, either the file spec-ified in the filePath argument is not valid or the value for msgFileargument 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


1.89. VLSsetTraceHandlerClient Server Static Library DLL

√ √ √

Registers a handler to which the tracemessages that are generated at run-time are sent.

1.89.1. SyntaxLS_STATUS_CODE VLSsetTraceHandler (

LS_STATUS_CODE (*myTraceHandler)( int traceLevel, char

*buffer, int bufferSize));


myTraceHandler A pointer to the trace handling function.

1.89.2. Description

This API is used to register a handler to which the tracemessages that are generated at run-time aresent. ThemyTraceHandler argument must point to the trace handling function, which must bedefined 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.

n buffer is to store the formatted tracemessages. The tracemessages passed depend on thethe level set.

n bufferSize is to store the size of the buffer argument passed.

n 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, ahandler cannot be unregistered without rebuilding the application.

1.89.3. Returns



VLS_CALLING_ERROR The argument specified is not correct, that is,myTraceHandler isNULL.

VLS_RESOURCE_LOCK_FAILURE Failed to obtain the API resource lock. On receiving this error,


please retry calling this API function.


1.89. VLSsetTraceHandler 173

Chapter 2:Commuter License API

Commuter licenses allow temporary check out of a license token to use a protected application from aSentinel RMS license server to a portable computer. Themost common use of this feature is to allowuse of a protected application on a laptop computer that will be disconnected from the network.



VLScommuterInfo Commuter information structure

VLSgetCommuterInfo Returns the commuter license information.

VLSgetAndInstallCommuterCode Obtains the commuter code from the license server and issuesthe commuter authorization to the client side persistence data-base

VLSuninstallAndReturn Com-muterCode

Removes the commuter authorization from the client side per-sistence database and returns the token to the license server.

VLScleanExpiredCommuterCode Cleans the expired commuter authorization on a client.

VLSgetMachineIDString Obtains commuter locking code from a remote computer.

VLSgetCommuterCode Checks out a commuter authorization for a remote computer.

VLSinstallCommuterCode Install a commuter authorization on a remote computer.

2

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;


commuter_code_version Version of commuter code

codegen_version Version of the code generator used

feature_name Name of the feature

feature_version Version of the feature

birth_day Start day (1-31)

birth_month Start month (1-12)

birth_year Start year

death_day End day (1-31)

death_month End month (1-12)

death_year End year

num_of_licenses Number of licenses

locking_crit Locking criteria of the client

lock_info Locking information of the client

vendor_info The vendor-defined information string. Maximum length of this stringcan be 2000 characters.


issuing_server License checked out from <servername>


protocol_type Type of protocol used

status n 1 - Activen 0 - Inactive

2.1. VLScommuterInfo 177


2.2. VLSgetCommuterInfo

2.2.1. Syntaxint VLSgetCommuterInfo (



int index,

VLScommuterInfo *commuter_info );




index Used to specify a particular client. The indexmust be greater than 0.When the index crosses themaximum number of commuter features avail-able, the error VLS_NO_MORE_COMMUTER_CODE will be returned.

commuter_info The structure, which returns the information about the checked-out license.Spacemust be allocated by the caller.

2.2.2. Description

VLSgetCommuterInfo() returns LS_SUCCESS when the locally checked-out commuter token is availableon the system whereas the function returns VLS_REMOTE_CHECKOUT, when the remotely checked-out 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 thisfeature. The call will ignore the index argument.

n Specify feature_name and version as NULL and use the index field in a loop. This will returninformation about all feature-version checked-out licenses from no-net.

VLSgetCommuterInfo should be called until it returns VLS_NO_MORE_FEATURES by incrementing theindex every time.

2.2.3. Returns

The status code VLScg_SUCCESS is returned if successful. For a complete list of the error codes, seeLicensing Library Error and Result Codes.

2.3. VLSgetAndInstallCommuterCode

2.3.1. Syntaxint VLSgetAndInstallCommuterCode (



long *units_reqd,

int *duration,

int *lock_mask,





feature_version Version of the feature.

units_reqd Number of units required to run the license. The license system verifies that therequested number of units exist and may reserve those units.The number ofunits available is returned. If the number of licenses available with the licenseserver is less than the requested number, the number of available licenses will bereturned using unitsReqd. If unitsReqd is NULL, VLS_CALLING_ERROR will bereturned.

duration Displays the number of days for which the license has to be checked out. Specifyzero (0) for unlimited check-out.If the remaining number of days available is less than the requested days, thenthe duration parameter will be ignored and the license server will issue the com-muter authorization for the remaining number of days. The license server willnever issue the commuter authorization beyond the birth and death date of thelicense.

The start date of the commuter authorization is based on the client system’s

time and not that of the license server.

lock_mask Mask defining which fields are to be used for locking.On entry, lock_mask specifies the locking-criteria that should be used for lookingthe commuter-code. If a zero is given, the API will lock the code to Disk ID (win-dows), otherwise it will lock to host name. Notice, the API will replace the zerowith lock_mask for Disk ID or host name before sending this value to the licenseserver.

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

challenge The challenge-response for this operation. Pointer to a challenge structure. Thechallenge-response will also be returned in this structure.

2.3. VLSgetAndInstallCommuterCode 179


2.3.2. Description

Obtains the commuter code from the license server and installs the stand-alone commuter author-ization at the client.

Before calling VLSgetAndInstallCommuterCode, the VLSgetMachineID function must be called in orderto 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 errorcodes:


VLS_CALLING_ERROR n duration is NULLn lock_mask is NULLn unitsReqd is NULL

VLS_UNABLE_TO_INSTALL_COM-MUTER_CODE

Could not install the checked out commuter license code onthe target computer.


2.4. VLSuninstallAndReturnCommuterCode

2.4.1. Syntaxint VLSuninstallAndReturnCommuterCode (



unsigned char *log_comment );




log_comment A string to be written by the license server to the comment field of the usagelog 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 thelicense server.

2.4.3. Returns

The status code LS_SUCCESS is returned if successful. For a complete list of the error codes, seeLicensing 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.

2.4. VLSuninstallAndReturnCommuterCode 181


2.5. VLSgetMachineIDStringReturns an encrypted string that contains the fingerprint information based on the locking criteriaspecified in the call.

Use this call when you are trying to check out a commuter authorization for a remote computer thatdoes not have access to the license server. The computer that will actually use the commuter author-ization runs this call and then passes on the string (via e-mail, disk, etc.) to a computer that has accessto the license server. The commuter authorization is then checked out and transmitted to a remoteuser, and locked to the information given by this string.

If themachine 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 VLSge-tAndInstallCommuterCode.

2.5.1. SyntaxLS_STATUS_CODE VLSgetMachineIDString (

unsigned long *lock_selector,

unsigned char *machineIDString,

unsigned long *bufSz );


lock_selector Bitmask identifying what criteria you would like to be contained in theMachine ID string. See the lock_selector Values below for information on thevalues for this bitmask. If you set this argument to NULL, this API call will usethe locking selector information it finds on the computer on which it is run-ning.

machineIDString A string that represents themachine’s locking information. This will be passedon to VLSgetCommuterCode on a computer that can actually check out a com-muter authorization from the license server.

bufSz Returns the buffer size of themachineIDString parameter if machineIDString isNULL. Otherwise, specifies the size of themachineIDString parameter.

2.5.2. Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indi-cating 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.3. lock_selector Values

The value of lock_selector is a bitmask in which each bit selects a fingerprinting element. It does notdescribe the fingerprint, but only designates the locking criteria that will be used to compute the fin-gerprint. Themasks which define each locking criterion are listed below:

VLS_LOCK_ID_PROM 0x1

VLS_LOCK_IP_ADDR 0x2

VLS_LOCK_DISK_ID 0x4

VLS_LOCK_HOSTNAME 0x8

VLS_LOCK_ETHERNET 0x10

VLS_LOCK_PORTABLE_SERV 0x80

VLS_LOCK_CUSTOM 0x100

VLS_LOCK_CPU 0x200

VLS_LOCK_CUSTOMEX 0x400

VLS_LOCK_HARD_DISK_SERIAL 0x800

VLS_LOCK_CPU_INFO 0x1000

VLS_LOCK_UUID 0x2000

VLS_LOCK_ALL 0x1FFF

VLS_LOCK_PORTABLE_SERV refers to the Computer ID key, and that VLS_LOCK_ALL selects all locking

criteria.

2.5. VLSgetMachineIDString 183


2.6. VLSgetCommuterCodeObtains a commuter authorization from the license server to be passed on to a remote client thatdoes not have network access to the license server. This call checks out a commuter authorization foranother machine. It requires a commuter locking code string from the VLSgetMachineIDString callused on the remote computer. After successful completion of the call, the authorization code stringshould be passed on to the remote computer which will use VLSinstallCommuterCode to install theauthorization.

If themachine 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 VLSge-tAndInstallCommuterCode. Once a commuter authorization is checked out for a remote computer, itcannot be checked back in until the commuter authorization expires.

2.6.1. SyntaxLS_STATUS_CODE VLSgetCommuterCode (



unsigned long *units_rqd,

unsigned long *duration,

unsigned long *lock_mask,


unsigned char *machineIDString,

unsigned char *commuter_code,


VLSserverInfo *requestInfo,

VLSserverInfo *commuterInfo,

unsigned long *extension_in_duration );


feature_name The feature name of the license to check out from the license server.

feature_version The feature version of the license to check out from the license server.

units_reqd Number of units required for the license.

duration Number of days the commuter authorization will last. This valuemay besuperseded by themaximum limit allowed by the license.

lock_mask The desired locking criteria for the client machine. The value here shouldbe equal to or a subset of the value used by the VLSgetMachineIDStringcall. This value will return the actual locking criteria used to lock the com-muter authorization.

log_comment A comment which will be placed inside the log file on the license server.

machineIDString Machine ID string generated by the remote computer desiring the com-muter authorization.

commuter_code The actual commuter authorization code. This string should be passedon to the remote computer desiring the commuter authorization for


installation.

challenge A challenge and response for the given license on the license server. Setto NULL if you are not using this feature.

requestInfo Reserved. Use NULL for this value.

commuterInfo To be used in future for hooks.

extension_in_duration The additional number of days to extend the duration of an existingremotely checked out commuter license (can be termed as "commutinga remote extension token"). However, pass this as NULL under the fol-lowing scenarios:

n If you are checking out a remote commuter license for first timefor a feature.

n If the checked out remote commuter license is lost.

Similarly, when an extension token is being commuted, non-applicableparameters (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 indi-cating the reason for the failure. Possible error codes that can be returned by this call include VLS_INVALID_MACHINEID_STRING.


2.6. VLSgetCommuterCode 185


2.7. VLScleanExpiredCommuterCode

2.7.1. Syntaxint VLScleanExpiredCommuterCode (



unsigned char *log_comment

unsigned long *unused );




log_comment Unused

unused This parameter is reserved for future use.

2.7.2. Description

Cleans the expired commuter authorization on a client system (both remote and normal).

2.7.3. Returns

The status code LS_SUCCESS is returned if successful. For a complete list of the error codes, seeLicensing Library Error and Result CodesLicensing Library Error and Result Codes.

2.8. VLSinstallCommuterCodeInstalls a commuter authorization onto a remote computer. A computer that has network access tothe license server should generate the commuter authorization using VLSgetCommuterCode (see ).The commuter authorization is then passed on to the computer requiring the authorization andinstalled using VLSinstallCommuterCode. After successful completion of this call, the remote com-puter should be able to use the commuter authorization.

If themachine 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 VLSge-tAndInstallCommuterCode. Once a commuter authorization is checked out for a remote computer, itcannot be checked back in—it simply expires.

2.8.1. SyntaxLS_STATUS_CODE VLSinstallCommuterCode (

unsigned char *commuter_code,

unsigned char *reserved1,

unsigned long *reserved2 );


commuter_code The commuter authorization that was generated by a computer with networkaccess to the license server.

reserved1 Reserved. Use NULL for this value.

reserved2 Reserved. Use NULL for this value.

2.8.2. Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indi-cating the reason for the failure. Possible errors that can be returned by this call include VLS_UNABLE_TO_INSTALL_COMMUTER_CODE.


2.8. VLSinstallCommuterCode 187

Chapter 3:Redundancy API

The license server redundancy allows the total number of licenses to remain available to the enter-prise even if one or more license servers fail. If a license server fails, the license tokens it is serving willbe taken over by the next-available license server. For information on setting up and using redundantlicense servers, please see the Sentinel RMS SDK Developer’s Guide and the Sentinel RMS SDK SystemAdministrator’s Guide.

The following API function have been deprecated since the 8.1.x release, VLSaddFeatureExt, VLSadd-

FeatureToFileExt, VLSchangeDistbCrit, and VLSsetBorrowingStatus. These functions do not perform any

operation and return the VLS_NOT_SUPPORTED error code.



VLSaddFeature Dynamically adds licensing information about a feature into thelicense server’s internal tables. If licensing information for thisfeature and version already exists in the license server’s tables,it may be overwritten with the new information.Feature is not permanently added to the license server, butonly until the license server is shut down and restarted.

VLSaddFeatureToFile Dynamically adds licensing information to the license server’sinternal tables and normal or redundant license file.

VLSaddServerToPool Sends a request to add a new license server into the pool. ThisAPI will actually modify the license redundant file in order toadd the given license server to the pool.

VLSdelServerFromPool Removes a license server’s name from the pool. This API willactually modify the license redundant file in order to delete thegiven license server from the pool.

VLSdiscoverExt Returns the license server characteristic information, which hasthe keys for a particular specified feature and version. The clientcan decide a license server preference based on some criteria.

VLSgetDistbCrit Returns the current token distribution status for the givenlicense feature and version.

3

190 Chapter 3: Redundancy API


VLSgetDistbCritToFile Requests the license server provide current token distributionstatus for the given license feature and version or for all fea-tures or versions (wild card characters are acceptable). Writesthe distribution to a file.

VLSgetLeaderServerName Returns the current leader license server’s name by contactingany license server. So a license server’s namemust be setbefore a call is made to this function.

VLSgetLicSharingServerList Returns the names of the license servers which are sharingtokens for a given feature name and version. The server_name_listwill contain license server names (hostNames or IPaddresses).

VLSgetPoolServerList Returns a list of redundant license servers and their status.

VLSsetServerLogState Turns logging on/off for the given event.

3.1. VLSaddFeature

3.1.1. Syntaxint VLSaddFeature (

unsigned char *licenseStr,




licenseStr The license string that will be added.

unused1 Should be NULL.


3.1.2. Description

Dynamically adds licensing information about a feature into the license server and adds the licensecode to the license server’s internal tables. If licensing information for this feature and version alreadyexists in the license server’s tables, it may be overwritten with the new information contained in licen-seStr.

A feature is not permanently added to the license server, but is cleared when the license server is shutdown and restarted.

3.1.3. Returns



VLS_CALLING_ERROR Attempted to use stand-alonemodewith network only library,or network modewith stand-alone library.

LS_NO_SUCCESS licenseString is NULL


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

VLS_NO_SERVER_ RUNNING License server on specified host is not available for processingthe license operation requests.



VLS_NO_SERVER_FILE License server has not been set and is unable to determinewhich license server to use.





LS_NO_NETWORK Generic error indicating that the network is unavailable in serv-icing the license operation.

LS_NORESOURCES An error occurred in attempting to allocatememory needed bythis function.


3.2. VLSaddFeatureToFile

3.2.1. Syntaxint VLSaddFeatureToFile (




unsigned char *unused3 );


licenseString The license_string character.




3.2.2. Description

Writes a license dynamically to either the redundant license file or normal license file. The feature ispermanently added to the license server when the license server is shutdown and restarted.

3.2.3. Returns



VLS_CALLING_ERROR Attempted to use stand-alonemodewith network only library,or network modewith stand-alone library.

LS_NO_SUCCESS licenseString is NULL


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

VLS_NO_SERVER_ RUNNING License server on specified host is not available for processingthe license operation requests.



VLS_NO_SERVER_FILE License server has not been set and is unable to determinewhich license server to use.





LS_NO_NETWORK Generic error indicating that the network is unavailable in serv-icing the license operation.



3.3. VLSaddServerToPool

3.3.1. Syntaxint VLSaddServerToPool (

char *server_name,

char *server_addr );


server_name Name of the license server to add to the pool.

server_addr IP address of the license server.

3.3.2. Description

Will send a request to add a new license server into the pool. This API will actually modify the licenseserver redundant license file in order to add the given license server to the pool.

3.3.3. Returns



VLS_CALLING_ERROR n server_name is NULLn server_address is NULLn Using stand-alone library. This function cannot

be used with stand-alone library.

LS_NO_SUCCESS Generic error indicating that the license server couldnot be added to the pool.

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

VLS_SERVER_ALREADY_ PRESENT Attempted to add a license server that is already inthe pool.

VLS_POOL_FULL Pool already has maximum number of license servers.No more license servers can be added.

VLS_BAD_HOSTNAME hostName is not valid.

VLS_NOT_AUTHORIZED Invalid user.


VLS_CONF_FILE_ERROR Error in configuration file.

VLS_NO_SERVER_ RUNNING License server on specified host is not available forprocessing the license operation requests.


3.3. VLSaddServerToPool 195




LS_NO_NETWORK Generic error indicating that the network is unavail-able in servicing license operation.



3.4. VLSdelServerFromPool

3.4.1. Syntaxint VLSdelServerFromPool (

char *server_name,

char *server_addr );


server_name Name of the license server to delete from the pool.

server_addr IP address of license server.

3.4.2. Description

Removes a license server’s name from the pool of redundant license servers. This API modifies theredundant license file in order to delete the given license server from the pool.

3.4.3. Returns



VLS_CALLING_ERROR n server_name is NULLn server_address is NULLn Using stand-alone library. This function cannot be

used with stand-alone library.

LS_NO_SUCCESS Generic error indicating that the license server could not bedeleted from the pool.


VLS_SERVER_NOT_PRESENT Attempted to delete a license server that is not in the pool.

VLS_ONLY_SERVER Cannot remove the last license server from the pool.

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

VLS_BAD_HOSTNAME hostName is not valid.

VLS_NOT_AUTHORIZED Invalid user.

VLS_CONF_FILE_ERROR Error in configuration file.




3.4. VLSdelServerFromPool 197



LS_NO_NETWORK Generic error indicating that the network is unavailable forservicing license operation.

LS_NORESOURCES An error occurred in attempting to allocatememory neededby this function.


3.5. VLSdiscoverExt

3.5.1. Syntaxint VLSdiscoverExt (

unsigned char *feature name,



int *num_servers,

VLSdiscoverInfo *discoverInfo,

int option_Flag,

int sharing_crit,

char *vendor_list );





num_servers Number of license servers for which discoverInfo array is allocated.

discoverInfo The core function that receives the broadcast message, splits and puts thelicense server’s name in array format. VLSdiscoverInfo struct that will con-tain requested information.

option_Flag The option flag is allowed to be logically ORed with other flags. However,this flag will have first priority. Valid flags are:

n VLS_DISC_NO_USERLIST – Do not check the host list specified by theuser. By default, it first consults the LSFORCEHOST environment var-iable. If LSFORCEHOST does not exist, it reads the fileLSHOST/lshost.

n VLS_DISC_RET_ON_FIRST – If the combined query list is NULL, itreturns the name of the first contacted license server in the server_list, as soon as it is contacted by any of the license servers. Other-wise, it returns the name of the first contacted license server spec-ified in the combined query list. If this option is not specified.VLSdiscover returns all the license servers that responded.

n VLS_DISC_PRIORITIZER_LIST – Treat the combined query list as aprioritized one, left most being the highest priority host. It returnsin server_list, license servers sorted in the order of priority host. Ifthis option is not specified, the combined query list is treated as ran-dom.

n VLS_DISC_REDUNDANT_ONLY – Expecting reply only from redun-dant license servers. All non-redundant license servers will ignorethemessage.

n VLS_DISC_DEFAULT_OPTIONS – This flag is a combination of theaforementioned flags. Use it if you are not sure which flag you want




to specify.

sharing_crit The license server will match client’s internal information with the keys it isalready granted. Values are:

n VLScg_NO_SHARINGn VLScg_USER_SHARINGn VLScg_HOSTNAME_SHARINGn VLScg_XDISPLAY_SHARINGn VLScg_VENDOR_SHARING

vendor_list Consists of server names. These license serves will be contacted. Thenames 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 inthe original (before the call) vendor_list.

3.5.2. Description

Returns the license server characteristic information of the license server which has the license tokensfor a specified feature and version. The client can specify a license server preference based on somecriteria.

Each license server that is contacted will determine if it has a license that matches the requested fea-ture name and version. If found, the license server will then notify the client with the following infor-mation:

n Protocol supported

n Total number of clients connected to the license server

n Server IP address

n Number of units/tokens available

n Whether this client has already been granted a license for the feature and version (based onsharing_crit)

3.5.3. Returns



VLS_CALLING_ERROR num_servers is less than or equal to zero.

VLS_NO_RESPONSE_TO_ BROAD-CAST

License servers have not responded.

LS_NO_SUCCESS Generic error indicating the license server’s characteristic infor-mation could not be retrieved.


LS_BAD_PARAMETER License server’s name is NULL or an empty string.


LS_SERVER_DOES_NOT_ EXIST Named license server does not exist.

LS_LEADER_NOT_KNOWN Leader name is not known.

LS_NON_REDUNDANT_ SERVER_CONTACTED

The license server contacted is non-redundant, and does notsupport this function.

LS_UNRESOLVED_SERVER_NAME License server’s name is not resolvable.

VLS_LEADER_NOT_ PRESENT Leader name is not known.

VLS_NON_REDUNDANT_ SERVER The license server contacted is non-redundant, and thereforedoes not support this function.




3.6. VLSgetDistbCrit

3.6.1. Syntaxint VLSgetDistbCrit (

char *feature_name,

char *feature_version,

char *dist_crit,

int *distcrit_buflen );



feature_version Version of the feature. Must be unique.

dist_crit (OUT) Dist_crit consists of the names of license server, which will have licensesfor the given feature_name and version. The dist_crit string must benull-terminated.

distcrit_buflen Size ofmemory allocated for dist_crit.

3.6.2. Description

Returns the current token distribution status for the given license feature and version.

3.6.3. Returns



VLS_CALLING_ERROR n feature_name is NULLn version is NULLn dist_crit is NULLn dist_crit_len is zero or negativen 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 featurename and version cannot be NULL at the same time.


LS_BUFFER_TOO_SMALL dist_crit buffer not large enough to store information.





VLS_NON_REDUNDANT_ FEATURE Feature is non-redundant and thus cannot be used in thisredundancy-related operation.

VLS_DIFF_LIB_VER Version mismatch between license server API and client API.

VLS_VENDORIDMISMATCH The vendor identification of the requesting application doesnot match the vendor identification of the feature for whichthe license server has a license. This error occurs only whenclient is older than version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.




LS_NO_NETWORK Generic error indicating that the network is unavailable inservicing license operation.



3.6. VLSgetDistbCrit 203


3.7. VLSgetDistbCritToFile

3.7.1. Syntaxint VLSgetDistbCritToFile (

char *feature_name,


char *file_name );




file_name License server will write distribution criteria for the specified feature orversion to the file.

3.7.2. Description

Requests the license server provide current token distribution status for the given license feature andversion, or for all features, or for all versions, or for all features and all versions (wild card charactersare acceptable).

3.7.3. Returns



VLS_CALLING_ERROR n feature_name is NULLn file_name is NULL.n Using stand-alone library. This function cannot be

used with stand-alone library.


VLS_FILE_OPEN_ERROR An error occurred opening the file.



VLS_DIFF_LIB_VER Version mismatch between license server API and clientAPI.

VLS_SERVER_SYNC_IN_ PROGRESS License server synchronization process.








LS_BUFFER_TOO_SMALL Buffer provided is too small.

LS_NO_SUCH_FEATURE feature_version is non-existent.

LS_NON_REDUNDANT_ SERVER_CONTACTED

LSHOST is set to non-redundant license server.

VLS_CALLING_ERROR License server’s name is NULL or an empty string.

VLS_LEADER_NOT_ PRESENT Leader name is not known.

VLS_NON_REDUNDANT_ SRVR Sets LSHOST to non-redundant license server.


3.7. VLSgetDistbCritToFile 205


3.8. VLSgetLeaderServerName

3.8.1. Syntaxint VLSgetLeaderServerName (

char *leader_name,

int leader_name_len );


leader_name Current lead license server’s IP address. Space to be allocated by thecaller.

leader_name_len Size of leader_name.

3.8.2. Description

Returns the IP address of the contacted leader server into the buffer specified by the leader_nameparameter. 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 VLSget-

ContactServer 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 errorcodes:


VLS_CALLING_ERROR n leader_name is NULLn leadername_len is NULL.

LS_BUFFER_TOO_SMALL leadername_len is smaller than the license server namethat will be returned.

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

VLS_LEADER_NOT_PRESENT Unknown leader.


VLS_NON_REDUNDANT_ FEATURE Feature is non-redundant and thus cannot be used inthis redundancy-related operation.






LS_NO_NETWORK Generic error indicating that the network is unavailablein servicing license operation.


LS_UNRESOLVED_IP_ADDRESS IP address given is not correct.


LS_BUFFER_TOO_SMALL Buffer provided is too small.


VLS_LEADER_NOT_PRESENT Leader name is not known.

VLS_NON_REDUNDANT_SRVR The license server is non-redundant, and therefore doesnot support this operation.


3.8. VLSgetLeaderServerName 207


3.9. VLSgetLicSharingServerList

3.9.1. Syntaxint VLSgetLicSharingServerList (

char *feature_name,


char *server_list_len,

int *server_list,

int *num_servers );




server_list A list that contains the license server’s names (hostNames or IPaddresses).

server_list_len License server will retrieve all the license servers names. If the list islarger than the specified limit, it will be truncated.

num_servers Identifies the number of license servers.

3.9.2. Description

Returns the license server names which are sharing tokens for a given feature name and version. Theserver_name_listwill contain license server names (hostNames or IP addresses).

3.9.3. Returns



VLS_CALLING_ERROR n feature_name is NULLn feature_version is NULLn server_list is NULLn server_list_len is zero.n License server’s name is NULL or an empty string.n Both feature name and version cannot be NULL at

the same time.

LS_BUFFER_TOO_SMALL server_list_len is smaller than license server name thatwill be returned.

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










LS_UNRESOLVED_HOSTNAME Host name given is not correct.




3.9. VLSgetLicSharingServerList 209


3.10. VLSgetPoolServerList

3.10.1. Syntaxint VLSgetPoolServerList (

char *outBuf,

int outBufSz );


outBuf (OUT) Output buffer.

outBufSz Output buffer size.

3.10.2. Description

Returns a list of license servers and their status where the servers are in the same pool as the con-tacted redundant license server. The status for each license server in the list indicates whether thatserver is active (running) or not. If a non-redundant license server is contacted, the VLS_NON_REDUN-DANT_SRVR error code is returned. The license server to be contacted is selected by VLSget-ContactServer, so you must set the license server’s name before calling VLSgetPoolServerList.

3.10.3. Returns




LS_BUFFER_TOO_SMALL The output buffer is too small.

VLS_SERVER_SYNC_IN_PROGRESS License server synchronization in process.


LS_NORESOURCES Insufficient resources (such as memory) as available tocomplete the request.


VLS_ LEADER_NOT_PRESENT Unknown leader.


3.11. VLSsetServerLogState

3.11.1. Syntaxint VLSsetServerLogState (

int event,

int state );


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

n LOG_SRVR_UP (the license server is running)n LOG_LDR_ELECT (a pool leader has been elected)n LOG_HRT_BT (license server heartbeat)n LOG_BORROW_REQ_RESP (token borrowing request and response)n LOG_USG_NOTIFY (follower notifies pool leader of token use)n LOG_CHNG_DIST_CRT (token distribution criteria has changed)n LOG_DIST_CRT_SYNC (the pool servers are synchronizing distribution

criteria)n LOG_CFG_FILE (the LSERVRLF file changed)n LOG_SRVR_DOWN (license server is down)n LOG_MOD_SERVER (addition or deletion of a license server to or from the

pool)n 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 VLSget-ContactServer, so you must set the license server’s name before calling VLSgetPoolServerList.

3.11.3. Returns




VLS_DIFF_LIB_VER Version mismatch between license server API and client API.

VLS_FEATURE_INACTIVE The given feature is inactive on the specified license server.

VLS_MSG_TO_LEADER The request has been sent to the leader license server.

VLS_NOT_AUTHORIZED The user making the request is invalid.

VLS_BAD_SERVER_MESSAGE Amessage returned from the license server could not beunderstood.

3.11. VLSsetServerLogState 211

Chapter 4:Volume Transaction Licensing API

Using the volume transaction licensing, you can limit and track the number of times a feature is usedand implement your own logic ofmanaging these limits, such as howmany units a licensed featurewill consume, when to generate an alert, how to increment the limit, and so on. For details about therelated concepts, see Chapter 12 - Volume Transaction Licensing in the Sentinel RMS SDK Developer’sGuide.



VLSgetConsumeLimit Returns the current limit stored.

VLSsetConsumeLimit Increases, decreases, or resets the limit.

VLSgetContextData Returns the current context data stored.

VLSsetContextData Sets the current context data with the data passed in context_buff.

4

214 Chapter 4: Volume Transaction Licensing API

4.1. VLSgetConsumeLimit

4.1.1. SyntaxLS_STATUS_CODE VMSWINAPI VLSgetConsumeLimit (

LS_HANDLE lshandle,

CONSUME_LIMIT_TYPE consume_type,

long LSFAR *consume_value,

LS_CHALLENGE LSFAR *challenge );

Parameter Direction Data Type Description

lshandle IN LS_HANDLE The license handle. A valid license handleis returned by the RMS license serverwhen the license request is successful.

consume_type IN CONSUME_LIMIT_TYPE Specifies the type of the limit whose cur-rent value is to be obtained. It can beeither of the following:

n VLS_LIMIT_TYPE_VOLUME – Setsthe number of transaction-basedlimit.

n 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 withthe current limit on its return.

challenge UNUSED LS_CHALLENGE Currently unused. Use NULL.

4.1.2. Description

Returns the current limit stored in the volume transaction licensing database for a particular license.

4.1.3. Returns

The API returns LS_SUCCESS when the API is successful otherwise it returns the following error codes:

Status Description

VLS_CALLING_ERROR n When the consume_value is NULL.n When the consume_type is neither VLS_LIMIT_

TYPE_VOLUME, nor VLS_LIMIT_TYPE_DURATION.

LS_BADHANDLE An invalid handle.

VLS_NOT_SUPPORTED If the API is called with a handle corresponding to aqueued client or a capacity token.

VLS_NO_RECORDS_FOUND No records for the limit in the database.

VLS_OPERATION_NOT_SUCCESSFUL The requested operation failed for any other reason.

4.2. VLSsetConsumeLimit

4.2.1. SyntaxLS_STATUS_CODE VMSWINAPI VLSsetConsumeLimit (

LS_HANDLE lshandle,

CONSUME_LIMIT_TYPE consume_type,

CONSUME_OPERATION_TYPE consume_op_type,

long LSFAR *consume_value,



lshandle IN LS_HANDLE The license handle. A valid license handleis returned by the RMS license serverwhen the license request is successful.

consume_type IN CONSUME_LIMIT_TYPE Specifies the type of the limit whose cur-rent value is to be obtained. It can beeither of the following:

n VLS_LIMIT_TYPE_VOLUME - Setsthe number of transactionbasedlimit.

n VLS_LIMIT_TYPE_DURATION -Sets the duration-based limit.

consume_op_type IN CONSUME_OPER-ATION_TYPE

Specifies the type of the operation to beperformed. It can be either of the fol-lowing:

n VLS_SET - Increments or dec-rements the current limit by thevalue specified in the consume_value. To decrement, specify anegetive value.

n VLS_RESET - Overwrites the cur-rent limit value with the valuespecified in consume_value.

consume_value IN/OUT long A pointer to a user allocated memoryfilled by the value (limit) to set or reset.


4.2.2. Description

Increases, decreases, or resets the limit in the volume transaction licensing database for a particularlicense.

4.2. VLSsetConsumeLimit 215


4.2.3. Returns


Status Description

VLS_CALLING_ERROR n When the consume_value is NULLn When the consume_type is not VLS_LIMIT_TYPE_

VOLUME or VLS_LIMIT_TYPE_DURATIONn When the consume_op_type is not VLS_SET or

VLS_RESET


VLS_NOT_SUPPORTED If the API is called with a handle corresponding to aqueued client or a capacity token.

VLS_NEW_RECORD_FOUND If the limit value has been updated by any other processafter the current process has retrieved the limit value. TheAPI function would also return the current limit value inthe consume_value parameter.

VLS_OPERATION_NOT_SUCCESSFUL The requested operation failed for any other reason.

4.3. VLSgetContextData

4.3.1. SyntaxLS_STATUS_CODE VMSWINAPI VLSgetContextData (

LS_HANDLE lshandle,

unsigned char LSFAR *context_buff,

unsigned long buff_len,



lshandle IN LS_HANDLE The license handle. A valid license handle isreturned by the license server when thelicense request is successful.

context_buff OUT unsigned char A pointer to a user allocated memory to befilled by the API with the current contextdata on its return.

buff_len IN unsigned long Contains the length of the allocated buffer.


4.3.2. Description

Returns the current context data stored in the volume transaction licensing database for a particularlicense.

4.3.3. Returns


Status Description

VLS_CALLING_ERROR n When context_buff is NULL.n When buff_len is less than zero or greater than VLS_

MAX_CONTEXT_LEN+1


VLS_NOT_SUPPORTED If the API is called with a handle corresponding to a queuedclientor a capacity token.

VLS_NO_RECORDS_FOUND No records for the context in the database.

4.3. VLSgetContextData 217


4.4. VLSsetContextData

4.4.1. SyntaxLS_STATUS_CODE VMSWINAPI VLSsetContextData (

LS_HANDLE lshandle,

unsigned char LSFAR *context_buff,

unsigned long buff_len,



lshandle IN LS_HANDLE The license handle. A valid license handle isreturned by the license server when thelicense request is successful.

context_buff IN unsigned char Contains a pointer to a user allocated mem-ory having the context data to be written inthe consume database.

buff_len IN unsigned long Contains the length of the allocated buffer.


4.4.2. Description

Sets the current context data with the data passed in context_buff in the volume transaction licensingdatabase for a particular license.

4.4.3. Returns


Status Description

VLS_CALLING_ERROR n When context_buff is NULL.n When buff_len is less than zero or greater than VLS_MAX_CON-

TEXT_LEN+1


VLS_NOT_SUPPORTED If the API is called with a handle corresponding to a queued clientor a capacity token.

VLS_OPERATION_NOT_SUCCESSFUL

The requested operation failed for any other reasons.

Chapter 5:Capacity License API

As the name suggests, the capacity license feature defines the capacity of a license. A capacity licenseis identified by feature name, version and capacity. The license request is granted on the basis of fea-ture name, version and capacity. Capacity licensing in Sentinel RMS Development Kit allows multiplelicense of same feature, version and different capacity to exist on the same Sentinel RMS licenseserver. For examples of capacity licensing and more information on this feature, see the Sentinel RMSSDK Developer's Guide.

Capacity Licensing is available through APIs only and is not supported by the Sentinel RMS Shell.



VLSrequestExt2 Supports capacity and non-capacity requests

VLSgetFeatureInfoExt Tracks the features available on the server

VLSgetCapacityList Returns the list of all the capacity for particular feature and ver-sion.

VLSgetClientInfoExt Returns the list of all clients running for a particular feature, ver-sion, and capacity

VLSdeleteFeatureExt Deletes a license from the server based on feature, version andcapacity

VLSgetCapacityFrom Handle Returns the team capacity and user capacity allocated to a handle

VLSsetTeamId Redefines team ID functions

VLSsetTeamIdValue Registers a customized team ID value

5

220 Chapter 5: Capacity License API

5.1. VLSrequestExt2

5.1.1. SyntaxVLSrequestExt2 (

unsigned char *license_system,

unsigned char *publisher_name,

unsigned char *product_name,


unsigned long *units_reqd,




VLSserverInfo *serverInfo,

unsigned long *team_capacity_reqd,

unsigned long *capacity_reqd,


unsigned long *special_flag );


license_system Unused.

n Use LS_ANY as the value of this variable.n LS_ANY is specified to indicate a match against the installed

license system.

publisher_name n A string identifying the publisher of the product. Limited to32 characters and cannot be NULL.

n Company name and trademark may be used.

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

version n Version of the feature for which a license code is requested.n May consist of any printable characters. Limited to 11 char-

acters.n Version can be NULL.

units_reqd n The number of licenses required. The license server verifiesthat the number of units exist and may reserve those units.The number of available units is returned.

n If the number of licenses available with the license server isless than the requested number, the number of availablelicenses will be returned using units_reqd. If units_reqd isNULL, a value of 1 unit is assumed.

n To use the capacity licensing it is necessary that unitsrequired be always 1.

log_comment n A string to be written by the license server to the comment


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

desired.

challenge n The challenge structure. If challenge-responsemechanism isnot being used, this pointer must be NULL.

n The response to the challenge is provided in the same struc-ture, provided a license was issued, i.e., provided the func-tion VLSrequestExt2 returns LS_SUCCESS.

lshandle n The handle for this request is returned in lshandle. This han-dle must be used to later update and release this licensecode.

n A client can havemore than one handle active at a time.n Space for lshandlemust be allocated by the caller.

serverInfo n This information is passed to the license server for use inserver hook functions.

n VLSinitServerInfo must be called to initialize serverinfo.

team_capacity_reqd n Required team capacityn If the server does not have the requested capacity this field

will return the team capacity available with the server for thisfeature and version.

n If the request is made for a non-capacity license, this must bepassed as NULL.

capacity_reqd n Required user capacityn If the server does not have the requested user capacity, this

field will return the user capacity available with the server forthis feature and version.

n If the request is made for a non-capacity license this must bepassed as NULL.

unused1 Reserved for future use.

special_flag An IN/OUT parameter with the following possible values:

n The IN value can be VLS_IGNORE_GRACE_ERROR (default) orVLS_NOTIFY_GRACE_ERROR. When the flag is set to VLS_IGNORE_GRACE_ERROR, any error encountered during theinstallation of a grace license will be ignored and theVLSrequestExt2 function will succeed. When the flag is set toVLS_NOTIFY_GRACE_ERROR, any error encountered duringthe installation of a grace license will make the VLSreque-stExt2 function fail (and the application will not run).

n The OUT value will be the grace period-related error code.n VLS_IGNORE_GRACE_ERROR will be applicable to the other

variants of the request API functions (like LSrequest,VLSrequestExt, and so on).



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 thecapacity_reqd or team_capacity_reqd field should contain the available capacity.

VLSrequestExt2must be used whenever the user wishes to use the capacity feature in a license. Thecall 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, hewould be using the VLSsetTeamId/ VLSsetTeamIdValue APIs.

The following information is sent by the licensing library as user identification information:

n User Namen Host Namen X-Display namen Vendor defined string

This information is used by the server when it manages or creates teams. VLSsetTeamId/ VLSset-TeamIdValue needs to be called before calling the request API so that it can pass the correct infor-mation 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 withsay "XYZ" user name, the license server would see the request as if it is coming from user "SENTINEL".Now

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

n User capacity has been exhausted

n Team capacity has been exhausted in case of pooled licenses only

5.1.3. Returns




Both feature name and version cannot be NULL at thesame time.

VLS_CALLING_ERROR n lshandle is NULLn challenge argument is non NULLn Attempted to use stand-alonemodewith network-


VLS_NO_LICENSE_GIVEN n unitsReqd is zeron License request is denied due to server hook failure.


LS_NOLICENSESAVAILABLE All licenses are in use.

LS_INSUFFICIENTUNITS License server does not have sufficient licensing units forrequested feature to grant license.




VLS_CLK_TAMP_FOUND n License server has determined that the client sys-tem lock has been modified.

n The license for this feature has time tampering pro-tection enabled, so the license operation is denied.

VLS_VENDORIDMISMATCH The vendor identification of requesting application does




not match the vendor identification of the feature forwhich the license server has the license. This error occursonly when client is older than version 6.3 else the errorreturned is VLS_NO_SUCH_FEATURE.




VLS_NO_SERVER_RUNNING License server on specified host is not available for proc-essing license operation request.



VLS_NO_SERVER_FILE n No license server has been setn Unable to determine which license server to use.

VLS_BAD_SERVER_MESSAGE Message from the license server could not be understood.



VLS_INTERNAL_ERROR Failure occurred in setting timer. (Timer is only attemptedto be set if timer is available for platform and if licenserequires timer for updates.)

VLS_INSUFFICIENT_TEAM_ CAPACITY License server does not currently have sufficient teamcapacity available.

VLS_INSUFFICIENT_USER_ CAPACITY License server does not currently have sufficient usercapacity available for this team member.


5.2. VLSgetFeatureInfoExt

5.2.1. SyntaxLS_STATUS_CODE VLSgetFeatureInfoExt (




int index,

char *unused1,

long *unused2,

VLSfeatureInfo feature_info );




capacity Capacity of the feature.

index Used to specify a particular feature.

unused1 Use NULL as value.


feature_info The structure in which information will be returned. Spacemust be allo-cated 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.

n If information about a non-capacity license is desired, capacity should be passed as NULL andfeaturemust be non-NULL.

n If information about all licensed features (capacity as well as non-capacity) is desired, featurename should be NULL, and index should be used in a loop.

5.2.3. Returns



VLS_CALLING_ERROR n featureinfo is NULLn index is negativen Attempted to use stand-alonemodewith network-only

library, or network modewith stand-alone library.

5.2. VLSgetFeatureInfoExt 225



VLS_APP_UNNAMED Version is NULL when name is non_NULL

VLS_NO_MORE_ FEATURES Finished retrieving feature information for all features on licenseserver.




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




VLS_NO_SUCH_ FEATURE License server does not have license that matches requestedfeature, version and capacity.


5.3. VLSgetCapacityList

5.3.1. Syntax

VLSgetCapacityList (

ifndef LSNOPRONTO

unsigned char LSFAR *feature_name,

unsigned char LSFAR *feature_version,

int LSFAR *index,

unsigned long LSFAR *bufferSize,

char LSFAR *capacityList,

char LSFAR *log_comment,

unsigned long LSFAR *unused2

#endif );




index Returns the index of the license up to which the capacity has beenretrieved based on the bufferSize

bufferSize Specifies the size of capacityList.

capacityList An array containing a list of all the capacities available for this feature andversion, separated by space. The caller should allocate the space.

log_comment 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 differentcapacity. This function returns list of capacities as one string, each capacity separated by a space char-acter.

If capacityList is passed as NULL, the API returns the buffersize required. VLSgetCapacityList returns anerror if the license is a non-capacity license. For example if Sentinel RMS license server has followinglicenses:

n Feature F1, version V1, capacity 500



n Then this API would return "500 1000 5000" as the output string in "capacity_list"

For a discussion of pooled versus non-pooled capacity licenses, refer to the Sentinel RMS Devel-opment Kit Developer's Guide.

5.3. VLSgetCapacityList 227


5.3.3. Returns



VLS_NO_SUCH_FEATURE License server does not have a license that matches the requestfeature, version and capacity.

VLS_APP_UNNAMED featureName is NULL.

VLS_CALLING_ERROR Attempted to use stand-alonemodewith network-only library,or network modewith stand-alone library.










5.4. VLSgetClientInfoExt

5.4.1. SyntaxVLSgetClientInfoExt (




int index,

char *log_comment,

VLSclientInfo *client_info );





index Used to specify a particular client.

log_comment Comment.

client_info The structure in which information will be returned. Space allocated bythe caller.

5.4.2. Description

Returns the list of all the clients running for a particular feature, version and capacity. If the capacity isspecified as NULL, this API shall return the list of all the clients for a particular feature and version. Thesuggested use of this function is in a loop, where the first call is made with index 0which retrieves infor-mation about the first client. Subsequent calls, when madewith 1, 2, 3, and so on, will retrieve infor-mation about other clients of that feature type.

Memory for client_info should be allocated beforemaking the call.

5.4.3. Returns



VLS_APP_UNNAMED n featureName is NULL.n version is NULL


VLS_CALLING_ERROR n clientInfo parameter is NULLn index is negativen Attempted to use stand-alonemodewith network-only

library, or network modewith stand-alone library.

5.4. VLSgetClientInfoExt 229



VLS_NO_MORE_CLIENTS Finished retrieving client information for all clients.

VLS_NO_SUCH_FEATURE License server does not have a license that matches requestedfeature, version and capacity.

VLS_MULTIPLE_VENDORID_FOUND

The license server has licenses for the same feature and versionfrom multiple vendors. It is ambiguous which feature isrequested.









5.5. VLSdeleteFeatureExt

5.5.1. SyntaxVLSdeleteFeatureExt (







unsigned char *unused2 );





log_comment Unused. Use NULL as value.

challenge Unused. Use NULL as value.



5.5.2. Description

Deletes a license from the server based on feature, version and capacity. If the capacity is NULL, thisAPI 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



VLS_APP_UNNAMED n featureName is NULL.n version is NULL


VLS_CALLING_ERROR Attempted to use stand-alonemodewith network-onlylibrary, or network modewith stand-alone library.


VLS_DELETE_LIC_FAILED Generic error indicating the feature has not been deleted.

5.5. VLSdeleteFeatureExt 231



VLS_VENDORIDMISMATCH The vendor identification of the requesting application doesnot match the vendor identification of the feature for whichthe license server has a license. This error occurs only whenclient 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 ver-sion from multiple vendors. It is ambiguous which feature isrequested.




VLS_NO_SERVER_FILE No license server has been set and unable to determinewhich license server to use.





5.6. VLSgetCapacityFromHandle

5.6.1. SyntaxVLSgetCapacityFromHandle (

LS_HANDLE lshandle,

unsigned long LSFAR *team_capacity,

unsigned long LSFAR *user_capacity

unsigned long LSFAR *license_capacity );


handle Handle

team_capacity Team capacity allocated to the handle and issued by the server

user_capacity User capacity allocated to the handle and issued by the server

license_capcity License capacity allocated to the handle

5.6.2. Description

VLSgetCapacityFromHandle returns the team capacity and user capacity allocated to a handle.

5.6.3. Returns



LS_BADHANDLE The handle is invalid.


5.6. VLSgetCapacityFromHandle 233


5.7. VLSsetTeamIdSee VLSsetSharedId/ VLSsetTeamId.

5.8. VLSsetTeamIdValueSee VLSsetSharedIdValue/ VLSsetTeamIdValue.

5.8. VLSsetTeamIdValue 235

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 inreserve until a license is available. Once the license is available, the license server will then notify therequesting application that the license is now ready for use.



VLSqueuePreference Struct Specifies the clients preference for how it wishesto be placed in the queue.

VLSserverInfo Struct Stores information about the server.

VLSgetQueuedClientInfo Struct Returns client information.

VLSqueuedRequestVLSqueuedRequestExt

An integrated request for an authorized license code from thelicense server. Use this API to:

n Request a license, with option to queue (requestFlag =VLS_REQ_GET | VLS_REQ_QUEUE).

n Request a license without queuing (requestFlag = VLS_REQ_GET). This option has the same effect as calling anon-queuing API request (LSRequest, VLSrequestExt,etc.).

n Request to be placed in the queue, even if the licenseserver has available licenses (requestFlag = VLS_REQ_QUEUE).

VLSgetQueuedClientInfo Retrieves the current information of a queued client, such asthe number of requested licenses, feature_name, version,and index.

VLSremoveQueuedClient Removes a queued client from the queue.

VLSremoveQueue Deletes the entire queue.

VLSgetHandleStatus Reports the current status of the handle.

VLSupdateQueuedClient Once the client has been put in the queue, it must call this APIperiodically to inquire its current status with the licenseserver. Moreover, calling this function has the effect of inform-ing the license server that the client is alive and is still seekingthe license.

VLSgetQueuedLicense Obtains license, once it has been granted. This function iscalled only after a call to VLSupdateQueuedClient reveals thata license has been granted to a queued client.

6

238 Chapter 6: License Queuing API


VLSqueuePreference Struct Specifies the client preference for getting into the queue.

VLSinitQueuePreference Initializes provided queue preference structure to defaultvalues.

6.1. The License Queuing Example Code

You may need to format spaces in an editor if using the sample code given below.

{/* License was available, run the application! */}else if (request_flag & VLS_REQ_QUEUE){/* Was placed on the queue *//* TODO: Start timer for sending periodic queue updates (every 50 secs is recommended). Assumefunction TimerHandler () will be called when the timer expires (see below).*/}}else{/* Queued request was not successful, clean up and exit. */VLScleanup ();return (1);} /* End if success */} /* end main () */

void TimerHandler (){/* Called periodically in order to check the queue status.*/long expiration_time;LS_STATUS_CODE returnCode;returnCode = VLSupdateQueuedClient (ls_handle,&expiration_time,(unsigned char LSFAR *)NULL,(LS_CHALLENGE LSFAR *) NULL);/* Is the queued license available*/if (returnCode == LS_SUCCESS && expiration_time > 0 ){if ((returnCode =VLSgetQueuedLicense(ls_handle,(unsigned char LSFAR *) NULL,(LS_CHALLENGELSFAR *) NULL))== LS_SUCCESS){/*Disable the application’s timer and run the application! *//* Enable automatic heartbeats to the server */VLSdisableAutoTimer (ls_handle, VLS_ON);}else{/* Error getting the license, clean up and quit. */VLScleanup ();/* Terminate the process */}}}

6.1. The License Queuing Example Code 239


6.2. VLSqueuePreference Structtypedef struct {

long wait_time;

long hold_time;

int priority_num;

long absPosition;

long grpPosition;

} VLSqueuePreference;

Member Description

wait_time Maximum time, the client can be in queue.

hold_time After allotment, themaximum time interval for which the server will keep therequested units reserved for this client.

priority_num Priority vis-a-vis other clients, as decided by the client application. For use infuture. Not implemented in SLM7.0.

absPosition Themaximum position within the queue, before which the client can bequeued.

grpPosition Themaximum position within the queue, considering only those queuedclients that belong to the same group as this client, before which the client canbe queued -1 if the client doesn't care.

6.3. VLSserverInfo Structtypedef struct {

char identifier[VLS_MAX_NAME_LEN];

char inBuf[VLS_MAX_BUF_LEN];

char outBuf[VLS_MAX_BUF_LEN];

} VLSserverInfo;

Member Description

identifier The name of the server hook which the user wants to call.

inBuf String passed to the server.

outBuf String returned by the server.

6.3. VLSserverInfo Struct 241


6.4. VLSQueuedClientInfo Structtypedef struct queued_client_info_struct {

char user_name[VLS_MAXLEN];


char x_display_name[VLS_MAXLEN];

char shared_id_name[VLS_MAXLEN];

char group_name[VLS_MAXLEN];

unsigned long host_id;

long server_start_time;

long server_end_time;

unsigned long qkey_id;

int num_units;

int num_resvd_default;

int num_resvd_native;

long wait_time;

long hold_time;

int priority_num;

long absPosition;

long grpPosition;

long availabilityTime;

} VLSqueuedClientInfo;

Member Description

user_name The login name of the user using the application, whereMAXLEN is setto 64 characters.

host_name Name of the host/computer where the user is running the application,whereMAXLEN is set to 64 characters.

x_display_name Name of the X display where the user is displaying the application,whereMAXLEN is set to 64 characters.

shared_id_name A special vendor-defined ID that can be used for license sharing deci-sions. It always has the fixed value, defaultsharing- ID, unless it ischanged by registering a custom function using the VLSsetSharedIdAPI call. Themaximum length of the string is set to 64 characters.

group_name Name of the reserved group to which the user belongs, whereMAX-LEN is set to 64 characters. If the user does not belong to an explicitlynamed group, DefaultGrp is returned.

host_id The host ID of the computer on which the user is working.

server_start_time server_start_time is the start time of the license token.

server_end_time server_end_time is the end time of the license token. server_end_time should be interpreted as as start_time + heart beat interval of thelicense.

qkey_id Identifier of the client queue.

Member Description

num_units Number of units consumed by the client so far.

num_resvd_default The number of tokens given to this queued token from default pool,that is from the unreserved tokens.

num_resvd_native The number of tokens given to this queued token from its reservationgroup.

wait_time Maximum time (in seconds), the client can be in queue.

hold_time After allotment, themaximum time interval (in seconds) for which theserver will keep the requested units reserved for this client.

priority_num Priority vis-a-vis other clients, as decided by the client application. Foruse in future. Not implemented in SLM7.0.

absPosition Themaximum position within the queue, before which the client canbe queued.

grpPosition Current position within the queue, considering only those queuedclients that belong to the same group to which this client belongs to.

6.4. VLSQueuedClientInfo Struct 243


6.5. VLSqueuedRequest and VLSqueuedRequestExt

6.5.1. Syntaxint VLSqueuedRequest(




unsigned char) *version,





VLSqueuePreference *qPreference,

int requestFlag);

int VLSqueuedRequestExt(




unsigned char) *version,





VLSqueuePreference *qPreference,

int requestFlag,

VLSserverInfo server_info );


license_system A license requested in the system. Pointer to the string which uniquelyidentifies a particular license system.

publisher_name Refers to the name of the publisher (manufacturer) of the product. Can-not be NULL and must be unique. It is recommended that a companyname and trademark be used.

product_name Feature name. The name of the product requesting licensing resources.Cannot be NULL and must be unique.

version Version for which licenses are requested. Must be unique for the asso-ciated feature

units_reqd Number of units requested to run the license. The license system verifiesthat the requested number of units exists and it is possible to reservethose units, but no units are actually consumed at this time. The default is1, and this value is used if a NULL value is passed.


log_comment A string that is written by the licensemanager to the comment field of theusage log file.

challenge Pointer to a challenge structure. The challenge-response will also bereturned.

lshandle Handle to the license which the user has requested. If the user has suc-cessfully received the license, the status of the handle is VLS_ACTIVE_HAN-DLE. Otherwise, the client is put in the queue and the status of the handleis VLS_QUEUED_HANDLE.

qPreference Pointer to the VLSqueuePreference structure, which is used to specify theclient’s preference for how it wishes to be placed in the queue. After thecall is made, the structure contains the values assigned by the licenseserver when it has placed the client in the queue.

requestFlag Valid values are:

n VLS_REQ_GET - specifies a non-queuing request (without queuingthe client). If license is not available, client will not be queued.

n VLS_REQ_QUEUE - specifies to queue the client (without returningwith the license). Even if license is available, client will be queued.

If both are specified, the client requests the license server to give thelicense, if available, otherwise to queue the client. Upon return from thisAPI, this parameter will be set to either VLS_REQ_GET (specifying thelicense has been granted) or, VLS_REQ_QUEUE (specifying that the clienthas been queued).

server_info Information about the server.

6.5.2. Description

The call provides themechanism to the calling application to ask the license server to grant a license ifavailable. If no license is available, the client will be queued. The client can call VLSupdateQueuedClientto inquire if a license is available. Once a license is available, the client can call VLSgetQueuedLicense toobtain 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.

n Time in seconds for the server to hold the license once it becomes available.

n Priority relative to other clients.

n Themaximum position within the queue before which the client can be queued.

n Themaximum position within the group queue, before which the client can be queued.



Notice that the LS_MAX_QLEN environment variable can override the qPreference structure. The end-user can put a limit on themaximum size of the queue by defining the LS_MAX_QLEN environmentvariable. This variable depends upon the availability ofmemory resources. The different values of LS_MAX_QLEN are:

n LS_MAX_QLEN not set. Client preference is applied.

n LS_MAX_QLEN = -1. Client preference is ignored and the client is always queued.

n LS_MAX_QLEN = 0. Queue is disabled and no clients will be put in the queue.

n LS_MAX_QLEN > 0. Overrides the client’s preference.

Similarly variable LS_MAX_GRP_QLENwill override the setting of themax group wait time in the qPref-erence structure.

Variables LS_MAX_WAIT_SEC and LS_MAX_HOLD_SEC override themaxwait time and max hold timeelements of the qPreference structure.

6.5.3. Returns



VLS_CALLING_ERROR n request_flag specifies queuing but qPreference is NULL.n lshandle is NULL.n challenge argument is non-NULL, but cannot be under-

stood.n publisherName is NULL

VLS_APP_UNNAMED n product_name is NULLn version is NULL

VLS_NO_LICENSE_GIVEN n units_reqd is zero.n Invalid handle specified.n Generic error indicating that the license is not granted.


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

VLS_NO_SUCH_FEATURE License server does not have a license that matches requested fea-ture, version and capacity.


VLS_NOMORE_QUEUE_RESOURCES

Queue is full.

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



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

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





VLS_NO_SERVER_FILE The license server has not been set and is unable to determinewhich license server to use.



VLS_NON_REDUNDANT_SRVR

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

VLS_SERVER_SYNC_IN_PROGRESS

License server synchronization in process.


VLS_MAJORITY_RULE_ FAIL-URE

Majority rule failure prevents token from being issued.





6.6. VLSgetQueuedClientInfo

6.6.1. Syntaxint VLSgetQueuedClientInfo (



int index,

char LSFAR *unused1,

VLSqueuedClientInfo *client_info );


feature_name Feature name of the client for which we are requesting information. An INparameter.

version Version for which licenses are requested. Must be unique, for the associatedfeature. An IN parameter.

index Index of the client with the license server, for a particular feature. An IN param-eter.

client_info The structure in which information will be returned. Pointer to the VLSqueued-ClientInfo 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 queuedclient identified by specified feature_name, version, and index.

6.6.3. Returns



VLS_CALLING_ERROR n client_info parameter is NULL.n index is negative.n Attempted to use stand-alonemodewith network only library,

or network modewith stand-alone library.

VLS_APP_UNNAMED n feature_name is NULLn version is NULL

Both feature and version cannot be NULL

VLS_NO_LICENSE_GIVEN Finished retrieving client information for all the clients.

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

VLS_MULTIPLE_ VEN-DORID_FOUND

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







VLS_NO_SERVER_FILE The license server has not been set and is unable to determine whichlicense server to use.






6.6. VLSgetQueuedClientInfo 249


6.7. VLSremoveQueuedClient

6.7.1. Syntaxint VLSremoveQueuedClient (



int qkey_id,

char *log_comment );


feature_name Feature name of the client for which we are requesting information.

version Version for which licenses are requested.

qkey_id Identifier of the client queue, which needs to be removed.


6.7.2. Description

This API provides an administrativemechanism 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 thequeue.

n The root/administrator account.

n 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 queuefor a specified feature should be removed.

6.7.3. Returns



VLS_CALLING_ERROR n qkey_id parameter cannot be negative.n Attempted to use stand-alonemodewith network only library,

or network modewith stand-alone library.


Both feature name and version cannot be NULL.

VLS_NO_SUCH_CLIENT License server does not have the specified client.

VLS_CLIENT_NOT_ Client is not authorized to make the specified request.


AUTHORIZED






VLS_NO_SERVER_FILE The license server has not been set and is unable to determine whichlicense server to use.










6.7. VLSremoveQueuedClient 251


6.8. VLSremoveQueue

6.8.1. Syntaxint VLSremoveQueue (



char *log_comment );


feature_name Identifies the license whose queue needs to be removed.

version Version for which licenses are requested. Must be unique.


6.8.2. Description

This API will provide a mechanism to delete the complete queue for a specified license.

VLSremoveQueuewill be available to:

n The user-account who started the license server, which actually signifies when the client wasput in the queue.

n The root/administrator account.

6.8.3. Returns





Both feature name and version cannot be NULL.

VLS_CLIENT_NOT_ AUTHORIZED Client not authorized to remove queue.



VLS_NO_SERVER_FILE The license server has not been set and is unable to deter-mine which license server to use.


LS_NO_NETWORK Generic error indicating that the network is unavailable for


servicing the license operation.



6.8. VLSremoveQueue 253


6.9. VLSgetHandleStatus

6.9.1. Syntaxint VLSgetHandleStatus (

LS_Handle lshandle );


lshandle 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:


LS_BADHANDLE Invalid handle. Handle is already released and destroyed fromprevious license operations.


VLS_AMBIGUOUS_ HANDLE lshandle is an ambiguous handle; it is not exclusively active orexclusively queued.

VLS_ACTIVE_HANDLE lshandle is an active handle.

VLS_QUEUED_HANDLE lshandle is a queued handle.


6.10. VLSupdateQueuedClient

6.10.1. Syntaxint VLSupdateQueuedClient (

LS_HANDLE lshandle,

long *absExpiryTime,




lshandle The handle previously returned by VLSqueuedRequest. The status of the han-dle must be VLS_QUEUED_HANDLE or an error will occur.

absExpiryTime Once the license is available with the license server, the next call to this APIreturns in this parameter, the absolute expiry time before which the clientshould get the license using VLSgetQueuedLicense. If any call to VLSup-dateQueuedClient returns a non-negative value in this parameter, then thelicense has been granted and set aside for the client. There is no need to con-tinue its periodic call to this function. The next step is to obtain the license bycalling VLSgetQueuedLicense.Possible values for absExpiryTime are:

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

unused1unused2

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 beenput 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 5minutes of the previous queue-update or the request to queue itself. This is imperative so as to make the license server aware of theactive clients. If the license server does not receive an update request from a client within 5minutes ofthe last queue-update, it will then assume the client to be inactive and remove the client from thequeue.

6.10.3. Returns



VLS_CALLING_ERROR n absExpiryTime is NULL.n Handle cannot be active.

6.10. VLSupdateQueuedClient 255



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


LS_LICENSETERMINATED Cannot update license because license has already expired.






VLS_FINGERPRINT_MIS-MATCH

User or machine excluded from accessing the requested feature.

VLS_APP_NODE_LOCKED Feature is node locked, but update request was issued from anunauthorized machine.

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

VLS_VENDORIDMISMATCH The vendor identification of the requesting application does notmatch the vendor identification of the feature for which the licenseserver has the license. This error occurs only when client is olderthan version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

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








6.11. VLSgetQueuedLicense

6.11.1. Syntaxint VLSgetQueuedLicense (

LS_HANDLE lshandle,




lshandle The handle previously returned by VLSqueuedRequest. The status of the han-dle must be VLS_QUEUED_HANDLE and the last call to VLSupdateQueuedClientmust have reported that the licenses have been made available with thelicense server.

log_comment A string that is written by the licensemanager to the comment field of theusage log file.

challenge The challenge-response for this operation. Pointer to a challenge structure.The challenge-response will also be returned.

6.11.2. Description

Once the queued client identifies that the required licenses aremade 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 themem-orized information to the license server. On return it will provide a valid client-handle value that will beused in later API calls.

6.11.3. Returns



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



VLS_NO_LICENSE_GIVEN Generic error indicating that the license is not granted.






VLS_FINGERPRINT_MIS- Client-locked. Locking criteria does not match.

6.11. VLSgetQueuedLicense 257



MATCH

VLS_APP_NODE_LOCKED Requested feature is node locked, but request was issued fromunauthorized machine.

VLS_VENDORIDMISMATCH The vendor identification of the requesting application does notmatch the vendor identification of the feature for which the licenseserver has the license. This error occurs only when client is olderthan version 6.3 else the error returned is VLS_NO_SUCH_FEATURE.

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








6.12. VLSinitQueuePreference

6.12.1. Syntaxint VLSinitQueuePreference (

VLSqueuePreference *qPreference );


qPreference Pointer to the VLSqueuePreference structure, which specifies the client pref-erence for getting into the queue. After the call is made, the structure signifiesthe actual values, which the license server allocates to the client while puttinghim in the queue.

6.12.2. Description

Initializes the VLSqueuePreference structure to default values. For more details, seeVLSqueuePreference structure.

6.12.3. Returns



VLS_CALLING_ERROR qPreference is NULL.


6.12. VLSinitQueuePreference 259

Chapter 7:Upgrade License API

The Sentinel RMS upgrade license feature enables you to update your customer's existing license tochange the version or/and increase the capacity. A special upgrade licensemust be created to updatethe existing license.

The API functions discussed in this section are categorized into license code generator and decoderAPI.

7

262 Chapter 7: Upgrade License API

The Upgrade License Code Generator APIThe following table summarizes the upgrade license code generator related functions:


ucodeT Struct Contains the values for the upgrade license.

VLSucgInitialize Initializes the upgrade codegen library

VLSucgCleanup Destroys the handle created using VLSucgInitialize

VLSucgReset Sets all the fields of ucodeT to their default values

VLSucgGetNumErrors Identifies the total number ofmessages recorded in the handle

VLSucgGetError Length Returns the length of error message identified bymsgNum andrecorded in the handle

VLSucgGetError Message Returns the earliest error from the handle up to bufLen char-acters

VLSucgPrintError Prints the complete info of all the error messages stored in thehandle to a file.

VLSucgAllowBase FeatureName Identifies whether the corresponding VLSucgSet-BaseFeatureName should be called or not

VLSucgSetBaseFeatureName Sets the value of base_feature_name in the ucodeT struct.

VLSucgAllowBase FeatureVersion Identifies whether the corresponding VLSucgSet-BaseFeatureVersion should be called or not.

VLSucgSetBaseFeatureVersion Sets the value of base_feature_version in the ucodeT struct.

VLSucgAllowUpgradeCode Identifies whether the corresponding VLSucgSetUpgradeCodeAPI should be called or not

VLSucgSetUpgrade Code Sets the value of base_lock_code in the ucodeT struct to thevalue in the upgrade_code

VLSucgAllowUpgradeFlag Identifies whether the corresponding VLSucgSetUpgradeFlagshould be called or not

VLSucgSetUpgrade Flag Sets the value of upd_flags in the ucodeT struct.

VLSucgAllowUpgradeVersion Identifies whether the corresponding VLSucgSetUpgradeVersionshould be called or not

VLSucgSetUpgrade Version Sets the value of upd_version in the ucodeT struct.

VLSucgAllowUpgradeCapacity Identifies whether the corresponding VLSucgSe-tUpgradeCapacityUnits and VLSucgSetUpgradeCapacity shouldbe called or not

VLSucgSetUpgrade CapacityUnits Sets the value of capacity_units in the ucodeT struct.

VLSucgSetUpgrade Capacity Sets the value of capacity_increment in the ucodeT struct.

VLSucgGenerate License Generates the upgrade license string for the given ucodeT struct

VLSucgGetLicenseMeterUnits Returns the number of license generation units available in theattached dongle

VLSGenerateUpgrade LockCode Allows the user to generate a unique upgrade code for the base


license.

The Upgrade License Code Generator API 263


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 ;



} ucodeT;

Member Description

structSz Size of the structure.

Vendor_code Internal use

version_num Upgrade license code generation library version

base_feature_name Feature Name of the base license that needs to be upgraded

base_feature_version Feature Version of the base license that needs to be upgraded

lock_code A unique code to identify base licenses which needs to be upgraded.

generation_time This value shall be set automatically during the license generationtime in GMT. It details about the time of license generation.

generation_sequence This value shall be set at license generation time along with gen-eration_time to ensure that on a fast system, even if two licenses aregenerated at the same time, this value should be different.

upd_flags Bit-wise flag. Controls what will be updated:

n VLSucg_UPGRADE_VERSIONn VLSucg_UPGRADE_CAPACITYn VLSucg_UPGRADE_ALL

Member Description

upd_version New version for this feature.

capacity_units Flag which determines capacity least count

capacity_increment Capacity increment for this feature.

Unused For future use.

Unused For future use.

7.1. ucodeT Struct 265


7.2. VLSucgInitialize

7.2.1. Syntaxint VLSucgInitialize (

VLSucg_HANDLE *iHandle );


iHandle The pointer to instance handle for this library, provides access to the inter-nal data structure.

7.2.2. Description

Initializes the upgrade codegen library.

VLSucgInitialize should be called before any other API. VLSucgInitialize returns a unique handle, whichis used in all the other API of this library.

7.2.3. Returns



VLSucg_BAD_HANDLE Call VLSucgCleanup to free the resources associated with theinvalid handle.

VLSucg_MAX_LIMIT_CROSSED Library has crossed the limit ofmaximum handles it can allocate.

VLSucg_LICMETER_NOT_ SUP-PORTED

Your Sentinel RMS Development Kit LicenseMeter is not sup-ported.

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

7.3. VLSucgCleanup

7.3.1. Syntaxint VLSucgCleanup (

VLSucg_HANDLE *iHandle );


iHandle 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



VLSucg_BAD_HANDLE If the handle passed is not a valid handle.


7.3. VLSucgCleanup 267


7.4. VLSucgReset

7.4.1. Syntaxint VLSucgReset (

VLSucg_HANDLE iHandle,

ucodeT *ucodeP );



ucodeP The pointer to ucodeT struct

7.4.2. Description

Sets all the fields of ucodeT to their default values. VLSucgReset is used after the Initialize and beforethe Set and Allow APIs.

7.4.3. Returns



VLSucg_INVALID_INPUT If the ucodeP is passed as NULL


7.5. VLSucgGetNumErrors

7.5.1. Syntaxint VLSucgGetNumErrors (


int *numMsgsP );



numMsgsP The number ofmessages queued to the handle

7.5.2. Description

Identifies the total number ofmessages recorded in the handle.

7.5.3. Returns




VLSucg_NO_RESOURCES If no resources are available.

VLSucg_FAIL On failure


7.5. VLSucgGetNumErrors 269


7.6. VLSucgGetErrorLength

7.6.1. Syntaxint VLSucgGetErrorLength (


int msgNum,

int *errLenP );



msgNum The number of themessage whose length is to be queried, starts from 0.

errLenP The length ofmessages identified bymsgNum

7.6.2. Description

Returns the length of error message identified bymsgNum and recorded in the handle.

The length returned by VLSucgGetErrorLength include the space required for NULL termination.

7.6.3. Returns





VLSucg_FAIL On failure


7.7. VLSucgGetErrorMessage

7.7.1. Synatxint VLSucgGetErrorMessage (


char *msgBuf,

int bufLen );



msgBuf A user allocated buffer into which the referencemessage will be copied

bufLen The byte length of themessage copied intomsgBuf

7.7.2. Description

Returns the earliest error from the handle up to bufLen characters.

n The bufLenmust be the length of the pre allocated buffermsgBuf.

n Themessage returned should always be NULL terminated.

7.7.3. Returns





VLSucg_FAIL On Failure


7.7. VLSucgGetErrorMessage 271


7.8. VLSucgPrintError

7.8.1. Syntaxint VLSucgPrintError (


FILE *file );



file File pointer

7.8.2. Description

Prints the complete info of all the error messages stored in the handle to a file.

7.8.3. Returns





VLSucg_FAIL On Failure


7.9. VLSucgAllowBaseFeatureName

7.9.1. Syntax int VLSucgAllowFeatureName (


ucodeT *ucodeP );




7.9.2. Description

Identifies whether the corresponding VLSucgSetBaseFeatureName should be called or not.

If the VLSucgAllowBaseFeatureName returns 1 only then the corresponding VLSucgSet-BaseFeatureName should be called.

7.9.3. Returns



1 VLSucgSetBaseFeatureName is allowed.

0 VLSucgSetBaseFeatureName is not allowed.


7.9. VLSucgAllowBaseFeatureName 273


7.10. VLSucgSetBaseFeatureName

7.10.1. Syntaxint VLSucgSetBaseFeatureName (


ucodeT *ucodeP,

char *feature_name );




feature_name Any printable ASCII text except #. Maximum of 24 characters.

7.10.2. Description

Sets the value of base_ feature_name in the ucodeT struct.

This function also checks the input variables for their validity and boundary conditions.

7.10.3. Returns



VLSucg_INVALID_CHARS Invalid characters in feature_name.

VLSucg_NO_FEATURE_NAME If feature_name is NULL.

VLSucg_RESERV_STR_ERROR If the feature_name is a reserved string.

VLSucg_EXCEEDS_MAX_VALUE

If the length of feature_name string exceeds maximum allowedlength(24 char).


7.11. VLSucgAllowBaseFeatureVersion

7.11.1. Syntaxint VLSucgAllowBaseFeatureVersion (


ucodeT *ucodeP );




7.11.2. Description

Identifies whether the corresponding VLSucgSetBaseFeatureVersion should be called or not.

If the VLSucgAllowBaseFeatureVersion returns 1 only then the corresponding VLSucgSet-BaseFeatureVersion should be called.

7.11.3. Returns



1 VLSucgSetBaseFeatureVersion is allowed.

0 VLSucgSetBaseFeatureVersion is not allowed.


7.11. VLSucgAllowBaseFeatureVersion 275


7.12. VLSucgSetBaseFeatureVersion

7.12.1. Syntaxint VLSucgSetBaseFeatureVersion (


ucodeT *ucodeP,

char *feature_version );




feature_version Any printable ASCII text except #. Maximum of 11 characters.

7.12.2. Description

Sets the value of base_ feature_version in the ucodeT struct. This function checks the input variablesfor their validity and boundary conditions.

7.12.3. Returns



VLSucg_INVALID_CHARS If feature_version characters are not printable.

VLSucg_RESERV_STR_ERROR If the feature_version is a reserved string.


If the length of feature_version string exceeds maximum allowedlength(11 char).


7.13. VLSucgAllowUpgradeCode

7.13.1. Syntaxint VLSucgAllowUpgradeCode (


ucodeT *ucodeP );




7.13.2. Description

Identifies whether the corresponding VLSucgSetUpgradeCode should be called or not.

Only if the VLSucgAllowUpgradeCode returns 1 then the corresponding VLSucgSetUpgradeCodeshould be called.

7.13.3. Returns



1 VLSucgSetUpgradeCode is allowed.

0 VLSucgSetUpgradeCode is not allowed


7.13. VLSucgAllowUpgradeCode 277


7.14. VLSucgSetUpgradeCode

7.14.1. Syntaxint VLSucgSetUpgradeCode (


ucodeT *ucodeP,

char *upgrade_code );


iHandle Instance handle for this library.

ucodeP The pointer to ucodeT struct.

upgrade_code Upgrade code of base license.

7.14.2. Description

Sets the value of the lock_code variable in the ucodeT struct.

This function checks the input variables for their validity and boundary conditions. However, this func-tion 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



VLSucg_INVALID_INPUT If ucodeP is passed as NULL.

VLSucg_NO_UPGRADE_CODE

If the upgrade_code is passed as NULL or empty string.


If the length of upgrade_code string exceeds maximum allowedlength.

VLSucg_FAIL On Failure.


7.15. VLSucgAllowUpgradeFlag

7.15.1. Syntaxint VLSucgAllowUpgradeFlag (


ucodeT *ucodeP );




7.15.2. Description

Indicates whether the corresponding VLSucgSetUpgradeFlag should be called or not.

If the VLSucgAllowUpgradeFlag returns 1 only then the corresponding VLSucgSetUpgradeFlag shouldbe called.

7.15.3. Returns



1 Capacity Upgrade is allowed.

0 Capacity Upgrade is not allowed.


7.15. VLSucgAllowUpgradeFlag 279


7.16. VLSucgSetUpgradeFlag

7.16.1. Syntaxint VLSucgSetUpgradeFlag (


ucodeT *ucodeP,

char *flag );




flag The value of flag is used to set the upd_flags of ucodeT struct. Legal values are bitcombinations of

n VLSucg_UPGRADE_VERSIONn VLSucg_UPGRADE_CAPACITYn 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 theirvalidity and boundary conditions.

n If the flag value is VLSucg_UPGRADE_VERSION then only version upgrade license can be gen-erated.

n If the flag value is VLSucg_UPGRADE_CAPACITY then only capacity upgrade license can be gen-erated.

n If the flag value is VLSucg_UPGRADE_ALL then both version and capacity upgrade license canbe generated.

7.16.3. Returns




VLSucg_INVALID_INPUT If the either the ucodeP or upd_flags is passed as NULL. Also if theupd_flags is passed as an empty string.

VLSucg_INVALID_INT_TYPE If value of upd_flags is not numeric.


If value of upd_flags exceeds VLSucg_UPGRADE_ALL

VLSucg_LESS_THAN_MIN_VALUE

If value is lower than VLSucg_UPGRADE_VERSION.


7.16. VLSucgSetUpgradeFlag 281


7.17. VLSucgAllowUpgradeVersion

7.17.1. Syntaxint VLSucgAllowUpgradeVersion (


ucodeT *ucodeP );




7.17.2. Description

Indicates whether the corresponding VLSucgSetUpgradeVersion should be called or not.

Only if the VLSucgAllowUpgradeVersion returns 1 then the corresponding VLSucgSetUpgradeVersionshould be called.

7.17.3. Returns



1 VLSucgSetUpgradeVersion is allowed

0 VLSucgSetUpgradeVersion is not allowed


7.18. VLSucgSetUpgradeVersion

7.18.1. Syntaxint VLSucgSetUpgradeVersion (


ucodeT *ucodeP,

char *upgrade_version );




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 alsochecks the input variables for their validity and boundary conditions.

7.18.3. Returns



VLSucg_INVALID_INPUT If the either the ucodeP or upgrade_version is passed as NULL. Alsoif the upgrade _version does not contain a valid string.

VLSucg_INVALID_CHARS If upgrade_version characters are not printable.

VLSucg_RESERV_STR_ERROR

If the upgrade_version is a reserved string.


If the length of upgrade_version string exceeds maximum allowedlength.


7.18. VLSucgSetUpgradeVersion 283


7.19. VLSucgAllowUpgradeCapacity

7.19.1. Syntaxint VLSucgAllowUpgradeCapacity (


ucodeT *ucodeP );




7.19.2. Description

Indicates whether the corresponding VLSucgSetUpgradeCapacityUnits and VLSucgSe-tUpgradeCapacity should be called or not. If the VLSucgAllowUpgradeCapacity returns 1 only then thecorresponding Capacity should be called.

7.19.3. Returns



1 VLSucgSetUpgradeCapacity is allowed

0 VLSucgSetUpgradeCapacity is not allowed


7.20. VLSucgSetUpgradeCapacityUnits

7.20.1. Syntaxint VLSucgSetUpgradeCapacityUnits (


ucodeT *ucodeP,

char *cap_units );




cap_units Capacity specification units: from 0 to 4. The values are:

n If capacity_units is 0, capacity shall bemultiple of 1(s), maximum 1022.n If capacity_units is 1, capacity shall bemultiple of 10(s), maximum 10220.n If capacity_units is 2, capacity shall bemultiple of 100(s), maximum 102200.n If capacity_units is 3, capacity shall bemultiple of 1000(s), maximum

1022000.n If capacity_units is 4, capacity shall bemultiple 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 ofcapacity upgrade or in case of both version and capacity upgrade.

VLSucgSetUpgradeCapacityUnits also check the input variables for their validity and boundary con-ditions.

7.20.3. Returns



VLSucg_INVALID_INPUT If the either the ucodeP or cap_units is passed as NULL. Also if thecap_units is passed as an empty string.

VLSucg_INVALID_INT_TYPE If value of cap_units is not numeric.


If the value of cap_units exceeds VLScg_CAPACITY_UNITS_MAX_VALUE

VLSucg_LESS_THAN_MIN_VALUE

If the value is lower than VLScg_CAPACITY_UNITS_MIN_VALUE.


7.20. VLSucgSetUpgradeCapacityUnits 285


7.21. VLSucgSetUpgradeCapacity

7.21.1. Syntaxint VLSucgSetUpgradeCapacity (


ucodeT *ucodeP,

char *cap_increment );




cap_ increment Controls the capacity.

n If capacity_units is 0, capacity shall bemultiple of 1(s), maximum1022.





n VLScg_NOLIMIT_STRING or EMPTY(“/0”) String can be used to specifyinfinite capacity.

7.21.2. Definition

Sets the value of capacity_increment in the ucodeT struct. This function also check the input variablesfor their validity and boundary conditions. Infinite capacity shall also be allowed.

7.21.3. Returns




VLSucg_INVALID_INPUT If the either the ucodeP or cap_increment is passed as NULL. Also ifthe cap_increment is passed as an empty string.

VLSucg_NOT_MULTIPLE If value is not a correct multiple.

VLSucg_INVALID_INT_TYPE If value of cap_increment is not numeric.


If the value of cap_increment exceeds maximum allowed.

VLSucg_LESS_THAN_MIN_ If the value is lower than minimum allowed.


VALUE


7.21. VLSucgSetUpgradeCapacity 287


7.22. VLSucgGenerateLicense

7.22.1. Syntaxint VLSucgGenerateLicense (

VLSucg_HANDLE VLSucg_HANDLE

ucodeT *ucodeP,

char *upgrade_code,

char **result );




upgrade_code Upgrade code of base license

result Address of pointer pointing to generated license string.

7.22.2. Description

Generates the upgrade license string for the given ucodeT struct. VLSucgGenerateLicense should becalled after all the VLSucgSet functions are called. Memory allocation and free for ucodeT are theresponsibilities of the caller of the API. Memory allocation for the license string shall be taken care bythe API.

VLSucgGenerateLicense decodes the upgrade_code and extract the information of base license. It per-forms the following validation before generating an upgrade license:

n Feature Name, Version and vendor code of base license is matched with the base featurename, base version and vendor code of ucodeT.

n The capacity upgrade is allowed only if the base license is a Non-pooled capacity license.

7.22.3. Returns



VLSucg_INVALID_INPUT If the ucodeP is passed as NULL.

VLSucg_INVALID_VENDOR_CODE

If vendor identification is illegal.

VLSucg_VENDOR_ ENCRYP-TION_FAIL

If vendor-customized encryption fails.

VLSucg_MALLOC_FAILURE If error occur while allocating internal memory for ucodeT struct.

VLSucg_LICMETER_ EXCEP-TION

If error occur while accessing the dongle.

VLSucg_NO_NETWORK_ If not authorized to generate network licenses.


AUTHORIZATION

VLSucg_LICMETER_COUNTER_TOOLOW

If licensemeter count is less than the expected decrement count.

VLSucg_NO_CAPACITY_AUTHORIZATION

If not authorized to generate capacity licenses.

VLSucg_NO_UPGRADE_AUTHORIZATION

If not authorized to generate upgrade licenses.

VLSucg_INTERNAL_ERROR If any internal error occur while generating the license string.

VLSucg_INVALID_BASE_LIC_INFO

The information-feature name, version vendor code provided forbase license is incorrect.

VLSucg_CAPACITY_UPD_NOT_ALLOWED

Capacity upgrade is not allowed, as the base lic is a non-capacitylicense.

VLSucg_INVALID_UPGRADE_CODE

The specified upgrade code is invalid.

VLSucg_LICMETER_NOT_SUPPORTED



7.22. VLSucgGenerateLicense 289


7.23. VLSucgGetLicenseMeterUnits

7.23.1. Syntaxint VLSucgGetLicenseMeterUnits (


long *initialUnitsP,

long *unitsLeftP,

int ucodegen_version );



initialUnitsP User provided license string to be decoded.

unitsLeftP User allocated buffer to receive decoded license string.

ucodegen_version Version of the ucodegen library

7.23.2. Description

Returns the number of license generation units available in the attached dongle.

7.23.3. Returns



VLSucg_INVALID_VENDOR_CODE If vendor identification is illegal.

VLSucg_VENDOR_ENCRYPTION_FAIL

If vendor-customized encryption fails

VLSucg_MALLOC_FAILURE If error occur while allocating internal memory for ucodeTstruct


VLSucg_LICMETER_NOT_ SUP-PORTED



7.24. VLSgenerateUpgradeLockCode

7.24.1. Syntaxint VLSgenerateUpgradeLockCode (

unsigned char *lic_string,

unsigned char *upgrade_lock_code,

unsigned long *buffer_size );


lic_string Base license string.

upgrade_lock_code

Buffer containing the generated upgrade lock code. The caller should allocate thememory space.

buffer_size Size of the allocated buffer.

If NULL is passed instead of buffer, then this will return buffer size required forthe generated upgrade lock code.

7.24.2. Description

VLSgenerateUpgradeLockCode allows the user to generate a unique upgrade code for the baselicense. The upgrade codemust be an encrypted string so that it doesn't make any visible sense to theuser/developer.

This API is a part of the generic library (lsutil32.lib).

7.24.3. Returns



LS_NORESOURCES Unable to allocatememory required to decode the passedlicense string and to generate upgrade code.

VLS_CALLING_ERROR If called with invalid arguments.

LS_NO_SUCCESS If unable to generate upgrade code.

VLS_VENDORIDMISMATCH If license string with invalid vendor code is passed. This erroroccurs only when client is older than version 6.3 else the errorreturned is VLS_NO_SUCH_FEATURE.

VLS_UPGRADE_NOT_ALLOWED It shall not generate the Upgrade Code if the base license isfound to be a Multi Feature Short Numeric, or Trial or Com-muter or Redundant License.

LS_BUFFER_TOO_SMALL buffer parameter is NULL.

Size of upgrade lock code exceeds buffer_size parameter.


7.24. VLSgenerateUpgradeLockCode 291


The Upgrade License Decode APIGiven below is a list of the API functions:


ulcCode Stores information required to decode upgrade lock code.

VLSdecodeUpgrade lockCode Decodes the upgrade lock code.

VLSucgDecodeLicense Decodes the encrypted license string generated by upgradecode generator library

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];


} ulcCode;

Member Description

version_num Number maintaining the version of the structure

hash_vendor_ string A numeric value representing the feature and version of thelicense.

capacity_flag The value of capacity flag.

standalone_flag The value of standalone flag.

num_keys The number of keys.

birth_day The starting day of the license.

birth_month The starting month of the license.

birth_year The starting year of the license.

death_day The expiration day of the license.

death_month The expiration month of the license.

death_year The expiration year of the license.

client_server_lock_mode The locking mode

base_lock_code Base lock code

base_feature_ name Base feature name

base_feature_ version Base feature version

capacity Capacity of the license.

7.25. ulcCode Struct 293


7.26. VLSdecodeUpgradelockCode

7.26.1. Syntaxint VLSdecodeUpgradelockCode (

char *upgrade_lock_code,

char *compacted_upd_lock_code,

int length,

ulcCode **ulcCodePP );


upgrade_lock_ code Upgrade lock code to be decoded.

compacted_upd_ lock_code Upgrade lock code string after removing comment chars andwhite spaces. This can also be set as null.

length Length of compacted_upd_lock_code in case it is not null.

ulcCodePP Pointer to pointer to ulcCode structure.

7.26.2. Description

VLSdecodeUpgardelockCode API decodes the upgarde lock code.

7.26.3. Returns



LS_NORESOURCES If vendor identification is illegal.

LS_NO_SUCCESS Failed to decrypt the license

VLS_INTERNAL_ERROR If error occur while allocating internal memory for ucodeT struct


7.27. VLSucgDecodeLicense

7.27.1. Syntax int VLSucgDecodeLicense (


char *AnyLicenseString,

char *lic_string,

int lic_string_length,

ucodeT **ucodePP );



AnyLicenseString User provided license string to be decoded.

Lic_string User allocated buffer to receive decoded license string.

Lic_string_length Length of decoded license string returned.

ucodePP Address of pointer to ucodeT struct. Contains input license string.

7.27.2. Description

VLSucgDecodeLicense API is contained in lsdcod32.lib. This library needs to be called for usingVLSucgDecodeLicense API without the licensemeter.

Decodes the encrypted license string generated by upgrade code generator library. It also convertsthe license string into ucodePP struct.

VLSucgDecodeLicense does not decodes/understand the normal (base) licenses.

7.27.3. Returns



VLSucg_INVALID_VENDOR_CODE

If vendor identification is illegal.

VLSucg_VEN-DOR_ENCRYP-TION_ FAIL

If vendor-customized encryption fails

VLSucg_MAL-LOC_FAILURE

If error occur while allocating internal memory forucodeT struct



7.27. VLSucgDecodeLicense 295

Chapter 8:Utility Functions

The utility functions aremeant for scheduling and disabling events.

The utility functions are only available for UNIX platforms.



VLSscheduleEvent Schedules eventhandler to be awakened after so many seconds. It handlesonly SIGALRM signal.

VLSdisableEvents Disables the events scheduled. To disable a particular event pass the eventhandler function name as the argument. To disable all the events pass NULLas argument.

VLSeventSleep Disables the feature for an allotted time.

8

298 Chapter 8: Utility Functions

8.1. VLSscheduleEvent

8.1.1. Syntaxint VLSscheduleEvent (

unsigned long seconds,

void *eventHandler,

long repeat_event );


seconds Time interval in seconds.

eventHandler Signal handler.

repeat_event Number of event repetitions.

8.1.2. Description

This function is called for scheduling eventHandler to be awakened after so many seconds. Handlesonly SIGALRM signal.

8.1.3. Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indi-cating the reason for failure. For a complete list of the error codes, Licensing Library Error and ResultCodes.

8.2. VLSdisableEvents

8.2.1. Syntaxint VLSdisableEvents(

void *eventHandler );


eventHandler Signal handler.

8.2.2. Description

This function is called for disabling the events scheduled. To disable a particular event, pass the eventhandler function name as the argument. To disable all the events, pass NULL as argument.

8.2.3. Returns


8.2. VLSdisableEvents 299

300 Chapter 8: Utility Functions

8.3. VLSeventSleep

8.3.1. Syntax

void VLSeventSleep (unsigned int seconds));


seconds 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 thesystem alarms.

VLSeventSleep must be used in conjunction with VLSdisableAutoTimer.

8.3.3. Returns


Chapter 9:Usage Log Functions

The usage log functions control and manipulate the usage log file.

The following table summarizes the usage log functions:


VLSchangeUsageLogFileName This API changes the name of the existing usage log file. Thischange can be done while the file is being used.

VLSgetUsageLogFileName API determines the name of the existing usage log file.

VLSUsageAuthenticate Verifies whether the usage log file is tampered or not?

VLSusageFileDecrypt Decrypts the usage log file in a readable format.

9

302 Chapter 9: Usage Log Functions

9.1. VLSchangeUsageLogFileName

9.1.1. Syntaxint VLSchangeUsageLogFileName(

char *hostName,

char *newFileName);


hostName The host name or IP address of the computer hosting the license server that isusing the log file.

newFileName 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. Thischange can be done while the file is being used.

9.1.3. Returns


9.2. VLSgetUsageLogFileName

9.2.1. Syntaxint VLSgetUsageLogFileName(

char *hostName,

char *fileName );


hostName The host name or IP address of the computer hosting the license server that isusing the log file.

fileName The name of the existing usage log file is returned in this argument.

9.2.2. Description

Determines the name of the existing usage log file.

9.2.3. Returns


9.2. VLSgetUsageLogFileName 303


9.3. VLSUsageAuthenticate

9.3.1. Syntaxint VLSUsageAuthenticate (

unsigned char *file_name,

int *len,

VLSerrorLine *Output_Message);


file_name The name of the input usage log file.

len When VLSUsageAuthenticate is called for the first time, the return value of lencontains the number of tampered lines in the usage log fileWhile calling this APIfor the second time, you need to pass the return (len) value received from thefirst VLSUsageAuthenticate call and Output_Message to get a detailed descrip-tion about the tampered lines.

Output_Mes-sage

This variable contains detailed description about the tampered lines in usagelog file. This parameter is used only after checking that the usage log file hasbeen tampered.

9.3.2. Description

Before calling this API first time for a given log file, it is unknown howmany lines of the log file havebeen tampered. To determine the number of tampered lines, call this API with output_messageparameter as NULL (VLSUsageAuthenticate(inFile, &len, NULL)).

The return value of this API indicates whether the log file has been tampered or not. Also, the lenparameter 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 suf-ficient memory to the output_parameter (len * sizeof(error_Msg) ), and call this API again (VLSUs-ageAuthenticate(inFile,&len,output_message)).

This time, the output_message parameter will be filled with the detailed description of the tamperedlines.

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

ommended).

9.3.3. Returns

The status code LS_SUCCESS is returned if successful. Otherwise, a specific error code is returned indi-cating 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.

9.3. VLSUsageAuthenticate 305


9.4. VLSusageFileDecrypt

9.4.1. Syntaxint VLSusageFileDecrypt (

unsigned char *file_name,

unsigned char *Option_field,

unsigned char *Output_file_name);


file_name The name of the input usage log file.

len You can specify the following options:

n -d New-log-filen -c CSV-Format-New-log-filen -f Feature-Name1, Version: Feature-Name2, Version ...]n [-y Start-Year (YYYY) [-m Start-Month(MM) [-a Start-Day(DD)]]]n [-Y End-Year(YYYY) [-M End-Month(MM)] [-A End-Day(DD)]]]

Option_field parameter format: -d file_name -f Feature-Name1,V-

ersion: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 outputreport in output_file_name.

9.4.3. Returns


The API allocates (len* sizeof(error_Msg)) memory for the Output_Message pointer. You should free the

allocated memory after calling this API.

Chapter 10:License Code Generation API

The License Code Generation Application Programming Interface (API) makes it possible to generatelicense codes to authorize use of an application program. The functions are prototyped in lscgen.hand the implementation is contained in lscgen32.lib. Use of these files enables you to write your ownutility 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 typecodeT. The handle is used with all other License Generation functions, and must be initialized beforeany of those functions can be called. The codeT data structure is used to pass arguments back andforth between the program and the different library functions. A typical sequence of operations to gen-erate a license would look like the following:

n Be sure that a handle and a codeT data structure have been allocated.

n Call VLScgInitialize to initialize the handle. This will ensure that the number of handles hasnot exceeded the limit, allocate space for internal data structures, and initialize the error listand error count.

n Call VLScgReset to install default values into the codeT data structure. This must be donebefore setting the values of any of the fields in the data structure.

n Obtain input from the user that is to be used to define the license code. The order of input isimportant since some values will depend on others. The order of input refers to the Allow andSet functions of code struct. We suggest you use the Allow function first to check the dif-ferential integrity of the field value before using the Set function.

n Call the appropriate VLScgAllowXXX function for each input to ensure that its value can beproperly included into the license code.

n If the input can be accepted, call the corresponding VLScgSetXXX function. This will lock thecodeT structure, install the values, and then unlock the structure.

n If the set function causes an error, call VLScgPrintErrorXXX function to copy the error struc-ture.

n After all inputs have been received, call VLScgGenerateLicense to create the license string.

n Call VLScgCleanup to release the handle.

10

308 Chapter 10: License Code Generation API

10.1. The License Code Generation FunctionsAvailable function calls fall into these categories:

n CodeT Struct

n Basic functions

n Functions which retrieve or print errors

n Functions which set flags and data fields of codeT struct

n License generation function(s)

n Licensemeter related functions

n License Hash and Decode Functions

n License revocation functions

An example is shown below:

...................#include <stdio.h> /* For scanf(), sprintf() etc.*/#include "lscgen.h" /* For the code generator API.*/

/* The fixed feature name of licenses generated by this example program. */

#define VLS_CGENXMPL_FEATURE_NAME "CGENXMPL"

/*Mnemonic used for setting code structure for long codes.*/

#define VLS_LONG_CODE_TYPE_STR "1"

/*Utility function to print code generator API errors to stderr.It also calls the code generatorlibrary 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 APIfunctions to generate an appropriate license for CGENXMPL. To build this example, compile andthen link with the appropriate code generator API library - lscgen32.lib*/

int main (){

/* 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(&iHandle))!= VLScg_SUCCESS){

(void) VLSPrintErrors(&iHandle, retCode);fprintf(stderr, "\nERROR: Code generator libraryinitialization failed.\n");return retCode;

} /* if (!VLScgInitialize()) */

/* Initialize the license code structure. */if((retCode=VLScgReset(iHandle,&licCode))!= VLScg_SUCCESS)

return VLSPrintErrors(&iHandle, retCode);

/* Specify that we want to generate a long code. */

if ((retCode = VLScgSetCodeLength(iHandle, &licCode,VLS_LONG_CODE_TYPE_STR))!= VLScg_SUCCESS)return VLSPrintErrors(&iHandle, retCode);

/* Set the feature name. */

if (VLScgAllowFeatureName(iHandle, &licCode) == 0)return VLSPrintErrors(&iHandle, VLScg_FAIL);

if ((retCode = VLScgSetFeatureName(iHandle, &licCode,VLS_CGENXMPL_FEATURE_NAME))!= VLScg_SUCCESS)return VLSPrintErrors(&iHandle, retCode);

/** Prompt for and acquire the expiration date from the user.*/

printf("License Expiration Month [1-12] : ");scanf("%d", &expMonthInt);printf("License Expiration Day [1-31] : ");scanf("%d", &expDayInt);printf("License Expiration Year : ");scanf("%d", &expYearInt);

/* Convert expiration date information to strings. */

sprintf(expMonth, "%d", expMonthInt);

10.1. The License Code Generation Functions 309


sprintf(expDay, "%d", expDayInt);sprintf(expYear, "%d", expYearInt);

/* Set the expiration date. */

if (VLScgAllowLicExpiration(iHandle, &licCode) == 0)return VLSPrintErrors(&iHandle, VLScg_FAIL);

if (((retCode = VLScgSetLicExpirationMonth(iHandle,&licCode,expMonth))!= VLScg_SUCCESS) ||((retCode = VLScgSetLicExpirationDay(iHandle,

&licCode,expDay))!= VLScg_SUCCESS) ||((retCode = VLScgSetLicExpirationYear(iHandle,&licCode,expYear))!= VLScg_SUCCESS))

return VLSPrintErrors(&iHandle, retCode);

/* Generate the license: memory for license string is allocated by library. */

if ((retCode = VLScgGenerateLicense(iHandle, &licCode,&licStr))!= VLScg_SUCCESS)return VLSPrintErrors(&iHandle, retCode);

/* Print out the license string. */(void) fprintf(stdout, "%s\n", licStr);

/* Free the license string, which was allocated by VLScgGenerateLicense() */free(licStr);

/* Terminate use of code generation library cleanly. */(void) VLScgCleanup(&iHandle);return 0;} /* main() */

10.2. CodeT Struct

10.2.1. Description

Holds the licensing information that is set using VLScgSetXXXX APIs and passes the same to VLScgGen-erateLicense API to generate the corresponding license string. Contains the decoded information fromthe 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;



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


/* 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 */





/* Fields for usage hours based trial licensing */


/* Fields for including public vendor information */

char plain_vendor_info[VLScg_MAX_VENINFOLEN+1];

vmDetectionFlagT vm_detection;

long structSz;

} codeT;

Member Description

code_type Pointer to CodeT struct

additive Can be set to:

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

client_server_lock_mode Locking mode can be:

n VLScg_FLOATING- Server is lockedn VLScg_BOTH_NODE_LOCKED - Clients and server are lockedn VLScg_DEMO_MODE - Demo license (no locking)n VLScg_CLIENT_NODE_LOCKED - Only clients are locked

holding_crit Criterion for held licenses can be:

n VLScg_HOLD_NONEn VLScg_HOLD_VENDORn VLScg_HOLD_CODE

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

n VLScg_NO_SHARINGn VLScg_USER_SHARINGn VLScg_HOSTNAME_SHARINGn VLScg_XDISPLAY_SHARINGn VLScg_VENDOR_SHARING

Criterion for sharing of capacity licenses, can be:

n VLScg_NO_TEAMn VLScg_USER_BASED_TEAMn VLScg_HOSTNAME_BASED_TEAMn VLScg_XDISPLAY_BASED_TEAMn VLScg_VENDOR_BASED_TEAM



Member Description

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

server_locking_crit2 n Server lock selector/criterion (group 2)n Allow 2 hostid's per server

client_locking_crit n Client lock selector/criterionn Allow 1 hostid per client

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

out_lic_type Specifies if the license is

n Encryptedn Expanded readablen Concise readable

clock_tamper_flag If set then the license does not allow time tampering

feature_name Name of the feature

feature_version Version of the feature

birth_day day of themonth (1-31)

birth_month 1 - 12 or JAN - DEC

birth_year 2003 to...; minimum birth year can be 2003.

death_day max day of themonth (1-31)

death_month 1 - 12 or JAN - DEC

death_year 2003 to... ; minimum death year can be 2003.

num_servers Identifies the number of license servers.1serverallowed for single server application and maximum 11 serversallowed for redundant server application.

server_lock_info1 Stores information in ASCII.

server_lock_info2 Stores information in ASCII.

num_nl_clients Number of node-locked clients, maximum of 7 node-locked clients allowed.

nl_client_lock_info Stores information in ASCII.

num_keys Number of concurrent keys.

soft_limit 0 to num_keys.

keys_per_node Number of keys alloted to each client for a network mode license.


site_lic_info Stores information in binary.

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

key_life_units Determines lifetime least count.

long key_lifetime Absolute value in minutes.

key_hold_units Flag which determines holdtime least count.

key_holdtime Absolute value in minutes .

num_secrets Number of Challenge response secrets.

Member Description

secrets Stores information in ASCII.

vendor_info The vendor-defined information string. Themaximum length of the stringcan be up to 2000 characters.

licType Trial or Normal license type.

trialDaysCount Life of trial license.

use_auth_code For multi-keys or short numeric codes

numeric_type For short numeric codes

n 0 - non-numericn 1 - general short numericn 2 - general numericn 10 and above specific type for codegen_version=7



isCommuter Commuter licenses.

commuter_max_checkout_days

Themaximum number of days a commuter license can be checked out for.It can be:

n A value between 1 to 1827 days for long licenses.n A value between 1 to 60 days for short licenses.n Zero for unlimited check-out (up to the license expiration)

log_encrypt_level For encryption level in the license code.

vendor_code Vendor identification code.

version_num The license version number, like version 11, 12, 13, and 14 licenses, in map-ping with the RMS SDK versions.

meter_value Fields for multi_key for short numeric codegen version >=2.

num_features Number of features in case ofmulti key.

key_type Single key/Multi key for short numeric only.

capacity_flag Specifies if the license is a capacity or non-capacity license. Values can be:

n VLScg_CAPACITY_NONEn VLScg_CAPACITY_NON_POOLEDn VLScg_CAPACITY_POOLED

capacity_units Flag which determines capacity least count.

long capacity The capacity of this license.

grace_period_flag A flag that decides whether grace period for a license will be provided ornot. It can be any of the following constants:

n VLScg_NO_GRACE_PERIOD - grace period not allowed (default)n 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 between1 to 180 days. The default value is 2 days.



Member Description

grace_period_elasped_hours The number of hours the grace period will last for. It can be a value between1 to 1440 hours. The default value is 20 hours.


overdraft_hours Not supported.

overdraft_users Not supported.

overdraft_users_isPercent Not supported.

local_request_lockcrit_flag 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 to1. This is the default setting.

n VLS_LOCAL_REQUEST_LOCKCRIT_DEFINED - Sets local_request_lock-crit_required to a user-defined value.

local_request_lockcrit_required The necessary number of locking criteria that must bemet for making thelicenses available to a local client.

local_request_lockcrit_float The desired number of locking criteria that must bemet for making thelicenses available to a local client.

local_request_lockcrit_min_num

Theminimum number of locking criteria that must bemet for making thelicenses available to a local client. For example, the “required” locking crite-ria can be disk ID, the “floating” criteria can be ethernet card and CID key,and the “minimum” criteria can be any two of the above.

trial_elapsed_hours The trial hours specified for a trial license.

plain_vendor_info The public vendor information. Themaximum length of the string can be upto 395 characters.

vm_detection The flag to allow or deny the grant of a license token in case the licenseserver is found running on a virtual machine. It can have the followingvalues:

n VLScg_VM_DISALLOWED_STRING - Denies the grant of a license.n 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.

WARNING

Th i s m embe r i s ad d e d i n th e 8 .4 .0 r e l e ase . How e ve r , toe n su r e c om pat i b i l i t y i n th e sub se que n t r e l e ase s , y o u m u s tf i l l u p th i s m embe r w i th th e s i z e o f Code T . E l s e , u p g r ad e toth e l i c e n se ge ne r a t i o n DL L w i l l f a i l .

About Reserved Characters and StringsPlease note the following guidelines regarding reserved characters and strings:

n ! and $ are reserved characters and cannot be used in feature name, feature version, privatevendor information, public vendor information and secret text.

n Space is not an acceptable character in the vendor information (both public and private).

n 011 and oil are reserved strings and cannot be used in feature name and feature version.

n NiL and Ni are reserved strings and cannot be used in feature name, feature version, privatevendor information and public vendor information.

n # is a comment character and all text appearing after this will be ignored in vendor infor-mation (both public and private).

About Reserved Characters and Strings 317


The Basic FunctionsGiven below is a list of the API functions:


VLScgInitialize Initializes the handle.

VLScgCleanup Destroys the created handle.

VLScgReset Resets the structure with default values.

VLScgGetLibInfo Returns information about the license generator library currentlybeing used in the structure pointed to by pStruct .

10.3. VLScgInitialize

10.3.1. Syntaxint VLScgInitialize (

VLScg_HANDLE *iHandleP );


iHandleP The pointer to the instance handle for this library. Provides access to the inter-nal data structure.

10.3.2. Description

Required library initialization call. Every API call requires a valid handle. This function allocatesresources required for generating licenses. This function must be called before using any otherVLScgXXX function.

10.3.3. Returns



VLScg_MAX_LIMIT_CROSSED No more handles left.

VLScg_BAD_HANDLE Call VLScgCleanup to free the resources associatedwith invalid handle.

VLScg_LICMETER_NOT_ SUPPORTED Your Sentinel RMS licensemeter is not supported.

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

10.3.4. See Also

n VLScgCleanup

10.3. VLScgInitialize 319


10.4. VLScgCleanup

10.4.1. Syntaxint VLScgCleanup (

VLScg_HANDLE *iHandleP );


iHandleP 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 returnedindicating the reason for failure. For a complete list of the error codes, see License Generation ErrorCodes.

10.5. VLScgReset

10.5.1. Syntaxint VLScgReset (

VLScg_HANDLE *iHandleP,

codeT *codeP );


iHandleP The instance handle for this library.

codeP Name of the structure.

10.5.2. Description

This function resets the codeP structure by filling in default values. It must be called before callingVLScgSetXXX functions.

10.5.3. Returns

The status code VLScg_SUCCESS is returned if successful. Otherwise, a specific error code is returnedindicating the reason for failure. For a complete list of the error codes, see License Generation ErrorCodes

10.5. VLScgReset 321


10.6. VLScgGetLibInfoReturns information about the license generator library currently being used in the structure pointedto by pStruct .

10.6.1. Syntaxint VLScgGetLibInfo (VLScg_LIBVERSION *pStruct )

typedef struct {

long structSz;

char szVersion [LIBINFOLEN];

} LS_CGLIBVERSION

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 pStructmust be allocated by the caller.

10.6.3. Returns



VLScg_INVALID_INPUT Input values for the IN/OUT structure parameter are incorrect.


Functions Retrieving ErrorsWhen errors are encountered during execution of License Generation functions, they are queued tothe handle that controls access to the library in use. These errors may be printed immediately, orallowed to accumulate and flushed at a later time.



VLScgGetNumErrors Retrieves number of error messages recorded.

VLScgGetErrorLength Retrieves the length of a error message.

VLScgGetErrorMessage Retrieves the earliest error from the handle.

VLScgPrintError Writes the error struct to a file.

VLScgPrintErrorExt

Functions Retrieving Errors 323


10.7. VLScgGetNumErrors

10.7.1. Syntaxint VLScgGetNumErrors (

VLScg_HANDLE iHandleP,

int *numMsgsP );


iHandleP The pointer to the instance handle for this library.

numMsgsP (OUT) The number ofmessages queued to the handle.

10.7.2. Description

This function retrieves the number ofmessages 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



VLScg_NO_RESOURCES If no resources are available.

VLScg_FAIL If operation failed.


10.8. VLScgGetErrorLength

10.8.1. Syntaxint VLScgGetErrorLength (

VLScg_HANDLE iHandle,

int msgNum,

int errLenP );


iHandle The instance handle for this library.

msgNum The number of themessage whose length is to be queried.

errLenP The length of themessage identified by msgNum.

10.8.2. Description

This function retrieves the length ofmessage #msgNum recorded in the handle. It includes the spacerequired for NULL termination.

10.8.3. Returns






10.8. VLScgGetErrorLength 325


10.9. VLScgGetErrorMessage

10.9.1. Syntaxint VLScgGetErrorMessage(


char *msgBuf,

int bufLen );



msgBuf (OUT) A user allocated buffer into which the referencemessage will be copied.

bufLen The byte length of themessage copied intomsgBuf.

10.9.2. Description

This function retrieves the oldest error queued to the handle, and copies a maximum of bufLen bytestomsgBuf as a null-terminated string.msgBuf is a user allocated buffer and must be bufLen bytes inlength. Upon successful completion of this function, themessage retrieved will have been removedfrom the queue.

10.9.3. Returns






10.10. VLScgPrintError

10.10.1. Syntaxint VLScgPrintError (


FILE *file );



file A pointer to a file.

10.10.2. Description

This function writes the accumulated errors to the specified file.

10.10.3. Returns






10.10. VLScgPrintError 327


10.11. VLScgPrintErrorExt

10.11.1. Syntaxint VLScgPrintErrorExt (


char *fileName );



fileName A pointer to a filename. To write data into the:

n standard output (stdout) - specify “stdout” as the filename.n standard error (stderr) - specify “stderr” as the filename.


This function writes the accumulated errors to the specified file or standard error or standard outputstreams.

10.11.3. Returns






The Functions for Setting the Fields in CodeT StructThe 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.


VLScgSetCodeLength Sets the license code length.

VLScgAllowFeatureNameVLScgSetFeatureName

Sets the name of the` feature to be licensed.

VLScgAllowFeatureVersionVLScgSetFeatureVersion

Sets the version number to be licensed.

VLScgAllowLicenseTypeVLScgSetLicenseType

Controls the license type.

VLScgAllowTrialLicFeatureVLScgSetTrialDaysCount

Sets the number of trial days.

VLScgAllowAdditiveVLScgAllowAggregateLicenseVLScgSetAdditive

Sets the license to additive, exclusive, or aggre-gate.

VLScgAllowKeyLifeUnitsVLScgSetKeyLifetimeUnits

Sets unit of time used to specify time betweenlicense renewals.

VLScgAllowStandAloneFlagVLScgAllowNetworkFlagVLScgAllowRepositoryFlagVLScgSetStandAloneFlag

Sets whether the license will be stand-alone, net-work, or repository.

VLScgAllowLogEncryptLevelVLScgSetLogEncryptLevel

Controls the network license encryption level forthe license server’s usage log file.

VLScgAllowSharedLic/ VLScgAllowTeamCriteriaVLScgSetSharedLicType/ VLScgSetTeamCriteria

Enables shared licenses and sets sharing criteriafor non-capacity license.

Enables team licenses and sets team criteria forcapacity license.

VLScgAllowShareLimit/ VLScgAllowTeamLimitVLScgSetShareLimit/ VLScgSetTeamLimit

Sets the number of users that can share a non-capacity license.

Sets the number of team members that can sharea token in case of capacity license.

VLScgAllowCommuterLicenseVLScgSetCommuterLicense

Enables commuter licenses to be checked out.

VLScgAllowNumKeysVLScgSetNumKeys

Sets the number of concurrent licenses allowed.




VLScgAllowLockModeQueryVLScgSetClientServerLockMode

Sets locking mode for the license server computer.Installs client server lock mode in codeP.

VLScgAllowRedundantFlagVLScgSetRedundantFlag

Controls whether the license will be used withredundant license servers.

VLScgAllowMajorityRuleFlagVLScgSetMajorityRuleFlag

Controls whether themajority of redundantlicense servers must be running.

VLScgAllowMultipleServerInfoVLScgSetNumServers Fields for information on various license servers.

VLScgAllowServerLockInfoVLScgSetServerLockInfo1

Sets license server primary locking code. Installslicense server lock code in primary lock.

VLScgSetServerLockMechanism1

Sets license server primary fingerprint criteria.Installs license server's fingerprint criteria in pri-mary lock.

VLScgSetServerLockMechanism2

Sets license server secondary fingerprint criteria.Installs license server's fingerprint criteria in sec-ondary lock.

VLScgSetServerLockInfo2 Sets license server secondary locking code. Installsserver lock code in secondary lock.

VLScgAllowLockMechanismVLScgSetClientLockMechanism

Sets client’s fingerprint criteria.

VLScgAllowClientLockInfoVLScgSetClientLockInfo

Sets the client locking code.

VLScgSetNumClients Sets the number of client locking codes to be spec-ified.

VLScgAllowClockTamperFlagVLScgSetClockTamperFlag

Controls action on detection of clock being setback on themachine.

VLScgAllowOutLicTypeVLScgSetOutLicType

Sets the license output format.

VLScgSetLicType Sets the license type.

VLScgAllowHeldLicVLScgSetHoldingCrit

Enables/disables license hold time and determineswhere that hold time is specified.

VLScgAllowCodegenVersionVLScgSetCodegenVersion

Sets the version of license codes to generate.Checks if the current license code setting allowsmultiple features.

VLScgAllowMultiKeyVLScgSetKeyType

Controls whether a license will be single or multi-feature.

VLScgAllowSecretsVLScgSetSecretsVLScgSetNumSecrets

Sets the value of the specified challenge-responsesecrets.Sets the total number of secrets for the challenge-response.

VLScgAllowVendorInfoVLScgSetVendorInfo

Sets vendor-defined information in the license.


VLScgAllowKeysPerNodeVLScgSetKeysPerNode

Sets the number of license tokens per node for thespecified number of clients.

VLScgAllowSiteLicVLScgSetSiteLicInfoVLScgSetNumSubnets

Sets address of subnets licensed application will berestricted to.Sets the number of subnets the licensed appli-cation is restricted to.

VLScgAllowMultipleFeatureVLScgSetNumFeatures

Sets the number of features.

VLScgAllowSoftLimitVLScgSetSoftLimit

Sets soft limit number.

VLScgAllowKeyHoldUnitsVLScgSetKeyHoldtimeUnits

Sets units of time to be used to specify licensehold time.

VLScgAllowKeyLifetimeVLScgSetKeyLifetime

Sets time between license renewals.

VLScgAllowKeyHoldtimeVLScgSetKeyHoldtime

Sets the time a license will be held.

VLScgAllowLicBirthVLScgSetLicBirthMonthVLScgSetLicBirthDayVLScgSetLicBirthYear

Sets themonth of the license start date (themonth 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.

VLScgAllowLicExpirationVLScgSetLicExpirationMonthVLScgSetLicExpirationDayVLScgSetLicExpirationYear

Sets month license expires.Themonths should bespecified in the range of 0-11.Sets day month the license expires.Sets the year the license expires.

VLScgSetNumericType Sets the value of numeric type.

VLScgSetLoadSWLicFile Sets and loads the software license file (lscgen.lic).

VLScgAllowGracePeriodFlagVLScgSetGracePeriodFlagVLScgAllowGracePeriodVLScgSetGracePeriodDaysVLScgSetGracePeriodHours

Set the grace period for the commuter license.

VLScgAllowVmDetectionVLScgSetVmDetection

Sets the action on detection of a virtualmachine—whether to allow\deny grant of alicense token.



10.12. VLScgSetCodeLength

10.12.1. Syntaxint VLScgSetCodeLength (


codeT *codeP,

char *flag );



codeP The pointer to the codeT struct.

flag Flag values are used to set the code_typemember of codeT struct. Legal valuesare:

n VLScg_SHORT_CODE_STRING = “0”n VLScg_LONG_CODE_STRING = “1”n VLScg_SHORT_NUMERIC_CODE = “2”


Sets the license code length to short or long.

License codes are 10 characters or longer uppercase alphanumeric or all-numeric strings. The code gen-erator will generate long, short or short, numeric license codes.

n Short codes contain less information than the long code and cannot support certain licensingoption. However, they have the advantage of being easier to generate and easier to com-municate to end users.

n Long codes contain as many characters as needed.

n Short, numeric codes generate numeric strings only and requires minimal information fromthe user. This code contains the least information.

10.12.3. Returns



VLScg_INVALID_INPUT If either codeP or flag are NULL.

VLScg_INVALID_INT_TYPE Value is not numeric.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_SHORT_CODE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_LONG_CODE_STRING.


10.13. VLScgAllowFeatureName

10.13.1. Syntaxint VLScgAllowFeatureName (


codeT *codeP );




10.13.2. Returns

The VLScgAllowXXX function tests whether the corresponding VLScgSetXXX should be called. IfVLScgAllowXXX returns 1 then the corresponding VLScgSetXXX function can be called. Otherwise, itwill return 0 as false.

10.13. VLScgAllowFeatureName 333


10.14. VLScgSetFeatureName

10.14.1. Syntax int VLScgSetFeatureName (


codeT *codeP,

char *info );




info Any printable ASCII text. Maximum of 24 and 11 characters for long and shortlicenses, respectively. The Basic Functions


A feature name can represent a single executable file, multiple executable files, or a portion (a func-tion) of an executable file.

A feature namemay be a maximum of 11 ASCII characters for short license codes and a maximum of24 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



VLScg_NO_FEATURE_NAME If the name is NULL.

VLScg_RESERV_STR_ERROR If the string is a reserved string.

VLScg_INVALID_CHARS If the string characters are not printable.

VLScg_EXCEEDS_MAX_VALUE Returned if the length of string passed exceeds themaximumlength of 24.


10.15. VLScgAllowFeatureVersion

10.15.1. Syntaxint VLScgAllowFeatureVersion (


codeT *codeP );




10.15.2. Returns


10.15. VLScgAllowFeatureVersion 335


10.16. VLScgSetFeatureVersion

10.16.1. Syntax int VLScgSetFeatureVersion (


codeT *codeP,

char *info );




info Any printable ASCII text. Maximum of 11 characters for long licenses. Not supportedfor short license codes. The Basic Functions


Version number is optional. Not supported for short license codes.

10.16.3. Returns



VLScg_RESERV_STR_ERROR

If the string is a reserved string.

VLScg_INVALID_CHARS If the string characters are not printable.

VLScg_EXCEEDS_MAX_ VALUE

If string exceeds maximum number of characters. Maximum length ofthe version is 11 characters.


10.17. VLScgAllowLicenseType

10.17.1. Syntaxint VLScgAllowLicenseType (


codeT *codeP );




10.17.2. Returns


10.17. VLScgAllowLicenseType 337


10.18. VLScgSetLicenseType

10.18.1. Syntaxint VLScgSetLicenseType (


codeT *codeP,

char *flag );




flag Flag is used to set the code_typemember of codeT struct. The values are:

n VLScg_NORMAL_LIC_STRING - Non-trial license = “0”n VLScg_TRIAL_LIC_STRING - Trial license = “1”


Controls the license type for non-trial and trial licenses.

10.18.3. Returns



VLScg_INVALID_INT_TYPE If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_TRIAL_LIC_STRING.

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_NORMAL_LIC_STRING


10.19. VLScgAllowTrialLicFeature

10.19.1. Syntaxint VLScgAllowTrialLicFeature (


codeT *codeP );




10.19.2. Returns


10.19. VLScgAllowTrialLicFeature 339


10.20. VLScgSetTrialDaysCount

10.20.1. Syntaxint VLScgSetTrialDaysCount (


codeT *codeP,

char *daysStr );




daysStr String representing the number of days to use in a trial period.


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 thelicense is requested.

10.20.3. Returns


10.21. VLScgAllowTrialHoursVerifies 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. Syntaxint VLScgAllowTrialHours (


codeT *codeP );




10.21.2. Returns

This API returns 1, if the trial elapsed hours is allowed, else it will return 0.

10.21. VLScgAllowTrialHours 341


10.22. VLScgSetTrialHoursSets the number of trial elapsed hours in a trial license code.

10.22.1. Syntaxint VLScgSetTrialHours (


codeT *codeP,

char *trialHourStr );




trialHourStr The number of hours for using the trial license. Theminimum and maximumvalues are defined by the VLScg_MIN_TRIALHOURS_LONGCODE_LIMIT and VLScg_MAX_TRIALHOURS_LONGCODE_LIMIT, respectively.


Sets the number of trial elapsed hours in a trial license code. However, before this API is called, youneed to call the VLScgAllowTrialHours API function. Calling the VLScgAllowTrialHours API functionensures 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:


VLScg_INVALID_INPUT Argument specified is not correct, that is, one of the following rea-sons exist:

n codeP is NULLn TrialHourStr is NULL.

VLScg_INVALID_TRI-ALHOURS

The trialHourStr argument is invalid.

10.23. VLScgAllowAdditive

10.23.1. Syntaxint VLScgAllowAdditive(


codeT *codeP );




10.23.2. Returns


10.23. VLScgAllowAdditive 343


10.24. VLScgAllowAggregateLicense

10.24.1. Syntaxint VLScgAllowAggregate(


codeT *codeP );

n Make sure that prior to this API, VLScgSetCodegenVersion API is called with license version as14 or later.

n Call VLScgSetAdditive after calling VLScgAllowAggregateLicense to set the combining propertyof the license.




10.24.2. Returns


10.25. VLScgSetAdditive

10.25.1. Syntaxint VLScgSetAdditive (


codeT *codeP,

char *flag );




flag The value of flag indicates whether the license to be generated is addi-tive/aggregate/exclusive. The legal values are:

n VLScg_ADDITIVE = “0”n VLScg_EXCLUSIVE = “1”n VLScg_AGGREGATE_LICENSE = “2”


This function determines how this license will interact with a license already installed for this featureand version.

n If a license is defined as exclusive, it will override an existing license for the same feature andversion.

n If a license is additive, it appends changes to an existing additive license for the feature andversion.

n If the license is aggregate, multiple license strings for the feature and version can be combinedto form an aggregated hard and soft limit, yet the start and expiry dates of the individuallicenses strings aremaintained in an independent manner.

10.25.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_AGGREGATE_LICENSE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_ADDITIVE_STRING.


10.25. VLScgSetAdditive 345


10.26. VLScgAllowKeyLifetime

10.26.1. Syntaxint VLScgAllowKeyLifetime (


codeT *codeP );




10.26.2. Returns


10.27. VLScgSetKeyLifetime

10.27.1. Syntaxint VLScgSetKeyLifetime (


codeT *codeP,

char *info );




info Absolute value in minutes of license lifetime. Maximum depends on lifetime unitsset by VLScgSetKeyLifetimeUnits.


A licensemust be renewed by the application on a regular schedule or the license will be reclaimed.This function specifies the number ofminutes between renewals. Maximum and granularity dependson VLScgSetKeyLifetimeUnits.

10.27.3. Returns



VLScg_INVALID_INT_TYPE If information is a non-negative integer.

VLScg_NOT_MULTIPLE If value is not a correct multiple.

VLScg_EXCEEDS_MAX_VALUE If value exceeds 3.

VLScg_LESS_THAN_MIN_VALUE If value is less than or equal to 0.


10.27. VLScgSetKeyLifetime 347


10.28. VLScgAllowStandAloneFlag

10.28.1. Syntaxint VLScgAllowStandAloneFlag (


codeT *codeP );




10.28.2. Returns


10.29. VLScgAllowNetworkFlag

10.29.1. Syntaxint VLScgAllowNetworkFlag (


codeT *codeP );




10.29.2. Returns


10.29. VLScgAllowNetworkFlag 349


10.30. VLScgAllowPerpetualFlag

Use VLScgAllowRepositoryFlag instead of VLScgAllowPerpetualFlag in implementations beyond RMS SDK

v8.5.0.

10.30.1. Syntaxint VLScgAllowPerpetualFlag(


codeT *codeP );




10.30.2. Returns


10.31. VLScgAllowRepositoryFlag

10.31.1. Syntaxint VLScgAllowRepositoryFlag(


codeT *codeP );




10.31.2. Returns


10.31. VLScgAllowRepositoryFlag 351


10.32. VLScgSetStandAloneFlag

10.32.1. Syntaxint VLScgSetStandAloneFlag (


codeT *codeP,

char *flag );




flag Flag values are used to set the standalone_flag of codeT struct. Legal values are:

n VLScg_NETWORK_STRINGn VLScg_STANDALONE_STRINGn VLScg_REPOSITORY_STRINGn VLScg_PERPETUAL_STRING (use VLScg_REPOSITORY_STRING instead for

implementations after v8.5.0)


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




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_REPOSITORY_STRING ,

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_NETWORK_STRING.


10.33. VLScgAllowLogEncryptLevel

10.33.1. Syntaxint VLScgAllowLogEncryptLevel (


codeT *codeP );




10.33.2. Returns


10.33. VLScgAllowLogEncryptLevel 353


10.34. VLScgSetLogEncryptLevel

10.34.1. Syntaxint VLScgSetLogEncryptLevel (


codeT *codeP,

char *flag );




flag Allowed value are:

n “0”n “1”n “2”n “3”n “4”


Controls the encryption level to the network licenses for the license server’s usage log file.

10.34.3. Returns



VLScg_INVALID_INT_TYPE If value is not a decimal number.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAX_ENCRYPTION_LEVEL.

VLScg_LESS_THAN_MIN_VALUE

If value is lower than VLScg_NO_ENCRYPTION.


10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria

10.35.1. Syntax

In case of non-capacity license:

int VLScgAllowSharedLic (


codeT *codeP );

In case of capacity license:

int VLScgAllowTeamCriteria (


codeT *codeP );




We recommend you use VLScgAllowSharedLic for non-capacity license and VLScgAllowTeamCriteria for

capacity license.

10.35.2. Returns


10.35. VLScgAllowSharedLic and VLSAllowTeamCriteria 355


10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria

10.36.1. Syntax


int VLScgSetSharedLicType (


codeT *codeP,

char *flag );


int VLScgSetTeamCriteria (


codeT *codeP,

char *flag );




flag This flag enables shared licenses and specifies the sharing criteria. Legal values are:

n VLScg_NO_SHARING_STRING = “0”n VLScg_USER_SHARING_STRING = “1”n VLScg_HOSTNAME_SHARING_STRING = “2”n VLScg_XDISPLAY_SHARING_STRING = “3”n VLScg_VENDOR_SHARING_STRING = “4” - Vendor defined / customized.

Need to customize the client library for this.


The concept of shared license is only applicable to network licenses. If sharing is enabled a user canusemultiple instances of a protected application without consuming more than one license. Call thisfunction enables sharing and also sets which criteria to use to determine eligibility of the user to sharea 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 timewithout using more thanone license.

Tip

We recommend you use VLScgSetSharedL icType for non-capac ity license and VLScgSet-TeamCriter ia for capac ity license.

10.36.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_VENDOR_SHARING_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_NO_SHARING_STRING.


10.36. VLScgSetSharedLicType/ VLScgSetTeamCriteria 357


10.37. VLScgAllowShareLimit/ VLScgAllowTeamLimit

10.37.1. Syntax


int VLScgAllowShareLimit (


codeT *codeP );


int VLScgAllowTeamLimit (


*codeP );




Tip

We recommend you use VLScgAllowShareLimit for non-capacity license andVLScgAllowTeamLimit for capacity license.

10.37.2. Returns


10.38. VLScgSetShareLimit and VLScgSetTeamLimit

10.38.1. Syntax


int VLScgSetShareLimit (


codeT *codeP,

char *decimalNUM );


int VLScgSetTeamLimit (


codeT *codeP,

char *decimalNUM );




decimalNUM Controls the number of users/clients who can share a single license. Use a decimalnumeric value setting to control the number of users that can share a license.VLScg_NOLIMIT_STRING for unlimited.


If sharing is set, multiple users or a single user using multiple instances of your application, can share alicense.

This function restricts the number of clients who can share a license. The decimalNUM limit forces theissue of a new license, when the sharing limit has been reached for a non-capacity license or when theteam limit has been reached for a capacity license.

Tip

We recommend you use VLScgSetShareL imit for non-capac ity license and VLScgSet-TeamLimit for capac ity license.

10.38.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than minimum.

10.38. VLScgSetShareLimit and VLScgSetTeamLimit 359

10.39. VLScgAllowCommuterLicense

10.39.1. Syntaxint VLScgAllowCommuterLicense (


codeT *codeP );




10.39.2. Returns


10.39. VLScgAllowCommuterLicense 361


10.40. VLScgSetCommuterLicense

10.40.1. Syntaxint VLScgSetCommuterLicense (


codeT *codeP,

char *flag );




flag Valid values are:

n VLScg_NOT_ISSUE_COMMUTER_CODES_STRING = “0”n VLScg_ISSUE_COMMUTER_LICENSE_CODE_STRING = “1”


Enables commuter licenses.

This function is used to generate license use authorizations for traveling clients. Commuter licensingallows end users to “check out” an authorization from a network served license group and “check itin” when they are done using the application.

10.40.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_ISSUE_COMMUTER_CODES_STRING


If value is lower than VLScg_NOT_ISSUE_COMMUTER_CODES_STRING.


10.41. VLScgAllowCommuterMaxCheckoutDays

10.41.1. Syntaxint VLScgAllowCommuterMaxCheckoutDays (


codeT *codeP );




10.41.2. Returns


10.41. VLScgAllowCommuterMaxCheckoutDays 363


10.42. VLScgSetCommuterMaxCheckoutDays

10.42.1. Syntaxint VLScgSetCommuterMaxCheckoutDays (


codeT *codeP,

char * dayStr );




daysStr


Sets themaximum check-out days allowed for a commuter license.

10.42.3. Returns


10.43. VLScgAllowNumKeys

10.43.1. Syntaxint VLScgAllowNumKeys (


codeT *codeP );




10.43.2. Returns


10.43. VLScgAllowNumKeys 365


10.44. VLScgSetNumKeys

10.44.1. Syntaxint VLScgSetNumKeys (


codeT *codeP,

char *info,

int num );




info Sets the number of concurrent licenses: should be from 0 to VLScg_NOLIMIT_STRING for no limit.

num Should be 0 in case of single feature and from 0 to “no_of_features -1” in case ofmulti-feature.


Can be used to set the hard limit or (the number of concurrent licenses allowed) for both a standaloneas well as a network license.

10.44.3. Returns



VLScg_INVALID_INT_TYPE If value is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE If value of info exceeds maximum number of license tokensallowed. Maximum value for long codes is 32766 and max-imum value for short codes is 254.

VLScg_LESS_THAN_MIN_VALUE If value of info is less than 0.


10.45. VLScgAllowLockModeQuery

10.45.1. Syntaxint VLScgAllowLockModeQuery (


codeT *codeP );




10.45.2. Returns


10.45. VLScgAllowLockModeQuery 367


10.46. VLScgSetClientServerLockMode

10.46.1. Syntaxint VLScgSetClientServerLockMode (


codeT *codeP,

char *flag );




flag The flag values are:

n VLScg_FLOATING_STRING - License server is locked = “0”n VLScg_BOTH_NODE_LOCKED_STRING - Clients and license server are locked

= “1”n VLScg_DEMO_MODE_STRING - Trial license (no locking) = “2”n VLScg_CLIENT_NODE_LOCKED_STRING - Only clients are locked = “3”


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 licensecode structure.

10.46.3. Returns




VLScg_EXCEEDS_MAX_VALUE

If the value of flag exceeds maximum of 3.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than theminimum of 0.


10.47. VLScgAllowRedundantFlag

10.47.1. Syntaxint VLScgAllowRedundantFlag (


codeT *codeP );




10.47.2. Returns


10.47. VLScgAllowRedundantFlag 369


10.48. VLScgSetRedundantFlag

10.48.1. Syntaxint VLScgSetRedundantFlag (


codeT *codeP,

char *flag );





n VLScg_NON_REDUNDANT_CODE_STRING - Non-redundant license = “0”n VLScg_REDUNDANT_CODE_STRING - Redundant license = “1”


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 ormore license servers fail.

10.48.3. Returns



VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_REDUNDANT_CODE_STRING.


If value is less than VLScg_NON_REDUNDANT_CODE_STRING.


10.49. VLScgAllowMajorityRuleFlag

10.49.1. Syntaxint VLScgAllowMajorityRuleFlag (


codeT *codeP );




10.49.2. Returns


10.49. VLScgAllowMajorityRuleFlag 371


10.50. VLScgSetMajorityRuleFlag

10.50.1. Syntaxint VLScgSetMajorityRuleFlag (


codeT *codeP,

char *flag );





n VLScg_MAJORITY_RULE_FOLLOWS_STRING - Sets themajority_rule_flag = “1”n VLScg_MAJORITY_RULE_NOT_FOLLOWS_STRING - Unsets themajority_rule_

flag = “0”


Controls whether themajority of redundant license servers must be running.

If the number of redundant license servers running is less than half of the number of license serversspecified in the license file, then all servers will stop servicing all old and new clients. For example, if 7redundant license servers are specified, at least 4 of them must be running to satisfy themajority rule.

10.50.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAJORITY_RULE_FOLLOWS_STRING

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_MAJORITY_RULE_NOT_FOLLOWS_STRING.


10.51. VLScgAllowMultipleServerInfo

10.51.1. Syntaxint VLScgAllowMultipleServerInfo (


codeT *codeP );




10.51.2. Returns


10.51. VLScgAllowMultipleServerInfo 373


10.52. VLScgSetNumServers

10.52.1. Syntaxint VLScgSetNumServers (


codeT *codeP

char *str );




str Number of servers


This API sets the number of redundant servers. It can be called for long codes only also the number ofservers should be odd. This sets the number of servers for redundancy.

10.52.3. Returns



VLScg_INVALID_INT_TYPE If value is not numeric

VLScg_EXCEEDS_MAX_VALUE If value exceeds themaximum number of license servers. Max-imum number of license servers can be 11.

VLScg_LESS_THAN_MIN_VALUE If the value is less than minimum number of license servers thatis equal to or less than 0.


10.53. VLScgAllowServerLockInfo

10.53.1. Syntaxint VLScgAllowServerLockInfo (


codeT *codeP );




10.53.2. Returns


10.53. VLScgAllowServerLockInfo 375


10.54. VLScgSetServerLockInfo1

10.54.1. Syntaxint VLScgSetServerLockInfo1 (


codeT *codeP,

char *lockCode,

int num );




lockCode The lock code to be checked and set. It should be a 5 or 16 character hex string forthe old and new style locking codes, respectively (optionally preceded by “0x”).

num Position in server_lock_info1where, lockCode is stored starting from 0 to num_servers-1where num_servers is set using VLScgSetNumServers.server_lock_info1 is an array of 11 elements storing the primary locking codes for 11servers.


Installs the value of lockCode in the code structure field server_lock_info1[num] to set the primarylocking code.

10.54.3. Returns



VLScg_INVALID_HEX_TYPE If value is not in hexadecimal format.

VLScg_EXCEEDS_MAX_VALUE If value exceeds themaximum number of license servers. Thevalue set using the API VLScgSetNumServers

VLScg_LESS_THAN_MIN_VALUE If the value is less than minimum number of license servers.


10.55. VLScgSetServerLockMechanism1

10.55.1. Syntaxint VLScgSetServerLockMechanism1 (


codeT *codeP,

char *criterion,

int server );




criterion The lock code to install. Value should be in hex format.

server Position in array which is storing the primary locking criteria of the 11 servers.Value 0 to num_servers where num_servers is set using VLScgSetNumServers.


This function sets the criteria for the primary license server. Installs a license server’s primary fin-gerprint criteria in the code structure. A fingerprint is computed by selecting operating characteristicsof the host system and forming a mask with bits set corresponding to those characteristics. The dif-ferent fingerprinting elements are defined in the VLScg_LOCK_ section of lscgen.h, and includes crite-ria such as ID Prom, IP address, disk ID, etc. A license server can be locked to either of two groups offingerprints. The second group will be tried if the first licensed fingerprint group fails to match thelicense server’s fingerprint at the end-user site.

10.55.3. Returns



VLScg_INVALID_HEX_TYPE If criterion is not in hexadecimal format.

VLScg_EXCEEDS_MAX_VALUE If number of server is too large. The value set using the APIVLScgSetNumServers.

VLScg_LESS_THAN_MIN_VALUE If the number of server is lower than minimum.




10.56. VLScgSetServerLockMechanism2

10.56.1. Syntaxint VLScgSetServerLockMechanism2 (


codeT *codeP,

char *criterion,

int server );




criterion The lock code to install (in hex).

server Position in array which is storing the secondary locking criteria of the 11 servers.Its value should also vary from 0 - num_servers where num_servers is set usingVLScgSetNumServers.


This function sets the criteria for the secondary license server. Installs a license server’s secondary fin-gerprint criteria in the code structure. A fingerprint is computed by selecting operating characteristicsof the host system and forming a mask with bits set corresponding to those characteristics. The dif-ferent fingerprinting elements are defined in the VLScg_LOCK_ section of lscgen.h, and includes crite-ria such as ID Prom, IP address, disk ID, etc. A license server can be locked to either of two groups offingerprints. The second group will be tried if the first licensed fingerprint group fails to match thelicense server’s fingerprint at the end-user site.

10.56.3. Returns



VLScg_INVALID_HEX_TYPE If criterion is not in hexadecimal format.

VLScg_EXCEEDS_MAX_VALUE If number of server is too large. The value set using the APIVLScgSetNumServers.

VLScg_LESS_THAN_MIN_VALUE If the number of server is lower than minimum.


10.57. VLScgSetServerLockInfo2

10.57.1. Syntaxint VLScgSetServerLockInfo2 (


codeT *codeP,

char *lockCode,

int num );




lockCode The lock code to be checked and set. Lock code should be an 8-character hexstring (32-bit numeric locking code), optionally preceded by “0x.”

num Position in server_lock_info2where lockCode is stored starting from 0 to num_servers-1where num_servers is set using VLScgSetNumServers.server_lock_info2 is an array of 11 elements storing the secondary locking codesfor 11 servers.


Installs the value of lockCode in the code structure field server_lock_info2[num] to set the secondarylocking code.

10.57.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value is too large. The value set using the API VLScgSet-NumServers.





10.58. VLScgAllowLockMechanism

10.58.1. Syntaxint VLScgAllowLockMechanism (


codeT *codeP );




10.58.2. Returns


10.59. VLScgSetClientLockMechanism

10.59.1. Syntax int VLScgSetClientLockMechanism (


codeT *codeP,

char *criterion,

int client_num );




criterion Mask defining which fields ofmachineID are to be used for locking. Value shouldbe in hex format.

client_num client_num is the position in the array storing the locking mechanisms for theclients. The value will vary from 0 to num_nl_clients where num_nl_clients is thenumber of clients set using VLScgSetNumClients.


Installs a client’s fingerprint criteria in the code structure. A fingerprint is computed by selecting oper-ating characteristics of the host system and forming a mask with bits set corresponding to those char-acteristics. 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




VLScg_EXCEEDS_MAX_VALUE If value is too large. The value set using the API VLScgSet-NumClients.



10.59. VLScgSetClientLockMechanism 381


10.60. VLScgAllowClientLockInfo

10.60.1. Syntaxint VLScgAllowClientLockInfo (


codeT *codeP );




10.60.2. Returns


10.61. VLScgSetClientLockInfo

10.61.1. Syntaxint VLScgSetClientLockInfo (


codeT *codeP,

char *lockCode,

int num );




lockCode This buffer is used to set the lock code information for clients.

num Number of clients: should be from 0 to maximum number of clients specified -1.num is the position in the array storing the locking codes for the clients. The valuewill vary from 0 to num_nl_clients where num_nl_clients is the number of clients setusing VLScgSetNumClients.


Sets the client locking code.

10.61.3. Returns




VLScg_EXCEEDS_MAX_VALUE If number is greater than num_nl_clients -1. Number of nodelocked clients.

VLScg_LESS_THAN_MIN_VALUE If number is less than 0.

VLScg_INVALID_IP_TYPE If value is not in dot format.

VLScg_UNKNOWN_LOCK If the locking criteria is unknown.


10.61. VLScgSetClientLockInfo 383


10.62. VLScgSetNumClients

10.62.1. Syntaxint VLScgSetNumClients (


codeT *codeP,

char *info );




info Number of client locking codes to be specified.


Applications can be locked to specific client computers using locking codes that uniquely identifythose computers.

10.62.3. Returns



VLScg_INVALID_INT_TYPE If input is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum number of 7 clients.

VLScg_LESS_THAN_MIN_VALUE If value is less than 1.


10.63. VLScgAllowClockTamperFlag

10.63.1. Syntaxint VLScgAllowClockTamperFlag (


codeT *codeP );




10.63.2. Returns


10.63. VLScgAllowClockTamperFlag 385


10.64. VLScgSetClockTamperFlag

10.64.1. Syntaxint VLScgSetClockTamperFlag (


codeT *codeP,

char *flag );





n VLScg_NO_CHECK_TAMPER_STRING - Do not check clock tamper = “0”n VLScg_CHECK_TAMPER_STRING - Check clock tamper = “1”


Controls action on detection of clock being set back on themachine.

Clock tamper check will only be done when the license server starts up, but the license server will notexit on detection of tampering. Only those license strings that specify they want the check will bedenied if tampering is detected. Other features will continue to be served by the license server. Even ifsomeone sets the clock back after starting the license server, and then dynamically adds a tamper-sen-sitive license string, the license server will detect it and throw the license string out. When the licenseserver accepts a license string at start-up but detects later that the clock has been set back, it does notgrant a license for the feature until the clock is reset to its correct value.

10.64.3. Returns




VLScg_INVALID_RANGE If value is not in the range allowed.


10.65. VLScgAllowOutLicType

10.65.1. Syntaxint VLScgAllowOutLicType (


codeT *codeP );




10.65.2. Returns


10.65. VLScgAllowOutLicType 387


10.66. VLScgSetOutLicType

10.66.1. Syntax int VLScgSetOutLicType (


codeT *codeP,

char *flag );





n VLScg_ENCRYPTED_STRING = “0”n VLScg_EXPANDED_READABLE_STRING = “1”n VLScg_CONCISE_READABLE_STRING = “2”


Controls the type of license string generated. License output formats can be: encrypted, expandedreadable, and concise readable.

The license code contains all of the information that defines the license agreement between you andyour customer: howmany users can run the application at a time, whether the license will expire aftera 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 byyour customers.

Concise readable license codes store information about the provisions of a licensing agreement inreadable form, such as plain text with white spaces so that it is easily read (and understood) by theuser.

The expanded readable license string, a string is appended to the numeric values to specify what thatnumeric value stands for, e.g., 60_MINS implies that 60 specifies the time in minutes. These strings donot appear in the concise format, only a 60 appears in the concise readable license string, as opposedto 60_MINS in the expandable readable format.

10.66.3. Returns




VLScg_INVALID_RANGE If value is not in the range allowed.


10.67. VLScgSetLicType

10.67.1. Syntaxint VLScgSetLicType (


codeT *codeP,

char *lictype );




lictype Set the type of license.

n VLScg_TRIAL_LIC_STRING = “1”n VLScg_NORMAL_LIC_STRING = “0”


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/1461days. Notice, trial licenses do not start until the first time the application is executed (as opposed tothe time that the application is installed).

10.67.3. Returns



VLScg_INVALID _LIC_TYPE If license type is not valid.


10.67. VLScgSetLicType 389


10.68. VLScgAllowHeldLic

10.68.1. Syntaxint VLScgAllowHeldLic (


codeT *codeP );




10.68.2. Returns


10.69. VLScgSetHoldingCrit

10.69.1. Syntaxint VLScgSetHoldingCrit (


codeT *codeP,

char *flag );




flag The flag is used to set the criteria for held licenses.Values are:

n VLScg_HOLD_NONE_STRING = “0” - Held licenses not allowed.n VLScg_HOLD_VENDOR_STRING = “1” - Client API specifies hold time.n VLScg_HOLD_CODE_STRING = “2” - License code specifies hold time.


This defines the criteria for determining the hold time for a license, and controls whether or not heldlicenses are allowed for this feature. Hold time provides a grace period after the license is released dur-ing which only the original license requestor will be granted the license. Validates and installs the valueof 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 errorcodes:



VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_HOLD_CODE_STRING.

VLScg_LESS_THAN_MIN_VALUE If the value is lower than VLScg_HOLD_NONE_STRING.


10.69. VLScgSetHoldingCrit 391


10.70. VLScgAllowCodegenVersion

10.70.1. Syntaxint VLScgAllowCodegenVersion (


codeT *codeP );




10.70.2. Returns


10.71. VLScgSetCodegenVersion

10.71.1. Syntaxint VLScgSetCodegenVersion (


codeT *codeP,

char *flag );




flag Sets the possible values for version_num flag.


Sets the version of license codes to generate. Checks if the current license code setting allowmultiplefeatures.

10.71.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds MAX_CODEGEN_VERSION.


10.71. VLScgSetCodegenVersion 393


10.72. VLScgAllowCapacityLic

10.72.1. Syntaxint VLScgAllowCapacityLic (


codeT *codeP );





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 Description

0 Capacity licensing is not allowed.

1 Capacity licensing is allowed.


10.73. VLScgSetCapacityFlag

10.73.1. Syntax int VLScgSetCapacityFlag (


codeT *codeP,

char *flag );




Flag The value of flag is used to set the capacity_flag of codeT struct. Legal values are-

n VLScg_CAPACITY_NONE_STRINGn VLScg_CAPACITY_NON_POOLED_STRINGn VLScg_CAPACITY_POOLED_STRING


Specifies whether the license is a capacity license or not. Also sets the appropriate fields of codeT struc-ture to make sure that it is:

n A normal license and not a trial license

n A network license and not a stand-alone license

n Not a held license

n Not a redundant license

n Not a commuter license

n License code format is “Encrypted” only.

10.73.3. Returns



VLScg_SUCCESS Success

VLScg_INVALID_INT_TYPE If value is not numeric

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_CAPACITY_POOLED


If value is lower than VLScg_CAPACITY_NONE


10.73. VLScgSetCapacityFlag 395


10.74. VLScgAllowCapacity

10.74.1. Syntaxint VLScgAllowCapacity (


codeT *codeP );





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 Description

0 It is a non-capacity license.

1 It is a capacity license.


10.75. VLScgSetCapacityUnits

10.75.1. Syntaxint VLScgSetCapacityUnits (


codeT *codeP,

char *units );




units Capacity specification units from 0 to 4. The values are:



10220000.

10.75.2. Definition

Sets the capacity_units field of codeT struct.

10.75.3. Returns



VLScg_SUCCESS Success.


VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_CAPACITY_UNITS_MAX_VALUE

VLScg_LESS_THAN_MIN_VALUE If value is less than VLScg_CAPACITY_UNITS_MIN_VALUE


10.75. VLScgSetCapacityUnits 397


10.76. VLScgSetCapacity

10.76.1. Syntaxint VLScgSetCapacity (


codeT *codeP,

char *capacity );




capacity Controls the capacity



10220000.

VLScg_NOLIMIT_STRING or EMPTY(“/0”) String can be used to specify infinite capac-ity.

10.76.2. Definition

Sets the capacity field of codeT struct.

10.76.3. Returns






VLScg_LESS_THAN_MIN_VALUE If value is lower than minimum.


10.77. VLScgAllowMultiKey

10.77.1. Syntaxint VLScgAllowMultiKey (


codeT *codeP );




10.77.2. Returns


10.77. VLScgAllowMultiKey 399


10.78. VLScgSetKeyType

10.78.1. Syntaxint VLScgSetKeyType(


codeT *codeP,

char *flag );




flag Flag used to set the code_typemember of codeT struct. The values are:

n VLScg_SINGLE_KEY_STRING = “0”n VLScg_MULTI_KEY_STRING = “1”


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 singlefeature. Notice, if you select Predefined-Single Feature, the feature namemust be no morethan 2 numeric digits. Most of the attributes are already defined for you and cannot bemod-ified.

n Multi Feature: Predefined short, numeric license types wheremultiple features (valuebetween 2 - 11) can be placed into a single license code. Notice, if you select Predefined-MultiFeature, the feature namemust be no more than 2 numeric digits. Most of the attributes arealready defined for you and cannot bemodified.

10.78.3. Returns




VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MULTI_KEY_STRING.


If value is lower than VLScg_SINGLE_KEY_STRING.


10.79. VLScgAllowSecrets

10.79.1. Syntaxint VLScgAllowSecrets (


codeT *codeP );




10.79.2. Returns


10.79. VLScgAllowSecrets 401


10.80. VLScgSetSecrets

10.80.1. Syntaxint VLScgSetSecrets (


codeT *codeP,

char *valu,

int num );




valu Any printable ASCII text.

num Number of secrets: should be from 0 to num_secrets -1. num is the position in thearray storing the secrets.The value varies from 0 to num_secrets-1, where num_secrets is set usingVLScgSetNumSecrets


Sets the value of the specified challenge-response secrets.

Both the application and the license contain data known as secrets. When an application wishes tochallenge, it generates a random text string, which is passed as the challenge value to the licenseserver. In response to this challenge value, the license server examines the software license to deter-mine the secret and computes the corresponding answer. The result is then passed back to the clientapplication as the response to the challenge.

The purpose of the challenge is to verify that there is a valid license present. Even a tampered licenseserver cannot respond correctly to the challenge.

10.80.3. Returns



VLScg_INVALID_CHARACTERS If string is not valid.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum. The value set by VLScgSet-NumSecrets



10.81. VLScgSetNumSecrets

10.81.1. Syntaxint VLScgSetNumSecrets (


codeT *codeP,

char *valu );




valu This value sets the number of secrets.


Sets the total number of secrets for the challenge-responsemechanism.

Up to seven secret text strings can be specified, each up to twelve characters long. The secrets areencrypted 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 con-firm its identity.

10.81.3. Returns



VLScg_INT_TYPE If value is not numeric.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAX_NUM_SECRETS.

VLScg_LESS_THAN_MIN_VALUE If value is lower than 0.


10.81. VLScgSetNumSecrets 403


10.82. VLScgAllowVendorInfo

10.82.1. Syntaxint VLScgAllowVendorInfo (


codeT *codeP );




10.82.2. Returns


10.83. VLScgSetVendorInfo

10.83.1. Syntaxint VLScgSetVendorInfo (


codeT *codeP,

char *pcPrivateVendorInfo );




pcPrivateVendorInfo Any printable ASCII text (see Reserved Characters and Strings). Max-imum of 2000 characters, except in case of redundant licenses, wherethe vendor information (both public and private) should not exceed 395characters. …


Sets the private vendor information to the value provided in a license. This function also sets the pub-lic vendor information to blank.

The private vendor information will remain encrypted in a license code and can be retrieved through aclient library function call. You may use it for keeping track of distributors or implementing a variety oflicensing schemes.

See VLScgAllowVendorInfoExt and VLScgSetVendorInfoExt for setting both the private and public infor-

mation in a license code. The public information can be read by customers (if the licenses are defined as

readable).

10.83.3. Returns



VLScg_INVALID_CHARS If string is not valid.





10.83. VLScgSetVendorInfo 405


10.84. VLScgAllowVendorInfoExtVerifies whether setting private vendor information and public vendor information is allowed for codetype 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. Syntaxint VLScgAllowVendorInfoExt (


codeT *codeP );




10.84.2. Returns

The API returns 1, if private vendor information and public vendor information is allowed to set, else itreturns 0.

10.85. VLScgSetVendorInfoExt

10.85.1. Syntaxint VLScgSetVendorInfoExt (


codeT *codeP,

char *pcPrivateVendorInfo,

char *pcPublicVendorInfo );




pcPrivateVendorInfo Any printable ASCII text. Maximum of 2000 characters. This valueappears as encrypted string in the license code.

pcPublicVendorInfo Any printable ASCII text (see Reserved Characters and Strings). Max-imum of 395 characters. This value appears as unencrypted string inthe license code.

In case of redundant licenses, the vendor information (both public

and private) should not exceed 395 characters.


Sets private vendor information and public vendor information in a license code. These values, passedas pcPrivateVendorInfo and pcPublicVendorInfo are set in the vendor_info and plain_vendor_infomembers, respectively, of the passed codeT structure.

The VLScgAllowVendorInfoExt API function must be called before calling this API to ensure that settingprivate 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



VLScg_INVALID_INPUT Argument specified is not correct. Can be because:

n codeP is NULL.

10.85. VLScgSetVendorInfoExt 407



n PcPrivateVendorInfo or pcPublicVendorInfo isNULL.

n If the API is called for licenses earlier than version11.

VLScg_EXCEEDS_MAX_STRLEN Length of the input string exceeds themaximum limit.

VLScg_RESERV_STR_ERR The input string is a reserved word.

VLScg_INVALID_CHARS The input string is invalid.



10.86. VLScgAllowKeysPerNode

10.86.1. Syntaxint VLScgAllowKeysPerNode (


codeT *codeP );




10.86.2. Returns


10.86. VLScgAllowKeysPerNode 409


10.87. VLScgSetKeysPerNode

10.87.1. Syntaxint VLScgSetKeysPerNode (


codeT *codeP,

char *keys,

int num );




keys Used to set the number of keys per node. Give any decimal value. Should be from0. Give VLScg_NOLIMIT_STRING for no limit.

num Position of client in the array of clients: should be from 0 to themaximumnumber of clients -1.


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 com-puter is controlled. This is an extra per-host restriction in addition to the overall number of licenses.

10.87.3. Returns



VLScg_INVALID_INT_TYPE If number is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE If number is greater than num_nl_clients -1. num_nl_clients is afield of CodeT structure storing the number of clients.

VLScg_LESS_THAN_MIN_VALUE If number is less than 0.


10.88. VLScgAllowSiteLic

10.88.1. Syntaxint VLScgAllowSiteLic (


codeT *codeP );




10.88.2. Returns


10.88. VLScgAllowSiteLic 411


10.89. VLScgSetSiteLicInfo

10.89.1. Syntaxint VLScgSetSiteLicInfo (


codeT *codeP,

char *info,

int num );




info Set the subnet address. You can use wildcard (e.g., *.123.*.28) to specify a range.

num num is the position of subnet in the array maintaining the subnet info.The valuevaries from 0 to num_subnets-1where num_subnets is an element of CodeT structset using VLScgSetNumSubnets.


Sets subnet address.

Specifies the number of subnets used for site licensing.

10.89.3. Returns



VLScg_INVALID_RANGE If value is not in the range allowed and if value is not a valid char-acter.


10.90. VLScgSetNumSubnets

10.90.1. Syntaxint VLScgSetNumSubnets (


codeT *codeP,

char *info );




info Sets the number of subnets: Should be from 1 to VLScg_MAX_NUM_SUBNETSwhose value is 7. 0 is a special value which means no site licensing.


Sets the number of subnets the licensed application can run on. To set actual site addresses, useVLScgSetSiteLicInfo*.

10.90.3. Returns



VLScg_INVALID_INT_TYPE If input is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE If num is greater than codeP to num_subnets.

VLScg_LESS_THAN_MIN_VALUE If num is less than 0.


10.90. VLScgSetNumSubnets 413


10.91. VLScgAllowMultipleFeature

10.91.1. Syntaxint VLScgAllowMultipleFeature (


codeT *codeP );




10.91.2. Returns


10.92. VLScgSetNumFeatures

10.92.1. Syntaxint VLScgSetNumFeatures (


codeT *codeP,

char *flag );




flag Sets the flag for number of features in case ofmulti-feature.


Sets the number of features.

10.92.3. Returns



VLScg_INVALID_INT_TYPE If input is not a decimal number.

VLScg_EXCEEDS_MAX_VALUE If value exceeds VLScg_MAX_NUM_FEATURES.

VLScg_LESS_THAN_MIN_VALUE If value is lower than VLScg_MIN_NUM_FEATURES.


10.92. VLScgSetNumFeatures 415


10.93. VLScgAllowSoftLimit

10.93.1. Syntaxint VLScgAllowSoftLimit (


codeT *codeP );




10.93.2. Returns


10.94. VLScgSetSoftLimit

10.94.1. Syntaxint VLScgSetSoftLimit (


codeT *codeP,

char *info );




info Sets soft limit: should be from 0 to VLScg_NOLIMIT_STRING for no limit. VLScg_NOL-IMIT_STRING is not allowed if the license is a commuter license.


The soft limit number defines a threshold at which a warning can be issued that themaximum numberof licenses is being approached. Must be less than themaximum number of users (the hard limit).

10.94.3. Returns



VLScg_INVALID_INT_TYPE If information is not a non-negative integer.

VLScg_EXCEEDS_MAX_VALUE If information exceeds maximum number of license tokensallowed. Maximum value for long codes is 32766 and maximumvalue for short codes is 254.

VLScg_LESS_THAN_MIN_VALUE If information is less than 0.


10.94. VLScgSetSoftLimit 417


10.95. VLScgAllowKeyLifeUnits

10.95.1. Syntaxint VLScgAllowKeyLifeUnits (


codeT *codeP );




10.95.2. Returns


10.96. VLScgSetKeyLifetimeUnits

10.96.1. Syntaxint VLScgSetKeyLifetimeUnits (


codeT *codeP,

char *info );




info Lifetime specification units of license tokens: from 0 to 3. The values are:

n “0” -Multiple of 1minute(s), maximum 15minutes.n “1” -Multiple of 10minute(s), maximum 150minutes.n “2” -Multiple of 30minute(s), maximum 450minutes.n “3” -Multiple of 60minute(s), maximum 900minutes.


This function specifies the units of time used to specify the time between renewals. A licensemust berenewed by the application on a regular schedule or the license will be reclaimed.VLScgAllowKeyLifetime

10.96.3. Returns







10.96. VLScgSetKeyLifetimeUnits 419


10.97. VLScgAllowKeyHoldUnits

10.97.1. Syntaxint VLScgAllowKeyHoldUnits (


codeT *codeP );




10.97.2. Returns


10.98. VLScgSetKeyHoldtimeUnits

10.98.1. Syntaxint VLScgSetKeyHoldtimeUnits (


codeT *codeP,

char *info );




info Hold time specification units of license tokens: from 0 to 3. The values are:

n “0” -Multiple of 1minute(s), maximum 15minutesn “1” -Multiple of 10minute(s), maximum 150minutes.n “2” -Multiple of 30minute(s), maximum 450minutes.n “3” -Multiple of 60minute(s), maximum 900minutes.


Network licenses may be held for a timewhen released by a specific user. During that time only theoriginal requestor of the license can be granted the license again. This function sets the units of timeused to specify the hold time.

10.98.3. Returns







10.98. VLScgSetKeyHoldtimeUnits 421


10.99. VLScgAllowKeyHoldtime

10.99.1. Syntaxint VLScgAllowKeyHoldtime (


codeT *codeP );




10.99.2. Returns


10.100. VLScgSetKeyHoldtime

10.100.1. Syntaxint VLScgSetKeyHoldtime (


codeT *codeP,

char *info );




info Absolute values in minutes. Maximum depends on units set by VLScgSet-KeyHoldtimeUnits. VLScg_NOLIMIT_STRING sets hold time to 900minutes.


Network licenses may be held for a timewhen released by a specific user. During that time only thatuser 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





VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed hold time.



10.100. VLScgSetKeyHoldtime 423


10.101. VLScgAllowLicBirth

10.101.1. Syntaxint VLScgAllowLicBirth (


codeT *codeP );




10.101.2. Returns


10.102. VLScgSetLicBirthMonth

10.102.1. Syntaxint VLScgSetLicBirthMonth (


codeT *codeP,

char *info );




info Sets themonth of year to 1-12 or Jan-Dec.


Sets themonth of the license start date. The license start month should be specified in the range of 0-11. VLScgSetLicBirthMonth is not applicable if year is infinite.

10.102.3. Returns



VLScg_INVALID_CHARACTERS If not a valid string.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed month (exceeds 12).



10.102. VLScgSetLicBirthMonth 425


10.103. VLScgSetLicBirthDaySets the day of the license start date.

10.103.1. Syntaxint VLScgSetLicBirthDay (


codeT *codeP,

char *info );




info Sets the day of themonth (1-31).


Sets the day of the license start date. Not applicable if year has been set to infinite.

10.103.3. Returns




VLScg_INVALID_DATE If value is not valid for themonth.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed day.



10.104. VLScgSetLicBirthYear

10.104.1. Syntaxint VLScgSetLicBirthYear (


codeT *codeP,

char *info );




info Enter year in 4 digits (e.g., 2003) to avoid year 2000 problem.


Sets the year of the license start date. Not applicable if year is infinite.

10.104.3. Returns




VLScg_INVALID_YEAR If year is invalid.

VLScg_INVALID_BIRTH_YEAR If year is less than 2003.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed year that is 2130.


10.104. VLScgSetLicBirthYear 427


10.105. VLScgAllowLicExpiration

10.105.1. Syntaxint VLScgAllowLicExpiration (


codeT *codeP );




10.105.2. Returns


10.106. VLScgSetLicExpirationMonth

10.106.1. Syntaxint VLScgSetLicExpirationMonth (


codeT *codeP,

char *info );




info Sets themonth of year: 1 -12 or Jan.-Dec.


Sets month of date license expires. The license expiration month should be specified in the range of 1-12. VLScgSetLicExpirationMonth is not applicable if year is infinite.

10.106.3. Returns



VLScg_INVALID_CHARACTERS If not a valid string.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed month (exceeds 12).



10.106. VLScgSetLicExpirationMonth 429


10.107. VLScgSetLicExpirationDay

10.107.1. Syntaxint VLScgSetLicExpirationDay (


codeT *codeP,

char *info );




info Sets the day of themonth: 1-31.


Sets the day of themonth of the date on which the license expires. No need to set if the year is infinite.

10.107.3. Returns




VLScg_INVALID_DATE If value is not valid for themonth.

VLScg_EXCEEDS_MAX_VALUE If value exceeds maximum allowed day.



10.108. VLScgSetLicExpirationYear

10.108.1. Syntaxint VLScgSetLicExpirationYear (


codeT *codeP,

char *info );




info Enter year in 4 digits (e.g., 2008). Use the VLScg_NEVER_STRINGmacro (defined inlscgen.h) for infinite expiration.


Sets the year of the date that the license expires.

10.108.3. Returns




VLScg_INVALID_YEAR If the year is invalid.

VLScg_INVALID_DEATH_YEAR If year is less than 2003.



10.108. VLScgSetLicExpirationYear 431


10.109. VLScgSetNumericType

10.109.1. Syntaxint VlScgSetNumericType (


codeT *codeP,

int num );




num Numeric type values are:

n VLScg_NUMERIC_UNKNOWN= “0”n VLScg_NOT_NUMERIC = “1”n VLScg_MISC_SHORT_NUMERIC = “2”n VLScg_MISC_NUMERIC = “3”


Sets the value codeP->numeric_type to the value of num and Checks the user input and saves thevalue in code struct.

10.109.3. Returns



VLScg_EXCEEDS_MAX_VALUE Value exceeds themaximum value of 3.


VLScg_INVALID_INT_TYPE If the value is not a non-negative integer.


10.110. VLScgSetLoadSWLicFile

10.110.1. Syntaxint VLScgSetLoadSWLicFile (


char *filename );



filename Complete name and path of sw license file.


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 returnedindicating the reason for failure. For a complete list of the error codes, see License Generation ErrorCodes.

10.110. VLScgSetLoadSWLicFile 433


10.111. VLScgAllowGracePeriodFlag

10.111.1. Syntaxint VLScgAllowGracePeriodFlag (


codeT *codeP );




10.111.2. Returns


10.112. VLScgSetGracePeriodFlag

10.112.1. Syntaxint VLScgSetGracePeriodFlag (


codeT *codeP,

char *flag );



codeP A pointer to the codeT structure.

flag A flag that will decide whether the VLScgAllowGracePeriod should be called ornot. The value can be:

n VLScg_NO_GRACE_PERIODn VLScg_STANDARD_GRACE_PERIOD


Sets the grace period flag value.

10.112.3. Returns


10.112. VLScgSetGracePeriodFlag 435


10.113. VLScgAllowGracePeriod

10.113.1. Syntaxint VLScgAllowGracePeriod (

VLScg_HANDLE iHandle,codeT *codeP );




10.113.2. Returns


10.114. VLScgSetGracePeriodDays

10.114.1. Syntaxint VLScgSetGracePeriodDays (


codeT *codeP,

char *calendar_daysStr );




calendar_daysStr The number of days the license can be used in the grace period.


Sets the number of calendar days the license can be used in the grace period.

10.114.3. Returns


10.114. VLScgSetGracePeriodDays 437


10.115. VLScgSetGracePeriodHours

10.115.1. Syntaxint VLScgSetGracePeriodHours (


codeT *codeP,

char *elapsed_hoursStr );




elapsed_hoursStr The number of hours the license can be used in the grace period.


Sets the number of elapsed hours the license can be used in a grace period.

10.115.3. Return


10.116. VLScgAllowLocalRequestLockCritFlag

10.116.1. Syntaxint VLScgAllowLocalRequestLockCritFlag (


codeT *codeP );




10.116.2. Returns


10.116. VLScgAllowLocalRequestLockCritFlag 439


10.117. VLScgSetLocalRequestLockCritFlag

10.117.1. Syntaxint VLScgSetLocalRequestLockCritFlag (


codeT *codeP,

char *str );




str The locking criteria, which can have any of the following values:

n VLScg_LOCAL_REQUEST_LOCKCRIT_USEDEFAULT_STRING: Refers to thedefault criteria.

n VLScg_LOCAL_REQUEST_LOCKCRIT_DEFINED_STRING: Refers to a user-defined criteria.


Sets the locking criteria as default or user-defined.

10.117.3. Returns


10.118. VLScgAllowLocalRequestLockCrit

10.118.1. Syntaxint VLScgAllowLocalRequestLockCrit (


codeT *codeP );




10.118.2. Returns


10.118. VLScgAllowLocalRequestLockCrit 441


10.119. VLScgSetLocalRequestLockCrit

10.119.1. Syntax int VLScgSetLocalRequestLockCrit (


codeT *codeP,

char *str );




str Allows setting the required, floating, and minimum required locking criteria forthe local request. For example, 0x4:0x3FF:2 will set:

n 0x4 as the required locking criteria.n 0x3FF as the floating locking criteria.n 2 as theminimum locking criteria.


Sets the required, floating, and minimum required locking criteria for the local request.

10.119.3. Returns


10.120. VLScgAllowVmDetection

10.120.1. Syntaxint VLScgAllowVmDetection (


codeT *codeP );

Argument DescriptioniHandle The instance handle for this library.


10.120.2. Returns


10.120. VLScgAllowVmDetection 443


10.121. VLScgSetVmDetection

10.121.1. Syntaxint VLScgSetVmDetection (


codeT *codeP,

char *vmDetectionStr );

ArgumentDirection

DataType

Description

iHandle IN VLScg_HANDLE

The instance handle for this library.

codeP IN codeT The pointer to the codeT struct.

vmDetectionStr IN char This buffer is used to set the virtual machine detec-tion flag for clients. Valid values are:

n VLScg_VM_ALLOWED_STRING - Issue licensetoken on virtual machine detection = “0”

n VLScg_VM_DISALLOWED_STRING - Do notissue license token on virtual machine detec-tion = “1”


Sets the action on detection of a virtual machine—whether to allow\deny grant of a license token.

This check will only be done when the license server starts up, but the license server will not exit ondetection of a virtual machine on the host. Only those license strings that disallow license use in caseof VM detection will be denied.

10.121.3. Returns


ErrorCode

Description

VLScg_INVALID_INPUT

If value is not any one of the above defined flags.


10.122. VLScgValidateCodeT

10.122.1. Syntax int VLScgValidateCodeT


codeT *codeP);





Validates fields value of the codeT structure. Call this API with the filled codeT structure. It comparesCodeT 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 theactual point of failure. For a complete list of the error codes, see License Generation Error Codes.

10.122. VLScgValidateCodeT 445


The License Generation FunctionThe following table summarizes the license generation function:


VLScgGenerateLicense Generates the license string.

10.123. VLScgGenerateLicense

10.123.1. Syntaxint VLScgGenerateLicense (


codeT *codeP,

char **result );




result Address of pointer pointing to generated license string.


This function generates the license string for the given codeT struct. It should be called after all theVLScgSet functions are called. Memory allocation and deallocation for codeT are the responsibilities ofthe caller of function.

Memory allocation for the license string is handled by this function. Its address is to be passed by thecaller of this function in the second argument.

10.123.3. Returns



VLScg_INVALID_VENDOR_CODE If vendor identification is illegal.

VLScg_VENDOR_ENCRYPTION_FAIL


VLScg_LICMETER_NOT_ SUP-PORTED



10.123. VLScgGenerateLicense 447


License Hash and Decode FunctionsThe following table summarizes the license hash and decode functions:


VLScgCalculateLicenseHash Calculates the license hash.

VLScgDecodeLicense Decodes the license string.

VLScgDecodeLicenseExt Decodes the license string. The user needs to allocatememory.

10.124. VLScgCalculateLicenseHash

10.124.1. Syntaxint VLScgCalculateLicenseHash (

char *pcLicenseString,

unsigned char *pucLicenseHash,

int *piLicenseHashLength );

ArgumentDirection

DataType

Description

pcLicenseString IN char A pointer to the license stringwhose hash is to be calculated.

pucLicenseHash OUT unsignedchar

A pointer to the location where thelicense hash is to be stored.If the value passed is NULL, therequired length for this buffer isreturned to the third argument piL-icenseHashLength.

piLicenseHashLength IN/OUT int The length of the hash buffer. Userneeds to allocatememory.


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

Tip

Make sure you pass a valid license str ing for calculating license hash. You can useVLScgDecodeL icense\VLScgDecodeL icenseExt to ver ify the license str ing's validity.

10.124.3. Returns



VLScg_INVALID_INPUT One or more input parameters are invalid.

VLScg_BUFFER_TOO_SMALL If the input size of the buffer specified for storing hash issmaller than required.


10.124. VLScgCalculateLicenseHash 449


10.125. VLScgDecodeLicense

10.125.1. Syntaxint VLScgDecodeLicense (


char *AnyLicenseString,

char *lic_string,

int lic_string_length,

codeT **codeP );



any_license_string User-provided license string to be decoded.

license_string User allocated buffer to receive decoded license string. An OUT parameter.

license_string_buflen Length of decoded license string returned.

codeP Pointing to codeT containing input license string.


The library can call the API VLScgDecodeLicense without requiring the licensemeter

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 thelast argument. Pointer to codeT struct is to be passed as the last argument. This pointer will containthe codeT corresponding to AnyLicenseString.

When decoding a license via the VLScgDecodeLicense API function, the codeT structure returned does not

contain the license secrets—instead the corresponding field contains an empty string.

10.125.3. Returns



VLScg_INVALID_VENDOR_CODE If vendor identification is illegal.




VLScg_MALLOC_FAILURE Out of heap memory.

VLScg_SHORT_STRING License string too small to parse.

VLScg_PREMATURE_TERM Premature termination of license string. Please check.

VLScg_INVALID_CHARS String is not valid.

VLScg_EXCEEDS_MAX_STRING Length of the string is greater than the defined limit.

VLScg_REMAP_DEFAULT Failed to remap default strings from configuration file forlicense.

VLScg_DECRYPT_FAIL Decryption failed for license code.

VLScg_INVALID_CHKSUM Checksum validation failed for license string.

VLScg_FIXED_STR_ERROR Default fixed string error.

VLScg_INVALID_RANGE Value violates the valid range of input.

VLScg_INVALID_INPUT Invalid input.

VLScg_INVALID_INT_TYPE Value is not numeric.

VLScg_LESS_THAN_MIN_VALUE Value entered is less than theminimum supported value.

VLScg_LESS_THAN_MAX_VALUE Value entered is greater than themaximum supported value.

VLScg_INVALID_HEX_TYPE Wrong value entered. (Should be hexadecimal).

VLScg_SECRET_DECRYPT_FAILURE Decryption failed for secrets. Verify the configuration file forreadable licenses.

VLScg_SIMPLE_ERROR Error in license string. Please check.


10.125. VLScgDecodeLicense 451


10.126. VLScgDecodeLicenseExt

10.126.1. SyntaxLS_STATUS_CODE VLScgDecodeLicenseExt (

VLScg_HANDLE handle,

char *any_license_string,

char *license_string,

int *license_string_buflen,

codeT *codeP );



any_license_string User-provided license string to be decoded.

license_string User allocated buffer to receive decoded license string. An OUT parameter.

license_string_buflen Length of decoded license string returned.

codeP Pointing to codeT containing input license string. You will need to allocatememory for the codeT structure.


This API function decodes the license code passed as any_license_string and places the correspondingcodeT structure in the codeP argument. The prototype of this function is defined in the lscgen.h (inWindows platform) and lsdecode.h (in UNIX platform) header file.

To decode a license, first call the VLScgInitialize API to allocate resources required for decoding alicense. Then, call VLScgDecodeLicenseExt API to decode the license. And then, call VLScgCleanup APIto clean up the resources created by VLScgInitialize API.

When decoding a license via the VLScgDecodeLicenseExt API function, the codeT structure returned does

not contain the license secrets—instead the corresponding field contains an empty string.

10.126.3. Returns



VLScg_INVALID_INPUT Argument specified is not correct, that is, one of the followingreasons exist:

n any_license_string or CodeP is NULLn If license_string is not NULL and license_string_buflen

is NULL.


n If license_string is not NULL and license_string_buflen is<= 0

n If any_license_string buffer size exceeds themaximumsize limit specified as VLS_MAX_LICENSE_SIZE.

VLScg_DECRYPT_FAIL This error code indicates that the API has failed to decode thespecified license due to invalid license signature. The licensesignature refers to the authentication string passed alongwith the license string.

VLS_CALLING_ERROR The argument specified is not correct.


LS_BUFFER_TOO_SMALL Allocated buffer is insufficient for this API.


Error occurs if vendor-customized encryption fails.

VLScg_MALLOC_FAILURE Out of heap memory.

VlsCG_SHORT_STRING Error occurs when the license code too small to parse.

VLScg_PREMATURE_TERM Premature termination of license code.

VLScg_INVALID_CHARS String is not valid.

VLScg_FIXED_STR_ERROR Default fixed string error.

VLScg_INVALID_RANGE Value violates the valid range of input.

VLScg_SIMPLE_ERROR Error in license code.


10.126. VLScgDecodeLicenseExt 453


License Meter Related FunctionsThe following table summarizes the licensemeter related functions:


VLScgGetLicenseMeterUnits Returns the number of license generation units.

VLScgGetTrialLicenseMeterUnits Returns the number of trial license generation units.

10.127. VLScgGetLicenseMeterUnits

10.127.1. Syntaxint VLScgGetLicenseMeterUnits (


long *initialUnitsP,

long *unitsLeftP,

int codegen_version );



initialUnitsP The number of units that were initially available.

unitsLeftP The number of units remaining.

codegen_version Version of the code generator (7 for Sentinel RMS Development Kit 7.x and 8for Sentinel RMS Development Kit 7.3.0 and greater).


Returns the number of license generation units available in the attached licensemeter key.

10.127.3. Returns



VLScg_LICMETER_EXCEPTION Unknown value in accessing the licensemeter.

VLScg_LICMETER_ACCESS_ERROR

Error accessing the licensemeter.

VLScg_LICMETER_CORRUPT Licensemeter is corrupted.

VLScg_LICMETER_VERSION_MIS-MATCH

Licensemeter has an invalid version.

VLScg_LICMETER_NOT_ SUP-PORTED



On platforms that do not support hardware keys, the function returns V_FAIL.

10.127. VLScgGetLicenseMeterUnits 455


10.128. VLScgGetTrialLicenseMeterUnits

10.128.1. Syntaxint VLScgGetTrialLicenseMeterUnits (


int units,

int codegen_version );



units The number of licenses available.

codegen_version Version of the code generator (7 for Sentinel RMS 7.x and 8 for Sentinel RMS7.3.0 and greater).


Returns the number of trial license generation units available in the attached licensemeter.

10.128.3. Returns


License Revocation FunctionsGiven below is a list of the API functions:


VLSgeneratePermissionTicket Generates a permission ticket for stand-alone licensesonly.

VLSgeneratePermissionTicketExt Generates a permission ticket for stand-alone and net-work licenses.

VLSverifyRevocationTicket Verifies the returned revocation ticket with the originalrequest for stand-alone licenses only.

VLSverifyRevocationTicketExt Verifies the returned revocation ticket with the per-mission ticket (whether passed as a request structure oras binary data) for stand-alone and network licenses.

VLScgDecodeLicenseRevocationTicket Decodes the license revocation ticket (LRT) generated thepre 8.4.1 network revocation workflow.

VLScgDecodeLicenseRevocationTicketExt Decodes all types of revocation tickets.

License Revocation Functions 457


10.129. VLSgeneratePermissionTicket

10.129.1. SyntaxLS_STATUS_CODE VLSgeneratePermissionTicket (

PVPT_REQUEST pvRequest,


unsigned int *pui16PermissionTicketLength );


pvRequest An IN parameter. A pointer to the structure containingrequest data.

pucPermissionTicket An OUT parameter. A pointer to the generated permissionticket. Thememory needs to be allocated by the caller.

pui16PermissionTicketLength An IN/OUT parameter. The length of the generated per-mission ticket.


This function is used to generate a permission ticket for stand-alone license revocation/addition thatcan be processed on the client side. You can create a customized application that calls this API func-tion 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 gen-erated permission ticket, the function will return the required length. The caller needs to allocate therequired 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, itwill return the following error codes:


VLScg_RT_INVALID_REQUEST_DATA The requested data is invalid.

VLScg_RT_UNSUPPORTED_OPERATION_TYPE The operation type is not 'A' or 'R'.

VLScg_RT_BUFFER_TOO_SMALL The allocated memory is not enough.

VLScg_RT_PARAMETERS_ERROR Invalid rehost parameters.

VLScg_RT_ALLOCATE_MEMORY_FAILURE Failure in memory allocation.

10.130. VLSgeneratePermissionTicketExt

10.130.1. SyntaxLS_STATUS_CODE VLSgeneratePermissionTicketExt (

PVPT_REQUEST pvRequest,


unsigned int *pui16PermissionTicketLength,

PVPT_REQUEST_EXT pvRequestExt );


pvRequest An IN parameter. A pointer to the structure containing requestdata.

pucPermissionTicket An OUT parameter. A pointer to the generated permission ticket.Thememory needs to be allocated by the caller.

pui16PermissionTicketLength An IN/OUT parameter. The length of the generated permissionticket.

pvRequestExt An IN parameter. A pointer to the structure containing requestdata.


This function is used to generate a permission ticket for:

n Network license revocation for processing on the license server.

n Stand-alone license revocation/addition that can be processed on the client side.

You can create a customized application that calls this API function.

If the pucPermissionTicket argument is passed as NULL or its length is less than the length of the gen-erated permission ticket, the function will return the required length. The caller needs to allocate therequired 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, itwill return the following error codes:


VLScg_RT_INVALID_REQUEST_DATA The requested data is invalid.

VLScg_RT_UNSUPPORTED_OPERATION_TYPE n The operation type is not 'A' or 'R' forstand-alone licenses.

n The operation type is not 'P' or 'R' fornetwork licenses.

VLScg_RT_BUFFER_TOO_SMALL The allocated memory is not enough.


10.130. VLSgeneratePermissionTicketExt 459




VLScg_RT_INSUFFICIENT_TOKENS_TO_REVOKE The license tokens available for revocationare less than the number specified in therequest structure.

VLScg_RT_MIXED_OPERATION_TYPE_UNSUP-PORTED

You cannot revoke stand-alone and networklicenses using a single permission ticket.

VLScg_RT_INFINITE_LIC_FINITE_REQ Network licenses with infinite tokens cannotbe partially revoked. Full revocation isrequired.

VLScg_RT_RDNT_LIC_UNSUPPORED The permission ticket cannot be generatedfor redundant licenses.

VLScg_TOO_MANY_OPERATIONS_FOR_SINGLE_PT The number of operations specified in thepermission ticket exceed themaximum limit.You cannot specify more than 15 operationsin a permission ticket for a network license.

VLScg_VENDOR_ID_MISMATCH Vendor ID mismatch. The permission ticketcannot be generated for licenses of othervendors.

VLScg_CODGEN_VERSION_UNSUPPORTED The permission ticket generation not sup-ported for licenses earlier than version 11.

10.131. VLSverifyRevocationTicket

10.131.1. SyntaxLS_STATUS_CODE VLSverifyRevocationTicket (

PVPT_REQUEST pvOriginalRequest,


unsigned long ulRevocationTicketLength,

PVRT_VERIFY_ERRORS pvErrorInfo,

unsigned long *pulErrorInfoTotalLength );


pvOriginalRequest An IN parameter. A pointer to the structure containing datafor the original request.

pucRevocationTicket An IN parameter. A pointer to the returned revocationticket.

ulRevocationTicketLength An IN parameter. The length of the revocation ticket.

pvErrorInfo An OUT parameter. A pointer to the structure to store theerror report. Thememory needs to be allocated by thecaller.

pulErrorInfoTotalLength An IN/OUT parameter. The size of the pvErrorInfo argu-ment.


This function verifies the returned stand-alone revocation ticket with the original request described inthe permission ticket. You can create a customized application that calls this API function when a cus-tomer sends the revocation request.

If the pvErrorInfo argument is passed as NULL or the length is less than the size required for the errorreport, the function will return the required length. The caller needs to allocate the required memoryand 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 willreturn the following error codes:




10.131. VLSverifyRevocationTicket 461



VLScg_RT_VERSION_MISMATCH Rehost ticket version mismatch.

VLScg_RT_REHOST_LINE_CORRUPT Rehost ticket line is corrupt.

VLScg_RT_TRANSACTION_ID_MISMATCH Transaction Id in rehost ticket is different from inrequest.

VLScg_RT_LOCK_CODE_MISMATCH Lock code in rehost ticket is different from inrequest.

VLScg_RT_REQUESTED_ACTION_NOT_PER-FORMED

Actions requested are not performed.

VLScg_RT_NON_REQUESTED_ACTION_PER-FORMED

Action performed was not requested.

VLScg_RT_ACTION_STATUS_NOT_SUCCESS Requested action failed.

VLScg_RT_REQUEST_EMPTY Request is empty.

VLScg_RT_REQUEST_LINE_INVALID Requested line is invalid.

VLScg_RT_REHOST_TICKET_INVALID_TLV_STRUCT

Rehost ticket is an invalid TLV (Tag-Length-Value)structure.

VLScg_RT_REHOST_TAG_MISSING Rehost tag is missing in the rehost ticket.

VLScg_RT_VERSION_TAG_MISSING Version tag is missing in the rehost ticket.

VLScg_RT_TRANSACTION_ID_TAG_MISSING Transaction Id tag is missing in the rehost ticket.

VLScg_RT_LOCK_SELECTOR_TAG_MISSING Lock selector tag is missing in the rehost ticket.

VLScg_RT_LOCK_SELECTOR_MISMATCH Lock selector is different from in request.

VLScg_RT_LOCK_CODE_TAG_MISSING Lock code is different from in request.

VLScg_RT_HASH_TAG_MISSING Hash tag is missing in the rehost ticket.

VLScg_RT_VERIFY_SINGLE_ERROR Only one error in rehost ticket. Verify if the oper-ation type is specified as NULL.

VLScg_RT_VERIFY_MULTIPLE_ERRORS Multiple errors in rehost ticket.

VLScg_RT_TIME_STAMP_MISMATCH Mismatch in time stamp.

VLScg_RT_TIME_STAMP_TAG_MISSING Mismatch in time stamp tag.

10.132. VLSverifyRevocationTicketExt

10.132.1. SyntaxLS_STATUS_CODE VLSverifyRevocationTicketExt (

PVPT_REQUEST_EXT pvOriginalRequestExt,


unsigned long ulPermissionTicketLength,


unsigned long ulRevocationTicketLength,

PVRT_VERIFY_ERRORS pvErrorInfo,

unsigned long *pulErrorInfoTotalLength,



pvOriginalRequestExt An IN parameter. A pointer to the structure containing datafor the original request. Specify NULL if passing permissionticket in binary format.

pucPermissionTicket An IN parameter. A pointer to the permission ticket (inbinary format). Specify NULL if passing permission ticket asa structure.

ulPermissionTicketLength An IN parameter. The length of the permission ticket. Spec-ify 0 if the permission ticket request structure is passed.

pucRevocationTicket An IN parameter. A pointer to the returned revocationticket.

ulRevocationTicketLength An IN parameter. The length of the revocation ticket.

pvErrorInfo An OUT parameter. A pointer to the structure to store theerror report. Thememory needs to be allocated by thecaller.

pulErrorInfoTotalLength An IN/OUT parameter. The size of the pvErrorInfo argu-ment.

unused Reserved for future use.


This function is an extended version of VLSverifyRevocationTicket.

The VLSverifyRevocationTicketExt API verifies the returned revocation ticket with the original requestdescribed 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 VLSver-ifyRevocationTicket) or directly in the format it is generated (binary format).

In case, the revocation ticket contains any status—other than success—then the field pucLicenseLineof structure PVRT_VERIFY_ERROR_LINE will contain a license line only if:



n A stand-alone revocation ticket was passed.

n Or, a network revocation ticket was verified against the original structure of a permissionticket.

Else, the field pucLicenseLinewill contain license hash, feature, and version information.

You can create a customized application that calls this API function when a customer sends the rev-ocation request.

If the pvErrorInfo argument is passed as NULL or the length is less than the size required for the errorreport, the function will return the required length. The caller needs to allocate the required memoryand 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 willreturn the following error codes:




VLScg_RT_VERSION_MISMATCH Revocation ticket version mismatch.

VLScg_RT_REHOST_LINE_CORRUPT Revocation ticket line is corrupt.

VLScg_RT_TRANSACTION_ID_MISMATCH Transaction ID in revocation ticket is different fromin request.

VLScg_RT_LOCK_CODE_MISMATCH Lock code in revocation ticket is different from inrequest.

VLScg_RT_REQUESTED_ACTION_NOT_PER-FORMED

Actions requested are not performed.

VLScg_RT_NON_REQUESTED_ACTION_PER-FORMED

Action performed was not requested.

VLScg_RT_ACTION_STATUS_NOT_SUCCESS Requested action failed.

VLScg_RT_REQUEST_EMPTY Request is empty.

VLScg_RT_REQUEST_LINE_INVALID Requested line is invalid.

VLScg_RT_REHOST_TICKET_INVALID_TLV_STRUCT

Revocation ticket is an invalid TLV (Tag-Length-Value) structure.

VLScg_RT_REHOST_TAG_MISSING Rehost tag is missing in the revocation ticket.

VLScg_RT_VERSION_TAG_MISSING Version tag is missing in the revocation ticket.

VLScg_RT_TRANSACTION_ID_TAG_MISSING Transaction ID tag is missing in the revocationticket.


VLScg_RT_LOCK_SELECTOR_TAG_MISSING Lock selector tag is missing in the revocation ticket.

VLScg_RT_LOCK_SELECTOR_MISMATCH Lock selector is different from in request.

VLScg_RT_LOCK_CODE_TAG_MISSING Lock code is different from in request.

VLScg_RT_HASH_TAG_MISSING Hash tag is missing in the revocation ticket.

VLScg_RT_VERIFY_SINGLE_ERROR Only one error in revocation ticket. Verify if theoperation type is specified as NULL.

VLScg_RT_VERIFY_MULTIPLE_ERRORS Multiple errors in revocation ticket.

VLScg_RT_TIME_STAMP_MISMATCH Mismatch in time stamp.

VLScg_RT_TIME_STAMP_TAG_MISSING Mismatch in time stamp tag.

VLScg_RT_CORRUPT_ORIG_REQ The permission ticket provided for verification iscorrupt.

VLScg_RT_CUSTOM_DATA_TAG_MISSING The custom defined data tag is not found in therevocation ticket.

VLScg_RT_CUSTOM_DATA_MISMATCH The custom defined data included in the per-mission ticket and revocation ticket does notmatch.

VLScg_RT_REVOCATION_TYPE_MISMATCH Either standalone revoke request is provided toverify with a network revocation ticket, or viceversa.



10.133. VLScgDecodeLicenseRevocationTicket

10.133.1. Syntaxint VLScgDecodeLicenseRevocationTicket (

char *license_revocation_ticket_buffer,

int license_revocation_ticket_buffer_size,

char *secret_key,

int secret_key_length,

VLSrevocationTicketInfoT *revocation_ticket );


license_revocation_ticket_buffer An IN parameter. A buffer that holds the string datareturned by the VLSrevokeLicense API function.

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

secret_key An IN parameter. Refers to the first secret specified in thelicense code. It is used by the license server for generatingthe encrypted license revocation ticket. If there is no secretspecified (when challenge-responsemechanism is notused), specify secret_key as NULL or set secret_key_lengthto zero.

secret_key_length An IN parameter. The length of the secret key.

revocation_ticket An OUT parameter. The VLSrevocationTicketInfoT struc-ture.


Decodes the license revocation ticket (LRT) generated the pre 8.4.1 network revocation workflow (referto the Appendix - "Network License Revocation Prior to the 8.4.1 Release" of the Sentinel RMS SDKDeveloper's Guide).

10.133.3. Returns

The status code VLScg_SUCCESS is returned if successful. Refer to the error codes given in LicenseGeneration Error Codes.

10.134. VLScgDecodeLicenseRevocationTicketExt

10.134.1. Syntaxint VLScgDecodeLicenseRevocationTicketExt (

char *license_revocation_ticket_buffer_old,

int license_revocation_ticket_buffer_old_size,

unsigned char revocation_ticket_buffer,

unsigned long revocation_ticket_buffer_size,

char *secret_key,

int secret_key_length,

VLSrevocationTicketInfoT *license_revocation_ticket_old,

PVRT_REVOKE_TICKET_INFO revocation_ticket,

unsigned long *pulRevocation_ticket_size,



license_revocation_ticket_buffer_old An IN parameter. A buffer that holds the stringdata returned by the VLSrevokeLicense API func-tion. In response, the structure VLSrev-ocationTicketInfoT is filled and returned.Specify NULL, if using the license_revocation_ticket_buffer described below.

license_revocation_ticket_buffer_old_size An IN parameter. A buffer that defines the size ofthe ticket returned by the VLSrevokeLicense APIfunction.

revocation_ticket_buffer An IN parameter. A buffer that holds the stringdata returned by theVLSrevokeByPermissionTicket API function. Inresponse, the structure PVRT_REVOKE_TICKET_INFO is filled and returned.Specify NULL, if using the license_revocation_ticket_buffer_old described above.

revocation_ticket_buffer_size, An IN parameter. A buffer that defines the size ofthe ticket returned by theVLSrevokeByPermissionTicket API function.

secret_key An IN parameter. Refers to the first secret specifiedin the license code. It is used by the license serverfor generating the encrypted license revocationticket. If there is no secret specified (when chal-lenge-responsemechanism is not used), specifysecret_key as NULL or set secret_key_length tozero.

10.134. VLScgDecodeLicenseRevocationTicketExt 467



secret_key_length An IN parameter. The length of the secret key.

license_revocation_ticket_old An OUT parameter. The VLSrevocationTicketInfoTstructure.

revocation_ticket An OUT parameter. The VRT_REVOKE_TICKET_INFO structure.

pulRevocation_ticket_size An OUT parameter. A buffer that defines the size ofthe revocation ticket. If the VRT_REVOKE_TICKET_INFO structure is passed as NULL, then it will returnthe length in the pulRevocation_ticket_size param-eter.

unused Reserved for future use.


Decodes all types of revocation tickets generated, which are:

n The license revocation ticket (LRT) generated using the pre 8.4.1 network revocation model.

n The stand-alone revocation tickets (which can also be decoded using VLScgDecodeLicense).

n The network revocation tickets generated using the workflow introduced in the v8.4.1.

10.134.3. Returns

The status code VLScg_SUCCESS is returned if successful. Refer to the error codes given in LicenseGeneration Error Codes.

10.135. VPT_REQUEST_LINE

10.135.1. Syntaxtypedef struct _VPT_REQUEST_LINE {

unsigned char ucOperation;

unsigned char *pucVendorDefined;

unsigned long ulVendorDefinedLength;

unsigned char *pucLicenseLine;

unsigned long ulLicenseLineLength;

} VPT_REQUEST_LINE, *PVPT_REQUEST_ LINE;

Member Description

ucOperation The requested operation. The possible values are:

n A: add a new licensen R: completely revoke a license

pucVendorDefined The vendor defined data. If there is no vendor defined data, the puc-VendorDefined argument must be NULL. In this case, the ulVen-dorDefinedLength argument is ignored.

ulVendorDefinedLength The length of the vendor defined data.

pucLicenseLine The license string to be added or revoked.

ulLicenseLineLength The length of license string to be added or revoked.

10.135. VPT_REQUEST_LINE 469


10.136. VPT_REQUEST

10.136.1. Syntaxtypedef struct _VPT_REQUEST {

unsigned char *pucTransactionId;

unsigned long ulLockCodeSelector;

unsigned char * pucLockInfo;

unsigned long ulTimeStamp;

unsigned long ulRequestArraySize;

PVPT_REQUEST_LINE pvRequestArray;

} VPT_REQUEST, *PVPT_REQUEST;

Member Description

pucTransactionId The transaction ID to uniquely identify a permission ticket to be gen-erated.

ulLockCodeSelector The lock code selector.

pucLockInfo The locking information of the target lock selector.

ulTimeStamp The time stamp of the permission ticket to be generated.

ulRequestArraySize The number of requests.

pvRequestArray A pointer to an array of structures for the requested operations andlicenses.

10.137. VPT_REQUEST_LINE_EXT

10.137.1. Syntaxtypedef struct _VPT_REQUEST_LINE_EXT {

unsigned long struct_size;


unsigned int hard_limit_to_revoke;

unsigned char *pucVendorDefined;

unsigned long ulVendorDefinedLength;



} VPT_REQUEST_LINE_EXT, *PVPT_REQUEST_LINE_EXT;

Member Description

struct_size The size of the structure.

ucOperation The requested operation. The possible values for stand-alonelicenses are:

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

The possible values for network licenses are:

n P: For partial revocation. Revokes the number of tokens lessthan or equal to hard limit.

n R: Completely revokes a license.

hard_limit_to_revoke Specify the number of tokens of a license to be revoked. Requiredfor partial network license revocation only.

Set 0 for stand-alone license revocation and full network license rev-ocation requests.

pucVendorDefined The vendor defined data. If there is no vendor defined data, the puc-VendorDefined argument must be NULL. In this case, the ulVen-dorDefinedLength argument is ignored.

ulVendorDefinedLength The length of the vendor defined data.

pucLicenseLine The license string to be added or revoked.

ulLicenseLineLength The length of license string to be added or revoked.

10.137. VPT_REQUEST_LINE_EXT 471


10.138. VPT_REQUEST_EXT

10.138.1. Syntaxtypedef struct _VPT_REQUEST_EXT {



unsigned long ulLockCodeSelector;

unsigned char *pucLockInfo;

unsigned long ulTimeStamp;

unsigned char *pucCustomDefined;

unsigned long ulCustomDefinedLength;

unsigned long ulRequestArraySize;

PVPT_REQUEST_LINE_EXT pvRequestArrayExt;

} VPT_REQUEST_EXT, *PVPT_REQUEST_EXT;

Member Description


pucTransactionId The transaction ID to uniquely identify a permission ticket to be gen-erated.

ulLockCodeSelector The lock code selector.

pucLockInfo The locking information of the target lock selector.

ulTimeStamp The time stamp of the permission ticket to be generated.

pucCustomDefined 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 ulCus-tomDefinedLength argument is ignored in case pucCustomDefined isset to NULL.

ulCustomDefinedLength The length of the vendor defined custom data.

ulRequestArraySize The number of requests.

pvRequestArrayExt A pointer to an array of structures for the requested operations andlicenses.

10.139. VRT_VERIFY_ERROR_LINE

10.139.1. Syntaxtypedef struct _VRT_VERIFY_ERROR_LINE {

unsigned long ulErrorCode;


unsigned long ulStatus;

unsigned char pucLicenseLine[VLS_MAX_CUSTOM_LICENSE_SIZE];


unsigned long ulCapacityRevoked;

unsigned long ulNumberOfLicensesRevoked;

} VRT_VERIFY _ERROR_LINE, *PVRT_VERIFY_ERROR_LINE;

Member Description

ulErrorCode The error reported by the verification process.Depending on the source of the error it is possiblethat only this member of the structure is present andthe others are ignored. This happens when the erroris related to either the validity of the revocationticket (for example, invalid format or the ticket is cor-rupt) or non-action related error (for example, Per-mission Id or Lock Codemismatch).

ucOperation Any of these requested / performed operation. Thepossible values are:

n A: add a new licensen R: completely revoke a licensen P: partially revoke a license

ulStatus The reported status of the performed operation.When any requested action fails, the VLSrevoke-ByPermissionTicket API does not generate rev-ocation ticket at all. Usually, you will never encounterfailure status in a revocation ticket.

10.139. VRT_VERIFY_ERROR_LINE 473


Member Description

pucLicenseLine The license line, either from the original request (if itwas not performed) or from the revocation ticket (ifthe status was non-success or it is something thatnever asked for by the original request).In case, the revocation ticket contains any status—other than success—then pucLicenseLinewill con-tain a license line only if:

n A stand-alone revocation ticket was passed.

n Or, a network revocation ticket was verifiedagainst the original structure of a permissionticket.

ulLicenseLineLength The length of the license line.

ulCapacityRevoked The capacity revoked. Unused.

ulNumberOfLicensesRevoked The number of licenses revoked.

10.140. VRT_VERIFY_ERRORStypedef struct _VRT_VERIFY_ERRORS {

unsigned long ulNumOfErrors;

VRT_VERIFY_ERROR_LINE *pvRTErrorArray;

} VRT_VERIFY_ERRORS, *PVRT_VERIFY_ERRORS;

Member Description

ulNumOfErrors The number of errors stored in the array structure.

pvRTErrorArray A pointer to an array of structures for reporting errors.

10.140. VRT_VERIFY_ERRORS 475


10.141. VRT_REVOKE_TICKET_LINE

10.141.1. Syntaxtypedef struct _VRT_REVOKE_TICKET_LINE {


unsigned char feature_name[VLS_MAXFEALEN];

unsigned char feature_version[VLS_MAXFEALEN];

unsigned char *pucLicenseHash;




unsigned int base_license_hard_limit;

unsigned int number_licenses_revoked;

unsigned int status;

unsigned long *unused1;

unsigned int unused2;

} VRT_REVOKE_TICKET_LINE, *PVRT_VERIFY_ERROR_LINE;

Member Description


feature_name The feature name for which the revocation ticket (RT) was generated.Required for network license revocation only.

feature_version The feature version for which the revocation ticket (RT) was gen-erated. Required for network license revocation only.

pucLicenseHash A pointer to the license hash. For network revocation only.

pucLicenseLine A pointer to the license string. For stand-alone revocation only.

ulLicenseLineLength The length of the license string. For stand-alone revocation only.

ucOperation The operation type (add, full revocation, or partial revocation).

base_license_hard_limit The hard limit of the license. For network revocation only.

number_licenses_revoked The number of license tokens revoked. For network revocation only.

status Status corresponding to the operations executed.



10.142. VRT_REVOKE_TICKET_INFOtypedef struct _VRT_REVOKE_TICKET_INFO {



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 Description


pucTransactionId A pointer to the transaction ID (uniquely identifies a permissionticket).

locking_criteria The locking criteria of the target system.

locking_info The locking information of the target system.

time_stamp The time stamp as specified while generating the permission ticket.

pucCustomDefined A pointer to the vendor defined custom data as specified while gen-erating the permission ticket.

ulCustomDefinedLength The length of the vendor defined custom data.

pvRevokeInfoArray A pointer to the array containing the revocation information.

ulRevokeInfoArraySize A size of the pvRevokeInfoArray array.



10.142. VRT_REVOKE_TICKET_INFO 477


10.143. VLSrevocationTicketInfoTThe VLSrevocationTicketInfoT structure used by the VLScgDecodeLicenseRevocationTicket function.

10.143.1. Syntaxtypedef struct {


unsigned long time_stamp;

unsigned char feature_name[VLS_MAXFEALEN];

unsigned char feature_version[VLS_MAXFEALEN];


unsigned int base_license_hard_limit;

unsigned int number_licenses_revoked;

unsigned int total_number_licenses_revoked;

unsigned long capacity_revoked;

unsigned long server_locking_criteria;

unsigned char server_locking_info[VLS_MAXSRVLOCKLEN];

} VLSrevocationTicketInfoT;

Member Description


time_stamp The timewhen the license revocation ticket was generated.

feature_name The feature name for which the license revocation ticket wasgenerated.

feature_version The feature version for which the license revocation ticket wasgenerated.

capacity The capacity of the feature whose license revocation ticket wasgenerated.

base_license_hard_limit The hard limit of the feature whose license revocation ticketwas generated.

number_licenses_revoked The number of licenses revoked.

total_number_licenses_revoked The total number of licenses revoked for a feature.

capacity_revoked The capacity of the feature revoked.

server_locking_criteria The locking criteria of the license server on which the rev-ocation was executed.

Chapter 11:System Initialization API

This chapter discusses the system initialization API functions, contained in the lsinit library. You mustinitialize the system for setting up the persistence data for the stand-alone licensemodels, such as atrial license or a checked-out commuter license. For understanding the importance of system initial-ization, refer to the Chapter 3 - Planning the Application Protection of the Sentinel RMS SDK Devel-oper’s Guide.



sntlInitStandaloneSystem Initializes the client or stand-alone system with the persistence infor-mation.

sntlInitNetworkSystem Sets up the license server for persistence information

11

480 Chapter 11: System Initialization API

11.1. sntlInitStandaloneSystem

11.1.1. Header

Include lsinit.h

11.1.2. Library

n Windows - lsinit32.lib (both MT and MD versions), lsinit32.dll

n UNIX - liblsinit.a, liblsinit.so

11.1.3. Description

Initializes the client or stand-alone system with the persistence information.

If the licensed application does not find the persistence data at the time of requesting a license, it willgenerate an error. The use of this function in your application installer will also ensure that yourlicensed 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 orchecking out a token for normal user.

11.1.4. Syntaxint sntlInitStandaloneSystem (

char *GUID,

char *featureName,

char *featureVersion );


GUID The application installer's GUID.£

featureName The application feature name.

featureVersion The application feature version.

£ Stands for GlobalUnique Identifier—a unique 128-bit number that is produced by

theWindows operating system or by someWindows 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 ofinput 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 arespecified they shall be ignored on UNIX systems. The function must be called only once to initialize thesystem.

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 isreturned indicating the reason for failure. For a list of error codes, see System Initialization ErrorCodes.

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.

n For UNIX, it is installed at <installdir>/examples.

11.1. sntlInitStandaloneSystem 481

482 Chapter 11: System Initialization API

11.2. sntlInitNetworkSystem

11.2.1. Header

Include lsinit.h

11.2.2. Library

n Windows - lsinit32.lib (both MT and MD versions), lsinit32.dll

n UNIX - lsinit32.a, lsinit32.so

11.2.3. Description

This function sets the requisite permissions for the Sentinel RMS registry keys (if applicable) and filesat the time of system initialization.

However, if you are going to integrate the license server installer in yourWindows installer, there is noneed 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 forexplicit initialization.

IMPORTANTS i n c e th e 8 .4 .0 r e l e ase , th e se r v e r - s i d e c ommu te r p e r s i s te n c e ar c h i te c tu r e h asb e e n mod i f i e d . Th e e ar l i e r p e r s i s te n c e d ata w i l l b e m i g r a te d au tom at i c a l l y b yu s i n g th e up g r ad e d l i c e n se se r v e r ( v 8 .4 .0 o r l a te r ) . How e ve r , th e m i g r a t i o n c an -n o t b e done th r ou gh th i s 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.

Chapter 12:Persistence Cleaning API

This topic discusses the persistence cleaning API functions, contained in the lsclean library. For under-standing the complete process of persistence cleaning, refer to the Sentinel RMS SDK Developer’sGuide.



VLScleanStandalonePersistenceInfo For cleaning up and repairing the persistence informationon a stand-alone system.

VLScleanNetworkPersistenceInfo For cleaning up and repairing the persistence informationon a license server.

The APIs can clean up the following types of persistence database:

n Trial license (VLS_TRIAL_STORE)

n Commuter license (VLS_COMMUTER_STORE)

n Time tampered license (VLS_TIME_TAMPER_STORE)

n License revocation (VLS_REVOKE_STORE)

n Grace license (VLS_GRACE_STORE)

n Volume transaction licenses (VLS_VTL_STORE)

12

484 Chapter 12: Persistence Cleaning API

12.1. VLScleanStandalonePersistenceInfo

12.1.1. Header and Library

n Include lsclean.h

n lsclean32.lib (MD, MT, and MDd)

12.1.2. Description

The API function can be used for cleaning or repairing the following type of information in case ofstand-alone licensing:

Stand-alone Persistence Type

Licensing Library Versions

8.1.0 or later 8.0.x 7.3.x 7.2.x

Trial √ (Repairingonly)

√ √ √

Commuter √ √ √ √

Time-tamper √ √ √ √

Grace √ √ NA NA

Revocation √ (Repairingonly)

NA NA NA

Volume Transaction √ (Repairingonly)

NA NA NA

12.1.3. SyntaxLS_STATUS_CODE VLScleanStandalonePersistenceInfo (

int clientLibVersion,

int persistenceType,

char* featureName,

char* featureVersion,

char* unused1,

int unused2 );

ArgumentDirection

DataType

Description

clientLibVersion IN int The licensing library's version. Specify any of the fol-lowing:

n 7 - For the licensing library version 7.2.x and

ArgumentDirection

DataType

Description

7.3.xn 8 - For the licensing library version 8.0.xn 82 - For the licensing library version 8.1.x and

8.2.xn 83 - For the RMS license server version 8.3.xn 84 - For the RMS license server version 8.4.x

persistenceType IN int The persistence type. Specify any of the following:

n 1 - For VLS_TRIAL_STOREn 2 - For VLS_COMMUTER_STOREn 3 - For VLS_TIME_TAMPER_STOREn 4 - For VLS_REVOKE_STOREn 5 - For VLS_GRACE_STOREn 6 - For VLS_VTL_STORE

featureName IN char* The feature name of the license. Should not be of zerolength and must not exceed 24 characters.

featureVersion IN char* The version of the license. Must not exceed 11 char-acters.

Call this API function with proper arguments to clean a particular persistence. No preprocessing (initial-ization) or post-processing (cleanup) is required.

NULL valuemust be passed to the arguments that are not applicable to a particular scenario. For exam-ple, feature name and version must be passed as NULL for repairing the:

n Trial license persistence (version 8.1.x or higher)

n Stand-alone revocation persistence (version 8.2.x or higher)

n Volume transaction license persistence (version 8.2.x or higher)

In case of trial license repairing, this is equivalent to the following command of lsclean:

lsclean -fixtrial

You need to 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 herewill be returned.

12.1. VLScleanStandalonePersistenceInfo 485


12.2. VLScleanNetworkPersistenceInfo

12.2.1. Header and Library

n Include lsclean.h

n lsclean32.lib (MD, MT, and MDd)

12.2.2. Description

The API function can be used for cleaning or repairing the following type of information in case of net-work licensing:

Network Persistence Type

Licensing Server Versions

8.4.x - 8.5.x 8.1.x - 8.3.x 8.0.x 7.2.x - 7.3.x

Trial NA √ (Repairingonly)

√ √

Commuter √ √ √ √

Time-tamper NA √ √ √

Revocation NA √ (Repairingonly)

√ NA

Volume Transaction NA √ (Repairingonly)

NA NA

12.2.3. SyntaxLS_STATUS_CODE VLScleanNetworkPersistenceInfo(

int serverVersion,

int persistenceType,

char* featureName,

char* featureVersion,

char* hostName,

char* unused1,

int operationType);

ArgumentDirection

DataType

Description

serverVersion IN int The license server version. Specify any of the following:

n 7 - For the RMS license server version 7.2.x and7.3.x

n 8 - For the RMS license server version 8.0.x

ArgumentDirection

DataType

Description

n 82 - For the RMS license server version 8.1.x and8.2.x

n 83 - For the RMS license server version 8.3.xn 84 - For the RMS license server version 8.4.x and

8.5.x

persistenceType IN int The persistence type. Specify any of the following:

n 1 - For VLS_TRIAL_STOREn 2 - For VLS_COMMUTER_STOREn 3 - For VLS_TIME_TAMPER_STOREn 4 - For VLS_REVOKE_STOREn 5 - For VLS_GRACE_STOREn 6 - For VLS_VTL_STORE

featureName IN char* The feature name of the license. Should not be of zerolength and must not exceed 24 characters.

The feature and version parameters are not

required for cleaning the version 13 (generated

using RMS v 8.4.0 or later) server-side commuter

and repository licenses.

featureVersion IN char* The version of the license. Must not exceed 11 char-acters.

hostName IN char* The hostname of the system whose commuter checkout information is to be cleaned from the server per-sistence. The NULL value shall be used to clean the infor-mation of all clients. It cannot exceed 64 characters.

unused1 IN char* Unused.

operationType IN int Set to any of the following:

n VLS_LPR_COMMUTER_CLEAN - For cleaning upcommuter data.

n VLS_LPR_COMMUTER_REPAIR - For recoveringcommuter data.

For details, see Scenario - Commuter PersistenceCleaning on the License Server.

Call this API function with proper arguments to clean a particular persistence. No preprocessing (initial-ization) 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.



NULL valuemust be passed to the arguments that are not applicable to a particular scenario. For exam-ple, host name, feature name, and version must be passed as NULL for repairing the:

n Trial license persistence (version 8.1.x or higher)

n Volume transaction license persistence (version 8.2.x or higher)

In case of volume transaction license repairing, this is equivalent to the following command of lsclean:

lsclean -fixvtl

Scenario - Commuter Persistence Cleaning on the License Server

Cleaning up of commuter information on the license server might be required whentokens are checked out for maximum duration and the c lient computer has crashed. Torestore the checked out token on the license server , call the VLSc lean-NetworkPersistenceInfo API with the following parameters:

• Spec ify the license server version (1st parameter) as 84 for license server version8.4.0 and higher (inc luding 8.5.0).

• Spec ify the host name parameter (5th parameter) as the actual host name of the c lientas shown by 'hostname' command (case sensitive).

• Spec ify the operationType parameter of int type (7th parameter) as any of the fol-lowing:

• VLS_LPR_COMMUTER_CLEAN for c leaning up commuter data.

• VLS_LPR_COMMUTER_REPAIR for recover ing commuter data.

Under this scenar io, the API may return the following errors:

• VLSc l_NO_COMMUTER_INFO_FOUND - No commuter persistence information is foundfor the given feature-version. Probably, no commuter tokens are checked out for this fea-ture-version, or when there are commuter check outs for other feature-version(s).

• VLSc l_NO_COMMUTER_FEATURE_IN_USE – The commuter information available forthe feature-version is for a different c lient.

• VLSc l_ INVALID_ARGUMENTS – This error may occur when following values are passedfor c leaning commuter persistence information:

• NULL as the feature name or host name.

• When the feature name passed is greater than 24 characters.

• When the feature version passed is greater than 11 characters.

• When the host name passed is greater than 64 characters.

• 84 as the license server version and the operationType value is other thanVLS_LPR_COMMUTER_CLEAN and VLS_LPR_COMMUTER_REPAIR.

12.2.4. Returns

The status code VLScl_SUCCESS is returned, if successful. Otherwise, any of the error codes listed herewill be returned.


Appendix A:Status Codes

This section contains status codes for the following:

n Licensing APIs

n License generation APIs

n Upgrade license APIs

n System initialization APIs

n Persistence cleaning APIs

A

492 Appendix A: Status Codes

A.1. Licensing Library Error and Result CodesThe table below contains the licensing library error messages and description:

Error # Error/Status Codes Description

0x0 LS_SUCCESS Successful operation.

0xC8001001 LS_BADHANDLE The client handle refers to an invalid licensing sys-tem context.

0xC8001002 LS_INSUFFICIENTUNITS Could not locate enough licensing resources tolicense this feature.

0xC8001003 LS_LICENSESYSNOTAVAILABLE The licensing system is not available.

0xC8001004 LS_LICENSETERMINATED Default error. Cannot update license because thekey lifetime has expired and re-request of the licensehas failed.

0xC8001005 LS_NOAU-THORIZATIONAVAILABLE

No license code is available for this feature on thespecified host.

0xC8001006 LS_NOLICENSESAVAILABLE All licensing tokens with the server for this featureare already in use.

0xC8001007 LS_NORESOURCES Insufficient system resources are available to com-plete the request.

0xC8001008 LS_NO_NETWORK Unable to talk to this host.

0xC8001009 LS_NO_MSG_TEXT Unknown error code, cannot print the error mes-sage.

0xC800100A LS_UNKNOWN_STATUS Unknown error code, cannot print the error mes-sage.

0xC800100B LS_BAD_INDEX Bad index.

0xC800100C LS_NO_MORE_UNITS No additional units are available for this feature.

0xC800100D LS_LICENSE_EXPIRED The feature cannot run anymore because the licenseexpiration date has reached. Check your machine'sdate and contact your vendor.

0xC800100E LS_BUFFER_TOO_SMALL Input buffer too small, string may be truncated.

0xC800100F LS_NO_SUCCESS Failed in performing the requisite operation.

0xC8001010 LS_GRACE_EXPIRED The feature cannot run as the total number of daysallowed in the grace period have been consumed.

0xC8001011 LS_GRACE_INVALID_STATE This feature cannot run as an unexpected state ofgrace period is found.

0xC8001012 LS_GRACE_HOURS_EXHAUSTED The feature cannot run as the total number of hoursallowed in the grace period have been consumed.

1 VLS_NO_LICENSE_GIVEN Unable to obtain licensing token for this feature.

2 VLS_APP_UNNAMED Feature name or version cannot be NULL.

3 VLS_HOST_UNKNOWN Failed to resolve the specified server host.


4 VLS_NO_SERVER_FILE Failed to figure out the license server correctly. Setthe environment variable LSHOST to name(s) ofserver(s).

5 VLS_NO_SERVER_RUNNING Cannot talk to the license server on the specifiedhost. The license server is not running.

6 VLS_APP_NODE_LOCKED The specified feature is not licensed to run on thismachine due to server/client lock-codemismatch.This error results both in the case of locking mis-match on client or license server end. To better diag-nose this condition, you should callVLSgetMachineID and VLSgetServInfo on client andserver end, respectively. The locking informationobtained then needs to bematched against thelicense code to knowwhether mismatch exists onthe client or license server end.

7 VLS_NO_KEY_TO_RETURN Attempt to return a non-existent token by the clientapplication.

8 VLS_RETURN_FAILED Failed to return the token issued for the specifiedfeature.

9 VLS_NO_MORE_CLIENTS No more clients exists for this feature.

10 VLS_NO_MORE_FEATURES No more features available on license server.

11 VLS_CALLING_ERROR Error in calling the API function. Check the callingparameters.




12 VLS_INTERNAL_ERROR The possible causes are:

n Vendor ID mismatch. Please check if the clientlibraries and license generator belong to thesame installation.

n Incorrect use of SharedID. The license libraryis not able to find the SharedID at runtime.

n Failure in parsing the license server namestring while adding a server to the redundantpool.

n If using the license queuing feature, whileremoving a queue from the license server, ifthe server returns an error message otherthan VLS_CLIENT_NOT_AUTHORIZED. In thiscase check the client authorization whoserequest is on hold.

n In case of VLSreque-stExt2/VLSqueuedRequestExt APIs, whenauto update is on and the licensing library isnot able to add a license to handle or theauto update list, or failed to start the licensetimer.

13 VLS_SEVERE_INTERNAL_ERROR The possible causes are:

n The encryption operation has failed.n The default function for obtaining hostname

on which licensed application is running hasfailed. Please check hostname-IP resolutionon a non-Windows machine.

n The system call fails while calculating time(localtime and localtime_r function on non-Windows OSes and time function on Win-dow).

n The licensing library is unable to construct amessage. If the encryption logic ofmessagesis customized, this error might come due tocustomization logic failure. Please verify theencryption logic again.

14 VLS_NO_SERVER_RESPONSE The license server on the specified host is notresponding.

15 VLS_USER_EXCLUDED This user/machine has been excluded from access-ing the specified feature.

16 VLS_UNKNOWN_SHARED_ID Unknown shared ID given for the specified feature.

17 VLS_NO_RESPONSE_TO_BROADCAST

Probably no servers are running on this subnet.

18 VLS_NO_SUCH_FEATURE No license code is available for the specified feature


on this host.

19 VLS_ADD_LIC_FAILED The given license code could not be added to thespecified license server.

20 VLS_DELETE_LIC_FAILED Failed to delete the specified feature from thelicense server on host.

21 VLS_LOCAL_UPDATE Last update was done locally.

22 VLS_REMOTE_UPDATE Last update was done by the license server.

23 VLS_VENDORIDMISMATCH The specified feature is licensed by a different ven-dor.

24 VLS_MULTIPLE_VENDORID_FOUND

The specified feature is licensed by multiple vendorsother than your vendor.

25 VLS_BAD_SERVER_MESSAGE Could not understand themessage received fromthe license server on the specified host. Client-serverversion mismatch.

26 VLS_CLK_TAMP_FOUND The following scenarios are possible:

Scenario A:

n In case of a network license, if the systemclock of the license server host is tampered.

n In case of a stand-alone license, if the systemclock is tampered.

To clean up the time tamper persistence infor-mation, please see “Appendix A - Cleaning LegacyPersistence Data” in the Sentinel RMS SDK Devel-oper's Guide.

Scenario B:

If the system is not initialized (using the sntlIn-itStandaloneSystem API or the lsinit utility) and per-sistence based licenses (like, grace, commuter, andstand-alone time tampering enabled) are requested.The API call returns this error.

Pleasemake sure that correct feature, version, andGUID (if applicable) are used for system initialization.

Scenario C:

If the serial number information corresponding tothe stand-alone system initialization, license string,and client library does not match, the API callreturns this error.

27 VLS_NOT_AUTHORIZED You are not authorized to perform the requestedoperation.




28 VLS_INVALID_DOMAIN Cannot perform this operation on the domain namespecified.

34 VLS_LOG_FILE_NAME_NOT_FOUND

The specified log filename not found on the specifiedlicense server host.

35 VLS_LOG_FILE_NAME_NOT_CHANGED

Cannot change the specified log filename on thespecifiedlicense server host.

36 VLS_FINGERPRINT_MISMATCH Machine's fingerprint mismatch for this feature.

37 VLS_TRIAL_LIC_EXHAUSTED The duration of the specified trial license isexhausted.

38 VLS_NO_UPDATES_SO_FAR No updates have taken place for this feature so far.

39 VLS_ALL_UNITS_RELEASED Returned all the tokens for this feature.

40 VLS_QUEUED_HANDLE The specified client handle is associated with aqueued request.

41 VLS_ACTIVE_HANDLE The specified client handle is associated with anactive request.

42 VLS_AMBIGUOUS_HANDLE Ambiguous client handle! The specified client handleis not associated with any request.

43 VLS_NOMORE_QUEUE_RESOURCES

Queued request denied for this application since thequeue is already full.

44 VLS_NO_SUCH_CLIENT Could not find the specified client for this feature.

45 VLS_CLIENT_NOT_AUTHORIZED Client not authorized for the specified action for thisfeature.

47 VLS_LEADER_NOT_PRESENT Processing not done because current leader is notknown.

48 VLS_SERVER_ALREADY_PRESENT

Server already exists in the redundant server pool.

49 VLS_SERVER_NOT_PRESENT The given server name does not exist in the redun-dant server pool.

50 VLS_FILE_OPEN_ERROR File open error.

51 VLS_BAD_HOSTNAME The specified host name is either not valid or cannotbe resolved.

52 VLS_DIFF_LIB_VER The server fails to identify the client application ver-sion.

53 VLS_NON_REDUNDANT_SRVR A non-redundant server contacted for redundantserver related information

54 VLS_MSG_TO_LEADER Message forwarded to the leader server.

55 VLS_CONTACT_FAILOVER_SERVER

Update Failure. Contact another fail-over server.

56 VLS_UNRESOLVED_IP_ADDRESS IP address given cannot be resolved.


57 VLS_UNRESOLVED_HOSTNAME Hostname given is unresolved.

58 VLS_INVALID_IP_ADDRESS Invalid IP address format.

59 VLS_SERVER_FILE_SYNC Server is synchronizing the distribution table

60 VLS_POOL_FULL The redundant server pool already has themax-imum number of servers. No more servers can beadded.

61 VLS_ONLY_SERVER The redundant server pool has only one server. Itcannot be deleted.

62 VLS_FEATURE_INACTIVE This feature is either unavailable on the server orserver is non-redundant.

63 VLS_MAJORITY_RULE_FAILURE The token for this feature cannot be issued becauseof themajority rule failure.

64 VLS_CONF_FILE_ERROR Configuration file modifications failed. Check thegiven parameters.

65 VLS_NON_REDUNDANT_FEA-TURE

A non-redundant feature given for redundant fea-ture related operation

66 VLS_NO_TRIAL_INFO Cannot find trial license information for given fea-ture.

67 VLS_TRIAL_INFO_FAILED Failure in retrieving the trial usage information forthe given feature.

69 VLS_NOT_LINKED_TO_INTE-GRATED_LIBRARY

Application is not linked with integrated library.

70 VLS_CLIENT_COMMUTER_CODE_DOES_NOT_EXIST

The commuter code for this feature does not existon the client system.

72 VLS_NO_MORE_COMMUTER_CODE

No more checked-out commuter code exists on theclient.

73 VLS_GET_COMMUTER_INFO_FAILED

Failed to get client commuter info on this server.

74 VLS_UNABLE_TO_UNINSTALL_CLIENT_COMMUTER_CODE

Unable to uninstall the client commuter license.

75 VLS_ISSUE_COMMUTER_CODE_FAILED

The possible causes are:

n If the client or server-side commuter per-sistence data is corrupt, then the local/re-mote checkout APIs return this error. Toresolve this condition, clean up the corruptpersistence as documented (see Chapter 3 -Planning Application Licensing of the SentinelRMS SDK Developer's Guide)

n When the detection of remote sessions is setoff in the VLSsetControlRemoteSession APIand an attempt is made to check out a com-




muter license from a remote system, thenthe API call returns error. To resolve, allowdetection of remote sessions by setting VLS_OFF in the API.

n If the update call is delayed and client doesnot receive a message from the license serverwhile license check-out, this error is returned.To resolve, you may increase the time-outinterval.

n When an attempt is made to check out anewer version license for an applicationlicensed using an older version of the licens-ing library, this error is returned. For exam-ple, the version 11 (or later) tool/libraryshould be used to check out version 11licenses.

76 VLS_NON_COMMUTER_LICENSE

A non-commuter license is requested for commuterrelated operation by this client.

The VLS_UNABLE_TO_ISSUE_COMMUTER_

CODE has been deprecated. Use VLS_NON_

COMMUTER_LICENSE instead.

77 VLS_NOT_ENOUGH_COM-MUTER_KEYS_AVAILABLE

Not enough commuter tokens are available on thisserver.

78 VLS_INVALID_INFO_FROM_CLIENT

Invalid commuter info from the client.

79 VLS_CLIENT_ALREADY_EXIST The client already exists on this server.

81 VLS_COMMUTER_CODE_ALREADY_EXIST

The client commuter license already exists on thissystem.

82 VLS_SERVER_SYNC_IN_PROG-RESS

Error specific to the redundant server pool setup.Occurs under the following scenarios:

n The server pool consists of only one licenseserver. Specify at least two license serversto form a pool.

n Even if theminimum number of licenseservers are defined in the pool, the serversare busy synchronizing with each otherwhen any redundant server API is called.This usually happens during the licenseserver start-up or restart.


83 VLS_REMOTE_CHECKOUT This commuter license is checked out remotely, so itcant be checked-in.

84 VLS_UNABLE_TO_INSTALL_COMMUTER_CODE

Error in installing the commuter authorization code.

85 VLS_UNABLE_TO_GET_MACHINE_ID_STRING

Error getting the locking information for the client.

86 VLS_INVALID_MACHINEID_STR Invalid remote locking code string.

87 VLS_EXCEEDS_LICENSE_LIFE Cannot issue commuter code. License expiration isless than the requested days for commuter code.

88 VLS_TERMINAL_SERVER_FOUND

Operating in stand-alonemode using terminalclient. This is not allowed by the vendor.

89 VLS_NOT_SUPPORTED_IN_NET_ONLY_MODE

Feature is not supported in Network-only mode oflibrary.

The VLS_NOT_APPROPRIATE_LIBRARY error

code has been deprecated. Use VLS_NOT_

SUPPORTED_IN_NET_ONLY_MODE instead.

90 VLS_INVALID_FILETYPE The specified file type is not supported.

91 VLS_NOT_SUPPORTED The client application is communicating with an oldlicense server.

92 VLS_INVALID_LICENSE The given license code is invalid. Hence, it could notbe added to this license server.

93 VLS_DUPLICATE_LICENSE The given license code is already added to the spec-ified license server.

94 VLS_INSUFFICIENT_USER_CAPACITY

Insufficient user capacity available.

95 VLS_TEAM_LIMIT_EXHAUSTED Team limit exhausted.

96 VLS_INSUFFICIENT_TEAM_CAPACITY

Insufficient team capacity available.

97 VLS_CANNOT_DELETE_UPGRADED_LIC

Deletion of upgraded feature/license is not allowed.

98 VLS_UPGRADE_NOT_ALLOWED License upgrade feature is not allowed for redun-dant licenses, commuter licenses and trial licenses.

99 VLS_FEATURE_MARKED_FOR_DELETION

The specified feature exists on this machine and it isalready marked for check-in.

101 VLS_TEAM_EXCLUDED This team has been excluded from accessing this fea-ture.




102 VLS_NETWORK_SRVR A network server is contacted for standalone relatedinformation.

103 VLS_PERPETUAL_LICENSE The contacted feature is a repository license.

104 VLS_COMMUTER_CHECKOUT A commuter token has already been checked out forthis license.

105 VLS_REVOKE_ERR_NO_FEA-TURE

License with given feature/version is either not avail-able on the server or belongs to a different vendor.

106 VLS_REVOKE_ERR_CORRUPT_MESSAGE

The client message received by the server was cor-rupted.

107 VLS_REVOKE_ERR_OUT_VALID_RANGE

The received number Of licenses to revoke is out ofrange.

108 VLS_REVOKE_ERR_MD5_PLU-GIN_LOAD_FAIL

Error loading theMD5 plug-in dll at the server.

109 VLS_REVOKE_ERR_MD5_PLU-GIN_EXEC_FAIL

Error in executing the authentication plug-in.

110 VLS_REVOKE_ERR_INSUF-FICIENT_FEATURE_LICENSES

This feature has less number of total licenses.

111 VLS_REVOKE_ERR_INSUF-FICIENT_DEFAULT_GROUP

Default group does not has sufficient licenses, recon-figure your user reservation file.

112 VLS_REVOKE_ERR_INSUF-FICIENT_FREE_IN_DEFAULT

Currently required number of licenses are not freefor revocation in the default group.

113 VLS_REVOKE_ERR_INVALID_SES-SION_ID

Invalid session id received from the client.

114 VLS_REVOKE_ERR_INVALID_PASSWORD

Invalid password for revocation.

115 VLS_REVOKE_ERR_INTERNAL_SERVER

Revocation failed due to internal server error.

116 VLS_REVOKE_ERR_INFINITE_GRP_DIST

Infinite revocation not possible with enabled groupdistribution.

117 VLS_REVOKE_ERR_INFINITE_LIC_IN_USE

All licenses must be free for infinite revocation.

118 VLS_REVOKE_ERR_INFINITE_LIC_FINITE_REQ

License has infinite keys. Only infinite license rev-ocation request is allowed for this license.

119 VLS_REVOKE_ERR_TICKET_GEN-ERATION

Revocation feature is not supported for redundantlicenses.

120 VLS_REVOKE_ERR_CODGEN_VERSION_UNSUPPORTED

Revocation feature is not supported for the givenlicense version.

121 VLS_REVOKE_ERR_RDNT_LIC_UNSUPPORED

122 VLS_REVOKE_ERR_CAPACITY_LIC_UNSUPPORED

Revocation feature is not supported for capacitylicenses.


123 VLS_REVOKE_ERR_UNEXPECTED_AUTH_CHLG_PKT

Failure occurred due to unexpected challengepacket received from server.

124 VLS_REVOKE_ERR_TRIAL_LIC_UNSUPPORED

Revocation feature is not supported for triallicenses.

125 VLS_REQUIRED_LOCK_FIELDS_NOT_FOUND

Required locking criteria for local request is not avail-able on your machine.

126 VLS_NOT_ENOUGH_LOCK_FIELDS

Minimum number of locking criteria for localrequest is not found.

127 VLS_REMOTE_CHECKOUT_NOT_ALLOWED_FOR_PER-PETUAL

Remote checkout is not available for a repositorylicense.

128 VLS_GRACE_LIC_INSTALL_FAIL This feature cannot run as installation of gracelicense is failed.

129 VLS_NOT_SUPPORTED_IN_NONET_MODE

The feature is not supported in no-net (stand-alone)mode.

The VLS_NOT_SUPPORTED_IN_NONET_

LIBRARY error code has been deprecated. Use

VLS_NOT_SUPPORTED_IN_NONET_MODE

instead.

130 VLS_NO_ACTIVE_HANDLE No active client handle exists.

131 VLS_LIBRARY_NOT_INITIALIZED The licensing library is not initialized. To initialize, callVLSinitialize.

132 VLS_LIBRARY_ALREADY_INITIAL-IZED

The licensing library is already in initialized state.

133 VLS_RESOURCE_LOCK_FAILURE Failed to fetch the API resource lock. On receivingthis error, retry calling this API.

139 VLS_NO_MORE_LICENSES No more licenses.

140 VLS_NO_SUCH_LICENSE No license found with the specified fea-ture/version/hash.

141 VLS_LICENSE_IN_USE Specified feature/license has active client(s).

142 VLS_SET_LICENSE_PREC-EDENCE_FAILED

Failure in setting precedence for specified triallicense.

143 VLS_STORE_ACCESS_ERROR Failure in accessing the license file.

147 VLS_LOCK_SELECTOR_INVALID The specified lock selector is not valid.

148 VLS_LOCK_CODE_NOT_SUP-PORTED

The specified lock code is not supported by the libra-ry/server.




149 VLS_LOCK_CODE_VER_INVALID Invalid lock code version.

150 VLS_LOCK_CODE_INVALID The specified lock code is invalid.

151 VLS_NO_AVAILABLE_MACHINE_ID

No available machine id for specified lock selector.

152 VLS_CODE_GENERATOR_LIBRARY_FAILED

Failure in initializing code generator library.

153 VLS_TRIAL_LIC_DATA_ACCESS_ERROR

The specified trial feature is not accessible.

154 VLS_TRIAL_LIC_DATA_INCON-SISTENT

Trial License data inconsistent for this feature.

155 VLS_TRIAL_LIC_DATE_RESTRICTED

Trial license date restriction error for this feature.

156 VLS_TRIAL_LIC_NOT_ACTI-VATED

The trial licensing for this feature is disabled.

165 VLS_NONET_LIBRARY A network request is made to the standalonelibrary.

184 VLS_NON_TRIAL_LICENSE Active feature on the server is not a trial license.

188 VLS_LICENSE_START_DATE_NOT_REACHED

License start date not yet reached.

210 VLS_GRACE_CODE_LENGTH_OVERFLOW_ERROR

Grace code length exceeds maximum limit.

211 VLS_ERROR_NO_MORE_FIN-GERPRINT_VALUE

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 spec-ified index.

The VLS_ERROR_FILE_NOT_FOUND error

code has been deprecated. Use VLS_ERROR_

FINGERPRINT_VALUE_NOT_FOUND instead.


213 VLS_LICENSE_DELETION_NOT_ALLOWED

License deletion is not supported for the followinglicenses:

n Checked out commuter license tokens resid-ing on the local computers

n Grace licenses being used on the non-net-worked computers

n Licenses in the redundant license files(lservrlf)

214 VLS_CAPACITY_MISMATCH The capacity value does not match, or an operationrelated to capacity licensing is requested for a non-capacity license (or vice-versa).

215 VLS_EXPIRED_COMMUTER_CODE

Error installing the commuter code, as the code isexpired.

216 VLS_COMMUTER_CODE_DATE_RESTRICTED

Commuter code start date not yet reached.

217 VLS_NEW_RECORD_FOUND If the limit value has been updated by any otherprocess after the current process has retrieved thelimit value. The API function also returns the currentlimit value in the consume_value parameter.

218 VLS_NO_RECORDS_FOUND No records for the limit in the database.

219 VLS_OPERATION_NOT_SUC-CESSFUL

The requested operation failed for any other reason.

220 VLS_ERROR_READING_SERVER_CONFIG_FILE

The redundant server configuration file being usedfor determining the primary server (from which thelicense authorization is to be checked out) is cor-rupt.

221 VLS_CHECKOUT_NOT_ALLOWED_FROM_NON-PRIMARY_LEADER

An attempt is made to check out an authorizationfrom a non-primary server.

222 VLS_REHOST_LIC_VERSION_NOT_SUPPORTED

The stand-alone revocation feature is supported forv 11 (or later) licenses only. If an attempt is made torevoke licenses of earlier versions, the VLSrevoke-ByPermissionTicket succeeds, and returns VLS_REHOST_LIC_VERSION_NOT_SUPPORTED as statusin the revocation ticket.

223 VLS_USAGE_FILE_TAMPERED The usage log file is tampered. One or more recordsare either modified or missing from the usage logfile.

224 VLS_NO_MATCH_FOUND Thematching record is not found in the usage logfile.




225 VLS_INVALID_TCPIP_VERSION TCP\IP protocol version specified for licensing libraryis incorrect. Verify if the client and server protocolsare incompatible.

226 VLS_VIRTUAL_MACHINE_IS_DETECTED

The license server is being run on a virtual machine.

227 VLS_GRACE_LIC_TIME_TAMPER_INIT_FAIL

The system initialization failed for a grace license.

228 VLS_REVOKE_LIC_DATA_INCON-SISTENT

The license persistence data is either corrupt or doesnot exist.

229 VLS_TOO_MANY_OPERATIONS_IN_SINGLE_PT

The permission ticket size is more than the lengthsupported internally. This is applicable to networklicense revocation only, where themaximumnumber of operations should not exceed 15. Tryreducing the number of operations from the per-mission ticket. Contact Technical Support for moretroubleshooting.

230 VLS_PT_ALREADY_EXECUTED_FOR_THIS_OPERATION

The permission ticket operation already executed onthe license server.

231 VLS_PT_VENDOR_ID_MIS-MATCH

Vendor ID mismatch. The permission ticket cannotbe used for revoking licenses of other vendors.

232 VLS_REVOKE_EXPIRED_LIC_FOUND

An expired license can neither be added norrevoked.

233 VLS_COMMUTER_CHECKOUT_NOT_ALLOWED

The commuter token checkout not allowed for thisfeature.

A.2. License Generation Error CodesThe following table lists the RMS license code generation return codes and their default messages:

Error#

Return Code Default Message

0 VLScg_SUCCESS Success

2 VLScg_NO_FEATURE_NAME Feature Namemust be specified. It cannot beempty.

3 VLScg_INVALID_INT_TYPE Expected an integer value, found “XXX”

4 VLScg_EXCEEDS_MAX_VALUE Value entered is greater than themaximum sup-ported value.

5 VLScg_LESS_THAN_MIN_VALUE Value entered is less than theminimum sup-ported value.

6 VLScg_EXCEEDS_MAX_STRLEN Length of <value> is greater than <value>.

7 VLScg_NOT_MULTIPLE Value should be a multiple of “XXX”.

8 VLScg_INVALID_DEATH_YEAR Expiration date cannot be less than “XXX”.

9 VLScg_INVALID_BIRTH_YEAR Start year cannot be less than “XXX”.

10 VLScg_INVALID_DATE Date is not valid.

11 VLScg_INVALID_HEX_TYPE Wrong value entered. (Should be hexadecimal)

12 VLScg_INVALID_IP_TYPE Wrong value entered. IP address should bespecified in dot form.

13 VLScg_INVALID_YEAR Invalid year entered.

14 VLScg_RESERV_STR_ERR The string is a reserved string.

15 VLScg_INVALID_RANGE Value violates the valid range of input.

16 VLScg_INVALID_CHARS Invalid characters.

17 VLScg_SHORT_STRING License string \”<value>\” too small to parse.

18 VLScg_PREMATURE_TERM Premature termination of license code. Pleasecheck.

19 VLScg_REMAP_DEFAULT Failed to remap default strings from con-figuration file for license \”<value>\”.

20 VLScg_DECRYPT_FAIL Decryption failed for license code.

21 VLScg_DYNAMIC_DECRYPT_FAILURE Decryption failed for dynamically added licensecode.

22 VLScg_INVALID_CHKSUM Checksum validation failed for license code.Please verify the license code.

23 VLScg_FIXED_STR_ERROR Default fixed string error.

24 VLScg_SECRET_DECRYPT_FAILURE Decryption failed for secrets. Verify the con-figuration file for readable licenses.

25 VLScg_SIMPLE_ERROR Error in license code. Please check.



Error#


26 VLScg_MALLOC_FAILURE Out of heap memory.

27 VLScg_INTERNAL_ERROR Internal error.

28 VLScg_UNKNOWN_LOCK Unknown lock mechanism.

29 VLScg_VALUE_LARGE Value: <value> too large

30 VLScg_INVALID_INPUT Invalid input.

31 VLScg_MAX_LIMIT_ CROSSED Maximum limit crossed.

32 VLScg_NO_RESOURCES No resources left.

33 VLScg_BAD_HANDLE Bad file handle.

34 VLScg_FAIL Operation failed.

35 VLScg_INVALID_VENDOR_CODE Invalid Vendor Code. Please contact your Sen-tinel RMS Development Kit distributor.

36 VLScg_VENDOR_ENCRYPTION_FAIL Vendor-customized encryption failed.

37 VLScg_INVALID_EXP_DATE License Expiration Datemust be greater thanStart Date.

38 VLScg_INVALID_EXP_YEAR License Expiration Year must be greater thanStart Year.

39 VLScg_INVALID_EXP_MONTH License Expiration Month must be greater thanStart Month.

40 VLScg_LICMETER_EXCEPTION Unknown exception in accessing Sentinel RMSlicensemeter(s).

41 VLScg_LICMETER_DECREMENT_OK Your licensemeter(s) have been decrementedby <value> units. You now have <value> unitsleft out of an initial count of <value> units.

42 VLScg_LICMETER_ACCESS_ERROR Error accessing licensemeter(s). Pleasemakesure the Sentinel System Driver is properlyinstalled and a licensemeter is attached to theparallel port or USB port.

43 VLScg_LICMETER_COUNTER_TOOLOW Too few units (Normal License Count=%d/ TrialLicense Count= %d) left in your Sentinel RMSDevelopment Kit licensemeter(s) to generaterequested license. %d units required.

44 VLScg_LICMETER_CORRUPT Your Sentinel RMS licensemeter(s) are cor-rupted.

45 VLScg_LICMETER_VERSION_MIS-MATCH

Your Sentinel RMS Development Kit licensemeter has an invalid version.

46 VLScg_LICMETER_EMPTY All <value> units of your Sentinel RMS Devel-opment Kit licensemeter(s) have been used up.License generation will fail.

Error#


47 VLScg_PORTSERV_ EXCEPTION Unknown exception (<value>) in accessing Sen-tinel RMS Development Kit portable server(s).

48 VLScg_PORTSERV_ ACCESS_ERROR Error accessing Sentinel RMS portable server(s).Pleasemake sure one is attached.

49 VLScg_PORTSERV_VERSION_MIS-MATCH

Your Sentinel RMS license server has an invalidversion (<value>.<value>) for commuterlicenses. Expected <value>.<value>.

50 VLScg_PORTSERV_CORRUPT Your Sentinel RMS Development Kit portableserver(s) are corrupted.

51 VLScg_EXPIRED_LICENSE Your software license has expired.

52 VLScg_INVALID_LICTYPE Invalid License Type.

53 VLScg_INVALID_TRIALDAYS Invalid Trial Days.

54 VLScg_INVALID_TRIAL_COUNT Invalid Trial License Count.

55 VLScg_TRIALMETER_EMPTY All <value> units of your Sentinel RMS Devel-opment Kit Trial licensemeter(s) have beenused up.

56 VLScg_TRIAL_SUCCESS Your trial licensemeter(s) have been dec-remented by <value> units. You now have<value> units left.

57 VLScg_NO_NETWORK_AUTHOR-IZATION

Your Sentinel RMS Development Kit licensemeter(s) have No authorization to generate Net-work Licenses.

58 VLScg_NO_ENABLE_FEATURE No feature is enabled.

59 VLScg_VI18N_INITIALIZE_FAIL Error in updating locale.

60 VLScg_INVALID_NUM_SERVERS Invalid number of servers.

61 VLScg_NO_CAPACITY_AUTHORIZATION Your licensemeter(s) have no authorization togenerate capacity licenses.

VLScg_UPGRADE_NOT_ALLOWED Your licensemeter(s) have no authorization togenerate upgrade licenses.

70 VLScg_LICMETER_NOT_SUPPORTED Your licensemeter is not supported.

71 VLScg_INCORRECT_BASE_FEATURE_VAL

The base feature is too high for supportingdesired number ofmulti-features.

72 VLScg_ENCRYPTION_FAIL License code encryption failed.

73 VLScg_INVALID_CAPACITY_SETTINGS Invalid capacity setting done in code structure.

74 VLScg_EXP_DATE_BEFORE_START_DATE

License expiration date is set before the licensestart date.

75 VLScg_INVALID_TRIALHOURS Invalid trial elapsed hours.

77 VLScg_GETLOCK_FAIL Process lock request failed.



Error#


78 VLScg_GETLOCK_TIMEOUT Process lock request timeout.

79 VLScg_VENDOR_DECRYPTION_FAIL Vendor decryption failed.

80 VLScg_RT_VERSION_MISMATCH Version value found in the revocation ticketdoes not match with that specified in requeststructure.

81 VLScg_RT_REHOST_LINE_CORRUPT One or more operation-specific information inthe revocation ticket is invalid.

82 VLScg_RT_TRANSACTION_ID_MIS-MATCH

The transaction ID value found in the rev-ocation ticket does not match with that spec-ified in request structure.

83 VLScg_RT_LOCK_CODE_MISMATCH The lock code value found in the revocationticket does not match with that specified in therequest structure.

84 VLScg_RT_REQUESTED_ACTION_NOT_PERFORMED

One or more operation(s) specified in therequest structure is/are not performed at clientside as corresponding information is not foundin revocation ticket.

85 VLScg_RT_NON_REQUESTED_ACTION_PERFORMED

The request structure does not specify one ormore operation(s) corresponding to which infor-mation is found in revocation ticket.

86 VLScg_RT_ACTION_STATUS_NOT_SUC-CESS

The requested operation is not successfully per-formed at the client-end.

87 VLScg_RT_REQUEST_EMPTY The request struture does not specify any oper-ation.

88 VLScg_RT_REQUEST_LINE_INVALID The request structure specified an invalid oper-ation.

89 VLScg_RT_REHOST_TICKET_INVALID_TLV_STRUCT

The revocation ticket is invalid.

90 VLScg_RT_REHOST_TAG_MISSING The rehost tag is not found in the revocationticket.

91 VLScg_RT_VERSION_TAG_MISSING The version tag is not found in the revocationticket.

92 VLScg_RT_TRANSACTION_ID_TAG_MISSING

The transaction ID tag is not found in the rev-ocation ticket.

93 VLScg_RT_LOCK_SELECTOR_TAG_MISS-ING

The lock selector tag is not found in the rev-ocation ticket.

94 VLScg_RT_LOCK_SELECTOR_MIS-MATCH

The lock selector value found in the revocationticket does not match with that specified in therequest structure.

Error#


95 VLScg_RT_LOCK_CODE_TAG_MISSING The lock code tag is not found in the revocationticket.

96 VLScg_RT_REHOST_LINE_TAG_MISS-ING

The rehost line tag is not found in the rev-ocation ticket.

97 VLScg_RT_HASH_TAG_MISSING The hash tag is not found in the revocationticket.

98 VLScg_RT_TIME_STAMP_MISMATCH The time stamp value found in the revocationticket does not match with that specified in therequest structure.

99 VLScg_RT_TIME_STAMP_TAG_MISS-ING

The time stamp tag is not found in the rev-ocation ticket.

100 VLScg_RT_VERIFY_SINGLE_ERROR The revocation ticket reported a single error.

101 VLScg_RT_VERIFY_MULTIPLE_ERRORS The revocation ticket reported multiple errors.

102 VLScg_RT_BUFFER_TOO_SMALL The buffer is too small.

103 VLScg_RT_PARAMETERS_ERROR A parameters-related error is encountered.

104 VLScg_RT_ALLOCATE_MEMORY_FAIL-URE

Amemory allocation failure.

105 VLScg_RT_UNSUPPORTED_OPER-ATION_TYPE

The operation type is not supported.

106 VLScg_RT_INVALID_REQUEST_DATA An invalid rehost request data.

107 VLScg_RT_TAG_NOT_FOUND The tag cannot be found in TLV.

108 VLScg_BUFFER_TOO_SMALL The buffer is too small.

109 VLScg_RT_INSUFFICIENT_TOKENS_TO_REVOKE

The license tokens available for revocation areless than the number specified in the per-mission ticket.

110 VLScg_RT_MIXED_OPERATION_TYPE_UNSUPPORTED

You cannot revoke stand-alone and networklicenses using a single permission ticket.

111 VLScg_RT_INFINITE_LIC_FINITE_REQ Network licenses with infinite tokens cannot bepartially revoked. Full revocation is required.

112 VLScg_RT_RDNT_LIC_UNSUPPORED The permission ticket cannot be generated forredundant licenses.

113 VLScg_RT_CORRUPT_ORIG_REQ The permission ticket provided for verification iscorrupt.

114 VLScg_RT_CUSTOM_DATA_TAG_MISS-ING

The custom defined data tag is not found in therevocation ticket.

115 VLScg_RT_CUSTOM_DATA_MISMATCH The custom defined data included in the per-mission ticket and revocation ticket does notmatch.

116 VLScg_RT_REVOCATION_TYPE_MIS-MATCH

Either standalone revoke request is provided to



Error#


verify with a network revocation ticket, or viceversa.

117 VLScg_TOO_MANY_OPERATIONS_FOR_SINGLE_PT

The number of operations specified in the per-mission ticket exceed themaximum limit. Youcannot specify more than 15 operations in a per-mission ticket for a network license revocation.

118 VLScg_VENDOR_ID_MISMATCH Vendor ID mismatch. The permission ticket can-not be generated for licenses of other vendors.

119 VLScg_CODGEN_VERSION_UNSUP-PORTED

The permission ticket generation not supportedfor licenses earlier than version 11.

130 VLScg_RESERV_CHAR_ERR The reserved characters are used. See AboutReserved Characters and Strings.

131 VLScg_LOWER_THAN_MIN_STRLEN The string length is lower than theminimumallowed.

A.3. Upgrade License Error CodesThe following table lists upgrade license code generation return codes and their default messages:

Error# Return Code Default Message

0 VLScg_SUCCESS Success

2 VLSucg_NO_FEATURE_NAME Feature Namemust be specified. It cannot beempty.

3 VLSucg_INVALID_INT_TYPE Expected an integer value, found “XXX”

4 VLSucg_EXCEEDS_MAX_VALUE

Value entered is greater than themaximum sup-ported value.

5 VLSucg_LESS_THAN_MIN_VALUE

Value entered is less than theminimum supportedvalue.

6 VLSucg_EXCEEDS_MAX_STRLEN

Length of <value> is greater than <value>.

7 VLSucg_NOT_MULTIPLE Value should be a multiple of “XXX”.

11 VLSucg_INVALID_HEX_TYPE Wrong value entered. (Should be hexadecimal)

14 VLSucg_RESERV_STR_ERROR <Value> is a reserved string.

16 VLSucg_INVALID_CHARS Invalid characters.

20 VLSucg_DECRYPT_FAIL Decryption failed for license code.

22 VLSucg_INVALID_CHKSUM Checksum validation failed for license code. Pleaseverify the license code.

26 VLSucg_MALLOC_FAILURE Out of heap memory.

27 VLSucg_INTERNAL_ERROR Internal error.

30 VLSucg_INVALID_INPUT Invalid input.

31 VLSucg_MAX_LIMIT_CROSSED

Maximum limit crossed.

32 VLSucg_NO_RESOURCES No resources left.

33 VLSucg_BAD_HANDLE Bad file handle.

34 VLSucg_FAIL Operation failed.

35 VLSucg_INVALID_VENDOR_CODE

Invalid Vendor Code. Please contact your SentinelRMS Development Kit distributor.

36 VLSucg_VENDOR_ENCRYP-TION_FAIL

Vendor-customized encryption failed.

40 VLSucg_LICMETER_EXCEP-TION

Unknown exception in accessing Sentinel RMSDevelopment Kit licensemeter(s).

41 VLSucg_LICMETER_DEC-REMENT_OK

Your licensemeter(s) have been decremented by<value> units. You now have <value> units left outof an initial count of <value> units.

42 VLSucg_LICMETER_ACCESS_ERROR

Error in accessing the licensemeter(s). Please

A.3. Upgrade License Error Codes 511


Error# Return Code Default Message

make sure the Sentinel System Driver is properlyinstalled and a licensemeter is attached to the par-allel port or USB port.

44 VLSucg_LICMETER_CORRUPT Your licensemeter(s) are corrupted.

45 VLSucg_LICMETER_VERSION_MISMATCH

Your licensemeter has an invalid version.

46 VLSucg_LICMETER_EMPTY All <value> units of your licensemeter(s) havebeen used up. License generation will fail.

52 VLSucg_INVALID_LICTYPE Invalid License Type.

59 VLSucg_VI18N_INITIALIZE_FAIL

Error in updating locale.

61 VLSucg_NO_CAPACITY_AUTHORIZATION

Your licensemeter(s) have no authorization to gen-erate Capacity Licenses.

62 VLSucg_NO_UPGRADE_AUTHORIZATION

Your licensemeter(s) have no authorization to gen-erate Upgrade Licenses.

63 VLSucg_NO_UPGRADE_CODE Upgrade Codemust be specified. It cannot beempty.

64 VLSucg_INVALID_BASE_LIC_INFO

The information-feature name, version and ven-dor code, provided for base license is incorrect.

65 VLSucg_CAPACITY_UPD_NOT_ALLOWED

Capacity upgrade is not allowed, as the base lic is anon-capacity license.

66 VLSucg_INVALID_UPGRADE_CODE

Invalid upgrade code.

67 VLSucg_LICMETER_COUNTER_TOOLOW

Too few units (Normal License Count=%d) left inyour licensemeter(s) to generate requestedlicense. %d units required.

69 VLSucg_LICMETER_NOT_SUP-PORTED

Your licensemeter is not supported.

A.4. System Initialization Error Codes The LSINIT functions will return the ORed value of the [first-level status code] and [second-level statuscode]. 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 bewritten.

You can decipher these status codes as described below:

Hexadecimal Code Status Code Description

First Level Status Codes

0x10000000 ERR_TIME_TAMPER_INIT_FAIL

Time Tamper Initialization Fail-ure

0x20000000 ERR_COMMUTER_PRS_INIT_FAIL

Commuter Initialization Failure

0x40000000 ERR_GRACE_PRS_INIT_FAIL

Grace License Initialization Fail-ure

0x80000000 ERR_TRIAL_INIT_FAIL

Trial License Initialization Failure

0xF0000000 ERR_STDRVK_INIT_FAIL

Standalone Revocation Initial-ization Failure

0x01000000 ERR_CONSUME_INIT_FAIL

VTL Initialization Failure

Second Level Status Codes

0x00000000 ERR_KEY_INFO_SUCCESS

Success

0x00000001 ERR_INVALID_INPUT

Invalid Input

0x00000002 ERR_INIT_LIB_FAIL Library Initialization Failure

0x00000008 ERR_INIT_INFO_EXISTS

Already Initialized

0x00000010 ERR_INIT_SEC_FAIL

Permissions failure on secureinformation

0x00000020 ERR_INIT_KEY_FAIL

Failed to create registry infor-mation (only for Windows)

0x00000040 ERR_INIT_KEY_SEC_FAIL

Permission failure for secure reg-istry (only for Windows)

0x00000080 ERR_INIT_OPEN_KEY_FAIL

Registry open failure (only forWindows)

0x00000100 ERR_INIT_SET_ Write failure on secure registry

A.4. System Initialization Error Codes 513


Hexadecimal Code Status Code Description

VALUE_FAIL (only for Windows)

0x00000200 ERR_INIT_QUERY_FAIL

Read failure on secure registry(only for Windows)

0x00000400 ERR_INIT_FILE_FAIL

File creation failure

0x00000800 ERR_INIT_FILE_OPEN_FAIL

File open failure

0x00001000 ERR_INIT_FILE_WRITE_FAIL

Write failure on secure file

0x00002000 ERR_INIT_FILE_SEC_FAIL

Permissions failure on secure file

0x00004000 ERR_EXCEPTION_OCCURED

An exception occurred duringexecution

0x00008000 ERR_INIT_FILE_INFO_EXISTS

Initialization file informationexits

0x00010000 ERR_INTERNAL_FAIL

Internal error

0x00020000 ERR_INSUF-FICIENT_PER-MISIONS

Access denied for read or writesecure data

0x00040000 ERR_TAMPER_DETECTED

Secure data is tampered

0x00080000 ERR_INIT_PATH_FAILED

Error retrieving persistence data-base location

0x00100000 ERR_INIT_FILE_READ_FAIL

Error encountered in readingpersistence file(s)

0x00200000 ERR_NORE-SOURCES

Failure in obtaining systemresources

0x00400000 ERR_LOCK_ERROR Resource lock failure

0x00800000 ERR_INIT_CON-FIG_FAIL

Error encountered in setting trialpersistence file location

A.5. Persistence Cleaning Error CodesThe persistence cleaning API can return any of the following error codes:

HexadecimalCode

Status Code Description

0xC8010001 VLScl_ILLEGAL_VENDOR_ID The library does not have a valid serialnumber information.

0xC8010002 VLScl_INSUFFICIENT_PERMISIONS If the application calling the API is runin non administrator user mode.

0xC8010003 VLScl_INVALID_ARGUMENTS If a wrong value or combination ofarguments is passed.

0xC8010004 VLScl_NO_TRIAL_FEATURE_IN_USE If the trial information of the given fea-ture-version is not found.

0xC8010005 VLScl_NO_COMMUTER_FEATURE_IN_USE If the commuter information of thegiven feature-version is not found.

0xC8010006 VLScl_NO_GRACE_INFORMATION_FOUND

If the grace information of the givenfeature-version is not found.

0xC8010007 VLScl_NO_REVOKE_INFORMATION_FOUND

The revocation information of thegiven feature-version is not found.

0xC8010008 VLScl_NORESOURCES Amemory related error (malloc, etc.)has occurred.

0xC8010010 VLScl_RESOURCE_LOCK_FAILURE Failed to acquire an API lock. The APIshould be recalled on receiving thiserror.

0xC8010009 VLScl_INTERNAL_ERROR An internal error.

0xC8010011 VLScl_NO_COMMUTER_INFO_FOUND No commuter persistence infor-mation is found for the given feature-version. Probably, no commutertokens are checked out for this fea-ture-version, or when there are com-muter check outs for other feature-version(s).

A.5. Persistence Cleaning Error Codes 515

Appendix B:Customization Features

Sentinel RMS provides a number of libraries to enable you to re-build the license server, code gen-erator executable, and override certain predefined features. In addition, few files and APIs are also pro-vided to allow customizations.

The table below lists the various customization features available in stand-alone or network licensingor both:

CustomizationNetworkLicensing

Stand-aloneLicensing

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 releaseevents

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 fingerprintcaching

Setting custom client information (username and hostname)

B

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 FunctionsRMS provides static libraries for all the customizablemodules. The customizable functions are pre-defined in these libraries. To override the default functions, you need to define the customizable func-tions and rebuild the executables using the static libraries. The resultant executables will contain thefunctions 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 theVLSdecryptLicense function in lic_decrypt.obj.

An Example Showing a Customized Implementation of License Decryption

B.1. Architecture of Overriding the Functions 519


B.2. Vendor-specified License Server InitializationUsing the VLSserverVendorInitialize function, you can register the following:

n The license server hooksn The custom Host ID lock functionn The custom extended lock functionn 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 performvendor-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 StringTo uniquely identify the license server, you can set unique license server information—a string con-sisting 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 licenseserver by setting the vendor -specific information in the license server. This information can bereturned to the client using the VLSgetServInfo function.


LSERV_STATUS VLSsetServerInfo

(

char **vendorInfo

);

B.3.4. Returns

n Returns LSERV_STATUS_SUCCESS on success.

n Returns non-zero on failure.

Parameter Description

vendorInfo An OUT parameter.A pointer to string of up to 50 characters to write to license server as iden-tification.


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.

B.3. Vendor-specified License Server Identification String 521


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 ServerBy default, the license server communicates at port number 5093. If required, you can set it to anyother 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.


n The license server (lservnt.exe) needs to be rebuild.

n The client application.

B.4.2. Description

Sets a new port number for the client-server communication.


int VLSchangePortNumber

(

int currentPort

);

B.4.4. Returns

Returns the new port number set for the client-server communication.


currentPort An IN parameter.The current port number used for communication.


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 toobtain the current port number.

4. Follow the procedure described in Build Procedure.

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


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 (meantfor redistribution)must also bemodified to reflect this change:

n lsmon

n lslic

n lswhere

There are two ways to do this:

n You can edit the default port using the VLSsetServerPort API and rebuild the utilities.

The source code of these utilities is provided in the \MsvcDev\Samples\API directory.

n You may instead remove the corresponding line (for example, VLSsetServerPort(SERVER_PORT) from the lsmon.c file) from the source code files of these utilities. And, your customerscan set the port using the LSPORT environment variable. However, remember that the portset in the source code overrides the one set using the environment variable.

B.5. Installing Hooks on Pre/Post Request and Release EventsYou can add hooks on the following events:

n Pre-request

n Post-request

n Pre-release

n Post-release

In the "pre" hook, you can decide on the licensing action, such as looking up the external informationbefore granting a request.

In the post hook, you cannot change the license decision but can provide custom information to theclient.


n In case of stand-alone licensing (application linked to the stand-alone library or the integratedlibrary), the client application needs to be rebuild.

n 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. Cur-rently, 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 arequest 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.

B.5. Installing Hooks on Pre/Post Request and ReleaseEvents

525



eventName An IN parameter.Specifies the type of event:

n LS_REQ_PRE - The handler function will be called right before thelicense server processes the license request.

n LS_REQ_POST - The handler function will be called right after thelicense server processes the license request.

n LS_REL_PRE - The handler function will be called right before thelicense server processes the license release.

n LS_REL_POST - The handler function will be called right after thelicense server processes the license release.

handlerFuncPtr An IN parameter.The callback function for specified event.

identifier An IN parameter.The client identifier to match.

B.5.5. Function Prototype (of the Callback Function)

int HandlerFunc

(

VLShandlerStruct* pHandlerStruct, /* IN */

char* inBuf /* IN */

char* outBuf /* OUT */

int outBufSz /* IN */

);

B.5.6. Returns

n Returns LSERV_STATUS_SUCCESS on success.

n Returns LSERV_STATUS_DENY on failure.


pHandlerStruct A pointer to VLShandletStruct containing client information, feature infor-mation, various file information and miscellaneous information.

inBuf The null-terminated string containing the input message.

outBuf A pointer to buffer that receives the output message.

outBufSz The size of the buffer pointer by outBufSz.


1. Create the hook functions. For example, LSReqPreHook, LSReqPostHook, LSRelPreHook andLSRelPostHook.

2. Update the SERVER_HOOK_OBJS variable in the custom32.mak file.

3. Register the hook functions in the license server.


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 out-BufSz);LSERV_STATUS VLSserverVendorInitialize(void){

VLSeventAddHook(LS_REQ_PRE, &GetCustomExValue, "Hook1");return LSERV_STATUS_SUCCESS;

}

B.5. Installing Hooks on Pre/Post Request and ReleaseEvents

527


B.6. Protection Against Time TamperingTo configure or override the built-in time tampering detection function, you can use the informationprovided in this section.




Please refer to Build Procedure.

B.6.2. Description

Following are some of the configurable properties used by the built-in time tampering detection func-tion of RMS.

n The action taken on time tampering detection

n Themethod of time tampering detection

n The default grace period

n The number or percentage of system files found to be tampered before concluding the sys-tem clock is tampered (for UNIX only).

Using the VLSconfigureTimeTamper API function you can modify the configurable properties.


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;

typedef enum {

VLS_ENABLE_DEFAULT_TM_TAMPER,

VLS_DISABLE_DEFAULT_TM_TAMPER

}VLStmTamperMethod;


actionOnTmTamper An OUT parameter.Whether to exit from the license server (or your application, in case ofstand-alone licensing) once the system clock tampering is detected.[Default: VLS_CONT_AFTER_TM_TAMPER]

tmTamperMethod An OUT parameter.Whether to use the built-in system clock tampering detection function,or use the one provided by you.[Default: VLS_ENABLE_DEFAULT_TM_TAMPER]

gracePeriod An OUT parameter.Useful only in case tmTamperMethod is VLS_ENABLE_DEFAULT_TM_TAMPER. If RMS finds the system clock has been set back by less thanthe gracePeriod seconds, it will not count the offending system file as aviolation.[Default: 86,400 seconds (1 day)]

percentViolations An OUT parameter.The percentage of the system files that must be found in violation ofthe grace period before concluding that the system clock has been setback. 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]

numViolationsForError An OUT parameter.The number of system files that must be found in violation of the graceperiod, before concluding that the system clock has been set back.Applicable only to UNIX systems.

If both percentViolations and numViolationsForError are used, the lower evaluated value will be used.

If the tmTamperMethod parameter is returned as VLS_DISABLE_DEFAULT_TM_TAMPER, then youmust override the VLSisClockSetBack function.


int VLSisClockSetBack(void);

B.6.6. Returns

n Returns 0 (zero) if the clock is found in non-tampered state.

n Returns non-zero if the clock is found in tampered state.

B.6. Protection Against Time Tampering 529



1. Create the VLSconfigureTimeTamper function.

2. If the tmTamperMethod parameter is returned as VLS_DISABLE_DEFAULT_TM_TAMPER, thencreate the VLSisClockSetBack function.

3. Update the TIME_TAMPER_OBJS in the custom32.mak file.

4. Follow the build procedure specified in "Build Procedure" section.


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




n lscgen.exe

n lsdecode.exe

n wlscgen.dll

B.7.2. Description

Provides the vendor-specified an extra layer of encryption and decryption for the license codes.

B.7.3. Encryption Function Prototype

int VLSencryptLicense

(

char *decrypted_mesg,

char *encrypted_mesg,

int size

);

B.7.4. Returns

n Returns 0 (zero) on success.



decrypted_mesg An IN parameter.The original license code.

encrypted_mesg An OUT parameter.The encrypted license code.

size An IN parameter.




The size of the encrypted_mesg buffer.

Please note that the encrypted licenses codemust not contain following characters:

Character Hex Value Description

\t 0x09 The tab character

\n 0x0A The new-line character

# 0x23 The pound sign or number sign or hash mark

( 0x28 The opening round parentheses

) 0x29 The closing round parentheses

, 0x2C The commamark

- 0x2D The hyphen or dash or minus sign

B.7.5. Decryption Function Prototype

int VLSdecryptLicense

(



int size

);

B.7.6. Returns




encrypted_mesg An IN parameter.The encrypted license code.

decrypted_mesg An OUT parameter.The original license code.

size An IN parameter.The size of the decrypted_mesg buffer.


1. Create the VLSencryptLicense function.

2. Create the VLSdecryptLicense function.

3. Update the ENCRYPT_LIC_OBJS variable in the custom32.mak file.

4. Update the DECRYPT_LIC_OBJS variable in the custom32.mak file.



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)

{


}

if (size == 0)

{


}

/* TODO: add the encryption code here */return 0; /*successful encryption */

}

The VLSdecryptLicense Function

int VLSdecryptLicense



(

char *encrypted_mesg, /* IN */

char *decrypted_mesg, /* OUT */int size /* IN */

)

{

if (encrypted_mesg == NULL)

{


}

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 CodesThe upgrade licenses generated using RMS are encrypted using proprietary encryption algorithm.However, for enhanced security, you can add an additional layer of encryption while generatingupgrade licenses.




n ulscgen.exe

n ulsdcod.exe

B.8.2. Description

Provides the vendor-specified extra layer of encryption and decryption for communication between aclient and the license server.


int VLSencryptUpgradeLicense

(



int size

);

B.8.4. Returns




decrypted_mesg An IN parameter.The original upgrade license code.

encrypted_mesg An OUT parameter.The encrypted upgrade license code.

size An IN parameter.The size of the encrypted_mesg buffer.

B.8. Encrypting the Upgrade License Codes 535



int VLSdecryptUpgradeLicense

(



int size

);

B.8.6. Returns




encrypted_mesg An IN parameter.The encrypted upgrade license code.

decrypted_mesg An OUT parameter.The original upgrade license code.



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.



Refer to the code snippets of VLSencryptLicense and VLSdecryptLicense.

B.9. Encrypting License Server MessagesIn RMS, the entire network communication is encrypted. However, you can add an additional layer ofencryption and decryption for enhanced security. This customization requires changes in the licenseserver as well as the client application.

In case of stand-alone licensing, since the license server module is part of the client library itself, this

extra layer of encryption is not required.

B.9.1. Executables Need to be Rebuild

n The license server (lservnt.exe).

n The client application.

Please refer to Build Procedure.

B.9.2. Description

Provides the vendor-specified extra layer of encryption and decryption for communication between aclient and the license server.


int VLSencryptMsg

(



int size

);

B.9.4. Returns




decrypted_mesg An IN parameter.The original network message.

encrypted_mesg An OUT parameter.The encrypted network message.

size An IN parameter.The size of the encrypted_mesg buffer.

B.9. Encrypting License Server Messages 537



int VLSdecryptMsg

(



int size

);

B.9.6. Returns




encrypted_mesg An IN parameter.The encrypted network message.

decrypted_mesg An OUT parameter.The original network message.



1. Create the VLSencryptMsg function.

2. Create the VLSdecryptMsg function.

3. Update the ENCRYPT_MSG_OBJS variable in the custom32.mak file.

4. Update theDECRYPT_MSG_OBJS variable in the custom32.mak file.



Refer to the code snippets of VLSencryptLicense and VLSdecryptLicense.

B.10. Vendor-specified 4-Byte Custom Fingerprint of aSystemRMS provides you the capability to have a vendor specified customized 4-byte fingerprint along withthe standard fingerprints of a system.



n In case of network licensing, the license server (lservnt.exe) needs to be rebuild only if thelicenses are server-locked and the client application needs to be rebuild only if the licenses areclient-locked.

n echoid.exe

n wechoid.exe

B.10.2. Description

For the server-locked licenses, locking is verified at the time of loading/adding licenses. For the client-locked licenses, locking is verified at the time of license request. Apart from the standard fingerprintsof a system, you can lock licenses to a hardware device (dongle) or a software-based implementationto generate a unique 4-byte value. You have to implement a customized Host ID function that needsto be registered using the VLSsetHostIdFunc function. This function must return an unsigned longvalue based on the customized logic that is unique for each system.

B.10.3. Function Prototype (of the Callback Function)

unsigned long GetCustomValue(void);


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 func-tion name in <installdir>\MsvcDev\Samples\API\echomain.c. Search for the call of VLSse-tHostIdFunc.

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


6. If the custom host ID function name is different from “GetCustomValue”, then update the func-tion name in <installdir>\MsvcDev\Samples\API\ wechoiddlg.cpp. Search for the call of VLSse-tHostIdFunc.



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 bedone in the VLSserverVendorInitialize function.

#include "lserv.h"extern unsigned long GetCustomValue();LSERV_STATUS VLSserverVendorInitialize(void){

VLSsetHostIDFunc(&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 inVLSserverVendorInitialize.

#include "lserv.h"extern unsigned long GetCustomValue();int main(int argc, char* argv[]){

VLSinitialize();VLSsetHostIDFunc(&GetCustomValue);/* here client application code */return 0;

}

B.11. Vendor-specified Custom Extended Fingerprint of aSystemRMS provides you the capability to have a vendor specified extended 64-byte fingerprint along withthe standard fingerprints ofmachine.


n In case of stand-alone licensing (application linked with the stand-alone library or the inte-grated library), the client application needs to be rebuild.

n In case of network licensing, the license server (lservnt.exe) needs to be rebuild only if thelicenses are server-locked and the client application needs to be rebuild only if the licenses areclient-locked.

n echoid.exe

n wechoid.exe

B.11.2. Description

For server locked licenses, locking is verified at the time of loading/adding licenses to server, while forclient locked licenses, locking is verified at the time of request. Apart from the standard fingerprint ofmachine, you can lock licenses on some kind of hardware device (dongle) or software based imple-mentation to generate a unique extended custom value for each machine. You have to implement afunction 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 definemultiple extended custom locking value and store it in individual element ofVLScustomEx array. Themaximum number allowed is VLS_MAX_CUSTOMEX_COUNT. Please referlserv.h for its value.


pCustomExTable An OUT parameter.A pointer to the array of the VLScustomEx structure. If passed as NULL,then as an output pulCountwill contain the required number of elementsin array pointed by this parameter.

pulCount An IN/OUT parameter.A pointer to unsigned long that specifies the number of elements in the




array pointed by the pCustomExTable parameter.

On input, the pulCount parameter of the extended custom function should specify the count of theVLScustomEx array pointed to by the pCustomExTable parameter. If the buffer is not large enough tohold the returned customEx fingerprint table, the function should set this parameter equal to therequired count.

On output, the function should update the pulCount parameter value to specify the actual count ofthe VLScustomEx objects that are received through this custom function.

B.11.4. Returns

n Returns LS_SUCCESS(0) on success.



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 updatethe function name in <installdir>\MsvcDev\Samples\API\echomain.c. Search for the call of theVLSsetCustomExFunc function.

6. If the extended custom lock function name is different from “GetCustomExValue”, then updatethe function name in <installdir>\MsvcDev\Samples\API\ wechoiddlg.cpp. Search for the callof the VLSsetCustomExFunc function.



Create the Extended Custom Lock Function

long GetCustomExValue(

VLScustomEx* pCustomExTable, /* OUT */unsigned long* pulCount /* IN/OUT */

){

if (pulCount == NULL){

return 1; /* non-zero to mark failure */}if ((*pulCount == 0) || (*pulCount > VLS_MAX_CUSTOMEX_COUNT)){

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 partneeds to be done in the VLSserverVendorInitialize function.

#include "lserv.h"extern long GetCustomExValue(VLScustomEx* pCustomExTable, unsigned long* pulCount);LSERV_STATUS VLSserverVendorInitialize(void){

VLSsetCustomExFunc(&GetCustomExValue);return LSERV_STATUS_SUCCESS;

}

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

#include "lserv.h"extern long GetCustomExValue(VLScustomEx* pCustomExTable, unsigned long* pulCount);int main(int argc, char* argv[]){

VLSinitialize();VLSsetCustomExFunc(&GetCustomExValue);/* here client application code */return 0;

}



B.12. Customizing the Stand-alone License File NamesTo 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 servershould operate. For stand-alone applications, these files are:

n lservrc - The license file, which contains one or more license strings.

n lservrccnf - The license server configuration file, which contains license server options.

Although you can change the names of these files by using the appropriate environment variable, thiscan cause a conflict if multiple stand-alone applications from different developers are installed on thesame computer since only one environment variable affects the entire computer. If environment var-iables aren't used, a different developer can overwrite the default license file when a new application isinstalled.

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;


LS_STATUS_CODE VLSsetFileName

(

VLS_FILE_TYPE filetype, /*IN*/

unsigned char* fileName,/*IN*/

unsigned char* unused1,

unsigned long* unused2

);

B.12.5. Returns

n Returns LS_SUCCESS(0) on success.



filetype An IN parameter.The type of license file (lservrc, lservrccnf, or ULSERVRC) or configurationfile you are going to provide a customized location/name.

fileName An IN parameter.The custom name that you want to use.

unused1 Reserved, Use NULL for this value.

unused2 Reserved, Use NULL for this value.


1. Call the VLSsetFileName function in client application before the VLSinitialize function call.


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;

}

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


B.13. Configuration File to Customize the Standard CustomFingerprint CachingSince the 8.2.x release, fingerprint caching was allowed to improve the performance while loadingstand-alone licenses (it reduced the load time typically when fingerprints—such as IP address, disk ID,host name, Ethernet address, computer ID key, and hard disk serial number—were used). However,this default caching conflicted with the standard custom locking when fingerprint values changeddynamically.

To overcome this, since the 8.3.0 release (Windows) and 8.4.1 release (non-Windows), you can use aconfiguration 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 OptionDefault FingerprintCaching (ON\OFF)

Caching Customization OptionProvided?

n IP addressn Disk IDn Host namen Ethernet addressn Computer ID keyn Hard disk serial numbern ID PROMn Processor ID

ON No.

You cannot disallow the default cach-ing setting.

Standard Custom ON Yes. Using the configuration file (asdescribed in this topic).

You are recommended to disablecaching using the configuration file incase ofmultiple standard customcriteria or when these change dynam-ically. For example, if license 1 islocked on UID 1 and license 2 islocked UID 2, you should use the con-figuration file to disable caching. Else,the first fingerprint retrieved will becached.

Extended Custom OFF No.

You can implement your own cachingmechanism as described in the cust-exlock sample (available at: <install-dir>\Samples\Customizecomponents for Windows)

B.13.1. Configuration File for Customizing Standard Custom

The configuration file can have theMACHINEIDCACHE section with the key-value pairs for Cus-tomLockCachingOff.

Where,

n Setting the value of CustomLockCachingOff key as 1 and 0, turns off and on the caching ofextended custom lock fingerprint, respectively.

n 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 fin-gerprint

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 Stand-alone License File Names). The new value is VLS_GENERICCONF added to the enum VLS_FILE_TYPEdefined 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 theapplication directory.

Notes:

The fingerprints will be cached under the following scenarios:

n When the configuration file is not set using the API VLSsetFileName.

n When the configuration file is set, but does not exist.

n When the configuration file exists, but the required section is not present.

n When the configuration file and the required section exist, but the required key is not presentin that section.

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


B.14. Setting Custom Client InformationYou can set custom client information—username and hostname—using a new client side API VLSset-CustomData. This information is passed to the license server when a license request API or its variantis called. It can then be retrieved through the:

n License server usage logs (in the user and host name fields of the log file)

n Query APIs (VLSgetClientInfo and VLSgetHandleInfo)

n WlmAdmin and lsmon utilities


LS_STATUS_CODE VLSsetCustomData

(

VLScustomData *pCustomData /*IN*/

);

B.14.2. Description

The API sets the custom client information—username and hostname. It takes a pointer to the struc-ture VLScustomData.

To set the custom user information, call VLSsetCustomData before the license request API, but afterthe system initialization API. If the VLSsetCustomData API is not called at all (or not called in the cor-rect 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 callthe API individually for each client instance.

If the API VLSsetSharedId or VLSsetSharedIdValue is called, it overrides the value set by the VLSset-CustomData API. This is because the former APIs can also set the username or hostname based on thesharedID value.

B.14.3. Parameters


VLScustomData An IN parameter.

Before passing the pointer to this structure, ensure that structSz field ofVLScustomData 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 The custom user information cannot exceed 31 bytes.n It cannot contain the following special characters:

n `~!@#$^&*()=+[]{}\|;:',/?<>"n Space, tab, and new line

B.14.4. Returns

Error Description

VLS_LIBRARY_NOT_INITIALIZED

When this API is called before VLSinitialize

VLS_CALLING_ERROR

n The username or hostname contain special characters (mentioned above).n The VLSsetCustomData API is called with NULL as its input parameter.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.

B.14. Setting Custom Client Information 549


B.15. Build Procedure

B.15.1. How to Use the custom32.mak File?

TheMakefile (custom32.mak), located at <installdir>\English\MsvcDev\Samples\Customize com-ponents>, is used for building the following customized executables:

n lservnt.exe - The license server.

n lscgen.exe - The command-line license code generator.

n lsdecode.exe - The command-line license code decoder.

n ulscgen.exe - The command-line license upgrade code generator.

n ulsdcod.exe - The command-line license upgrade code decoder.

n echoid.exe - The command-line utility to obtain the system fingerprint.

n wechoid.exe - AWindows-based graphical utility to obtain the system fingerprint.

n wlscgen.dll - A vendor-specified extra layer of encryption the plug-in forwlscgen.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

n VENDOR_INFO_OBJS

n CHANGE_PORT_OBJS

n SERVER_HOOK_OBJS

n TIME_TAMPER_OBJS

n ENCRYPT_LIC_OBJS

n DECRYPT_LIC_OBJS

n ENCRYPT_UPG_LIC_OBJS

n DECRYPT_UPG_LIC_OBJS

n ENCRYPT_MSG_OBJS

n DECRYPT_MSG_OBJS

n CUSTOM_LOCK_OBJS

n CUSTOM_EX_LOCK_OBJS

The following tables depicts the relationship between the above-mentioned defines and the execut-ables:

Defines in custom32.mak Network Stand-alone

SRV_VENDOR_INIT_OBJS lservnt.exe The client application

VENDOR_INFO_OBJS lservnt.exe NA

CHANGE_PORT_OBJS n lservnt.exen Client application

NA

SERVER_HOOK_OBJS lservnt.exe The client application

TIME_TAMPER_OBJS lservnt.exe The client application

ENCRYPT_LIC_OBJSDECRYPT_LIC_OBJS

n lservnt.exen lscgen.exen lsdecode.exen wlscgen.dll

n Client Applicationn lscgen.exen lsdecode.exen wlscgen.dll

ENCRYPT_UPG_LIC_OBJSDECRYPT_UPG_LIC_OBJS

n lservnt.exen ulscgen.exen ulsdcod.exe

n Client Applicationn ulscgen.exen ulsdcod.exe

ENCRYPT_MSG_OBJS DECRYPT_MSG_OBJS

n lservnt.exen Client Application

NA

CUSTOM_LOCK_OBJS n lservnt.exen Client Applicationn echoid.exen wechoid.exe

n Client Applicationn echoid.exen wechoid.exe

CUSTOM_EX_LOCK_OBJS n lservnt.exen Client Applicationn echoid.exen wechoid.exe

n Client Applicationn echoid.exen wechoid.exe

Based on the licensing mode, whether stand-alone or network, you need to rebuild your executables.

B.15.2. Stand-alone Licensing

Use the following command on the command prompt:

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

B.15. Build Procedure 551


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, ifyou specified the value of TIME_TAMPER_OBJS as "tmtampcf.obj", issue the build command. Thiscommand 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 filesbefore 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 sce-narios:

n An extra layer of encryption for communication between the client and the license server.

n Communication over a vendor-specified license server port.

n Vendor specified 4-byte custom fingerprint of a system.

n Vendor specified custom extended fingerprint of a system.

B.15.5. How to Build Your Client Application?

1. Use the same object files that were used while generating the customized executables using thecustom32.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 ofcustom host ID, you need to call VLSsetHostIdFunc in client application. While in case of pro-tection against time tampering, you do not need to call any function in the client application.

4. Build the client application.

Index

A

addingfeature licensing information 126, 128

APIsclient 1license code generation 307upgrade license code generator 262

authenticating the licensemanager 28-29

B

basic license code generation functions 317broadcast intervalsretrieving 57setting 57

C

challenge-responsemechanism 28-29CHALLENGE structure, defined 28CHALLENGERESPONSE structure, defined 28checking out remote commuter authorization184client API 1client feature information, retrieving 98client libraryinitializing 8retrieving information 139tracing calls 169

client query functions 82client utility functions 123, 139code struct field setting functions 311, 387codeT 307commuter authorization, remote 184commuter licensing 175, 182

D

deletingfeature licensing information 131

destroying the handle for lscgen.h 320disable auto timer 81displaying error messages 165, 167

E

environment variablesLS_MAX_GRP_QLEN 246LS_MAX_HOLD_SEC 246LS_MAX_QLEN 246LS_MAX_WAIT_SEC 246

error codesupgrade license generation functions 511

error handling 167setting 166

error message display 167error messages, displaying 165errors, retrieving 327-328

F

feature licensing informationadding 126, 128deleting 131retrieving 112

feature names, retrieving 116feature time left informationretrieving 119

functionscapacity license 213, 219client query 82client utility 123, 139license queuing 237redundancy 189

554 Index

upgrade license 262

G

get remote computer locking info 182

H

host IDsetting 54

host namesretrieving 35setting 32

I

initializingnetwork system 482persistence data 480, 482stand-alone system 480

initializing fields of themachineID 38, 72initializing the client library 8initializing the server info 53installing remote commuter authorization 187

K

key time left informationretrieving 121

L

license code generation API 307license generation function return codes 505licensemanagerauthenticating 28

license revocation 156, 457license serverAPIs

license code generation 307

locating 123licenseslocal vs. remote renewal of 75releasing 15, 23requesting 9, 19

single-call licensing

disabling 6

local license renewal 76locating the license server 123LS_LIBVERSION structure, defined 139LS_MAX_QLEN 246lscgen.h handledestroying 320

LSGetMessage 165LSRelease 15LSRequest 9

M

machine names, retrieving 123

P

persistence datainitializing 480, 482

port numbersretrieving 37

printing errors 327-328

R

redundant license server 189releasing licenses 15, 23remote commuter authorization 184remote renewal time, setting 80requesting licenses 9, 19reserved characters 317retrievingbroadcast intervals 57client feature information 98client library information 139errors 327-328feature licensing information 112feature names 116feature time left information 119license time left information 121machine names 123server host names 35server port numbers 37time-out intervals 60time drift information 118

Index 555

version information 114, 117revocation 156, 457

S

Sentinel RMSAPIs

capacity license 219

client 1

commuter license 175

license code generation 307

license queuing 237

redundancy 189

upgrade license 261

serversretrieving host names 35retrieving port numbers 37setting

host names 32

settingbroadcast intervals 57code struct fields 311, 387error handling 166host ID 54remote renewal time 80server names 32time-out intervals 59

shared IDs 63, 65shutting down lserv 140single-call licensingdisabling 6

sntlInitNetworkSystem 482sntlInitStandaloneSystem 480structure definitionsCHALLENGE 28CHALLENGERESPONSE 28LS_LIBVERSION 139VLSclientInfo 95

T

time-out intervalsretrieving 60setting 59

time drift informationretrieving 118

tracing client-library calls 169

U

ucodeT Struct 264ulcCode 293updating 25updating licenses 25Upgrade License Code Generation Return Codes511using the Sentinel RMS client API 1

V

version informationretrieving 114, 117

VLSaddFeature 126, 191VLSaddFeatureToFile 128, 193VLSaddServerToPool 195VLSbatchUpdate 25VLScalculateLicenseHash 70VLScgAllowAdditive 343-344VLScgAllowCapacity 396VLScgAllowCapacityLic 394VLScgAllowClientLockInfo 382VLScgAllowClockTamperFlag 385VLScgAllowCodegenVersion 392VLScgAllowCommuterLicense 361VLScgAllowCommuterMaxCheckoutDays 363VLScgAllowFeatureName 333VLScgAllowFeatureVersion 335VLScgAllowGracePeriod 436VLScgAllowGracePeriodFlag 434VLScgAllowHeldLic 390VLScgAllowKeyHoldtime 422VLScgAllowKeyHoldUnits 420VLScgAllowKeyLifetime 346VLScgAllowKeyLifeUnits 418VLScgAllowKeysPerNode 409

556 Index

VLScgAllowLicBirth 424VLScgAllowLicenseType 337VLScgAllowLicExpiration 428VLScgAllowLocalRequestLockCrit 441VLScgAllowLocalRequestLockCritFlag 439VLScgAllowLockMechanism 380VLScgAllowLockModeQuery 367VLScgAllowLogEncryptLevel 353VLScgAllowMajorityRuleFlag 371VLScgAllowMultiKey 399VLScgAllowMultipleServerInfo 373VLScgAllowNetworkFlag 349VLScgAllowNumKeys 363-365VLScgAllowOutLicType 387VLScgAllowRedundantFlag 369VLScgAllowSecrets 401VLScgAllowServerLockInfo 375VLScgAllowSharedLic 355VLScgAllowShareLimit 358VLScgAllowSiteLic 411VLScgAllowSoftLimit 416VLScgAllowStandAloneFlag 348VLScgAllowTeamCriteria 355VLScgAllowTrialLicFeature 339VLScgAllowVendorInfo 404VLScgAllowVendorInfoExt 406VLScgAllowVmDetection 443VLScgCleanup 320-321VLScgDecodeLicenseExt 452VLScgDecodeLicenseRevocationTicket 466-467VLScgGenerateLicense 447, 450VLScgGetErrorLength 325VLScgGetErrorMessage 326VLScgGetLicenseMeterUnits 455VLScgGetNumErrors 324VLScgGetTrialLicenseMeterUnits 456VLScgInitialize 319VLScgPrintError 327-328VLScgReset 321VLScgSetAdditive 345VLScgSetCapacityFlag 395VLScgSetCapacityUnits 397VLScgSetClientLockInfo 383, 444VLScgSetClientLockMechanism 381VLScgSetClientServerLockMode 368VLScgSetClockTamperFlag 386

VLScgSetCodegenVersion 393VLScgSetCodeLength 332VLScgSetCommuterLicense 362VLScgSetFeatureName 334VLScgSetFeatureVersion 336VLScgSetGracePeriodFlag 434VLScgSetGracePeriodHours 438VLScgSetHoldingCrit 391VLScgSetKeyHoldtime 423VLScgSetKeyHoldtimeUnits 421VLScgSetKeyLifetime 347VLScgSetKeyLifetimeUnits 419VLScgSetKeysPerNode 410VLScgSetKeyType 400VLScgSetLicBirthDay 426VLScgSetLicBirthMonth 425VLScgSetLicBirthYear 427VLScgSetLicenseType 338VLScgSetLicExpirationDay 430VLScgSetLicExpirationMonth 429VLScgSetLicExpirationYear 431VLScgSetLicType 389VLScgSetLoadSWLicFile 433VLScgSetLogEncryptLevel 354VLScgSetMajorityRuleFlag 372VLScgSetNumClients 384VlScgSetNumericType 432VLScgSetNumFeatures 413-415VLScgSetNumKeys 366VLScgSetNumSecrets 403VLScgSetNumServers 374VLScgSetOutLicType 388VLScgSetRedundantFlag 370VLScgSetSecrets 402VLScgSetServerLockInfo1 376VLScgSetServerLockInfo2 379VLScgSetServerLockMechanism1 377VLScgSetServerLockMechanism2 378VLScgSetSharedLicType 356VLScgSetShareLimit 359VLScgSetSiteLicInfo 412VLScgSetSoftLimit 417VLScgSetStandAloneFlag 352VLScgSetTeamCriteria 356VLScgSetTrialDaysCount 340VLScgSetTrialHours 342

Index 557

VLScgSetVendorInfo 405VLScgSetVendorInfoExt 407VLScgSetVmDetection 444VLSchangeUsageLogFileName 301VLSCleanup 17VLSclientInfo 95VLSdecodeUpgradelockCode 294VLSdeleteFeature 131VLSdeleteFeatureExt 231VLSdeleteLicenseFromFile 133VLSdeleteLicenseFromFileExt 136VLSdelServerFromPool 197VLSdisableAutoTimer 81VLSdisableEvents 299VLSdisableLicense 6VLSdiscover 123VLSdiscoverExt 199VLSenableLocalRenewal 76VLSerrorHandle 164VLSgeneratePermissionTicket 458VLSgeneratePermissionTicketExt 459VLSgenerateUpgradeLockCode 291VLSgetActiveHandleList 101VLSgetBroadcastInterval 57VLSgetCapacityFromHandle 233VLSgetCapacityList 227VLSgetClientInfo 98VLSgetCommuterCode 184VLSgetCommuterCode call 184VLSgetCommuterInfo 179VLSgetContactServer 35VLSgetDistbCrit 202VLSgetDistbCritToFile 204VLSgetFeatureFromHandle 116VLSgetFeatureInfo 112VLSgetFeatureInfoExt 225VLSgetFeatureTimeLeftFromHandle 119VLSgetGraceRequestFlag 69VLSgetHandleInfo 100VLSgetHandleStatus 254VLSgetKeyTimeLeftFromHandle 121VLSgetLastErrorStatusFromHandle 102VLSgetLeaderServerName 206VLSgetLibInfo 139VLSgetLicenseInfo 89VLSgetLicenseInfoExt 92

VLSgetLicInUseFromHandle 103VLSgetLicSharingServerList 208VLSgetMachineID 40-42, 45VLSgetMachineIDString 182VLSgetPoolServerList 210VLSgetQueuedClientInfo 248VLSgetQueuedLicense 257VLSgetServerList 52VLSgetServerNameFromHandle 50VLSgetServerPort 37VLSgetTimeDriftFromHandle 118VLSgetTimeoutInterval 60VLSgetTrialPeriodLeft 150VLSgetVersionFromHandle 117VLSgetVersions 114VLSinitialize 8VLSinitMachineID 38, 72VLSinitQueuePreference 259VLSinitServerInfo 53VLSinitServerList 51VLSinstallCommuterCode 187VLSinstallCommuterCode call 187VLSisLocalRenewalDisabled 77VLSisVirtualMachine 72VLSlicense 3VLSmachineIDtoLockCode 47VLSqueuedRequestExt 244VLSreleaseExt 23VLSremoveQueue 252VLSremoveQueuedClient 250VLSrequestExt 19VLSrevokeByPermissionTicket 157VLSrevokeLicense 156, 160VLSscheduleEvent 297-298, 483VLSsetBroadcastInterval 57VLSsetContactServer 32VLSsetCustomExFunc 55VLSsetGraceRequestFlag 67VLSsetHoldTime 61, 67VLSsetLicensePrecedence 147VLSsetRemoteRenewalTime 80VLSsetServerLogState 211VLSsetServerPort 36VLSsetSharedId 63VLSsetSharedIdValue 65VLSsetTeamId 63

558 Index

VLSsetTimeoutInterval 59VLSsetTraceLevel 169VLSsetUserErrorFile 167VLSshutDown 140VLSucgAllowUpgradeCapacity 284VLSucgAllowUpgradeFlag 279VLSucgAllowUpgradeVersion 282VLSucgDecodeLicense 295VLSucgGenerateLicense 288VLSucgGetErrorLength 270VLSucgGetLicenseMeterUnits 290VLSucgInitialize 266VLSucgPrintError 272VLSucgReset 268VLSucgSetBaseFeatureName 274VLSucgSetBaseFeatureVersion 276VLSucgSetUpgradeCapacity 286VLSucgSetUpgradeCode 278VLSuninstallAndReturnCommuterCode 181VLSupdateQueuedClient 255VLSverifyRevocationTicket 461, 463VM detection 72, 443-444

manual sentinel rms

Documents

problems correctedin

windows release

client configuration

orregistered trademarks

revision actionchange

revision lsoftware versions

free softwarefoundation

product names