Platform SDK: Quality of Service

WSPGetQOSByName

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

BOOL WSAAPI WSPGetQOSByName ( 
  SOCKET s, 
  LPWSABUF lpQOSName, 
  LPQOS lpQOS,
  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 QOS 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 that fails, the service provider checks its internal table of QOS templates (if it has such a table).
If that fails, the service provider calls WPUGetQOSTemplate again, using the same QOS name, but using NULL for the GUID to facilitate a query of the global list of QOS names.
If any of the preceding steps succeeds, the service provider can modify the QOS template before returning it to Windows Sockets. Otherwise, WSPGetQOSByName returns FALSE, and lpErrno is set to WSA_NODATA.

Remarks

Applications can use this function 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. 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 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. 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

Error Code	Meaning
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