The IAAFEssenceStream interface is an internal interface used by AAFEssenceAccess and essence codecs to read the low-level representation of the essence. More...

Public Member Functions
HRESULT	Write ([in] aafUInt32 bytes,[out, size_is(bytes)] aafDataBuffer_t buffer,[out, ref] aafUInt32 *bytesWritten)
	Write some number of bytes to the stream exactly and with no formatting or compression.
HRESULT	Read ([in] aafUInt32 buflen,[out, size_is(buflen), length_is(pBytesRead)] aafDataBuffer_t pBuffer,[out, ref] aafUInt32 pBytesRead)
	Read some number of bytes from the stream exactly and with no formatting or compression.
HRESULT	Seek ([in] aafPosition_t byteOffset)
	Seek to the absolute byte offset into the stream.
HRESULT	SeekRelative ([in] aafInt32 byteOffset)
	This method should return only the following codes.
HRESULT	GetPosition ([out] aafPosition_t *pPosition)
	Returns the position within the stream.
HRESULT	GetLength ([out] aafLength_t *pLength)
	Returns the length of the stream.
HRESULT	FlushCache ()
	NOTE: Methods which help support optional buffering or caching of the essence data.
HRESULT	SetCacheSize ([in] aafUInt32 itsSize)
	Sets the size of the cache buffer used for further operations.

Detailed Description

The IAAFEssenceStream interface is an internal interface used by AAFEssenceAccess and essence codecs to read the low-level representation of the essence.

There are multiple classes implementing this interface, each representing a different underlying container holding the essence data. The idea of "container" is separate from any formatting such as WAVE or JPEG. Examples of containers (and therefore streams), are essence embedded in AAF files, and essence in a file all by itself (ex. a WAVE file).

Objects which support this interface must be created by methods in IAAFContainerDef, since the container definition is what is used to differentiate between the different streams. If the stream needs a reference to data other than a file pointer (ex. the AAFContainer makes a stream which needs a reference to a structureed storage stream) will have another interface to support the additional behaviour. For an AAF container, the additional interface is IAAFEssenceDataStream.

NOTE: The SDK will init the representation of this object with the correct path and open the underlying file before handing out an interface pointer. Hence, there is no Open method on the stream.

Definition at line 3318 of file AAFPlugin.idl.

Member Function Documentation

HRESULT IAAFEssenceStream::FlushCache ( )

NOTE: Methods which help support optional buffering or caching of the essence data.

Caching is not required to be supported, and may actually reduce performance. on some platforms. If your stream does not support caching, then return AAFRESULT_SUCCESS for these calls. Ensure that all bits are written. The caller of this interface is required to call FlushCache before releasing the stream.

This method should return only the following codes. If more than one of the listed errors is in effect\, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. \(This is the only code indicating success.\)

AAFRESULT_STREAM_FULL

The essence can not be written because of a fault such as a disk full error in the underlying operating system.

HRESULT IAAFEssenceStream::GetLength ( [out] aafLength_t * pLength )

Returns the length of the stream.

This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

pLength is null.
Parameters:

pLength [out] The length of the stream.

HRESULT IAAFEssenceStream::GetPosition ( [out] aafPosition_t * pPosition )

Returns the position within the stream.

This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

pPosition is null.
Parameters:

pPosition [out] The position within the stream.

HRESULT IAAFEssenceStream::Read	(	[in] aafUInt32	buflen,
		[out, size_is(buflen), length_is(*pBytesRead)] aafDataBuffer_t	pBuffer,
		[out, ref] aafUInt32 *	pBytesRead
	)

Read some number of bytes from the stream exactly and with no formatting or compression.

This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

pBuffer or pBytesRead is null.

AAFRESULT_END_OF_ESSENCE

Hit either the end-of-file on a raw essence file, or the end of the essence property. The pBytesRead parameter correctly reflects the number of bytes actually read.
Parameters:

buflen [in] to a buffer of this size

pBuffer [out, size_is(buflen), length_is(*pBytesRead)] here is the buffer

pBytesRead [out,ref] Return bytes actually read

HRESULT IAAFEssenceStream::Seek ( [in] aafPosition_t byteOffset )

Seek to the absolute byte offset into the stream.

Parameters:

byteOffset [in] The absolute byte offset into the stream.

HRESULT IAAFEssenceStream::SeekRelative ( [in] aafInt32 byteOffset )

This method should return only the following codes.

If more than one of the listed errors is in effect\\, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. \\(This is the only code indicating success.\\)

AAFRESULT_STREAM_BOUNDS

The new position would be outside of the bounds of the stream.) Seek forward or backward the given byte count. This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)

AAFRESULT_STREAM_BOUNDS

The new position would be outside of the bounds of the stream.
Parameters:

byteOffset [in] The relative byte offset into the stream.

HRESULT IAAFEssenceStream::SetCacheSize ( [in] aafUInt32 itsSize )

Sets the size of the cache buffer used for further operations.

Destroys the current contents of the cache. This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)
Parameters:

itsSize [in] The size of the cache buffer. Zero is a valid size, and means to turn caching off

HRESULT IAAFEssenceStream::Write	(	[in] aafUInt32	bytes,
		[out, size_is(bytes)] aafDataBuffer_t	buffer,
		[out, ref] aafUInt32 *	bytesWritten
	)

Write some number of bytes to the stream exactly and with no formatting or compression.

This method should return only the following codes. If more than one of the listed errors is in effect, it should return the first one encountered in the order given below:

AAFRESULT_SUCCESS

succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

pBuffer or pBytesRead is null.

AAFRESULT_STREAM_FULL

The essence can not be written because of a fault such as a disk full error in the underlying operating system.
Parameters:

bytes [in] the number of bytes to write

buffer [out, size_is(bytes)] the buffer that contains at least bytes

bytesWritten [out,ref] the number of bytes actually written from the buffer

buflen	[in] to a buffer of this size
pBuffer	[out, size_is(buflen), length_is(*pBytesRead)] here is the buffer
pBytesRead	[out,ref] Return bytes actually read

bytes	[in] the number of bytes to write
buffer	[out, size_is(bytes)] the buffer that contains at least bytes
bytesWritten	[out,ref] the number of bytes actually written from the buffer

Public Member Functions

Detailed Description

Member Function Documentation