WSAGetQOSByName
The WSAGetQOSByName function initializes a QOS structure based on a named template, or retrieves an enumeration of the available template names.
Note Windows Vista: This function is no longer supported. If this function is called, it always returns with an error of WSAEOPNOTSUPP.
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 Value
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.
| Return code | Description |
|---|---|
| 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. |
Remarks
In Windows Vista and later, this function always returns with an error.
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.
Requirements
| Client | Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows Me, or Windows 98. |
| Server | Requires Windows Server "Longhorn", Windows Server 2003, or Windows 2000 Server. |
| Header | Declared in Winsock2.h. |
| Library | Use Ws2_32.lib. |
| DLL | Requires Ws2_32.dll. |