Stock COM Wrapper Methods

This section describes the stock methods in the COM wrapper objects created by the Export Bridge Assistant:

• Abort
• CreateObject
• CreateObjectEx
• DestroyObject
• ExecuteString
• GetIDLObjectClassName
• GetIDLObjectVariableName
• GetIDLVariable
• GetLastError
• GetProcessName
• SetIDLVariable
• SetProcessName

Every connector object and custom COM wrapper object has these methods in addition to those defined by the wrapped IDL object.

Abort

The Abort method requests that the IDL process containing the underlying IDL object abort its current activity. This method is useful if a given IDL method call is busy for a very long time (e.g., a very long image processing command).

Note: The request is only that, a request, and IDL might take a long time before it actually stops or might completely finish its current activity. Such a wait is an effect of the IDL interpreter.

The client can only abort the current IDL activity if that wrapper object is the current owner of the underlying IDL process.

Syntax

HRESULT Abort(void)

Parameters

None

CreateObject

The CreateObject method creates the actual underlying IDL object. The argc, argv, and argpal parameters are used to supply parameters to the underlying IDL object’s Init method. If the Init method does not have any parameters, the caller sets argc, argv, and argpal to 0, NULL, and NULL, respectively.

This method creates IDL objects that use a default licensing algorithm (see IDL Licensing Modes for details). To use a specific IDL licensing mode, use the CreateObjectEx method.

Syntax

HRESULT CreateObject ([in] int argc, [in] VARIANT argv, [in] VARIANT argpal)

Parameters

argc

An integer that specifies the number of elements in the argv and argpal arrays.

argv

A VARIANT containing a COM SafeArray of VARIANT types, one for each parameter to Init. The elements in the array are given in order of the parameters listed in Init, ordered from left to right.

argpal

A VARIANT containing a COM SafeArray of 32-bit integer flag values, which can be a combination of the IDLBML_PARMFLAG_CONST and IDLBML_PARMFLAG_CONVMAJORITY values ORed together. The latter value is only used when an argv element is an array itself. For parameters that are not arrays, the argpal[n] value must be 0.

The following constant values defined in the typlib information of a wrapped IDL object can be used:

IDLBML_PARMFLAG_CONST	Use for parameters that are constant (In-Only, meaning that their values cannot be changed).
IDLBML_PARMFLAG_CONVMAJORITY	Include if the property value is an array. For more information, see Converting Array Majority.

Example

Note: See COM Object Creation for examples of creating objects from a variety of COM programming languages.

The Init method of the IDL object being wrapped has the following signature:

PRO IDLexFoo::INIT, rect, filename

where rect is an array of 4 integers and filename is a string.

The COM client code that creates an instance of the wrapper object, and calls the CreateObject() method with the rect and filename parameters, would look like the following:

CComSafeArray<int> csa(4);

csa[0] = 0; csa[1] = 0; csa[2] = 5; csa[3] = 10;

 

CComVariant argv[2];

int argp[2];

 

argv[0] = csa.Detach();

argp[0] = IDLBML_PARMFLAG_CONST;

argv[1] = "someFilename.txt";

argp[1] = IDLBML_PARMFLAG_CONST;

 

CComPtr<IMyWrapper> spWrapper;

spWrapper.CoCreateInstance( uuidof(MyWrapper));

 

spWrapper->CreateObject(2, argv, argp);

CreateObjectEx

The CreateObjectEx method creates the actual underlying IDL object; it differs from the CreateObject method in that it allows the specification of flag values that control the way the IDL process is initialized. The argc, argv, and argpal parameters are used to supply parameters to the underlying IDL object’s Init method. If the Init method does not have any parameters, the caller sets argc, argv, and argpal to 0, NULL, and NULL, respectively. The flags parameter specifies one or more initialization flags governing the way the IDL process is initialized; currently, the available flags control the method used to license the IDL session. (See IDL Licensing Modes for details on the default licensing mechanism.)

Syntax

HRESULT CreateObjectEx ([in] int argc, [in] VARIANT argv, [in] VARIANT argpal, [in] long flags))

Parameters

argc

An integer that specifies the number of elements in the argv and argpal arrays.

argv

A VARIANT containing a COM SafeArray of VARIANT types, one for each parameter to Init. The elements in the array are given in order of the parameters listed in Init, ordered from left to right.

argpal

A VARIANT containing a COM SafeArray of 32-bit integer flag values, which can be a combination of the IDLBML_PARMFLAG_CONST and IDLBML_PARMFLAG_CONVMAJORITY values ORed together. The latter value is only used when an argv element is an array itself. For parameters that are not arrays, the argpal[n] value must be 0.

The following constant values defined in the typlib information of a wrapped IDL object can be used:

IDLBML_PARMFLAG_CONST	Use for parameters that are constant (In-Only, meaning that their values cannot be changed). Include if the property value is an array.
IDLBML_PARMFLAG_CONVMAJORITY	For more information, see Converting Array Majority.

flags

