version 1.7, 2003/11/13 16:02:37
|
version 1.8, 2003/11/20 13:54:10
|
|
|
/// @name Pegasus API Documentation |
/** @name Pegasus API Documentation |
/* api.dxx - Top Level file for Developer api Documentation. |
|
This file defines the document strucuture and provides the introduction |
|
| |
$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 |
|
| |
<CENTER><FONT Size=+4>PEGASUS Public APIs</FONT></CENTER> | <CENTER><FONT Size=+4>PEGASUS Public APIs</FONT></CENTER> |
| |
<P><B><CENTER>STATUS: DRAFT FOR REVIEW</CENTER></B> | <P><B><CENTER>STATUS: DRAFT FOR REVIEW</CENTER></B> |
<SMALL><CENTER>version 1.01 30 October 2003, Pegasus 2.3</CENTER></SMALL> | <SMALL><CENTER>version 1.01 30 October 2003, Pegasus 2.3</CENTER></SMALL> |
| |
Pegasus is an open source implementation of the manageability environment defined by the DMTF WBEM standards. |
<p> This document was produced on \date .</p> |
|
|
| |
<P>This is a working document that contains the interfaces for the Pegasus | <P>This is a working document that contains the interfaces for the Pegasus |
CIM Server implementation. This is created by the OpenGroup | CIM Server implementation. This is created by the OpenGroup |
Enterprise Management Program Group. | 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 | <p>In addition to this documentation, Pegasus has a Users' Guide that |
specifies overview information and how to set up and install Pegasus. In | specifies overview information and how to set up and install Pegasus. In |
addition to the manual, the README files contain specific information to | addition to the manual, the README files contain specific information to |
aide you in when working with Pegasus and its documentation.</p> | aide you in when working with Pegasus and its documentation.</p> |
| |
<p>Within this document, you will find the following:</p> |
@memo Public API reference document for the Pegasus CIM Object Manager |
<UL> |
implementation. |
<LI>A definition of the public APIs defined for the current version of Pegasus including |
|
the client, CIMOM, and provider APIs. |
*/ |
<LI>Information on the status of these APIs (frozen, experimental, etc.). |
/* api.dxx - Top Level file for Developer api Documentation. |
<LI> Usage examples of the APIs with the defintions. |
This file defines the document strucuture and provides the introduction |
</UL> |
|
|
$Author$ |
|
*/ |
| |
|
|
|
//@{ |
|
/** @name Introduction |
|
|
|
|
|
The APIs documented here are those that are considered frozen and that we expect |
|
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. |
|
|
|
REVIEWERS: more on versions. |
|
*/ |
|
//@{ |
|
|
|
|
|
/// @name Common API Characteristics |
|
|
|
//@{ |
|
|
|
/** @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 |
|
*/ |
|
|
|
|
|
/** @name Memory Ownership |
|
REVIEWERS: |
|
*/ |
|
|
|
|
|
//@} |
|
//@} |
|
|
|
/* |
<p>The following are interfaces that are frozen with the 2.3 release of Pegasus: | <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 | 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 | in the classes and methods themselves, not in this list. In reality |
|
|
references here and text in the individual files. | references here and text in the individual files. |
</p> | </p> |
| |
TBD: Pegasus API version information |
TODO: We should be getting Pegasus Version information directly from Pegasus, not |
|
just in this text file. |
|
|
*/ | */ |
| |
/** @name Pegasus CIM Objects and Common Function APIs. | /** @name Pegasus CIM Objects and Common Function APIs. |
|
|
//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h | //@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h |
//@} | //@} |
| |
/// @name General Information on the APIs |
//@Include: ..\DevManual\definitions.dxx |
//@{ |
|
//@Include: Commondefinitions.dxx |
|
//@} |
|
//@Include: definitions.dxx |
|
| |
/** @name Document References | /** @name Document References |
| |
|
|
</UL> | </UL> |
*/ | */ |
| |
|
//@} |
| |