The IAAFMasterMob interface is implemented by objects which provide access to the File Source Mobs and EssenceData objects. More...

Public Member Functions
HRESULT	Initialize ()
	Initializes a newly allocated, empty IAAFMasterMob-supporting object.
HRESULT	AddMasterSlot ([in] IAAFDataDef pDataDef,[in] aafSlotID_t sourceSlotID,[in] IAAFSourceMob pSourceMob,[in] aafSlotID_t masterSlotID,[in, string] aafCharacter_constptr pSlotName)
	This function adds a slot to the specified Master Mob that references the specified a slot in the specified Source Mob.
HRESULT	GetTapeName ([in] aafUInt32 masterSlotID,[out, size_is(bufSize), string] aafCharacter *pTapeName,[in] aafUInt32 bufSize)
	Finds the tape Source Mob associated with a Master Mob slot and writes the name of the tape, which is stored in the Mobs Name property, into the pTapeName buffer.
HRESULT	GetTapeNameBufLen ([in] aafUInt32 masterSlotID,[out] aafUInt32 *pLen)
	Returns the length of buffer required for the GetTapeName() method.
HRESULT	GetNumRepresentations ([in] aafSlotID_t slotID,[out, retval] aafNumSlots_t *pNumReps)
	This function returns the number of media representations available for the specified SlotID on a specified Master Mob.
HRESULT	GetRepresentation ([in] aafSlotID_t slotID,[in] aafUInt32 index,[out] IAAFSegment **ppSourceClip)
	This method returns the indexed media representation for the specified Master Mob, SlotID, and index.
HRESULT	GetCriteriaSegment ([in] aafSlotID_t slotID,[in] aafMediaCriteria_t pCriteria,[out] IAAFSegment *ppSegment)
	Returns the Segment on the specified slot of a Master Mob that references the Source Mob that best meets the specified criteria.
HRESULT	AppendPhysSourceRef ([in] aafRational_t editrate,[in] aafSlotID_t aMobSlot,[in] IAAFDataDef *pEssenceKind,[in] aafSourceRef_t ref,[in] aafLength_t srcRefLength)
	Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, appending it to existing Mob data.
HRESULT	NewPhysSourceRef ([in] aafRational_t editrate,[in] aafSlotID_t aMobSlot,[in] IAAFDataDef *pEssenceKind,[in] aafSourceRef_t ref,[in] aafLength_t srcRefLength)
	Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, replacing any existing Mob data.
HRESULT	CreateEssence ([in] aafSlotID_t masterSlotID,[in] IAAFDataDef pMediaKind,[in, ref] aafUID_constref codecID,[in] aafRational_t editRate,[in] aafRational_t samplerate,[in] aafCompressEnable_t Enable,[in] IAAFLocator destination,[in, ref] aafUID_constref fileFormat,[out] IAAFEssenceAccess **access)
	Creates a single channel stream of essence.
HRESULT	CreateMultiEssence ([in, ref] aafUID_constref codecID,[in] aafUInt16 arrayElemCount,[in, ref, size_is(arrayElemCount)] aafmMultiCreate_t mediaArray,[in] aafCompressEnable_t Enable,[in] IAAFLocator destination,[in, ref] aafUID_constref fileFormat,[out] IAAFEssenceMultiAccess **access)
	Creates a multi-channel interleaved stream of essence.
HRESULT	OpenEssence ([in] aafSlotID_t slotID,[in] aafMediaCriteria_t mediaCrit,[in] aafMediaOpenMode_t openMode,[in] aafCompressEnable_t compEnable,[out] IAAFEssenceAccess *access)
	Opens a single channel of a file mob.
HRESULT	OpenMultiEssence ([in] aafSlotID_t slotID,[in] aafMediaCriteria_t mediaCrit,[in] aafMediaOpenMode_t openMode,[in] aafCompressEnable_t compEnable,[out] IAAFEssenceMultiAccess *access)
	Opens a all channels associated with a file mob.
