Public Types | List of all members
DgnDocument Struct Referenceabstract

A DgnDocument represents a file. More...

#include <DgnDocumentManager.h>

Inheritance diagram for DgnDocument:
RefCounted< IRefCounted > IRefCounted

Public Types

enum  OverwriteMode { Never = 0, Always = 1, Prompt = 2 }
 Specifies what to do when creating a document if the document already exists. More...
 
enum  CreateOptions { Default = 0, SupressFailureNotification = 1<<0 }
 Options to apply when creating a document. More...
 
enum  Access { None = 1, ReadOnly = 2, ExclusiveWrite = 3 }
 The access level for a document. More...
 
enum  Permissions { None = 0, Read = 1<<0, Write = 1<<1, ReadWrite = Read | Write }
 The permissions for opening a document. More...
 
enum  State { DoesNotExist = 0, InDMS = 1<<0, InFileSystem = 1<<1 }
 The state of the filesystem and DMS copies of a document. More...
 
enum  FetchMode { InfoOnly = 0, Read = 1, Write = 2 }
 
enum  FetchOptions {
  Default = 0, Export = 1<<0, WithSet = 1<<1, Silent = 1<<2,
  ApplicationReserved = 0xff00
}
 
enum  PutAction { Checkin = 0, UpdateRepository = 1, Free = 2 }
 
enum  PutOptions {
  Default = 0, LeaveLocal = 1<<0, PushSet = 1<<1, Silent = 1<<2,
  ApplicationReserved = 0xff00
}
 

Public Member Functions

Access to the document's moniker
DGNPLATFORM_EXPORT
DgnDocumentMonikerPtr 
GetMonikerPtr () const
 Get a Ptr to the moniker that identifies this document. More...
 
DGNPLATFORM_EXPORT
DgnDocumentMonikerCR 
GetMoniker () const
 Get reference to the moniker that identifies this document. More...
 
Methods to synchronize the local copy of the document with the DMS repository
DGNPLATFORM_EXPORT StatusInt Fetch (FetchMode mode=FetchMode::Read, FetchOptions options=FetchOptions::Default)
 Create a local copy of the document from the master copy in the DMS. More...
 
DGNPLATFORM_EXPORT StatusInt Put (PutAction action=PutAction::Checkin, PutOptions options=PutOptions::Default, WCharCP comment=NULL)
 Use the local copy of the document to update the master copy of the document in the DMS. More...
 
DGNPLATFORM_EXPORT StatusInt OnNewFileCreated ()
 Call this method after creation of a new file is finished. More...
 
DGNPLATFORM_EXPORT bool HasLocalChanges () const
 Has the document been changed locally since it was last put? More...
 
DGNPLATFORM_EXPORT StatusInt GetCommitTime (Int64 &commitTime) const
 Get the time of the last commit of this document to the DMS. More...
 
DGNPLATFORM_EXPORT bool HasServerChanges () const
 Has the document been changed in the DMS since it was fetched or most recently put? More...
 
Methods to query the state of the document in the DMS repository
DGNPLATFORM_EXPORT State GetDocState () const
 Query if the this document exists in the file system only, in the repository, or both. More...
 
DGNPLATFORM_EXPORT bool IsSameFile (DgnDocument const &other) const
 Query if this document and other refer to the same file. Calls DgnBaseMoniker::Compare. More...
 
DGNPLATFORM_EXPORT bool IsInSameRepository (DgnDocumentCP compareDocument) const
 Check to see whether the specified DgnDocument resides in the same repository as this DgnDocument of the file, and optionally prompt the user for whether to overwrite the file or not. More...
 
DGNPLATFORM_EXPORT bool IsInSameRepository (DgnFolderCP compareFolder) const
 Check to see whether the specified DgnFolder resides in the same repository as this DgnDocument of the file, and optionally prompt the user for whether to overwrite the file or not. More...
 
Methods to query access privileges and permissions granted for the document in the DMS repository.
DGNPLATFORM_EXPORT Permissions GetPermissions () const
 Get the permissions of this DMS document (for the current user account). More...
 
