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

# RegisterLampArrayStatusCallback

> RegisterLampArrayStatusCallback

# RegisterLampArrayStatusCallback

注册一个回调函数，每次 LampArray 状态发生变化时都会调用它。

## 语法

```cpp theme={null}
STDAPI RegisterLampArrayStatusCallback(
    _In_ LampArrayStatusCallback callbackFunc,
    LampArrayEnumerationKind enumerationKind,
    _In_opt_ void * context,
    _Out_ _Result_zeroonfailure_ LampArrayCallbackToken * callbackToken);
```

### 参数

*callbackFunc*   \_In\_
类型：[LampArrayStatusCallback](/reference/lighting/lamparray/functions/lamparraystatuscallback)

要注册的、由调用方定义的函数。每当 LampArray 状态发生变化时都会调用它。

*enumerationKind*\
类型：[LampArrayEnumerationKind](/reference/lighting/lamparray/enums/lamparrayenumerationkind)

指定 [LampArrayStatusCallback](/reference/lighting/lamparray/functions/lamparraystatuscallback) 函数所期望的设备枚举行为。

*context*   \_In\_opt\_\
类型：void\*

指向包含回调函数相关信息的对象的指针。通常，这是调用对象。

*callbackToken*   \_Out\_ \_Result\_zeroonfailure\_
类型：LampArrayCallbackToken\*

可用于以后取消注册该回调函数的令牌值。

### 返回值

类型：HRESULT

函数结果。

## 备注

LampArrayEnumerationKind 参数允许调用方指定如何为在调用时已连接的 LampArray 设备接收回调。如果选择 [LampArrayEnumerationKind::Blocking](/reference/lighting/lamparray/enums/lamparrayenumerationkind)，[RegisterLampArrayStatusCallback](/reference/lighting/lamparray/functions/registerlamparraystatuscallback) 函数将阻塞，直到对每个已连接设备都调用了该回调（这意味着回调将在调用线程上执行）。

在注册第一个回调时，LampArray API 会启动一个工作线程来处理 ILampArray 设备状态通知。这些事件并不频繁，工作线程在其他时间保持等待状态。注册调用返回后，所有后续的 LampArrayStatusCallbacks 将在此工作线程上按顺序执行。

如果指定 [LampArrayEnumerationKind::Async](/reference/lighting/lamparray/enums/lamparrayenumerationkind)，此调用会立即返回，且调用时已连接的任何 LampArrays 将在前述 LampArray 回调工作线程上进行枚举。

以下代码是注册和取消注册 [LampArrayStatusCallback](/reference/lighting/lamparray/functions/lamparraystatuscallback) 函数的示例：

```c++ theme={null}
void MyLampArrayStatusCallback(
    _In_opt_ void* context,
    LampArrayStatus currentStatus,
    LampArrayStatus previousStatus,
    _In_ ILampArray* lampArray)
{
    // Application-specific code to handle LampArray status changes
}

void MonitorLampArrays(
    _In_ volatile bool & cancelMonitoring) noexcept
{
    LampArrayCallbackToken token = LAMPARRAY_INVALID_CALLBACK_TOKEN_VALUE;
    if (SUCCEEDED(RegisterLampArrayStatusCallback(
        MyLampArrayStatusCallback,
        LampArrayEnumerationKind::Async,
        nullptr /* context */,
        &token)))
    {
        while (!cancelMonitoring)
        {
            Sleep(100);
        }

        UnregisterLampArrayCallback(token, 5000);
    }
}
```

## 要求

**头文件：** LampArray.h

**库：** xgameplatform.lib

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

## 另请参阅

[光照 API 概览](/build/core-features/common/lighting/gc-lighting-toc)\
[光照基础](/build/core-features/common/lighting/lighting-basics)\
[LampArrayStatusCallback](/reference/lighting/lamparray/functions/lamparraystatuscallback)\
[UnregisterLampArrayCallback](/reference/lighting/lamparray/functions/unregisterlamparraycallback)\
[LampArrayEnumerationKind](/reference/lighting/lamparray/enums/lamparrayenumerationkind)


## Related topics

- [LampArrayStatusCallback](/zh-CN/reference/lighting/lamparray/functions/lamparraystatuscallback.md)
- [LampArrayEnumerationKind 枚举](/zh-CN/reference/lighting/lamparray/enums/lamparrayenumerationkind.md)
- [光照 API 参考](/zh-CN/reference/lighting/gc-reference-lighting-toc.md)
- [RegisterLampArrayCallback](/zh-CN/reference/lighting/lamparray/functions/registerlamparraycallback.md)
- [LampArray](/zh-CN/reference/lighting/lamparray/lamparray_members.md)