The AAFEssenceCodec2 interface adds SetFlavour() to the interfaces of the now deprecated AAFEssenceCodec API. More...

Public Member Functions
HRESULT	SetEssenceAccess ([in] IAAFEssenceAccess *pEssenceAccess)
	Set the essence access associated with the codec.
HRESULT	CountFlavours ([out] aafUInt32 *pCount)
	Some codecs have different variants or flavours of the media handled by a single codec.
HRESULT	GetIndexedFlavourID ([in] aafUInt32 index,[out] aafUID_t *pVariant)
	Some codecs have flavour handled by a single codec.
HRESULT	CountDataDefinitions ([out] aafUInt32 *pCount)
	Some codecs support formats which can encode multiple types of essence.
HRESULT	GetIndexedDataDefinition ([in] aafUInt32 index,[out] aafUID_t *pDataDefID)
	All codecs handle at least one kind of media (picture, sound, control) but some handle more than one.
HRESULT	GetMaxCodecDisplayNameLength ([out] aafUInt32 *pBufSize)
	This method should return the buffer size required to hold the largest display name (and optional flavour) including the terminating NUL character.
HRESULT	GetCodecDisplayName ([in, ref] aafUID_constref flavour,[out, string, size_is(bufSize)] aafCharacter *pName,[in] aafUInt32 bufSize)
	Given a flavour ID, return the human readable name.
HRESULT	CountChannels ([in] IAAFSourceMob fileMob,[in, ref] aafUID_constref essenceKind,[in] IAAFEssenceStream stream,[out] aafUInt16 *pNumChannels)
	Returns the number of channels which this codec can handle of the given essence kind.
HRESULT	GetSelectInfo ([in] IAAFSourceMob fileMob,[in] IAAFEssenceStream stream,[out] aafSelectInfo_t *pSelectInfo)
	Returns a block of information required to select essence by criteria.
HRESULT	ValidateEssence ([in] IAAFSourceMob fileMob,[in] IAAFEssenceStream stream,[in] aafCheckVerbose_t verbose,[in] aafCheckWarnings_t outputWarnings,[in] aafUInt32 bufSize,[out, size_is(bufSize), length_is(pBytesRead)] aafCharacter pErrorText,[out] aafUInt32 *pBytesRead)
	This method validates the metadata associated with the essence data.
HRESULT	Create ([in] IAAFSourceMob fileMob,[in, ref] aafUID_constref flavour,[in, ref] aafUID_constref essenceKind,[in, ref] aafRational_constref sampleRate,[in] IAAFEssenceStream stream,[in] aafCompressEnable_t compEnable)
	Initalize the stream to be of the correct format with no data and default metadata, attach the correct type of EssenceDescriptor to the fileMob, and file in the default metadata on the descriptor also.
HRESULT	Open ([in] IAAFSourceMob fileMob,[in] aafMediaOpenMode_t openMode,[in] IAAFEssenceStream stream,[in] aafCompressEnable_t compEnable)
	Read the metadata from the essence descriptor and/or the formatted data, and prepare the stream for reading the first sample of data.
HRESULT	CountSamples ([in, ref] aafUID_constref essenceKind,[out] aafLength_t *pNumSamples)
	Return the number of samples present on a given essenceKind.
HRESULT	WriteSamples ([in] aafUInt32 nSamples,[in] aafUInt32 buflen,[in, size_is(buflen)] aafDataBuffer_t buffer,[out, ref] aafUInt32 samplesWritten,[out, ref] aafUInt32 bytesWritten)
	Writes data the given essence stream.
HRESULT	ReadSamples ([in] aafUInt32 nSamples,[in] aafUInt32 buflen,[out, size_is(buflen), length_is(bytesRead)] aafDataBuffer_t buffer,[out, ref] aafUInt32 samplesRead,[out, ref] aafUInt32 *bytesRead)
	Read a given number of samples from an opened essence stream.
HRESULT	Seek ([in] aafPosition_t sampleFrame)
	Seek to a particular sample frame on the media.
HRESULT	CompleteWrite ([in] IAAFSourceMob *pFileMob)
	Close the essence stream, ready to open another or Finish.