DGNPLATFORM_EXPORT Access GetAvailableAccess () const
 Get the highest available access for this client. More...
 
DGNPLATFORM_EXPORT Access GetMyAccess () const
 Get the current access for this client. More...
 
Methods to query and set properties of the local copy of the document.
DGNPLATFORM_EXPORT WString GetFileName () const
 Get the stored filename for the document, if it has one, or the portable name if not. More...
 
DGNPLATFORM_EXPORT StatusInt SetLocalFileModifyTime (Int64 newTime) const
 Set the time of the last modification to the local copy of this document. More...
 
DGNPLATFORM_EXPORT bool IsReadOnly () const
 Is the document marked for read-only access in the DMS? More...
 
DGNPLATFORM_EXPORT void SetReadOnly (bool)
 Mark the document for read-only access in the DMS. More...
 
Name for file list
DGNPLATFORM_EXPORT WString GetNameForRecentFileList () const
 Query the name for the recent file list, if any, that is assigned to this document. More...
 
DGNPLATFORM_EXPORT void SetNameForRecentFileList (WCharCP name)
 Set or clear the name for the recent file list for this document. More...
 
- Public Member Functions inherited from RefCounted< IRefCounted >
void * operator new (size_t size)
 
void operator delete (void *rawMemory, size_t size)
 
UInt32 AddRef () const
 
UInt32 Release () const
 
 RefCounted ()
 
 RefCounted (RefCounted const &rhs)
 
RefCountedoperator= (RefCounted const &rhs)
 
UInt32 GetRefCount () const
 

Static Public Member Functions

Methods to create document objects
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateFromMoniker (StatusInt &status, DgnDocumentMonikerR moniker, int defFileId=DEFDGNFILE_ID, FetchMode fetchMode=FetchMode::Read, FetchOptions fetchOptions=FetchOptions::Default)
 Create a new DgnDocument object from a moniker object that refers to an existing file. More...
 
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateFromFileName (DgnFileStatus &status, WCharCP fileName, WCharCP searchPath, int defFileId, FetchMode fetchMode, FetchOptions fetchOptions=FetchOptions::Default)
 Create a DgnDocument object that represents an existing file in the native file system. More...
 
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateForNewFile (DgnFileStatus &status, WCharCP documentName, WCharCP searchPath, int defFileId, WCharCP wDefaultFileName, OverwriteMode overwriteMode, CreateOptions options=CreateOptions::Default)
 Create a new DgnDocument object to represent a new file in the native file system. More...
 
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateNew (DgnFileStatus &status, WCharCP documentName, DgnFolderMonikerR parentFolderMoniker, int defFileId, OverwriteMode overwriteMode, CreateOptions options=CreateOptions::Default)
 Create a new document in DMS. More...
 
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateForEmbeddedFile (WCharCP pseudoFileName)
 Create a DgnDocument object that represents an embedded file. More...
 
static DGNPLATFORM_EXPORT
DgnDocumentPtr 
CreateForLocalFile (WCharCP fileName)
 Create a DgnDocument object that represents a file in the native file system, without attempting to link it to a document in the DMS. More...
 

Additional Inherited Members

- Protected Member Functions inherited from RefCounted< IRefCounted >
virtual ~RefCounted ()
 
- Protected Member Functions inherited from IRefCounted
virtual ~IRefCounted ()
 
void * operator new (size_t size)
 
void operator delete (void *rawMemory, size_t size)
 

Detailed Description

A DgnDocument represents a file.

The file may or may not exist.

Remarks
Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib

Member Enumeration Documentation

enum Access
strong

The access level for a document.

Remarks
Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib
Enumerator
None 

No access is available.

ReadOnly 

Read-only access.

ExclusiveWrite 

Exclusive write access.

enum CreateOptions
strong

Options to apply when creating a document.

Enumerator
Default 

no special options

SupressFailureNotification 

do not send user notifications in case of failure

enum FetchMode
strong
Enumerator
InfoOnly 

