> ## 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.

# XAsyncBlock

> XAsyncBlock

# XAsyncBlock

代表非同步呼叫的存留期。

## 語法

```cpp theme={null}
typedef struct XAsyncBlock {  
    XTaskQueueHandle queue;  
    void* context;  
    XAsyncCompletionRoutine* callback;  
    unsigned internal[sizeof ( void* ) * 4];  
} XAsyncBlock  
```

### 成員

*queue*\
類型：XTaskQueueHandle

選擇性。非同步呼叫的工作佇列控制代碼，也可選擇性地用於 *callback* 中指定的完成回呼。如果設定為 null，非同步呼叫會嘗試使用處理序工作佇列。如果處理序工作佇列也設定為 null，則非同步呼叫會失敗並傳回 `E_NO_TASK_QUEUE`。

*context*\
類型：void\*

選擇性。指向傳遞給完成回呼之資訊的指標。

*callback*\
類型：[XAsyncCompletionRoutine\*](/zh-TW/reference/system/xasync/functions/xasynccompletionroutine)

選擇性的回呼，會在呼叫完成時叫用。

*internal*\
類型：unsigned char\[sizeof(void\*) \* 4]

保留供內部使用。

## 備註

`XAsyncBlock` 結構代表非同步呼叫的存留期。您可以使用 `XAsyncBlock` 先叫用非同步呼叫，並為該呼叫提供選擇性的完成回呼。之後，您可以將 `XAsyncBlock` 當作該特定呼叫叫用的控制代碼使用。當您叫用非同步呼叫時，該呼叫會提交至工作佇列以供執行。工作佇列可讓您決定由哪個執行緒執行非同步呼叫，以及由哪個執行緒叫用完成回呼 (如果有指定的話)。您不需要建立工作佇列即可呼叫非同步呼叫。如果未在 *queue* 中指定工作佇列，預設會使用處理序工作佇列。一般而言，處理序工作佇列會將非同步呼叫分派至系統執行緒集區，而完成回呼則會在起始非同步呼叫的執行緒處於可警示狀態時，於該執行緒上叫用。如需工作佇列分派模式的詳細資訊，請參閱[非同步工作佇列設計](/zh-TW/build/core-features/common/async/async-task-queue-design)。

<Note>叫用非同步呼叫之後，請勿修改該非同步呼叫之 `XAsyncBlock` 中的任何參數。</Note>

### 完成回呼

您可以選擇在 *callback* 中指定指向回呼函式的指標，為非同步呼叫提供*完成回呼*。完成回呼是在非同步呼叫完成之後執行的回呼函式。您可以在 *context* 中指定代表完成回呼資訊的指標，以將內容特定的資料提供給完成回呼。

如果您未在 *callback* 中指定完成回呼，可以使用 [XAsyncGetStatus](/zh-TW/reference/system/xasync/functions/xasyncgetstatus) 函式定期檢查非同步呼叫是否已完成，然後視需要使用 [XAsyncGetResult](/zh-TW/reference/system/xasyncprovider/functions/xasyncgetresult) 和 [XAsyncGetResultSize](/zh-TW/reference/system/xasync/functions/xasyncgetresultsize) 從已完成的工作取得結果。

如需完成回呼的詳細資訊，請參閱 [XAsyncCompletionRoutine](/zh-TW/reference/system/xasync/functions/xasynccompletionroutine)。

### 實作 XAsyncBlock

您可以使用 [XAsyncProvider](/zh-TW/reference/system/xasyncprovider/xasyncprovider_members) 透過 `XAsyncBlock` 實作您自己的非同步功能，然後使用 [XTaskQueue](/zh-TW/reference/system/xtaskqueue/xtaskqueue_members) 函式叫用該功能。您也可以叫用 [XAsyncRun](/zh-TW/reference/system/xasync/functions/xasyncrun) 來呼叫非同步呼叫，這是一個協助程式函式，會在內部使用 `XAsyncProvider` 來執行和追蹤由另一個協助程式函式 [XAsyncWork](/zh-TW/reference/system/xasync/functions/xasyncwork) 指定的回呼函式。如需使用 `XAsyncProvider` 和 `XAsyncBlock` 實作您自己的非同步功能的詳細資訊，請參閱[非同步程式設計模型](/zh-TW/build/core-features/common/async/async-programming-model)。

`XAsyncBlock` 必須在非同步呼叫的整個存留期內保留在記憶體中。不過，如果 `XAsyncBlock` 是動態配置的，則可以在非同步呼叫的完成回呼中安全地將其刪除。

## 需求

**標頭：** XAsync.h

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

## 概念文件

* [設定非同步工作](/zh-TW/build/core-features/common/async/async-libraries/async-library-xasync-example-setup-async-task)
* [XAsync 程式庫概觀](/zh-TW/build/core-features/common/async/async-libraries/async-library-xasync)
* [XAsyncProvider 程式庫概觀](/zh-TW/build/core-features/common/async/async-libraries/async-library-xasyncprovider)
* [XTaskQueue 程式庫概觀](/zh-TW/build/core-features/common/async/async-libraries/async-library-xtaskqueue)
* [非同步程式設計模型](/zh-TW/build/core-features/common/async/async-programming-model)
* [非同步程式設計的設計目標與改進](/zh-TW/build/core-features/common/async/async-whitepaper)
* [傳送邀請](/zh-TW/services/xbox-services/multiplayer/invites/how-to/live-invites-send)

## 另請參閱

[XAsync 成員](/zh-TW/reference/system/xasync/xasync_members)\
[XAsyncProvider 成員](/zh-TW/reference/system/xasyncprovider/xasyncprovider_members)\
[非同步程式設計模型](/zh-TW/build/core-features/common/async/async-programming-model)


## Related topics

- [XAsyncBlock](/reference/system/xasync/structs/xasyncblock.md)
- [Making Async Calls](/services/playfab/sdks/c/async.md)
- [PFGroupsBlockEntityAsync](/services/playfab/api-references/c/pfgroups/functions/pfgroupsblockentityasync.md)
- [PFGroupsListGroupBlocksAsync](/services/playfab/api-references/c/pfgroups/functions/pfgroupslistgroupblocksasync.md)
- [Making async calls in the XSAPI C API](/services/xbox-services/fundamentals/xbox-services-api/live-flatc-async-patterns.md)