Chapter 3: Editing a File

The RmFile interface allows you to use the ActiveX control to remotely view and edit a RealMedia file that has already been created by the ActiveX control. You can view and edit the following:

clip information, such as title, author, and copyright
file characteristics, such as video width and height, file format, etc.
clip start and end times

You can also paste two or more clips together and add image maps and text files to a clip.

Using the RmFile Interface

Follow these steps to use the RmFile interface.

Create an RmFile using ProducerControl.
Open RmFile, passing in the file's pathname.
View or edit the file's properties, performing operations with the RmFile API.
Save any changes.

RmFile Sample

Below is sample code showing a Visual Basic implementation of how to use the RmFile interface.


'Get the RmFile interface from ProducerControl
Dim MyFile As RmFile
Set MyFile = ProducerControl1.OpenRmFile("c:\foo.rm")


'View/edit the file
Text1.Text = MyFile.Title
MyFile.Description = "A RealMedia file"
MyFile.AddImageMaps "c:\imap.txt"
MyFile.EndTime = 8000


'Save the file
MyFile.Save "c:\foo.rm"


'Open the next file for editing
MyFile.Open "c:\foo2.rm"

Error Handling

Unlike the ProducerControl interface, the RmFile interface does not use OnErrorOccurred events. All errors are returned via returns codes. Like ProducerControl, clients can call GetErrorString to learn more information about a particular return code. Note that the ProducerControl and RmFile interface have separate GetErrorString methods (this is because an error may mean one thing in the ProducerControl content, and something slightly different to RmFile), so be sure to use RmFile's GetErrorString for RmFile's return codes.

One special case where GetErrorString can't be used to obtain error information is when the OpenRmFile method fails. In this case, no RmFile interface is created, so it is not possible to retrieve error information from that interface.

Below is some sample code showing how to handle RmFile errors in Visual Basic:


'Set error handler -- use 'Resume Next' instead of 'GoTo'
On Error Resume Next


'Open the file. Display a generic error msg if the
'file could not be opened.
Set MyFile = ProducerControl1.OpenRmFile("c:\foo.rm")
If Err.Number < 0 Then MsgBox "Could not open file."


'Edit the file
MyFile.Description = "A RealMedia file"
MyFile.EndTime = 8000


'Save the file. Display error info if an error occured
MyFile.Save "c:\foo.rm"
If Err.Number < 0 Then MsgBox MyFile.GetErrorString(Err.Number)

The RmFile interface allows callers to make multiple changes to a file (such as cutting the file, and adding image maps/events before saving). However, it is not possible to paste files after a cut has been performed (but you can cut a pasted file).

The RmFile API

Properties

Read/Write Properties
Name Type Description

Title String title of the clip

Author String author of the clip

Copyright String copyright date and owner of the clip

Description String brief summary of the clip's contents

Keywords String 3 or 4 words that sum up the clip

Rating Enum rates the clip's contents

Selective Record Boolean whether or not the clip can be recorded

Mobile Play Boolean whether or not a mobile player can download the clip

Indexable Boolean whether or not the clip can be indexed by a search engine

StartTime Long start time (in millisecods) of the clip

EndTime Long end time (in milliseconds) of the clip

Read/Write Properties
Name	Type	Description
Title	String	title of the clip
Author	String	author of the clip
Copyright	String	copyright date and owner of the clip
Description	String	brief summary of the clip's contents
Keywords	String	3 or 4 words that sum up the clip
Rating	Enum	rates the clip's contents
Selective Record	Boolean	whether or not the clip can be recorded
Mobile Play	Boolean	whether or not a mobile player can download the clip
Indexable	Boolean	whether or not the clip can be indexed by a search engine
StartTime	Long	start time (in millisecods) of the clip
EndTime	Long	end time (in milliseconds) of the clip

Read Only Properties
Name	Type	Description
IsSingleRate	Boolean	TRUE if clip is a single rate file
IsSureStream	Boolean	TRUE if clip is a SureStream file
HasAudio	Boolean	TRUE if clip contains an audio stream
HasVideo	Boolean	TRUE if clip contains a video stream
HasEvents	Boolean	TRUE if clip contains an events stream
HasImageMaps	Boolean	TRUE if clip has an image map added
VideoHeight	Long	the height of the video (in pixels)
VideoWidth	Long	the width of the video (in pixels)

Methods

Open(InputPathFilename)

Opens a RealMedia file.

Parameters: InputPathFilename (String)

Save(OutputPathFilename)

Saves all changes made to current file.

Parameters: OutputPathFilename (String)

AppendRmFile(RealMediaFilePathname)

Pastes a RealMedia file to the current file.

Parameters: RealMediaFilePathname (String)

AddImageMaps(ImageMapFilePathname)

Adds image maps to the current file.

Parameters: ImageMapFilePathname (String)

AddEvents(EventsFilePathname )

Adds events to the current file.

Parameters: EventsFilePathname (String)

GetErrorString(ErrorNumber, ErrorDescription)

Returns the error description. Not supported under VB Script.

Parameters: ErrorNumber (Long), ErrorDescription (String)