DesignHistory.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once
#include <DgnPlatform/DgnFileIO/DgnHistory.h>
#include <Bentley/bstdmap.h>


BEGIN_BENTLEY_DGNPLATFORM_NAMESPACE
namespace DgnHistory {

/*=================================================================================**/
/*===========+===============+===============+===============+===============+======*/

// <p>To customize the presentation of historical changes, see \ref Bentley::DgnPlatform::DgnHistory::UI namespace.


class   ElementQueryResultsForModel;
class   ElementQueryResultsForFile;
class   ElementsAsOfQuery;
class   ElementsAsOfAdapter;
class   ElementsAsOfUncommittedAdapter;
class   DesignHistory;
class   DesignHistoryRestore;
class   ElementChangeRecordFilter;
struct  IRevisionCatalogProcessor;

#define ELEMENT_CHANGETYPE_PLACEHOLDER  ElementChangeType::Missing
#define ELEMENT_CHANGETYPE_NO_CHANGE    ElementChangeType::Missing

typedef bvector<RevisionNumber> T_RevisionNumberVectorType;

//=========================================================================
//=========================================================================
class FarElementID
{
    public:
    ModelId         model;
    ElementId       id;

    DGNPLATFORM_EXPORT FarElementID ();
    DGNPLATFORM_EXPORT FarElementID (ModelId, ElementId);
    DGNPLATFORM_EXPORT FarElementID& operator= (const FarElementID&);
    DGNPLATFORM_EXPORT bool          operator< (const FarElementID&) const;
    DGNPLATFORM_EXPORT bool          operator== (const FarElementID&) const;
};

/*=================================================================================**/
class           RevisionNumbersForFile
{

private:
    DgnFileP                    m_file;
    bool                        m_hasRecent;
    bool                        m_isPreparedForQuery;
    T_RevisionNumberVectorType  m_revs;

public:
    DGNPLATFORM_EXPORT RevisionNumbersForFile ();



    DgnFileP        GetDgnFileP() const {return m_file;}

    T_RevisionNumberVectorType const& GetRevisions() const {return m_revs;}

    bool operator == (RevisionNumbersForFile const& c2) const {return m_file==c2.m_file && m_revs==c2.m_revs;}



    DGNPLATFORM_EXPORT
    void AddRevisionNumberForQuery (DgnHistory::RevisionNumber const&);

};

/*=================================================================================**/
class           ElementQueryResult
{
public:



    DGNPLATFORM_EXPORT
    ElementHandle   GetElemHandle () const;

    //  Short-cut method to query model that contains(ed) this element. \see ElementQueryResultsForModel::GetModelId
    DGNPLATFORM_EXPORT
    ModelId         GetModelId () const;

    DGNPLATFORM_EXPORT
    DgnFileP        GetDgnFileP () const;




    DGNPLATFORM_EXPORT
    ElementChangeType GetChangeType () const;

    DGNPLATFORM_EXPORT
    bool            IsPreChangeVersion () const;

    DGNPLATFORM_EXPORT
    ElementQueryResultsForModel* GetResultsForModel() const;


}; // ElementQueryResult

/*=================================================================================**/
struct     IElementQueryResultFilter
{
    virtual bool AcceptElementQueryResult (ElementQueryResult const&) = 0;

    virtual bool AnyClientSideFilter () const = 0;
}; // IElementQueryResultFilter

/*---------------------------------------------------------------------------------**/
struct NopElementQueryResultFilter : IElementQueryResultFilter
    {
    virtual bool AcceptElementQueryResult (ElementQueryResult const&) {return true;}
    virtual bool AnyClientSideFilter () const {return false;}
    };

/*---------------------------------------------------------------------------------**/
struct ElementQueryResultFilterPipeline : IElementQueryResultFilter
    {
    IElementQueryResultFilter&  m_f1;
    IElementQueryResultFilter&  m_f2;

    ElementQueryResultFilterPipeline (IElementQueryResultFilter& f1, IElementQueryResultFilter& f2) : m_f1(f1), m_f2(f2) {;}

    //  IElementQueryResultFilter:
    virtual bool AcceptElementQueryResult (ElementQueryResult const& eq)
        {
        return m_f1.AcceptElementQueryResult(eq) && m_f2.AcceptElementQueryResult(eq);
        }
    virtual bool AnyClientSideFilter() const
        {
        return m_f1.AnyClientSideFilter() || m_f2.AnyClientSideFilter();
        }
    };

typedef bstdmap<ElementId, ElementQueryResult>             T_ElementIdToElementQueryResultMapType;

/*=================================================================================**/
class           ElementQueryResultsForModel
{
    typedef T_ElementIdToElementQueryResultMapType  T_Map;
public:

    typedef ElementQueryResult value_type;

