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 /** @name Pegasus Operations
206 NOTE That this section should probably go away
207 */
208 //@{
209 //@Include: ../../doc/CIMOperations.h
210 //@}
|
211 karl 1.3 /// @name Pegasus Client CIM Operation and Connection Interfaces
|
212 karl 1.1 //@{
213 //@Include: ../../src/Pegasus/Client/CIMClient.h
|
214 karl 1.5 //@Include: ../../src/Pegasus/Client/CIMClientException.h
|
215 karl 1.1 //@}
|
216 karl 1.3 /// @name Pegasus Client SLP interfaces
217 //@{
218 //@Include: ../../src/Pegasus/Client/CIMServerDiscovery.h
219 //@Include: ../../src/Pegasus/Client/CIMServerDescription.h
220 //@Include: ../../src/Pegasus/Client/Attribute.h
221 //@}
222 /// @name Pegasus Listener Interfaces
223 //@{
224 //@Include: ../../src/Pegasus/Listener/CIMListener.h
225 //@}
|
226 karl 1.2 //@}
|
227 karl 1.7 /// @name C++ Provider Interfaces
|
228 karl 1.2 //@{
|
229 karl 1.3 /// Pegasus CIM Provider Types and Interfaces
230 //@{
231 //@Include: ../../src/Pegasus/Provider/CIMProvider.h
232 //@Include: ../../src/Pegasus/Provider/CIMAssociationProvider.h
|
233 karl 1.5 //@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h
|
234 karl 1.3 //@Include: ../../src/Pegasus/Provider/CIMIndicationProvider.h
235 //@Include: ../../src/Pegasus/Provider/CIMInstanceProvider.h
236 //@Include: ../../src/Pegasus/Provider/CIMMethodProvider.h
237 //@}
238 /// Pegasus CIM Provider CIMOM Handle Callback
|
239 karl 1.6 //@{
240 //@Include: ../../src/Pegasus/Provider/CIMOMHandle.h
241 //@}
|
242 karl 1.3 /// Pegasus CIM Provider Exceptions
|
243 karl 1.6 //@{
244 //@Include: ../../src/Pegasus/Provider/ProviderException.h
245 //@}
246 //@}
|
247 karl 1.5 /// @name Pegasus Server Indication Consumer
248 //@{
249 //@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h
250 //@}
251
|
252 karl 1.8 //@Include: ..\DevManual\definitions.dxx
|
253 karl 1.5
|
254 karl 1.1 /** @name Document References
255
256 This section will contain references to external documents.
257
|
258 karl 1.7 NOTE: Documents we must reference include:
259 <UL>
260 <LI>CIM Operations Spec.
261 <LI>CIM Spec.
262 </UL>
263 */
|
264 karl 1.1
|
265 karl 1.8 //@}
|
266 karl 1.1
|