#include <IMediaUtils.h>

Inheritance diagram for IMediaUtils:

Public Types
enum	{ kDefaultIID = IID_IMEDIAUTILS }

enum	MediaFormatType { kAudio = 0, kVideo, kUnknown }

Public Member Functions
virtual ErrorCode	AddAdornments (IDataBase db, UID itemUID, IMediaAdornmentInfo info)=0

virtual ErrorCode	AddMediaPIToGraphicFrame (IDataBase *db, UID mediaUID, UID frameUID, bool16 alignComponents=kFalse)=0

virtual ErrorCode	AlignMediaComponents (UIDRef mediaRef)=0

virtual bool16	CanConvertToMediaFrame (UIDRef candidateRef)=0

virtual ErrorCode	ChangeMediaLocation (UIDRef mediaRef, const MediaLocation &newLocation=MediaLocation(), IMediaReadFormat *readFormat=nil, bool16 customPosterFromMedia=kFalse, bool16 preservePoster=kFalse)=0

virtual ErrorCode	ChangePoster (UIDRef mediaRef, IMediaAttributes::PosterType newPosterType, const IDFile posterImageFile=nil, IPMStream posterFromMediaStream=nil, bool16 customPosterFromMedia=kFalse, int32 posterTime=0, bool setUndoable=false)=0

virtual ErrorCode	ChangePoster (UIDRef mediaRef, IMediaAttributes::PosterType newPosterType, IPMStream *imageStream)=0

virtual ErrorCode	CreateMediaPageItem (ClassID classID, IDataBase *db, UID frameUID, UID &outMediaUID)=0

virtual ErrorCode	CreateMediaPageItem (ClassID classID, IDataBase *db, UID frameUID, PMRect bounds, UID &outMediaUID)=0

virtual ErrorCode	CreateMediaWithDefaultPoster (ClassID mediaClassID, IDataBase db, UID &outMediaUID, const ClassID formatClassID=kInvalidClass, IPMStream mediaImportStream=nil, IURIData *uriData=nil)=0

virtual IPMStream *	CreatePosterLoResReadStream (UIDRef mediaRef)=0

virtual PMString	ExtractMediaName (const MediaLocation &loc)=0

virtual UID	FindMediaUID (UIDRef &rootUIDRef)=0

virtual UIDRef	GetMediaContentRef (const UIDRef &mediaRef)=0

virtual UID	GetMediaParentUID (IDataBase *db, UID mediaUID)=0

virtual UID	GetParentGraphicFrameUID (const UIDRef &mediaRef)=0

virtual bool16	HasAdornments (UID itemUID, IDataBase db, IMediaAdornmentInfo info)=0

virtual void	InvalidateMediaFrameCaches (IDataBase *db, UID mediaUID)=0

virtual bool16	IsMediaItem (ClassID classID, UID itemUID, IDataBase *db)=0

virtual bool16	GetExportableMediaFile (UIDRef mediaRef, IDFile &outFile)=0

virtual bool16	GetExportableMediaURL (UIDRef const &mediaRef, PMString &url) const =0

virtual bool	GetInstalledVideoSkins (K2Vector< IDFile > &skins) const =0

virtual bool	ResolveSkinNameToFile (PMString const &skin, IDFile &file) const =0

virtual bool	IsLegacyMediaItem (UIDRef mediaRef) const =0

virtual IMediaReadFormat *	FindMediaReadFormatForClassID (ClassID readFormatClassID)=0

virtual IMediaReadFormat *	FindMediaReadFormatForLocation (const MediaLocation &loc)=0

virtual IMediaReadFormat *	FindMediaReadFormatForStream (MediaType mediaType, IPMStream *iPMStream)=0

virtual ErrorCode	CanAccess (const MediaLocation &loc, const MediaType mediaType)=0

virtual ErrorCode	SchedulePlaceMediaFromURL (UIDRef mediaRef, const MediaLocation &loc, bool preserveExistingPoster=false, bool allowDecoding=true)=0

virtual ErrorCode	SchedulePosterFromMedia (UIDRef mediaRef)=0

virtual bool	IsFlashOnlyMedia (ILinkResource *iResource)=0

virtual void	GoToAPERemovalURL ()=0

virtual ErrorCode	ChangeFlashFormatExtension (UID resourceUID, ILinkManager *iLinkMgr)=0