    struct const_iterator : std::iterator<std::forward_iterator_tag, value_type const>
        {
      private:
        friend class  ElementQueryResultsForModel;
        T_Map::const_iterator    m_it;
        const_iterator (T_Map::const_iterator const&);
      public:
        DGNPLATFORM_EXPORT const_iterator&  operator++();   
        DGNPLATFORM_EXPORT value_type const& operator*() const;    
        DGNPLATFORM_EXPORT bool       operator != (const_iterator const &) const; 
        DGNPLATFORM_EXPORT bool       operator == (const_iterator const & r) const {return !(*this != r);}
        };

    DGNPLATFORM_EXPORT
    const_iterator  begin () const;

    DGNPLATFORM_EXPORT
    const_iterator  end () const;

    DGNPLATFORM_EXPORT
    ElementQueryResult const* GetElement (ElementId) const;


    DGNPLATFORM_EXPORT
    ModelId         GetModelId () const;

    DGNPLATFORM_EXPORT
    DgnModelP       GetDgnModelP () const;
    DGNPLATFORM_EXPORT
    DgnFileP        GetDgnFileP () const;

    DGNPLATFORM_EXPORT
    ElementQueryResultsForFile* GetResultsForFile () const;


}; // ElementQueryResultsForModel

typedef bstdmap<ModelId, ElementQueryResultsForModel>           T_ModelIdToElementQueryResultsForModelMapType;

/*=================================================================================**/
class           ElementQueryResultsForFile : public RefCounted<IRefCounted>
{
    typedef T_ModelIdToElementQueryResultsForModelMapType T_Map;

private:
    virtual void MakeClassAbstract() = 0;
public:
public:

    DGNPLATFORM_EXPORT
    DgnFileP        GetDgnFileP () const;

    typedef ElementQueryResultsForModel value_type;

    struct const_iterator : std::iterator<std::forward_iterator_tag, value_type const>
        {
      private:
        friend class ElementQueryResultsForFile;
        T_Map::const_iterator    m_it;
        const_iterator (T_Map::const_iterator const&);
      public:
        DGNPLATFORM_EXPORT const_iterator&  operator++();   
        DGNPLATFORM_EXPORT value_type const& operator*() const;    
        DGNPLATFORM_EXPORT bool       operator != (const_iterator const &) const; 
        DGNPLATFORM_EXPORT bool       operator == (const_iterator const & r) const {return !(*this != r);}
        };

    typedef const_iterator iterator;    

    DGNPLATFORM_EXPORT
    const_iterator  begin () const;

    DGNPLATFORM_EXPORT
    const_iterator  end () const;

    DGNPLATFORM_EXPORT
    const_iterator  FindModelById (ModelId) const;

    DGNPLATFORM_EXPORT
    ElementQueryResultsForModel& GetResultsForModel (ModelId);



    DGNPLATFORM_EXPORT
    ElementChangeType GetChangeType (ModelId, ElementId) const;

    DGNPLATFORM_EXPORT
    ElementQueryResult const* GetElement (ModelId, ElementId) const;

    DGNPLATFORM_EXPORT
    ElementHandle GetElemHandle (ModelId, ElementId) const;

    DGNPLATFORM_EXPORT
    UInt32          ComputeElementCount() const;


}; // ElementQueryResultsForFile

/*=================================================================================**/
class           ElementsAsOfQuery : public   ElementQueryResultsForFile
{
private:
private:
    virtual void MakeClassAbstract() = 0;
public:
public:
}; // ElementsAsOfQuery

/*=================================================================================**/
class           DesignHistory
{
private:
    DgnFileP        m_file;

    /*-----------------------------------------------------------------------------------
        Public Member functions
    -----------------------------------------------------------------------------------*/

public:
    DGNPLATFORM_EXPORT
    explicit
    DesignHistory (DgnFileR);

    DGNPLATFORM_EXPORT
    DesignHistory ();

    DgnFileP        GetDgnFileP() const {return m_file;}

// ##########################################################################

// ##########################################################################

    DGNPLATFORM_EXPORT
static bool         ContainsHistory (DgnFileR);

    DGNPLATFORM_EXPORT
static StatusInt   InitializeHistory
    (
    DgnFileR        file,           
    WChar const* comment          
    );

    DGNPLATFORM_EXPORT
static StatusInt  RemoveHistory (DgnFileR);

    DGNPLATFORM_EXPORT
    StatusInt CombineRevisions
    (
    RevisionNumber const&   start,
    RevisionNumber const&   end,
    CommitInfo const&      parms
    );

    DGNPLATFORM_EXPORT
    StatusInt DeleteEarlyRevisions
    (
    RevisionNumber const&   tooOld
    );

    DGNPLATFORM_EXPORT
    StatusInt       UpdateRevision
    (
    RevisionNumber const& revNo,    
    WChar const*  user,           
    WChar const*  desc            
    );

// ##########################################################################
// ##########################################################################

// ##########################################################################

// ##########################################################################

    DGNPLATFORM_EXPORT
    RevisionNumber  GetTip () const;

