INTRO:sfcc - Small Footprint CIM Client Library
SFCC information:
Version 1:
Version 2:
Compatibility:
Backend Selection:
CVS Instructions:
Functions:
====================================================================================
INTRO:sfcc - Small Footprint CIM Client Library
===============================================
The small footprint CIM client library is a C API allowing client applications
to interface with CIM implementations (e.g. CIM servers). Due to it's small
memory and disk footprint it is well-suited for embedded environments.
SFCC information:
=================
SFCC provides a generic layer to load the underlying libraries to communicate to the
CIM server via 2 methods:
1- http interface
2- local connect interface
SFCC provides the libraries for cimxml via http and SFCB provides a library
which is loaded by SFCC to provide local connect.
When using the http interface the CIM server can physically be located on the same
system as SFCC or a remote system and communication is over the http protocol.
When using the local connect interface the CIM server must be SFCB and physically
located on the same system as SFCC and is provided via SFCB and SFCC libraries.
Communication is accomplished via localconnect sockets. Note that the local connect
will use a library that is part of sfcb so the application must have the same
authorization as the installer of sfcb.
If the sfcb libraries have not been installed to the default location
(<libdir>/sfcb), SFCC will need to be configured to find them. Use
"configure SFCB_LIBDIR=<dir>" to inform the SFCC build where to find the
libraries.
Applications using SFCC determine which method to use by calling the NewCIMCEnv
library function which establishes the environment for using one of the above
communication methods.
Version 1:
==========
The initial version of sfcc is based on concepts of the Common Manageability
Programming Interface (CMPI) defined by the Open Group. A client program
using version 1 of sfcc usually needs to include the following headers or
a subset thereof and link against libcmpisfcc.so:
- cmci.h
- cmcidt.h
- cmcift.h
- cmcimacs.h
- native.h
Version 2:
==========
The current version of sfcc has undergone some structural changes in order
to support different backend implementations, like local communication to
a CIM server or even direct provider calls.
For this purpose a three-layer architecture has been chosen, consisting of
a frontend layer, the core CIM C API and a backend layer.
The core CIM C API which in fact is also an application binary interface (ABI)
just offers two functions: NewCIMCEnv and ReleaseCIMCEnv.
These are used to establish or to remove a CIM client environment which can
be used to connect to a CIM server and perform CIM operations against
that connection.
A CIM client environment needs to be implemented by a backend which is a
shared library offering a defined entry point with a name like
_Create_<backend>_Env
which is used to return a pointer to a CIMCEnv structure containing a function
pointer table exposing the services supported by the backend. This is very
similar to the way a CMPI provider is implemented.
Currently sfcc ships with a CIM XML backend which should be the most common
protocol for CIM-based client-server communication. The sfcb CIM server also
ships with a local connect backend. The effort to write a backend for a CIM server
is roughly comparable to the effort of writing a CMPI provider adapter/manager.
While it's possible to write programs directly against the core CIM C API,
it's likely that this will not be appropriate for everybody. Therefore
it's possible to add frontend APIs (aka language bindings) on top of the
core CIM C API. Currently there's one frontend in sfcc v2: the v1
compatibility library.
Compatibility:
==============
There's a number of reasons why the original sfcc API is not well suited to
serve as the core CIM C API.
Most problematic is that the object creation functions are not implemented
via function pointer tables but with fixed entry points which would
add overhead and complication for backend implementations.
The core CIM C API groups these functions in the CIMCEnv function pointer
table.
Another, more cosmetic issue, is that the original sfcc implementation
in fact uses modified CMPI headers which disallows to mix provider and
client code in the same executable. The new core CIM C API headers have
their own declarations prefixed with CIMC (instead of CMPI or CMCI).
Compatibility with version 1 is ensured via a frontend implementation.
This allows old applications to take advantage of new backends without
the need to rewrite them.
There are however some restrictions to keep in mind:
A. Removed Functions
Some functions have been removed from the set of public functions, as they
are considered internal stuff, which shouldn't be of concern to clients.
These are:
native_release_CMPIValue
newList
newStringBuffer
As consequence of this it was necessary to re-version the library which
will require a re-linking of your application.
B. Feature Freeze
The version 1 sfcc API is frozen: new features won't be backported.
Backend Selection:
==================
The proper way to select the backend is via the NewCIMCEnv call. The first
argument is used to construct the backend library name and the entry point.
I.e.
example 1 - sets up the CIM XML environment.
CIMCEnv ce = NewCIMCEnv("XML",0,&rc,&msg);
will load the shared library libcimcClientXML.so, locate the
function _Create_XML_Env and call it to establish the environment.
example 2 - sets up the local connect environment.
CIMCEnv ce = NewCIMCEnv("SfcbLocal",0,&rc,&msg);
will load the shared library libcimcClientLocal.so, locate the
function _Create_SfcbLocal_Env and call it to establish the environment.
This also implies that any future library that implements the functions
specified in the cimc layer could also be loaded by specifying "XXX" to
load the libcimcClientXXX.so library.
CVS Instructions:
=================
If you checkout from CVS run autoconfiscate.sh to prepare for building.
To build:
# configure
# make
# make install
These make the test cases under TEST as well.
# configure CPPFLAGS='-DDEBUG'
Builds a version of the library with debug output enabled.
Note that to pass the tests it is necessary to install the following
provider packages from the SBLIM project
http://sourceforge.net/projects/sblim
- sblim-cmpi-base (available in tar.bz2 format)
- cmpi-tests (currently available
Functions:
==========
Necessary for initialization:
NewCIMCEnv - sets up the environment to use for communication to the CIM server.
usage for local connect
ce = NewCIMCEnv("SfcbLocal",0,&rc,&msg);
usage for http connect
ce = NewCIMCEnv("XML",0,&rc,&msg);
connect - establishes the connection to the CIM server
CIM Request functions:
getClass
enumClasses
enumClassNames
createInstance
getInstance
setInstance
deleteInstance
execQuery
enumInstanceNames
enumInstances
associators
associatorNames
references
referenceNames
invokeMethod
setProperty
getProperty
Since the enumeration functions can result in an array of responses there
are 2 functions to control getting the responses.
enumeration special functions
hasNext
getNext
The hasNext function will return a boolean value
0 - no more responses
1 - more responses available
The getNext function will return the next response for the enumeration.
The release function is used to release resources associated with the specific
pointer.