WSPGetQOSByName

[This is preliminary documentation and subject to change.]

The GQOS WSPGetQOSByName 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
  OUT LPINT lpErrno
);

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.
lpErrno: [out] Pointer to the error code.

Return Values

If WSPGetQOSByName succeeds, the return value is TRUE. If the function fails, the return value is FALSE. Error information is available in lpErrno.

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

The service provider checks for a provider-specific template by calling WPUGetQOSTemplate, using the service provider's globally unique identifier (GUID) and QOS name as search criteria.
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 calls WPUGetQOSTemplate again, using the same QOS name, but this uses NULL for the GUID to facilitate a query of the global list of QOS names.
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, WSPGetQOSByName returns FALSE, and lpErrno is set to WSA_NODATA.

Remarks

Clients may use this function 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. Applications may retrieve these values by setting the buf member of WSABUF, indicated by lpQOSName, to point to a Unicode 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 may 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 Unicode string. The buffer indicated by buf is then overwritten with a sequence of as many null-terminated Unicode 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 Unicode name string. When WSPGetQOSByName is used to retrieve template names, the lpQOS parameter is ignored.

Error Codes

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

  Windows NT: Requires version 5.0 or later.
  Windows: Requires Windows 98.
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.