Introduction to Y-Browser plugin development

What are Y-Browser plug-ins

In general Y-Browser plug-ins are Ecom plug-ins, which are returning defined Y-Browser base class implementations.

For file handler all plug-in instances are CCoeControl based containers which are also required to implement some additional interface functions. These additional interface function are then called by the Y-Browser when these plug-ins are utilized.

The recognizer plug-in is basically a CBase derived class with additional interface functions used for recognizing files.

With current 0.80 version Y-Browser file handlers there are 4 different types of plug-ins:

1. Normal file handler
2. File sender
3. File folder
4. "Open with..." file handler

Basically different types of file handler plug-ins are utilized with different menu’s and also they need to be derived from correct base class. More information on how to tell Y-Browser which handler your plug-in is you can find from the chapter covering the Ecom plug-in resource file.

File Handlers

All file handler plug-ins are either deriving directly from the CYBrowserBaseHandler base class, or are deriving from a class that is derived from the CYBrowserBaseHandler. Thus all of the virtual functions defined for it are required to be implemented by all file handlers. The class is defined as follows:

When Y-Browser constructs a file handler plug-in, it calls SetUtils() function before calling the ConstructL() function. This function should just set the internal variable pointer to point a Y-Browser utility interface. This interface provides quite many useful functionalities and you could read more about it from the Y-Browser utilities chapter.
The ConstructL() function is normal second phase constructor, in which you could do all leaving constructions required for your plug-in implementation.

SetFocusL() function is used by Y-Browser to tell the plug-in when it is gaining/losing focus, thus you should stop any processing when you lose focus and make sure your UI stuff and all is correct when you gain a focus. For example if another plug in is launched while your plug-in is still on, you will be informed that you have lost the focus, and when that plug in exits you will be informed about focus gain.

DynInitMenuPaneL() is actually the same as with Application user interface classes, thus you could get information from it by reading SDK documentations.

HandleCommandL() function is then called by Y-Browser when user selects menu options from your plug-in or clicks command buttons in it. Note that, to make the command handling work correctly, you should always start your command numbering from 0x7000 or higher value.

Normal file handler

Normal file handlers (which do not make new files) are not shown in any specific menu of Y-Browser, but merely are used for handling a specific type of file. Thus Y-Browser will load and construct these handlers when user tries to open a file which is marked to be handled with this specific file handler plug-in.

With the Ecom resource you can also specify that your file handler can construct new files, then the file handler will be shown in the list when user selects “New File” option from the menu.

Normal file handler plug-in needs to be derived from CYBrowserFileHandler, which also derives from CYBrowserBaseHandler (which derived from CCoeControl). CYBrowserFileHandler class definition looks like this:

As can be seen, this class basically just has some functions that are used for constructing new files & opening existing files. And depending on what you have specified in the Ecom resource file, you can leave some of the functions empty.

OpenFileL() functions are called by Y-Browser to tell the plug-in to handle opening the file user has selected. The TDesC version will give the full filename including drive, and this one needs to be implemented in every instance of file handlers, the function utilizing RFile is optional, and if you don’t specify it in the resource file, then you can leave it empty.

NewFileL() functions are called when user has selected “New File” from the menu, and wants to make a new file. The path is the current path for Y-Browser, thus you could assume that user wants to make the file into this particular folder. Filetype shows the filetype selected, thus if your plug-in only supports one file type, then you could ignore it, otherwise, you should check which type of file is supposed to be constructed.

With the Ecom resource file, you can specify if the plug-in supports new empty files, or/and new files with files. And if you have specified that new empty files are supported, the file type specified will be shown in the “New file” list, and the NewFileL() function without file array will be called.

And if you have defined in the resource file that your plug-in supports new files with files, then the plug-in is also shown in the list when user selects “Paste to new file” menu item.

The AddFilesL() function is called by Y-Browser to ask the plug-in to add files into a existing file (this option is actually not used currently, and propably will be removed later).

”Open with...” file handler

"Open with..." file handler is basically a normal file handler that also specifies in the resource file that it should be included in the “Open with...” list. Do not abuse this feature (or you might get black listed), basically if your file handler is only capable of handling specific file types, you are required to identify them correctly, and you also required to make recognizers for the file types that are otherwise not recognized.

You should only specify your plug-in to be “Open with” handler, in case you can handle any file type, i.e. your plug-in is hex editor etc.. Of course if you have a really-really good reason this rule could be relaxed.

