pegasus/doc/apidoc/Attic/apidoc.dxx - diff

Return to apidoc.dxx CVS log

Up to [Pegasus] / pegasus / doc / apidoc / Attic

Diff for /pegasus/doc/apidoc/Attic/apidoc.dxx between version 1.1 and 1.10

version 1.1, 2003/10/01 19:02:04

version 1.10, 2005/12/14 18:38:55

Line 1

/** @name Pegasus API Documentation

<CENTER>PEGASUS Public APIs</CENTER>

<CENTER>STATUS: DRAFT FOR REVIEW</CENTER>

<CENTER>version 1.01 30 October 2003, Pegasus 2.3</CENTER>

This document was produced on \date .

This is a working document that contains the interfaces for the Pegasus

CIM Server implementation. This is created by the OpenGroup

Enterprise Management Program Group.

Within this document, you will find the following:

<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.

In addition to this documentation, Pegasus has a Users' Guide that

specifies overview information and how to set up and install Pegasus. In

addition to the manual, the README files contain specific information to

aide you in when working with Pegasus and its documentation.

@memo Public API reference document for the Pegasus CIM Object Manager

implementation.

/* api.dxx - Top Level file for Developer api Documentation.

This file defines the document strucuture and provides the introduction

//@{

/** @name Introduction

$Author$

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.

/* do not change the following Name. Used in the Frame definition.

//@{

If you change it, the HTML Frame must also be changed.

/// @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 Introduction

<CENTER>PEGASUS Public APIs</CENTER>

<CENTER>STATUS: DRAFT FOR REVIEW</CENTER>

/** @name Encapsulation

<CENTER>version 1.01 13 September 2003</CENTER>

REVIEWERS: To be completed

Pegasus is an open source implementation of the manageability environment defined by the DMTF WBEM standards.

/** @name Error Handling

This Document

REVIEWERS: TO Be completed

This is a working document that is the temporary user and developers manual for the Pegasus CIM Server implementation which is being created by the OpenGroup Enterprise Management Program Group.

This manual serves as both a manual for installation and operation of the prototype version of Pegasus and a manual for developing components to attach to Pegasus. In addition to the manual, we keep current working information in a set of README files within the Pegasus distributions. Please consult these files also.

/** @name Threading

REVIEWERS: To be completed

Within this manual you will find:

<UL>

<LI>Information on the installation and operation of the broker and additional components.

<LI> A basic defintion of the architecture and function of Pegasus.

<LI>The current definition of the programming interfaces that Pegasus allows. As these interfaces are stabilized they will be moved from this document to an Open Group specificaton.

<LI>A number of defintions of additional code that is

available to interface with Pegasus as providers, consumers, and services.

</UL>

/** @name Memory Ownership

REVIEWERS:

/* The following is the complete file hiearchy for this document.

//@}

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

in the classes and methods themselves, not in this list. In reality

all interfaces that are not explicitly marked experimental are frozen.

We should state that.

Need to reference PEP 57 as the authority for this release.

The following are interfaces that are experimental:

CONNIE: We might get by with this experimental list but it will change for each

version of the document.

The following is the complete file hiearchy for this document.

We have tried to keep all file references in only this one place

to make modification easier. In the future, please keep the

references here and text in the individual files.

TODO: We should be getting Pegasus Version information directly from Pegasus, not

just in this text file.

TBD: Pegasus API version information

/** @name Pegasus CIM OBjects and General Function APIs

/** @name Pegasus CIM Objects and Common Function APIs.

NOTE: This needs to be reorganized to take into account a structure for these APIs

This section defines the Pegasus C++ Classes that represent

the CIM objects and the common functions used by Pegasus

//@{

/// @name Classes for CIM Objects and Containers

//@{

//@Include: ../../src/Pegasus/Common/Array.h

//@Include: ../../src/Pegasus/Common/ArrayInter.h

//@Include: ../../src/Pegasus/Common/Boolean.h

//@Include: ../../src/Pegasus/Common/CIMClass.h

//@Include: ../../src/Pegasus/Common/CIMClassRep.h

//@Include: ../../src/Pegasus/Common/CIMDateTime.h

//@Include: ../../src/Pegasus/Common/CIMExceptionRep.h

//@Include: ../../src/Pegasus/Common/CIMFlavor.h

//@Include: ../../src/Pegasus/Common/CIMIndication.h

//@Include: ../../src/Pegasus/Common/CIMInstance.h

//@Include: ../../src/Pegasus/Common/CIMInstanceRep.h

//@Include: ../../src/Pegasus/Common/CIMMessage.h

//@Include: ../../src/Pegasus/Common/CIMMethod.h

//@Include: ../../src/Pegasus/Common/CIMMethodRep.h

//@Include: ../../src/Pegasus/Common/CIMName.h

//@Include: ../../src/Pegasus/Common/CIMOMPort.h

//@Include: ../../src/Pegasus/Common/CIMObject.h

//@Include: ../../src/Pegasus/Common/CIMObjectPath.h

//@Include: ../../src/Pegasus/Common/CIMObjectRep.h

//@Include: ../../src/Pegasus/Common/CIMParamValue.h

//@Include: ../../src/Pegasus/Common/CIMParamValueRep.h

//@Include: ../../src/Pegasus/Common/CIMParameter.h

//@Include: ../../src/Pegasus/Common/CIMParameterRep.h

//@Include: ../../src/Pegasus/Common/CIMPredicate.h

//@Include: ../../src/Pegasus/Common/CIMProperty.h

//@Include: ../../src/Pegasus/Common/CIMPropertyList.h

//@Include: ../../src/Pegasus/Common/CIMPropertyRep.h

//@Include: ../../src/Pegasus/Common/CIMQualifier.h

//@Include: ../../src/Pegasus/Common/CIMQualifierDecl.h

//@Include: ../../src/Pegasus/Common/CIMQualifierDeclRep.h

//@Include: ../../src/Pegasus/Common/CIMQualifierList.h

//@Include: ../../src/Pegasus/Common/CIMQualifierNames.h

//@Include: ../../src/Pegasus/Common/CIMQualifierRep.h

//@Include: ../../src/Pegasus/Common/CIMRepositoryBase.h

//@Include: ../../src/Pegasus/Common/CIMScope.h

//@Include: ../../src/Pegasus/Common/CIMStatusCode.h

//@Include: ../../src/Pegasus/Common/CIMType.h

//@Include: ../../src/Pegasus/Common/CIMValue.h

//@Include: ../../src/Pegasus/Common/Char16.h

//@Include: ../../src/Pegasus/Common/Formatter.h

//@Include: ../../src/Pegasus/Common/Config.h

//@Include: ../../src/Pegasus/Common/OperationContext.h

//@Include: ../../src/Pegasus/Common/Queue.h

//@Include: ../../src/Pegasus/Common/Stopwatch.h

//@Include: ../../src/Pegasus/Common/String.h

//@Include: ../../src/Pegasus/Common/CIMIndication.h

//@}

/// @name General Server Functionality Classes

//@{

/// @name Exceptions

//@Include: ../../src/Pegasus/Common/OperationContext.h

//@Include: ../../src/Pegasus/Common/Exception.h

//@Include: ../../src/Pegasus/Common/ResponseHandler.h

//@Include: ../../src/Pegasus/Common/SSLContext.h

//@}

/// @name CIM Object Exceptions

//@{

//@Include: ../../src/Pegasus/Common/Exception.h

//@}

/// @name Client and Provider Interfaces

/// @name Client Interfaces

//@{

/** @name Pegasus Operations

/// @name Pegasus Client CIM Operation and Connection Interfaces

NOTE That this section should probably go away

//@{

//@Include: ../../src/Pegasus/Client/CIMClient.h

//@Include: ../../src/Pegasus/Client/CIMClientException.h

//@}

/// @name Pegasus Client SLP interfaces

//@{

//@Include: ../../doc/CIMOperations.h

//@Include: ../../src/Pegasus/Client/CIMServerDiscovery.h

//@Include: ../../src/Pegasus/Common/CIMServerDescription.h

//@Include: ../../src/Pegasus/Common/Attribute.h

//@}

/// @name Pegasus Client Interfaces

/// @name Pegasus Listener Interfaces

//@{

//@Include: ../../src/Pegasus/Client/CIMClient.h

//@Include: ../../src/Pegasus/Listener/CIMListener.h

//@}

/// @name Pegasus Provider Interfaces

//@}

/// @name C++ Provider Interfaces

//@{

/// Pegasus CIM Provider Types and Interfaces

//@{

//@Include: ../../src/Pegasus/Provider/CIMProvider.h

//@Include: ../../src/Pegasus/Provider/CIMAssociationProvider.h

//@Include: ../../src/Pegasus/Provider/CIMClassProvider.h

//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h

//@Include: ../../src/Pegasus/Provider/CIMIndicationConsumer.h

//@Include: ../../src/Pegasus/Provider/CIMIndicationProvider.h

//@Include: ../../src/Pegasus/Provider/CIMInstanceProvider.h

//@Include: ../../src/Pegasus/Provider/CIMMethodProvider.h

//@Include: ../../src/Pegasus/Provider/CIMNullProvider.h

//@}

/// Pegasus CIM Provider CIMOM Handle Callback

//@{

//@Include: ../../src/Pegasus/Provider/CIMOMHandle.h

//@Include: ../../src/Pegasus/Provider/CIMPropertyProvider.h

//@}

//@Include: ../../src/Pegasus/Provider/CIMQueryProvider.h

/// Pegasus CIM Provider Exceptions

//@{

//@Include: ../../src/Pegasus/Provider/ProviderException.h

//@}

/// @name Pegasus Server Indication Consumer

//@{

//@Include: ../../src/Pegasus/Consumer/CIMIndicationConsumer.h

//@}

//@Include: ..\DevManual\definitions.dxx

/** @name Document References

This section will contain references to external documents.

NOTE: documents we must reference include:

NOTE: Documents we must reference include:

<UL>

<LI>DMTF Specifications

<LI>CIM Operations Spec.

<LI>

<LI>CIM Spec.

</UL/

</UL>

*/ //@Include: references.dxx

//@}

Legend:

Removed from v.1.1
changed lines
	Added in v.1.10

No CVS admin address has been configured