Wrap (lx_wrap.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search

The wrap header provides classes and functions for:

  • Localizing interfaces from nexus as C++ objects
  • Exporting C++ objects as interface to nexus
  • Managing conversions between the two

Localizing Interfaces

When nexus passes an object to the client it will be of type ILxUnknownID, a pointer to an unknown interface, or LXtObjectID, a void pointer equivalent to an ILxUnknownID. In order to be able to call methods on the interface it has to be localized. This header defines the core types used for localization.

CLxLocalizedObject

A localized object is a C++ wrapper around a COM interface -- a kind of container for native nexus objects allowing them to be used like C++ objects. This is a pure virtual class, and has methods for manipulating the wrapper.

  • guid() -- return the interface guid, mostly for internal use
  • set(obj) -- set the localization wrapper to use the object
  • take(obj) -- same as set but also releases the object, taking ownership
  • copy(loc) -- sets this to use the same object as another
  • test() -- returns true if this wrapper has a valid interface
  • clear() -- releases the interface for the current object
  • get(ppvObj) -- sets a ppvObj pointer for exporting wrapped objects
  • cast to ILxUnknownID -- casts the current object to the forms most often wanted in method calls

Case is important in method names. Lowercase methods manipulate the wrapper, while uppercase methods call through the interface. Don't call obj.clear() when you mean obj.Clear().

CLxLocalize

This template class specializes the localization wrapper for a specific interface. It also adds the "=" assignment operator to localized objects.

CLxUser_interface

The user class for a wrapper is defined specifically for each interface. It derives from CLxLocalizedObject as follows:

  • CLxUser_interface -- adds nice user methods for calling raw interface methods
    • CLxLoc_interface -- defines C++ versions of the raw interface methods (generated)
      • CLxLocalize<ILxinterface> -- wraps the interface as a localized template object
        • CLxLocalizedObject -- abstract root class

Exporting Objects

Exporting C++ classes as COM objects is done using a kind of factory called a polymorph.

CLxGenericPolymorph

This class is the general factory for COM objects. It can be subclassed for managing specific object types.

  • NewObj(), FreeObj() -- virtual functions for allocating and freeing the class instance pointer.
  • AddInterface() -- called during construction, this adds the interfaces supported by the COM object.
  • TestInterface() -- returns true if an interface GUID is supported.
  • DefaultInterface() -- returns the class interface for this object, which is the first interface added.
  • Spawn() -- creates a new COM object using the core object and interfaces.

The polymorph object for a given COM object must exist as long as any of the COM objects that it spawns. This is normally done by caching these by name in the server or spawner tables for the module.

CLxPolymorph

This template class configures a polymorph for the target class. Spawning creates a new instance of the class, and it's destroyed when its use count goes to zero.

  • Cast() -- takes a COM object ILxUnknownID pointer and returns the template class. This is done without type checking.
  • Alloc() -- several flavors of this function create new objects, returning both the C++ object pointer and the COM object.

CLxSingletonPolymorph

A variation of the polymorph class that allows any object that derives from it to be exported as a standalone COM object.

Other