HRESULT	CreateDescriptorFromStream ([in] IAAFEssenceStream pStream,[in] IAAFSourceMob pSourceMob)
	Given some raw essence (like a WAVE file), create an AAFEssenceDescriptor to match, with all fields filled in.
HRESULT	GetCurrentEssenceStream ([out] IAAFEssenceStream **ppStream)
	Return the current essence stream.
HRESULT	PutEssenceFormat ([in] IAAFEssenceFormat *pFormat)
	Set the format of the one or more parameters.
HRESULT	GetEssenceFormat ([in] IAAFEssenceFormat pFormatTemplate,[out] IAAFEssenceFormat *ppNewFormat)
	Get the format of the one or more parameters by scanning the list of format codes supplied, and filling in the data values.
HRESULT	GetDefaultEssenceFormat ([out] IAAFEssenceFormat **ppNewFormat)
	Returns an essence format object specifying which contains the complete list of essence formats supported by this codec, along with the default values.
HRESULT	GetEssenceDescriptorID ([out] aafUID_t *pDescriptorID)
	Returns the stored object AUID of the essence descriptor class associated with this codec.
HRESULT	GetEssenceDataID ([out] aafUID_t *pEssenceDataID)
	Returns the stored object AUID of the essence data class associated with this codec.
HRESULT	GetIndexedSampleSize ([in, ref] aafUID_constref essenceDefID,[in] aafPosition_t sampleOffset,[out] aafLength_t *pLength)
	Returns the size of the sample at the given offset, and of the given data definition.
HRESULT	GetLargestSampleSize ([in, ref] aafUID_constref essenceDefID,[out] aafLength_t *pLength)
	Returns the size of the largest sample, and of the given data definition.
HRESULT	SetFlavour ([in, ref] aafUID_constref flavour)
	Switches the codec into the specified flavour.
HRESULT	IsCompressionSupported ([in] aafUID_constref compression,[out, retval] aafBoolean_t *pIsSupported)
	Returns AAFTrue if the codec supports opening essence with the specified compression ID.

Detailed Description

The AAFEssenceCodec2 interface adds SetFlavour() to the interfaces of the now deprecated AAFEssenceCodec API.

The AAFEssenceCodec2 interface describes the calls of a plugin which handles encoding media in a particular file format, with optional compression. These methods are used internally by the SDK, and are not exported through the client interface.

The AAFPluginManager keeps a copy of each codec in a table, along with cached copies of pertinant metadata about the codec, and instantiates a copy of the codec for each media stream.

In addition to the specific error results listed for each method, all methods in this interface may also return one of the following values:

AAFRESULT_NULL_PARAM

One of the passed in pointers is NULL.

AAFRESULT_NOMEMORY

insufficient system memory is available to perform the operation.

Objects that implement IAAFEssenceCodec3 also implement the following interfaces:

IAAFPlugin

Definition at line 1986 of file AAFPlugin.idl.

Member Function Documentation

HRESULT IAAFEssenceCodec3::CompleteWrite ( [in] IAAFSourceMob * pFileMob )

Close the essence stream, ready to open another or Finish.

In the case where the client has created essence in an external AAF file, two essence descriptors will need to be updated. After updating the essence descriptor for the file which you are writing (like updating the number of samples), find the essence descriptor associated with pFileMob, and make the same changes to that essence desriptor.

NOTE that pFileMob may be NULL in all cases except writing essence to an external AAF file.

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

pDescriptor 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:

pFileMob [in] Optional second essence descriptor to also update

HRESULT IAAFEssenceCodec3::CountChannels	(	[in] IAAFSourceMob *	fileMob,
		[in, ref] aafUID_constref	essenceKind,
		[in] IAAFEssenceStream *	stream,
		[out] aafUInt16 *	pNumChannels
	)

Returns the number of channels which this codec can handle of the given essence kind.

If the essence kind is not handled by this codec at all, then return zero channels through pNumChannels, and return AAFRESULT_SUCCESS.

The AAFEssenceStream is owned by IAAFEssenceAccess, and therefore should not AddRef() it. The codec may seek and read the supplied open stream as much as required to determine the number of channels, but should not assume that the Open method on the codec has been called (ie: it must parse any header itself). If the given IAAFEssenceStream pointer is NULL then the codec should look at the information in then source mob and essence descriptor (in the mob).

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

