DgnDocumentManager.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/DgnHost.h>


BEGIN_BENTLEY_DGNPLATFORM_NAMESPACE

/*=================================================================================**/
struct DgnDocumentManager;

struct DgnDocumentBrowserDefaults
    {
    WCharCP       m_defaultFilter;        // default file extension to filter in the dialog
    WCharCP       m_suggestedFileName;    // suggested name of file to search for
    WCharCP       m_defaultDirectory;     // directory to begin searching
    WCharCP       m_dialogTitle;          // for the dialog's title bar
    };

struct DgnFolderBrowserDefaults
    {
    WCharCP       m_suggestedFolderName;  // suggested folder to search for
    WCharCP       m_defaultDirectory;     // directory to begin searching
    WCharCP       m_dialogTitle;          // for the dialog's title bar
    };

 /*=================================================================================**/
struct DgnBaseMoniker : RefCountedBase
    {
public:
    enum class SearchStatus
        {   // NB: Must fit into 16 bits
        NotAttempted                =  0, 
        Failed                      =  1, 
        FoundFull                   =  2, 
        FoundComplete               =  3, 
        FoundLogical                =  4, 
        FoundRelative               =  5, 
        FoundEnvironment            =  6, 
        FoundRelativeFileName       =  7, 
        FoundEnvironmentFileName    =  8, 
        FoundInPackage              =  9, 
        };

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

public:
    DGNPLATFORM_EXPORT static WString SearchForFile (SearchStatus& searchStatus, WCharCP inFileName, WCharCP fullPath, WCharCP searchPath, bool fullPathFirst, bool searchAsFolder = false);

    DGNPLATFORM_EXPORT int Compare (DgnBaseMoniker const& anotherMoniker) const;

    DGNPLATFORM_EXPORT int CompareBinary (DgnBaseMoniker const& anotherMoniker) const;

    DGNPLATFORM_EXPORT WString Externalize() const;

    DGNPLATFORM_EXPORT DgnBaseMonikerPtr Clone() const;

    DGNPLATFORM_EXPORT WString ResolveLocation (StatusInt& status) const;

    DGNPLATFORM_EXPORT WString ResolveLocationDisplayName (StatusInt& status) const;

    DGNPLATFORM_EXPORT WString ResolveDisplayName () const;

    DGNPLATFORM_EXPORT WString ResolveURI (StatusInt* status = NULL) const;

    DGNPLATFORM_EXPORT WString GetShortDisplayName() const;

    DGNPLATFORM_EXPORT WString GetPortableName() const;

    DGNPLATFORM_EXPORT bool IsRemote () const;
    };


enum class  RelativePathPreference
    {
    Never             = 0,    // disallow relative paths.
    Allow             = 1,    // if a relative path was passed in by the user, retain it.
    CreateIfPossible  = 2,    // try to make a relative path.
    };