HRESULT	CountChannels ([in] aafSlotID_t slotID,[in] aafMediaCriteria_t mediaCrit,[in] IAAFDataDef pMediaKind,[out] aafUInt16 *numCh)
	Takes an opaque handle, a master mob reference, and a slot ID so that it may be called before the essence is opened.

Detailed Description

The IAAFMasterMob interface is implemented by objects which provide access to the File Source Mobs and EssenceData objects.

The Master Mob object is used to provide a level of indirection for accessing Source Mobs from Composition Mobs.

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_NOMEMORY

insufficient system memory is available to perform the operation.

Objects that implement IAAFMasterMob also implement the following interfaces:

Definition at line 13006 of file AAF.idl.

Member Function Documentation

HRESULT IAAFMasterMob::AddMasterSlot	(	[in] IAAFDataDef *	pDataDef,
		[in] aafSlotID_t	sourceSlotID,
		[in] IAAFSourceMob *	pSourceMob,
		[in] aafSlotID_t	masterSlotID,
		[in, string] aafCharacter_constptr	pSlotName
	)

This function adds a slot to the specified Master Mob that references the specified a slot in the specified Source Mob.

The new slot in the Master Mob contains a Source Clip that specifies the Source Mob in its source reference properties. Typically this is done automatically by passing the Master Mob handle to AAFMedia::Create, but this function allows you to add it later.

Note: If pSlotName is passed in with zero length, then the slot is not assigned a name. Slot names are not used by the SDK, and exist only so the user can name slots.

Succeeds if all of the following are true: (more conditions here)

If this method fails no state is changed.

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

One or more of the following parameters are NULL pSourceMob, pSlotName, and pDataDef.

AAFRESULT_INVALID_DATADEF

The data kind of the source MOB slot to be added to the Master Mob does not match what is specfied in pDataDef.

AAFRESULT_SLOT_NOTFOUND

The specified Source Mob slot was not found.

AAFRESULT_SLOT_EXISTS

The specified Master slot ID already exists.

Parameters:

pDataDef	[in] Data kind of new slot. Requires a data kind valid for a media stream. Valid data kinds are: Picture Sound
sourceSlotID	[in] Slot ID of the Source Mob slot to be added to the Master Mob
pSourceMob	[in] Source Mob containing the slot to be added to the Master Mob
masterSlotID	[in] SlotID assigned to the new Master Mob slot
pSlotName	[in, string] Name to assign to new slot in Master Mob

HRESULT IAAFMasterMob::AppendPhysSourceRef	(	[in] aafRational_t	editrate,
		[in] aafSlotID_t	aMobSlot,
		[in] IAAFDataDef *	pEssenceKind,
		[in] aafSourceRef_t	ref,
		[in] aafLength_t	srcRefLength
	)

Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, appending it to existing Mob data.

If a physical Source Mob, such as a File Source Mob or tape Source Mob, references another physical Source Mob as its ancestor, with no pulldown, then this function makes the connection between the two.

Functionally, this is a helper function to create a slot with an AAFSourceClip referencing a particular piece of media. This function takes many parameters because the components of an aafSourceRef_t have been broken out as separate parameters.

The ancestor of an AAFSourceMob with an AAFFileDescriptor is often an AAFTapeDescriptor or NIL.

Succeeds if all of the following are true:

the pSourceRefObj pointer is valid.
the pEssenceKind pointer is valid. (other conditions here)

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

pSourceRefObj or pEssenceKind is null.

(other codes here.)

Parameters:

editrate	[in] Edit rate of slot to contain reference
aMobSlot	[in] SlotID of slot to contain reference
pEssenceKind	[in] Data kind of slot to contain reference. Requires a data kind valid for a essence stream. Valid data kinds are: Picture Sound
ref	[in] Reference to a Physical Source Mob
srcRefLength	[in] Length of the Source Clip