pNumChannels is null.

Parameters:

fileMob	[in] Get the number of processable channels on this file mob
essenceKind	[in, ref] This is the type of essence to open
stream	[in] Here is an essence stream with the data
pNumChannels	[out] The number of channels present

HRESULT IAAFEssenceCodec3::CountDataDefinitions ( [out] aafUInt32 * pCount )

Some codecs support formats which can encode multiple types of essence.

For example, interleaved video and audio. This call returns the number of essence data definitions (usually one) supported by this codec.

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

pCount is null.

Parameters:

pCount [out] Number of essence data definitions supported

HRESULT IAAFEssenceCodec3::CountFlavours ( [out] aafUInt32 * pCount )

Some codecs have different variants or flavours of the media handled by a single codec.

(For example, the Avid AVR codec handles multiple AVRs.) This call returns the number of flavours (usually one) supported by this codec.

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

pCount is null.

Parameters:

pCount [out] Number of flavours supported

HRESULT IAAFEssenceCodec3::CountSamples	(	[in, ref] aafUID_constref	essenceKind,
		[out] aafLength_t *	pNumSamples
	)

Return the number of samples present on a given essenceKind.

The assumption is made that all slots of the same essence kind have the same number of samples.

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

pNumSamples is null.

Parameters:

essenceKind	[in, ref] Tell how many samples of this type are on the mob
pNumSamples	[out] The number of samples present of the given essence kind

HRESULT IAAFEssenceCodec3::Create	(	[in] IAAFSourceMob *	fileMob,
		[in, ref] aafUID_constref	flavour,
		[in, ref] aafUID_constref	essenceKind,
		[in, ref] aafRational_constref	sampleRate,
		[in] IAAFEssenceStream *	stream,
		[in] aafCompressEnable_t	compEnable
	)

Initalize the stream to be of the correct format with no data and default metadata, attach the correct type of EssenceDescriptor to the fileMob, and file in the default metadata on the descriptor also.

Prepare the stream for writing the first sample of data.

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

pEssenceAccess 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:

fileMob	[in] Create the essence attached to this file mob
flavour	[in, ref] which flavour of the codec to use
essenceKind	[in, ref] This is the type of essence to create
sampleRate	[in, ref] The sample rate for this essence
stream	[in] Here is an essence stream with the data
compEnable	[in] optionally compressing

HRESULT IAAFEssenceCodec3::CreateDescriptorFromStream	(	[in] IAAFEssenceStream *	pStream,
		[in] IAAFSourceMob *	pSourceMob
	)

Given some raw essence (like a WAVE file), create an AAFEssenceDescriptor to match, with all fields filled in.

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

pStream or pSourceMob is null.

Parameters:

pStream	[in] A raw file stream
pSourceMob	[in] Put the finished descriptor on this source mob

HRESULT IAAFEssenceCodec3::GetCodecDisplayName	(	[in, ref] aafUID_constref	flavour,
		[out, string, size_is(bufSize)] aafCharacter *	pName,
		[in] aafUInt32	bufSize
	)

Given a flavour ID, return the human readable name.

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

pName is null.

Parameters:

flavour	[in, ref] which flavour of the codec to use, or kNoCodecFlavour
pName	[out, string, size_is(bufSize)] Human-readable name of the flavour
bufSize	[in] length of the buffer to hold flavour Name

HRESULT IAAFEssenceCodec3::GetCurrentEssenceStream ( [out] IAAFEssenceStream ** ppStream )

Return the current essence 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

ppStream is null.

Parameters:

ppStream [out] The current essence stream

HRESULT IAAFEssenceCodec3::GetDefaultEssenceFormat ( [out] IAAFEssenceFormat ** ppNewFormat )

Returns an essence format object specifying which contains the complete list of essence formats supported by this codec, along with the default values.

Previous systems required you to "know" what parameters a given codec could support. With this function, a client application can check what the default parameter would be, and change only those which are required. It differs from GetEssenceFormat() in that it GetEssenceFormat() returns the current client-set settings.

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