/*=================================================================================**/
struct DgnDocumentMoniker : public DgnBaseMoniker
    {
private:
    virtual void MakeClassAbstract() = 0;
public:

public:
    DGNPLATFORM_EXPORT void SetParentSearchPath (WCharCP newPath);
    DGNPLATFORM_EXPORT WString GetParentSearchPath () const;
    DGNPLATFORM_EXPORT void UpdateSavedFileName (WCharCP fullPath);

    DGNPLATFORM_EXPORT WString GetProviderId () const;

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreateFromRawData (WCharCP portableName, WCharCP fullPath, WCharCP providerID, WCharCP searchPath, bool fullPathFirst, WCharCP customXMLStrings);

    DGNPLATFORM_EXPORT bool     IsEmbedded () const;

    DGNPLATFORM_EXPORT WString  GetPackageName () const;

    DGNPLATFORM_EXPORT Int32    GetEmbeddedIndex ()  const;

    DGNPLATFORM_EXPORT WString  GetEmbeddedName ()  const;

public:

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreateEmpty ();

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr Create (WCharCP externalizedState, WCharCP searchPath=NULL, bool fullPathFirst=false);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreateFromFileName (WCharCP fileName, WCharCP searchPath = NULL);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreatePortableMoniker (WCharCP userEnteredPath, WCharCP fullPath, WCharCP basePath, WCharCP directoryConfigVar, WCharCP searchPath, RelativePathPreference relativePref);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreatePackagedFileMonikerFromFileName (WCharCP packageFilePortableName, WCharCP packageFilefullPath, Int32 embeddedId, WCharCP embedName, WCharCP providerID, bool isRelative, WCharCP searchPath, bool findFullPathFirst, WCharCP customXMLString);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreatePackagedFileMonikerFromPackageFileMoniker (DgnDocumentMonikerR packageMoniker, Int32 embeddedId, WCharCP embedName);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr CreateFromURI (WCharCP uri, WCharCP basePath);

    DGNPLATFORM_EXPORT static DgnDocumentMonikerPtr Clone (DgnDocumentMonikerCR source);


    DGNPLATFORM_EXPORT WString ResolveFileName (StatusInt* status = NULL, bool dontRetryIfFailed = true) const;

    DGNPLATFORM_EXPORT WString GetSavedFileName () const;

    DGNPLATFORM_EXPORT DgnFolderMonikerPtr ResolveParentFolderMoniker (StatusInt* status = NULL) const;

    //Else, a new moniker based on the new search path is returned.
    DGNPLATFORM_EXPORT DgnDocumentMonikerPtr TransformTo (DgnDocumentMonikerCR base) const;
    };

/*=================================================================================**/
struct DgnFolderMoniker : public DgnBaseMoniker
    {
private:
    virtual void MakeClassAbstract() = 0;
public:
public:
    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr CreateFromRawData (WCharCP portableName, WCharCP fullPath, WCharCP providerID, WCharCP searchPath, bool fullPathFirst, WCharCP customXMLStrings);

    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr CreateEmpty ();

    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr Create (WCharCP externalizedState, WCharCP searchPath=NULL, bool fullPathFirst=false);

    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr CreateFromFolderName (WCharCP folderName, WCharCP searchPath = NULL);

    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr CreateFromURI (WCharCP uri, WCharCP basePath);

    DGNPLATFORM_EXPORT static DgnFolderMonikerPtr Clone (DgnFolderMonikerCR source);

    DGNPLATFORM_EXPORT WString ResolveFolderName (StatusInt* status = NULL, bool dontRetryIfFailed=true) const;

    DGNPLATFORM_EXPORT WString GetSavedFolderName () const;

    DGNPLATFORM_EXPORT DgnFolderMonikerPtr ResolveParentFolderMoniker (StatusInt* status = NULL) const;

    //Else, a new moniker based on the new search path is returned.
    DGNPLATFORM_EXPORT DgnFolderMonikerPtr TransformTo (DgnDocumentMonikerCR base) const;
    };

/*=================================================================================**/
struct          DgnDocumentNameProperty : RefCounted<IRefCounted>
    {
    WString     m_name;
    DgnDocumentNameProperty (WCharCP n) : m_name(n) {;}
    static DgnDocumentNameProperty* Create (WCharCP n) {return new DgnDocumentNameProperty(n);}
    }; // DgnDocumentNameProperty

