注意:这是Microsoft Windows的将来版本中将支持的技术的初步文档。
LSRequest功能要求许可证系统授予许可资源,以便调用应用程序可以执行。
LS_STATUS_CODE LS_API_ENTRY LSRequest(
LS_STR 【*LicenseSystem】, | //指向许可证系统的字符串的指针 |
LS_STR 【*PublisherName】, | //指向发布商的产品请求许可资源 |
LS_STR 【*ProductName】, | //指向请求许可资源的产品名称的指针 |
LS_STR 【*版】, | //指向请求许可资源的产品版本号的指针 |
LS_ULONG 【TotUnitsReserved】, | //运行应用程序所需的单位 |
LS_STR 【*LogComment】, | //指向与请求相关联的可选注释的指针 |
LS_CHALLENGE 【*挑战】, | //指向挑战结构的指针 |
LS_ULONG 【*TotUnitsGranted】, | //指向授予的总单位数 |
LS_HANDLE【*LicenseHandle】 | //指向许可证上下文的指针 |
); |
参数
【LicenseSystem】
[in]指向唯一标识特定许可证系统的字符串。您可以使用LSEnumProviders函数获取此字符串。如果指定了常量LS_ANY,则将搜索所有许可证系统提供程序的许可证匹配。
【PublisherName】
[in]指向包含请求许可资源的软件产品发布者名称的字符串。字符串的前32个字符必须是唯一的。建议使用公司名称和商标。此字符串不能为空,也不能为LS_ANY。
【ProductName】
[in]指向包含请求许可资源的软件产品名称的字符串。字符串的前32个字符在【PublisherName】域内必须是唯一的。此字符串不能为空,也不能为LS_ANY。
【版】
[in]指向包含产品版本号的字符串。字符串的前12个字符在【PublisherName】域内必须是唯一的。此字符串不能为空,也不能为LS_ANY。
【TotUnitsReserved】
[in]指定运行应用程序所需的单位数。软件发行人可以选择在应用程序中指定此策略属性。LS_DEFAULT_UNITS的建议值允许许可证系统使用许可证系统或许可证本身提供的信息来确定适当的值。许可证系统验证所要求的单位数量是否存在,并且可以保留这些单位,但目前没有实际消耗单位。可在【TotUnitsGranted】参数中返回可用的单位数。
【LogComment】
[in]指向可选字符串,指示与请求相关联的注释。如果支持并启用日志记录,许可证系统可以记录注释。如果返回错误,许可证系统可以记录错误和注释,但不能保证。如果不指定字符串,则该值必须为LS_NULL。
【挑战】
[in/out]指向挑战结构。此结构中也将返回挑战响应。
【TotUnitsGranted】
[out]指向返回授予的总单位数的LS_ULONG值。给定【TotUnitsReserved】参数输入值和返回的状态代码,下表描述了【TotUnitsGranted】返回值:
【TotUnitsReserved】 | |||||||||||||||||||||||||
返回状态码 | LS_DEFAULT_UNITS | 其他(具体计数) | |||||||||||||||||||||||
LS_SUCCESS | (A) | (C) | |||||||||||||||||||||||
LS_INSUFFICIENT_UNITS | (B) | (D) | |||||||||||||||||||||||
其他错误 | (E) | (E) |
【TotUnitsGranted】返回值:
(A)与授予的许可证相当的默认单位数。
(B)请求软件可用的最大单位数。这可以小于正常默认值。
(C)用于批准请求的单位数。该值可以大于或等于所请求的实际单位。例如,许可证政策可允许仅允许增加五个单位;因此,七个单位的要求将导致10个单位的拨款。
(D)请求软件可用的最大单位数。这可以或多或少是所要求的单位。
(E)返回零。
【LicenseHandle】
[out]指向返回许可证上下文的句柄的LS_HANDLE。
返回值
如果函数成功,返回值为LS_SUCCESS。
如果函数失败,则返回值为状态码。有关扩展错误信息,请调用LSGetMessage 返回与状态【码】对应的状态【文本】.LSGetMessage功能可能会返回以下状态代码之一:
值 | 含义 |
LS_INSUFFICIENT_UNITS | 许可证系统无法找到足够的可用许可资源来完成请求。 |
LS_SYSTEM_UNAVAILABLE | 无法找到执行所调用函数的许可证系统。 |
LS_AUTHORIZATION_UNAVAILABLE | 许可证制度没有许可资源来完成请求。 |
LS_LICENSE_UNAVAILABLE | 许可证制度具有可以满足请求的许可资源,但在请求时它们不可用。 |
LS_RESOURCES_UNAVAILABLE | 由于资源不足(如内存),请求无法完成。 |
LS_NETWORK_UNAVAILABLE | 网络不可用 |
LS_BAD_ARG | 一个或多个参数是不正确的。 |
备注
使用LSRequest功能来请求许可资源来授权标识的产品执行。如果找到有效的许可证,则计算挑战响应并返回LS_SUCCESS。至少,【PublisherName】,【ProductName】和【版】字符串用于标识匹配的许可证或许可证。请注意,底层许可证系统服务提供商可以确定许可证请求__的附加信息,例如当前用户名,计算机名称等。
如果所有服务提供商不能满足对LSRequest功能的调用,则LSRequest返回与最后一个服务提供商响应关联的句柄。因此,无论是否授予有效的许可资源,LSRequest总是返回有效的许可证句柄。应用程序运行结束后,必须始终使用LSFreeHandle功能释放该句柄。如果许可资源被授予,应用程序必须在致电LSFreeHandle之前致电LSRelease以释放许可资源。
除非许可证请求成功完成__,否则质询响应为【不】,除非它返回状态码为LS_SUCCESS。
如果请求的单位数量大于可用单位数量,则不会授予许可证请求。成功完成后,【TotUnitsReserved】参数中返回的值表示授予的单位数。这大于或等于所指定的单位数,除非指定了LS_DEFAULT_UNITS。在失败的情况下,【TotUnitsGranted】参数中返回的值为零。
也可以看看
LS_CHALLENGE,LSEnumProviders,LSFreeHandle,LSGetMessage,LSRelease