Pegasus Enhancement Proposal (PEP)
PEP #: 260
PEP Type: Functional
Title: CMPI 2.0 Currency
Version: 1.1
Created: 15 May 2006
Author: Mark Hamzy / Dave Sudlik
Status: Approved
Version History:
Version | Date | Author | Change Description |
---|---|---|---|
0.1 | 15 May 2006 | Dave Sudlik |
Preliminary Draft |
1.0 | 11 Aug 2006 |
Dave Sudlik | First Draft, based on 2.0 spec going out for company
review Approved version for development. |
1.1 |
07 Nov 2006 |
Dave Sudlik |
Final draft, minor updates based
on spec changes after implementation (see bug 5817). Final approved version. |
Abstract:
Version 2.0 of the CMPI Standard is expected to be
approved by the end of September 2006. This PEP proposes changes to
OpenPegasus to support the new version of the CMPI standard.
OpenPegasus needs to support the latest version of the CMPI
standard. The areas addressed by the newest CMPI standard are:
The subsections below define the areas of enhancement in CMPI 2.0
(see section 1.4 of the spec). No incompatibilities between version 1.0
and 2.0 have been observed, but the CMPI_VERSION feature test macro
allows an MI implementation (ie. provider) to define the minimal
version support needed from the Management Broker (ie. CMPI run-time).
Valid values are:
The situation is the same for cmpimacs.h
as it is for the other CMPI header files. Differences between it and
the now standardized version are minimal, mostly formatting. It will be
merged into OpenPegasus in a similar manner.
These enhanced messaging APIs will be
based on the OpenPegasus MessageLoader class. There are a number of
changes here. Currently, CMPI getMessage() is converted into a call to
MessageLoader::getMessage() which opens the ICU message file, extracts
the specified message, closes the message file, and returns the
formatted message (including optional message inserts). A deficiency in
the existing CMPI getMessage() support is that there is no way to
indicate the location of the message file to use. Today it uses the
Pegasus default location, which is suitable for the CIM Server but not
for providers. The interfaces for the new CMPI APIs, as they relate to
Pegasus, are described here.
CMPIStatus
CMPIBrokerEncFT.openMessageFile(
const CMPIBroker* mb,
const char* msgFile,
CMPIMsgFileHandle*
msgFileHandle
);
The CMPIBrokerEncFT.openMessageFile()
function will open a message file supported by Pegasus MessageLoader
translation services and return a unique identifier to that file. This
function will use the AcceptLanguage entry from the current context in
determining the message file to open, and also add the ContentLanguage
entry to the current context based on the actual message file that was
opened. All subsequent calls to the CMPIBrokerEncFT.getMessage2()
function using this msgFileHandle will be associated with this
ContentLanguage.
The msgFile argument contains the
implementation-specific file path to the message file. This will be
used to set the msg_src_path data member of MessageLoaderParms, which
tells MessageLoader where to find message resources. It can be
The msgFileHandle output argument
contains a unique identifier to the open message file that can be
passed to the CMPIBrokerEncFT.getMessage2() and
CMPIBrokerEncFT.closeMessageFile() functions. In Pegasus, this is just
a pointer to an instance of MessageLoaderParms the is allocated on the
heap. In this way, this same MessageLoaderParms instance will be used
on every call to getMessage2 (which will call
MessageLoader::getMessage2() under the covers, see below).
Note that for any error conditions
returned by CMPIBrokerEncFT.openMessageFile(), a subsequent call to
CMPIBrokerEncFT.getMessage2() using the CMPIMsgFileHandle that was
returned will result in the default message being used.
CMPIStatus
CMPIBrokerEncFT.closeMessageFile(
const CMPIBroker* mb,
const CMPIMsgFileHandle
msgFileHandle
);
The CMPIBrokerEncFT.closeMessageFile()
function will close a message file previously opened by
CMPIBrokerEncFT.openMessageFile(), as specified by the msgFileHandle
argument. The heap storage for the MessageLoaderParms instance will be
released.
Note:
If the provider returns control to the CIMOM without first closing the
message file, the storage for the MessageLoaderParms instance will
*not* be cleaned up. This gives a provider the option of using an open
message file across multiple invocations. However, this storage will be
automatically cleaned up when the provider is unloaded, if not done
explicitly by the provider.
CMPIString*
CMPIBrokerEncFT.getMessage2(
const CMPIBroker* mb,
const char* msgId,
const CMPIMsgFileHandle
msgFileHandle,
const char* defMsg,
CMPIStatus* rc,
CMPICount count,
...
);
These APIs are intended to be used by a
CMPI provider in the following way:
CMPIError support is optional.
Availability of this
support is indicated by the CMPI_MB_Supports_Extended_Error flag in CMPIBrokerFT.brokerCapabilities. CMPIError support will be implemented
in Pegasus 2.6 as part of this PEP, and in conjunction with the work to
be done in PEP 245 (CIM_Error).
typedef enum
_CMPIErrorType {
Unknown = 0,
Other = 1,
CommunicationsError = 2,
QualityOfServiceError = 3,
SoftwareError = 4,
HardwareError = 5,
EnvironmentalError = 6,
SecurityError = 7,
OversubscriptionError = 8,
UnavailableResourceError = 9,
UnsupportedOperationError = 10,
} CMPIErrorType;
typedef enum
_CMPIErrorSeverity {
Unknown = 0,
Low = 2,
Medium = 3,
High = 4,
Fatal = 5,
} CMPIErrorSeverity;
typedef enum
_CMPIErrorProbableCause {
Unknown = 0,
Other = 1,
Adapter_Card_Error
= 2,
Application_Subsystem_Failure = 3,
Bandwidth_Reduced
= 4,
Connection_Establishment_Error = 5,
Communications_Protocol_Error = 6,
Communications_Subsystem_Failure = 7,
Configuration/Customization_Error = 8,
Congestion = 9,
Corrupt_Data = 10,
CPU_Cycles_Limit_Exceeded = 11,
Dataset/Modem_Error = 12,
Degraded_Signal =
13,
DTE_DCE_Interface_Error = 14,
Enclosure_Door_Open = 15,
Equipment_Malfunction = 16,
Excessive_Vibration = 17,
File_Format_Error
= 18,
Fire_Detected = 19,
Flood_Detected =
20,
Framing_Error = 21,
HVAC_Problem = 22,
Humidity_Unacceptable = 23,
IO_Device_Error =
24,
Input_Device_Error
= 25,
LAN_Error = 26,
Non_Toxic_Leak_Detected = 27,
Local_Node_Transmission_Error = 28,
Loss_of_Frame = 29,
Loss_of_Signal =
30,
Material_Supply_Exhausted = 31,
Multiplexer_Problem = 32,
Out_of_Memory = 33,
Output_Device_Error = 34,
Performance_Degraded = 35,
Power_Problem = 36,
Pressure_Unacceptable = 37,
Processor_Problem
= 38,
Pump_Failure = 39,
Queue_Size_Exceeded = 40,
Receive_Failure =
41,
Receiver_Failure =
42,
Remote_Node_Transmission_Error = 43,
Resource_at_or_Nearing_Capacity = 44,
Response_Time_Excessive = 45,
Retransmission_Rate_Excessive = 46,
Software_Error =
47,
Software_Program_Abnormally_Terminated = 48,
Software_Program_Error = 49,
Storage_Capacity_Problem = 50,
Temperature_Unacceptable = 51,
Threshold_Crossed
= 52,
Timing_Problem =
53,
Toxic_Leak_Detected = 54,
Transmit_Failure =
55,
Transmitter_Failure = 56,
Underlying_Resource_Unavailable = 57,
Version_Mismatch =
58,
Previous_Alert_Cleared = 59,
Login_Attempts_Failed = 60,
Software_Virus_Detected = 61,
Hardware_Security_Breached = 62,
Denial_of_Service_Detected = 63,
Security_Credential_Mismatch = 64,
Unauthorized_Access = 65,
Alarm_Received =
66,
Loss_of_Pointer =
67,
Payload_Mismatch =
68,
Transmission_Error
= 69,
Excessive_Error_Rate = 70,
Trace_Problem = 71,
Element_Unavailable = 72,
Element_Missing =
73,
Loss_of_Multi_Frame = 74,
Broadcast_Channel_Failure = 75,
Invalid_Message_Received = 76,
Routing_Failure =
77,
Backplane_Failure
= 78,
Identifier_Duplication = 79,
Protection_Path_Failure = 80,
Sync_Loss_or_Mismatch = 81,
Terminal_Problem =
82,
Real_Time_Clock_Failure = 83,
Antenna_Failure =
84,
Battery_Charging_Failure = 85,
Disk_Failure = 86,
Frequency_Hopping_Failure = 87,
Loss_of_Redundancy
= 88,
Power_Supply_Failure = 89,
Signal_Quality_Problem = 90,
Battery_Discharging = 91,
Battery_Failure =
92,
Commercial_Power_Problem = 93,
Fan_Failure = 94,
Engine_Failure =
95,
Sensor_Failure =
96,
Fuse_Failure = 97,
Generator_Failure
= 98,
Low_Battery = 99,
Low_Fuel = 100,
Low_Water = 101,
Explosive_Gas =
102,
High_Winds = 103,
Ice_Buildup = 104,
Smoke = 105,
Memory_Mismatch =
106,
Out_of_CPU_Cycles
= 107,
Software_Environment_Problem = 108,
Software_Download_Failure = 109,
Element_Reinitialized = 110,
Timeout = 111,
Logging_Problems =
112,
Leak_Detected_113,
Protection_Mechanism_Failure = 114,
Protecting_Resource_Failure = 115,
Database_Inconsistency = 116,
Authentication_Failure = 117,
Breach_of_Confidentiality = 118,
Cable_Tamper = 119,
Delayed_Information = 120,
Duplicate_Information = 121,
Information_Missing = 122,
Information_Modification = 123,
Information_Out_of_Sequence = 124,
Key_Expired = 125,
Non_Repudiation_Failure = 126,
Out_of_Hours_Activity = 127,
Out_of_Service =
128,
Procedural_Error =
129,
Unexpected_Information = 130,
}
CMPIErrorProbableCause;
typedef
_CMPIErrorSrcFormat {
Unknown
= 0,
Other = 1,
CIMObjectHandle = 2,
}
CMPIErrorSrcFormat;
CMPIStatus CMPIResultFT.returnError(
const CMPIResult* rslt,
const CMPIError* er
);
The CMPIResultFT.returnError()
function shall accept a CMPIError object which will be returned
to the MB.
CMPIError*
CMPIBrokerEncFT.newCMPIError(
const CMPIBroker* mb,
const char* owner,
const char* msgID,
const char*
msg,
const CMPIErrorSeverity sev,
const CMPIErrorProbableCause pc,
const CMPIrc cimStatusCode,
CMPIStatus* rc
);
typedef struct
CMPIError {
void* hdl;
CMPIErrorFT ft;
} CMPIError;
CMPISint32 ftVersion;
CMPIStatus
(*release)(CMPIError*);
CMPIError*
(*clone)(const
CMPIError*,
CMPIStatus*);
/* get* functions
*/
CMPIErrorType (*getErrorType)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getOtherErrorType)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getOwningEntity)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getMessageID)(const CMPIError*,
CMPIStatus*);
CMPIString*
(*getMessage)(const CMPIError*,
CMPIStatus*);
CMPIErrorSeverity
(*getPerceivedSeverity)(const CMPIError*, CMPIStatus*);
CMPIErrorProbableCause
(*getProbableCause)(const CMPIError*, CMPIStatus*);
CMPIString*
(*getProbableCauseDescription)(const CMPIError*, CMPIStatus*);
CMPIArray*
(*getRecommendedActions)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getErrorSource)(const
CMPIError*, CMPIStatus*);
CMPIErrorSrcFormat (*getErrorSourceFormat)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getOtherErrorSourceFormat)(const CMPIError*, CMPIStatus*);
CMPIrc
(*getCIMStatusCode)(const
CMPIError*, CMPIStatus*);
CMPIString*
(*getCIMStatusCodeDescription)(const CMPIError*, CMPIStatus*);
CMPIArray*
(*getMessageArguments)(const
CMPIError*, CMPIStatus*);
/* set* functions
*/
CMPIStatus (*setErrorType)(CMPIError*,
const CMPIErrorType);
CMPIStatus
(*setOtherErrorType)(CMPIError*,
const char* );
CMPIStatus
(*setProbableCauseDescription)(CMPIError*, const char* );
CMPIStatus
(*setRecommendedActions)(CMPIError*, const CMPIArray*);
CMPIStatus
(*setErrorSource)(CMPIError*,
const char*);
CMPIStatus
(*setErrorSourceFormat)(const
CMPIError*, const CMPIErrorSrcFormat );
CMPIStatus
(*setOtherErrorSourceFormat)(CMPIError*, const char*);
CMPIStatus
(*setCIMStatusCodeDescription)(CMPIError*, const
char*);
CMPIStatus
(*setMessageArguments)(CMPIError*, CMPIArray*);
} CMPIErrorFT;
This set of memory functions are
optional and available only when the CMPI_MB_MemoryEnhancmentSupport
flag in
CMPIBrokerFT.brokerCapabilities is set. CMPIBrokerMemFT is routed in
CMPIBrokerFT.
These optional memory
functions will not be implemented in Pegasus 2.6.
For your reading pleasure...
The functions in CMPIBrokerMemFT are
memory
related, and are used to guide the garbage collector, allocation and
deallocation of
memory. These do not replace the 'clone' and 'release' functions
defined in the
various CMPI data structures, those should continue to be used as
previously
documented. These new functions allow providers to participate more
openly in
the garbage collection mechanism provided by the MB, and to keep
non-CMPI
related memory allocated via this mechanism. A MB does not need to
actually
provide anything except a pass through to the underlying OS call. All
MI's
should use these functions for memory management.
There are three sets of memory
related functions
and each can help in various situations. The 'mark' and 'release'
functions can
be used by long-running secondary threads. The 'cmpiMalloc',
'cmpiCalloc',
'cmpiRealloc' and 'cmpiStrDup' can be used to hook-up the providers
memory data
storage to the MB garbage collector. The 'freeXXX' functions can be
used to
instruct the garbage collector that the CMPI objects are no longer
needed and
can be collected.
Long-running secondary threads are a
common
situation in indication providers. They often stay for the life-time of
the MB
and often create new CMPIInstance objects. Unfortunately those CMPI
objects are
not being garbage collected because the thread has not finished
executing. The
'mark()' and 'release()' help in this fashion by setting a marker which
the
garbage collector can use to determine which of CMPI objects are
temporary.
When 'release()' is called, the garbage collector kicks in and reclaims
all of
the CMPI objects that have been created since the 'mark' call.
The garbage collector can also be
used to
support the user-defined data storage. By using the 'cmpiMalloc',
'cmpiCalloc',
'cmpiRealloc' and 'cmpiStrDup' the resulting data storage is included
in the
garbage collector and when it is invoked, those data storages become
automatically
reclaimed.
typedef struct CMPIBrokerMemFT {
const int ftVersion;
CMPIGcStat* (*mark)(const
CMPIBroker*, CMPIStatus*);
CMPIStatus (*release)(const CMPIBroker*, const CMPIGcStat*);
void* (*cmpiMalloc)(const CMPIBroker*, size_t);
void* (*cmpiCalloc)(const CMPIBroker*, size_t, size_t);
void* (*cmpiRealloc)(const CMPIBroker*, void*, size_t);
char* (*cmpiStrDup)(const CMPIBroker*, const char*);
void (*cmpiFree)(const
CMPIBroker*, void*);
void (*freeInstance)(const CMPIBroker*, CMPIInstance*);
void (*freeObjectPath)(const CMPIBroker*, CMPIObjectPath*);
void (*freeArgs)(const CMPIBroker*, CMPIArgs*);
void (*freeString)(const CMPIBroker*, CMPIString*);
void (*freeArray)(const CMPIBroker*, CMPIArray*);
void (*freeDateTime)(const CMPIBroker*, CMPIDateTime*);
void (*freeSelectExp)(const CMPIBroker*, CMPISelectExp*);
} CMPIBrokerMemFT;
In all cases that I am aware of, these
errors were in the spec, with the headers being correct. However, part
of the effort of this PEP will be to examine existing function
definitions and compare them against the standard headers (and the
spec, again, just to make sure we got them all).
One area that Pegasus is currently
non-conformant is captured by bug 4985, which will be fixed as part of
this effort:
CMPI 1.0 specification has the following prototype for these functions (see
section 5.1.3.4):
...
CMPIStatus (*enableIndications)(CMPIIndicationMI*,const CMPIContext*);
CMPIStatus (*disableIndications)(CMPIIndicationMI*,const CMPIContext*);
However the CMPI headers that Pegasus ships has these functions returning 'void'
(see cmpift.h lines 2612 & 2614).
Providers written to these headers are non-conformant and may crash on other
implmentations as they do not return the proper CMPIStatus object.
It is important to stay current with the latest version of the CMPI
standard. Working on the implementation while the spec is out for
company review allows for (1) detailed check of the accuracy of the
spec, and (2) review comments to be made on the spec before it has been
approved, where errors or problems are detected. Any comments made and
incorporated into the CMPI 2.0 spec as part of the company review will
need to be incorporated here. Company review is expected to end around
September 25th, 2006.
Action | Planned | Actual | Comment |
PEP Submitted | 08/01/2006 |
08/11/2006 | |
PEP Reviewed | 08/15/2006 |
08/15/2006 | version 1.0 |
PEP Approved | 08/29/2006 |
10/06/2006 | version 1.0 |
Code Committed | Pegasus 2.6 09/29/2006 |
11/01/2006 | Bugzillas 5734 and 5735 |
Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person obtaining a
copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation
the
rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or
sell copies of the Software, and to permit persons to whom the Software
is
furnished to do so, subject to the following conditions:
THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED
IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS
PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Template last modified: March 26th 2006 by Martin Kirk
Template version: 1.11