Programming Reference: ODSession

# Programming Reference

## ODSession

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

Class Hierarchy

    SOMObject
       ODObject
          ODBaseSession
             ODSession

Description

The ODSession class provides access to document-wide OpenDoc objects as well as the initialization and shutdown of the OpenDoc environment.

When an OpenDoc document is opened, the document shell creates and initializes a single instance of ODSession. A part editor should never create an instance of this class directly. During its initialization, the session object creates a single instance of several OpenDoc classes. These OpenDoc objects provide the environment for supporting and manipulating the document.

Through the session object, a part editor can obtain references to most of the OpenDoc global objects: the arbitrator, the clipboard object, the dispatcher, the drag-and-drop object, the information object, the name-space manager, the storage system, the translation object, the undo object, and the window-state object. The document shell can similarly obtain references to the binding object, and the link manager.

The ODSession class also includes methods for converting between a type string (an ODType) and the corresponding token (an ODTypeToken), removing an entry from the type/token table and accessing the name of the current user of the document. The session object also generates link update IDs, which parts use to prevent circular updating when they synchronize linked data.

For more information about the OpenDoc objects that part editors can access, see the chapter on OpenDoc runtime features in the OpenDoc Programming Guide. For more information about linking and link update IDs, see the chapters on storage and data transfer in the OpenDoc Programming Guide.

Methods

The methods defined by the ODSession class include:

Initializing

- InitSession

Accessing Global Objects

- GetArbitrator
- GetBinding
- GetClipboard
- GetDispatcher
- GetDragAndDrop
- GetHelp
- GetInfo
- GetNameSpaceManager
- GetStorageSystem
- GetTranslation
- GetUndo
- GetWindowState

Replacing Global Objects

- SetArbitrator
- SetBinding
- SetClipboard
- SetDispatcher
- SetDragAndDrop
- SetInfo
- SetLinkManager
- SetNameSpaceManager
- SetStorageSystem
- SetTranslation
- SetUndo
- SetWindowState

Converting Between Type Strings and Tokens

- GetType
- RemoveEntry
- Tokenize

Miscellaneous

- GetUserName
- UniqueUpdateID

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

### GetArbitrator

This method returns a reference to the arbitrator for this session.

Signature

    ODArbitrator *GetArbitrator ()

Parameters

None.

Returns

rv (ODArbitrator *) - returns

  A reference to the arbitrator.

### GetBinding

This method is called by the document shell or container application to retrieve a reference to the binding object for this session.

Signature

    ODBinding *GetBinding ()

Parameters

None.

Returns

rv (ODBinding *) - returns

  A reference to the binding object.

### GetClipboard

This method returns a reference to the clipboard object for this session.

Signature

    ODClipboard *GetClipboard ()

Parameters

None.

Returns

rv (ODClipboard *) - returns

  A reference to the clipboard object.

### GetDispatcher

This method returns a reference to the dispatcher for this session.

Signature

    ODDispatcher *GetDispatcher ()

Parameters

None.

Returns

rv (ODDispatcher *) - returns

  A reference to the dispatcher.

### GetDragAndDrop

This method returns a reference to the drag-and-drop object for this session.

Signature

    ODDragAndDrop *GetDragAndDrop ()

Parameters

None.

Returns

rv (ODDragAndDrop *) - returns

  A reference to the drag-and-drop object.

### GetHelp

This method returns a reference to the help object for this session.

Signature

    ODHelp *GetHelp ()

Parameters

None.

Returns

rv (ODHelp *) - returns

  A reference to the help object.

### GetInfo

This method returns a reference to the information object for this session.

Signature

    ODInfo *GetInfo ()

Parameters

None.

Returns

rv (ODInfo *) - returns

  A reference to the information object.

### GetNameSpaceManager

This method returns a reference to the name-space manager for this session.

Signature

    ODNameSpaceManager *GetNameSpaceManager ()

Parameters

None.

Returns

rv (ODNameSpaceManager *) - returns

  A reference to the name-space manager.

### GetStorageSystem

This method returns a reference to the storage system for this session.

Signature

    ODStorageSystem *GetStorageSystem ()

Parameters

None.

Returns

rv (ODStorageSystem *) - returns

  A reference to the storage system.

### GetTranslation

This method returns a reference to the translation object for this session.

Signature

    ODTranslation *GetTranslation ()

Parameters

None.

Returns

rv (ODTranslation *) - returns

  A reference to the translation object.

### GetType

This method gets the type string corresponding to the specified token, if the token exists.

Signature

    ODBoolean GetType (ODTypeToken token,
                       ODType *type)

Parameters

token (ODTypeToken) - input

  A tokenized string representing the token of interest.

type (ODType *) - output

  The type string corresponding to the specified token.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified token exists in the type/token table for this session.

  kODTrue | The specified token exists in the type/token table for this session.
  kODFalse | The specified token does not exist in the type/token table for this session.

Related Methods

- ODSession::RemoveEntry
- ODSession::Tokenize

### GetUndo

This method returns a reference to the undo object for this session.

Signature

    ODUndo *GetUndo ()

Parameters

None.

Returns

rv (ODUndo *) - returns

  A reference to the undo object.

