oaPlugInVCInterfaces.h

Go to the documentation of this file.

// *****************************************************************************
// *****************************************************************************
// oaPlugInVCInterfaces.h
//
// This file contains the definitions for Version Control interface classes.
// These include:
//
//  IDMObjectStatus
//      This interface represents a pairing of a DM object with a version
//      control status. This interface is intended to be used in conjunction
//      with the IBaseIter interface to pass collections of object/status pairs
//      between OA and the VC/DM plug-ins. In most cases, OA will allocate the
//      memory for the collection, and the plug-in will iterate the it calling
//      "setStatus" with the actual status of the file in the repository.
//
//  IDMObjectStatus::StatusEnum
//      This enumeration represents a bit-field that can hold all of the status
//      information for a given file. The rules for plug-in implementors and
//      clients are:
//      *   You must be able to deal with a status value that contains a bit
//          that wasn't defined at the time your code was compiled (simple
//          masking will deal with this)
//      *   You can set or clear any flag that was in effect at the time your
//          code was compiled.
//      Rules that the interface will follow:
//      *   The set of bits that are currently defined will not change their
//          values, or be removed, after the interface has been declared as
//          finalized.
//      *   New bits can be added to the set of values but can only occupy
//          unused spaces in the bitfield.
//
//  IDMObjectStatusIter
//      This is a particular expansion of the IIter interface to iterate
//      components via IDMObjectStatus interface pointers.
//
//  IVersion
//      This interface is a generic representation of a version. It is
//      implemented by a version class in the VC plug-in. The functionality
//      that OA DM is interested in is limited to getting the display name (that
//      is, the string representation of the version) and comparing it to other
//      versions. Additional capability can be implemented by the VC plug-in by
//      defining and implementing custom interfaces. These interfaces can be
//      accessed by the VC plug-in when the version object is passed back in
//      to it, for example in the "getFiles" method of the IVersionControl
//      interface.
//
//  IDMObjectVersion
//      This interface is used to represent an association between an IDMObject
//      and an IVersion. It's generally used in conjunction with the
//      IDMObjectVersionIter. The setVersion method is defined for the case
//      where OA DM is requesting the version information for a collection of
//      IDMObjects. Output parameters are used in the "get" methods to enforce
//      the reference counting rules for interfaces.
//
//  IDMObjectVersionIter
//      This is a particular expansion of the IIter interface to iterate
//      components via IDMObjectVersion interface pointers.
//
// IVCMessageObserver
//      This interface is implemented by a client of the Version Control system
//      recieve observer messages resulting from VC operations. The OpEnum
//      represents the values that can be passed to the "operation" parameter
//      of the onMessageOut function and indicate what VC operation generated
//      the message. The "msgType" parameter takes one of the MsgTypeEnum values
//      to indicate to the client severity and disposition information about
//      the message. The return value of onMessageOut is used if the cQueryOk
//      message type is indicated - this allows the client the opportunity to
//      query the user if the operation that the VC system is about to perform
//      is "OK" or should be aborted. This will usualy happen when the VC system
//      finds it needs to perform some destructive action resulting from the
//      requested operation and wants verification that this is ok.
//
//  IVCSystem
//      this interfaces is implemented by an object in the version control
//      system that is capabable of reporting on general attributes of the
//      system. It will generally be a "singleton" object, meaning that the
//      same instance of the object is returned no matter how many times the
//      plug-in system requests it (although this behaviour isn't strictly
//      required).
//
//  IVCPlugIn
//      This is an abstract class which specifies the interface for a version
//      control plug-in. It is used from OA to initialize the VC plug-in. It is
//      typically impemented by a stand-alone version control plug-in that is
//      designed to be aggregated by a separate DM plug-in. A DM plug-in that
//      also directly implements version control would *not* implement this
//      interface - the "init" function on ILib serves to initialize these types
//      of plug-ins
//
//      NOTE that both IVCPlugIn and IVersionControl would be implemented by
//      a the same object in a stand alone version control system. An instance
//      of this component would be created for each instance of a DM plug-in
//      component. This implies that there will be one instance of this
//      component per library that is controlled by this system. The library
//      name for this instance is passed in through the "init" call. This
//      information can be gathered by the vc system in order to be able to
//      respond to the "getControlledLibs" function on the IVCSystem interface.
//
//  IVersionControl
//      This is an abstract class which specifies the interface for version
//      control. This interface is used from OA to access the version control
//      functionality. It can be impemented by DM plug-ins that also implement
//      version control functionality, or by a stand-alone version control
//      plug-in can be aggregated by a DM plug-in.
//
// *****************************************************************************
// Except as specified in the OpenAccess terms of use of Cadence or Silicon
// Integration Initiative, this material may not be copied, modified,
// re-published, uploaded, executed, or distributed in any way, in any medium,
// in whole or in part, without prior written permission from Cadence.
//
//                Copyright 2002-2005 Cadence Design Systems, Inc.
//                           All Rights Reserved.
//
//  $Author: icftcm $
//  $Revision: #1 $
//  $Date: 2010/08/09 $
//  $State: Exp $
// *****************************************************************************
// *****************************************************************************