/*=================================================================================**/
struct DgnDocument : RefCounted <IRefCounted>
    {
    enum class OverwriteMode
        {
        Never        = 0,                       
        Always       = 1,                       
        Prompt       = 2,                       
        };

    enum class CreateOptions
        {
        Default                     = 0,        
        SupressFailureNotification  = 1<<0,     
        };

    /*=================================================================================**/
    enum class Access
        {
        None                = 1,            
        ReadOnly            = 2,            
        ExclusiveWrite      = 3,            
        };

    /*=================================================================================**/
    enum class Permissions
        {
        None                = 0,            
        Read                = 1<<0,         
        Write               = 1<<1,         
        ReadWrite           = Read | Write, 
        };

    /*=================================================================================**/
    enum class State
        {
        DoesNotExist        = 0,            
        InDMS               = 1<<0,         
        InFileSystem        = 1<<1,         
        };

    enum class FetchMode
        {
        InfoOnly            = 0,            
        Read                = 1,            
        Write               = 2,            
        };

    enum class FetchOptions
        {
        Default             = 0,            
        Export              = 1<<0,         
        WithSet             = 1<<1,         
        Silent              = 1<<2,         
        ApplicationReserved = 0xff00,       
        };

    enum class PutAction
        {
        Checkin             = 0,            
        UpdateRepository    = 1,            
        Free                = 2,            
        };

    enum class PutOptions
        {
        Default             = 0,            
        LeaveLocal          = 1<<0,         
        PushSet             = 1<<1,         
        Silent              = 1<<2,         
        ApplicationReserved = 0xff00,       
        };

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

   public:


    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateFromMoniker (StatusInt& status, DgnDocumentMonikerR moniker, int defFileId = DEFDGNFILE_ID, FetchMode fetchMode = FetchMode::Read, FetchOptions fetchOptions = FetchOptions::Default);

    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateFromFileName (DgnFileStatus& status, WCharCP fileName, WCharCP searchPath, int defFileId, FetchMode fetchMode, FetchOptions fetchOptions = FetchOptions::Default);

    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateForNewFile (DgnFileStatus& status, WCharCP documentName, WCharCP searchPath, int defFileId, WCharCP wDefaultFileName, OverwriteMode overwriteMode, CreateOptions options = CreateOptions::Default);

    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateNew (DgnFileStatus& status, WCharCP documentName, DgnFolderMonikerR parentFolderMoniker, int defFileId, OverwriteMode overwriteMode, CreateOptions options = CreateOptions::Default);


    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateForEmbeddedFile (WCharCP pseudoFileName);

    DGNPLATFORM_EXPORT static DgnDocumentPtr CreateForLocalFile (WCharCP fileName);


    DGNPLATFORM_EXPORT DgnDocumentMonikerPtr  GetMonikerPtr() const;
    DGNPLATFORM_EXPORT DgnDocumentMonikerCR   GetMoniker() const;


    DGNPLATFORM_EXPORT StatusInt  Fetch (FetchMode mode = FetchMode::Read, FetchOptions options = FetchOptions::Default);

    DGNPLATFORM_EXPORT StatusInt  Put (PutAction action = PutAction::Checkin, PutOptions options = PutOptions::Default, WCharCP comment = NULL);

    DGNPLATFORM_EXPORT StatusInt OnNewFileCreated ();

    DGNPLATFORM_EXPORT bool HasLocalChanges () const;

    DGNPLATFORM_EXPORT StatusInt GetCommitTime (Int64& commitTime) const;

    DGNPLATFORM_EXPORT bool HasServerChanges () const;


    DGNPLATFORM_EXPORT State GetDocState() const;

    DGNPLATFORM_EXPORT bool IsSameFile (DgnDocument const& other) const;

    DGNPLATFORM_EXPORT bool IsInSameRepository (DgnDocumentCP compareDocument) const;

    DGNPLATFORM_EXPORT bool IsInSameRepository (DgnFolderCP compareFolder) const;


    DGNPLATFORM_EXPORT Permissions GetPermissions() const;

    DGNPLATFORM_EXPORT Access GetAvailableAccess() const;

    DGNPLATFORM_EXPORT Access GetMyAccess() const;


    DGNPLATFORM_EXPORT WString GetFileName () const;

    DGNPLATFORM_EXPORT StatusInt SetLocalFileModifyTime (Int64 newTime) const;

    DGNPLATFORM_EXPORT bool IsReadOnly () const;
    DGNPLATFORM_EXPORT void SetReadOnly (bool);






    DGNPLATFORM_EXPORT WString GetNameForRecentFileList () const;

    DGNPLATFORM_EXPORT void SetNameForRecentFileList (WCharCP name);


    };

