Invoking the Providers | A Practical Approach to WBEM[s]CIM Management

Missing Provider

Before actually linking the provider code into the shared library, it is instructive to try to invoke a provider when it is not in the library. I wrote a simple XML file to invoke the intrinsic method EnumerateInstances() on the ACNE_PBXTelephoneModule class while the library file was not present in the library directory. I then used the wbemexec utility to send the XML to the WBEM server. The wbemexec program is very simple and is provided with the openPegasus release ”it connects to the WBEM server as a WBEM client, reads the specified XML file and passes the XML to the WBEM server. It then prints out the XML response which it receives. When I tried to invoke the EnumerateInstances() intrinsic function, not unreasonably I received the message:

 <?xml version="1.0" encoding="utf-8"?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">  <MESSAGE ID="25000" PROTOCOLVERSION="1.0">   <SIMPLERSP>    <IMETHODRESPONSE NAME="EnumerateInstances">     <ERROR CODE="7"      DESCRIPTION="CIM_ERR_NOT_SUPPORTED: The requested "                  "operation is not supported: "                  "&quot;Invalid provider interface.&quot;"/>    </IMETHODRESPONSE>   </SIMPLERSP>  </MESSAGE> </CIM>

The line breaking in the description of the error is mine to ensure that it was readable in this book. This is a sensible error message given the condition: it simply says that it could not find the provider.

Providers Throwing Exceptions

Having determined that, quite reasonably, the system does not work unless we write providers, let us now compile the providers that we wrote above and add these to the library.

We started our coding with the methods that did not do anything other than throw an exception. Let us start there again and try to create an instance of the ACNE_PBXTelephoneModule class. We can see from the code for createInstance() included as Figure 12.5 that this should fail and an exception be thrown.

I give the XML which I sent to the WBEM server in this forlorn attempt to create an instance of ACNE_PBXTelephoneModule in Figure 12.17. Because the input XML is very similar for different commands, I save a few trees by only giving this one example.

 <?xml version="1.0" encoding="utf-8"?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">   <MESSAGE ID="53044" PROTOCOLVERSION="1.0">     <SIMPLEREQ>       <IMETHODCALL NAME="CreateInstance">         <LOCALNAMESPACEPATH>           <NAMESPACE NAME="root"/>           <NAMESPACE NAME="acnePbx"/>         </LOCALNAMESPACEPATH>         <IPARAMVALUE NAME="NewInstance">           <INSTANCE CLASSNAME="ACNE_PBXTelephoneModule">            <PROPERTY NAME="Protocol" TYPE="uint32">             <VALUE>0</VALUE>            </PROPERTY>            <PROPERTY NAME="ModuleNumber" TYPE="uintl6">             <VALUE>4</VALUE>            </PROPERTY>            <PROPERTY NAME="SystemCreationClassName"                                            TYPE="string">             <VALUE>ACNE_PBX</VALUE>            </PROPERTY>            <PROPERTY NAME="SystemName" TYPE="string">             <VALUE>XYZCompanyPBX1</VALUE>            </PROPERTY>            <PROPERTY NAME="CreationClassName" TYPE="string">             <VALUE>ACNE_PBXTelephoneModule</VALUE>            </PROPERTY>            <PROPERTY NAME="DeviceID" TYPE="string">             <VALUE>123</VALUE>            </PROPERTY>           </INSTANCE>         </IPARAMVALUE>       </IMETHODCALL>     </SIMPLEREQ>   </MESSAGE> </CIM>

Figure 12.17: XML to Create an ACNE_PBXTelephoneModule

As expected, the following XML snippet is returned, surrounded by the normal CIM-XML pre- and postamble (again, the line is broken to make it readable):

 <IMETHODRESPONSE NAME="CreateInstance">   <ERROR CODE="7"    DESCRIPTION="CIM_ERR_NOT_SUPPORTED: The requested "                "operation is not supported: "                "&quot;Modules may not be created "                "manually&quot;"/> </IMETHODRESPONSE>

