Programming Reference

ODDocument

     

Class Definition File

Document.idl

Class C++ Binding

Document.xh

Class Hierarchy 

SOMObject
   ODObject
      ODRefCntObject
         ODDocument

Description

An object of the ODDocument class is used to represent a document and manipulate its drafts.

The ODDocument class is implemented differently for different platforms and storage mechanism.

The set of related classes, ODContainer, ODDocument, ODDraft, and ODStorageUnit, is called a container suite. Container-suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels.

An OpenDoc container can contain one or more documents. Each document, in turn, can contain one or more drafts, and each draft can contain one or more storage units. Each container, document, draft and storage unit has a unique ID.

The document shell or container application creates or accesses a document object by calling the AcquireDocument method of the appropriate container. You can obtain a reference to the document's container by calling its GetContainer method. Each document object has a unique name within its container. The GetName and SetName methods retrieve and set this name.

Because each draft corresponds to a version of its document, a document can be defined as a collection of version-drafts. The document shell or container application creates or accesses drafts by calling the document's CreateDraft, AcquireDraft, and AcquireBaseDraft methods. Other ODDocument methods copy drafts between documents and discard unwanted drafts. ODDocument is responsible for ensuring that there is only one draft object for each draft in the document.

Each draft as permissions that control access to it. Drafts are created with exclusive read/write permissions. The document shell or container application can change a draft's permissions when it calls the document's AcquireDraft and AcquireBaseDraft methods. Access to a draft is guaranteed to be exclusive only if the draft has exclusive read/write permissions.

Drafts are linearly derived in a document. The drafts of a document can be thought of as a stack; the oldest draft, called the base draft, is at the bottom of the stack, and the most recent draft is at the top. A given draft is said to be above an earlier draft and below a more recent draft. The stack of drafts in the document is called the document's draft history. Although part editors can access any draft of a document, only the most recent (topmost) draft can be modified; all earlier drafts are read only.

For more information on how ODDocument and other container-suite classes are used, see the chapters on storage and OpenDoc runtime features in the OpenDoc Programming Guide.

Note:

Parts are rarely involved with the manipulation of drafts in a document. OpenDoc and the user cooperate to create and manipulate drafts.

Methods

The methods defined by the ODDocument class include:

Overridden Methods

There are no methods overridden by the ODDocument class.

     

AcquireBaseDraft

This method is called by the document shell or container application to retrieve a reference to the base draft of this document with its permissions set as specified.

Signature 
ODDraft *AcquireBaseDraft (ODDraftPermissions perms)

Parameters

perms  (ODDraftPermissions)  -  input 

The target permissions for the draft. Valid permissions are dependent on the container suite; the Bento container suite supports the following values:
kODDPExclusiveWrite Exclusive read/write
kODDPReadOnly Read-only

Returns

rv  (ODDraft *)  -  returns 

A reference to the base draft of this document.

Remarks

This method returns a reference to the base draft for this document with its permissions set as specified in the perms parameter. If this document does not already have a base draft, this method creates, initializes, stores the base draft.

The permissions specified by the perms parameter must be consistent with how other objects access the base draft. The restrictions placed on the permissions depend on the container suite. With the Bento container suite, the permissions may be set to exclusive read/write (kODDPExclusiveWrite) if the base draft is the document's only draft and no other object already has access to the draft (read-only or exclusive read/write). The permissions can be set to read-only (kODDPReadOnly) if no object has exclusive read/write access to the draft.

This method increments the reference count of the returned draft object. When the caller has finished using that draft object, it should call the draft's Release method.

Exception Handling
kODErrInvalidPermissions The base draft is not accessible with the specified permissions.

Related Methods

     

AcquireDraft

This method is called by the document shell or container application to retrieve a reference to the specified draft of this document with its permissions set as specified.

Signature 
ODDraft *AcquireDraft (ODDraftPermissions perms,
                       ODDraftID id,
                       ODDraft *draft,
                       ODPositionCode posCode,
                       ODBoolean release)

Parameters

perms  (ODDraftPermissions)  -  input 

The target permissions for the draft. Valid permissions are dependent on the container suite; the Bento container suite supports the following values:
kODDPExclusiveWrite Exclusive read/write
kODDPReadOnly Read-only

id  (ODDraftID)  -  input 

The ID of the desired draft or kODNULLID to use the draft and posCode parameters to identify the desired draft.

draft  (ODDraft *)  -  input 

A reference to the draft object used with the posCode parameter to identify the desired draft or kODNULL to use the id parameter to identify the desired draft.

posCode  (ODPositionCode)  -  input 

The position, relative to the draft parameter, of the desired draft in this document's draft history. This parameter can also be set to one of the following values:
kODPosFirstAbove The draft above, immediately more recent than, the specified draft.
kODPosLastAbove The draft below, immediately previous to, the specified draft.
kODLastAbove The draft above, immediately more recent than, the specified draft.
kODLastBelow The draft below, immediately previous to, the specified draft.
kODPosSame The desired draft is the draft object specified by the draft parameter.
kODPosUndefined The id parameter is to be used to identify the desired draft.
kODPosTop The top, most recent, draft in the document.

release  (ODBoolean)  -  input 

A flag indicating whether the specified draft should be released after the desired draft is returned. This flag is used only when the draft and posCode parameters are used to identify the desired draft.
kODTrue The specified draft should be released after the desired draft is returned.
kODFalse The draft should not be released.

Returns

rv  (ODDraft *)  -  returns 

A reference to the specified draft object.

Remarks

If the id parameter is not null, this method uses that parameter to identify the desired draft, and the draft, posCode, and release parameters are ignored.

If the id parameter is kODNULLID, this method uses the draft and posCode parameters to identify the desired draft. When the posCode parameter is kODPosSame, the desired draft is the draft object specified by its draft parameter, and this method changes the permissions of that draft. If the release parameter is kODTrue, and if the desired draft can be returned, the draft passed in the draft parameter is released.

Once the desired draft is identified, this method returns a reference to that draft object with its permissions set as specified in the perms parameter. The specified permissions must be consistent with how other objects access the desired draft. The restrictions placed on the permissions depend on the container suite. With the Bento container suite, the permissions can be set to exclusive read/write (kODDPExclusiveWrite) if the desired draft is the document's most recent draft and no other object already has access to the draft (read-only or exclusive read/write). The permissions may be set to read-only (kODDPReadOnly) if no object has exclusive read/write access to the draft.

This method increments the reference count of the returned draft object. When the caller has finished using that draft object, it should call the draft's Release method.

Exception Handling

kODErrCannotChangePermissions

The draft's permissions cannot be changed if the draft is retrieved with different permissions.

kODErrInvalidDraftID

The specified draft ID is invalid.

kODErrInvalidPermissions

The target permissions are invalid.

kODErrRefCountNotEqualOne

An attempt was made to change the permissions for a draft while other objects have references to it.

kODErrUnsupportedPosCode

The specified position code is not supported.

Related Methods

     

CollapseDrafts

This method is called by the document shell or container application to remove a specified range of empty drafts from this document.

Signature 
ODDocument *CollapseDrafts (ODDraft *from, ODDraft *to)

Parameters

from  (ODDraft *)  -  input 

A reference to the first (most recent) draft in the range.

to  (ODDraft *)  -  input 

A reference to the last (oldest) draft in the range or kODNULL to set the draft immediately previous to (below) the from draft.

Returns

rv  (ODDocument *)  -  returns 

A reference to this document with the specified drafts removed.

Remarks

When successful, this method removes all the drafts between the from draft (inclusive) and the to draft (exclusive), and returns a reference to the amended document object. This method maintains the appropriate draft topology for this document. After successful execution, the from draft is no longer a valid draft object.

For this method to be successful, the following conditions must be met:

Before calling this method, the document shell or container application can call the SaveToAPrevDraft method to consolidate the changes in a range of drafts.

Exception Handling

kODErrCannotCollapseDrafts

The from draft is not a more recent draft than the to draft.

kODErrNonEmptyDraft

There are nonempty drafts between the from draft (inclusive) and the to draft (exclusive).

kODErrOutstandingDraft

There are outstanding drafts between the from draft (exclusive) and the to draft (exclusive) or the from draft has a reference count greater than 1.

kODErrIllegalNullDraftInput

The from parameter is null.

Related Methods

     

CreateDraft

This method is called by the document shell or container application to create a new most-recent draft object in this document.

Signature 
ODDraft *CreateDraft (ODDraft *below, ODBoolean releaseBelow)

Parameters

below  (ODDraft *)  -  input 

A reference to the most-recent draft for this document.

releaseBelow  (ODBoolean)  -  input 

A flag indicating whether the specified draft should be released.
kODTrue The specified draft should be released.
kODFalse The specified draft should not be released.

Returns

rv  (ODDraft *)  -  returns 

A reference to the newly created draft object with exclusive read/write permissions.

Remarks

This method creates, initializes, and returns a new draft object, which is the most recent draft of this document. To create the base draft of the document, the document shell calls the AcquireBaseDraft method instead.

If the releaseBelow parameter is kODTrue, this document removes its reference to the specified draft by calling that draft's Release method.

This method initializes the reference count of the returned draft. When the caller has finished using that draft, it should call the draft's Release method.

Exception Handling

kODErrInvalidBelowDraft

The document has previous drafts, and the below draft is not the most recent draft of the document.

kODErrInvalidPermissions

The below draft has exclusive read/write permissions, and the releaseBelow parameter is kODFalse; this combination is illegal because only the most-recent draft can have write permission.

Related Methods

 

Exists

This method indicates whether the specified draft exists in this document.

Signature 
ODBoolean Exists (ODDraftID id,
                  ODDraft *draft,
                  ODPositionCode posCode)

Parameters

id  (ODDraftID)  -  input 

The draft ID or kODNULLID to use the draft and posCode parameters to identify the desired draft.

draft  (ODDraft *)  -  input 

A reference to the draft object used with the posCode parameter to identify the desired draft or kODNULL to use the id parameter to identify the desired draft.

posCode  (ODPositionCode)  -  input 

The position, relative to the draft parameter, of the desired draft in this document's draft history. This parameter can also be set to one of the following values:
kODPosFirstAbove The draft above, immediately more recent than, the specified draft.
kODPosLastAbove The draft below, immediately previous to, the specified draft.
kODLastAbove The draft above, immediately more recent than, the specified draft.
kODLastBelow The draft below, immediately previous to, the specified draft.
kODPosSame The desired draft is the draft object specified by the draft parameter.
kODPosUndefined The id parameter is to be used to identify the desired draft.
kODPosTop The top, most recent, draft in the document.

Returns

rv  (ODBoolean)  -  returns 

A flag indicating whether the specified draft exists in this document.
kODTrue The draft exists in this document.
kODFalse The draft does not exist in this document.

Remarks

If the id parameter is not null, this method uses that parameter to identify the desired draft and ignores the draft and posCode parameters. If the id parameter is kODNULLID, this method uses the draft and posCode parameters to identify the desired draft.

Exception Handling

kODErrInsufficientInfoInParams

No draft was specified; the id parameter is kODNULLID, and the draft parameter is kODNULL.

kODErrUnsupportedPosCode

The specified position code is not supported.

   

GetContainer

This method returns a reference to the container object that created this document.

Signature 
ODContainer *GetContainer ()

Parameters

None.

Returns

rv  (ODContainer *)  -  returns 

A reference to the container object that created this document.

Remarks

This method does not increment the reference count of the returned container. For that reason, if you cache the returned container, you should call its AcquireDocument method to increment its reference count and then call its Release method when you are finished using it.

Related Methods

   

GetID

This method returns the unique ID of this document object.

Signature 
ODDocumentID GetID ()

Parameters

None.

Returns

rv  (ODDocumentID)  -  returns 

The ID of this document object.
   

GetName

This method returns the name of this document.

Signature 
ODDocumentName GetName ()

Parameters

None.

Returns

rv  (ODDocumentName)  -  returns 

The name of this document or an empty sequence if this document does not have a name.

Remarks

Although parts can call this method, they are not usually concerned with document names.

If this document has a name, this method returns a copy of that name; otherwise, the text field of the ODDocumentName structure represents an empty sequence of characters; that is, the text field is an ODByteArray structure whose _length field contains 0 and whose _buffer field contains a null pointer.

Exception Handling

kODErrInvalidPersistentFormat

Unable to read the name from persistent storage because it is not a recognized format.

Related Methods

     

SaveToAPrevDraft

This method is called by the document shell or container part to consolidate the changes in the specified range of drafts.

Signature 
void SaveToAPrevDraft (ODDraft *from, ODDraft *to)

Parameters

from  (ODDraft *)  -  input 

A reference to the first (most recent) draft in the range.

to  (ODDraft *)  -  input 

A reference to the last (oldest) draft in the range or kODNULL to set the draft immediately previous to (below) the from draft.

Returns

None.

Remarks

This method copies the content of all the drafts between the from draft (inclusive) and the to draft (exclusive) to the to draft. It then makes all the drafts from the from draft (inclusive) to the to draft (exclusive) empty. The document shell or container application can call the CollapseDrafts method to delete these empty drafts from this document.

For this method to be successful, there must be no outstanding drafts between the from draft (exclusive) and the to draft (exclusive). An outstanding draft has a reference count greater than 0, meaning that it is being used by some object.

Exception Handling

kODErrDraftNotExists

The from draft does not exist, the to draft does not exist, or the from draft is not a later draft than the to draft.

kODErrOutstandingDraft

There are outstanding drafts between the from draft (exclusive) and the to draft (exclusive).

kODErrIllegalNullDraftInput

The from parameter is null.

Related Methods

     

SetBaseDraftFromForeignDraft

This method is called by the document shell or container application to copy a draft from another document to the base draft of this document.

Signature 
void SetBaseDraftFromForeignDraft (ODDraft *draft)

Parameters

draft  (ODDraft *)  -  input 

A reference to the draft of some other document to be copied to the base draft of this document.

Returns

None.

Remarks

The document shell or container application can call this method when this document is newly created to set this document's base draft to a copy of a draft of another document.    

SetName

This method is called by the document shell or container application to set the name of this document.

Signature 
void SetName (ODDocumentName *name)

Parameters

name  (ODDocumentName *)  -  input 

The new name of this document.

Returns

None.

Related Methods

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]