(file) Return to apidoc.dxx CVS log (file) (dir) Up to [Pegasus] / pegasus / doc / apidoc / Attic

Diff for /pegasus/doc/apidoc/Attic/apidoc.dxx between version 1.7 and 1.8

version 1.7, 2003/11/13 16:02:37 version 1.8, 2003/11/20 13:54:10
Line 1 
Line 1 
 /// @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
Line 53 
Line 148 
    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.
Line 152 
Line 249 
                 //@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
  
Line 169 
Line 262 
         </UL>         </UL>
 */ */
  
   //@}
  

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.8
No CVS admin address has been configured
 Powered by
ViewCVS 0.9.2