ppNewFormat is null.

Parameters:

ppNewFormat [out] An essence format with all valid parameter names and values filled in

HRESULT IAAFEssenceCodec3::GetEssenceDataID ( [out] aafUID_t * pEssenceDataID )

Returns the stored object AUID of the essence data class associated with this codec.

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

pEssenceDataID is null.

Parameters:

pEssenceDataID [out] The stored object AUID of the essence data class

HRESULT IAAFEssenceCodec3::GetEssenceDescriptorID ( [out] aafUID_t * pDescriptorID )

Returns the stored object AUID of the essence descriptor class associated with this codec.

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

pDescriptorID is null.

Parameters:

pDescriptorID [out] The stored object AUID of the essence descriptor class

HRESULT IAAFEssenceCodec3::GetEssenceFormat	(	[in] IAAFEssenceFormat *	pFormatTemplate,
		[out] IAAFEssenceFormat **	ppNewFormat
	)

Get the format of the one or more parameters by scanning the list of format codes supplied, and filling in the data values.

The client should have called GetDefaultEssenceFormat() in order to find out what format codes are supported, but you may still get format codes out of range.

The expected bevhavior of this routine is to pre-scan the list for valid format codes before setting any data, and returning AAFRESULT_INVALID_OP_CODEC.

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_ILLEGAL_FILEFMT

One of the format codes is not supported by this codec. Call GetDefaultEssenceFormat() in order to find the list of supported format codes. No data will have been transferred.

AAFRESULT_INVALID_PARM_SIZE

The data supplied with the parameter is not of the correct size. No data will have been transferred.

AAFRESULT_NULL_PARAM

pFormatTemplate or ppNewFormat is null.

Parameters:

pFormatTemplate	[in] An essence format object to use as a template of which fields to read
ppNewFormat	[out] A new essence format object with the data filled in

HRESULT IAAFEssenceCodec3::GetIndexedDataDefinition	(	[in] aafUInt32	index,
		[out] aafUID_t *	pDataDefID
	)

All codecs handle at least one kind of media (picture, sound, control) but some handle more than one.

The kind of media is specified by an AUID representing an AAFDataDef. The number of data definitions is returned by CountDataDefinitions, and cached by the AAFPluginManager.

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

ppDataDef is null.

Parameters:

index	[in] Which data definition to get
pDataDefID	[out] The returned dataDefinition ID

HRESULT IAAFEssenceCodec3::GetIndexedFlavourID	(	[in] aafUInt32	index,
		[out] aafUID_t *	pVariant
	)

Some codecs have flavour handled by a single codec.

(For example, the Avid AVR codec handles multiple AVRs.) The number of flavours is returned by CountFlavours(), and cached by the AAFPluginManager.

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

pVariant is null.

AAFRESULT_OUT_OF_RANGE

index must be >= 0 and < the number of flavours returned in CountFlavours().

Parameters:

index	[in] Which flavour to get the ID for
pVariant	[out] The returned flavour ID

HRESULT IAAFEssenceCodec3::GetIndexedSampleSize	(	[in, ref] aafUID_constref	essenceDefID,
		[in] aafPosition_t	sampleOffset,
		[out] aafLength_t *	pLength
	)

Returns the size of the sample at the given offset, and of the given data definition.

For formats with fixed sample sizes (without a sample offset table), this method should return the standard sample size.

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:

essenceDefID	[in, ref] The ID of the data definition describing the essence
sampleOffset	[in] The zero-based offset to get the size of
pLength	[out] The returned length of the given sample

HRESULT IAAFEssenceCodec3::GetLargestSampleSize	(	[in, ref] aafUID_constref	essenceDefID,
		[out] aafLength_t *	pLength
	)

Returns the size of the largest sample, and of the given data definition.

For formats with fixed sample sizes (without a sample offset table), this method should return the standard sample size.

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:

essenceDefID	[in, ref] The ID of the data definition of the essence
pLength	[out] The returned length of the largest sample

HRESULT IAAFEssenceCodec3::GetMaxCodecDisplayNameLength ( [out] aafUInt32 * pBufSize )

This method should return the buffer size required to hold the largest display name (and optional flavour) including the terminating NUL character.

