Inside Macintosh: OpenDoc Class Reference /

Part 1 - Classes and Methods / ODDraft

Clone

The Clone method clones the specified persistent object or storage unit.

ODID Clone (in ODDraftKey key, 
            in ODID fromObjectID, 
            in ODID toObjectID, 
            in ODID scope);

key

The draft key of the current cloning transaction.

fromObjectID

The ID of the persistent object or storage unit to be cloned.

toObjectID

The ID of the destination persistent object or storage unit, or kODNULLID to create a new storage unit in the destination draft.

scope

The ID of the frame that defines the scope of this cloning operation.

return value

The ID of the destination persistent object or storage unit. (The ID of a persistent object is the same as the ID of its storage unit.)

DISCUSSION

The following summary describes how to use the Clone method.

• You start a cloning transaction by calling this draft object's BeginClone method, which returns the draft key identifying the cloning transaction.
• Next, call this draft object's Clone method, passing as parameters the draft key returned by the BeginClone method, the ID of the object to be cloned, the ID of the destination storage unit, and the frame object specifying the scope.
• Finally, call this draft object's EndClone method, passing as a parameter the draft key returned by the BeginClone method. The EndClone method commits the cloning transaction and performs the data transfer.

The key parameter is the draft key of the current cloning transaction, which was returned by a call to this draft object's BeginClone method and passed to the calling object's CloneInto method.

The fromObjectID parameter identifies the object to be cloned. If a persistent object exists with the specified ID, that persistent object is cloned; otherwise, the storage unit with the specified ID is cloned.

The toObjectID parameter specifies the ID of the destination storage unit. If the toObjectID parameter is null, a new destination storage unit is created in the destination draft.

If the object being cloned has persistent references to other objects, the scope parameter determines which of the referenced objects are within the scope of this cloning operation. Typically, the scope parameter is the ID of a frame and only those objects embedded in that frame are within scope. In the rare case in which the scope parameter is kODIDAll, all referenced objects are within scope.

This method passes its key parameter, the destination storage unit, and its scope parameter to the CloneInto method of the persistent object or storage unit being cloned. If that persistent object or storage unit has persistent references, its CloneInto method clones any persistently referenced objects that are within the scope of this cloning operation. Objects referenced by strong persistent references are strongly cloned by recursive calls to the Clone method; objects referenced by weak persistent references are weakly cloned by calls to the WeakClone method.

You must not use the returned ID until the end of the current cloning transaction. Furthermore, before you try to access the persistent object or storage unit with the corresponding ID, you must call the IsValidID method to verify that the ID is still valid.

EXCEPTIONS

kODErrInvalidDraftKey

The specified draft key is not the draft key for the current cloning transaction.

kODErrInvalidID

The toObjectID parameter did not specify a valid destination object or storage unit.

SEE ALSO

The ODDraftKey type (page 902).
The ODID type (page 899).
The ODDraft::AbortClone method (page 151).
The ODDraft::BeginClone method (page 159).
The ODDraft::EndClone method (page 171).
The ODDraft::IsValidID method (page 175).
The ODDraft::WeakClone method (page 185).
The ODPersistentObject::CloneInto method (page 557).
The ODStorageUnit::CloneInto method (page 673).
"Clone" on page 323 in OpenDoc Programmer's Guide.
"The CloneInto Method of Your Part Editor" on page 327 in OpenDoc Programmer's Guide.