The Management Interface

The MI API is divided into four groups of functions. The Initialization function allows management applications to register with the SP and get configuration information. The second group of functions comprise the Listing functions, which are used as discovery methods to obtain and list information from the SP. Operation functions allow management applications to retrieve detailed property values from the SP. Database administrative functions make up the last group of functions.

See below for descriptions of the functions. Parameters and possible error codes are detailed in the DMI 2.0 spec.

Initialization Functions

DmiRegister

The DmiRegister procedure provides the management application with a unique per-session handle. The DMI SP uses this procedure to initialize its internal state for subsequent procedure calls made by the application. This must be the first DMI command executed by the application.

DmiUnregister

The DmiUnregister procedure must be the last DMI command executed by the management application. The DMI SP uses this procedure to perform its end-of-session cleanup actions. On return from this function, the session handle is no longer valid.

DmiGetVersion

The DmiGetVersion procedure retrieves information about the DMI SP. The management application uses this procedure to determine the DMI specification level supported by the service provider. This procedure also returns the service provider description string and may contain version information about the service provider implementation.

DmiGetConfig

The DmiGetConfig procedure retrieves the per-session configuration information. For the DMI 2.0 specification, this configuration information consists of a string describing the current language in use for the session.

DmiSetConfig

The DmiSetConfig procedure sets the per-session configuration information. For the DMI 2.0 specification, this configuration information consists of a string describing the language required by the management application.

Listing Functions

DmiListComponents

This call retrieves the name and (optionally) the description of components in a system. An enumeration can access a specific component or may be used to sequentially access all components in a system. The caller may choose not to retrieve the component description by setting the value getDescription to false. Likewise, the caller may choose not to retrieve the pragma string by setting the value of getPragma to false.

The maxCount, requestMode and compId parameters let the caller control the information returned by the DMI SP. When the requestMode is DMI_UNIQUE, compId specifies the first component requested (or only component if maxCount is one). When the requestMode is DMI_NEXT, compId specifies the component just before the one requested. When requestMode is DMI_FIRST, compId is unused.

To control the amount of information returned, the caller sets maxCount to something other than zero. The service provider must honor this limit on the amount of information returned. When maxCount is zero, the service provider returns information for all components, subject to the constraints imposed by requestMode and compId.

DmiListComponentsByClass

By listing components matching specified criteria, this command can determine if a component contains a certain group or a certain row in a table. A filter condition may be that a component contains a specified group class name or that it contains a specific row in a specific group. As with DmiListComponents, the description and pragma strings are optional return values.

Also, see DmiListComponentsSee for an explanation of how requestMode, maxCount and compId interact to select the information returned.

DmiListLanguages

The DmiListLanguages procedure retrieves the set of language mappings installed for the specified component. The maxCount parameter limits the number of strings returned to the caller.

DmiListClassNames

By retrieving the class name strings for all groups in a component,. the DmiListClassNames procedure lets the management application easily determine if a component contains a specific group or groups. The maxCount parameter limits the number of class name strings returned to the caller.

DmiListGroups

This call retrieves a list of groups within a component; it can access a specific group or may be used to sequentially access all groups in a component. Note that all enumerations of groups occur within the specified component and do not span components.

The caller may choose not to retrieve the group description by setting the value getDescription to false. Likewise, the caller may choose not to retrieve the pragma string by setting the value of getPragmaSee to false.

The maxCount, requestMode and groupId parameters allow the caller to control the information returned by the DMI SP. When the requestMode is DMI_UNIQUE, groupId specifies the first group requested (or the only group if maxCount is one). When the requestMode is DMI_NEXT, groupId specifies the group just before the one requested. When requestMode is DMI_FIRST, groupIdSee is unused.

To control the amount of information returned, the caller sets maxCount to a measurement other than zero. The service provider must honor this limit on the amount of information returned. When maxCount is zero, the service provider returns information for all groups, subject to the constraints imposed by requestMode and groupId.

DmiListAttributes

This DmiListAttributes procedure retrieves the properties for one or more attributes in a group. Note that all enumerations of attributes occur within the specified group, and do not span groups.

The caller may choose not to retrieve the description string by setting the value of getDescription to false. Likewise, the caller may choose not to retrieve the pragma string by setting the value of getPragma to false.

