IRsFileHandleDisp Interface Reference

Inherits IDispatch.

List of all members.

Public Member Functions

HRESULT Open ([in] RtDWORD dwFlags)

HRESULT GetStreamName ([out, retval] BSTR *pbstrStreamName)

HRESULT GetFlags ([out, retval] RtDWORD *pdwFlags)

HRESULT GetChunksList ([in] RtBOOL bCheckConsistency,[out, retval] VARIANT *pvChunksList)

HRESULT ScanChunksList ([out, retval] VARIANT *pvChunksList)

HRESULT GetChunk ([in] RtDWORD dwIndex,[in] RtDWORD dwFlags,[out, retval] VARIANT *pvRsFileChunk)

HRESULT FindChunk ([in] BSTR bszIID,[in] RtDWORD dwFromIndex,[out, retval] RtDWORD *pdwIndex)

HRESULT AddChunk ([in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)

HRESULT ReplaceChunk ([in] RtDWORD dwIndex,[in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)

HRESULT InsertChunk ([in] RtDWORD dwIndex,[in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)

HRESULT DeleteChunk ([in] RtDWORD dwIndex)

HRESULT Close ([in] RtBOOL bForce)

Detailed Description

Specifies dispatch (scriptable) version of the IRsFileHandle interface.

Warning:: this IRsFileHandleDisp has to be exact mirror of IRsFileHandle interface.

Member Function Documentation

HRESULT IRsFileHandleDisp::Open ( [in] RtDWORD dwFlags )

Use this method to re-open the file if you call the close method or you need change the read-write flags.

Parameters:

dwFlags

[in] IRsFileHandle::ReFileHandleOpenFlags Possible values:

RSFHNDO_READ - If set mean you can read from opened file.
RSFHNDO_WRITE - Specify if you want modify the stream.
Note: If only RSFHNDO_WRITE is specified, you can only write into the file. If the file exist, it will be replaced.
RSFHNDO_NO_CHNK_LIST - Don't add chunks list or remove it if the file was created or modified.
RSFHNDO_NO_CHNK_SUPP - Supports only plain stream.

Returns:: Standard HRESULT processing can be applied to the result.

Remarks:: If you modify the file, all the changes are not saved immediately
but only when the FileHandle object is closed. To do it manually call Close method.

    var mainDir = System.GetMainDir();
    var target = mainDir + '\\Rs Main Libraries\\AntonPhysics\\nmj.RsObj';
    var a = RsFileIO.CreateRsFileHandle(target, 1);
    a.open(1);

HRESULT IRsFileHandleDisp::GetStreamName ( [out, retval] BSTR * pbstrStreamName )

Returns stream/file name of the file that is handled.

Returns:: pbstrFileName [out, retval] - handled file file name.

    var b = a.GetStreamName();

HRESULT IRsFileHandleDisp::GetFlags ( [out, retval] RtDWORD * pdwFlags )

Returns flags of the stream/file.

Returns:: pdwFlags [out, retval] - returned flags.
See Open method for details.

    var c = a.GetFlags();

HRESULT IRsFileHandleDisp::GetChunksList	(	[in] RtBOOL	bCheckConsistency,
		[out, retval] VARIANT *	pvChunksList
	)

Get current chunks list for stream and check stream consistency.

Parameters:

bCheckConsistency

[in] If true then check the stream consistency too, so the loaded chunk list is compared with the scanned one.
If you specify false, then the chunk list will be loaded from stream.
If you are in write mode, you will get current chunk list that could not be consistent with the one stored in the stream.
Thus it hasn't sense to specify in this case.
If you delete a chunk and set true, then the deleted chunk will be again added.

Returns:

pvChunksList [out, retval] - returned chunks list.

S_OK - if the chunk was found and match with stream.
S_FALSE - if the chunk was not found or if it doesn't match with stream.
See the RSCHUNK_LST_FLG_MODIFIED flag in RdChunksList::ReChunkListInfoFlags for these chunks. Otherwise error.

Remarks:: See IRdChunksListDisp for additional methods to run with GetChunksList().

 var d = a.GetChunksList(true);
 var e = d.GetNumChunks();

HRESULT IRsFileHandleDisp::ScanChunksList ( [out, retval] VARIANT * pvChunksList )

Scan chunks from the current stream. Use this method to detect really written chunks.

Returns:: *pvChunksList [out, retval] - returned chunks list.
Standard HRESULT processing can be applied to the result.

 var f = a.ScanChunksList();

HRESULT IRsFileHandleDisp::GetChunk	(	[in] RtDWORD	dwIndex,
		[in] RtDWORD	dwFlags,
		[out, retval] VARIANT *	pvRsFileChunk
	)

Get specified chunk from stream.
Next predefined chunks implements appropriated access interface that you can use to read its data or to modify them:

RdChunk Header
RdChunk Thumbnail
RdChunk RsObj
IRdChunkTags
IRdChunkHistory
IRdChunkSystem
RdChunk Unknown
RdChunks List

Parameters:

	dwIndex	[in] Index of the chunk you want to read.
	dwFlags	[in] Get chunk flags (see IRsFileHandle::ReFHndGetChunFlags): FHND_GET_CHUNK_FLG_MAKE_COPY = 0x00000001 - If set you get copy of the chunk. FHND_GET_CHUNK_FLG_AS_UNKNOWN= 0x00000002 - Load the chunk as unknown, so it will be read not as object but as a stream only (none processing).

Returns:: pvRsFileChunk [out, retval] contains the chunk if it is found.
Standard HRESULT processing can be applied to the result.

    var headr = a.FindChunk('RdChunk Header', -1);
    var g = a.GetChunk(headr, false);

HRESULT IRsFileHandleDisp::FindChunk	(	[in] BSTR	bszIID,
		[in] RtDWORD	dwFromIndex,
		[out, retval] RtDWORD *	pdwIndex
	)

Find specified by its ID.

Parameters:

	bszIID	[in] Class ID of the chunk. You can use also names of the chunk objects in form: "<Package Name>/<Chunk Name>" -> e.g. "FileIO Package/RdChunk Header" or use these pre-defined string names: "RdChunk Header" "RdChunk Thumbnail" "RdChunk RsObj" "RdChunks List" "RdChunk Tags" "RdChunk History" "RdChunk System" "RdChunk Unknown"
	dwFromIndex	[in] from which chunk index it will be searched. Specify -1 to search from the first chunk.

Returns:: pdwIndex [out, retval] contains the chunk index if it is found, -1 if it was not found.
Standard HRESULT processing can be applied to the result.

    var headr = a.FindChunk('RdChunk Header', -1);

HRESULT IRsFileHandleDisp::AddChunk	(	[in] VARIANT	vRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Add chunk to end of the stream.

Parameters:

	vRsFileChunk	[in] the chunk you want to add.
	bMakeCopy	[in] If true, a copy of the chunk will be added.

Returns:: Standard HRESULT processing can be applied to the result.

Remarks:: The ChunksList chunk is placed to end of the stream (while you don't specify
RSFHNDO_NO_CHNK_LIST from IRsFileHandle::ReFileHandleOpenFlags in Open method) and is managed separately.

 var addChunk = a.AddChunk('RdChunk Thumbnail', true);

HRESULT IRsFileHandleDisp::ReplaceChunk	(	[in] RtDWORD	dwIndex,
		[in] VARIANT	vRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Replace specified chunk.

Parameters:

	dwIndex	[in] Specify index of the chunk you want to replace.
	vRsFileChunk	[in] The new chunk.
	bMakeCopy	[in] If true, a copy of the chunk will replace the existing chunk.

Returns:: Standard HRESULT processing can be applied to the result.

    var newThumb = System.CreateDO('Common Data Package/Bitmap Data');
    target = mainDir + '\\Textures\\checkered.bmp';
    newThumb.LoadFromFile(target);
    var oldThumb = a.FindChunk('RdChunk Thumbnail', -1);
    a.ReplaceChunk(oldThumb, newThumb, false);

HRESULT IRsFileHandleDisp::InsertChunk	(	[in] RtDWORD	dwIndex,
		[in] VARIANT	vRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Insert new chunk at specified position.

Parameters:

	dwIndex	[in] position when the chunk will be inserted.
	vRsFileChunk	[in] the chunk you want to add.
	bMakeCopy	[in] If true, a copy of the chunk will be inserted.

Returns:: Standard HRESULT processing can be applied to the result.

    var d = a.GetChunksList(true);
    var e = d.GetNumChunks(); 
    a.InsertChunk(e-1,'RdChunk Thumbnail', copy);

HRESULT IRsFileHandleDisp::DeleteChunk ( [in] RtDWORD dwIndex )

Delete specified chunk from stream.

Parameters:

dwIndex

[in] index of the chunk that will be deleted.

Returns:: Standard HRESULT processing can be applied to the result.

 a.DeleteChunk(e-1);

HRESULT IRsFileHandleDisp::Close ( [in] RtBOOL bForce )

Close stream. If you were creating or modifying the stream,
then call Close method all the changes will be written.
If you don't call this method, then the stream will be closed anyway but as force close.

Parameters:

bForce

[in] If true the the handle will be closed even an error occurs (e.g. missing chunks or save errors).

Returns:: Standard HRESULT processing can be applied to the result.

 a.close(true);


Public Member Functions
HRESULT	Open ([in] RtDWORD dwFlags)
HRESULT	GetStreamName ([out, retval] BSTR *pbstrStreamName)
HRESULT	GetFlags ([out, retval] RtDWORD *pdwFlags)
HRESULT	GetChunksList ([in] RtBOOL bCheckConsistency,[out, retval] VARIANT *pvChunksList)
HRESULT	ScanChunksList ([out, retval] VARIANT *pvChunksList)
HRESULT	GetChunk ([in] RtDWORD dwIndex,[in] RtDWORD dwFlags,[out, retval] VARIANT *pvRsFileChunk)
HRESULT	FindChunk ([in] BSTR bszIID,[in] RtDWORD dwFromIndex,[out, retval] RtDWORD *pdwIndex)
HRESULT	AddChunk ([in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	ReplaceChunk ([in] RtDWORD dwIndex,[in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	InsertChunk ([in] RtDWORD dwIndex,[in] VARIANT vRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	DeleteChunk ([in] RtDWORD dwIndex)
HRESULT	Close ([in] RtBOOL bForce)