The client code does not expect this to be equal to any particular display name.

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

pBufSize is null.

Parameters:

pBufSize [out] length of the buffer required to hold the longest flavour Name

HRESULT IAAFEssenceCodec3::GetSelectInfo	(	[in] IAAFSourceMob *	fileMob,
		[in] IAAFEssenceStream *	stream,
		[out] aafSelectInfo_t *	pSelectInfo
	)

Returns a block of information required to select essence by criteria.

The SDK will use this criteria to find the best essence to fit requirements of size or speed.

The AAFEssenceStream is owned by IAAFEssenceAccess, and therefore should not AddRef() it. The codec may seek and read the supplied open stream as much as required to determine the number of channels, but should not assume that the Open method on the codec has been called (ie: it must parse any header itself). If the given IAAFEssenceStream pointer is NULL then the codec should look at the information in then source mob and essence descriptor (in the mob).

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

pSelectInfo is null.

Parameters:

fileMob	[in] Get the number of processable channels on this file mob
stream	[in] Here is an essence stream with the data
pSelectInfo	[out] Information required to select by media criteria

HRESULT IAAFEssenceCodec3::IsCompressionSupported	(	[in] aafUID_constref	compression,
		[out, retval] aafBoolean_t *	pIsSupported
	)

Returns AAFTrue if the codec supports opening essence with the specified compression ID.

Succeeds if all of the following are true:

the pIsSupported pointer is valid.

If this method fails nothing will be written to *pIsSupported.

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

AAFRESULT_SUCCESS

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

AAFRESULT_NULL_PARAM

pIsSupported is null.

Parameters:

compression	[in] The compression to test for support
pIsSupported	[out,retval] Is this compression supported

HRESULT IAAFEssenceCodec3::Open	(	[in] IAAFSourceMob *	fileMob,
		[in] aafMediaOpenMode_t	openMode,
		[in] IAAFEssenceStream *	stream,
		[in] aafCompressEnable_t	compEnable
	)

Read the metadata from the essence descriptor and/or the formatted data, and prepare the stream for reading the first sample of data.

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

pEssenceAccess is null.

AAFRESULT_ESSENCE_NOT_FOUND

The essence could not be located inside of the current file, or by following any of the locators.

Parameters:

fileMob	[in] Open the essence attached to this file mob
openMode	[in] In this mode
stream	[in] Here is an essence stream with the raw data
compEnable	[in] optionally decompressing

HRESULT IAAFEssenceCodec3::PutEssenceFormat ( [in] IAAFEssenceFormat * pFormat )

Set the format of the one or more parameters.

The client should have called GetDefaultEssenceFormat() in order to find out what format codes are supported, but you may still get format codes out of range.

The expected bevhavior of this routine is to pre-scan the list for valid format codes and lengths before setting any data, and returning AAFRESULT_INVALID_OP_CODEC.

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_ILLEGAL_FILEFMT

One of the format codes is not supported by this codec. Call GetDefaultEssenceFormat() in order to find the list of supported format codes. No data will have been transferred.

AAFRESULT_INVALID_PARM_SIZE

The data supplied with the parameter is not of the correct size. No data will have been transferred.

AAFRESULT_NULL_PARAM

pFormat is null.

Parameters:

pFormat [in] An essence format object

HRESULT IAAFEssenceCodec3::ReadSamples	(	[in] aafUInt32	nSamples,
		[in] aafUInt32	buflen,
		[out, size_is(buflen), length_is(*bytesRead)] aafDataBuffer_t	buffer,
		[out, ref] aafUInt32 *	samplesRead,
		[out, ref] aafUInt32 *	bytesRead
	)

Read a given number of samples from an opened essence 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

pTransferParm is null.

AAFRESULT_SMALLBUF

The buffer is not large enough to hold the data

AAFRESULT_CODEC_CHANNELS

SPecified channel numbers are out of range

AAFRESULT_END_OF_DATA

Hit either the end-of-file on a raw essence file, or the end of the essence property. The bytesRead fields inside of pTransferParm correctly reflect the number of bytes and complete samples on each track.

Parameters:

