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

130 karl  1.1 

131 karl  1.8 /*

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

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

138 karl  1.4 
139           
140           <p>The following are interfaces that are experimental:

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

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

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

149 karl  1.4   </p>

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

153 karl  1.1    
154           */
155           

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

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

159 karl  1.6 */
160                       

161 karl  1.1         //@{

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

202 karl  1.3        //@}

203 karl  1.7     /// @name Client Interfaces

204 karl  1.1        //@{

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

206 karl  1.1 		//@{    
207           		    //@Include: ../../src/Pegasus/Client/CIMClient.h

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

209 karl  1.1 		//@}

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

213 karl  1.9 		    //@Include: ../../src/Pegasus/Common/CIMServerDescription.h
214           		    //@Include: ../../src/Pegasus/Common/Attribute.h

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

220 karl  1.2        //@}

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

222 karl  1.2 	//@{

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

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

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

233 karl  1.6 	        //@{ 
234           		    //@Include: ../../src/Pegasus/Provider/CIMOMHandle.h
235           	        //@}  	 

236 karl  1.3 	    /// Pegasus CIM Provider Exceptions

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

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

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

247 karl  1.5 

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

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

258 karl  1.1 

259 karl  1.8 //@}

260 karl  1.1