ENUM_IS_FLAGS (DgnDocument::CreateOptions)
ENUM_IS_FLAGS (DgnDocument::FetchOptions)
ENUM_IS_FLAGS (DgnDocument::PutOptions)
ENUM_IS_FLAGS (DgnDocument::State)
ENUM_IS_FLAGS (DgnDocument::Permissions)


/*=================================================================================**/
struct DgnFolder : RefCounted <IRefCounted>
    {

    enum class CreateOptions
        {
        Default          = 0,       
        AcceptExisting   = 1<<0,    
        };

    /*=================================================================================**/
    enum class Permissions
        {
        None            = 0,        
        Read            = 1<<0,     
        CreateFolder    = 1<<1,     
        CreateDocument  = 1<<2,     
        Delete          = 1<<3,     
        };
private:
    virtual void MakeClassAbstract() = 0;
public:
public:
    DGNPLATFORM_EXPORT DgnFolderMonikerPtr GetMonikerPtr() const;
    DGNPLATFORM_EXPORT DgnFolderMonikerCR GetMoniker() const;

    DGNPLATFORM_EXPORT WString GetFolderName() const;

    DGNPLATFORM_EXPORT DgnBaseMonikerListPtr      GetContents (WCharCP filter = NULL) const;

    DGNPLATFORM_EXPORT DgnFolderMonikerListPtr    GetSubFolders (WCharCP filter = NULL) const;

    DGNPLATFORM_EXPORT DgnDocumentMonikerListPtr  GetDocuments (WCharCP filter = NULL) const;


    DGNPLATFORM_EXPORT bool                       IsDmsFolder () const;

    DGNPLATFORM_EXPORT static DgnFolderPtr  CreateFromMoniker (StatusInt& status, DgnFolderMonikerR moniker);

    DGNPLATFORM_EXPORT static DgnFolderPtr CreateNew (DgnFileStatus& status, WCharCP folderName, DgnFolderMonikerR parentFolderMoniker, CreateOptions options = CreateOptions::Default);

    DGNPLATFORM_EXPORT bool IsInSameRepository (DgnFolderCP compareFolder) const;

    DGNPLATFORM_EXPORT bool IsInSameRepository (DgnDocumentCP compareDocument) const;

    DGNPLATFORM_EXPORT Permissions GetPermissions () const;
    };

ENUM_IS_FLAGS (DgnFolder::CreateOptions)
ENUM_IS_FLAGS (DgnFolder::Permissions)

typedef bvector<DgnBaseMonikerPtr>     T_BaseMonikerList;
typedef bvector<DgnDocumentMonikerPtr> T_DocumentMonikerList;
typedef bvector<DgnFolderMonikerPtr>   T_FolderMonikerList;
/*=============================================================================**/
struct DgnBaseMonikerList : RefCountedBase
    {
    typedef T_BaseMonikerList::const_iterator const_iterator;
    typedef T_BaseMonikerList::iterator iterator;
    typedef T_BaseMonikerList::size_type size_type;

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

    DGNPLATFORM_EXPORT const_iterator begin () const;
    DGNPLATFORM_EXPORT iterator begin ();

    DGNPLATFORM_EXPORT const_iterator end () const;
    DGNPLATFORM_EXPORT iterator end ();

    DGNPLATFORM_EXPORT size_type size () const;

    DGNPLATFORM_EXPORT void Add (DgnBaseMonikerR moniker);
    DGNPLATFORM_EXPORT bool Remove (DgnBaseMonikerR moniker);
    DGNPLATFORM_EXPORT void Clear ();

    DGNPLATFORM_EXPORT static DgnBaseMonikerListPtr Create ();
    };

