5
Navigator and Map Integration

This chapter covers the integration with the Navigator and Map. Topics include:

• Integration of Services
• Registering Service Types
• Integrating Application's APIs

Integration of Services

Discovery takes place when the Console boots up, and can occur at other times. The discovery mechanism is determined by the integrating application. Once in the Discovery Cache, a type is available for use in the Navigator, Map, Job, and Event interface. Anywhere there is a list of types, a new type will appear along with a list of services of the new type with the appropriate icons.

The most direct consequence of defining an external service type is integration into the Navigator and Map within the console user interface. The implementation provides the necessary bitmaps and icons for display of the services. Just as for internally-defined services, objects of external service types can be dragged and dropped onto the map. When the QuickEdit command is invoked from either the Navigator or the Map, an executable is called to launch a property sheet for the administration of the selected object. If the Related Tools command is selected from the Navigator, the user can choose to launch any applications which have been declared for the administration of the service types. Those applications will be passed details about the selected service, including name, type, and credential information. For more information, see Chapter 3, "General Coding Techniques".

In addition, you can schedule jobs to services of types that you have defined. During service discovery, the implementation specifies not only the name of your service, but also the name of the node on which the service appears. Fundamentally, the running of a job is the execution of Tcl script by an Oracle Intelligent Agent on a particular node. For example, a database job only differs from a node job by description of their effects. If the nodes that you associate with your services have agents installed upon them, you can schedule jobs to those services. For additional information, see Chapter 6, "Discovery Cache Integration".

The OLE service within which you define your service types is created via a call to the COleDispatchDriver::CreateDispatch API based on the CLSID that you provide in the NT registry. The OLE service gets re-created for each call to any of its interfaces.

One OLE application service can support multiple, externally-defined service types using the same set of APIs. Because of this, all the API's take Type as the first parameter. Externally-defined services get stored in the discovery cache the same as internally-defined types. They stay discovered until the services are explicitly deleted from the Console.

Notes on External Services

When defining an external service in the Navigator tree, the following limitations apply to this release:

• The service objects can only be displayed in the top-level container defined for the service types.
• The object cannot appear in or have subtrees.

Registering Service Types

For each service type you want to add, enter a unique subkey into the NT registry under HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects. You must provide values for the internal and external name keys, and CLSID. See the smpxsrvc.reg file for a complete example of a registration file.

Internal Type

This is the name of the type as it is represented internally within the discovery cache. It also serves as the string which represents the type for all of the APIs within the SDK. This internal type name must be unique. Compare it to other types under HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects and to those defined in the voxtype.h header to ensure that this is the case. Oracle recommends that you use the company name as a prefix. You supply the internal type name as a value for the subkey which represents your type. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects\Apple = APPLE

External (NLS) Type

This is the name string that Enterprise Manager uses in its user interface to list the type among others. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects\Apple\Name = Apples

HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects\Apple\Name\US = Apples

See Integrating an Application into the Console on page 2-2 for information on registering an application in the NT registry. See Chapter 2, "Tool Palette and Menu Integration" for the method of defaulting and translation of this string.

CLSID

This provides the Enterprise Manager Console with the CLSID of the OLE service that defines the type. For example:

HKEY_CLASSES_ROOT\OracleSmpConsole\Navigator\Objects\Apple\CLSID =

{46CD44FC-C541-11CF-8F38-0020AFF2B3FF}

Integrating Application's APIs

An application should expose the following APIs:

• Discover
• GetIconList
• GetDefaultDisplayInfo
• QuickEdit

Common Parameters

This parameter is used by multiple Integrating APIs and is described in this section.

Type

The internal name for that type as it appears in the registry. See Optional Registration Keys on page 2-5.

Discover

Purpose

The Console calls this when it needs to discover the list of services, which will be stored in the Discovery Cache. For services that can be discovered by the agent, see Discovering Services on page 6-4.

Syntax

VTS_BOOL Discover(VTS_BSTR Type, VTS_PVARIANT pServices)

Parameters

Name	Type	Mode
Type	VTS_BSTR	IN
pServices	VTS_PVARIANT	OUT

  See Common Parameters on page 5-4.

pServices

A list of the names of the services of a specified type. pServices is an array of the form:

{ { Name1, Node1 }

  { Name2, Node2 }

  ...

  { Namex, Nodex } }

where Namex is the service name. Nodex is the name of the node the service is located on. This is used for job submission and event registration.

Comments

One OLE service can discover multiple types over multiple calls.

GetIconList

Purpose

Used by the Console to get the icons it needs to use in the Navigator and map when displaying your services. This function is obsolete in Enterprise Manager release 1.3.5 and later releases. See GetDefaultDisplayInfo on page 5-6.

Syntax

VT_BOOL GetIconList(VTS_BSTR Type, VTS_PVARIANT pIconOffsets)

Parameters

Name	Type	Mode
Type	VTS_BSTR	IN
pIconOffsets	VTS_PVARIANT	OUT

  See Common Parameters on page 5-4.

pIconOffsets

An array of offsets that reference which icons to use for the specified type. pIconOffsets contains exactly four VTS_I4 which represent, in order:

1. Offset of the tree icon (13x13)
2. Offset of the tree group icon (13x13) [not yet used]
3. Offset of the map icon (32x32)
4. Offset of the map group icon (32x32)

You must always pass a 32x32 icon, but for tree bitmaps, the Console only uses the upper left hand 13x13 portion of the icon. The unused area for small bitmaps (13x13) is ignored. A large icon is 32x32.

Comments

These offsets correspond to the order in which the icons are listed in the .exe file. These are the same as the offsets you would use in a call to the Windows SDK ::ExtractIcon API.

GetDefaultDisplayInfo

Purpose

Used by the Console to get the icons it needs to use in the Navigator and map when displaying your services.

Syntax

VT_BOOL GetDefaultDisplayInfo(VTS_BSTR Type, 

                VTS_PBSTR pbstrDisplayName

                VTS_PBSTR pbstrIcon)

Parameters

Name	Type	Mode
Type	VTS_BSTR	IN
pbstrDisplayName	VTS_PBSTR	OUT
pbstrIcon	VTS_PBSTR	OUT

  See Common Parameters on page 5-4.

pbstrDisplayName

This is the NLS display name for this type.

pbstrIcon

This is the string listing of the icons to use for this type. Four numeric values are expected. These values correspond to the resource Ids (in the .h resource file) for the icons. The offset are, in order:

1. Offset of the tree icon (13x13)
2. Offset of the tree group icon (13x13) [not yet used]
3. Offset of the map icon (32x32)
4. Offset of the map group icon (32x32)

Comments

This function returns TRUE if the Type was handled successfully.

QuickEdit

Purpose

This is called to launch a property sheet to administer an object ObjectName of type Type. It is called when the Quick Edit menu item is selected for an object of the selected type in the Navigator. This property sheet should remain under the OLE server's control until the user explicitly closes it.

Syntax

VT_BOOL QuickEdit(VTS_BSTR Type, VTS_BSTR ObjectName)

Parameters

Name	Type	Mode
Type	VTS_BSTR	IN
ObjectName	VTS_BSTR	IN

  See Common Parameters on page 5-4.

ObjectName

The name of the service object.

Comments

It is expected that your OLE service will launch a property sheet in response to QuickEdit which looks and works similarly to all of those which get launched from the Enterprise Manager Console Navigator. This dialog should be mode-less but should dismiss after use. There may be multiple QuickEdit property sheets invoked for objects of your type at once, but there should be at most one for each object of your type.

---