WHvCreateTrigger

建立一個觸發物件，當主機事件被發出訊號時，會向分割區傳送預先設定的中斷或事件。

語法

typedef enum WHV_TRIGGER_TYPE
{
#if defined(_AMD64_)
    WHvTriggerTypeInterrupt = 0,
#endif
    WHvTriggerTypeSynicEvent = 1,
    WHvTriggerTypeDeviceInterrupt = 2,
} WHV_TRIGGER_TYPE;

typedef struct WHV_TRIGGER_PARAMETERS
{
    WHV_TRIGGER_TYPE TriggerType;
    UINT32 Reserved;
    union
    {
#if defined(_AMD64_)
        WHV_INTERRUPT_CONTROL Interrupt;
#endif
        WHV_SYNIC_EVENT_PARAMETERS SynicEvent;
        struct
        {
            UINT64 LogicalDeviceId;
            UINT64 MsiAddress;
            UINT32 MsiData;
            UINT32 Reserved;
        } DeviceInterrupt;
    };
} WHV_TRIGGER_PARAMETERS;

typedef PVOID WHV_TRIGGER_HANDLE;

HRESULT
WINAPI
WHvCreateTrigger(
    _In_ WHV_PARTITION_HANDLE Partition,
    _In_ const WHV_TRIGGER_PARAMETERS* Parameters,
    _Out_ WHV_TRIGGER_HANDLE* TriggerHandle,
    _Out_ HANDLE* EventHandle
    );

Parameters

Partition

handle 轉到 partition 物件。

Parameters

指定觸發器的類型及要傳送到分割區的動作。 TriggerType成員選擇使用聯集的哪個成員： WHvTriggerTypeInterrupt （僅限 x64）使用Interrupt、WHvTriggerTypeSynicEvent使用SynicEvent、使用、WHvTriggerTypeDeviceInterrupt使用DeviceInterrupt。 請參閱 觸發資料類型 以了解每個成員的完整定義。

TriggerHandle

接收新建立觸發物件的句柄。 用這個 handle WHvUpdateTriggerParameters 來重新定位觸發器，用 來 WHvDeleteTrigger 刪除它。

EventHandle

會收到一個 Win32 事件帳號。 呼叫者透過發送此事件來啟動觸發器——例如，以 —— SetEvent 啟動該觸發器，使設定 Parameters 中的動作被送達到分割區。 呼叫者擁有此帳號，當不再需要時必須解除 CloseHandle 。

傳回值

如果函式成功，則傳回值為 S_OK。

如果 中的Parameters參數對所選觸發類型不適用，函式會回傳E_INVALIDARG。 對於觸發條件 WHvTriggerTypeDeviceInterrupt ，無效 LogicalDeviceId 值會回傳 HRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID)。

Remarks

該函式會 WHvCreateTrigger 建立一個分割範圍物件，將主機事件綁定到預先設定的訪客目標動作。 觸發器建立後，主機會向回 EventHandle 傳訊號——例如來自 I/O 完成例程或其他執行緒——將設定好的中斷或事件送達分區，無需在每次交付中分別呼叫 API 或超呼叫。 這使得觸發器非常適合用於資料路徑情境，如虛擬網卡接收佇列、儲存完成環及通道訊號。

TriggerType成員Parameters選擇事件發出信號時所執行的動作：

• WHvTriggerTypeInterrupt （僅限 x64）注入由 WHV_INTERRUPT_CONTROL 結構描述的虛擬中斷——與 的效果 WHvRequestInterrupt相同，但預先啟動，每次事件發出訊號時都能重新傳送。
• WHvTriggerTypeSynicEvent 在虛擬處理器上設定合成中斷控制器（SynIC）事件標誌，虛擬信任層級，並由結構命名 WHV_SYNIC_EVENT_PARAMETERS SINT。 TargetVtl 一定是 VTL 0。
• WHvTriggerTypeDeviceInterrupt為由 LogicalDeviceIdMsiAddressMsiData、 和 命名的邏輯裝置斷言一個裝置（MSI）中斷。 邏輯裝置必須已經存在於分割區中，且中斷必須在觸發器被發出訊號前映射——例如通過 WHvMapVpciDeviceInterrupt ——。

傳送是非同步的。 多個訊號在交付完成前抵達，可能會合併成單一交付。 訪客必須準備好在每次送達時耗盡觸發器所代表的佇列或環線。

WHvTriggerTypeInterrupt 而 Interrupt Member of WHV_TRIGGER_PARAMETERS 僅在 x64 上提供。 在 Arm64 上，只有 WHvTriggerTypeSynicEvent 和 WHvTriggerTypeDeviceInterrupt 才有。

觸發器和事件把柄的壽命是獨立的。 刪除觸發器 並不會使觸發 WHvDeleteTrigger 器失效 EventHandle;呼叫者仍必須以 CloseHandle關閉 。 觸發點不會在活體遷徙中被保存。

Requirements

另請參閱

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• 觸發資料類型
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows Hypervisor 平台 API 定義