Programming Reference: ODObject

# Programming Reference

## ODObject

Class Definition File | ODObject.idl
Class C++ Binding | ODObject.xh

Class Hierarchy

    SOMObject
       ODObject

Description

The ODObject class is the superclass of all OpenDoc classes; it defines features that all subclasses support, such as memory recovery and extensions.

The ODObject class defines a general memory recovery system through the Purge method. It also defines an extension mechanism that allows subclasses to extend the functionality of objects. Subclasses are responsible for defining the extensions they support. For more information on extensions, see the class description for ODExtension.

You should never instantiate ODObject. You can create an object of ODObject subclass by calling the appropriate factory method, if a factory method exists.

Methods

The methods defined by the ODObject class include:

- AcquireExtension
- HasExtension
- InitObject
- IsEqualTo
- Purge
- ReleaseExtension
- SubClassResponsibility

Overridden Methods | There are no methods overridden by the ODObject class.

### AcquireExtension

This method returns a reference to the specified extension object.

Signature

    ODExtension AcquireExtension (ODType extensionName)

Parameters

extensionName (ODType) - input

  The name of extension to be retrieved. This parameter can be set to a part-specific string or one of the following values:

  kODScriptExtension | An extension to support direct scripting.
  kODSettingsExtension | An extension to add parameters to the Properties notebook.

Returns

rv (ODExtension) - returns

  A reference to the specified extension object.

Remarks

Your part calls this method to obtain a reference to an extension object with the specified extension type. If the subclass does not support the specified extension, this method raises an exception. The ODObject class has no inherent extensions of its own and always raises an exception.

Your override of this method should increment the reference count of the returned extension object. The caller must call the ReleaseExtension method of the returned ODExtension object.

Exception Handling

kODErrUnsupportedExtension | The specified extension is not supported by this object.

Override Policy

Your subclass of ODPart can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited AcquireExtension method at the end of your implementation. The client of an extension object must be prepared if the specified extension is not supported.

Your override of this mehtod should return a reference to your part's extension object. A client of an extension object calls this method to obtain a reference to the specified extension.

Related Methods

- ODObject::HasExtension
- ODObject::ReleaseExtension

### HasExtension

This method indicates whether the object supports the specified extension.

Signature

    ODBoolean HasExtension (ODType extensionName)

Parameters

extensionName (ODType) - input

  The name of the extension to be checked.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the object supports the specified extension.

  kODTrue | The object supports the specified extension.
  kODFalse | The object does not support the specified extension.

Remarks

Your part can call this method before accessing an object's extension.

The ODObject class has no inherent extensions of its own and always returns kODFalse.

Override Policy

Your subclass of ODPart can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited HasExtension method at the end of your implementation. The client of an extension object must be prepared in the event that the specified extension is not supported.

Your override of this method shoudl return a reference to the part's extension object. A client of an extension object calls this method to obtain a reference to the specified extension.

Related Methods

- ODObject::AcquireExtension
- ODObject::ReleaseExtension

### InitObject

This method initializes the object.

Signature

    void InitObject ()

Parameters

None.

Returns

None.

Remarks

Subsequent calls to this method have no affect.

### IsEqualTo

This method indicates whether the specified object is equal to this object.

Signature

    ODBoolean IsEqualTo (ODObject object)

Parameters

object (ODObject) - input

  A reference to an object to be compared with this object.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified object is equal to this object.

  kODTrue | The objects are the same.
  kODFalse | The objects are different.

Remarks

You should call this method when you need to compare objects for equality. You should never use the equal or not equal operators (for example, the == and != operators of the C++ language) to compare references of two objects.

### Purge

This method releases any unneeded memory during low-memory situations.

Signature

    ODSize Purge (ODSize size)

Parameters

size (ODSize) - input

  The number of bytes needed by OpenDoc.

Returns

rv (ODSize) - returns

  The number of bytes that were released by this object.

Remarks

Your part may call this method, but in general, OpenDoc calls this method in low-memory situations to free any caches, noncritical buffers, or objects; you should not allocate memory for this operation.

Because the ODObject class does not allocate (or deallocate) any memory, it always returns the value 0.

Override Policy

Every subclass of ODObject can and should override this method if it creates caches and temporary buffers. If you subclass specific classes, for example ODPart, you must override this method or risk running out of available memory. Your override method must call its inherited purge method during your implementation. You should save the size value returned by the inherited purge method and add it to the size value returned from your override method.

Your override of this method should:

- Free any caches, non-critial buffers, and objects up to the amount of memory specified.
- Add the number of bytes freed to the number returned by the inherited method and return this sum to the amount of memory released.

OpenDoc calls this method when needed, do not allocate memory for this operation.

### ReleaseExtension

This method releases the specified extension object.

Signature

    void ReleaseExtension (ODExtension extension)

Parameters

extension (ODExtension) - input

  A reference to the extension to be released.

Returns

None.

Remarks

OpenDoc or an extension object client calls this method to release an extension object that was previously acquired using the AcquireExtension method. If the extension was not previously acquired by the caller, the ReleaseExtension method raises an exception. After this method executes successfully, the specified extension object is no longer guaranteed to be valid.

The ODObject class has no inherent extensions and always raises an exception.

Exception Handling

kODErrUnsupportedExtension | This object did not recognize the specified extension object and cannot release it.

Override Policy

Your subclass of ODPart can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited ReleaseExtension method at the end of your implementation. The client of the extension object must be prepared if the specified extension is not supported.

Your override of this method should release the specified extension object, acquired when AcquireExtension was called. A client of an extension object calls this method when it finishes working with the extension.

Related Methods

- ODObject::AcquireExtension
- ODObject::HasExtension

### SubClassResponsibility

This method raises an exception to indicate that a subclass failed to override a required method.

Signature

    void SubClassResponsibility ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method at run time to indicate that a subclass that should have overridden a particular method failed to do so.

Exception Handling

kODErrSubClassResponsibility | The subclass must override this method. The called method should have, but was not, overridden by the subclass of the class that defines this method.

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