### GetUserName

This method returns a text string identifying the current user of the document.

Signature

    void GetUserName (ODIText *name)

Parameters

name (ODIText *) - output

  A string identifying the current user of the document.

Returns

None.

### GetWindowState

This method returns a reference to the window-state object for this session.

Signature

    ODWindowState *GetWindowState ()

Parameters

None.

Returns

rv (ODWindowState *) - returns

  A reference to the window-state object.

### InitSession

This method initializes this session and creates its objects.

Signature

    void InitSession ()

Parameters

None.

Returns

None.

Remarks

Your part editor should never call this method directly; the document shell calls this method when an OpenDoc document is opened.

### RemoveEntry

This method removes the specified entry from the type/token table for this session.

Signature

    void RemoveEntry (ODType type)

Parameters

type (ODType) - in/out

  The type string identifying the entry to be removed from the type/token table.

Returns

None.

Remarks

If the type string was never converted to a token, no action is taken (because the table does not contain an entry for the specified type).

Related Methods

- ODSession::GetType
- ODSession::Tokenize

### SetArbitrator

This method replaces the arbitrator object for this session.

Signature

    void SetArbitrator (ODArbitrator *arbitrator)

Parameters

arbitrator (ODArbitrator *) - input

  A reference to the new arbitrator for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetBinding

This method replaces the binding object for this session.

Signature

    void SetBinding (ODBinding *binding)

Parameters

binding (ODBinding *) - input

  A reference to the new binding object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetClipboard

This method replaces the clipboard object for this session.

Signature

    void SetClipboard (ODClipboard *clipboard)

Parameters

clipboard (ODClipboard *) - input

  A reference to the new clipboard object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetDispatcher

This method replaces the dispatcher object for this session.

Signature

    void SetDispatcher (ODDispatcher *dispatcher)

Parameters

dispatcher (ODDispatcher *) - input

  A reference to the new dispatcher for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetDragAndDrop

This method replaces the drag-and-drop object for this session.

Signature

    void SetDragAndDrop (ODDragAndDrop *dragAndDrop)

Parameters

dragAndDrop (ODDragAndDrop *) - input

  A reference to the new drag-and-drop object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetInfo

This method replaces the information object for this session.

Signature

    void SetInfo (ODInfo *info)

Parameters

info (ODInfo *) - input

  A reference to the new info object for this session.

Returns

None.

Remarks

This method can be called only by a shell plug-in's installation function.

### SetLinkManager

This method replaces the link manager object for this session.

Signature

    void SetLinkManager (ODLinkManager *linkManager)

Parameters

linkManager (ODLinkManager *) - input

  A reference to the new link manager for this session.

Returns

None.

Remarks

This method can be called only by a shell plug-in's installation function.

### SetNameSpaceManager

This method replaces the name-space manager object for this session.

Signature

    void SetNameSpaceManager (ODNameSpaceManager *nameSpaceManager)

Parameters

nameSpaceManager (ODNameSpaceManager *) - input

  A reference to the new name-space manager for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetStorageSystem

This method replaces the storage system object for this session.

Signature

    void SetStorageSystem (ODStorageSystem *storageSystem)

Parameters

storageSystem (ODStorageSystem *) - input

  A reference to the new storage system object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetTranslation

This method replaces the translation object for this session.

Signature

    void SetTranslation (ODTranslation *translation)

Parameters

translation (ODTranslation *) - input

  A reference to the new translation object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetUndo

This method replaces the undo object for this session.

Signature

    void SetUndo (ODUndo *undo)

Parameters

undo (ODUndo *) - input

  A reference to the new undo object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### SetWindowState

This method replaces the window-state object for this session.

Signature

    void SetWindowState (ODWindowState *windowState)

Parameters

windowState (ODWindowState *) - input

  A reference to the new window-state object for this session.

Returns

None.

Remarks

This method may be called only by a shell plug-in's installation function.

### Tokenize

This method converts the specified type string to a token.

Signature

    ODTypeToken Tokenize (ODType type)

Parameters

type (ODType) - input

  A type string to be converted.

Returns

token (ODTypeToken) - returns

  A tokenized string representing the token corresponding to the specified type.

Remarks

If the specified type string has already been converted to a token (by a previous call to the Tokenize method), this method returns the corresponding token from the type/token table; otherwise, it converts the type to a token and adds a new entry to the type/token table.

Only tokens with entries in the type/token table can be converted back to type strings (by calling the GetType method).

Exception Handling

kODErrOutOfMemory | There is not enough memory to generate a token.

Related Methods

- ODSession::GetType
- ODSession::RemoveEntry

### UniqueUpdateID

This method returns a new update ID that is unique to this session and unlikely to be repeated on the network.

Signature

    ODUpdateID UniqueUpdateID ()

Parameters

None.

Returns

rv (ODUpdateID) - returns

  A unique update ID.

Remarks

An update ID uniquely identifies the version of the clipboard content or linked content. The update ID values have no significance other than the context of testing them for equality; they remain valid only during the current session.

For more information on linking and link update IDs, see the chapters on storage and data transfer in the OpenDoc Programming Guide.

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