Public Types | Public Member Functions
CComAPIHandler Class Reference

Detailed Description

The CComAPIHandler class implements a C++ wrapper for calling automation objects (scripting objects) or objects implemented using the Softimage Object Model (formerly called the COM API).

Automation objects can be created from C++ using CComAPIHandler::CreateInstance. The handler provides access to an automation object's methods and properties via CComAPIHandler::Call, CComAPIHandler::GetProperty, CComAPIHandler::PutProperty and CComAPIHandler::Invoke.

See also:
ConvertObject
Example:
        using namespace XSI;
        CStatus st;

        CComAPIHandler xsiuitoolkit;

        xsiuitoolkit.CreateInstance( L"XSI.UIToolkit");

        CValue return = xsiuitoolkit.GetProperty( L"ProgressBar" );

        // The return contains a pointer to the progressbar
        // that has had its reference count incremented, the destructor of CValue
        // takes care of dereferencing the pointer.
        CComAPIHandler progressbar( return );

        // set min/max
        progressbar.PutProperty( L"Minimum", (LONG)1 );
        progressbar.PutProperty( L"Maximum", (LONG)200 );
        progressbar.PutProperty( L"Value", (LONG)195 );
        progressbar.PutProperty( L"Caption", CValue(L"My Caption") );

        return = progressbar.GetProperty( L"Value" );

        // show the progress bar
        progressbar.PutProperty( L"Visible", true );

        while ( (progressbar.GetProperty( L"CancelPressed" ) == false) &&
            ((LONG)return < 200))
        {
            // your code here

            progressbar.Call( L"Increment", return );
        }

        // Just for good measure. If you put break points in the
        // code sometimes the progress dialog doesn't go away.
        progressbar.PutProperty( L"Visible", false );

#include <xsi_comapihandler.h>

List of all members.

Public Types

enum  InvokeFlag {
  Method,
  PropertyGet,
  PropertyPut,
  PropertyPutRef
}

Public Member Functions

 CComAPIHandler ()
virtual ~CComAPIHandler ()
 CComAPIHandler (const CValue &in_val)
 CComAPIHandler (const CComAPIHandler &in_obj)
CComAPIHandleroperator= (const CComAPIHandler &in_obj)
CStatus CreateInstance (const CString &in_name)
CStatus Attach (const CValue &in_val)
CStatus Detach (void)
CValue GetProperty (const CString &in_name) const
CStatus PutProperty (const CString &in_name, const CValue &in_newval) const
CStatus Call (const CString &in_name, CValue &io_return, const CValueArray &in_args=CValueArray()) const
CStatus Call (const CString &in_name, CValue &io_return, const CValue &in_arg) const
CStatus Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1) const
CStatus Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1, const CValue &in_arg2) const
CStatus Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1, const CValue &in_arg2, const CValue &in_arg3) const
CStatus Invoke (const CString &in_name, LONG in_flags, CValue &io_return, const CValueArray &in_args=CValueArray()) const
CValue GetRef (void) const

Member Enumeration Documentation

enum InvokeFlag

Flags to specify the context for the CComAPIHandler::Invoke function.

Enumerator:
Method 

Invokes a Method

PropertyGet 

Invokes getting a Property

PropertyPut 

Invokes setting a Property

PropertyPutRef 

Invokes setting a Property with a pointer


Constructor & Destructor Documentation

Default constructor.

virtual ~CComAPIHandler ( ) [virtual]

Default destructor.

CComAPIHandler ( const CValue in_val)

Constructor.