EnumerateInstanceNames()

We should now try to invoke a method which actually does something other than throw an exception. enumerateInstanceNames() is a good example. The XML returned from invoking our enumerateInstanceNames() method is as follows (again excluding the XML pre- and postamble and giving only one of the three instances):

 <IMETHODRESPONSE NAME="EnumerateInstanceNames">  <IRETURNVALUE>   <INSTANCENAME CLASSNAME="ACNE_PBXTelephoneModule">    <KEYBINDING NAME="CreationClassName">     <KEYVALUE VALUETYPE="string">      ACNE_PBXTelephoneModule     </KEYVALUE>    </KEYBINDING>    <KEYBINDING NAME="DeviceID">     <KEYVALUE VALUETYPE="string"> 1 </KEYVALUE>    </KEYBINDING>    <KEYBINDING NAME="SystemCreationClassName">     <KEYVALUE VALUETYPE="string"> ACNE\_PBX </KEYVALUE>    </KEYBINDING>    <KEYBINDING NAME="SystemName">     <KEYVALUE VALUETYPE="string"> XYZCompanyPBXl </KEYVALUE>    </KEYBINDING>   </INSTANCENAME>   ......(for other instances).....  </IRETURNVALUE> </IMTHODRESPONSE>

This is effectively just the Object Path encoded in XML.

GetInstance()

Given the rather artificial code for getInstance() ”see Figures 12.7 to 12.9, it is easy to predict the XML that a call to GetInstance will return to the WBEM client (again shorn of its XML wrappers):

 <IMETHODRESPONSE NAME="GetInstance">  <IRETURNVALUE>   <INSTANCE CLASSNAME="ACNE_PBXTelephoneModule">    <PROPERTY NAME="SystemCreationClassName" TYPE="string">     <VALUE>ACNE_PBX</VALUE>    </PROPERTY>    <PROPERTY NAME="SystemName" TYPE="string">     <VALUE>XYZCompanyPBX1</VALUE>    </PROPERTY>    <PROPERTY NAME="CreationClassName" TYPE="string">     <VALUE>ACNE_PBXTelephoneModule</VALUE>    </PROPERTY>    <PROPERTY NAME="DeviceID" TYPE="string">     <VALUE>3</VALUE>    </PROPERTY>    <PROPERTY NAME="Protocol" TYPE="sint32">     <VALUE>1</VALUE>    </PROPERTY>    <PROPERTY NAME="ModuleNumber" TYPE="sint32">     <VALUE>4</VALUE>    </PROPERTY>    ....and so on for the remaining properties   </INSTANCE>  </IRETURNVALUE> </IMETHODRESPONSE>

This is just a list of the property values which we hard-coded into the helper functions for the provider.

Extrinsic Method Invocation

As you can see from Figure 12.11 and Figure 12.12, I actually wrote the code for two extrinsic functions: reset() and setIndicator() . Of these, setIndicator() is by far the more exciting ^[2] as it can be provoked to return exceptions. If, for example, it is invoked with two parameters instead of the one expected, then the following is returned to the WBEM client (again, I have broken the string for readability):

 <METHODRESPONSE NAME="setIndicator">  <ERROR CODE="4" DESCRIPTION="CIM_ERR_INVALID_PARAMETER: "           "One or more parameter values passed to the "           "method were invalid: "           "&quot;setIndicator needs 1 param&quot;"/> </METHODRESPONSE>

This incorporates the error string which I programmed into the code.

If this method is invoked correctly with a single parameter set to TRUE then it returns FALSE:

 <METHODRESPONSE NAME="setIndicator">  <RETURNVALUE PARAMTYPE="boolean">   <VALUE> FALSE </VALUE>  </RETURNVALUE> </METHODRESPONSE>

^[2] This depends, of course, on your standards of excitement.