The maxCount, requestMode, and attribId parameters allow the caller to control the information returned by the DMI SP. When the requestMode is DMI_UNIQUE, attribId specifies the first attribute requested (or the only attribute if maxCount is one). When the requestMode is DMI_NEXT, attribId specifies the attribute just before the one requested. When requestMode is DMI_FIRST, attribId is unused.

To control the amount of information returned, the caller sets maxCount to a measurement other than zero. The service provider must honor this limit on the amount of information returned. When maxCount is zero, the service provider returns information for all attributes, subject to the constraints imposed by requestMode and attribId.

Operation Functions

DmiGetAttribute

The DmiGetAttribute procedure provides a simple method for retrieving a single attribute value from the DMI SP. The compId, groupId, attribId and keyList identify the desired attribute. The resulting attribute value is returned in a newly allocated DmiDataUnion structure. The address of this structure is returned through the value parameter.

DmiSetAttribute

The DmiSetAttribute procedure provides a simple method for setting a single attribute value. The compId, groupId, attribId and keyList identify the desired attribute; the setMode parameter defines the procedure call as a Set, Reserve, or Release operation. The new attribute value is contained in the DmiDataUnion structure whose address is passed in the value parameter.

DmiGetMultiple

The DmiGetMultiple procedure retrieves attribute values from the DMI SP. This command may get the value for an individual attribute, or for multiple attributes across groups, components or rows of a table.

DmiSetMultiple

This command performs a set operation on an attribute or list of attributes. Set operations include actually setting the value, testing and reserving the attribute for future setting, or releasing the set reserve. These variations on the set operation are specified by the parameter setMode.

The rowData array describes the attributes to set and contains the new attribute values. Each element of rowData specifies a component, group, key list (for table accesses) and attribute list to set. No data is returned from this function.

DmiAddRow

The DmiAddRow procedure adds a row to an existing table. The rowData parameter contains the full data, including key attribute values, for a row. It is an error for the key list to specify an existing table row.

DmiDeleteRow

The DmiDeleteRow procedure removes a row from an existing table. The key list must specify valid keys for a table row.

Database Administration Functions

DmiAddComponent

The DmiAddComponent procedure can add a new component to the DMI database. It takes the name of a file, or the address of memory block containing schema description data, checks the data for adherence to the appropriate schema description format (e.g. DMI MIF format) and installs the schema description in the database. The procedure returns a unique component ID for the newly installed component.

DmiAddLanguage

The DmiAddLanguage procedure can add a new language mapping for an existing component in the database. It takes the name of a file, or the address of memory block containing translated schema description data, checks the data for adherence to the schema description grammar (e.g. DMI MIF grammar) and installs the translated schema description in the database.

DmiAddGroup

The DmiAddGroup procedure can add a new group to an existing component in the database. It takes the name of a file, or the address of memory block containing the group's schema description data, checks the data for adherence to the schema description grammar (e.g. DMI MIF grammar), and installs the group schema description in the database.

DmiDeleteComponent

The DmiDeleteComponent procedure can remove an existing component from the database.

DmiDeleteLanguage

The DmiDeleteLanguage procedure can remove a specific language mapping for a component. The caller specifies the language string and component ID.

DmiDeleteGroup

The DmiDeleteGroup procedure can remove a group from a component. The caller specifies the component and group IDs.

Component Interface

Component instrumentation code may register with the service provider to override its current access mechanism for the registered attributes. Instead of manipulating the data in the MIF database or invoking programs, the service provider will call the entry points provided in the registration call. Once the component unregisters, the SP will return to its "normal method" of processing requests for the data as defined in the MIF. In this way, component instrumentation can temporarily interrupt normal processing to perform some special function. Note that registering attributes through the direct interface will override attributes that are already being served through the direct interface.

DmiRegisterCi Function

The DmiRegisterCi() call can register a callable interface for components that have resident instrumentation code and/or to get the version of the service provider.

DmiUnregisterCi Function

DmiUnregisterCi() tells the service provider to remove a direct component instrumentation interface from the service provider's table of registered interfaces. This procedural DmiUnregisterCI() call is simplified over the DMIv1.x model for unregistering component instrumentation, requiring a single parameter: the service provider assigned handle given to instrumentation at registration time.

DmiOriginateEvent

This function call originates an event for filtering and delivery. Any necessary indication filtering is performed by this function (or by subsequent processing) before the event is forwarded to the management applications. Implementation note: A compID value of zero (0) specifies that the event was generated by something that has not been installed as a component, and hence has no component ID.