1 karl  1.8 /** @name Pegasus API Documentation

  2 karl  1.1 
  3           
  4           <CENTER><FONT Size=+4>PEGASUS Public APIs</FONT></CENTER>
  5           
  6           <P><B><CENTER>STATUS: DRAFT FOR REVIEW</CENTER></B>

  7 karl  1.5 <SMALL><CENTER>version 1.01 30 October 2003, Pegasus 2.3</CENTER></SMALL>

  8 karl  1.1 

  9 karl  1.8 <p> This document was produced on \date .</p>

 10 karl  1.1 

 11 karl  1.5 <P>This is a working document that contains the interfaces for the Pegasus 

 12 karl  1.7 CIM Server implementation.  This is created by the OpenGroup 

 13 karl  1.8 Enterprise Management Program Group.
 14           <p>Within this document, you will find the following:</p>
 15           <UL>
 16           <LI> An introduction to the public APIs defined and used in Pegasus in the \Ref{Introduction} section.
 17           <LI>A definition of the public APIs defined for the current version of Pegasus including
 18                   <ul>
 19                   <li>the client APIs \Ref{Client Interfaces}
 20                   <li>The CIM Object Manager APIs (see  \Ref{} includng both the Pegasus object equivalent to
 21                   the CIM Objects(see \Ref{} and other server service APIs (\Ref{}) that have been
 22                   made public. 
 23                   <li>the APIs required by provider writers to create Pegasus C++ providers in section \Ref{Providers}.
 24                   <li>Common term definitions (See \Ref{Glossary}).
 25                   </u.>
 26           <LI>Information on the status of these APIs (frozen, experimental, etc.).
 27           <LI> Usage examples of many of the APIs with the defintions.
 28           </UL>

 29 karl  1.5 

 30 karl  1.8 This API documentation is not a tutorial on Pegasus or a developers guide.

 31 karl  1.5 <p>In addition to this documentation, Pegasus has a Users' Guide that 
 32           specifies overview information and how to set up and install Pegasus.  In 
 33           addition to the manual, the README files contain specific information to 
 34           aide you in when working with Pegasus and its documentation.</p> 

 35 karl  1.1 

 36 karl  1.8 @memo Public API reference document for the Pegasus CIM Object Manager
 37           implementation.
 38           
 39           */
 40           /* api.dxx - Top Level file for Developer api Documentation.
 41           This file defines the document strucuture and provides the introduction
 42           */
 43           
 44           
 45           //@{
 46           /** @name Introduction
 47           
 48           
 49           The APIs documented here are those that are considered frozen and that we expect
 50           not to change within minor releases of Pegasus. It is an objective of Pegasus
 51           to keep these APIs frozen as long as Pegasus remains at the version 2.x revision
 52           level so that providers written for any 2.x Pegasus will run in environments that
 53           use the same or higher level revisions.
 54           
 55           Note that Pegasus does extend and add new APIs to the publically available API set
 56           most releases as new functionality is defined.  Typically these are marked experimental
 57 karl  1.8 for the first release so that developers can be made aware that they may change.  Once
 58           they have been tested and used, the experimental qualifications will be removed and they
 59           become part of the Pegasus public API set.
 60           
 61           REVIEWERS: more on versions.
 62           */
 63           //@{
 64           
 65           
 66           /// @name Common API Characteristics
 67           
 68           //@{
 69            
 70           /** @name Shared Classes.
 71           A shared class consists of a pointer to a shared data block that
 72           contains a reference count and the data. 
 73           
 74           When a shared object is created, it sets the reference count to 1.  The 
 75           reference count is incremented whenever a new object references the shared 
 76           data, and decremented when the object dereferences the shared data.  The 
 77           shared data is deleted when the reference count becomes zero.  
 78 karl  1.8 
 79           When dealing with shared objects, there are two ways of copying an object.  
 80           We usually speak about deep and shallow copies.  A deep copy implies 
 81           duplicating an object.  A shallow copy is a reference copy, i.e.  just a 
 82           pointer to a shared data block.  Making a deep copy can be expensive in 
 83           terms of memory and CPU.  Making a shallow copy is very fast, because it 
 84           only involves setting a pointer and incrementing the reference count.  
 85           
 86           Object assignment (with operator=()) for implicitly and explicitly shared 
 87           objects is implemented using shallow copies.  A deep copy can be made by 
 88           calling a copy() function.  
 89           
 90           The benefit of sharing is that a program does not need to duplicate data 
 91           unnecessarily, which results in lower memory use and less copying of data.  
 92           Objects can easily be assigned, sent as function arguments, and returned 
 93           from functions.  
 94           
 95           Now comes the distinction between explicit and implicit sharing.  Explicit 
 96           sharing means that the programmer must be aware of the fact that objects 
 97           share common data.  Implicit sharing means that the sharing mechanism 
 98           takes place behind the scenes and the programmer does not need to worry 
 99 karl  1.8 about it. 
100           
101           All of the shared classes in Pegasus are explicitly shared.  These classes 
102           have a clone() function that returns a deep copy with a reference count of 1. 
103           */
104            
105           
106           /**  @name Encapsulation
107           REVIEWERS: To be completed
108           */
109            
110           /** @name Error Handling
111           
112           REVIEWERS: TO Be completed
113           */
114           
115            
116           /** @name Threading
117           REVIEWERS: To be completed
118           */ 
119           
120 karl  1.8 
121           /** @name Memory Ownership
122           REVIEWERS:
123           */
124           
125           
126           //@}
127           //@}

