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: |
Overridden Methods | There are no methods overridden by the ODTranslation class. |
This method indicates whether translation is possible from the specified value type.
Signature
ODTranslateResult CanTranslate (ODValueType fromType) |
Parameters
Returns
| 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.
This method returns the ISO type corresponding to the specified platform-specific type.
Signature
ODValueType GetISOTypeFromPlatformType (ODPlatformType platformType,
ODPlatformTypeSpace typeSpace)
|
Parameters
| kODPlatformDataType | The native operating system scrap type. |
| kODPlatformFileType | The native operating system file type. |
Returns
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
This method returns the platform-specific type corresponding to the specified ISO type.
Signature
ODPlatformType GetPlatformTypeFromISOType (ODValueType type) |
Parameters
Returns
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
This method returns a type list to which the specified value type can be translated.
Signature
ODTypeList *GetTranslationOf (ODValueType fromType) |
Parameters
Returns
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.
This method translates the source data to the specified value type.
Signature
ODTranslateResult Translate (ODValueType fromType,
ODByteArray *fromData,
ODValueType toType,
ODByteArray *toData)
|
Parameters
Returns
| 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
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
Returns
| 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.