Platform SDK: Quality of Service

WSAGetQOSByName

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

BOOL WSAAPI WSAGetQOSByName ( 
  SOCKET s, 
  LPWSABUF lpQOSName, 
  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 QOS structure to be filled. The ProviderSpecific buffer member of the QOS structure must be initialized before calling the WSAGetQOSByName function.

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—a template installed specifically for the socket's service provider—with a name that matches the service provider's name.
If that fails, the service provider checks its internal table of QOS templates (if it has such a table).
If that fails, the service provider checks for a list of global QOS templates.
If any of the preceding steps succeeds, the service provider can modify the QOS 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 QOS 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 can 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. 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

Error Code	Meaning
WSANOTINITIALIZED	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 parameter is 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.

Requirements