Release 1.4.0
A53701_01
 Library |
 Product |
 Contents |
 Index |
| Oracle Enterprise Manager Application Developer's Guide Release 1.4.0 A53701_01 |
|
This chapter covers the integration with the Navigator and Map. Topics include:
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.
When defining an external service in the Navigator tree, the following limitations apply to this release:
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.
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.
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}
An application should expose the following APIs:
This parameter is used by multiple Integrating APIs and is described in this section.
The internal name for that type as it appears in the registry. See Optional Registration Keys on page 2-5.
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.
VTS_BOOL Discover(VTS_BSTR Type, VTS_PVARIANT pServices)
| Name | Type | Mode |
|---|---|---|
|
Type |
VTS_BSTR |
IN |
|
pServices |
VTS_PVARIANT |
OUT |
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.
One OLE service can discover multiple types over multiple calls.
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.
VT_BOOL GetIconList(VTS_BSTR Type, VTS_PVARIANT pIconOffsets)
| Name | Type | Mode |
|---|---|---|
|
Type |
VTS_BSTR |
IN |
|
pIconOffsets |
VTS_PVARIANT |
OUT |
An array of offsets that reference which icons to use for the specified type. pIconOffsets contains exactly four VTS_I4 which represent, in order:
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.
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.
Used by the Console to get the icons it needs to use in the Navigator and map when displaying your services.
VT_BOOL GetDefaultDisplayInfo(VTS_BSTR Type,
VTS_PBSTR pbstrDisplayName
VTS_PBSTR pbstrIcon)
| Name | Type | Mode |
|---|---|---|
|
Type |
VTS_BSTR |
IN |
|
pbstrDisplayName |
VTS_PBSTR |
OUT |
|
pbstrIcon |
VTS_PBSTR |
OUT |
This is the NLS display name for this type.
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:
This function returns TRUE if the Type was handled successfully.
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.
VT_BOOL QuickEdit(VTS_BSTR Type, VTS_BSTR ObjectName)
| Name | Type | Mode |
|---|---|---|
|
Type |
VTS_BSTR |
IN |
|
ObjectName |
VTS_BSTR |
IN |
The name of the service object.
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.