virtual bool	HasUnsupportedExtension (ILinkResource *iResource)=0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

This interface defines utility methods for working with media page items.

Member Enumeration Documentation

enum IMediaUtils::MediaFormatType

Identifiers that denote a media's format type.
Enumerator
kAudio
Media format is an audio format.
kVideo
Media format is a video format.
kUnknown
Media format is not known or not applicable.

Member Function Documentation

virtual ErrorCode IMediaUtils::AddAdornments	(	IDataBase *	db,
		UID	itemUID,
		IMediaAdornmentInfo *	info
	)

pure virtual

Adds top and bottom adornments to a spline item.

Parameters

db	valid pointer to the IDataBase interface of the spline item.
itemUID	UID of the spline item.
info	valid pointer to an IMediaAdornmentInfo interface which will provide the adornment info.

Returns: kSuccess if successful; kFailure if unable to add the adornments.

virtual ErrorCode IMediaUtils::AddMediaPIToGraphicFrame	(	IDataBase *	db,
		UID	mediaUID,
		UID	frameUID,
		bool16	alignComponents = `kFalse`
	)

pure virtual

Attaches a media page item to a graphic frame. Existing children in the graphic frame's IHierarchy are destroyed.

Parameters

db	valid pointer to the IDataBase interface of the page item to be added.
mediaUID	UID of the page item to be added.
frameUID	UID of a graphic frame.
alignComponents	if kTrue, aligns the media page item with the frame and the poster with the media page item. The media page item is resized if it has no intrinsic bounds.

Precondition: if alignComponents is kTrue, make sure IMediaAttributes::enIntrinsicBounds is set before calling this method in order to ensure proper alignment and sizing.

Returns: kSuccess if successful; kFailure if the page item could not be added.

virtual ErrorCode IMediaUtils::AlignMediaComponents ( UIDRef mediaRef )

pure virtual

Aligns the poster with its parent media page item and the media page item with its parent frame. For media with no intrinsic bounds, resizes the media page item according to the rule: if the poster exists, the media page item is sized to the poster bounds; otherwise, the media page item is sized to the parent frame's bounds.

Parameters

mediaRef a valid reference to the media page item.

Precondition: For correct alignment and sizing, make sure IMediaAttributes::enIntrinsicBounds is set before calling this method.

Returns: kSuccess if successful, otherwise an ErrorCode (not necessarily kFailure).

virtual ErrorCode IMediaUtils::CanAccess	(	const MediaLocation &	loc,
		const MediaType	mediaType
	)

pure virtual

Verifies that a media location can be accessed for a MediaType. This method is especially usefulfor checking whether URLs, though well-formed, can nevertheless be supported.

Parameters

loc	a MediaLocation to media content.
mediaType	is either enMovie or enSound.

Returns: kSuccess if the MediaLocation can be accessed, else an ErrorCode that describes why the MediaLocation can not be accessed.

virtual bool16 IMediaUtils::CanConvertToMediaFrame ( UIDRef candidateRef )

pure virtual

Determines if a candidate page item can be converted into a media frame.

Parameters

candidateRef UIDRef of the page item to test for conversion.

Returns: kTrue if the candidate can be converted; kFalse otherwise.

virtual ErrorCode IMediaUtils::ChangeFlashFormatExtension	(	UID	resourceUID,
		ILinkManager *	iLinkMgr
	)

pure virtual

Modifies the extension format of flash based formats(e.g. flv, f4v and swf) by appending .unsupported(translated) in the end

of the URI in order to trigger the missing links workflow.

Parameters

resourceUID	valid existing UID of the imported file.
iLinkMgr	valid existing object of LinkManager class.

Returns: kSuccess if the rename is succesful; kFailure otherwise.

virtual ErrorCode IMediaUtils::ChangeMediaLocation	(	UIDRef	mediaRef,
		const MediaLocation &	newLocation = `MediaLocation()`,
		IMediaReadFormat *	readFormat = `nil`,
		bool16	customPosterFromMedia = `kFalse`,
		bool16	preservePoster = `kFalse`
	)

pure virtual

Changes the location of media content from a specified filter. Changes the poster if it originated from the media.

Parameters

mediaRef	valid UIDRef of existing media page item.
newLocation	specifies the new MediaLocation; if empty, clears the current location.
readFormat	IMediaReadFormat interface that is accessed to obtain the poster IPMStream and media attributes from the media filter (e.g., intrinsic bounds, whether a poster is available, etc); may be nil.
customPosterFromMedia	if True, the poster obtained from IMediaReadFormat is a custom poster from the media source.
preservePoster	if True, does not change the poster

