Programming Reference: ODTranslation

# Programming Reference

## ODTranslation

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

Class Hierarchy

    SOMObject
       ODObject
          ODBaseTranslation
             ODTranslation

Description

An object of the ODTranslation class provides data translation services for OpenDoc documents and their parts.

The ODTranslation class depends on platform-specific system services to provide OpenDoc data translation. OpenDoc uses translation objects to maintain information on what kinds of translations are available to the user. OpenDoc and part editors can also use the translation object to perform any requested translations, rather than directly calling the underlying platform-specific services.

When a document is opened, the session object creates a single translation object. All parts of the document share the translation object; you can obtain a reference to it by calling the session object's GetTranslation method.

The translation service can be triggered when a part does not know how to handle data of an unfamiliar type. For example, if the user initiates linking or importing of data from the clipboard or drag-and-drop objects. The part can ask the translation object to translate the data into a recognizable format, a part kind. Similarly, OpenDoc can initiate translation when opening a part on a system where no part editor can directly read the part's data.

OpenDoc does not use platform types; therefore, to operate between OpenDoc and non-OpenDoc systems, platform types and ISO types need to be translated from one kind to the other. If you have part data expressed as a platform-dependent type and need to express it as a part kind, an ISO string, you can use the GetISOTypeFromPlatformType method to determine if there is a part kind equivalent to that file type. To convert in the opposite direction, use the GetPlatformTypeFromISOType method.

The ODTranslation class wraps platform-specific translation facilities. These facilities do not exist on AIX, OS/2, or Windows. Therefore, most ODTranslation methods are not implemented on these platforms. Only type conversion methods are implemented on these platforms.

For more information related to data translation, see the chapter on data transfer in the OpenDoc Programming Guide.

Methods

The ODTranslation class defines the following methods:

- CanTranslate
- GetISOTypeFromPlatformType
- GetPlatformTypeFromISOType
- GetTranslationOf
- Translate
- TranslateView

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

### CanTranslate

This method indicates whether translation is possible from the specified value type.

Signature

    ODTranslateResult CanTranslate (ODValueType fromType)

Parameters

fromType (ODValueType) - input

  The type of data to be translated.

Returns

rv (ODTranslateResult) - returns

  The result of a translation. This parameter can return one of the following values:

  kODCanTranslate | Translation is allowed with the specified type.
  kODCannotTranslate | Translation is not allowed with the specified type.

Remarks

Your part calls this method to determine if translation facilities are available for a particular value type. On AIX, OS/2, and Windows, this method returns kODCannotTranslate.

### GetISOTypeFromPlatformType

This method returns the ISO type corresponding to the specified platform-specific type.

Signature

    ODValueType GetISOTypeFromPlatformType (ODPlatformType platformType,
                                            ODPlatformTypeSpace typeSpace)

Parameters

platformType (ODPlatformType) - input

  A wrapper for the platform-specific type.

typeSpace (ODPlatformTypeSpace) - input

  The type of platform-specific structure identifying a type space (data or file). This parameter can be set to one of the following values:

  kODPlatformDataType | The native operating system scrap type.
  kODPlatformFileType | The native operating system file type.

Returns

rv (ODValueType) - returns

  The corresponding ISO type.

Remarks

Your part calls this method. OpenDoc does not use platform types; therefore, to interoperate between OpenDoc and non-OpenDoc systems, platform types and ISO types need to be translated from one kind to the other.

It is your responsibility to deallocate the returned value type when it is no longer needed.

Related Methods

- ODStorageSystem::CreatePlatformTypeList
- ODTranslation::GetPlatformTypeFromISOType

### GetPlatformTypeFromISOType

This method returns the platform-specific type corresponding to the specified ISO type.

Signature

    ODPlatformType GetPlatformTypeFromISOType (ODValueType type)

Parameters

type (ODValueType) - input

  The ISO type.

Returns

rv (ODPlatformType) - returns

  A wrapper for the corresponding platform-specific type.

Remarks

Your part calls this method. OpenDoc does not use platform types; therefore, to interoperate between OpenDoc and non-OpenDoc systems, platform types and ISO types need to be translated from one kind to the other.

Related Methods

- ODStorageSystem::CreatePlatformTypeList
- ODTranslation::GetISOTypeFromPlatformType

### GetTranslationOf

This method returns a type list to which the specified value type can be translated.

Signature

    ODTypeList *GetTranslationOf (ODValueType fromType)

Parameters

fromType (ODValueType) - input

  The type of data to be translated.

Returns

rv (ODTypeList *) - returns

  A reference to a type list specifying a set of part kinds to which the specified value type can be translated or an empty list if the translation cannot be achieved.

Remarks

Your part calls this method to determine all possible results that you can obtain by translating the specified type of data. This method does not change the value of the data to be translated. This method always returns an empty list.

Exception Handling

kODErrOutOfMemory | There is not enough memory to allocate the type list object.

This method may return platform-specific exceptions.

### Translate

This method translates the source data to the specified value type.

Signature

    ODTranslateResult Translate (ODValueType fromType,
                                 ODByteArray *fromData,
                                 ODValueType toType,
                                 ODByteArray *toData)

Parameters

fromType (ODValueType) - input

  The type of the source data to be translated.

fromData (ODByteArray *) - input

  A byte array whose buffer contains the source data to be translated.

toType (ODValueType) - input

  The type to which the source data is to be translated.

toData (ODByteArray *) - output

  A byte array whose buffer is to contain the translated data.

Returns

rv (ODTranslateResult) - returns

  The result of a translation. This parameter can return one of the following values:

  kODCanTranslate | Translation is allowed with the specified type.
  kODCannotTranslate | Translation is not allowed with the specified type.

Remarks

Your part calls this method after calling the CanTranslate method to establish that the source type can be translated. This method does not change the content of the source byte array.

If translation is successful, this method allocates the destination byte array structure and its buffer, and stores the translated data in that buffer. It is your responsibility to deallocate the byte array structure (and its buffer) when it is no longer needed.

On AIX, OS/2, and Windows, this method throws the exception kODErrNoSysTranslationFacility.

Exception Handling

kODErrNoSysTranslationFacility | The underlying system translation facility is not present.
kODErrOutOfMemory | There is not enough memory to allocate the destination byte array structure (or its buffer).

This method may return platform-specific exceptions.

Related Methods

- ODTranslation::CanTranslate

### TranslateView

This method translates the content of the source storage-unit view and stores the translated data in the destination storage-unit view.

Signature

    ODTranslateResult TranslateView (ODStorageUnitView *fromView,
                                     ODStorageUnitView *toView)

Parameters

fromView (ODStorageUnitView *) - input

  A reference to a storage-unit view; the focused value that contains the translated data.

toView (ODStorageUnitView *) - input

  A reference to a storage-unit view; the focused value that is to contain the translated data.

Returns

rv (ODTranslateResult) - returns

  The result of a translation. This parameter can return one of the following values:

  kODCanTranslate | Translation is allowed with the specified type.
  kODCannotTranslate | Translation is not allowed with the specified type.

Remarks

Your part calls this method when it wants to translate some data in a storage unit. On AIX, OS/2, and Windows, this method throws the exception kODErrNoSysTranslationFacility.

Exception Handling

kODErrNoSysTranslationFacility | The underlying system translation facility is not present.
kODErrOutOfMemory | There is not enough memory to allocate the translated data.

This method may return platform-specific exceptions.

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