终止支持通知：2026 年 5 月 20 日， AWS 将终止对的支持。 AWS SimSpace Weaver 2026 年 5 月 20 日之后，您将无法再访问 SimSpace Weaver 控制台或 SimSpace Weaver 资源。有关更多信息，请参阅[AWS SimSpace Weaver 终止支持](https://docs.aws.amazon.com/simspaceweaver/latest/userguide/simspaceweaver-end-of-support.html)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 实体事件
<a name="working-with_app-sdk_events"></a>

您可以使用 SimSpace Weaver 应用程序 SDK 中的以下函数来获取所有权和订阅事件：
+ `Result<OwnershipChangeList> OwnershipChanges(Transaction& txn) `
+ `Result<SubscriptionChangeList> AllSubscriptionEvents(Transaction& txn) `

如果您需要回调驱动的实体事件处理，则可以使用 SimSpace Weaver 演示框架。有关更多信息，请参阅以下网站头文件：
+ `sdk-folder/packaging-tools/samples/ext/DemoFramework/include/DemoFramework/EntityEventProcessor.h`

您还可以创建自己的实体事件处理。

**Topics**
+ [遍历所拥有实体的事件](working-with_app-sdk_events_own.md)
+ [遍历所订阅实体的事件](working-with_app-sdk_events_sub.md)
+ [遍历实体的所有权更改事件](working-with_app-sdk_events_change.md)

# 遍历所拥有实体的事件
<a name="working-with_app-sdk_events_own"></a>

使用 `OwnershipChanges()` 可获取所拥有实体（应用程序所有权区域中的实体）的事件列表。该函数具有以下签名：

```
Result<OwnershipChangeList> OwnershipChanges(Transaction& txn)
```

然后使用循环遍历各个实体，如以下示例所示。

**Example 示例**  

```
WEAVERRUNTIME_TRY(Result<Api::OwnershipChangeList> ownershipChangesResult, Api::OwnershipChanges(transaction));

for (const Api::OwnershipChange& event : ownershipChangeList.changes)
{
    Api::Entity entity = event.entity;
    Api::ChangeListAction action = event.action;

    switch (action)
    {
    case Api::ChangeListAction::None:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Remove:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Add:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Update:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Reject:
        // insert code to handle the event
        break;
    }
}
```

**事件类型**
+ `None` – 实体位于该区域内，未修改其位置和字段数据。
+ `Remove` – 实体已从该区域内移除。
+ `Add` – 实体已添加到该区域内。
+ `Update` – 实体位于该区域内且已被修改。
+ `Reject` – 应用程序未能将实体从该区域内移除。

**注意**  
如果发生 `Reject` 事件，应用程序将在下一个刻度再次尝试转移。

# 遍历所订阅实体的事件
<a name="working-with_app-sdk_events_sub"></a>

使用 `AllSubscriptionEvents()` 可获取所订阅实体（应用程序订阅区域中的实体）的事件列表。该函数具有以下签名：

```
Result<SubscriptionChangeList> AllSubscriptionEvents(Transaction& txn)
```

然后使用循环遍历各个实体，如以下示例所示。

**Example 示例**  

```
WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionChangeList, Api::AllSubscriptionEvents(transaction));

for (const Api::SubscriptionEvent& event : subscriptionChangeList.changes)
{
    Api::Entity entity = event.entity;
    Api::ChangeListAction action = event.action;

    switch (action)
    {
    case Api::ChangeListAction::None:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Remove:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Add:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Update:
        // insert code to handle the event
        break;
    case Api::ChangeListAction::Reject:
        // insert code to handle the event
        break;
    }
}
```

**事件类型**
+ `None` – 实体位于该区域内，未修改其位置和字段数据。
+ `Remove` – 实体已从该区域内移除。
+ `Add` – 实体已添加到该区域内。
+ `Update` – 实体位于该区域内且已被修改。
+ `Reject` – 应用程序未能将实体从该区域内移除。

**注意**  
如果发生 `Reject` 事件，应用程序将在下一个刻度再次尝试转移。

# 遍历实体的所有权更改事件
<a name="working-with_app-sdk_events_change"></a>

要获取实体在所有权区域和订阅区域之间移动的事件，请比较实体所有权和订阅事件当前与之前的变化。

您可以通过阅读以下 API 来处理这些事件：
+ `Api::SubscriptionChangeList`
+ `Api::OwnershipEvents`

然后，您可以将更改与之前存储的数据进行比较。

以下示例说明了如何处理实体所有权更改事件。此示例假设，对于在已订阅实体和拥有的实体（任一方向）之间过渡的实体，所有权remove/add event occurs first followed by the subscription remove/add事件将在下一个勾选中显示。

**Example 示例**  

```
Result<void> ProcessOwnershipEvents(Transaction& transaction)
{
    using EntityIdsByAction =
        std::unordered_map<Api::ChangeListAction, 
        std::vector<Api::EntityId>>;
    using EntityIdSetByAction =
        std::unordered_map<Api::ChangeListAction, 
        std::unordered_set<Api::EntityId>>;
   
    static EntityIdsByAction m_entityIdsByPreviousOwnershipAction;
    
    EntityIdSetByAction entityIdSetByAction;
   
    /**
     * Enumerate Api::SubscriptionChangeList items 
     * and store Add and Remove events.
     */ 
    WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionEvents, 
        Api::AllSubscriptionEvents(transaction));
   
    for (const Api::SubscriptionEvent& event : subscriptionEvents.changes)
    {
        const Api::ChangeListAction action = event.action;
    
        switch (action)
        {
        case Api::ChangeListAction::Add:
        case Api::ChangeListAction::Remove:
    
            {
                entityIdSetByAction[action].insert(
                    event.entity.descriptor->id);
                break;
            }
        case Api::ChangeListAction::None:
        case Api::ChangeListAction::Update:
        case Api::ChangeListAction::Reject:
            {
                break;
            }
        }
    }
    
    EntityIdsByAction entityIdsByAction;
    
    /**
     * Enumerate Api::OwnershipChangeList items 
     * and store Add and Remove events.
     */
    
    WEAVERRUNTIME_TRY(Api::OwnershipChangeList ownershipChangeList, 
        Api::OwnershipChanges(transaction));
   
    for (const Api::OwnershipChange& event : ownershipChangeList.changes)
    {
        const Api::ChangeListAction action = event.action;
    
        switch (action)
        {
        case Api::ChangeListAction::Add:
        case Api::ChangeListAction::Remove:
            {
                entityIdsByAction[action].push_back(
                    event.entity.descriptor->id);
                break;
            }
        case Api::ChangeListAction::None:
        case Api::ChangeListAction::Update:
        case Api::ChangeListAction::Reject:
            {
                break;
            }
        }
    
    }
      
    std::vector<Api::EntityId> fromSubscribedToOwnedEntities;
    std::vector<Api::EntityId> fromOwnedToSubscribedEntities;
   
    /**
     * Enumerate the *previous* Api::OwnershipChangeList Remove items
     * and check if they are now in 
     * the *current* Api::SubscriptionChangeList Add items.
     *
     * If true, then that means 
     * OnEntityOwnershipChanged(bool isOwned = false)
     */ 
    for (const Api::EntityId& id : m_entityIdsByPreviousOwnershipAction[
        Api::ChangeListAction::Remove])
    {
        if (entityIdSetBySubscriptionAction[
            Api::ChangeListAction::Add].find(id) !=
                entityIdSetBySubscriptionAction[
                Api::ChangeListAction::Add].end())
        {
            fromOwnedToSubscribedEntities.push_back(id);
        }
    }
    
   
    /**
     * Enumerate the *previous* Api::OwnershipChangeList Add items
     * and check if they are now in 
     * the *current* Api::SubscriptionChangeList Remove items.
     *
     * If true, then that means 
     * OnEntityOwnershipChanged(bool isOwned = true)
     */ 
    for (const Api::EntityId& id : m_entityIdsByPreviousOwnershipAction[
        Api::ChangeListAction::Add])
    {
        if (entityIdSetBySubscriptionAction[
            Api::ChangeListAction::Remove].find(id) !=
            
                entityIdSetBySubscriptionAction[
                Api::ChangeListAction::Remove].end())
        {
            fromSubscribedToOwnedEntities.push_back(id);
        }
    }
    
    m_entityIdsByPreviousOwnershipAction = entityIdsByOwnershipAction;
    
    return Success();
}
```