Don't fetch file, retrieve just information (e.g. file name/location)

Read 

Fetch file for reading (Copy Out)

Write 

Fetch file for writing (Check Out)

enum FetchOptions
strong
Enumerator
Default 

Honor settings for repository and user.

Export 

Export the document.

WithSet 

Fetch associated items.

Silent 

Don't show dialogs.

ApplicationReserved 

Application reserved values.

enum OverwriteMode
strong

Specifies what to do when creating a document if the document already exists.

Enumerator
Never 

Do not replace an existing file.

Always 

Always try to replace an existing file.

Prompt 

Prompt the user to replace an existing file.

enum Permissions
strong

The permissions for opening a document.

Remarks
Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib
Enumerator
None 

No permissions granted.

Read 

Read-only permission.

Write 

Write permission.

ReadWrite 

Read-write permission.

enum PutAction
strong
Enumerator
Checkin 

Check in the document.

UpdateRepository 

Update the document in the repository.

Free 

Delete the local file copy of the document.

enum PutOptions
strong
Enumerator
Default 

Honor settings for repository and user.

LeaveLocal 

Leave local file copy.

PushSet 

Push associated items that are checked out (?)

Silent 

Don't show dialogs.

ApplicationReserved 

Application reserved values.

enum State
strong

The state of the filesystem and DMS copies of a document.

Remarks
Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib
Enumerator
DoesNotExist 

Does not exist in a DMS, no local file.

InDMS 

Exists in DMS.

InFileSystem 

Local file exists.

Member Function Documentation

static DGNPLATFORM_EXPORT DgnDocumentPtr CreateForEmbeddedFile ( WCharCP  pseudoFileName)
static

Create a DgnDocument object that represents an embedded file.

Remarks
Does not check that the embedded storage exists.
This method does not create an embedded storage or a document in the DMS repository. It creates a DgnDocument object in memory that represents an embedded storage.
static DGNPLATFORM_EXPORT DgnDocumentPtr CreateForLocalFile ( WCharCP  fileName)
static

Create a DgnDocument object that represents a file in the native file system, without attempting to link it to a document in the DMS.

Remarks
Does not check that the file exists.
This method does not create a disk file. It creates a DgnDocument object in memory that represents an existing disk file.
static DGNPLATFORM_EXPORT DgnDocumentPtr CreateForNewFile ( DgnFileStatus status,
WCharCP  documentName,
WCharCP  searchPath,
int  defFileId,
WCharCP  wDefaultFileName,
OverwriteMode  overwriteMode,
CreateOptions  options = CreateOptions::Default 
)
static

Create a new DgnDocument object to represent a new file in the native file system.

Optionally, test for the existence of a local file by the same name, and optionally prompt the user for whether to overwrite the file or not.

NB: The caller should call DgnDocument::OnNewFileCreated after creating the new disk file.

Returns
a DgnDocument that represents the file. On failure, NULL is Returned.
Parameters
[out]statusIf NULL is returned, this gives an indication of why. The possible values are:
  • DGNFETCH_STATUS_FileAlreadyExists - the file already exists and overwrite was not specified.
  • DGNFETCH_STATUS_AccessViolation - the file already exists and could not be overwritten.
[in]documentNameThe name for the file or document created
[in]searchPathThe base path used for relative searches or NULL to ignore this parameter. A search path may contain one or more configuration variables, directory paths, and/or file paths.
[in]defFileIdIdentifies the type of file being created.
[in]wDefaultFileNameSpecifies the default drive, path, filename, and/or extension to be used when locating an existing file from a partially specified name.
[in]overwriteModeSpecifies what to do if the document already exists.
[in]optionsCreate Options.
Remarks
This method does not create a disk file or a document in the DMS repository. It creates a DgnDocument object in memory to represent a new file.
After writing out the disk file for the new document, the caller must call DgnDocument::OnNewFileCreated.
static DGNPLATFORM_EXPORT DgnDocumentPtr CreateFromFileName ( DgnFileStatus status,
WCharCP  fileName,
WCharCP  searchPath,
int  defFileId,
FetchMode  fetchMode,
FetchOptions  fetchOptions = FetchOptions::Default 
)
static

