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

# XApuConnect

> XApuConnect

# XApuConnect

建立連線，並為音訊處理單元 (XAPU) 配置必要的資源。

## 語法

```cpp theme={null}
HRESULT XApuConnect(  
         XApuConnectInputParameters* params,  
         XApuConnectOutputParameters* data,  
         XApuHandle* handle  
)  
```

### 參數

*params*   \_In\_\
類型: [XApuConnectInputParameters\*](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters.md)

傳遞給 XApuConnect 以配置資源的參數。

*data*   \_Out\_\
類型: [XApuConnectOutputParameters\*](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters.md)

XApuConnect 傳回的參數。

*handle*   \_Outptr\_\
類型: XApuHandle\*

傳回之 XAPU 控制代碼的指標。呼叫其他 XAPU API 時，會使用此控制代碼來指出要操作的 XAPU 執行個體。

### 傳回值

類型: HRESULT

如果成功，會傳回 S\_OK；否則會傳回錯誤碼。

## 備註

呼叫端必須指定 XAPU 用戶端要執行的 [XApuProcessType](https://docs.xbox.com/zh-TW/reference/audio/xapu/enums/xapuprocesstype.md)。XAPU 執行個體在其存留期間只能處理一種類型的處理程序。若要執行兩個以上不同的處理程序，必須具現化兩個以上的 XAPU 執行個體。

在 [XApuConnectInputParameters](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters.md) 中，呼叫端必須指定下列項目:

* XAPU 預期要同時處理的串流數目上限。
* 每個串流的佇列命令數目上限。
* 所有命令和串流所需的記憶體配置總量。這包括在串流數目上限乘以每個串流佇列命令數的範圍內，輸入、輸出和處理資料的總配置量。

如果呼叫成功，[XApuConnectOutputParameters::baseData](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters.md) 參數會指向一個記憶體區塊，呼叫端應使用此區塊來傳遞輸入資料並擷取串流的輸出資料。分割和回收此記憶體區塊由呼叫端負責。此配置會在呼叫 [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md) 時釋放。

設定 [XApuConnectOptions::EnableResultReadyEvent](https://docs.xbox.com/zh-TW/reference/audio/xapu/enums/xapuconnectoptions.md) 時，[XApuConnectOutputParameters::resultReadyEvent](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters.md) 會包含 Win32 事件控制代碼。此控制代碼會在呼叫 [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md) 時關閉。

此控制代碼會在呼叫 [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md) 時關閉。

不建議經常呼叫 [XapuConnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapuconnect.md) 和 [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md) 來啟動和停止串流，因為這些呼叫相當耗時，而且可能因記憶體片段化而導致資源損失。相反地，應在串流工作階段初始化時呼叫 [XapuConnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapuconnect.md) 一次，然後在串流期間使用 [XApuCommandType::Activate](https://docs.xbox.com/zh-TW/reference/audio/xapu/enums/xapucommandtype.md) 和 [XApuCommandType::Deactivate](https://docs.xbox.com/zh-TW/reference/audio/xapu/enums/xapucommandtype.md) 來啟動和停止串流。在串流工作階段結束時，應呼叫 [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md)。這適用於所有 XAPU 用戶端。

## 需求

**標頭:** xapu.h

**程式庫:** xapu.lib

**支援的平台:** XBOX Series X|S

## 概念文件

* [XAPU 概觀](https://docs.xbox.com/zh-TW/build/console-features/audio/overviews/xapu-overview.md)

## 另請參閱

[XAPU](https://docs.xbox.com/zh-TW/reference/audio/xapu/xapu_members.md)\
[XApuDecodeConvertCommand](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand.md)\
[XApuDequeueResult](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudequeueresult.md)\
[XApuEnqueueCommand](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapuenqueuecommand.md)\
[XApuGetResultCount](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapugetresultcount.md)


## Related topics

- [XApuConnectOptions](https://docs.xbox.com/zh-TW/reference/audio/xapu/enums/xapuconnectoptions.md)
- [XApuConnectOutputParameters](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters.md)
- [XApuConnectInputParameters](https://docs.xbox.com/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters.md)
- [XApuDisconnect](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudisconnect.md)
- [XApuDequeueResult](https://docs.xbox.com/zh-TW/reference/audio/xapu/functions/xapudequeueresult.md)