#if !defined(oaPlugInVCInterfaces_P)
#define oaPlugInVCInterfaces_P



// *****************************************************************************
// Nested includes
// *****************************************************************************
#include "oaPlugInDMInterfaces.h"



// *****************************************************************************
// Declare and define types in the OpenAccess namespace.
// *****************************************************************************
BEGIN_OA_PLUGIN_NAMESPACE



// *****************************************************************************
// Forward Public Class Declarations
// *****************************************************************************
class IDMObject;
class IDMAccess;
class IDMContainer;



// *****************************************************************************
// IDMObjectStatus
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IDMObjectStatus;

class OA_PLUGIN_DLL_API IDMObjectStatus : public IBase {
public:
    enum StatusEnum {
        cControlled = 0x00000001,
        cEditable   = 0x00000002,
        cUpToDate   = 0x00000004,
        cAdded      = 0x00000008,
        cDeleted    = 0x00000010,
        cModified   = 0x00000020,
        cLocked     = 0x00000040,
        cMerged     = 0x00000080,
        cConflict   = 0x00000100,
        cMissing    = 0x00000200,
        cRemote     = 0x00000400,

        cAllStatus  = 0xFFFFFFFF
    };

    virtual void            getDMObject(IDMObject *&object) = 0;
    virtual oa::oaUInt4     getStatus() = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IDMObjectStatusIter
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IDMObjectStatusIter;
typedef IIter<IDMObjectStatus*, &IID_IDMObjectStatusIter> IDMObjectStatusIter;



// *****************************************************************************
// IVersion
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVersion;

class OA_PLUGIN_DLL_API IVersion : public IBase {
public:
    virtual SRef<IString>   getVCSystemName() = 0;
    virtual SRef<IString>   getDisplayName() = 0;
    virtual oa::oaUInt4     compare(IVersion *other) = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IVersionIter
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVersionIter;
typedef IIter<IVersion*, &IID_IVersionIter> IVersionIter;



// *****************************************************************************
// IDMObjectVersion
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IDMObjectVersion;

class OA_PLUGIN_DLL_API IDMObjectVersion : public IBase {
public:
    virtual void            getDMObject(IDMObject *&object) = 0;
    virtual void            getVersion(IVersion *&version) = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IDMObjectVersionIter
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IDMObjectVersionIter;
typedef IIter<IDMObjectVersion*, &IID_IDMObjectVersionIter> IDMObjectVersionIter;



// *****************************************************************************
// IVCMessageObserver
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVCMessageObserver;

class OA_PLUGIN_DLL_API IVCMessageObserver : public IBase {
public:

    virtual oa::oaUInt4     onMessageOut(IDMObject      *object,
                                         oa::oaUInt4    operation,
                                         oa::oaUInt4    msgType,
                                         const char     *text) = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IVCSystem
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVCSystem;

class OA_PLUGIN_DLL_API IVCSystem : public IBase {
public:
    virtual SRef<IString>   getName() = 0;
    virtual bool            testCapability(oa::oaUInt4 capability) = 0;

    virtual void            getControlledLibs(IDMLibIter *&libs) = 0;

    virtual void            newVersionObject(IVersion   *&version,
                                             const char *displayName = NULL) = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IVCPlugIn
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVCPlugIn;

class OA_PLUGIN_DLL_API IVCPlugIn : public IBase {
public:
    virtual bool            init(const char *dmSystemName,
                                 const char *libName,
                                 IDMAccess  *dmAccess,
                                 IAttrIter  *attrs) = 0;

    virtual bool            setAttributes(IAttrIter *attrs) = 0;
    virtual void            getAttributes(IAttrIter *&attrs) = 0;
    virtual void            newVersionObject(IVersion   *&version,
                                             const char *displayName = NULL) = 0;

    static const Guid       &getId();
};



// *****************************************************************************
// IVersionControl
// *****************************************************************************
extern OA_PLUGIN_DLL_API const Guid IID_IVersionControl;

class OA_PLUGIN_DLL_API IVersionControl : public IBase {
public:
    virtual void            getVCSystem(IVCSystem *&system) = 0;

    virtual void            addObserver(IVCMessageObserver *observer) = 0;
    virtual void            removeObserver(IVCMessageObserver *observer) = 0;

    virtual oa::oaUInt4     getStatus(IDMObject     *object,
                                      oa::oaUInt4   mask = IDMObjectStatus::cAllStatus) = 0;
    virtual void            getStatus(IDMObjectStatusIter   *&info,
                                      IDMContainer          *cont,
                                      oa::oaUInt4           depth = oacCellViewFileVCQueryDepth,
                                      oa::oaUInt4           mask = IDMObjectStatus::cAllStatus) = 0;

    virtual void            getControlledObjects(IDMObjectIter  *&objects,
                                                 oa::oaUInt4    depth = oacCellViewFileVCQueryDepth,
                                                 IDMObject      *top = NULL,
                                                 bool           localOnly = false) = 0;

    virtual void            getVersions(IVersionIter    *&versions,
                                        IDMObject       *object) = 0;
    virtual void            getWorkingVersion(IVersion  *&version,
                                              IDMObject *object) = 0;
    virtual void            getWorkingVersions(IDMObjectVersionIter *&objects,
                                               IDMContainer         *cont,
                                               oa::oaUInt4          depth = oacCellViewFileVCQueryDepth) = 0;

    virtual void            update(IVersion     *version,
                                   IDMObject    *object,
                                   bool         recurse = true,
                                   const char   *options = NULL) = 0;

    virtual void            makeEditable(IDMObject  *object,
                                         bool       lock,
                                         bool       recurse = true,
                                         const char *options = NULL) = 0;
    virtual void            cancelEdit(IDMObject    *object,
                                       bool         recurse = true,
                                       const char   *options = NULL) = 0;
    virtual void            commitEdits(IDMObject   *object,
                                        const char  *comment,
                                        bool        recurse = true,
                                        bool        keepEditable = false,
                                        const char  *options = NULL) = 0;

    virtual void            setControlled(IDMObject     *object,
                                          bool          recurse = true,
                                          const char    *options = NULL) = 0;
    virtual void            unsetControlled(IDMObject   *object,
                                            bool        recurse = true,
                                            bool        keepLocal = true,
                                            const char  *options = NULL) = 0;

    static const Guid       &getId();
};



END_OA_PLUGIN_NAMESPACE

#endif

Return to top of page

Copyright © 2002 - 2010 Cadence Design Systems, Inc.
All Rights Reserved.