A document manager virtualizes access to physical files so that a host program and its applications can be written to work equally well with the native file system or a document management system (DMS). More...
Classes | |
| struct | DgnDocumentBrowserDefaults |
| struct | DgnFolderBrowserDefaults |
| struct | DgnBaseMoniker |
| A DgnBaseMoniker identifies a file or a folder. More... | |
| struct | DgnDocumentMoniker |
| A DgnDocumentMoniker identifies a file. More... | |
| struct | DgnFolderMoniker |
| A DgnFolderMoniker identifies a folder. More... | |
| struct | DgnDocumentNameProperty |
| struct | DgnDocument |
| A DgnDocument represents a file. More... | |
| struct | DgnFolder |
| struct | DgnBaseMonikerList |
| Collection of base monikers. More... | |
| struct | DgnDocumentMonikerList |
| Collection of document monikers. More... | |
| struct | DgnFolderMonikerList |
| Collection of folder monikers. More... | |
| struct | DgnDocumentManager |
| DgnDocumentManager provides services to create, find, open, and save files, either to/from the local file system or to/from a DMS such as ProjectWise if one is in use. More... | |
Enumerations | |
| enum | RelativePathPreference { Never = 0, Allow = 1, CreateIfPossible = 2 } |
A document manager virtualizes access to physical files so that a host program and its applications can be written to work equally well with the native file system or a document management system (DMS).
DgnDocumentManager is an interface presented by an implementation of a document manager. DgnDocumentManager defines methods that allow users to pick files, reopen existing files, create new files, and identify files across sessions. Both DgnPlatform and the host program should use the DgnDocumentManager when accessing (non-temporary) files, regardless of whether a DMS seems important or not.
There is only one document manager in a DgnPlatform session.
The DgnDocumentManager collaborates with the following classes:
A DgnDocumentMoniker identifies an existing file or a file that is to be created. A moniker can be saved between sessions. A moniker is created by a DgnDocumentManager and identifies or will identify a document in the document manager's repository. A ProjectWise/StartPoint moniker contains a document GUID, while a native file system moniker contains a filename. A file system moniker can locate a file by searching paths and config variables.
A DgnDocument represents an existing file or a file that is to be created. A DgnDocument holds a moniker to identify the file. A DgnDocument can represent both a file and other types of files.
A DgnFile holds a DgnDocument to represent a file. A DgnAttachment holds a DgnDocumentMoniker to identify the reference file.
Every function in DgnPlatform that opens, creates, or identifies a file takes a DgnDocument or DgnDocumentMoniker as an argument.
A DgnDocument is meant to represent a file. When an application opens the target file or otherwise creates an object that represents the file's contents, it should call DgnDocument::SetFileObject to associate the file object with the document. Note that a document points to only one file object. The file object should point back to its document (see DgnFile for example). It is up to the application to call SetFileObject when the file is opened and then call SetFileObject with NULL if the file is closed.
A Document Management System (DMS) is a repository for documents of various kinds. The native file system is a simple DMS. ProjectWise is an advanced DMS that supports user access controls and workflow management. In order to work with a document, a program must first get a local copy from the DMS. This operation is called "fetching". After the program has modified the contents of its local copy, it must update the DMS by doing a "put". A DMS may allow multiple users to fetch local copies of the same document. Only one uer can obtain write access to a document. When one user puts changes to the document in the DMS repository, the other users must call fetch in order to refresh their local copies.
A filename is used by legacy host programs to identify a file in the native file system. A filename may be relative or fully qualified. A stored filename is often indequate to find a file after it has been moved or renamed.
A DgnDocumentMoniker identifies a document and its current local copy. A moniker from a DMS like ProjectWise contains a unique identifier of some kind that identifies a document unambiguously. A DgnDocumentMoniker from a DMS like ProjectWise can be used to locate a document and its local copy even after the document has been moved or renamed.
A DgnDocumentMoniker is also portable. It can identify a document in such a way that the reference can be resolved even if the holder of the moniker is moved to a different location or a different file system. Filenames are not really portable, because a relative filename is ambiguous.