Developer

API Reference

IActorFrame

Brew Release
Brew MP 1.0.2
See Also
IActorFrameLoader_Create()
Description
ActorFrame is an optional framework that can be used to develop actors. It strives to make life easier by:
1) Following a simple model of one object per actor. 2) Liberating actor developers from error prone reference counting (exclusively when dealing with IVfsNodes created by IActorFrame) 3) Additional behaviours (event handlers, accessors [_GetData] and mutators [_SetData]) can be applied to VFS nodes by supplying individual functions with friendly signatures. 4) Providing a set of helper functions to make TrigML event handling easier.
An actor object must be derived from the ActorBase class; the lifecycle of this object is maintained by the framework. When it is time to delete the actor, the destructor supplied in the ActorBase::pfnDtor field will be invoked to allow the actor to clean up.
The ActorBase class provides access to the IActorFrame interface. This interface includes some higher-level APIs (as compared to IActorContext) to create various types of VFS nodes. Unlike IActorContext, the lifecycle of VFS nodes created by IActorFrame is also maintained by the framework.
ActorFrame guarantees the VFS nodes it creates will exist for as long as the actor exists. Therefore no reference counting is required! The exception to this rule are children of CacheContainers --- ActorFrame guarantees that these nodes will exist until the PFNACTORFRAME_DESTROYNODE function is called for that CacheContainer. WARNING: VFS nodes created by IActorContext and all other BREW interfaces are still subject to the standard BREW reference counting rules.
Usage
The following is a simple example of how to use IActorFrameLoader and IActorFrame to build an actor:

      // SampleActor class. 
      typedef struct {
         // All IActorFrame actors must functionally derive from ActorBase
         ActorBase base; 
   
         // Other actor specific fields...
         int actorSpecificData1;
         AECHAR *actorSpecificData2;
      } SampleActor;
   
   
      int SampleActor_New(
         IActorLoader **ppActorLoader, 
         IShell *pShell,
         IModule *pModule
      )
      {
         int result;
   
         IActorFrameLoader *pLoader = NULL;
         result = ISHELL_CreateInstance(
            pShell, 
            AEECLSID_ActorFrameLoader, 
            &pLoader
         );
   
         if (pLoader != NULL) {
            result = IActorFrameLoader_Create(
               pLoader,
               sizeof(SampleActorClass),
               (PFNACTORFRAME_CREATENODE) SampleActor_CreateRootNode,
               pModule,
               ppActorLoader
            );
            IActorFrameLoader_Release(pLoader);
         }
         return result;
      }
   
      int SampleActor_CreateRootNode(
         SampleActor *pMe,
         IVfsContainer *pParent,
         VfsPathElement name
      )
      {
         // Set our destructor for easy cleanup
         pMe->base.pfnDtor = (PFNACTORFRAME_DTOR) SampleActor_Dtor;
      
         pMe->actorSpecificData2 = WSTRDUP(L"Hello");
         if (NULL == pMe->actorSpecificData2) {
            return ENOMEMORY;
         }
      
         (void) IActorFrame_CreateConstInteger(
            &pMe->base,
            name,
            pParent,
            123 // Value of the node
         );
         return SUCCESS;
      }
      
      void SampleActor_Dtor(SampleActor *pMe)
      {
         FREEIF(pMe->actorSpecificData2);
      }

  • Follow