Create a DgnDocument object that represents an existing file in the native file system.

This is just a short cut for the following:

DgnDocumentMonikerPtr moniker = CreateMonikerFromFileName (fileName, NULL, envvar);
DgnDocumentP openedDoc = CreateFromMoniker (status, *moniker, defFileId, fetchMode, fetchOptions);
Returns
A DgnDocument object that represents the file. If the file cannot be found or cannot be accessed, NULL is returned.
Parameters
[out]statusIf NULL is returned, this gives an indication of why:
  • DGNFETCH_STATUS_FileNotFound: the file could not be found
[in]fileNameThe name of the existing file.
[in]searchPathThe base path used for relative searches or NULL to ignore this parameter. A search path may contain one or more configuration variables, directory paths, and/or file paths.
[in]defFileIdIdentifies the type of file being opened.
[in]fetchModeSpecifies the access that should be requested when fetching the DgnDocument from the DMS.
[in]fetchOptionsFetch options
Remarks
This method does not open a disk file. It creates a DgnDocument object in memory that identifies and represents an existing disk file that the caller can open if desired.
static DGNPLATFORM_EXPORT DgnDocumentPtr CreateFromMoniker ( StatusInt status,
DgnDocumentMonikerR  moniker,
int  defFileId = DEFDGNFILE_ID,
FetchMode  fetchMode = FetchMode::Read,
FetchOptions  fetchOptions = FetchOptions::Default 
)
static

Create a new DgnDocument object from a moniker object that refers to an existing file.

This method would typically be used by code that intends to read or write data from the document. The document manager will optionally fetch the document from the repository.

Returns
a DgnDocument that represents the existing document. On failure, NULL is returned.
Parameters
[out]statusIf NULL is returned, this gives an indication of why:
  • DGNFETCH_STATUS_FileNotFound: the file could not be found
  • ERROR: the moniker is invalid
[in]monikerThe moniker string which specifies the location and name of the document.
[in]defFileIdGives the caller a way to tell the document manager about the intended use of this document. See the list of ids in deffiles.h
[in]fetchModeSpecifies the access that should be requested when fetching the DgnDocument from the DMS.
[in]fetchOptionsFetch options
Remarks
This method does not open a disk file. It creates a DgnDocument object in memory that identifies and represents an existing disk file that the caller can open if desired.
static DGNPLATFORM_EXPORT DgnDocumentPtr CreateNew ( DgnFileStatus status,
WCharCP  documentName,
DgnFolderMonikerR  parentFolderMoniker,
int  defFileId,
OverwriteMode  overwriteMode,
CreateOptions  options = CreateOptions::Default 
)
static

Create a new document in DMS.

Returns DgnDocument object if the document was created.

Parameters
[out]statusIf NULL is returned, this gives an indication why.
[in]documentNameThe name for the new document.
[in]parentFolderMonikerThe moniker of the parent folder under which this new folder should be created.
[in]defFileIdIdentifies the type of file being created.
[in]overwriteModeSpecifies what to do if the document already exists.
[in]optionsCreate Options.

Create a local copy of the document from the master copy in the DMS.

Remarks
If the DMS is the native file system, this method does nothing and returns SUCCESS.
DGNPLATFORM_EXPORT Access GetAvailableAccess ( ) const

Get the highest available access for this client.

Available access is the highest access I can get right now. For example, if the document is out to someone else, I have read-only access; if it is IN, I have the access based on the document permissions.

Remarks
If the DMS is the native file system, this method will always return Access::ExclusiveWrite.
DGNPLATFORM_EXPORT StatusInt GetCommitTime ( Int64 commitTime) const

Get the time of the last commit of this document to the DMS.

Remarks
If the DMS is the native file system, this method returns the last time the file was modified.
DGNPLATFORM_EXPORT State GetDocState ( ) const

Query if the this document exists in the file system only, in the repository, or both.

