MailMaster Plugin Definitions for MailMaster 1.1 Document last modified: 7/23/99 Table of Contents: 1. Introductions 2. Plugin Properties Required: kPluginType kVersion kMMPluginVersion Recommended: kMessageList 3. Mail App Plugins Required: MA_InitSession() MA_EndSession(yourInfo) MA_CheckMail() MA_CheckMailbox(itsMailbox) MA_GetMessage(msgRecord, messageRef) MA_DeleteMessage(messageRef) MA_QuitApps() Recommended: MA_MoveMessage(messageRef, newMailbox) 4. Database App Plugins Required: DB_AddMessage(dbInfo, msgRecord) DB_QuitApps() 5. Network Volume Plugins Required: NV_MountVolume(volEntry) NV_DismountVolume(volAlias) 6. Routines Provided LogInfo(logText) LogWarning(logText) LogError(logText) 7. License Issues 1. Introduction The next version of the MailMaster application will use "load script"ed script files to interface with EMail applications, Database applications, and Volume Mounting methods instead of the current hard-coded definitions for Eudora 3, FileMaker Pro, and various OSAXen. To do so, external script files will need to have certain properties and handlers so that the MailMaster can figure out what they are. This is a work in progress document. This version especially is just an overview so you can see what I'm going to be looking for in a plugin, and comments can be made to further adapt this for a wider set of programs. As the MM changes over and the plugins actually take form, this spec will solidify. - Mike 2. Plugin Properties All script plugins need to have these properties: property kPluginType : "MA" kPluginType is a two letter code that identifies what kind of plugin this script is. There are three plugin types: "MA" : Mail "DB" : Database "NV" : Network Volume property kVersion : {1,0,0} kVersion is a three number list in traditional Mac major, minor, more minor format. This is mostly for your own use. property kMMPluginVersion : {1,1,0} kMMPluginVersion is the version of the MailMaster Plugin format for which this plugin is written. As the MailMaster evolves, your plugin may go out of date. With this, the MailMaster can filter out plugins that will not work with its current version of plugins. kMMPluginVersions aren't necessarily equivalent between types. (The mail plugin version may be 1,1,0 while the database plugin version is 1,2,0 for version 1.2 of MailMaster.) You are not required to include this property, but it is recommended: property kMessageList : {"An error occurred getting messages.", "An error occurred opening the database."} -- If there is ever a localizable version of the MailMaster, there will -- also have to be localizable versions of the plugins. If you move all -- the text strings you use to the front of the app, then a generic tool -- can be written to localize plugins, even if they're read only. Notes for all plugins: You need to verify that your application exists and is running whenever you talk to it. Any applications you use are to be launched (not run or activated), and you need to tell the MailMaster when you launched your app so it can close it if necessary. (Mechanism forthcoming.) 3. Mail App Plugins -- version 1.1.0 Mail App plugins provide these handlers: MA_InitSession() MA_InitSession tells you to check your app to make sure it is running and change any settings that need to be changed. It can return a list of anything, which will be saved and passed in to MA_EndSession. This is mostly used to disable settings that might otherwise interfere with MailMaster operation, like periodic automatic mail downloading. MA_EndSession(yourInfo) MA_EndSession is called when the MailMaster is about to go back to idle. You receive back the information returned from MA_InitSession, so you can return settings to the way they were before MailMaster was triggered. MA_CheckMail() MA_CheckMail makes sure the mail app is open (launching it if necessary) then tells it to connect to the mail server and get mail. It shouldn't return until all the mail is downloaded, if at all possible. MA_CheckMailbox(itsMailbox) MA_CheckMailbox takes the name of a mailbox and returns a list of messageRef. messageRef is currently a list of the mailbox name and the index into the mailbox for Eudora, but this will (hopefully) change. The best messageRef is one that is not going to change if the messages are rearranged in their window (indexes are bad). MA_GetMessage(msgRecord, messageRef) MA_GetMessage takes a reference to a message and a Message Record, which is a list of msgElementRecord. msgElementRecord: {msgHeader:"To", msgContents:"parody@pconline.com"} Currently the list of "headers" that the MailMaster handles is hard-coded in MM: msgHeader msgContents "To" string "From" string "Date" string "Time" string "Subject" string "Body" string "Attachments" list of string paths Thus, your script will be taking a list of records and filling in the empty contents side, then returning the record list. In the future, the headers list may be user-created, which may require a generic message-with-full-headers-searching script. :( MA_DeleteMessage(messageRef) MA_DeleteMessage takes a reference to a mesage and "deletes it". In Eudora, it goes into the trash folder. (MM doesn't empty the trash.) MA_QuitApps() MA_QuitApps should quit the mail app you use, and any extra things that are running. Make sure you verify first. If possible, mail plugins should support these handlers: MA_MoveMessage(messageRef, newMailbox) MA_MoveMessage (as implied) moves a message from one mailbox to another. This would get called instead of DeleteMessage, if the user doesn't want messages to be deleted. 4. Database Plugins -- version 1.1.0 Database plugins currently only have to provide two handlers: DB_AddMessage(dbInfo, msgRecord) DB_AddMessage adds a message to the database. The msgRecord is the same thing that was returned from MA_GetMessage. The dbInfo is MailMaster's settings for the Database, which you'll need to know how to open the database. In MM 1.0, dbInfo looks like: dbinfo : {mlName:"MyName", dbName:"MyName ML Archive", mbName:"MyName", openMethod:1, openInfo:"", newScript:"MakeNewRecord", beforeScript:"", afterScript:"EndNewRecord", useBeforeScript:false, useAfterScript:true, addSubject:true, addFrom:true, addTo:true, addBody:true, addDate:true, addTime:true, addAttachments:true, attachmentsFolder:"My HD:Attachments"} openMethods: 1=Direct (tell FMP to open dbName) 2=Local File (tell FMP to open file openInfo) 98=Run Script File (run script file openInfo) 99=Run Script Line (run script openInfo) MM 1.1 should add a "Network" type and a "Local File With Password" type, or something similar (comments needed! :) Note that you'll need to open the database if necessary (and update MM that you did so). The Script options will be dealt with if/when someone writes this for an app other than FileMaker Pro. DB_AddMessage returns the "index" of the message created. Currently, MailMaster assumes that the database used with it has a non-duplicatable serial number field, and DB_AddMessage returns the new entry's value in that field. This is only required if you are going to save attachments (it needs some way to link the attachments to the messages that spawned them). DB_QuitApps() Like MA_QuitApps, DB_QuitApps quits any apps you might have used, if they're running. 5. Network Volume Mounting Plugins -- version 1.1.0 You have to provide two handlers, and in most cases one will be written for you: NV_MountVolume(volEntry) NV_MountVolume mounts the volume using the parameters passed in via volEntry. It should return an alias to the volume. volEntry looks like this: {volName:"", volUser:"", volPassword:"", volServer:"", volZone:""} The settings are pretty obvious for mounting AppleTalk volumes. For IP, volServer will hold the server address, and volZone is ignored. NV_DismountVolume(volAlias) NV_DismountVolume looks like this for most volumes: on NV_DismountVolume(volAlias) try tell application "Finder" put away {volAlias} end tell on error errTxt number errNum -- Insert LogError call here once LogError is written end try end NV_DismountVolume ...but your network volume mounting method may require something different. 6. Routines provided by MailMaster and/or included in the plugin framework: These routines are available for your plugins to call when doing their duty: LogInfo(logText) LogInfo is called when you want to add something to the Log. Generally, the plugins won't need to call this (MM handles the informative entries in the log) but it's there if you need it. LogWarning(logText) LogWarning should be called when you encounter an error which doesn't necessarily prevent MM from continuing but should be noted in the log. A Mail plugin might call LogWarning if a message specified a header that wasn't found in the message, like "Reply-To". LogError(logText) LogError is called when you encounter a serious error which stops operations on either this message, this mailbox, or in general. If the messageRef you are passed doesn't exist, that's a job for LogError. Note that neither LogWarning or LogError actually abort your script. You will need to fire an error (and pass it on to MM) if you reach a point where your routine can't continue. This mechanism is still being worked out, but will probably consist of three error codes you pass: 20001 "Cannot continue with this message/entry." 20002 "Cannot continue with this mailbox." 20003 "Cannot continue with this procedure." (Your try...on errors will need to look for these and pass them if found.) 7. License Issues I'm only going to keep the core MailMaster under license. The initial plugins will be free, editable scripts. Any plugins you write you can license any way you see fit, although I'm hoping you wouldn't go any farther than the postcard that the MM asks for. :) Mike Miller ESG Labs