  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Twelve — Internet Functions (continued)
Legato 1.x allows for basic emails to be sent and retrieved using Simple Mail Transfer Protocol (SMTP) and Post Office Protocol (POP or POP3), respectively. The mail functions do not encode or decode the messages, that must be performed with the Multipurpose Internet Mail Extensions (MIME) functions. Legato does not directly support IMAP.
For sending email, the settings must be setup in the Application Preferences. Internet email is a wide ranging topic with many facets. This section is largely written assuming the reader has a basic understanding of email, SMTP and POP.
SMTP is supported for sending email. The process employs the application post office which once started runs in the background to send messages.
12.2.3 POP3 and the POP Object
The POP Object allows for the connection, downloading and management of email messages. Messages are only managed from the inbox of the server.
To use the POP Object, a handle must be created using the POPConnect functions which take the server name and user credentials as parameters. The returned handle is essentially a snap shot or session with the server at a particular time. Messages arriving after the connection has been established will appear in message lists. Therefore, mail functions should connect, perform their work, disconnect using the CloseHandle function and cycle again after some defined time period.
Unlike SMTP, the base application does not store POP user credentials. These must be managed by the script.
Once a connection has been established, the POPGetMessageCount, POPGetMessageIDList and POPGetMessageSizeList functions can be used to get a picture of what is in the mailbox. Mail entries are referenced by a position, a non-zero-based index where the oldest message is first and the latest is last.
Messages can be retrieved in part by using the POPGetMessageHeader function and in whole by using the POPGetMessage function. The return data from both functions is in MIME format. When retrieving the headers, the content layers are not included in the message. MIME functions can be used to open the messages and retrieve data such as MIMEOpen and MIMEGetProperties.
Note that Legato does not contain any built-in virus checking so it is up to the system to detect malicious data and the script programmer to insure data is not downloaded and executed. However, Legato will never interpret or execute any data within an email message.
Tracking individual messages is best performed by associating the downloaded data with a message ID. Each type of mail server will have its own scheme to create unique message IDs. The IDs can be of any value and format but by RFC specification each ID string will not exceed 70 characters. Since the format is not guaranteed, programmers should treat the string as an ID and avoid interpreting its content. Messages cannot be directly referenced by ID. Rather, the list of IDs must be downloaded using the POPGetMessageIDList and then referenced by array position.
Mailbox items can be deleted using the POPDeleteMessage function. The messages are not actually deleted until the session is closed. It is up to the script to manage the mailbox. Not managing the messages on the server by failing to delete item can result in poor performance on both the server and client.
Example POP mailbox reader (enter appropriate server and credentials within the POPConnect function):
string s1, s2, s3, s4;
handle hPop, hMIME;
string id_list[];
int ms_list[];
string data[][];
int sx, ix, count;
int rc;
AddMessage("POP3 Example:");
hPop = POPConnect("mail.xxxxxxxxxxxx.com", "my user", "my password");
if (IsError(hPop)) {
rc = GetLastError();
AddMessage(" FAIL: Failed to open Connection - 0x%08X", rc);
exit;
}
AddMessage(" PASS: POPConnect");
// Get Count
count = POPGetMessageCount(hPop);
if (IsError(count)) {
AddMessage("Failed to Get Message Count - 0x%08X", rc);
exit;
}
if (count == 0) {
AddMessage(" The Inbox is Empty -- STOPPED");
exit;
}
id_list = POPGetMessageIDList(hPop);
ms_list = POPGetMessageSizeList(hPop);
count++; // zero-inclusive
// Dump Message Headers to Log
AddMessage("Message List (%d messages):", count - 1);
ix = 1;
while (ix < count) {
s1 = POPGetMessageHeader(hPop, ix);
hMIME = MIMEOpen(s1);
if (IsError(hMIME)) {
rc = GetLastError();
s2 = "";
s3 = "--Header Error--";
s4 = FormatString("Code: 0x%08X", rc);
}
else {
s2 = ""; s3 = ""; s4 = "";
data = MIMEGetProperties(hMIME);
sx = FindInTable(data, "Date");
if (sx >= 0) { s2 = data[sx][1]; }
sx = FindInTable(data, "Subject");
if (sx >= 0) { s3 = data[sx][1]; }
sx = FindInTable(data, "From");
if (sx >= 0) { s4 = data[sx][1]; }
CloseHandle(hMIME);
}
s1 = TrailStringAfter(id_list[ix], 42);
s3 = TrailStringAfter(s3, 32);
AddMessage(" %3d %-42s %8a bytes %-33s %-32s %s ", ix, s1, ms_list[ix], s2, s3, s4);
ix++;
}
A resulting mail index will be dumped to the default log.
Page revised 2024-12-13
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.