Remarks
If the DMS is the native file system, this method returns an indication of whether the file exists on disk or not.
DGNPLATFORM_EXPORT WString GetFileName ( ) const

Get the stored filename for the document, if it has one, or the portable name if not.

See also
DgnDocumentMoniker::ResolveFileName

Get reference to the moniker that identifies this document.

DGNPLATFORM_EXPORT DgnDocumentMonikerPtr GetMonikerPtr ( ) const

Get a Ptr to the moniker that identifies this document.

DGNPLATFORM_EXPORT Access GetMyAccess ( ) const

Get the current access for this client.

My access is the access I have as a user right now. For example, if the document is checked out to me, I have exclusive write access; if the document is IN, I have no access.

Remarks
If the DMS is the native file system, this method will always return Access::ExclusiveWrite.
DGNPLATFORM_EXPORT WString GetNameForRecentFileList ( ) const

Query the name for the recent file list, if any, that is assigned to this document.

DGNPLATFORM_EXPORT Permissions GetPermissions ( ) const

Get the permissions of this DMS document (for the current user account).

Remarks
If the DMS is the native file system, this method returns the read-only or read-write status of the disk file if found.
DGNPLATFORM_EXPORT bool HasLocalChanges ( ) const

Has the document been changed locally since it was last put?

Remarks
If the DMS is the native file system, this method will always return false.
DGNPLATFORM_EXPORT bool HasServerChanges ( ) const

Has the document been changed in the DMS since it was fetched or most recently put?

Remarks
If the DMS is the native file system, this method will always return false.
DGNPLATFORM_EXPORT bool IsInSameRepository ( DgnDocumentCP  compareDocument) const

Check to see whether the specified DgnDocument resides in the same repository as this DgnDocument of the file, and optionally prompt the user for whether to overwrite the file or not.

Returns
true if both are in the same repository, false if not
Parameters
[in]compareDocumentA pointer to a DgnDocument object used for comparison
DGNPLATFORM_EXPORT bool IsInSameRepository ( DgnFolderCP  compareFolder) const

Check to see whether the specified DgnFolder resides in the same repository as this DgnDocument of the file, and optionally prompt the user for whether to overwrite the file or not.

Returns
true if both are in the same repository, false if not
Parameters
[in]compareFolderA pointer to DgnFolder object used for comparison
DGNPLATFORM_EXPORT bool IsReadOnly ( ) const

Is the document marked for read-only access in the DMS?

Remarks
If the DMS is the native file system, this queries the flag that was set by calling SetIsReadOnly to indicate that that file should be opened read-only. You must call DgnFile::IsReadOnly to query if the file was actually opened read-only.
DGNPLATFORM_EXPORT bool IsSameFile ( DgnDocument const &  other) const

Query if this document and other refer to the same file. Calls DgnBaseMoniker::Compare.

DGNPLATFORM_EXPORT StatusInt OnNewFileCreated ( )

Call this method after creation of a new file is finished.

This tells the document manager to complete document creation started with DgnDocument::CreateForNewFile or DgnDocument::CreateNew. In case of DMS, the file would be stored to the remote repository. After this method you should assume the document is in the FetchMode::InfoOnly access mode. If the created file needs to be accessed locally request the desired access via DgnDocument::Fetch. Note that the original file name can possibly be modified (DMS case). To retrieve the current file name call DgnDocument::GetFileName. Don't call this method for a temporary local file.

Use the local copy of the document to update the master copy of the document in the DMS.

Remarks
If the DMS is the native file system, this method does nothing and returns SUCCESS.
DGNPLATFORM_EXPORT StatusInt SetLocalFileModifyTime ( Int64  newTime) const

Set the time of the last modification to the local copy of this document.

DGNPLATFORM_EXPORT void SetNameForRecentFileList ( WCharCP  name)

Set or clear the name for the recent file list for this document.

DGNPLATFORM_EXPORT void SetReadOnly ( bool  )

Mark the document for read-only access in the DMS.


The documentation for this struct was generated from the following file:

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.