File sender

File senders are used for sending files from the phone, and they are shown in the list when user selects “Send“ option from the menu. The identification steps of how you can specify that your plug-in is a file sender can be found from the Ecom resource chapter.

File senders are required to derive from CYBrowserFileSender base class, which looks like this:

As can be seen the only function CYBrowserFileSender has is the SendFilesL() function, which will be called by the Y-Browser when user selects files to be send with this plug-in implementation.

File folder

File folder is a bit misleading name, basically it means that this handler does not actually handle any file types, but does something else for the files, for example allows accessing other file sources like Messaging inbox. Basically this type of handler is shown in the main menu only, just as the “Mail folders” plug-in is.

The base class for File folder is the CYBrowserBaseHandler.

Y-Browser file recognizers

File recognizer plug-ins are provided so file types which are normally not recognized could be recognized by the Y-Browser without using any other than self-signed capabilities. The base class for the Y-Browser file recognizer is as follows:

With GetCreditsL() you should return a HBufC* pointer (which the caller will take ownership) that says your recognizer name, version, your name, your contact details, etc.. Basically something that you would like to show in about box. Currently this function is not used, but as soon as some-kind of plug-in management system is made, it will be used, so better be prepared.

GetIconL() is used by Y-Browser to get a specific icon you would like to use with the filetype. Should always use AknIconUtils:: CreateIconL(), so the icon can be scaled by the Y-Browser, also note that the size parameter if often zero sized, anyway if it is not, then you must use AknIconUtils::SetSize() to size it right. The index value is from Zero to FileTypeCount() -1.

FileTypeL() function is used by Y-Browser to query the recognized file types this plug-in is supporting. The index value is from Zero to FileTypeCount() -1.

With the minimum size you could tell the Y-Browser what is the minimum file size in bytes that your supported file types has to have.

RecognizeFile() function is called by Y-Browser to ask the recognizer to try recognizing the file. The aResult is used to tell back the Y-Browser if the file was recognized, the aFileName is filename for the file (could be non-parseable, as well as could be zero length, thus take account in your code), and the aBuffer is 0-255 bytes long buffer containing bytes from the start of the file.

The definition for the CYBRecognitionResult looks like this:

The iConfidence tells the Y-Browser of how sure the recognizer is that this file is the type that the recognizer thinks it is. And if it is other than certain, other recognizers are asked to check if they could get better recognizing confidence for the file.

The iIdString is the file type identified string, which should be the same as returned in the FileTypeL() function. Note that you should first delete the pointer, set it to NULL and then re-allocate the buffer.

Y-Browser utilities

Y-Browser will give all file handler plug-ins a pointer to a utility interface which with you can utlize some functionalities and resources, thus making it easier to your plug-in to do its own tasks. This interface pointer is given as argument in SetUtils() function which is called just before the file handlers ConstructL() function is called. Even though the utility interface is a pointer, your plug-in does not gain ownership to it, thus do not try deleting it. The utility looks like this:

Most important function in it is the HandleExitL() function, which with you can tell Y-Browser that you wish to exit. The aFileHandler must be your this-pointer, so Y-Browser can know which plug-in wishes to exit. With aChanges you can tell whether you made any changes to the files in current folder, and if it is set to EChangesMade, Y-Browser will re-read the current folder when the plug-in exits, othervise no action other than deleting the plug-in is taken.

GetCba() gives you the current command buttons, so you can set your own commands active easily by using this function.

GetFileUtils() gives you a reference to a MYBrowserFileUtils utilities and GetIconUtils() gives you a reference to a MYBrowserIconUtils utilities.

MYBrowserFileUtils

The MYBrowserFileUtils looks like this:

ShowFileErrorNoteL() function can be used to show a error note to the user, just give the full name for the file causing the problem and the Symbian error code.

The OpenFileWithHandler() function is provided so you could open a file with Y-Browser handlers (or system handler, if no Y-Browser file handler for the file type is found)

With RecognizeFile() functions you could recognize file types, just as they are recognized by the Y-Browser.

GetGeneralFileItem() returns a reference a to a file type item that is used with files which are not recognized by Y-Browser, basically you could use this to retrieve the index number for the icon used with un-recognized files for example.

GetItemTypeArray() function returns you a reference to a array that contains all of the filetypes recognized by Y-Browser.

The definition for the CFFileTypeItem looks like this:

