AAFA Developer Support

Public Member Functions
IAAFMasterMob Interface Reference

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

List of all members.

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

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

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

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

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

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

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

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

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:

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

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

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.

Generated on Wed Jul 4 2012 22:13:28 for AAF COM API by doxygen 1.7.4