Функция QOSCreateHandle (qos2.h)

Статья
2023-08-25

Эта функция инициализирует подсистему QOS и параметр QOSHandle . Параметр QOSHandle используется при вызове других функций QOS. QOSCreateHandle должен вызываться перед любыми другими функциями.

QOSCloseHandle закрывает дескрипторы, созданные этой функцией.

Синтаксис

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

Параметры

[in] Version

Указатель на структуру QOS_VERSION , указывающую используемую версию QOS. Для элемента MajorVersion необходимо задать значение 1, а для элемента MinorVersion — значение 0.

[out] QOSHandle

Указатель на переменную, которая получает дескриптор QOS. Этот дескриптор используется при вызове других функций QOS.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция завершается сбоем, возвращаемое значение равно 0. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Ниже приведены некоторые возможные коды ошибок.

Код возврата	Описание
ERROR_GEN_FAILURE	Внутренняя ошибка логики. Ошибка инициализации. Например, если узел переходит в спящий или резервный режим, все существующие дескрипторы и потоки становятся недействительными.
ERROR_INVALID_PARAMETER	Недопустимый параметр QOSHandle .
ERROR_NOT_ENOUGH_MEMORY	Указывает, что произошел сбой выделения памяти.
ERROR_NO_SYSTEM_RESOURCES	Недостаточно ресурсов для выполнения операции.
ERROR_RESOURCE_DISABLED	Ресурс, необходимый службе, недоступен. Эта ошибка может быть возвращена, если пользователь не включил исключение брандмауэра для службы qWAVE.
ERROR_SERVICE_DEPENDENCY_FAIL	Одна из зависимостей этой службы недоступна. Не удалось запустить службу qWAVE.

Каждый процесс, который планирует использовать qWAVE, должен сначала вызвать QOSCreateHandle. Возвращаемый дескриптор можно использовать для выполнения перекрывающихся операций ввода-вывода. Например, этот дескриптор можно связать с портом завершения ввода-вывода (IOCP) для получения перекрывающихся уведомлений о завершении. Эту функцию можно вызывать несколько раз для получения нескольких дескрипторов, хотя для большинства приложений достаточно одного дескриптора.

Если компьютер переходит в режим энергопотребления, который прерывает подключение, например спящий режим или режим ожидания, существующие и активные сетевые эксперименты, такие как QOSStartTrackingClient , должны быть повторно инициалированы. Это повторное создание потока отражает действия по очистке и созданию, которые также необходимы для существующих сокетов. Необходимо создать новый дескриптор, а поток должен быть повторно создан и перенаправлен.

Примеры

В следующем коде показано использование функций и обязательные инициализации параметров. Фактические значения зависят от версии QoS.

Для использования функции WSAGetLastError необходимо включить winsock.h.

Полный пример кода см. в Windows SDK. Папка пакета SDK: 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;
}

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	qos2.h (включая Qos2.h)
Библиотека	Qwave.lib
DLL	Qwave.dll

См. также раздел

Качество звука и видео Windows (qWAVE)

Поделиться через