Basically in it the iIdString is the file type identified for a file type, which is same format as given by the recognizer for the file type. The iTypeId is then internal index number for the file type, used for mapping the file type to a icon. The index value for any given file type can vary thus do not map it to any specific value, but always check the filetype array to find out the right index value for any given filetype.

With GetCurrentPath() function you could retrieve the current folder user has browser to with Y-Browser.

With SetNaviTextL(), you could use the Y-Browser navi control and make it to show your own text. In case the text is too long to be shown in the navi control is it scrolled with a timer.

StartSelectionViewL() allows you to use Y-Browser folder/file selection utility. With it, if you set the aFolderSelector to ETrue, the selection will not show files, but only allow selecting a folder. aFolder argument can be used to specify the star folder and with aTitle you can specify what is shown in the title panel while the selector is on. With non-folder selection, you can also specify an array of file types with aTypeFilter. If this filter is non-NULL, it will be used to filter files that are shown in the selection, and other than the filetypes specified will be ignored.

The aCallback is then a interface definition which Y-Browser will use to inform your plug-in that the file/folder selection has finished. It it defined as follows:

SelectedFilesL() will be called for file selectors, when user selects “Done”, and the aArray will identify all files user has selected.

SelectedFolderL() will be called for folder selectors, when user selects “Done”, and the aFolderName will identify the folder user has selected.

SelectorCancelledL() will be called if user cancels the file/folder selector without pressing “Done”.

MYBrowserIconUtils

The definition for the MYBrowserIconUtils looks like this:

GetIconIndex() function can be used to retrieve a icon index for a file type that is recognized. The index is the same value as the iTypeId (with CFFileTypeItem) has for the file type.

GetIconL() gives you icon for specified file type, and it also gives you the ownership to the returned icon. Note that with CAkn… listboxes, you can define the size as TSize(0,0), since listboxes are taking care of the sizing by themselves.

GetIconArrayL() gives you the full icon array that is ordered according to the iTypeId (from CFFileTypeItem) values.

GetSelectionIconArrayL() gives you a array that could be used with selection dialogs. Zero index icon is non-selected and index 1 is selected icon.

Y-Browser Ecom resource definitions

The Ecom resource definition for Y-Browser plug-ins is quite much as with any other Ecom plug-in, the main difference is that you need to define some Y-Browser specific aspects in the opaque_data variable.

The interface_uid UIDs for Y-Browser plug-ins are defined as follows:

1. Y-Browser file recognizer = 0x20009992
2. Y-Browser file handlers = 0x20009991

The opaque_data needs to be defined as follows:

The data has to be enclosed between <YTOOLS> and </YTOOLS> tag, and the plug-in version identified between <VERSION> and </VERSION> tags has to be exactly “080” with the current version, otherwise all other data is not read and the plug-in is not loaded into the Y-Browser.

The data between <IMPLEMENTATION> and </IMPLEMENTATION> tags identifies the type of the plug-in and the file type support etc. for Y-Browser.

First tags inside the implementation tags has to be type tags (<TYPE> </TYPE>), possible strings inside these tags are as follows:
- FILEHANDLER (normal file handler),
- FILESENDER (File sender plug-in),
- FILEFOLDER (the file folder plug-in),
- OPENWITH (open with plug-in),
- FILERECOGNIZER (used for file recognizers, note that also the UID has to be correct)

After the type there can be multiple support tag (<SUPPORT></SUPPORT>) pairs. The support tags can contain following tags inside it:

<FILETYPE></FILETYPE> are used to define normal full file type identifier strings, like for example “YTools/Myfile”

<TYPEPARTIAL> </TYPEPARTIAL> are used to defined partial file type identifier string. Basically the strings is then matched to a left part of the file type identifier string to make a match. For example “image” would have a match with both “image/jpg” and “image/gif”.

Note that you can not have both partial and full file type identifier inside same support tag, and if you do so, other one of them will be definitely ignored., or the whole support line could also be ignored.

<RFILE>YES</RFILE>, add this line if the plug-in can handle RFile overwrites of the OpenFileL() function, if it can not, then do not add these tags at all.

<NEWWITHFILES>YES</NEWWITHFILES>, add this line if the plug-in supports making new files with file array (i.e. will be used in paste-files-to-new-file menu) , if it can not, then do not add these tags at all.

<NEWEMPY>YES</NEWEMPY>, add this line if the plug-in supports making new empty files (will be added to the "New File" menu list), if it can not, then do not add these tags at all.