WSCInstallQOSTemplate function

[ This function is not supported as of Windows Vista.]

The WSCInstallQOSTemplate function installs a QOS template, based on a QOS name. This QOS structure (and thus its QOS settings) can be retrieved by calling the WSAGetQOSByName function and passing in its associated QOS name. Note that the caller of this function must have administrative rights.

Syntax

BOOL WSCInstallQOSTemplate(
  _In_ const LPGUID   lpProviderId,
  _In_       LPWSABUF lpQOSName,
  _In_       LPQOS    lpQOS
);

Parameters

lpProviderId [in]

Pointer to a provider-selected globally unique identifier (GUID).

lpQOSName [in]

Specifies the QOS template name.

lpQOS [in]

Pointer to a QOS structure.

Return value

If WSCInstallQOSTemplate succeeds, the return value is TRUE. If the function fails, the return value is FALSE. For extended error information, call WSAGetLastError.

Remarks

In Windows Vista and later, this function always returns with an error.

The WSCInstallQOSTemplate function installs a QOS-named template containing the specified and subsequently associated QOS structure, or replaces settings of an existing template. Values are stored in nonvolatile storage, so subsequent calls to WSAGetQOSByName, passing the same lpQOSName, return the QOS structure. If lpProviderId is set to NULL, the installed QOS-named template applies across all service providers; otherwise the QOS-named template applies only to the provider indicated by the lpProviderId parameter.

Windows Sockets 2 includes a base set of QOS templates. You can override and replace any of these QOS templates or change an existing QOS template by simply installing a new template with the existing name. You do not need to delete an existing template before replacing or modifying it. You cannot delete the base set of QOS-named templates included in Windows Sockets 2. However, you can delete templates added subsequently, perhaps by other service providers.

The lpQOS parameter, which points to a QOS structure, can include a ProviderSpecific buffer that will be stored with the basic QOS structure and returned in subsequent WSAGetQOSByName calls.

You can provide the ProviderSpecific buffer even if lpProviderId is set to NULL to install global name templates that include provider-specific information. Note that this practice may lead the service provider to ignore the ProviderSpecific buffer if the service provider does not recognize its contents. The recommended use of WSCInstallQOSTemplate is to include a ProviderSpecific buffer only if the named template is being installed on a particular service provider, as implemented when lpProviderId is not NULL.

Requirements

See also

QOS

WPUGetQOSTemplate

WSAGetQOSByName

WSCRemoveQOSTemplate