WSAGetQOSByName

[This is preliminary documentation and subject to change.]

The GQOS WSAGetQOSByName function initializes a QUALITYOFSERVICE structure based on a named template, or retrieves an enumeration of the available template names.

BOOL WSAAPI 
  WSAGetQOSByName( 
  IN  SOCKET s, 
  IN  OUT LPWSABUF lpQOSName, 
  OUT LPQOS lpQOS 
);

Parameters

s: [in] Descriptor identifying a socket.
lpQOSName: [in out] Specifies the QOS template name, or supplies a buffer to retrieve an enumeration of available template names.
lpQOS: [out] Pointer to the QUALITYOFSERVICE structure to be filled.

Return Values

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

The algorithm that WSAGetQOSByName applies in its search for a template's name match is:

The socket's service provider checks for a provider-specific template with a matching name—a template installed specifically for the socket's service provider—with a name that matches the service provider's name.
If this fails, the service provider checks its internal table of GQOS templates (if it has such a table).
If this fails, the service provider checks for a list of global GQOS templates.
If any one of the above succeeds, the service provider has the option of modifying the GQOS template before returning it to Windows Sockets.
Otherwise WSAGetQOSByName returns FALSE, and WSAGetLastError returns WSA_NODATA to indicate an invalid name.

Remarks

Applications can use WSAGetQOSByName to initialize a QUALITYOFSERVICE structure with a prescribed set of known values appropriate for a particular service class or media type. These known values are stored in a template, and the template is referenced by a well-known name; for example, if the service provider's .dll is named ipphone.dll, the template may be referenced by the name IPPHONE. Applications can retrieve these values by setting the buf member of WSABUF, indicated by lpQOSName, to point to a string of nonzero length specifying a template name. When doing so, lpQOSName is an in parameter only and results are returned through lpQOS.

This function can also be used to retrieve an enumeration of available template names. This is done by setting the buf member of WSABUF, indicated by lpQOSName, to a zero-length, null-terminated string. The buffer indicated by buf is then overwritten with a sequence of as many null-terminated template names as are available—up to the number of bytes available in buf, as provided by the len member of WSABUF indicated by lpQOSName. The list of names itself is terminated by a zero-length name. When WSAGetQOSByName is used to retrieve template names, the lpQOS parameter is ignored.

If two templates have the same name, with one template being specific to the service provider and the other being global, they will appear in the list only once.

Error Codes

WSANOTINITIALISED	A successful call to WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEFAULT	The lpQOSName or lpQOS arguments are not a valid part of the user address space.
WSAENOBUFS	The buffer length for lpQOS is too small.
WSA_NODATA	The specified QOS template name is invalid.

QuickInfo