共用方式為

QOSCreateHandle 函式 (qos2.h)

  • 發行項

此函式會初始化 QOS 子系統和 QOSHandle 參數。 呼叫其他 QOS 函式時，會使用 QOSHandle 參數。 QOSCreateHandle 必須在任何其他函式之前呼叫。

QOSCloseHandle 會關閉此函式所建立的句柄。

語法

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

參數

[in] Version

指出所使用 QOS 版本的 QOS_VERSION 結構的指標。 MajorVersion 成員必須設定為 1，而 MinorVersion 成員必須設定為 0。

[out] QOSHandle

接收 QOS 句柄之變數的指標。 呼叫其他 QOS 函式時，會使用此句柄。

傳回值

如果函式成功，則傳回非零的值。

如果函式失敗，則傳回值為 0。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 以下是一些可能的錯誤碼。

傳回碼 Description
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。 傳回的句柄可用於執行重疊的 I/O。 例如，此句柄可以與 I/O 完成埠相關聯， (IOCP) 以接收重疊的完成通知。 雖然單一句柄足以供大部分應用程式使用，但可以多次呼叫此函式來取得多個句柄。

如果計算機進入中斷睡眠或待命等連線的電源儲存模式，則必須重新初始化 QOSStartTrackingClient 等現有和作用中網路實驗。 此流程的重新建立會鏡像現有套接字所需的清除和建立活動。 必須建立新的句柄，而且必須重新建立並讀取流程。

範例

下列程式代碼說明函式的使用和必要的參數初始化。 實際值會根據 QoS 版本而有所不同。

必須包含 Winsock.h，才能使用 WSAGetLastError 函式。

如需完整的範例程式代碼清單，請參閱 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
標頭 qos2.h (包括 Qos2.h)
程式庫 Qwave.lib
Dll Qwave.dll

另請參閱

品質 Windows 音訊/視訊體驗 (qWAVE)