Flag values that control the way the IDL process is initialized. The following constant values defined in the typlib information of a wrapped IDL object can be used:

IDLBML_LIC_FULL	The application requires that a licensed copy of IDL be installed on the local machine. If IDL is installed but no license is available, the application will run in IDL Demo (7-minute) mode.
IDLBML_LIC_RUNTIME	The application looks for a runtime IDL license. If no runtime license is available, the application will run in Virtual Machine mode.

Example

Note: See COM Object Creation for examples of creating objects from a variety of COM programming languages.

The Init method of the IDL object being wrapped has the following signature:

PRO IDLexFoo::INIT, rect, filename

where rect is an array of 4 integers and filename is a string.

The COM client code that creates an instance of the wrapper object and calls the CreateObjectEx() method with the rect and filename parameters, and which explicitly specifies that it should run in IDL Virtual Machine mode, would look like the following:

CComSafeArray<int> csa(4);

csa[0] = 0;

csa[1] = 0;

csa[2] = 5;

csa[3] = 10;

 

CComVariant argv[2];

 

int argp[2];

 

argv[0] = csa.Detach();

argp[0] = IDLBML_PARMFLAG_CONST;

argv[1] = "someFilename.txt";

argp[1] = IDLBML_PARMFLAG_CONST;

 

CComPtr<IMyWrapper> spWrapper;

 

spWrapper.CoCreateInstance( uuidof(MyWrapper));

spWrapper.CreateObjectEx(2, argv, argp, IDLBML_LIC_VM);

DestroyObject

The DestroyObject method destroys the underlying IDL object. If the object being destroyed is the last object within an OPS process, the OPS process is also destroyed.

Note: Trying to re-create an object after it has been destroyed is not supported. You must re-define the variable and then re-create the object.

Syntax

HRESULT DestroyObject(void)

Parameters

None

ExecuteString

The ExecuteString method executes the specified command in the IDL process containing the underlying IDL object.

Note: This method is disabled for applications running in the IDL Virtual Machine.

Syntax

HRESULT ExecuteString([in] BSTR bstrCmd)

Parameters

bstrCmd

A string containing the IDL command to be executed.

Examples

See IDL Command Line with a COM Connector Object for an example that executes any IDL command entered into one textbox and writes IDL output or error information to a second textbox.

GetIDLObjectClassName

The GetIDLObjectClassName method returns the IDL class name of the underlying IDL object.

Syntax

HRESULT GetIDLObjectClassName([out,retval] BSTR* Name)

Return Value

A string containing the class name of the IDL object.

GetIDLObjectVariableName

When the underlying IDL object was created in the IDL process, it was assigned a variable name. The GetIDLObjectVariableName method returns that name.

Syntax

HRESULT GetIDLObjectVariableName([out,retval] BSTR* Name)

Return Value

A string containing the variable name of the IDL object.

GetIDLVariable

The GetIDLVariable method retrieves a named variable from the IDL process containing the underlying IDL object.

Note: This method is disabled for applications running in the IDL Virtual Machine.

Syntax

HRESULT GetIDLVariable([in] BSTR bstrVar, [out,retval] VARIANT* Value)

Parameters

bstrVar

A string containing the name of the variable to retrieve from the IDL process.

Return Value

The variable’s values. If the variable is an array, the array is always converted from IDL majority to the standard COM SAFEARRAY majority ordering.

Examples

See Data Manipulation with a COM Connector Object for an array manipulation example that uses the GetIDLVariable, SetIDLVariable and ExecuteString methods.

GetLastError

The GetLastError method gets the error string for the last error that has occurred. It is called after a method call returns an error. The returned error string is usually the actual IDL error message, if IDL generated the error message.

Syntax

HRESULT GetLastError([out,retval] BSTR* LastError)

Return Value

The error string for the last error that occurred.

GetProcessName

The GetProcessName method returns the name of the process that contains the underlying IDL object.

Syntax

HRESULT GetProcessName([out,retval] BSTR* Name)

Return Value

A string containing the name of the process that contains the IDL object.

SetIDLVariable

The SetIDLVariable method sets the specified variable name to the specified value in the IDL process containing the underlying IDL object. If the value is a SAFEARRAY, it is always converted from the standard COM SAFEARRAY majority ordering to IDL majority.

Note: This method is disabled for applications running in the IDL Virtual Machine.

Syntax

HRESULT SetIDLVariable([in] BSTR bstrVar, [in] VARIANT Value)

Parameters

bstrVar

A string identifying the variable in the IDL process to be set to Value.

Value

The value for the variable.

Examples

See Data Manipulation with a COM Connector Object for an array manipulation example that uses the GetIDLVariable, SetIDLVariable and ExecuteString methods.

SetProcessName

The SetProcessName method sets the name of the process that will contain the IDL object. This can only be called before making the CreateObject call. Once the object is created, the process name cannot be reset and calling this method after CreateObject has no effect.

Syntax

HRESULT SetProcessName([in] BSTR Name)

Parameters

Name

A string containing the name of the process that will contain the IDL object.