QOSCreateHandle function

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


BOOL WINAPI QOSCreateHandle(
  _In_  PQOS_VERSION Version,
  _Out_ PHANDLE      QOSHandle
);

Parameters

Version [in]

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.

QOSHandle [out]

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 codeDescription
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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Qos2.h (include Qos2.h)

Library

Qwave.lib

DLL

Qwave.dll

See also

Quality Windows Audio/Video Experience (qWAVE)

 

 

Community Additions

ADD
Show: