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

# IAcpHal::Connect

> IAcpHal::Connect

# IAcpHal::Connect

连接到 ACP。

## 语法

```cpp theme={null}
HRESULT Connect(  
         UINT32 numCommands,  
         UINT32 numMessages  
)  
```

### 参数

*numCommands*   \
类型:UINT32

指定要在 ACP 命令队列中分配的命令数量。该值必须大于零,并且要足以容纳每个 2.67 毫秒音频帧所发出的全部命令。

*numMessages*   \
类型:UINT32

指定要在 ACP 消息队列中分配的消息数量。如果游戏不处理接收到的消息,该值可以为零。如果注册了 *command completed* 消息(参见 [ACP\_MESSAGE\_TYPE](/reference/audio/acphal/enums/acp_message_type)),那么消息数量至少要与命令数量相同。通常此消息队列的处理频率低于每个音频帧一次,因此请预留几帧数量的消息容量。

### 返回值

类型:HRESULT

如果方法成功,则返回 `S_OK`。如果方法失败,则返回以下代码之一(部分列表):

| 返回代码                       | 描述                                 |
| -------------------------- | ---------------------------------- |
| E\_INVALIDARG              | 一个或多个参数无效,或者 *numCommands* 参数设置为零。 |
| E\_OUTOFMEMORY             | 内存分配失败。                            |
| ACP\_E\_ALREADY\_CONNECTED | 已连接到 ACP。                          |
| E\_UNEXPECTED              | 发生了意外错误。                           |
| ACP\_E\_QUEUE\_FULL        | ACP 队列已满。                          |
| E\_TIMEOUT                 | 发生了超时错误。                           |

## 备注

在调用此接口中的任何其他方法之前,请先调用此方法。但是,在调用 [Disconnect](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_disconnect) 之后,可以再次调用此方法。另请参阅 [SubmitCommand](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand)。

如果该方法因 `E_INVALIDARG` 或 `ACP_E_ALREADY_CONNECTED` 以外的错误而失败,建议销毁**所有**现有的 ACP 客户端对象,并使用 [AcpHalReleaseShapeContexts](/reference/audio/acphal/functions/acphalreleaseshapecontexts) 释放已分配的 SHAPE 上下文。之后应根据需要,分别使用 [AcpHalAllocateShapeContexts](/reference/audio/acphal/functions/acphalallocateshapecontexts) 和 [AcpHalCreate](/reference/audio/acphal/functions/acphalcreate) 重新分配/创建新的 SHAPE 上下文和 ACP 客户端对象。

## 要求

**头文件:** acphal.h

**支持的平台:** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[Disconnect](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_disconnect)\
[AcpHal](/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [SHAPE 音频流程图构建最佳实践](/zh-CN/build/console-features/audio/overviews/best-practices-audio-flowgraph-construction.md)
- [IAcpHal::Disconnect](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_disconnect.md)
- [IAcpHal::SubmitCommand](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand.md)
- [IAcpHal::PopMessage](/zh-CN/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_popmessage.md)