HRESULT IAAFMasterMob::CountChannels	(	[in] aafSlotID_t	slotID,
		[in] aafMediaCriteria_t *	mediaCrit,
		[in] IAAFDataDef *	pMediaKind,
		[out] aafUInt16 *	numCh
	)

Takes an opaque handle, a master mob reference, and a slot ID so that it may be called before the essence is opened.

Returns the number of interleaved essence channels of a given type in the essence stream referenced by the given file mob.

If the data format is not interleaved, then the answer will always be zero or one. This function correctly returns zero for essence types not handled by a given codec, and handles codecs which work with multiple essence types.

Parameters:

slotID	[in] On this slot
mediaCrit	[in] using this essence criteria
pMediaKind	[in] for this essence type
numCh	[out] How many channels?

HRESULT IAAFMasterMob::CreateEssence	(	[in] aafSlotID_t	masterSlotID,
		[in] IAAFDataDef *	pMediaKind,
		[in, ref] aafUID_constref	codecID,
		[in] aafRational_t	editRate,
		[in] aafRational_t	samplerate,
		[in] aafCompressEnable_t	Enable,
		[in] IAAFLocator *	destination,
		[in, ref] aafUID_constref	fileFormat,
		[out] IAAFEssenceAccess **	access
	)

Creates a single channel stream of essence.

Convenience functions exist to create audio or video essence, and a separate call (MultiCreate) exists to create interleaved audio and video data.

The essence handle from this call can be used with WriteDataSamples and possibly WriteDataLines, but NOT with WriteMultiSamples.

If you are creating the essence, and then attaching it to a master mob, then the "masterMob" field may be left NULL. For video, the sampleRate should be the edit rate of the file mob. For audio, the sample rate should be the actual samples per second.

Parameters:

masterSlotID	[in]
pMediaKind	[in] create essence of this type
codecID	[in, ref] using this codec
editRate	[in] with this edit rate
samplerate	[in] with this sample rate
Enable	[in] optionally compressing it
destination	[in] Optionally create the file HERE.
fileFormat	[in, ref] with this format
access	[out] Return an essence access on the essence.

HRESULT IAAFMasterMob::CreateMultiEssence	(	[in, ref] aafUID_constref	codecID,
		[in] aafUInt16	arrayElemCount,
		[in, ref, size_is(arrayElemCount)] aafmMultiCreate_t *	mediaArray,
		[in] aafCompressEnable_t	Enable,
		[in] IAAFLocator *	destination,
		[in, ref] aafUID_constref	fileFormat,
		[out] IAAFEssenceMultiAccess **	access
	)

Creates a multi-channel interleaved stream of essence.

The essence handle from this call can be used with WriteDataSamples or WriteMultiSamples but NOT with or WriteDataLines.

If you are creating the essence, and then attaching it to a master mob, then the "masterMob" field may be left NULL.

Parameters:

codecID	[in, ref] using this codec
arrayElemCount	[in] this many channels
mediaArray	[in,ref,size_is(arrayElemCount)] using these definitions
Enable	[in] optionally compressing it
destination	[in] Optionally create the file HERE.
fileFormat	[in, ref] with this format
access	[out] Return an essence access on the essence.

HRESULT IAAFMasterMob::GetCriteriaSegment	(	[in] aafSlotID_t	slotID,
		[in] aafMediaCriteria_t *	pCriteria,
		[out] IAAFSegment **	ppSegment
	)

Returns the Segment on the specified slot of a Master Mob that references the Source Mob that best meets the specified criteria.

This function will work whether multiple media representations exist or not.

The returned segment is AddRef()ed before it is returned.

Succeeds if all of the following are true:

the ppSegment pointer is valid.

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

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

ppSegment arg is NULL.

AAFRESULT_SLOT_NOTFOUND

The specified Master Slot was not found.

Parameters:

slotID	[in] Slot ID
pCriteria	[in] Index of requested representation. Note: the aafMediaCriteria_t is defined as the following structure: typedef struct { aafCriteriaType_t type; aafCriteriaProc_t proc; } aafMediaCriteria_t;

