Eudora 4.0 Automation SDK
Version 1.0
November 22, 1997
Copyright © 1997 Qualcomm, Inc.
Eudora Division
Written by Ted Bogner
Introduction
Automation allows you to access many of the mail capabilities of Eudora. For instance, from an external program supporting Windows Automation capability, you could check and send mail, or access the contents of any of the mailboxes. This SDK and documentation is intended for software developers who wish to make custom applications to interface with Eudora.
Eudoras Automation uses the standard Windows COM (Component Object Model) and supports the dual standard interfaces IUnknown and IDispatch. Programs designed to take advantage of this object model, such as Visual Basic, make it relatively easy to access the exposed functionality of Eudora. Programs written in C or C++ are more difficult to write but may access the same interfaces. The included samples are written in Microsoft Visual Basic, but we plan to include some C++ samples in future releases of the SDK.
To get a quick feel for what Automation can do for you as a developer, here is an example code fragment that will search the folder "Marketing" moving all messages containing the text "Bob Smith" to the folder "BobsFolder", and adding the subject of the message to a list box.
Dim message As EuMessage
Dim folder As EuFolder
Dim folder2 As EuFolder
At this point in the code:
The variable app is already set to Eudora app
The folders "BobsFolder" and "Marketing" exist
The list box "List1" has been created
List1.Clear
Set folder = app.Folder("Marketing", 1)
Set folder2 = app.Folder("BobsFolder", 1)
For Each message In folder
If InStr(1, message.Body, "Bob Smith") Then
List1.AddItem message.Subject
message.Move folder2
End If
End If
Next
(Legal note: Microsoft, Windows, and Visual Basic are trademarks of Microsoft Inc. Eudora and Qualcomm are trademarks of Qualcomm, Inc.)
Updated information
The capabilities of Automation are dependent upon the version of Eudora. The Automation SDK may only take advantage of the latest version of Eudora, but will be updated between versions to include better samples and documentation. When new information becomes available, it will be posted on the Internet at
http://www.eudora.com/developers. This release of Automation focuses on the mail and folder objects of Eudora. Future version of Eudora should include more objects such as the Address Book, Directory Services, Accounts & Personalities, and Options.
Feedback to the Eudora developers
We welcome and appreciate your feedback about Automation in Eudora and the Automation SDK. The current email address for feedback about Automation is:
emsapi-info@qualcomm.com
Automation vs. Plugins and MAPI
Eudora supports external access to its features by three methods: Plugins, Simple MAPI, and Automation. Some of the functionality overlaps, but usually one is preferable depending on what you are trying to accomplish. All three allow generation of mail messages. Currently only plugins allow you to create a menu/toolbar item and translate messages automatically during all the stages of a mail message. Automation supports access to of all of the mail folders and mail messages as a hierarchical object set, whereas the other two focus on mail coming in and mail going out. Automation and MAPI interfaces may be written in languages such as VB, C or C++, but a plugin typically needs to be written in C or C++. To find out more information about Plugins, please refer to the EMSAPI SDK.
Running the Sample Application
The sample application AUTOTEST shows browsing through mail folders and mail messages in Eudora. Clicking the mail folder list will show its table of contents. Clicking the table of contents will show the individual mail message. There is a "compose mail message" button and a "send queued message button" for sending mail. If you dont own Visual Basic, but are able to access Automation another way, it will still be useful to open the .bas files in the sample applications with a text editor.
To run the sample application, check the following items:
Registering and Enabling Automation
Enabling Automation
Automation is enabled in Eudora in one of two ways:
/EnableAutomation
Disabling Automation
Automation is disabled in Eudora in one of two ways:
/DisableAutomation
Registering Automation
Enabling Eudora also registers all of the COM objects in Eudora. Disable unregisters these objects. If you have obtained a new version of Eudora, you will need to update your registration by disabling then re-enabling Automation. Note that enabling / disabling (and the associated registration) takes place when the "OK" button is pressed, so if you use the options menu, make sure you dont just uncheck and re-check the option without closing the dialog inbetween.
The Eudora Interfaces
Eudora has a single COM Automation server. The server is normally inactive, and becomes active, or running, only after a client application has connected to it. The current version of Eudora supports one Automation server and one Automation client, but will be changed in future versions to support multi-client, multi-server configurations. When the Eudora Automation server is running, its object will be registered in the Running Object Table.
Currently Eudora supports five interfaces:
Common Name
Class Name Interface NameApplication EuApplication IEuApplication
Folder EuFolder IEuFolder
Folder Collection EuFolders IEuFolders
Message EuMessage IEuMessage
Message Collection EuMessages IEuMessages
Application Interface
The application interface represents the top-level of Eudora. All other objects are obtained from starting with this interface. To get access to the application interface, you should first query the Running Object Table to find out if there is already an Eudora Automation Server running. If not, you can create it. An example of this is given in the sample application.
The application interface supports some key methods and properties, and is currently the only object to support events. Here are some of the most important ones:
Folders property the top-level Folders object. Provides access to all mailboxes and folders, including the inbox and outbox.
CheckMail method causes Eudora to check mail
QueueMessage method creates and queues a new mail message
Folder Interface
The folders in Eudora are hierarchical, and may be obtained from the Application interface. In automation, a mailbox is the same as a folder, but containing mail messages instead of (sub) mail folders. Here are some important methods and properties of the Folder interface:
Folders lists sub folders, if they exist
Messages lists messages, if they exist
Name short name of folder
bCanContainMessages determines if its a mailbox
Here are three ways to get to the inbox, as an example (see also sample apps):
Dim Folder As EuFolder
Set Folder = App.InBox
Dim Folder As EuFolder
Set Folder = App.Folders.Item(1)
Dim Folder As EuFolder
Set Folder = App.Folder( "In", 0)
Folders Interface
The folders interface is obtained from its parent folder. The highest level is the Application.RootFolder. The most important properties of the Folders interface are:
Count number of folders in this collection of folders
Item returns specific folder by index (index starts at one)
Add allows adding a new folder to the collection
Remove removes (deletes) a folder from the collection
_NewEnum allows enumeration in scripting languages
Enumeration of sub-folders is accomplished in two ways:
Here is an example subroutine to create a list of all child folders of a folder using the "Item" property
Sub MakeListOfFolders (ParentFolder As EuFolder)
Dim FolderCount As Integer
Dim x as Integer
Dim Folder
FolderCount = ParentFolder.Folders.Count
If FolderCount > 0 Then
For x = 1 to FolderCount
This adds the name of the folder into
the list box named "List1"
List1.AddItem Folder.Name
Next
End If
End Sub
Here is an example subroutine to create a list of all child folders of a folder using the "for each" scripting method:
Sub MakeListOfFolders (ParentFolder As EuFolder)
Dim Folder
For Each Folder In ParentFolder.Folders
This adds the name of the folder into
the list box named "List1"
List1.AddItem Folder.Name
Next
End Sub
Message Interface
The message interface allows read-access to mail messages in Eudora. The most important properties of the message interface are:
ID unique ID of message within a given folder
To who the message is to
From who the message is from
Subject the subject of the message
Body the message body
BodyAsHtml the message converted to HTML
HeaderInfo misc. header information
Messages Interface
The messages interface lists all of the mail messages in a folder (mailbox) and functions similar to the Folders interface. When doing work with list of messages within a folder, it is helpful to keep track of the messages by their ID, in some cases, instead of their objects. See the section about object lifetimes.
Exception Handling and Object Lifetimes
When a property or method call on an object is unsuccessful, it raises an exception. Before any properties or methods called, it is necessary to setup an exception handler. In Visual Basic this is accomplished by the statement "On Error Resume Next" at the beginning of a function or right before the call. If the Err.Number property is not equal to zero then the call failed. (If so, Err.Clear should be called immediately aftwerwards.) In C++ this is accomplished by using a "try catch" block.
The application object and the folder objects are valid as long as one or more clients are connected to Eudora and automation is enabled. The message objects are only created temporarily to limit the amount of memory allocated within Eudora. After getting a message object from a folder, it is valid until:
The folder list presented with Automation will always match the folder list internal to Eudora. For the reasons above, the message list within a folder can become out-dated. To make sure that they match, one of the two methods may be called:
Tips for programming in Visual Basic
We recommend that you take a close look at the code in the examples provided with the SDK. The settings of the sample applications have a "reference" to Eudora which you will not have when you first create your own projects. To create a reference to Eudora so that Visual Basic is aware of the Eudora type library, youll need to do the following:
All objects in Eudora are accessed through the Application object. In a typical Visual Basic application, it is declared as follows:
Public WithEvents app As EuApplication
The "Public" creates a public instance of the application object. The "WithEvents" allows the Visual Basic application to receive messages back from Eudora. "EuApplication" is the class name of Eudoras application object.
Visual Basic can shows lists of the available properties and methods of a given objects. For instance, in development mode in Visual Basic, typing the variable "app", as declared above, followed by a period after it (as in app.) will cause a popup list box with all of the possible properties and methods for the application object.
Eudora Automation Type Library
All class names begin with "Eu" and all interface names begin with "IEu" so that they are more easily distinguished from the mass of other available classes and interfaces.
dispinterface IEuApplicationEvents;
interface IEuApplication;
interface IEuFolders;
interface IEuFolder;
interface IEuMessages;
interface IEuMessage;
[
uuid(EDA00000-AAAA-11D0-B3C5-00805F8AA4FB),
version(1.0),
helpstring("Eudora Type Library")
]
library EudoraLib
{
// TLib : OLE Automation : {00020430-0000-0000-C000-000000000046}
importlib("StdOle2.tlb");
[
uuid(EDA30001-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuApplication Events")
]
dispinterface IEuApplicationEvents {
properties:
methods:
[id(0x00000001)]
HRESULT OnClose();
[id(0x00000002), helpstring("method OnFolderChange")]
HRESULT OnFolderChange();
[id(0x00000003), helpstring("method OnCheckMailComplete")]
HRESULT OnCheckMailComplete();
[id(0x00000004), helpstring("method OnSendMailComplete")]
HRESULT OnSendMailComplete();
[id(0x00000005), helpstring("method OnEmptyTrashComplete")]
HRESULT OnEmptyTrashComplete();
[id(0x00000006), helpstring("method OnCompactFoldersComplete")]
HRESULT OnCompactFoldersComplete();
};
[
uuid(EDA20001-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("EuApplication Class"),
noncreatable
]
coclass EuApplication {
[default] interface IEuApplication;
[default, source] dispinterface IEuApplicationEvents;
};
[
odl,
uuid(EDA10001-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuApplication Interface"),
hidden,
dual,
oleautomation
]
interface IEuApplication : IDispatch {
[id(0x00000001), propget, helpstring("property Application")]
HRESULT _stdcall Application([out, retval] IEuApplication** pVal);
[id(0x00000002), propget, helpstring("property Caption")]
HRESULT _stdcall Caption([out, retval] BSTR* pVal);
[id(0x00000002), propput, helpstring("property Caption")]
HRESULT _stdcall Caption([in] BSTR pVal);
[id(0x00000003), propget, helpstring("property Folders")]
HRESULT _stdcall Folders([out, retval] IEuFolders** pVal);
[id(0x00000004), propget, helpstring("property FullName")]
HRESULT _stdcall FullName([out, retval] BSTR* pVal);
[id(0x00000005), propget, helpstring("property Height")]
HRESULT _stdcall Height([out, retval] long* pVal);
[id(0x00000005), propput, helpstring("property Height")]
HRESULT _stdcall Height([in] long pVal);
[id(0x00000006), propget, helpstring("property InBox")]
HRESULT _stdcall InBox([out, retval] IEuFolder** pVal);
[id(0x00000007), propget, helpstring("property Interactive")]
HRESULT _stdcall Interactive([out, retval] long* pVal);
[id(0x00000008), propget, helpstring("property Left")]
HRESULT _stdcall Left([out, retval] long* pVal);
[id(0x00000008), propput, helpstring("property Left")]
HRESULT _stdcall Left([in] long pVal);
[id(0x00000009), propget, helpstring("property Name")]
HRESULT _stdcall Name([out, retval] BSTR* pVal);
[id(0x0000000a), propget, helpstring("property Path")]
HRESULT _stdcall Path([out, retval] BSTR* pVal);
[id(0x0000000b), propget, helpstring("property Parent")]
HRESULT _stdcall Parent([out, retval] IEuApplication** pVal);
[id(0x0000000c), propget, hidden, helpstring("property ProcessID")]
HRESULT _stdcall ProcessID([out, retval] long* pVal);
[id(0x0000000d), propget, hidden, helpstring("property RefCount")]
HRESULT _stdcall RefCount([out, retval] long* pVal);
[id(0x0000000e), propget, helpstring("property RootFolder")]
HRESULT _stdcall RootFolder([out, retval] IEuFolder** pVal);
[id(0x0000000f), propget, helpstring("property StatusBar")]
HRESULT _stdcall StatusBar([out, retval] BSTR* pVal);
[id(0x0000000f), propput, helpstring("property StatusBar")]
HRESULT _stdcall StatusBar([in] BSTR pVal);
[id(0x00000010), propget, helpstring("property Top")]
HRESULT _stdcall Top([out, retval] long* pVal);
[id(0x00000010), propput, helpstring("property Top")]
HRESULT _stdcall Top([in] long pVal);
[id(0x00000011), propget, helpstring("property VersionBuild")]
HRESULT _stdcall VersionBuild([out, retval] short* pVal);
[id(0x00000012), propget, helpstring("property VersionMajor")]
HRESULT _stdcall VersionMajor([out, retval] short* pVal);
[id(0x00000013), propget, helpstring("property VersionMinor")]
HRESULT _stdcall VersionMinor([out, retval] short* pVal);
[id(0x00000014), propget, helpstring("property VersionMinor2")]
HRESULT _stdcall VersionMinor2([out, retval] short* pVal);
[id(0x00000015), propget, helpstring("property Visible")]
HRESULT _stdcall Visible([out, retval] long* pVal);
[id(0x00000015), propput, helpstring("property Visible")]
HRESULT _stdcall Visible([in] long pVal);
[id(0x00000016), propget, helpstring("property Width")]
HRESULT _stdcall Width([out, retval] long* pVal);
[id(0x00000016), propput, helpstring("property Width")]
HRESULT _stdcall Width([in] long pVal);
[id(0x00000017), helpstring("method CloseEudora")]
HRESULT _stdcall CloseEudora();
[id(0x00000018), helpstring("method CheckMail")]
HRESULT _stdcall CheckMail([in, optional] VARIANT Password);
[id(0x00000019), helpstring("method CompactFolders")]
HRESULT _stdcall CompactFolders();
[id(0x0000001a), helpstring("method EmptyTrash")]
HRESULT _stdcall EmptyTrash();
[id(0x0000001b), helpstring("method Folder")]
HRESULT _stdcall Folder(
BSTR Name,
long FindRecursive,
[out, retval] IEuFolder** pVal);
[id(0x0000001c), helpstring("method FolderByID")]
HRESULT _stdcall FolderByID(
long ID,
long FindRecursive,
[out, retval] IEuFolder** pVal);
[id(0x0000001d), helpstring("method QueueMessage")]
HRESULT _stdcall QueueMessage(
BSTR To,
BSTR Subject,
BSTR Cc,
BSTR Bcc,
BSTR Attach,
BSTR Body);
[id(0x0000001e), helpstring("method SendQueuedMessages")]
HRESULT _stdcall SendQueuedMessages();
};
[
odl,
uuid(EDA10015-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuFolders Interface"),
hidden,
dual,
oleautomation
]
interface IEuFolders : IDispatch {
[id(00000000), propget]
HRESULT _stdcall Item(
[in] long Index,
[out, retval] VARIANT* ppFolder);
[id(0xfffffffc), propget, restricted]
HRESULT _stdcall _NewEnum([out, retval] IUnknown** ppEnum);
[id(0x00000001), propget, helpstring("property Count")]
HRESULT _stdcall Count([out, retval] long* pVal);
[id(0x00000002), propget, hidden, helpstring("property RefCount")]
HRESULT _stdcall RefCount([out, retval] long* pVal);
[id(0x00000003), helpstring("method Add")]
HRESULT _stdcall Add(
BSTR Name,
long bCanContainMessages);
[id(0x00000004), helpstring("method RemoveByID")]
HRESULT _stdcall RemoveByID(long ID);
};
[
odl,
uuid(EDA10014-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuFolder Interface"),
hidden,
dual,
oleautomation
]
interface IEuFolder : IDispatch {
[id(0x00000001), propget, helpstring("property bCanContainMessages")]
HRESULT _stdcall bCanContainMessages([out, retval] long* pVal);
[id(0x00000002), propget, helpstring("property bCanContainSubFolders")]
HRESULT _stdcall bCanContainSubFolders([out, retval] long* pVal);
[id(0x00000003), propget, helpstring("property bContainsUnreadMessages")]
HRESULT _stdcall bContainsUnreadMessages([out, retval] long* pVal);
[id(0x00000004), propget, helpstring("property bIsImapFolder")]
HRESULT _stdcall bIsImapFolder([out, retval] long* pVal);
[id(0x00000005), propget, helpstring("property Level")]
HRESULT _stdcall Level([out, retval] short* pVal);
[id(0x00000006), propget, helpstring("property Folders")]
HRESULT _stdcall Folders([out, retval] IEuFolders** pVal);
[id(0x00000007), propget, helpstring("property FullName")]
HRESULT _stdcall FullName([out, retval] BSTR* pVal);
[id(0x00000008), propget, helpstring("property ID")]
HRESULT _stdcall ID([out, retval] long* pVal);
[id(0x00000009), propget, hidden, helpstring("property Index")]
HRESULT _stdcall Index([out, retval] long* pVal);
[id(0x0000000a), propget, helpstring("property Messages")]
HRESULT _stdcall Messages([out, retval] IEuMessages** pVal);
[id(0x0000000b), propget, helpstring("property Name")]
HRESULT _stdcall Name([out, retval] BSTR* pVal);
[id(0x0000000c), propget, helpstring("property Path")]
HRESULT _stdcall Path([out, retval] BSTR* pVal);
[id(0x0000000d), propget, hidden, helpstring("property RefCount")]
HRESULT _stdcall RefCount([out, retval] long* pVal);
[id(0x0000000e), helpstring("method Move")]
HRESULT _stdcall Move(IEuFolder* NewParentFolder);
[id(0x0000000f), helpstring("method Open")]
HRESULT _stdcall Open();
};
[
odl,
uuid(EDA10005-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuMessages Interface"),
hidden,
dual,
oleautomation
]
interface IEuMessages : IDispatch {
[id(00000000), propget]
HRESULT _stdcall Item(
[in] long Index,
[out, retval] VARIANT* ppFolder);
[id(0xfffffffc), propget, restricted]
HRESULT _stdcall _NewEnum([out, retval] IUnknown** ppEnum);
[id(0x00000001), propget, helpstring("property Count")]
HRESULT _stdcall Count([out, retval] long* pVal);
[id(0x00000002), propget, helpstring("property ItemByID")]
HRESULT _stdcall ItemByID(
[in] long ID,
[out, retval] VARIANT* ppFolder);
[id(0x00000003), propget, hidden, helpstring("property RefCount")]
HRESULT _stdcall RefCount([out, retval] long* pVal);
[id(0x00000004), helpstring("method RemoveByID")]
HRESULT _stdcall RemoveByID(long ID);
[id(0x00000005), helpstring("method UpdateList")]
HRESULT _stdcall UpdateList();
};
[
uuid(EDA20014-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("EuMessage Class"),
noncreatable
]
coclass EuMessage {
[default] interface IEuMessage;
};
[
odl,
uuid(EDA10004-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("IEuMessage Interface"),
hidden,
dual,
oleautomation
]
interface IEuMessage : IDispatch {
[id(0x00000001), propget, helpstring("property AttachmentListAsString")]
HRESULT _stdcall AttachmentListAsString([out, retval] BSTR* pVal);
[id(0x00000002), propget, helpstring("property Body")]
HRESULT _stdcall Body([out, retval] BSTR* pVal);
[id(0x00000003), propget, helpstring("property BodyAsHTML")]
HRESULT _stdcall BodyAsHTML([out, retval] BSTR* pVal);
[id(0x00000004), propget, helpstring("property BodyAsSimpleText")]
HRESULT _stdcall BodyAsSimpleText([out, retval] BSTR* pVal);
[id(0x00000005), propget, helpstring("property Date")]
HRESULT _stdcall Date([out, retval] BSTR* pVal);
[id(0x00000006), propget, helpstring("property From")]
HRESULT _stdcall From([out, retval] BSTR* pVal);
[id(0x00000007), propget, helpstring("property HeaderInfo")]
HRESULT _stdcall HeaderInfo(
[in] enHeaderField HeaderField,
[out, retval] BSTR* pVal);
[id(0x00000008), propget, helpstring("property ID")]
HRESULT _stdcall ID([out, retval] long* pVal);
[id(0x00000009), propget, helpstring("property Index")]
HRESULT _stdcall Index([out, retval] long* pVal);
[id(0x0000000a), propget, helpstring("property RawMessage")]
HRESULT _stdcall RawMessage([out, retval] BSTR* pVal);
[id(0x0000000b), propget, hidden, helpstring("property RefCount")]
HRESULT _stdcall RefCount([out, retval] long* pVal);
[id(0x0000000c), propget, helpstring("property Priority")]
HRESULT _stdcall Priority([out, retval] BSTR* pVal);
[id(0x0000000d), propget, helpstring("property Status")]
HRESULT _stdcall Status([out, retval] enMessageStatus* pVal);
[id(0x0000000d), propput, helpstring("property Status")]
HRESULT _stdcall Status([in] enMessageStatus pVal);
[id(0x0000000e), propget, helpstring("property Subject")]
HRESULT _stdcall Subject([out, retval] BSTR* pVal);
[id(0x0000000f), propget, helpstring("property To")]
HRESULT _stdcall To([out, retval] BSTR* pVal);
[id(0x00000010), helpstring("method Move")]
HRESULT _stdcall Move(IEuFolder* NewParentFolder);
};
typedef [helpstring("Message header field")public]
__MIDL___MIDL_itf_EudoraExe_0000_0001 enHeaderField;
typedef [helpstring("Message header field")]
enum {
hfAttachments = 0,
hfBcc = 1,
hfCc = 2,
hfEmbeddedContent = 3,
hfFrom = 4,
hfHeaderDate = 5,
hfHeaderStatus = 6,
hfInReplyTo = 7,
hfMessageID = 8,
hfPersona = 9,
hfPrecedence = 10,
hfPriority = 11,
hfPriorityMatch = 12,
hfReferences = 13,
hfReplyTo = 14,
hfSubject = 15,
hfTo = 16
} __MIDL___MIDL_itf_EudoraExe_0000_0001;
typedef [helpstring("Message status types")public]
__MIDL___MIDL_itf_EudoraExe_0000_0002 enMessageStatus;
typedef [helpstring("Message status types")]
enum {
msUnread = 0,
msRead = 1,
msReplied = 2,
msForwarded = 3,
msRedirect = 4,
msUnsendable = 5,
msSendable = 6,
msQueued = 7,
msSent = 8,
msUnsent = 9,
msTimeQueued = 10
} __MIDL___MIDL_itf_EudoraExe_0000_0002;
[
uuid(EDA20004-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("EuMessages Class"),
noncreatable
]
coclass EuMessages {
[default] interface IEuMessages;
};
[
uuid(EDA20005-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("EuFolder Class"),
noncreatable
]
coclass EuFolder {
[default] interface IEuFolder;
};
[
uuid(EDA20015-AAAA-11D0-B3C5-00805F8AA4FB),
helpstring("EuFolders Class"),
noncreatable
]
coclass EuFolders {
[default] interface IEuFolders;
};
};