QOSCreateHandle function (qos2.h)

Article
10/13/2021

This function initializes the QOS subsystem and the QOSHandle parameter. The QOSHandle parameter is used when calling other QOS functions. QOSCreateHandle must be called before any other functions.

QOSCloseHandle closes handles created by this function.

Syntax

ExternC BOOL QOSCreateHandle(
  [in]  PQOS_VERSION Version,
  [out] PHANDLE      QOSHandle
);

Parameters

[in] Version

Pointer to a QOS_VERSION structure that indicates the version of QOS being used. The MajorVersion member must be set to 1, and the MinorVersion member must be set to 0.

[out] QOSHandle

Pointer to a variable that receives a QOS handle. This handle is used when calling other QOS functions.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is 0. To get extended error information, call GetLastError. Some possible error codes follow.

Return code	Description
ERROR_GEN_FAILURE	Internal logic error. Initialization failed. For example, if the host goes into sleep or standby mode, all existing handles and flows are rendered invalid.
ERROR_INVALID_PARAMETER	The QOSHandle parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY	Indicates that a memory allocation failed.
ERROR_NO_SYSTEM_RESOURCES	There are insufficient resources to carry out the operation.
ERROR_RESOURCE_DISABLED	A resource required by the service is unavailable. This error may be returned if the user has not enabled the firewall exception for the qWAVE service.
ERROR_SERVICE_DEPENDENCY_FAIL	One of the dependencies of this service is unavailable. The qWAVE service could not be started.

Remarks

Every process intending to use qWAVE must first call QOSCreateHandle. The handle returned can be used for performing overlapped I/O. For example, this handle can be associated with an I/O completion port (IOCP) to receive overlapped completion notifications. This function can be called multiple times to obtain multiple handles although a single handle is sufficient for most applications.

If a machine enters a power save mode that interrupts connectivity such as sleep or standby, existing and active network experiments such as QOSStartTrackingClient must be reinitiated. This recreation of the flow mirrors the cleanup and creation activities also necessary for existing sockets. A new handle must be created, and the flow must be recreated and readmitted.

Examples

The following code illustrates function use and required parameter initializations. Actual values will vary depending on QoS version.

Winsock.h must be included to use the WSAGetLastError function.

See the Windows SDK for a complete sample code listing. SDK folder: Samples\NetDs\GQos\Qos2

QOS_VERSION Version;
HANDLE      QoSHandle = NULL;
BOOL        QoSResult = FALSE;

// Initialize the QoS version parameter.
Version.MajorVersion = 1;
Version.MinorVersion = 0;

// Get a handle to the QoS subsystem.
QoSResult = QOSCreateHandle(
    &Version, 
    &QoSHandle );

if (QoSResult != TRUE)
{
    std::cerr << "QOSCreateHandle failed. Error: "; 
    std::cerr << WSAGetLastError() << std::endl;
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	qos2.h (include Qos2.h)
Library	Qwave.lib
DLL	Qwave.dll