/*=============================================================================**/
struct DgnDocumentMonikerList : RefCountedBase
    {
    typedef T_DocumentMonikerList::const_iterator const_iterator;
    typedef T_DocumentMonikerList::iterator iterator;
    typedef T_DocumentMonikerList::size_type size_type;

private:
    virtual void MakeClassAbstract() = 0;
public:
public:
    DGNPLATFORM_EXPORT const_iterator begin () const;
    DGNPLATFORM_EXPORT iterator begin ();

    DGNPLATFORM_EXPORT const_iterator end () const;
    DGNPLATFORM_EXPORT iterator end ();

    DGNPLATFORM_EXPORT size_type size () const;

    DGNPLATFORM_EXPORT void Add (DgnDocumentMonikerR moniker);
    DGNPLATFORM_EXPORT bool Remove (DgnDocumentMonikerR moniker);
    DGNPLATFORM_EXPORT void Clear ();
    DGNPLATFORM_EXPORT DgnBaseMonikerListPtr ToDgnBaseMonikerList () const;

    DGNPLATFORM_EXPORT static DgnDocumentMonikerListPtr Create ();
    };

/*=============================================================================**/
struct DgnFolderMonikerList : RefCountedBase
    {
    typedef T_FolderMonikerList::const_iterator const_iterator;
    typedef T_FolderMonikerList::iterator iterator;
    typedef T_FolderMonikerList::size_type size_type;

private:
    virtual void MakeClassAbstract() = 0;
public:
public:
    DGNPLATFORM_EXPORT const_iterator begin () const;
    DGNPLATFORM_EXPORT iterator begin ();

    DGNPLATFORM_EXPORT const_iterator end () const;
    DGNPLATFORM_EXPORT iterator end ();

    DGNPLATFORM_EXPORT size_type size () const;

    DGNPLATFORM_EXPORT void Add (DgnFolderMonikerR moniker);
    DGNPLATFORM_EXPORT bool Remove (DgnFolderMonikerR moniker);
    DGNPLATFORM_EXPORT void Clear ();
    DGNPLATFORM_EXPORT DgnBaseMonikerListPtr ToDgnBaseMonikerList () const;

    DGNPLATFORM_EXPORT static DgnFolderMonikerListPtr Create ();
    };

/*=================================================================================**/
struct DgnDocumentManager : DgnHost::IHostObject
    {
    enum class DeleteOptions
        {
        Default         = 0,        
        AllowRestore    = 1<<0,     
        IncludeSubItems = 1<<1,     
        };

    enum class DgnBrowserStatus
        {
        Success                 = 0, 
        Cancel                  = 1, 
        NoIntegrationLoaded     = 2, 
        };

private:
    virtual void MakeClassAbstract() = 0;
public:
public:
    DGNPLATFORM_EXPORT static DgnDocumentManager& GetManager();

    DGNPLATFORM_EXPORT static void PortableNameFromFullPath (WStringR portableName, WCharCP fullPath, WCharCP basePath, WCharCP dirCfgVar, RelativePathPreference relative);

    DGNPLATFORM_EXPORT static void PortableNameFromUserEnteredFileName (WStringR portableName, WCharCP userEnteredPath, WCharCP fullPath, WCharCP basePath, RelativePathPreference relativePref);


    DGNPLATFORM_EXPORT StatusInt DeleteDocument (DgnDocumentR doc, DeleteOptions options = DeleteOptions::Default);

    DGNPLATFORM_EXPORT StatusInt DeleteFolder (DgnFolderMonikerR folderMoniker, DeleteOptions options = DeleteOptions::Default);

    //@(
    DGNPLATFORM_EXPORT DgnDocumentPtr OpenDocumentDialog (DgnBrowserStatus& status, DgnDocumentBrowserDefaults const & defaults);

    DGNPLATFORM_EXPORT DgnFolderMonikerPtr OpenFolderBrowser (DgnBrowserStatus& status, DgnFolderBrowserDefaults const & defaults);

    };

ENUM_IS_FLAGS (DgnDocumentManager::DeleteOptions)


END_BENTLEY_DGNPLATFORM_NAMESPACE