Parameters:
in_valContains a reference to a Softimage Object Model object.
Example:
Demonstrates how it is possible to access properties exposed on Softimage objects using the object model interface rather than the C++ API. This approach is important for accessing any method or property that is available in the object model but not the C++ API.
        using namespace XSI ;
        Application app ;
        Model root = app.GetActiveSceneRoot();

        X3DObject arc;
        root.AddGeometry( L"Arc", L"NurbsCurve", L"AnArc", arc ) ;

        // Construct a CComAPIHandler representing the newly created arc object
        CComAPIHandler omArc( arc.GetRef() );

        // Now we can use the object model to modify the object.
        // In this case we change the name property.
        omArc.PutProperty( L"Name", L"MyArc" ) ;

        // Retrieve the object name using the Name property
        CValue nameFromCOMAPI = omArc.GetProperty( L"Name" ) ;
        app.LogMessage( L"Softimage OM SIObject::Name property returns: " + nameFromCOMAPI.GetAsText() ) ;

        // In this case the same property is available directly from the C++ API
        // so we didn't really need to use CComAPIHandler
        CString nameFromCppAPI = arc.GetName() ;
        app.LogMessage( L"C++ API SIObject::GetName returns: " + nameFromCppAPI ) ;

        // Expected results:
        //'INFO : Softimage OM SIObject::Name property returns: MyArc
        //'INFO : C++ API SIObject::GetName returns: MyArc
CComAPIHandler ( const CComAPIHandler in_obj)

Copy constructor.

Parameters:
in_objconstant class object.

Member Function Documentation

CComAPIHandler& operator= ( const CComAPIHandler in_obj)

Assignment operator

Parameters:
in_objCComAPIHandler to copy.
CStatus CreateInstance ( const CString in_name)

Creates an automation object and attaches it to the CComAPIHandler object. If you try to create an automation object that doesn't exist an error (CStatus::Fail) occurs.

Parameters:
in_nameProgID of the Softimage OM object to create. The ProgID is a string found in the Registry, that maps to the CLSID of the object. For example XSI.UIToolkit and Scripting.FileSystemObject.
Returns:
CStatus::OK success
CStatus::Fail other failure
CStatus Attach ( const CValue in_val)

Attaches an automation object or Softimage object to the CComAPIHandler object. The CValue can be set either with a CRef object or with a pointer to an object model interface. CComAPIHandler takes care of handling the reference counting on the underlying Softimate OM object.

Parameters:
in_valCValue to attach
Returns:
CStatus::OK Success
CStatus::InvalidArgument Invalid referance object
CStatus::Fail Other failure
CStatus Detach ( void  )

Detaches an automation object pointer from the CComAPIHandler object.

Returns:
CStatus::OK Success
CStatus::Fail Other failure
CValue GetProperty ( const CString in_name) const

Returns the property value.

Parameters:
in_nameThe name of the property.
Returns:
The property value.
CStatus PutProperty ( const CString in_name,
const CValue in_newval 
) const

Sets the property value. If you try to set a read-only property, an error (CStatus::AccessDenied) occurs. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the property.
in_newvalThe new property value.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Property does not exist.
CStatus Call ( const CString in_name,
CValue io_return,
const CValueArray in_args = CValueArray() 
) const

Calls the object method specified by name. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the method.
io_returnThe return value.
in_argsArray of arguments passed through to the method to call,
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method does not exist.
CStatus Call ( const CString in_name,
CValue io_return,
const CValue in_arg 
) const

Calls the object method specified by name. This version is convenient for calling a method that takes one argument. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the property.
io_returnThe return value.
in_argThe argument passed through to the method.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method does not exist.
CStatus Call ( const CString in_name,
CValue io_return,
const CValue in_arg,
const CValue in_arg1 
) const

Calls the object method specified by name. This version is convenient for calling a method that takes two arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the property.
io_returnThe return value.
in_argThe first argument passed through to the method.
in_arg1The second argument passed through to the method.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method does not exist.
CStatus Call ( const CString in_name,
CValue io_return,
const CValue in_arg,
const CValue in_arg1,
const CValue in_arg2 
) const

Calls the object method specified by name. This version is convenient for calling a method that takes three arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the property.
io_returnThe return value.
in_argThe first argument passed through to the method.
in_arg1The second argument passed through to the method.
in_arg2The third argument passed through to the method.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method does not exist.
CStatus Call ( const CString in_name,
CValue io_return,
const CValue in_arg,
const CValue in_arg1,
const CValue in_arg2,
const CValue in_arg3 
) const