Precondition: if readFormat is non-nil, it must be open before calling this method.

Returns: kSuccess if successful; kFailure if the content could not be replaced.

Postcondition: Caller is responsible for closing readFormat.

virtual ErrorCode IMediaUtils::ChangePoster	(	UIDRef	mediaRef,
		IMediaAttributes::PosterType	newPosterType,
		const IDFile *	posterImageFile = `nil`,
		IPMStream *	posterFromMediaStream = `nil`,
		bool16	customPosterFromMedia = `kFalse`,
		int32	posterTime = `0`,
		bool	setUndoable = `false`
	)

pure virtual

Changes the media poster page item to a specified PosterType. If the change is made, the resulting poster page item will have a new UID.

This method has no affect and returns kSuccess if the current poster already meets the call specifications (see also the description of the customPosterFromMedia param, below). To force a poster change, first call this method with the newPosterType set to IMediaAttributes::eNone.

Parameters

mediaRef	the UIDRef of the parent media page item.
newPosterType	the desired IMediaAttributes::PosterType.
posterImageFile	a valid pointer to the poster image IDFile, required when newPosterType is IMediaAttributes::eProxyImage.
posterFromMediaStream	specifies the IPMStream to a media poster. This parameter is referenced when newPosterType is IMediaAttributes::eFromMedia. If nil, the poster is taken directly from the media content of the parent media page item specified by mediaRef.
customPosterFromMedia	boolean flag that indicates that the poster is a custom poster selected from the media content (e.g., an arbitrary frame in a movie). This flag is referenced only when newPosterType is IMediaAttributes::eFromMedia. The poster is always taken from the specified posterFromMediaStream and always results in a new poster page item. It is an error for this flag to be set to kTrue when posterFromMediaStream is nil.
setUndoable	specifies whether the changePoster command is undoable.

Returns: kSuccess if the change was successful or if no change was necessary; an error code is returned if an error occurred during the change.

virtual ErrorCode IMediaUtils::ChangePoster	(	UIDRef	mediaRef,
		IMediaAttributes::PosterType	newPosterType,
		IPMStream *	imageStream
	)

pure virtual

Changes the media poster page item to a specified PosterType using the image from the imageStream.

Parameters

mediaRef	the UIDRef of the parent media page item.
newPosterType	must be set to IMediaAttributes::eFromMedia.
imageStream	read stream to the poster image data.

Returns: kSuccess if the change was successful; an error code other than kSuccess is returned if an error occurred. kFailure is returned if one or more arguments are invalid.

virtual ErrorCode IMediaUtils::CreateMediaPageItem	(	ClassID	classID,
		IDataBase *	db,
		UID	frameUID,
		UID &	outMediaUID
	)

pure virtual

Creates a media page item of a specified classID, under a specified frame item, and the same size as the frame.

Parameters

classID	the ClassID of the media page item to create.
db	valid pointer to an IDataBase instance.
frameUID	the UID of the frame that will contain the new page item. This method will fail if the frameUID is invalid.
outMediaUID	upon successful return, this is populated with the UID of the new page item.

Returns: kSuccess if successful; kFailure if the page item could not be created.

virtual ErrorCode IMediaUtils::CreateMediaPageItem	(	ClassID	classID,
		IDataBase *	db,
		UID	frameUID,
		PMRect	bounds,
		UID &	outMediaUID
	)

pure virtual

Creates a media page item of a specified classID, under a specified frame item with the specified bounds.

Parameters

classID
db	valid pointer to an IDataBase instance.
frameUID	the UID of the frame that will contain the new page item, or kInvalidUID.
bounds	the PMRect of the new page item bounds.
outMediaUID	upon successful return, this is populated with the UID of the new page item.

Returns: kSuccess if successful; kFailure if the page item could not be created.

virtual ErrorCode IMediaUtils::CreateMediaWithDefaultPoster	(	ClassID	mediaClassID,
		IDataBase *	db,
		UID &	outMediaUID,
		const ClassID	formatClassID = `kInvalidClass`,
		IPMStream *	mediaImportStream = `nil`,
		IURIData *	uriData = `nil`
	)

pure virtual

