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
|