[This is preliminary documentation and subject to change.]
The GQOS WSCInstallQOSTemplate function installs a GQOS template, based on a GQOS name. This QUALITYOFSERVICE structure (and thus its GQOS settings) can be retrieved by calling the WSPGetQOSByName function, and passing in its associated GQOS name. Note that the caller of this function must have administrative privileges.
BOOL
WSCInstallQOSTemplate(
IN const LPGUID lpProviderId,
IN LPWSABUF lpQOSName,
IN LPQOS lpQOS
);
If WSCInstallQOSTemplate succeeds, the return value is TRUE. If the function fails, the return value is FALSE. For extended error information, call WSAGetLastError.
The WSCInstallQOSTemplate function installs a GQOS name template containing the specified and subsequently associated QUALITYOFSERVICE 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 QUALITYOFSERVICE structure. If lpProviderId is set to NULL, the installed GQOS name template applies across all service providers; otherwise the GQOS name template applies only to the provider indicated by the lpProviderId parameter.
Windows Sockets 2 includes a base set of GQOS templates. You can override and replace any of these GQOS templates, or change an existing GQOS 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; the base set of GQOS name templates included in Windows Sockets 2 cannot be deleted. However, templates added subsequently, perhaps by other service providers, can be deleted.
The lpQOS parameter, which points to a QUALITYOFSERVICE structure, can include a ProviderSpecific buffer that will be stored with the basic QUALITYOFSERVICE structure, and returned in subsequent WSAGetQOSByName calls.
Providing the ProviderSpecific buffer, even if lpProviderId is set to NULL, can be used 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 name template is being installed against a particular service provider, as implemented when lpProviderId is not NULL.
| WSAEINVAL | The specified QOS template name or Provider ID is invalid, or the contents of the template structure is invalid or incomplete. |
| WSEFAULT | One or more of the arguments is not a valid part of the user address space. |
Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in qosname.h.
QUALITYOFSERVICE, WPUGetQOSTemplate, WSAGetQOSByName, WSCRemoveQOSTemplate