AEEncoder

Derived From: none
Declared in: AEEncoder.h
Library: libaeencoder.a
Summary: more...

AEEncoder is the base class for all encoders used by FlipSide A.E. There are a maximum of 5 methods that an AEEncoder subclass should implement. Of those five, only Encode() is required. The AEEncoder baseclass does several things for you.

Reads in saved settings upon creation, and if there are no settings saved, calls the LoadDefault* methods to load the default values.
Saves settings before the object is destroyed. Settings are saved in: <USER SETTINGS DIRECTORY>/FlipSide Software/FlipSide A.E./<ADDON NAME> Settings
Provides a utility method FindExecutable() to find a program on any queryable drive on the users system.

Documentation: You should provide an html document with a production add-on. It should be named the same as your Add-on's name with a .html extension. FlipSide A.E. may soon be providing a way to pull up your help file from the GUI, and these are the most likely requirements. It should be installed into the same file structures as the ones that shipped with FlipSide A.E. Feel free to use them as a template. In fact we encourage it. You may also use the flipsideae_icon.gif file as your BeBits icon. If you would like to notify me of its publication we will be happy to link to it from both the FlipSide A.E. hompepage, and it's BeBits page. We are also here to help in any way we can to make your encoder work as well as possible.

Constructor and Destructor

AEEncoder()

AEEncoder(const char* encoderName)

Sets the encoder add-ons name, and loads saved settings. If your Add-on requires the service of external applications (e.g. command line apps) you should use the FindExecutable() method to get the full path for the application. This should be done in the constructor and not in Encode(). If you can't find the application, set the protected member error to FSS_EXE_NOT_FOUND.

~AEEncoder()

~AEEncoder()

Saves settings to the users settings directory, and then deletes the objects allocated memory.

Member Functions

CheckForCancel()

protected bool CheckForCancel()

Returns true if the user has canceled encoding.

Encode()

int32 Encode(BMessage* encodeMessage)

This is the meat of a FlipSide A.E. Encoder Add-on. encodeMessage is a pointer to a FSS_ENCODE Message. The details of the contents of the message are described below. Basicly, it contains the path to the input file, the path to the output file, desired attribute values, and a pointer to a BMessenger for the status bar. So here are the rules of the game:

The input file is not guaranteed to be of a type you can handle. You should check the mime type to see if it's one you can handle. (BNodeInfo is good for this)

FlipSide A.E. guarantees that the directory that the output file is to reside exists.

You should you use the BMessenger provided to send B_UPDATE_STATUS_BAR messages to FlipSide A.E. Don't bother adding anything but "delta" to the message. All other names are filtered out. You can optionally use the FSS_SETMAX_STATUS_BAR message to set the maximum value of the status bar. You can't reset the status bar from an add-on (the message is dropped by a filter). The status bar is reset for you by FlipSide A.E. after every call to Encode()

You must call CheckForCancel() at least once (just before returning B_OK). If you are doing the encoding in a looping structure (or checking for output from an external encoder), you should check for cancel at the beginning of the loop.

You can retrieve any of your settings by traversing your protected BMenu* menu. The structure of this menu is set by you in LoadDefaultMenu()

Use only one of the following return codes for this function.

RETURN VALUES

B_OK Everything went great!

B_ERROR Damn! Something screwed up.

FSS_CANCEL_ENCODING What? You don't want to play anymore?

FSS_EXE_NOT_FOUND Now where did I put it?

FSS_INPUT_NOT_SUPPORTED I can't handle this input file!

RETURN VALUES
B_OK	Everything went great!
B_ERROR	Damn! Something screwed up.
FSS_CANCEL_ENCODING	What? You don't want to play anymore?
FSS_EXE_NOT_FOUND	Now where did I put it?
FSS_INPUT_NOT_SUPPORTED	I can't handle this input file!

FindExecutable()

protected int32 FindExecutable(const char* executable, char* path)

A utility method that queries all queriable drives (starting with /boot) for executable. If found, it copies the full path to the executable into path and returns B_OK. If it cannot find executable, path remains unchanged and FSS_EXE_NOT_FOUND is returned. If an error occured creating the query, B_ERROR is returned.

RETURN VALUES

B_OK We found it!

B_ERROR Ooops!

FSS_EXE_NOT_FOUND Now where did I put it?

RETURN VALUES
B_OK	We found it!
B_ERROR	Ooops!
FSS_EXE_NOT_FOUND	Now where did I put it?

GetMenu()

BMenu* GetMenu()

Returns a pointer to the encoder's menu.

GetName()

const char* GetName()

Returns a pointer to the encoder's name.

GetPattern(), SetPattern()

const char* GetPattern()

void SetPattern(const char* value)

These functions get and set the output file pattern for the encoder.

InitCheck()

int32 InitCheck()

Returns the status of the initialization.

RETURN VALUES

B_OK Everything's peachy.

B_ERROR Not cool.

