IRsFileIOType Interface Reference

Inherits IUnknown.

List of all members.

Public Member Functions
HRESULT	GetFileTypeIID ([out, retval] IID *piidType)
HRESULT	GetFileTypeExt ([out, retval] BSTR *pbstrExt)
HRESULT	GetAlternativeFileTypeExt ([out, retval] BSTR *pbstrExt)
HRESULT	GetFileTypeName ([out, retval] BSTR *pbstrName)
HRESULT	GetDefaultThumbnail ([out, retval] IRdBitmap **ppThumbnail)
HRESULT	GetFileTypeCaps ([out, retval] RtDWORD *pdwCaps)
HRESULT	GetCaps ([in] IRsObject *pObject,[in] RePckFileIOOperation eOperation,[out, retval] RtDWORD *pdwCaps)
HRESULT	Save ([in] IRsFileHandle *pRsFileHandle,[in] IRsObject *pObject)
HRESULT	SaveAsync ([in] IRsFileHandle *pRsFileHandle,[in] IRsObject *pObject,[in] IRsFileIOAsyncNotify *pNotify)
HRESULT	Load ([in] IRsFileHandle *pRsFileHandle,[in] IRsObject *pTarget,[out, retval] IRsObject **ppObject)
HRESULT	LoadAsync ([in] IRsFileHandle *pRsFileHandle,[in] IRsObject *pTarget,[in] IRsFileIOAsyncNotify *pNotify)
HRESULT	Apply ([in] IRsObject *pObject,[in] IRsObject *pTarget,[out, retval] IRsObject **ppObject)
HRESULT	GetNameForObject ([in] IRsObject *pObject,[out, retval] BSTR *pbstrName)
HRESULT	GetThumbnailForObject ([in] IRsObject *pObject,[out, retval] IRdBitmap **ppThumbnail)
HRESULT	GetThumbnailFromStream ([in] IRsFileHandle *pRsFileHandle,[out, retval] IRdBitmap **ppThumbnail)

---

Detailed Description

Interface allows you register and maintain object's file or stream type that is defined in your package.

Use this interface for example if your package defines new object or material type and you want to serialize/deserialize it with specified new file extension.

Sync vs. Async , Save and Apply operations: The synchronous operation may access the Dependency graph, therefore always call them from a command that can access the DG. Asynchronous operations treat the DG itself, so you can call them from any thread. Remember that synchronous operation don't implements UNDO/REDO operations.

---

Member Function Documentation

HRESULT IRsFileIOType::GetFileTypeIID

(

[out, retval] IID *

piidType

)

Get file type GUID.

Parameters:

piidType

[out, retval] Returns file type IID.

HRESULT IRsFileIOType::GetFileTypeExt

(

[out, retval] BSTR *

pbstrExt

)

Get file extension.

Parameters:

pbstrExt

[out, retval] Returns file type extension.

HRESULT IRsFileIOType::GetAlternativeFileTypeExt

(

[out, retval] BSTR *

pbstrExt

)

Get alternative file extension(s).

Parameters:

pbstrExt

[out, retval] Returns alternative file type extension(s) separated by semicolon(s) (e.g. ".bmp;.dib). The main extension is included in the string.

HRESULT IRsFileIOType::GetFileTypeName

(

[out, retval] BSTR *

pbstrName

)

Get file type short name.

Parameters:

pbstrName

[out, retval] Returns file type name.

HRESULT IRsFileIOType::GetDefaultThumbnail

(

[out, retval] IRdBitmap **

ppThumbnail

)

Get default object file type thumbnail.

Parameters:

ppThumbnail

[out, retval] Returns default thumbnail.

HRESULT IRsFileIOType::GetFileTypeCaps

(

[out, retval] RtDWORD *

pdwCaps

)

Get file type capabilities.

Parameters:

pdwCaps

[out, retval] Return's capabilities for the file type. See IRsPackageFileIOReg::RePckFileTypeIOCaps for more details.

Returns:

Standard HRESULT processing can be applied to the result.

HRESULT IRsFileIOType::GetCaps	(	[in] IRsObject *	pObject,
		[in] RePckFileIOOperation	eOperation,
		[out, retval] RtDWORD *	pdwCaps
	)

Get all capabilities for the object and/or file type.

Parameters:

	pObject	[in] The object that is to be checked. The object could be any arbitrary Rosetta object, such as DataObject, Node, Selection or just NULL if an global property should be checked.
	eOperation	[in] Operation that is asking for the caps. You can take in consider your caps only for specified operation. See IRsPackageFileIOReg::RePckFileIOOperation for more details.
	pdwCaps	[out, retval] Return's capabilities for the object. See IRsPackageFileIOReg::RePckFileIOCaps for more details

Returns:

Standard HRESULT processing can be applied to the result.

HRESULT IRsFileIOType::Save	(	[in] IRsFileHandle *	pRsFileHandle,
		[in] IRsObject *	pObject
	)

Serialize given object in desired file/stream format. FileIO system automatically add header, thumbnail and other chunks for the file/stream, but if you wants change them or add another chunks, this method should do it.

Parameters:

	pRsFileHandle	[in] Handle to the stream where the object should be serialized.
	pObject	[in] The object that is to be serialized. The object could be any arbitrary Rosetta object, such as DataObject, Node, Selection and etc.

Returns:

S_OK - if the object was serialized successfully.

E_INVALIDARG - if the object cannot be saved in desired format.

other standard error.

HRESULT IRsFileIOType::SaveAsync	(	[in] IRsFileHandle *	pRsFileHandle,
		[in] IRsObject *	pObject,
		[in] IRsFileIOAsyncNotify *	pNotify
	)

Serialize given object in desired file/stream format asynchronously. FileIO system automatically adds header, thumbnail and other chunks for the file/stream, but if you want to change them or add other chunks, this method should do it.

Parameters:

	pRsFileHandle	[in] Handle to the stream where the object should be serialized.
	pObject	[in] The object that is to be serialized. The object could be any arbitrary Rosetta object, such as DataObject, Node, Selection and etc.
	pNotify	[in] - Put here an IRsFileIOAsyncNotify object that will be called when the operation finish.

Returns:

S_OK - if the object's serialization started successfully.

E_INVALIDARG - if the object cannot be saved in desired format.

other standard error.

Remarks:

If you are implementing this method and pNotify is specified, call the AsyncOperationResult method to inform caller about the operarion result.

HRESULT IRsFileIOType::Load	(	[in] IRsFileHandle *	pRsFileHandle,
		[in] IRsObject *	pTarget,
		[out, retval] IRsObject **	ppObject
	)

Deserialize given object as desired file/stream format.

Parameters:

	pRsFileHandle	[in] File handle from which the object should be deserialized.
	pTarget	[in] If target is: NULL - Just load the object. IRsObjectList - Apply the object to all selected Nodes. If it is not possible, do not load the object. an other object - Apply the loaded object to the target. If it is not possible, don't load the object.
	ppObject	[out, retval] Returns interface to the deserialized object if it possible. This parameter is optional and can be NULL.

Returns:

S_OK - if the object was deserialized and applied successfully.

S_FALSE - if the object was loaded successfully but it was not applied. In such case caller may call your Apply method.

E_INVALIDARG - if the object cannot be deserialized in desired format. In this case check the ppObject as the object could be loaded but not applied. If you don't need the object, release it properly (e.g. IRsNode->Destroy()).

other standard error.

HRESULT IRsFileIOType::LoadAsync	(	[in] IRsFileHandle *	pRsFileHandle,
		[in] IRsObject *	pTarget,
		[in] IRsFileIOAsyncNotify *	pNotify
	)

Deserialize given object as desired file/stream format asynchronously.

Parameters:

	pRsFileHandle	[in] File handle from which the object should be deserialized.
	pTarget	[in] If target is: NULL - Just load the object. IRsObjectList - Apply the object to all selected Nodes. If it is not possible, do not load the object. an other object - Apply the loaded object to the target. If it is not possible, don't load the object.
	pNotify	[in] - Put here an IRsFileIOAsyncNotify object that will be called when the operation finish.

Returns:

S_OK - if the object was deserialized successfully.

E_INVALIDARG - if the object cannot be deserialized in desired format. In this case check the ppObject as the object could be loaded but not applied. If you don't need the object, release it properly (e.g. IRsNode->Destroy())

other standard error.

Remarks:

If you are implementing this method and pNotify is specified, call the AsyncOperationResult method to inform caller about the operarion result.

HRESULT IRsFileIOType::Apply	(	[in] IRsObject *	pObject,
		[in] IRsObject *	pTarget,
		[out, retval] IRsObject **	ppObject
	)

Apply given object as desired file/stream format to target object. While the load method is called to load the object, this method is called to apply the loaded object on target. E.g you load material once but apply it to more targets. In such case caller could call the Load with NULL target and then Apply with different targets. Another usage is to apply loaded object even if target is not specified. For example you know load Space 3D even if target is NULL. This cannot be done while the Load is called as you don't know what caller intends with the loaded object.

Parameters:

	pObject	[in] Object that should be applied.
	pTarget	[in] Target object on which the object should be applied. The object could be any arbitrary Rosetta object, such as DataObject, Node, Selection, NULL and etc.
	ppObject	[out, retval] Returns interface to the applied object if it possible. When the applied pObject was destroyed during the apply action, then ppObject points to applied object.

Returns:

S_OK - if the object was applied successfully.

S_FALSE - if the object was applied successfully but caller should delete the source object if it is not more necessary.

E_INVALIDARG - if the object cannot be applied in desired format.

other standard error.

HRESULT IRsFileIOType::GetNameForObject	(	[in] IRsObject *	pObject,
		[out, retval] BSTR *	pbstrName
	)

Get name for the object. The name will be used e.g. in header or default filename.

Parameters:

	pObject	[in] Object thats name is required.
	pbstrName	[out, retval] Returns object's name.

HRESULT IRsFileIOType::GetThumbnailForObject	(	[in] IRsObject *	pObject,
		[out, retval] IRdBitmap **	ppThumbnail
	)

Get thumbnail for object.

Parameters:

	pObject	[in] Object for which the thumbnail is required.
	ppThumbnail	[out, retval] Returns thumbnail for the object. : If you don't return a thumbnail, then an automatically generated or none will be added .

HRESULT IRsFileIOType::GetThumbnailFromStream	(	[in] IRsFileHandle *	pRsFileHandle,
		[out, retval] IRdBitmap **	ppThumbnail
	)

Get thumbnail from stream. If the stream is not Rosetta object, then this method is called to get the thumbnail.

Parameters:

	pRsFileHandle	[in] File handle for the stream.
	ppThumbnail	[out, retval] Returns thumbnail for the object. : If you don't return a thumbnail, then an automatically generated or none will be added.