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)
CComAPIHandler & | operator= (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

CComAPIHandler | ( |  | ) |

Default constructor.

virtual ~CComAPIHandler | ( |  | ) | `[virtual]`

Default destructor.

CComAPIHandler | ( | const CValue & | in_val | ) |

Constructor.

Parameters:

  in_val | Contains 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_obj | constant class object.

## Member Function Documentation

CComAPIHandler& operator= | ( | const CComAPIHandler & | in_obj | ) |

Assignment operator

Parameters:

  in_obj | CComAPIHandler 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_name | `ProgID` 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_val | CValue 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_name | The 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_name | The name of the property.
  in_newval | The 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_name | The name of the method.
  io_return | The return value.
  in_args | Array 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_name | The name of the property.
  io_return | The return value.
  in_arg | The 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_name | The name of the property.
  io_return | The return value.
  in_arg | The first argument passed through to the method.
  in_arg1 | The 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_name | The name of the property.
  io_return | The return value.
  in_arg | The first argument passed through to the method.
  in_arg1 | The second argument passed through to the method.
  in_arg2 | The 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_name | The name of the property.
  io_return | The return value.
  in_arg | The first argument passed through to the method.
  in_arg1 | The second argument passed through to the method.
  in_arg2 | The third argument passed through to the method.
  in_arg3 | The 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_name | The name of the property or method to invoke
  in_flags | Specify the context (whether it's calling a method, setting or getting a property). See CComAPIHandler::InvokeFlag.
  io_return | The return value.
  in_args | Array 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:

- xsi_comapihandler.h