Programming Reference: ODExtension

# Programming Reference

## ODExtension

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

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODExtension

Description

An object of the ODExtension class represents an extended interface to an OpenDoc object.

The OpenDoc architecture is designed to be extended. You can enhance the capabilities of and communications among your parts or other OpenDoc objects in a compound document by extending the standard OpenDoc interfaces. All subclasses of ODObject (including shapes, facets, frames, documents, windows, and parts) can be extended. A part editor can define an extended interface for any purpose, including extensions to handle text searching, linking, specialized text formatting, database accessing, and specialized graphics processing. You can even use extensions to develop component software that goes well beyond the standard OpenDoc model of parts and compound documents.

The ODExtension class is an abstract superclass that you can subclass to create an extended interface to a base object. For example, the ODScriptExtension class is a subclass of ODExtension. Callers can access an already existing extension object by calling its base object's AcquireExtension method, which returns a reference to the extension object.

The ODExtension class itself has minimal functionality. Each extension object knows which object it is an extension of and how to release resources in itself and in its base object. Further behavior should be implemented in a subclass of ODExtension.

Overriding Inherited Methods

The following methods are inherited and available for use by your subclass of ODExtension.

- Purge
- Release
- somInit
- somUninit

Methods

The methods defined by the ODExtension class include:

- BaseRemoved
- CheckValid
- GetBase
- InitExtension
- IsValid

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

### BaseRemoved

This method invalidates this extension object.

Signature

    void BaseRemoved ()

Parameters

None.

Returns

None.

Remarks

An extension object becomes invalid when its base object is removed. This extension object should no longer attempt to communicate with its base object; any pointers that this extension object had to its base object should be considered invalid. The base object of this extension should call this method from its ReleaseAll method.

Override Policy

If you subclass ODExtension, you can override this method. Your override of this method must call its inherited method at some point in your implementation. You should not access the base object after calling the inherited object.

### CheckValid

This method checks whether this extension object is valid and generates an exception if it is not valid.

Signature

    void CheckValid ()

Parameters

None.

Returns

None.

Remarks

Every subclass of ODExtension must test the extension object's validity at the beginning of the implementation of each of its noninherited methods (except for the subclass-specific initialization method) by calling this method or the IsValid method. Unlike the IsValid method, calling this method has no effect if this extension object is valid; otherwise, it generates an exception.

If you want to ensure that you make calls only to a valid extension object, without generating an exception, then call the IsValid method instead.

Exception Handling

kODErrInvalidExtension | This extension object is invalid and should not be used because its base object no longer exists.

Related Methods

- ODExtension::IsValid

### GetBase

This method returns a reference to this extension's base object.

Signature

    ODObject *GetBase ()

Parameters

None.

Returns

rv (ODObject *) - returns

  A reference to this extension's base object.

Remarks

A client of this extension object calls this method if it has a reference to this extension object but did not save a reference to its base object.

### InitExtension

This method initializes this extension object.

Signature

    void InitExtension (ODObject *base)

Parameters

base (ODObject *) - input

  A reference to this extension's base object.

Returns

None.

Remarks

This method is not called directly to initialize this extension object but is called by a subclass-specific initialization method. By convention, every subclass of ODExtension should have a separate initialization method that is called when an instance of that subclass is created. The override method may have additional parameters beyond those of the InitExtension method. The separate initialization method should call the inherited InitExtension method at the beginning of its implementation.

If you subclass ODExtension, your subclass-specific initialization method, rather than its somInit method, should handle any initialization code that can potentially fail. For example, your initialization method may attempt to allocate memory for your extension.

Override Policy

If you subclass ODExtension, you should not override this method.

### IsValid

This method indicates whether this extension object is valid.

Signature

    ODBoolean IsValid ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this extension object is valid.

  TRUE | This extension object is valid.
  FALSE | This extension object is invalid.

Remarks

A client of this extension object calls this method if it wants to ensure that it makes calls only to a valid extension object, without generating an exception.

Related Methods

- ODExtension::CheckValid

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