The type field can have one of the following values: typedef enum { kAAFAnyRepresentation = 0, kAAFFastestRepresentation, kAAFBestFidelityRepresentation, kAAFSmallestRepresentation, kAAFUseRepresentationProc } aafCriteriaType_t;

Parameters:

ppSegment [out] Requested Segment

HRESULT IAAFMasterMob::GetNumRepresentations	(	[in] aafSlotID_t	slotID,
		[out, retval] aafNumSlots_t *	pNumReps
	)

This function returns the number of media representations available for the specified SlotID on a specified Master Mob.

This function is meant to work with GetRepresentationSourceClip, so that you can iterate through all of the choices yourself. In most cases, you can use GetCriteriaSourceClip to handle multiple representations. This function and GetRepresentationSourceClip are lower-level functions.

Succeeds if all of the following are true:

the pNumReps pointer is valid.

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

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

pNumReps arg is NULL.

AAFRESULT_SLOT_NOTFOUND

The Master Slot specified by slotID was not found.

Parameters:

slotID	[in] SlotID
pNumReps	[out, retval] number of representations

HRESULT IAAFMasterMob::GetRepresentation	(	[in] aafSlotID_t	slotID,
		[in] aafUInt32	index,
		[out] IAAFSegment **	ppSourceClip
	)

This method returns the indexed media representation for the specified Master Mob, SlotID, and index.

This call is meant to work with GetNumRepresentations, so that you can iterate through all of the choices yourself. This method uses an integer index, not an iterator. The function GetRepresentationSourceClip takes an index between 1 and the number of representations [inclusive], and returns the indexed Source Mob. You can make calls to functions such as AAFMedia::GetVideoInfo and AAFMedia::IsMediaContiguous to determine which media is the best fit.

The returned source clip is AddRef()ed before it is returned.

Succeeds if all of the following are true:

the ppSourceClip pointer is valid.

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

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

ppSourceClip arg is NULL.

AAFRESULT_SLOT_NOTFOUND

The specified Master Slot was not found.

AAFRESULT_BADINDEX

No Source Mob at specified index.

Parameters:

slotID	[in] Slot ID
index	[in] Index of requested representation
ppSourceClip	[out] Requested Source Clip

HRESULT IAAFMasterMob::GetTapeName	(	[in] aafUInt32	masterSlotID,
		[out, size_is(bufSize), string] aafCharacter *	pTapeName,
		[in] aafUInt32	bufSize
	)

Finds the tape Source Mob associated with a Master Mob slot and writes the name of the tape, which is stored in the Mobs Name property, into the pTapeName buffer.

The buffer is allocated by the caller. The size of the buffer is given by bufSize. If the property name has not yet been set, a zero-length string will be written (that is, only the trailing null character).

Caller may call GetTapeNameBufLen() to determine the required buffer size.

Succeeds if all of the following are true:

the pTapeName pointer is valid.
the specified master slot was found.
the specified master slot contains a tape mob.
bufSize indicates the buffer is large enough to hold the name.

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

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

pTapeName arg is NULL.

AAFRESULT_SLOT_NOTFOUND

The specified Master Slot was not found.

AAFRESULT_NOT_TAPEMOB

The specified Master Slot does not contain a Tape MOB.

AAFRESULT_SMALLBUF

bufSize indicates the buffer is too small to hold the string.

Parameters:

masterSlotID	[in] SlotID of the Master Mob slot
pTapeName	[out, size_is(bufSize), string] The returned name
bufSize	[in] the size of the pTapeName buffer

HRESULT IAAFMasterMob::GetTapeNameBufLen	(	[in] aafUInt32	masterSlotID,
		[out] aafUInt32 *	pLen
	)

Returns the length of buffer required for the GetTapeName() method.

The value is placed into the location specified by pLen. The value will include space required for the trailing null character.

Succeeds if all of the following are true:

the pLen pointer is valid.

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

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

pLen arg is NULL.

AAFRESULT_SLOT_NOTFOUND