nSamples	[in] Read this many samples
buflen	[in] into a buffer of this size
buffer	[out, size_is(buflen),length_is(*bytesRead)] The transfer buffer
samplesRead	[out, ref] The number of samples actually read
bytesRead	[out, ref] The number of bytes actually read

HRESULT IAAFEssenceCodec3::Seek ( [in] aafPosition_t sampleFrame )

Seek to a particular sample frame on the media.

The sample frame is one frame for picture, and one sample times the number of interleaved channels for audio or other interleaved formats.

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_BADSAMPLEOFFSET

The supplied sample offset is out of range

AAFRESULT_SUCCESS

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

Parameters:

sampleFrame [in] The sample frame to seek to.

HRESULT IAAFEssenceCodec3::SetEssenceAccess ( [in] IAAFEssenceAccess * pEssenceAccess )

Set the essence access associated with the codec.

This routine is called by the SDK when creating or opening an essence stream, in order to give the codec access to the AAFEssenceAccess object, because this is the factory object for creating AAFEssenceFormats. It would be best to store away this pointer inside of the codec. In order to avoid circular reference counting problems DO NOT AddRef this interface pointer. Also, DO NOT save any interface derived from the the saved IAAFEssenceAccess pointer using QueryInterface unless the reference count is restored by a call to ReleaseReference.

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

pEssenceAccess is null.

Parameters:

pEssenceAccess [in] The associated IAAFEssenceAccess

HRESULT IAAFEssenceCodec3::SetFlavour ( [in, ref] aafUID_constref flavour )

Switches the codec into the specified flavour.

Flavour is codec dependent. For example, the DV codec could use a flavour to switch into a legacy mode causing legacy properties to be added which are needed by legacy applications.

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.)

HRESULT_NOT_IMPLEMENTED

flavour not implemented by the codec

Parameters:

flavour [in, ref] the codec flavour to use

HRESULT IAAFEssenceCodec3::ValidateEssence	(	[in] IAAFSourceMob *	fileMob,
		[in] IAAFEssenceStream *	stream,
		[in] aafCheckVerbose_t	verbose,
		[in] aafCheckWarnings_t	outputWarnings,
		[in] aafUInt32	bufSize,
		[out, size_is(bufSize), length_is(pBytesRead)] aafCharacter	pErrorText,
		[out] aafUInt32 *	pBytesRead
	)

This method validates the metadata associated with the essence data.

It may compare fields within the data, and also compare essence data against values in the IAAFFileDescriptor.

The fields bufSize, pErrorText, and pBytes read are used to return a textual description of any problems encountered. If no problems were encountered, pBytesRead should be zero.

This method is used during client and SDK validation, and is not intended for general use.

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

pErrorText is null.

Parameters:

fileMob	[in] Run a check on this file mob
stream	[in] and this essence data stream
verbose	[in] This is the verbosity level of the output
outputWarnings	[in] This determines whether the output contains warnings
bufSize	[in] length of the buffer to hold the error result
pErrorText	[out, size_is(bufSize), length_is(*pBytesRead)] Human-readable text describing problems (or lack therof) with the essence
pBytesRead	[out] The number of result bytes returned

HRESULT IAAFEssenceCodec3::WriteSamples	(	[in] aafUInt32	nSamples,
		[in] aafUInt32	buflen,
		[in, size_is(buflen)] aafDataBuffer_t	buffer,
		[out, ref] aafUInt32 *	samplesWritten,
		[out, ref] aafUInt32 *	bytesWritten
	)

Writes data the given essence 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_ZERO_SAMPLESIZE

The sample size of the stream has not been set.

AAFRESULT_NULL_PARAM

buffer or pResultParm is null.

AAFRESULT_SMALLBUF

One of the supplied buffers is not large enough to hold the given number of samples.

AAFRESULT_CODEC_CHANNELS

SPecified channel numbers are out of range

AAFRESULT_CONTAINERWRITE

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

Parameters:

nSamples	[in] write this many samples
buflen	[in] from a buffer of this size
buffer	[in,size_is(buflen)] from a buffer
samplesWritten	[out, ref] number of samples actually written
bytesWritten	[out, ref] number of bytes actually written

Public Member Functions

Detailed Description

Member Function Documentation