    DGNPLATFORM_EXPORT
    RevisionNumber  GetNextPossibleRevisionNumber (DgnHistory::RevisionNumber const& r);

    DGNPLATFORM_EXPORT
    RevisionNumber  GetEarliest () const;

    struct TagDefinition
        {
        WString         tag;                
        RevisionNumber  revNo;  
        };

    DGNPLATFORM_EXPORT
    StatusInt       GetRevisionNumbers
    (
    RevisionNumbersForFile& revNos,                         
    RevisionNumber const&   startRevNo = RevisionNumber(),  
    RevisionNumber const&   endRevNo = RevisionNumber()     
    ) const;

    DGNPLATFORM_EXPORT
    StatusInt       GetRevisions
    (
    T_RevisionInfoVector& revs,                             
    RevisionNumbersForFile& nums,                           
    ElementChangeRecordFilter const* ssfilter = NULL,       
    bool                    removeRejectedRevisions = false 
    ) const;

    DGNPLATFORM_EXPORT
    StatusInt       GetTags
    (
    bvector<TagDefinition>& tags                            
    );

    DGNPLATFORM_EXPORT
    StatusInt       GetTag (DgnHistory::RevisionNumber* revNo, WChar const* tag);

    DGNPLATFORM_EXPORT
    StatusInt       SetTag (WChar const* tag, RevisionNumber const& revNo, bool replaceExisting);

    DGNPLATFORM_EXPORT
    StatusInt       RemoveTag (WChar const* tag);


// ##########################################################################
// ##########################################################################

// ##########################################################################

// ##########################################################################

    DGNPLATFORM_EXPORT
    RefCountedPtr<ElementsAsOfQuery> QueryPreChangeState
    (
    RevisionNumbersForFile const&   range                   
    );

    DGNPLATFORM_EXPORT
    RefCountedPtr<ElementsAsOfQuery> QueryPostChangeState
    (
    RevisionNumbersForFile const&   range                   
    );

    DGNPLATFORM_EXPORT
    StatusInt       QueryElementAsOf
    (
    EditElementHandleR              historicalVersion,      
    ModelId                         modelId,                
    ElementId                       elementId,              
    RevisionNumber const& rev                   
    );


// ##########################################################################
// ##########################################################################

// ##########################################################################

// ##########################################################################

    DGNPLATFORM_EXPORT
    bool            CheckUncommittedChanges (bool force = false) const;

    DGNPLATFORM_EXPORT
    StatusInt       Commit
    (
    RevisionInfo*       result, 
    CommitInfo const&  parms,  
    bool                ignoreVersion = false 
    ) const;

// ##########################################################################
// ##########################################################################


// ##########################################################################


    DGNPLATFORM_EXPORT
    WString         GetRevisionNumberFormat () const;

    DGNPLATFORM_EXPORT
    void            SetRevisionNumberFormat (WChar const*);

    DGNPLATFORM_EXPORT
    WString         FormatRevisionNumber (DgnHistory::RevisionNumber const&);

    DGNPLATFORM_EXPORT
    static
    WString         FormatRevisionNumber (DgnHistory::RevisionNumber const&, WChar const*);

    DGNPLATFORM_EXPORT
    RevisionNumber  ParseRevisionNumber (WChar const* str, WChar const* fmt = NULL) const;

// ##########################################################################

// ##########################################################################
//  Miscellaneous functions, not grouped or highlighted in the doc.

    DGNPLATFORM_EXPORT
static
    StatusInt       ExtractModelElementInfo
    (
    ModelInfoR       pInfo,         // <=
    MSElementDescrCP modelElement,
    DgnFileP         dgnFile
    );

    DGNPLATFORM_EXPORT
    StatusInt       CheckFormatVersion (bool prompt) const;

    DGNPLATFORM_EXPORT
    static
    StatusInt       GetLastError (WStringR details);

}; // DesignHistory

/*---------------------------------------------------------------------------------*/
typedef enum
    {
    HistoryCapabilities_Supported   = 0x0001,
    HistoryCapabilities_Create      = 0x0002,
    HistoryCapabilities_Combine     = 0x0004,
    HistoryCapabilities_Commit      = 0x0008,
    HistoryCapabilities_Browse      = 0x0010,
    HistoryCapabilities_Delete      = 0x0020,
    HistoryCapabilities_Retire      = 0x0040,
    HistoryCapabilities_Trace       = 0x0080,
    HistoryCapabilities_Tag         = 0x0100,
    HistoryCapabilities_ChangeDesc  = 0x0200,
    HistoryCapabilities_AutoUpgrade = 0x0400,
    HistoryCapabilities_ChangeAuthor= 0x0800,
HistoryCapabilities_SetRevisionFormat=0x1000,
    HistoryCapabilities_SetVersion  = 0x2000,
    HistoryCapabilities_ALL         = 0xffff,
    } HistoryCapabilities;

}; // DgnHistory
END_BENTLEY_DGNPLATFORM_NAMESPACE