version 1.1, 2003/10/01 19:02:04
|
version 1.8, 2003/11/20 13:54:10
|
|
|
|
/** @name Pegasus API Documentation |
|
|
|
|
|
<CENTER><FONT Size=+4>PEGASUS Public APIs</FONT></CENTER> |
|
|
|
<P><B><CENTER>STATUS: DRAFT FOR REVIEW</CENTER></B> |
|
<SMALL><CENTER>version 1.01 30 October 2003, Pegasus 2.3</CENTER></SMALL> |
|
|
|
<p> This document was produced on \date .</p> |
|
|
|
<P>This is a working document that contains the interfaces for the Pegasus |
|
CIM Server implementation. This is created by the OpenGroup |
|
Enterprise Management Program Group. |
|
<p>Within this document, you will find the following:</p> |
|
<UL> |
|
<LI> An introduction to the public APIs defined and used in Pegasus in the \Ref{Introduction} section. |
|
<LI>A definition of the public APIs defined for the current version of Pegasus including |
|
<ul> |
|
<li>the client APIs \Ref{Client Interfaces} |
|
<li>The CIM Object Manager APIs (see \Ref{} includng both the Pegasus object equivalent to |
|
the CIM Objects(see \Ref{} and other server service APIs (\Ref{}) that have been |
|
made public. |
|
<li>the APIs required by provider writers to create Pegasus C++ providers in section \Ref{Providers}. |
|
<li>Common term definitions (See \Ref{Glossary}). |
|
</u.> |
|
<LI>Information on the status of these APIs (frozen, experimental, etc.). |
|
<LI> Usage examples of many of the APIs with the defintions. |
|
</UL> |
|
|
|
This API documentation is not a tutorial on Pegasus or a developers guide. |
|
<p>In addition to this documentation, Pegasus has a Users' Guide that |
|
specifies overview information and how to set up and install Pegasus. In |
|
addition to the manual, the README files contain specific information to |
|
aide you in when working with Pegasus and its documentation.</p> |
|
|
|
@memo Public API reference document for the Pegasus CIM Object Manager |
|
implementation. |
|
|
|
*/ |
/* api.dxx - Top Level file for Developer api Documentation. | /* api.dxx - Top Level file for Developer api Documentation. |
This file defines the document strucuture and provides the introduction | This file defines the document strucuture and provides the introduction |
| |
|
|
$Author$ | $Author$ |
*/ | */ |
/* do not change the following Name. Used in the Frame definition. |
|
If you change it, the HTML Frame must also be changed. |
|
*/ |
//@{ |
/** @name Introduction | /** @name Introduction |
| |
<CENTER><FONT Size=+4>PEGASUS Public APIs</FONT></CENTER> |
|
| |
<P><B><CENTER>STATUS: DRAFT FOR REVIEW</CENTER></B> |
The APIs documented here are those that are considered frozen and that we expect |
<SMALL><CENTER>version 1.01 13 September 2003</CENTER></SMALL> |
not to change within minor releases of Pegasus. It is an objective of Pegasus |
|
to keep these APIs frozen as long as Pegasus remains at the version 2.x revision |
|
level so that providers written for any 2.x Pegasus will run in environments that |
|
use the same or higher level revisions. |
|
|
|
Note that Pegasus does extend and add new APIs to the publically available API set |
|
most releases as new functionality is defined. Typically these are marked experimental |
|
for the first release so that developers can be made aware that they may change. Once |
|
they have been tested and used, the experimental qualifications will be removed and they |
|
become part of the Pegasus public API set. |
| |
Pegasus is an open source implementation of the manageability environment defined by the DMTF WBEM standards. |
REVIEWERS: more on versions. |
|
*/ |
|
//@{ |
| |
<B>This Document</B> |
|
| |
<P>This is a working document that is the temporary user and developers manual for the Pegasus CIM Server implementation which is being created by the OpenGroup Enterprise Management Program Group. |
/// @name Common API Characteristics |
| |
This manual serves as both a manual for installation and operation of the prototype version of Pegasus and a manual for developing components to attach to Pegasus. In addition to the manual, we keep current working information in a set of README files within the Pegasus distributions. Please consult these files also. |
//@{ |
|
|
|
/** @name Shared Classes. |
|
A shared class consists of a pointer to a shared data block that |
|
contains a reference count and the data. |
|
|
|
When a shared object is created, it sets the reference count to 1. The |
|
reference count is incremented whenever a new object references the shared |
|
data, and decremented when the object dereferences the shared data. The |
|
shared data is deleted when the reference count becomes zero. |
|
|
|
When dealing with shared objects, there are two ways of copying an object. |
|
We usually speak about deep and shallow copies. A deep copy implies |
|
duplicating an object. A shallow copy is a reference copy, i.e. just a |
|
pointer to a shared data block. Making a deep copy can be expensive in |
|
terms of memory and CPU. Making a shallow copy is very fast, because it |
|
only involves setting a pointer and incrementing the reference count. |
|
|
|
Object assignment (with operator=()) for implicitly and explicitly shared |
|
objects is implemented using shallow copies. A deep copy can be made by |
|
calling a copy() function. |
|
|
|
The benefit of sharing is that a program does not need to duplicate data |
|
unnecessarily, which results in lower memory use and less copying of data. |
|
Objects can easily be assigned, sent as function arguments, and returned |
|
from functions. |
|
|
|
Now comes the distinction between explicit and implicit sharing. Explicit |
|
sharing means that the programmer must be aware of the fact that objects |
|
share common data. Implicit sharing means that the sharing mechanism |
|
takes place behind the scenes and the programmer does not need to worry |
|
about it. |
|
|
|
All of the shared classes in Pegasus are explicitly shared. These classes |
|
have a clone() function that returns a deep copy with a reference count of 1. |
|
*/ |
|
|
|
|
|
/** @name Encapsulation |
|
REVIEWERS: To be completed |
|
*/ |
|
|
|
/** @name Error Handling |
|
|
|
REVIEWERS: TO Be completed |
|
*/ |
|
|
|
|
|
/** @name Threading |
|
REVIEWERS: To be completed |
|
*/ |
| |
Within this manual you will find: |
|
<UL> |
|
<LI>Information on the installation and operation of the broker and additional components. |
|
<LI> A basic defintion of the architecture and function of Pegasus. |
|
<LI>The current definition of the programming interfaces that Pegasus allows. As these interfaces are stabilized they will be moved from this document to an Open Group specificaton. |
|
<LI>A number of defintions of additional code that is |
|
available to interface with Pegasus as providers, consumers, and services. |
|
</UL> |
|
| |
|
/** @name Memory Ownership |
|
REVIEWERS: |
*/ | */ |
| |
| |
/* The following is the complete file hiearchy for this document. |
//@} |
|
//@} |
|
|
|
/* |
|
<p>The following are interfaces that are frozen with the 2.3 release of Pegasus: |
|
CONNIE: we will go nuts if we try to do the lists this way. We need to mark them |
|
in the classes and methods themselves, not in this list. In reality |
|
all interfaces that are not explicitly marked experimental are frozen. |
|
We should state that. |
|
Need to reference PEP 57 as the authority for this release. |
|
|
|
|
|
<p>The following are interfaces that are experimental: |
|
CONNIE: We might get by with this experimental list but it will change for each |
|
version of the document. |
|
|
|
|
|
<p>The following is the complete file hiearchy for this document. |
We have tried to keep all file references in only this one place | We have tried to keep all file references in only this one place |
to make modification easier. In the future, please keep the | to make modification easier. In the future, please keep the |
references here and text in the individual files. | references here and text in the individual files. |
|
</p> |
|
|
|
TODO: We should be getting Pegasus Version information directly from Pegasus, not |
|
just in this text file. |
| |
TBD: Pegasus API version information |
|
*/ | */ |
| |
/** @name Pegasus CIM OBjects and General Function APIs |
/** @name Pegasus CIM Objects and Common Function APIs. |
NOTE: This needs to be reorganized to take into account a structure for these APIs |
This section defines the Pegasus C++ Classes that represent |
|
the CIM objects and the common functions used by Pegasus |
*/ | */ |
|
|
//@{ | //@{ |
|
/// @name Classes for CIM Objects and Containers |
//@{ | //@{ |
//@Include: ../../src/Pegasus/Common/Array.h | //@Include: ../../src/Pegasus/Common/Array.h |
|
//@Include: ../../src/Pegasus/Common/ArrayInter.h |
//@Include: ../../src/Pegasus/Common/Boolean.h | //@Include: ../../src/Pegasus/Common/Boolean.h |
//@Include: ../../src/Pegasus/Common/CIMClass.h | //@Include: ../../src/Pegasus/Common/CIMClass.h |
//@Include: ../../src/Pegasus/Common/CIMClassRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMDateTime.h | //@Include: ../../src/Pegasus/Common/CIMDateTime.h |
//@Include: ../../src/Pegasus/Common/CIMExceptionRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMFlavor.h | //@Include: ../../src/Pegasus/Common/CIMFlavor.h |
//@Include: ../../src/Pegasus/Common/CIMIndication.h | //@Include: ../../src/Pegasus/Common/CIMIndication.h |
//@Include: ../../src/Pegasus/Common/CIMInstance.h | //@Include: ../../src/Pegasus/Common/CIMInstance.h |
//@Include: ../../src/Pegasus/Common/CIMInstanceRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMMessage.h |
|
//@Include: ../../src/Pegasus/Common/CIMMethod.h | //@Include: ../../src/Pegasus/Common/CIMMethod.h |
//@Include: ../../src/Pegasus/Common/CIMMethodRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMName.h | //@Include: ../../src/Pegasus/Common/CIMName.h |
//@Include: ../../src/Pegasus/Common/CIMOMPort.h |
|
//@Include: ../../src/Pegasus/Common/CIMObject.h | //@Include: ../../src/Pegasus/Common/CIMObject.h |
//@Include: ../../src/Pegasus/Common/CIMObjectPath.h | //@Include: ../../src/Pegasus/Common/CIMObjectPath.h |
//@Include: ../../src/Pegasus/Common/CIMObjectRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMParamValue.h | //@Include: ../../src/Pegasus/Common/CIMParamValue.h |
//@Include: ../../src/Pegasus/Common/CIMParamValueRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMParameter.h | //@Include: ../../src/Pegasus/Common/CIMParameter.h |
//@Include: ../../src/Pegasus/Common/CIMParameterRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMPredicate.h |
|
//@Include: ../../src/Pegasus/Common/CIMProperty.h | //@Include: ../../src/Pegasus/Common/CIMProperty.h |
//@Include: ../../src/Pegasus/Common/CIMPropertyList.h | //@Include: ../../src/Pegasus/Common/CIMPropertyList.h |
//@Include: ../../src/Pegasus/Common/CIMPropertyRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMQualifier.h | //@Include: ../../src/Pegasus/Common/CIMQualifier.h |
//@Include: ../../src/Pegasus/Common/CIMQualifierDecl.h | //@Include: ../../src/Pegasus/Common/CIMQualifierDecl.h |
//@Include: ../../src/Pegasus/Common/CIMQualifierDeclRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMQualifierList.h | //@Include: ../../src/Pegasus/Common/CIMQualifierList.h |
//@Include: ../../src/Pegasus/Common/CIMQualifierNames.h |
|
//@Include: ../../src/Pegasus/Common/CIMQualifierRep.h |
|
//@Include: ../../src/Pegasus/Common/CIMRepositoryBase.h |
|
//@Include: ../../src/Pegasus/Common/CIMScope.h | //@Include: ../../src/Pegasus/Common/CIMScope.h |
//@Include: ../../src/Pegasus/Common/CIMStatusCode.h | //@Include: ../../src/Pegasus/Common/CIMStatusCode.h |
//@Include: ../../src/Pegasus/Common/CIMType.h | //@Include: ../../src/Pegasus/Common/CIMType.h |
//@Include: ../../src/Pegasus/Common/CIMValue.h | //@Include: ../../src/Pegasus/Common/CIMValue.h |
//@Include: ../../src/Pegasus/Common/Char16.h | //@Include: ../../src/Pegasus/Common/Char16.h |
//@Include: ../../src/Pegasus/Common/Formatter.h |
//@Include: ../../src/Pegasus/Common/Config.h |
//@Include: ../../src/Pegasus/Common/OperationContext.h |
|
//@Include: ../../src/Pegasus/Common/Queue.h |
|
//@Include: ../../src/Pegasus/Common/Stopwatch.h |
|
//@Include: ../../src/Pegasus/Common/String.h | //@Include: ../../src/Pegasus/Common/String.h |
|
//@Include: ../../src/Pegasus/Common/CIMIndication.h |
|
//@} |
|
/// @name General Server Functionality Classes |
//@{ | //@{ |
/// @name Exceptions |
//@Include: ../../src/Pegasus/Common/OperationContext.h |
//@Include: ../../src/Pegasus/Common/Exception.h |
//@Include: ../../src/Pegasus/Common/ResponseHandler.h |
|
//@Include: ../../src/Pegasus/Common/SSLContext.h |
//@} | //@} |
|
/// @name CIM Object Exceptions |
|
//@{ |
|
//@Include: ../../src/Pegasus/Common/Exception.h |
//@} | //@} |
|
|
//@} | //@} |
/// @name Client and Provider Interfaces |
/// @name Client Interfaces |
//@{ | //@{ |
/** @name Pegasus Operations | /** @name Pegasus Operations |
NOTE That this section should probably go away | NOTE That this section should probably go away |
|
|
//@{ | //@{ |
//@Include: ../../doc/CIMOperations.h | //@Include: ../../doc/CIMOperations.h |
//@} | //@} |
/// @name Pegasus Client Interfaces |
/// @name Pegasus Client CIM Operation and Connection Interfaces |
//@{ | //@{ |
//@Include: ../../src/Pegasus/Client/CIMClient.h | //@Include: ../../src/Pegasus/Client/CIMClient.h |
|
//@Include: ../../src/Pegasus/Client/CIMClientException.h |
//@} | //@} |
/// @name Pegasus Provider Interfaces |
/// @name Pegasus Client SLP interfaces |
|
//@{ |
|
//@Include: ../../src/Pegasus/Client/CIMServerDiscovery.h |
|
//@Include: ../../src/Pegasus/Client/CIMServerDescription.h |
|
//@Include: ../../src/Pegasus/Client/Attribute.h |
|
//@} |
|
/// @name Pegasus Listener Interfaces |
|
//@{ |
|
//@Include: ../../src/Pegasus/Listener/CIMListener.h |
|
//@} |
|
//@} |
|
/// @name C++ Provider Interfaces |
|
//@{ |
|
/// Pegasus CIM Provider Types and Interfaces |
//@{ | //@{ |
|
|
//@Include: ../../src/Pegasus/Provider/CIMProvider.h | //@Include: ../../src/Pegasus/Provider/CIMProvider.h |
//@Include: ../../src/Pegasus/Provider/CIMAssociationProvider.h | //@Include: ../../src/Pegasus/Provider/CIMAssociationProvider.h |
//@Include: ../../src/Pegasus/Provider/CIMClassProvider.h |
//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h |
//@Include: ../../src/Pegasus/Provider/CIMIndicationConsumer.h |
|
//@Include: ../../src/Pegasus/Provider/CIMIndicationProvider.h | //@Include: ../../src/Pegasus/Provider/CIMIndicationProvider.h |
//@Include: ../../src/Pegasus/Provider/CIMInstanceProvider.h | //@Include: ../../src/Pegasus/Provider/CIMInstanceProvider.h |
//@Include: ../../src/Pegasus/Provider/CIMMethodProvider.h | //@Include: ../../src/Pegasus/Provider/CIMMethodProvider.h |
//@Include: ../../src/Pegasus/Provider/CIMNullProvider.h |
//@} |
|
/// Pegasus CIM Provider CIMOM Handle Callback |
|
//@{ |
//@Include: ../../src/Pegasus/Provider/CIMOMHandle.h | //@Include: ../../src/Pegasus/Provider/CIMOMHandle.h |
//@Include: ../../src/Pegasus/Provider/CIMPropertyProvider.h |
//@} |
//@Include: ../../src/Pegasus/Provider/CIMQueryProvider.h |
/// Pegasus CIM Provider Exceptions |
|
//@{ |
//@Include: ../../src/Pegasus/Provider/ProviderException.h | //@Include: ../../src/Pegasus/Provider/ProviderException.h |
//@} | //@} |
//@} | //@} |
|
/// @name Pegasus Server Indication Consumer |
|
//@{ |
|
//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h |
|
//@} |
|
|
|
//@Include: ..\DevManual\definitions.dxx |
|
|
/** @name Document References | /** @name Document References |
| |
This section will contain references to external documents. | This section will contain references to external documents. |
| |
NOTE: documents we must reference include: |
NOTE: Documents we must reference include: |
|
|
<UL> | <UL> |
<LI>DMTF Specifications |
<LI>CIM Operations Spec. |
<LI> |
<LI>CIM Spec. |
</UL/ |
</UL> |
*/ //@Include: references.dxx |
*/ |
| |
|
//@} |
| |