Platform SDK: Quality of Service

WSCInstallQOSTemplate

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 WSPGetQOSByName function and passing in its associated QOS name. Note that the caller of this function must have administrative rights.

BOOL WSCInstallQOSTemplate ( 
  const LPGUID lpProviderId, 
  LPWSABUF lpQOSName, 
  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 Values

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

Remarks

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.

Error Codes

Error Code	Meaning
WSAEINVAL	The specified QOS template name or provider identifier is invalid, or the contents of the template structure is invalid or incomplete.
WSEFAULT	One or more of the parameters is not a valid part of the user address space.

Requirements