DR Developer's Guide
DR Interfaces | DR Methods | DR Types and Misc API

IMoaDrMediaOwner


Interface ID: IID_IMoaDrMediaOwner
Pointer type: PIMoaDrMediaOwner
Inheritance: IMoaMmPropOwner
Header file: driservc.h

Description


The IMoaDrMediaOwner interface adds three methods to the IMoaMmPropOwner interface, AttachMedia(), GetMedia(), and SetMedia(). These methods enable an Xtra to retrieve media information from objects such as cast members and movies.

Methods of this interface include pointers to a MoaDrMediaInfo structure as parameters. Before a GetMedia(), SetMedia(), or AttachMedia() call, use IMoaDrUtils::NewMediaInfo() to fill out the structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. Using this call forces you to fill out all the needed parameters. The aux information currently applies only when setting image media.

The formatSymbol and labelSymbol members of this structure are MoaMmSymbols. These symbols are obtained from strings using the host application symbol dictionary, accessed through the StringToSymbol() method of the IMoaMmUtils interface

The labelSymbol refers to the specific chunk of media data you want from the media owner. These labels are generic descriptors for the content media. In the IMoaDrCastMem interface, which inherits from IMoaDrMediaOwner, the labels used are different than the cast member types. For example, a film loop cast member has score media label, a bitmap cast member has an image media label, and so on. These generic labels are used to allow multiple representations for specific media data types. For example, a bitmap is really just one type of image.

The formatSymbol refers to the specific media data type you want to get or set. In Director, the media types represented by these sy mbols are largely platform-specific, except for opaque handles and strings. For example, a bitmap cast member provides image media. On the Macintosh, the format for getting and setting this data is a Macintosh PICT. You use the formatSymbol "macPICT" to access this data. On Windows, packed DIBs are supported; you use the formatSymbol "winDIB" to access this data.

This mechanism uses symbols rather than hardwired constants for future expansion of media access support. The goal is to allow Xtra media assets to export arbitrary labels and formats of their media to other Xtras. (Currently, Xtras can only access media data of other Xtras through the opaque handle provided by composite media. label. So, for example, in the future, someone may make a 3D plug-in, and other Xtras could use GetMedia() to get the "geometry" (label) media in "DXF" (format)).

Methods

Property owner methods

GetProp()
SetProp()

Media owner methods

GetMedia()
SetMedia()
AttachMedia()

AttachMedia()

Syntax

AttachMedia(PIMoaDrMediaOwnerThis,
PMoaDrMediaInfopMediaInfo)

Parameters

This
Pointer to the IMoaDrMediaOwner interface

pMediaInfo
PMoaDrMediaInfo

Returns

MoaError

Description


Attaches media to an object, releasing it from the caller. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the media information structure, specifying NULL for the auxfield and kMoaDrMediaOpts_Nonefor the options field.

On enter, the labelSymbol and formatSymbol fields should be populated with symbols indicating which chunk of media is to be attach (labelSymbol), and what format the media is supplied in (formatSymbol). The mediaData field should hold the data itself (typically a MoaHandle , Macintosh Handle, or Windows global handle)

Upon return, if there is no error, the media has changed ownership and belongs to the host application, and should no longer be referenced by the caller.


GetMedia()

Syntax

GetMedia(PIMoaDrMediaOwnerThis,
PMoaDrMediaInfopMediaInfo)

Parameters

This
Pointer to the IMoaDrMediaOwner interface

pMediaInfo
PMoaDrMediaInfo

Returns

MoaError

Description


Gets media data. This method obtains a copy of the media associated with an object. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the media information structure, specifying NULL for the auxfield and kMoaDrMediaOpts_None for the options field. The caller partially populates a MoaDrMediaInfo struct with symbols indicating the requested chunk of media (labelSymbol) and the requested format (formatSymbol). After the call, the mediaDatafield is populated with the requested data; the type of this field depends on the format requested. The caller then owns the data and is responsible for disposing it, if applicable. Typically this data is either a MoaHandle, a Macintosh Handle or Pointer, or a Windows global handle.


GetProp()

Syntax

GetProp(PIMoaDrMediaOwnerThis,
MoaMmSymbolsymbol,
PMoaMmValuepPropValue)

Parameters

This
Pointer to the IMoaDrMediaOwner interface

symbol
MoaMmSymbolMoaMmSymbol representing the property to get

pPropValue
PMoaMmValuePointer to a MoaMmValue to receive the property's value

Returns

kMoaErr_NoErr Property exists and value was returned
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
kMoaMmErr_InternalError Property exists but couldn't get due to internal err
kMoaMmErr_NoMemForString Couldn't allocate memory for string value data
kMoaErr_OutOfMem Couldn't allocate memory for other value data

Description


Retrieves the value of a specified property.


SetMedia()

Syntax

SetMedia(PIMoaDrMediaOwnerThis,
PMoaDrMediaInfopMediaInfo)

Parameters

This
Pointer to the IMoaDrMediaOwner interface

pMediaInfo
PMoaDrMediaInfo

Returns

MoaError

Description


Sets media data. This method copies caller-supplied media data and associates it with an object. Before making this call, use IMoaDrUtils::NewMediaInfo()to fill out the media information structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the optionsfield. The caller populates a MoaDrMediaInfo structure with symbols indicating the supplied chunk of media (labelSymbol), the supplied format (formatSymbol), and the media data itself (mediaData). If the label and format are supported by the object, a call to this method copies the caller's data and replaces any existing media data for the supplied label for the cast member. Since the data is copied, the caller retains ownership of the media data passed in. Typically, this data is either a MoaHandle, a Macintosh Handle or pointer, or a Windows global handle.


SetProp()

Syntax

SetProp(PIMoaDrMediaOwnerThis,
MoaMmSymbolsymbol,
ConstPMoaMmValuepPropValue)

Parameters

This
Pointer to the IMoaDrMediaOwner interface

symbol
MoaMmSymbolMoaMmSymbol representing the property to set

pPropValue
ConstPMoaMmValuePointer to a ConstPMoaMmValue containing the property value

Returns

kMoaErr_NoErr Property exists and value was set
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
kMoaMmErr_InternalError Property exists, value ok, couldn't - - internal error
kMoaMmErr_NoMemForString Couldn't allocate memory for setting string value data
kMoaErr_OutOfMem Couldn't allocate memory for setting other value data
kMoaMmErr_IntegerExpected Type mismatch: integer value expected
kMoaMmErr_SymbolExpected Type mismatch: symbol value expected
kMoaMmErr_FloatExpected Type mismatch: float value expected
kMoaMmErr_StringExpected Type mismatch: string value expected
kMoaMmErr_PointExpected Type mismatch: point value expected
kMoaMmErr_RectExpected Type mismatch: MoaRect value expected
kMoaMmErr_ValueTypeMismatch Type mismatch: other value expected (non-specific)
kMoaDrErr_CastMemberExpected Type mismatch: CMRef expected

Description


Sets the value of a specified property.

Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.