128 karl  1.1 

129 karl  1.8 /*

130 karl  1.4 <p>The following are interfaces that are frozen with the 2.3 release of Pegasus:

131 karl  1.5 CONNIE: we will go nuts if we try to do the lists this way.  We need to mark them
132                   in the classes and methods themselves, not in this list.  In reality
133                   all interfaces that are not explicitly marked experimental are frozen.
134                   We should state that.
135                   Need to reference PEP 57 as the authority for this release.

136 karl  1.4 
137           
138           <p>The following are interfaces that are experimental:

139 karl  1.5 CONNIE: We might get by with this experimental list but it will change for each
140                   version of the document.

141 karl  1.4 
142           
143           <p>The following is the complete file hiearchy for this document.

144 karl  1.1    We have tried to keep all file references in only this one place
145              to make modification easier.  In the future, please keep the
146              references here and text in the individual files.

147 karl  1.4   </p>

148 karl  1.8   
149           TODO: We should be getting Pegasus Version information directly from Pegasus, not 
150           just in this text file.

151 karl  1.1    
152           */
153           

154 karl  1.7 /** @name Pegasus CIM Objects and Common Function APIs.
155           	This section defines the Pegasus C++ Classes that represent

156 karl  1.5         the CIM objects and the common functions used by Pegasus 

157 karl  1.6 */
158                       

159 karl  1.1         //@{

160 karl  1.8                 /// @name Classes for CIM Objects and Containers
161                              //@{ 
162                   		//@Include: ../../src/Pegasus/Common/Array.h
163                   		//@Include: ../../src/Pegasus/Common/ArrayInter.h
164                   		//@Include: ../../src/Pegasus/Common/Boolean.h
165                   		//@Include: ../../src/Pegasus/Common/CIMClass.h
166                   		//@Include: ../../src/Pegasus/Common/CIMDateTime.h
167                   		//@Include: ../../src/Pegasus/Common/CIMFlavor.h
168                   		//@Include: ../../src/Pegasus/Common/CIMIndication.h
169                   		//@Include: ../../src/Pegasus/Common/CIMInstance.h
170                   		//@Include: ../../src/Pegasus/Common/CIMMethod.h
171                   		//@Include: ../../src/Pegasus/Common/CIMName.h
172                   		//@Include: ../../src/Pegasus/Common/CIMObject.h
173                   		//@Include: ../../src/Pegasus/Common/CIMObjectPath.h
174                   		//@Include: ../../src/Pegasus/Common/CIMParamValue.h
175                   		//@Include: ../../src/Pegasus/Common/CIMParameter.h
176                   		//@Include: ../../src/Pegasus/Common/CIMProperty.h
177                   		//@Include: ../../src/Pegasus/Common/CIMPropertyList.h
178                   		//@Include: ../../src/Pegasus/Common/CIMQualifier.h
179                   		//@Include: ../../src/Pegasus/Common/CIMQualifierDecl.h
180                   		//@Include: ../../src/Pegasus/Common/CIMQualifierList.h
181 karl  1.8         		//@Include: ../../src/Pegasus/Common/CIMScope.h
182                   		//@Include: ../../src/Pegasus/Common/CIMStatusCode.h
183                   		//@Include: ../../src/Pegasus/Common/CIMType.h
184                   		//@Include: ../../src/Pegasus/Common/CIMValue.h
185                   		//@Include: ../../src/Pegasus/Common/Char16.h
186                   		//@Include: ../../src/Pegasus/Common/Config.h
187                   		//@Include: ../../src/Pegasus/Common/String.h
188                   		//@Include: ../../src/Pegasus/Common/CIMIndication.h
189                   	    //@}
190                           /// @name General Server Functionality Classes
191                              //@{ 
192                   		//@Include: ../../src/Pegasus/Common/OperationContext.h
193                   		//@Include: ../../src/Pegasus/Common/ResponseHandler.h
194                   		//@Include: ../../src/Pegasus/Common/SSLContext.h
195                               //@}
196                          /// @name CIM Object Exceptions
197                               //@{
198                           	//@Include: ../../src/Pegasus/Common/Exception.h
199                               //@}