Creates a media page item with a default poster (standard poster or poster from the media if available).

Parameters

mediaClassID	valid ClassID of the media page item to create.
db	valid IDataBase pointer.
outMediaUID	set to the new media page item UID upon successful return.
frameUID	if valid, attaches the new media page item to the frame as a child page item.
mediaLocation	specifies the location of the media content (optional).
formatClassID	specifies the ClassID of the filter boss capable of reading the mediaImportStream. Required if mediaImportStream is non-nil.
mediaImportStream	a stream to the media content; if non-nil, formatClassID must specify a valid filter boss.
uriData	pass the link URI data if the linked media item is not a file.

Returns: creation status; if successful, returns kSuccess.

virtual IPMStream* IMediaUtils::CreatePosterLoResReadStream ( UIDRef mediaRef )

pure virtual

Creates a read stream to the poster's low-res image (for thumbnails).

Parameters

mediaRef valid UIDRef to a media page item containing a poster page item.

Returns: a valid pointer to an IPMStream object, or nil if an image could not be found.

virtual PMString IMediaUtils::ExtractMediaName ( const MediaLocation & loc )

pure virtual

Extracts an appropriate media name attribute from a MediaLocation.

Parameters

loc	a MediaLocation object.

Returns: PMString media name (may be a null string).

virtual IMediaReadFormat* IMediaUtils::FindMediaReadFormatForClassID ( ClassID readFormatClassID )

pure virtual

Finds the IMediaReadFormat instance for a specified ClassID.

Parameters

readFormatClassID the ID of a boss aggregating the IMediaReadFormat interface.

Returns: valid pointer to an IMediaReadFormat instance, if available; nil if not found.

virtual IMediaReadFormat* IMediaUtils::FindMediaReadFormatForLocation ( const MediaLocation & loc )

pure virtual

Finds the IMediaReadFormat instance that can read from a specified MediaLocation.

Parameters

loc	a MediaLocation to media content.

Returns: valid pointer to an IMediaReadFormat instance which can access the URL and recognize the content. Returns nil if Internet access is not available, or there is no filter available which recognizes the content.

virtual IMediaReadFormat* IMediaUtils::FindMediaReadFormatForStream	(	MediaType	mediaType,
		IPMStream *	iPMStream
	)

pure virtual

Finds an IMediaReadFormat capable of reading media content from a stream.

Parameters

mediaType	is either enMovie or enSound.
iPMStream	is a stream capable of reading the media content.

Returns: valid pointer to an IMediaReadFormat instance if a format filter exists that recognizes the content; nil if a filter was not found.

virtual UID IMediaUtils::FindMediaUID ( UIDRef & rootUIDRef )

pure virtual

Finds the UID of the Media page item under the specified root.

Parameters

rootUIDRef valid UIDRef of IHierarchy root containing a Media page item.

Returns: a valid UID if found; kInvalidUID if not found.

See Also: IHierarchy.

virtual bool16 IMediaUtils::GetExportableMediaFile	(	UIDRef	mediaRef,
		IDFile &	outFile
	)

pure virtual

Retrieves the media file for a specified media page item that can is compatible with the export format (assumed to be SWF for now).

Parameters

mediaRef	refers to the UIDRef of an existing media page item.
outFile	is set to the media file to use for export. For example, if the original placed media file is an MPEG, outFile will refer to the equivalent FLV file.

Returns: kTrue if a file is available; kFalse otherwise.

virtual bool16 IMediaUtils::GetExportableMediaURL	(	UIDRef const &	mediaRef,
		PMString &	url
	)		const

pure virtual

Retrieves the URL for a specified media page item that is compatible with the export format (assumed to be SWF for now).

Parameters

mediaRef	[IN] The UIDRef of an existing media page item.
url	[OUT] The URL of the media page item, if any.

Returns: kTrue if a URL is available; kFalse otherwise.

virtual bool IMediaUtils::GetInstalledVideoSkins ( K2Vector< IDFile > & skins ) const

pure virtual

Retrieves the location of the folder where video skins are stored.

Parameters

skins [OUT] Vector of IDFiles, one per installed skin

Returns: true if successful, else false

virtual UID IMediaUtils::GetMediaParentUID	(	IDataBase *	db,
		UID	mediaUID
	)

pure virtual

Retrieves the parent of a Media page item.

Parameters

db	valid pointer to an IDataBase instance.
mediaUID	valid UID of a media page item.