The specified Master Slot was not found.

AAFRESULT_NOT_TAPEMOB

The specified Master Slot does not contain a Tape MOB.

Parameters:

masterSlotID	[in] SlotID of the Master Mob slot
pLen	[out] required buffer length

HRESULT IAAFMasterMob::Initialize ( )

Initializes a newly allocated, empty IAAFMasterMob-supporting object.

This method must be called after allocation, and before any other method can be called.

Succeeds if:

Initialize() has not yet been called on this object.

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_ALREADY_INITIALIZED

Initialize() has already been called on this object.

HRESULT IAAFMasterMob::NewPhysSourceRef	(	[in] aafRational_t	editrate,
		[in] aafSlotID_t	aMobSlot,
		[in] IAAFDataDef *	pEssenceKind,
		[in] aafSourceRef_t	ref,
		[in] aafLength_t	srcRefLength
	)

Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, replacing any existing Mob data.

If a physical Source Mob, such as a File Source Mob or tape Source Mob, references another physical Source Mob as its ancestor, with no pulldown, then this function makes the connection between the two.

Functionally, this is a helper function to create a slot with an AAFSourceClip referencing a particular piece of media. This function takes many parameters because the components of an aafSourceRef_t have been broken out as separate parameters.

The ancestor of an AAFSourceMob with an AAFFileDescriptor is often an AAFTapeDescriptor or NIL.

Succeeds if all of the following are true:

the pSourceRefObj pointer is valid.
the pEssenceKind pointer is valid. (other conditions here)

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_NOT_INITIALIZED

This object has not yet had Initialize() called on it.

AAFRESULT_NULL_PARAM

pSourceRefObj or pEssenceKind is null.

(other codes here.)

Parameters:

editrate	[in] Edit rate of slot to contain reference
aMobSlot	[in] SlotID of slot to contain reference
pEssenceKind	[in] Data kind of slot to contain reference. Requires a data kind valid for a essence stream. Valid data kinds are: Picture Sound
ref	[in] Reference to a Physical Source Mob
srcRefLength	[in] Length of the Source Clip

HRESULT IAAFMasterMob::OpenEssence	(	[in] aafSlotID_t	slotID,
		[in] aafMediaCriteria_t *	mediaCrit,
		[in] aafMediaOpenMode_t	openMode,
		[in] aafCompressEnable_t	compEnable,
		[out] IAAFEssenceAccess **	access
	)

Opens a single channel of a file mob.

If the essence is interleaved, then it will be di-interleaved when samples are read. This routine follows the locator, and may call the locator failure callback if the essence can not be found. If the failure callback finds the essence, then this routine will return normally.

The essence handle from this call can be used with ReadDataSamples and possibly ReadDataLines, but NOT with ReadMultiSamples.

NOTE: If a locator is followed, then essencePtr may reference ANOTHER file object, which must be closed on file close.

Parameters:

slotID	[in] On this slot
mediaCrit	[in] using this essence criteria
openMode	[in] ReadOnly or Append
compEnable	[in] optionally decompressing
access	[out] Return an essence access on the essence.

HRESULT IAAFMasterMob::OpenMultiEssence	(	[in] aafSlotID_t	slotID,
		[in] aafMediaCriteria_t *	mediaCrit,
		[in] aafMediaOpenMode_t	openMode,
		[in] aafCompressEnable_t	compEnable,
		[out] IAAFEssenceMultiAccess **	access
	)

Opens a all channels associated with a file mob.

This routine follows the locator, and may call the locator failure callback if the essence can not be found. If the failure callback finds the essence, then this routine will return normally.

The essence handle from this call can be used with WriteMultiSamples but NOT with WriteDataSamples.

Parameters:

slotID	[in] On this slot
mediaCrit	[in] using this essence criteria
openMode	[in] ReadOnly or Append
compEnable	[in] optionally decompressing
access	[out] Return an essence access on the essence.

Public Member Functions

Detailed Description

Member Function Documentation