Calls the object method specified by name. This version is convenient for calling a method that takes four arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:
in_nameThe name of the property.
io_returnThe return value.
in_argThe first argument passed through to the method.
in_arg1The second argument passed through to the method.
in_arg2The third argument passed through to the method.
in_arg3The fourth argument passed through to the method.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method does not exist.
CStatus Invoke ( const CString in_name,
LONG  in_flags,
CValue io_return,
const CValueArray in_args = CValueArray() 
) const

Calls the object method or property specified by name, in the context specified by in_flags. If you try to call a method or property that doesn't exist an error (CStatus::MemberNotFound) occurs.

Note:
A common use of this function is to get a property that uses input parameters; for example, the 'Item' property on a collection that needs to specify the index or name of the item to retrieve from the collection.
Example:
This example demonstrates how to use the CComAPIHandler to browse the list of selected components (since the SubComponent class is not fully implemented in the C++ API).
        // Make sure something is selected
        Selection sel = app.GetSelection();
        LONG lCount = sel.GetCount();
        app.LogMessage(L"Found " + CString(lCount) + L" selected items.");
        if ( lCount < LONG(1) )
        {
            app.LogMessage( L"No components are selected" );
            return CStatus::OK;
        }
        for ( LONG i=0; i<lCount; i++ )
        {
            if ( sel.GetItem(i).GetClassIDName() == L"X3DObject" )
            {
                X3DObject x3dobj(sel.GetItem(i));
                app.LogMessage(L"\titem[" + CString(i) + L"]: " + x3dobj.GetName() );
            }
            else
            {
                app.LogMessage(L"\titem[" + CString(i) + L"]: " + sel.GetItem(i).GetClassIDName() );
            }
        }

        // The collection of selected components exists in the first member
        CComAPIHandler comCollItem( sel.GetItem(0) );
        CComAPIHandler comSubComp( comCollItem.GetProperty(L"SubComponent") );
        CValue subCompType = comSubComp.GetProperty( L"Type" );
        app.LogMessage( L"Type of subcomponent: " + CString(subCompType) );

        // Grab the component collection
        CComAPIHandler comCompColl( comSubComp.GetProperty(L"ComponentCollection") );

        // Now we can iterate over the component collection's members
        LONG lCollCount( comCompColl.GetProperty(L"Count") );
        app.LogMessage(L"Found " + CString(lCollCount) + L" selected components.");
        for ( LONG j=0; j<lCollCount; j++ )
        {
            CValue rtn;                             // output from the Item property
            CValueArray idx; idx.Add(j);            // set the index to use
            comCompColl.Invoke( L"Item", CComAPIHandler::PropertyGet, rtn, idx );

            // From the CRef class, we can convert it to the actual class
            CRef itm(rtn);
            if ( itm.GetClassID() == siVertexID )
            {
                Vertex vtx = Vertex(itm);
                app.LogMessage( L"Found a vertex at index " + CString(vtx.GetIndex()) );
            }
            if ( itm.GetClassID() == siSampleID )
            {
                Sample smp = Sample(itm);
                app.LogMessage( L"Found a sample at index " + CString(smp.GetIndex()) );
            }
            if ( itm.GetClassID() == siEdgeID )
            {
                Edge edg = Edge(itm);
                app.LogMessage( L"Found a edge at index " + CString(edg.GetIndex()) );
            }
            if ( itm.GetClassID() == siControlPointID )
            {
                ControlPoint ctrl = ControlPoint(itm);
                app.LogMessage( L"Found a control point at index " + CString(ctrl.GetIndex()) );
            }
            // etc.
        }
Parameters:
in_nameThe name of the property or method to invoke
in_flagsSpecify the context (whether it's calling a method, setting or getting a property). See CComAPIHandler::InvokeFlag.
io_returnThe return value.
in_argsArray of arguments for the method to call.
Returns:
CStatus::OK Success
CStatus::Fail Other failure
CStatus::AccessDenied Trying to set a read-only parameter.
CStatus::MemberNotFound Method or property does not exist.
CValue GetRef ( void  ) const

Returns a reference to the automation object attached to the CComAPIHandler.

Returns:
A reference to an automation object.

The documentation for this class was generated from the following file: