IRsFileHandle Interface Reference

Inherits IUnknown.

List of all members.

Public Member Functions
HRESULT	Open ([in] RtDWORD dwFlags)
HRESULT	GetStreamName ([out, retval] BSTR *pbstrStreamName)
HRESULT	GetStream ([out, retval] IStream **ppStm)
HRESULT	GetFlags ([out, retval] RtDWORD *pdwFlags)
HRESULT	GetChunksList ([in] RtBOOL bCheckConsistency,[out, retval] IRdChunksList **ppChunksList)
HRESULT	ScanChunksList ([out, retval] IRdChunksList **ppChunksList)
HRESULT	GetChunk ([in] RtDWORD dwIndex,[in] RtDWORD dwFlags,[out, retval] IRsFileChunk **ppRsFileChunk)
HRESULT	FindChunk ([in] IID iid,[in] RtDWORD dwFromIndex,[out, retval] RtDWORD *pdwIndex)
HRESULT	AddChunk ([in] IRsFileChunk *pRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	ReplaceChunk ([in] RtDWORD dwIndex,[in] IRsFileChunk *pRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	InsertChunk ([in] RtDWORD dwIndex,[in] IRsFileChunk *pRsFileChunk,[in] RtBOOL bMakeCopy)
HRESULT	DeleteChunk ([in] RtDWORD dwIndex)
HRESULT	FlushToStream ([in] RtBOOL bIgnoreBadChunks)
HRESULT	Close ([in] RtBOOL bForce)

---

Detailed Description

Warning:

this IRsFileHandle has to be exact mirror of IRsFileHandleDisp interface.

---

Member Function Documentation

HRESULT IRsFileHandle::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.

HRESULT IRsFileHandle::GetStreamName

(

[out, retval] BSTR *

pbstrStreamName

)

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

Parameters:

pbstrFileName

[out, retval] - handled file file name.

HRESULT IRsFileHandle::GetStream

(

[out, retval] IStream **

ppStm

)

Access the opened stream. You get the same stream interface that is used by the IRsFileHandle. If you want the stream don't interfere with chunks, use RSFHNDO_NO_CHNK_SUPP flag in Open method.

Parameters:

ppStm

[out, retval] - Returns opened stream.

HRESULT IRsFileHandle::GetFlags

(

[out, retval] RtDWORD *

pdwFlags

)

Returns flags of the stream/file.

Parameters:

pdwFlags

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

HRESULT IRsFileHandle::GetChunksList	(	[in] RtBOOL	bCheckConsistency,
		[out, retval] IRdChunksList **	ppChunksList
	)

Get current chunks list for stream and check stream consistency.

Parameters:

	bCheckConsistency	[out, retval] 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.
	ppRsFileChunk	[out, retval] returned chunks list.

Returns:

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.
other error

HRESULT IRsFileHandle::ScanChunksList

(

[out, retval] IRdChunksList **

ppChunksList

)

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

Parameters:

ppRsFileChunk

[out, retval] returned chunks list.

Returns:

Standard HRESULT processing can be applied to the result.

HRESULT IRsFileHandle::GetChunk	(	[in] RtDWORD	dwIndex,
		[in] RtDWORD	dwFlags,
		[out, retval] IRsFileChunk **	ppRsFileChunk
	)

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

• IRdChunkHeader
• IRdChunkThumbnail
• IRdChunkRsObj
• IRdChunkTags
• IRdChunkHistory
• IRdChunkSystem
• IRdChunkUnknown
• IRdChunksList

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).
	ppRsFileChunk	[out, retval] contains the chunk if it is found.

Returns:

Standard HRESULT processing can be applied to the result.

HRESULT IRsFileHandle::FindChunk	(	[in] IID	iid,
		[in] RtDWORD	dwFromIndex,
		[out, retval] RtDWORD *	pdwIndex
	)

Find specified by its ID.

Parameters:

	iid	[in] Class ID of the chunk.
	dwFromIndex	[in] from which chunk index it will be searched. Specify -1 to search from the first chunk.
	pdwIndex	[out, retval] contains the chunk index if it is found, -1 if it was not found.

Returns:

Standard HRESULT processing can be applied to the result.

HRESULT IRsFileHandle::AddChunk	(	[in] IRsFileChunk *	pRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Add chunk to end of the stream.

Parameters:

	pRsFileChunk	[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.

HRESULT IRsFileHandle::ReplaceChunk	(	[in] RtDWORD	dwIndex,
		[in] IRsFileChunk *	pRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Replace specified chunk.

Parameters:

	dwIndex	[in] Specify index of the chunk you want to replace.
	pRsFileChunk	[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.

HRESULT IRsFileHandle::InsertChunk	(	[in] RtDWORD	dwIndex,
		[in] IRsFileChunk *	pRsFileChunk,
		[in] RtBOOL	bMakeCopy
	)

Insert new chunk at specified position.

Parameters:

	dwIndex	[in] position when the chunk will be inserted.
	pRsFileChunk	[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.

HRESULT IRsFileHandle::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.

HRESULT IRsFileHandle::FlushToStream

(

[in] RtBOOL

bIgnoreBadChunks

)

Save all the chunks into the stream.

Parameters:

[in]

bIgnoreBadChunks

If true, then all the chunks will be written even if some bad or missing are found.

Returns:

Standard HRESULT processing can be applied to the result.

Remarks:

The stream itself.

HRESULT IRsFileHandle::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.

Remarks:

Call this method always if you are not copying the chunks but using only instances.