AMX DVX-21XXHD, Webconsole & Programming Manual

Page: 112 / 116

Appendix B: SMTP Support
112
NetLinx Integrated Controllers (Firmware v4)- WebConsole & Programming Guide
Sending Mail
Sending mail is accomplished with the use of the Master's built-in Mail Service. An outbound mail is handed to the Mail Service via
the following built-in NetLinx function:
sinteger SMTP_SEND (DEV responseDPS, CONSTANT CHAR toAddress[], CONSTANT CHAR mailSubject[], CONSTANT
CHAR mailBody[], CONSTANT CHAR textAttachment[])
where:

responseDPS - The DPS address to return asynchronous send status. Ex. 0:3:0

toAddress - The email address of destination. Ex.
john.doe@amx.com
.
Note that the NetLinx mail service supports up to eight recipient address (semi-colon delimited). These are "To" addresses
only (not "Cc" or "Bcc" addresses.)
The maximum number of characters allowed for email destination is 127.

mailSubject - The email subject line.

mailBody - The email body text.

textAttachment - A text filename to attach to the email (optional argument). Filenames must be 256 characters or less,
and file size must be under 65536 bytes. When no attachment is included textAttachment should be set to
NULL_STR
.
SMTP_SEND
returns a signed integer.

If the return value is negative (<0) that is an indication there was a failure in handing the message off to the mail service,
most likely due to an invalid argument supplied to the
SMTP_SEND
call.

If the return value is positive (>0) then the value is the index associated with the mail being sent.

Mail sends are asynchronous to the normal processing of the NetLinx application.

When
SMTP_SEND
is called and the mail is posted to the internal Mail Service, the NetLinx application will continue
executing the code following the
SMTP_SEND
.

The failed send status will be returned via an
ONERROR DATA_EVENT
for the responseDPS specified in the
SMTP_SEND
call
with
DATA.NUMBER
set to the error code and
DATA.TEXT
set to the mail identifier returned from the
SMTP_SEND
call.
Example
SMTP_SEND
:
DEFINE_DEVICE
MAIL_SERVICE=0:3:0
DEFINE_VARIABLE
SINTEGER MAIL_IDX
…
MAIL_IDX = SMTP_SEND(MAIL_SERVICE,'jdoe@somemail.com','Mail Subj','Mail Body', NULL_STR)
IF (MAIL_IDX < 0)
{
// FAILED TO SEND MAIL
}
…
DATA_EVEN [MAIL_SERVICE]
{
ONERROR:
{
// AN ERROR OCCURRED
LOG_ERROR("MAIL SEND FAILURE - IDX=',DATA.TEXT,' ERROR=',ITOA(DATA.NUMBER))
}
}
The possible error codes are:
MALFORMED DATA = 1;
NOT ENOUGH MEMORY = 2;
SERVER UNREACHABLE = 3;
AUTHENTICATION FAILURE = 4;
SMTP PROTOCOL ERROR = 5;