This method allows the client to define a variable name that represents an object within the script context. This name can later be used from within a script code that is passed to the Run() method. In essence, this is like declaring a new variable that the TerraExplorer script engine can now work with. For example, a client may decide to register the name “DBConnection” that represents a connection to a database and later use this variable from within a script to access the database.
There are, however, a few restrictions:
The name “this” is a reserved keyword and an attempt to register it returns an error. The “this” keyword is used to represent the ITerraExplorer object.
The name being registered must be a COM object that is derived from IUnknown.
The scope of the registered name is only within the client that is registering it. This name is not available to other clients. To register a name that can also be used by other clients, use the RegisterGlobalName() method.
When a name is registered with TerraExplorer, its reference count is increased by 1. To unregister a name, call the UnregisterName() method. This also decreases the object reference count by 1. If the client does not call UnregisterName by the time the client realeases the TerraExplorer object, TerraExplorer does this automatically for it.
HRESULT RegisterName(
[in] BSTR Name,
[in] IUnknown* punkItem,
[in, defaultvalue(0)] long Flags)
Parameters:
Name – The name of the new object being registered. This name can now be used as a variable from within a script code sent to the Run() method.
punkItem – An IUnknown interface pointer to the object being registered.
Flags – Currently not used.
Return Values:
The return value obtained from the returned HRESULT can be one of the following:
|
Return value |
Meaning |
|
S_OK |
Success. |
|
E_FAIL |
Catastrophic failure. |
|
E_INVALIDARG |
Invalid argument. This is usually one of the following: "Reserved Name" "Name already registered" "NULL IUnknown" |