> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XTaskQueueRegisterWaiter

> XTaskQueueRegisterWaiter

# XTaskQueueRegisterWaiter

向工作佇列註冊等候控制代碼。

## 語法

```cpp theme={null}
HRESULT XTaskQueueRegisterWaiter(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         HANDLE waitHandle,  
         void* callbackContext,  
         XTaskQueueCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### 參數

*queue*   \_In\_\
類型：XTaskQueueHandle

要提交回呼的佇列。

*port*   \_In\_\
類型：[XTaskQueuePort](/zh-TW/reference/system/xtaskqueue/enums/xtaskqueueport)

要提交回呼的連接埠。回呼可以指派給工作連接埠或完成連接埠。

*waitHandle*   \_In\_\
類型：HANDLE

要監視的控制代碼。

<Note>這是等候控制代碼，收到訊號時會導致叫用回呼。等候控制代碼通常是自動重設或手動重設事件。如果等候控制代碼是手動重設，只要事件處於已收到訊號狀態，就會重複叫用回呼。如果這不是您要的行為，請在回呼中重設事件，或取消註冊等候回呼。</Note>

*callbackContext*   \_In\_opt\_\
類型：void\*

將傳遞給回呼的選擇性內容指標。

*callback*   \_In\_\
類型：[XTaskQueueCallback\*](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuecallback)

回呼函式的指標。

*token*   \_Out\_\
類型：[XTaskQueueRegistrationToken\*](/zh-TW/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

註冊權杖。可以將此權杖傳遞給 [XTaskQueueUnregisterWaiter](/zh-TW/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter) 以取消註冊等候。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

當等候控制代碼得到滿足時，工作佇列會叫用指定的回呼。這提供一種有效率的方式，可在控制代碼收到訊號時將項目加入工作佇列。

下列範例會向工作佇列註冊 Win32 核心控制代碼。當控制代碼收到訊號時，您的回呼就會提交至佇列。一般而言，您會建立自動重設事件來發出訊號。如果控制代碼不是自動重設，只要控制代碼處於已收到訊號狀態，每當目前的回呼完成時，就會提交新的回呼。

```cpp theme={null}
void CreatingTaskQueueWaiter()
{
    HANDLE waitEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);
    if (waitEvent == nullptr)
    {
        printf("Error creating wait handle: %d\r\n", GetLastError());
        return;
    }

    XTaskQueueHandle queue;

    HRESULT hr = XTaskQueueCreate(
        XTaskQueueDispatchMode::ThreadPool,
        XTaskQueueDispatchMode::ThreadPool, 
        &queue);

    if (FAILED(hr))
    {
        printf("Error creating task queue: %x\n", hr);
        CloseHandle(waitEvent);
        return;
    }

    auto callback = [](void*, bool)
    {
        printf("Callback invoked.\r\n");
    };

    XTaskQueueRegistrationToken token;

    hr = XTaskQueueRegisterWaiter(
        queue, 
        XTaskQueuePort::Completion, 
        waitEvent, 
        nullptr, 
        callback, 
        &token);

    if (FAILED(hr))
    {
        printf("Error registering task queue waiter: %x\n", hr);
        CloseHandle(waitEvent);
        XTaskQueueCloseHandle(queue);
        return;
    }

    // Now, whenever our wait event becomes signaled the callback will be called.
    for (uint32_t i = 0; i < 5; i++)
    {
        SetEvent(waitEvent);
        Sleep(100);
    }

    // Note: unregistering the waiter is optional
    XTaskQueueUnregisterWaiter(queue, token);
    XTaskQueueCloseHandle(queue);
    CloseHandle(waitEvent);
}
```

## 需求

**標頭：** XTaskQueue.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [XTaskQueue 程式庫概觀](/zh-TW/build/core-features/common/async/async-libraries/async-library-xtaskqueue)
* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XTaskQueue 成員](/zh-TW/reference/system/xtaskqueue/xtaskqueue_members)\
[非同步程式設計模型](/zh-TW/build/core-features/common/async/async-programming-model)\
[非同步工作佇列設計](/zh-TW/build/core-features/common/async/async-task-queue-design)


## Related topics

- [XTaskQueueRegisterWaiter](/reference/system/xtaskqueue/functions/xtaskqueueregisterwaiter.md)
- [XTaskQueueUnregisterWaiter](/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter.md)