200 karl  1.3        //@}

201 karl  1.7     /// @name Client Interfaces

202 karl  1.1        //@{

203 karl  1.3 	    /// @name Pegasus Client CIM Operation and Connection Interfaces   

204 karl  1.1 		//@{    
205           		    //@Include: ../../src/Pegasus/Client/CIMClient.h

206 karl  1.5 		    //@Include: ../../src/Pegasus/Client/CIMClientException.h

207 karl  1.1 		//@}

208 karl  1.3 	    /// @name Pegasus Client SLP interfaces   
209           		//@{    
210           		    //@Include: ../../src/Pegasus/Client/CIMServerDiscovery.h

211 karl  1.9 		    //@Include: ../../src/Pegasus/Common/CIMServerDescription.h
212           		    //@Include: ../../src/Pegasus/Common/Attribute.h

213 karl  1.3 		//@}
214           	    /// @name Pegasus Listener Interfaces   
215           		//@{    
216           		    //@Include: ../../src/Pegasus/Listener/CIMListener.h
217           		//@}

218 karl  1.2        //@}

219 karl  1.7    /// @name C++ Provider Interfaces

220 karl  1.2 	//@{

221 karl  1.3 	    /// Pegasus CIM Provider Types and Interfaces
222           	        //@{
223           			//@Include: ../../src/Pegasus/Provider/CIMProvider.h
224           			//@Include: ../../src/Pegasus/Provider/CIMAssociationProvider.h

225 karl  1.5 			//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h

226 karl  1.3 			//@Include: ../../src/Pegasus/Provider/CIMIndicationProvider.h
227           			//@Include: ../../src/Pegasus/Provider/CIMInstanceProvider.h
228           			//@Include: ../../src/Pegasus/Provider/CIMMethodProvider.h
229           	        //@}  	 
230           	    /// Pegasus CIM Provider  CIMOM Handle Callback

231 karl  1.6 	        //@{ 
232           		    //@Include: ../../src/Pegasus/Provider/CIMOMHandle.h
233           	        //@}  	 

234 karl  1.3 	    /// Pegasus CIM Provider Exceptions

235 karl  1.6 	        //@{ 
236           		    //@Include: ../../src/Pegasus/Provider/ProviderException.h
237                           //@}
238           	//@}  	 

239 karl  1.5   /// @name Pegasus Server Indication Consumer
240                   //@{
241                           //@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h
242                   //@}  	 
243           

244 karl  1.8 //@Include: ..\DevManual\definitions.dxx

245 karl  1.5 

246 karl  1.1 /** @name Document References
247           
248           This section will contain references to external documents.
249           

250 karl  1.7 NOTE: Documents we must reference include:
251           	<UL>
252           	<LI>CIM Operations Spec.
253           	<LI>CIM Spec.
254           	</UL>
255           */ 

256 karl  1.1 

257 karl  1.8 //@}

258 karl  1.1