This section describes the stock methods in the COM wrapper objects created by the Export Bridge Assistant:
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
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.