FSS_EXE_NOT_FOUND Now where did I put it?

RETURN VALUES
B_OK	Everything's peachy.
B_ERROR	Not cool.
FSS_EXE_NOT_FOUND	Now where did I put it?

InitEncoder(), UninitEncoder()

int32 InitEncoder()

int32 UninitEncoder()

InitEncoder() is called before a session of Encode()'s. You should only override this is you have data that should persist over an entire encoding session. This is very rare. If you do override it, you have to call AEEncoder::InitEncoder() at the beginning of your method. UninitEncoder() is called at the end of the session. It will always be called, even when a user cancels, or a call to Encode() fails. It should be used to release any resources allocated in InitEncoder().

RETURN VALUES

B_OK Sweeeeeet!

B_ERROR Uh Oh!

RETURN VALUES
B_OK	Sweeeeeet!
B_ERROR	Uh Oh!

LoadDefaultPattern()

int32 LoadDefaultPattern()

The Default DefaultPattern is the empty string. I strongly suggest overriding this method to provide a sane default for the users of your add-on. The variables available to you for replacement are:

Variable Meaning

%a Artist

%n Album

%t Title

%y Year

%c Comment

%k Track

%g Genre

RETURN VALUES

B_OK Awsome!

B_ERROR Something is really screwed.

Variable	Meaning
%a	Artist
%n	Album
%t	Title
%y	Year
%c	Comment
%k	Track
%g	Genre

RETURN VALUES
B_OK	Awsome!
B_ERROR	Something is really screwed.

LoadDefaultMenu()

int32 LoadDefaultMenu()

This is the backbone of probably the coolest feature of FlipSide A.E.: encoder based settings. All you have to do is create a BMenu that contains all your settings. There are only a couple of requirements.

the protected member menu must point to your new BMenu.

your BMenu must be created with new (obviously)

menu->Label() should return the same thing that GetName() does. In other words, the first line of this method should look something like:

menu = new BMenu(GetName());

To have an option checked or unchecked when a user clicks on it (and it's not in a menu that has radiomode turned on) set the invoker message to one of type FSS_MENU_ITEM_SELECTED. FlipSide A.E. will then take care of checking and unchecking it.

RETURN VALUES

B_OK Awsome!

B_ERROR Something is really screwed.

RETURN VALUES
B_OK	Awsome!
B_ERROR	Something is really screwed.

SetPattern() see GetPattern()

BMessages

FSS_ENCODE

This is the message passed to Encode().

Field Type code Description Required

"input file" B_STRING_TYPE full path to input file Yes

"output file" B_STRING_TYPE full path to output file Yes

"statusBarMessenger" B_MESSENGER_TYPE BMessenger for the Status Bar Yes

"artist" B_STRING_TYPE Artist No

"album" B_STRING_TYPE Album No

"title" B_STRING_TYPE Title No

"year" B_STRING_TYPE Year No

"Comment" B_STRING_TYPE Comment No

"track" B_STRING_TYPE Track No

"genre" B_STRING_TYPE Genre No

"genre number" B_INT32_TYPE ID3 v1.1 number for "genre" No; supplied if "genre" is.

"error" B_STRING_TYPE A clear user understandable error message to explain what went wrong. No, but should supplied if the addon returns B_ERROR.

Field	Type code	Description	Required
"input file"	B_STRING_TYPE	full path to input file	Yes
"output file"	B_STRING_TYPE	full path to output file	Yes
"statusBarMessenger"	B_MESSENGER_TYPE	BMessenger for the Status Bar	Yes
"artist"	B_STRING_TYPE	Artist	No
"album"	B_STRING_TYPE	Album	No
"title"	B_STRING_TYPE	Title	No
"year"	B_STRING_TYPE	Year	No
"Comment"	B_STRING_TYPE	Comment	No
"track"	B_STRING_TYPE	Track	No
"genre"	B_STRING_TYPE	Genre	No
"genre number"	B_INT32_TYPE	ID3 v1.1 number for "genre"	No; supplied if "genre" is.
"error"	B_STRING_TYPE	A clear user understandable error message to explain what went wrong.	No, but should supplied if the addon returns B_ERROR.

FSS_MENU_ITEM_SELECTED

Pass a new BMessage of this type into the constructor of a BMenuItem if you would like FlipSide A.E. to toggle checked/unchecked on the item.

FSS_SETMAX_STATUS_BAR

You send this message if you wish to change the maximum value of the status bar.

Field Type code Description Required

"max" B_FLOAT_TYPE the desired maximum value of the status bar Yes

Add-on Function

load_encoder()

AEEncoder* load_encoder()

This is the function FlipSide A.E. calls to get the pointer to your AEEncoder object. The code is very simple.

MyAEEncoderSubclass::MyAEEncoderSubclass() : AEEncoder("my subclass") { } AEEncoder* load_encoder() { return new MyAEEncoderSubclass(); }