Returns: a valid UID if found; kInvalidUID if not found.

virtual UID IMediaUtils::GetParentGraphicFrameUID ( const UIDRef & mediaRef )

pure virtual

Retrieves the UID of the graphic frame parent of a Media page item.

Parameters

mediaRef valid UIDRef of a media page item.

Returns: a valid UID if found; kInvalidUID if not found.

virtual void IMediaUtils::GoToAPERemovalURL ( )

pure virtual

Directs to the APE removal GoURL which consists of information regarding the removal of flash

and flash based formats(e.g. flv, f4v and swf) from InDesign.

virtual bool16 IMediaUtils::HasAdornments	(	UID	itemUID,
		IDataBase *	db,
		IMediaAdornmentInfo *	info
	)

pure virtual

Tests if a specified spline item has media adornments.

Parameters

itemUID	valid UID of spline item to test.
db	valid pointer to an IDataBase instance.
info	valid pointer to an IMediaAdornment instance.

Returns: kTrue if media adornments were found on the spline item; kFalse if not.

virtual bool IMediaUtils::HasUnsupportedExtension ( ILinkResource * iResource )

pure virtual

Verifies if the extension contains .unsupported(translated) append in the end of the URI of the imported file.

Parameters

iResource is the resource file to be verified.

Returns: true if the resource has .unsupported extension; false otherwise.

virtual void IMediaUtils::InvalidateMediaFrameCaches	(	IDataBase *	db,
		UID	mediaUID
	)

pure virtual

Invalidates media frame page item caches; if mediaUID is not a frame, then invalidates the caches of its parent frame. This utility should be called whenever a change affects the size of media frame adornments.

Parameters

db	valid pointer to an IDataBase instance.
mediaUID	valid UID of a media page item.

virtual bool IMediaUtils::IsFlashOnlyMedia ( ILinkResource * iResource )

pure virtual

Determines the media resource is in a flash only format that is unsupported(e.g. flv, f4v and swf).

Parameters

iResource the resource whose format to check.

Returns: true if the resource is in an unsupported media format; false otherwise.

virtual bool IMediaUtils::IsLegacyMediaItem ( UIDRef mediaRef ) const

pure virtual

Determines the media page item is legacy media.

Parameters

mediaRef [IN] The UIDRef of an existing media page item.

Returns: true if the page item is legacy media, else false.

virtual bool16 IMediaUtils::IsMediaItem	(	ClassID	classID,
		UID	itemUID,
		IDataBase *	db
	)

pure virtual

Tests if a specified page item is a Media page item of a specified ClassID.

Parameters

classID	the ClassID (boss ID) of a media page item boss based on the kMediaPageItemBoss.
itemUID	valid UID of the page item to test.
db	valid pointer to an IDataBase instance.

Returns: kTrue if the item satisfies the condition; kFalse if not.

virtual bool IMediaUtils::ResolveSkinNameToFile	(	PMString const &	skin,
		IDFile &	file
	)		const

pure virtual

Resolves a skin name to its location on disk.

Parameters

skin	[IN] The name of the skin to resolve
file	[OUT] The location of the skin file on disk

Returns: true if successful, else false

virtual ErrorCode IMediaUtils::SchedulePlaceMediaFromURL	(	UIDRef	mediaRef,
		const MediaLocation &	loc,
		bool	preserveExistingPoster = `false`,
		bool	allowDecoding = `true`
	)

pure virtual

Schedules a command to place a URL-based media item. The command is executed after the media format is decoded and attributes are available.

Parameters

mediaRef	valid existing UIDRef.
loc	is set to the URL. Currently restricted to FLV and F4V video.
bool	if true, the existing poster is preserved; if false, the existing poster may be replaced as necessary.
bool	if true, decode attributes from the media file as needed; if false, does not decode.

Returns: kSuccess if the command was scheduled; kFailure otherwise.

virtual ErrorCode IMediaUtils::SchedulePosterFromMedia ( UIDRef mediaRef )

pure virtual

Schedules a command to replace the media poster with an image from the media. The poster is replaced when the image is decoded and the command completes.

Parameters

mediaRef valid existing UIDRef.

Returns: kSuccess if the command was scheduled; kFailure otherwise.

Enumerator
kAudio	Media format is an audio format.
kVideo	Media format is a video format.
kUnknown	Media format is not known or not applicable.

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation