Inside Macintosh: OpenDoc Class Reference /

Part 1 - Classes and Methods / ODDocument

AcquireDraft

Document Shell

The AcquireDraft method returns a reference to the specified draft of this document with its permissions set as specified.

ODDraft AcquireDraft (in ODDraftPermissions perms, 
                  in ODDraftID id, 
                  in ODDraft draft, 
                  in ODPositionCode posCode, 
                  in ODBoolean release);

perms

The target permissions for the draft. Valid values for perms are dependent on the container suite; the Bento container suite supports two values: read only (kODDPReadOnly) and exclusive read/write (kODDPExclusiveWrite).

id

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

draft

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

posCode

The position, relative to the draft parameter, of the desired draft in this document's draft history, or kODPosUndefined to use the id parameter to identify the desired draft.

release

kODTrue if the draft specified by the draft parameter should be released after the desired draft is returned, otherwise kODFalse. (Used only when the draft and posCode parameters identify the desired draft.)

return value

A reference to the specified draft object.

DISCUSSION

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 the draft parameter, and this method changes the permissions of that draft. If the release parameter is true, the draft passed in the draft parameter is released if the desired draft can be returned.

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 the ways in which other objects are currently accessing the desired 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 desired draft is the document's most recent draft and no other object already has access to the draft (either 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. When the caller has finished using that draft, it should call the draft's Release method.

EXCEPTIONS

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

Attempt to change the permissions for a draft while other objects have references to it.

kODErrUnsupportedPosCode

The specified position code is not supported.

SEE ALSO

The ODDraftID type (page 902).
The ODDraftPermissions type (page 902).
The ODPositionCode type (page 915).
The ODContainer::AcquireDocument method (page 100).
The ODDocument::AcquireBaseDraft method (page 134).
"Insert" on page 247 in OpenDoc Programmer's Guide.
Table 11-1 on page 466 in OpenDoc Programmer's Guide.