Sending Email from Duet

This guide is intended to be a very basic introduction to use amx_mail.jar to send email from Cafe Duet. There are several steps to obtain the necessary files and setup the Duet environment to use them.

Step 1: Obtain amx_mail.jar

The amx_mail.jar file exists on your AMX control system running firmware version 4 and above. The file is required by Cafe Duet (eclipse) as a library reference to prevent compiler errors and/or warnings, and for it to be available in the list of available Import Packages. The file does not need to be included in your module jar. There are two ways that I know of to acquire this file, from AMX technical support, and by copying it from the master itself.

Step 2: Add amx_mail.jar to the Java Build Path

1. In the "Navigator" tab of Cafe Duet right click on your Duet Project and select "Properties".
2. In the "Properties" dialog, select "Java Build Path" from the tree on the left.
3. Select the "Libraries" tab.
4. Click on the "Add External JARs..." button.
5. Navigate to the "amx_mail.jar" file and select it.
6. Click on the "Open" button.

Step 3: Add com.amx.mail to the Import Packages list

1. In the "Navigator" tab of Cafe Duet expand your Duet project and find the "META-INF" folder, expand it.
2. Double click manifest.duetmf to open the "Duet Manifest Editor".
3. Scroll down in the Duet Manifest Editor to the "Import Packages" section.
4. Click on the "Add..." button.
5. Select "com.amx.mail" in the list. Click on "OK".
6. "com.amx.mail" should be added to the list of "Import Packages".
7. Leave the version number field empty! In all the 4.x.x versions of firmware that I have tested the AMX bundles were exported without version numbers. If a version number is entered into the field the bundle/class will not be resolved at runtime.

Step 4: Example Code

package com.example.duet.mail.test.dr1_0_0;

import java.util.Properties;

import org.osgi.framework.BundleContext;

import com.amx.duet.da.NetLinxDevice;
import com.amx.duet.devicesdk.Utility;

import com.amx.mail.MailRef;
import com.amx.mail.MailListener;

public class MailTest extends Utility{

	MailRef amxMail = null;
	MailListener mailListener = this.new InnerMailListener();
	Object callerData = new Object();
	
	public MailTest() {
		super();
		// TODO Auto-generated constructor stub
	}

	/**
	 * @param bctxt
	 * @param nd
	 * @param props
	 */
	public MailTest(BundleContext bctxt, NetLinxDevice nd, Properties props) {
		super(bctxt, nd, props);
		amxMail = new MailRef(bctxt, mailListener);
		// TODO Auto-generated constructor stub
	}

	protected void doAddNetLinxDeviceListeners() {
		// TODO Auto-generated method stub
		
	}

	protected boolean doNetLinxDeviceInitialization() {
		amxMail.setServerName("mail.example.com");
		amxMail.setServerPort((char)25);
		amxMail.setUsername("user@example.com");
		amxMail.setFromAddress("user@example.com");
		amxMail.setPassword("password");
		amxMail.send("user2@example.com", "Test Email from AMX Java", "Java Test", null, callerData);
		return false;
	}

	public boolean isDeviceOnLine() {
		// TODO Auto-generated method stub
		return false;
	}

	public boolean isDataInitialized() {
		// TODO Auto-generated method stub
		return false;
	}

	private class InnerMailListener implements MailListener {

		/* (non-Javadoc)
		 * @see com.amx.mail.MailListener#handleMailEvent(java.lang.Object, int)
		 */
		public void handleMailEvent(Object arg0, int arg1) {
			switch (arg1) {
				case MailListener.cMailErrAuthFailure: {
					System.out.println("Mail Error - Authentication Failure");
				}
				case MailListener.cMailErrMalformedData: {
					System.out.println("Mail Error - Malformed Mail");
				}
				case MailListener.cMailErrNoMemory: {
					System.out.println("Mail Error - Out of Memeory");
				}
				case MailListener.cMailErrProtocol: {
					System.out.println("Mail Error - Protocol Error");
				}
				case MailListener.cMailErrServerUnreachable: {
					System.out.println("Mail Error - Server Unreachable");
				}
				case MailListener.cMailErrUnknown: {
					System.out.println("Mail Error - Unknown Error");
				}
			}
		}
	}
}

Notes

• The setServerPort method takes a char value as its parameter, hence the type cast.
• From what I have been able to tell the the last parameter in the send method is only for identifying the call to the send method that has called the mailListener, and is returned as arg0.
• The callerData Object should not be neccessary and could just as easily be null or amxMail itself.
• The paramters for the send method are: String toAddress, String subject, String body, String attachment, Object reference.
• The attachment String is a Path/File name of a txt file. I think that any other attachment types would have to be Base64 encoded.

Please feel free to add any additional notes, corrections, etc.