WSPGetQOSByName function

Article
06/19/2017

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

Syntax

BOOL WSPGetQOSByName(
  _In_    SOCKET   s,
  _Inout_ LPWSABUF lpQOSName,
  _Out_   LPQOS    lpQOS,
  _Out_   LPINT    lpErrno
);

Parameters

s [in]
Descriptor that identifies a socket.
lpQOSName [in, out]
Pointer to a WSABUF structure that either contains the template name or receives an enumeration of the available template names.
lpQOS [out]
Pointer to a QoS structure that receives quality of service (QoS) information. For information about QoS, see the Microsoft Windows SDK documentation.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns TRUE if successful; otherwise, returns FALSE and, at lpErrno, one of the following error codes:

Return code	Description
WSAENETDOWN	Network subsystem failed.
WSAENOTSOCK	Descriptor is not a socket.
WSAEFAULT	The lpQOS parameter is not a valid part of the user address space, or the buffer length for lpQOS is too small.
WSAEINVAL	Specified QoS template name is invalid.
WSAEOPNOTSUPP	The SAN service provider does not support QoS.

Remarks

The Windows Sockets switch can call a SAN service provider's WSPGetQOSByName function to initialize a quality of service (QoS) structure to a set of values that are appropriate for the SAN. The SAN service provider stores these values in a template that is referenced by a name well known to applications and, therefore, the switch. To retrieve these values, the switch sets the buf member of the WSABUF structure, to which lpQOSName points, to a Unicode string of nonzero length that contains the template name. In this case, the switch uses lpQOSName as an input (IN) parameter only, and receives QoS values in a QoS structure at the lpQOS output (OUT) parameter.

Alternatively, the switch can call a SAN service provider's WSPGetQOSByName function to retrieve an enumeration of available template names. To retrieve available template names, the switch sets the buf member of the WSABUF structure to which lpQOSName points, to a zero-length, null-terminated Unicode string. In this case, the SAN service provider overwrites the buffer indicated by buf with a sequence of as many null-terminated, Unicode template name strings as are available up to the size of that buffer. The len member of the WSABUF structure to which lpQOSName points indicates the size of the buffer. The list of names itself is terminated by a zero-length, Unicode name string. If the switch calls WSPGetQOSByName to retrieve template names, the SAN service provider ignores lpQOS.

A SAN service provider is not required to support QoS, but if it does, it implements full functionality for WSPGetQOSByName. If it does not support QoS, its WSPGetQOSByName function must at least return the WSAEOPNOTSUPP error code.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.0.
Header	Ws2spi.h (include Ws2spi.h)

Partager via