Class Reference
IRIS for UNIX 2019.4
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%Net] >  [FetchMailProtocol]
Private  Storage   

abstract class %Net.FetchMailProtocol extends %RegisteredObject

Abstract Class that %Net.POP3 implements.

Methods are Connect,,GetMailBoxStatus, GetSizeOfMessages,GetMessageUIDArray, FetchMessage,DeleteMessage, RollbackDeletes,QuitAndCommit, QuitAndRollback,Ping.

Important after Connect is called, you must call before your session ends either QuitAndCommit or QuitAndRollback.

Each of the methods of this class returns a value of type %Status indicating success or failure.

The charset used for each text mail message part is returned in the Charset property of the %Net.MailMessagePart class. The data is automatically translated to the current cache locale's default character set when reading from the TextData text stream.

The following shows an example of getting messages:

	#include %occOptions
	#include %occStatus
	; display mail but don't delete from mailbox
	testmail6 ;
	new mailserver,status,err,mailMsg
	set mailserver=##class(%Net.POP3).%New()
	set mailserver.AttachDir="d:\attach\"  ; need terminating \
	set mailserver.StoreAttachToFile=1
	write !,"Calling Connect"
	set status=mailserver.Connect("moon.kinich.com","testjsl","jsltest")
	if $$$ISERR(status) do DecomposeStatus^%apiOBJ(status,.err) write !,err(err),! quit
	write !,"Calling Fetch to retrieve the oldest message on the server."
	set status=mailserver.Fetch(1,.mailMsg,0)
	if $$$ISERR(status) do DecomposeStatus^%apiOBJ(status,.err) write !,err(err),! quit
	write !,"from="_mailMsg.From
	write !,"to="_mailMsg.Headers.GetAt("to")
	write !,"date="_mailMsg.Date
	write !,"subject="_mailMsg.Subject
	write !,"messagesize="_mailMsg.MessageSize
	do DumpMessage(mailMsg)
	quit
	DumpMessage(msg) 
	new i,index,value,len
	if msg.IsMultiPart {
	    for i=1:1:msg.Parts.Count() write !,"Dumping part "_i do DumpMessage(msg.Parts.GetAt(i))
	    quit
	}
	set index=""  for  set value=msg.Headers.GetNext(.index) quit:index=""  write !,"Headers("_index_")="_value
	if msg.IsBinary {
	    write !,"msg is binary, filename="_msg.FileName_" filename="_msg.GetAttribute("content-disposition","filename")
	} else {
	    write !,"Dumping text msg Filename="_msg.FileName_" filename="_msg.GetAttribute("content-disposition","filename"),!
	    set stream=msg.TextData
	    do stream.Rewind()
	    set len=32763
	    while 'stream.AtEnd {
	        write stream.Read(.len)
	    }
	}
	quit

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
5 15


Summary

Properties
AttachDir Connected Debug StoreAttachToFile
StoreInlineToFile

Methods
%%OIDGet %AddToSaveSet %BindExport %BuildObjectGraph
%ClassIsLatestVersion %ClassName %Close %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IncrementCount %IsA %IsModified
%New %NormalizeObject %ObjectModified %OnClose
%OriginalNamespace %PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %ValidateObject Connect DeleteMessage
Fetch FetchFromStream FetchMessage FetchMessageInfo
GetMailBoxStatus GetMessageUID GetMessageUIDArray GetSizeOfMessages
Ping QuitAndCommit QuitAndRollback RollbackDeletes

Subclasses
%Net.POP3

Properties

• property AttachDir as %String;
When receiving messages using POP3, the directory where attached files will be stored
• property Connected as %Boolean;
• property Debug as %Integer [ InitialExpression = 0 ];
• property StoreAttachToFile as %Integer [ InitialExpression = 0 ];
We always store attachments as a part in the message. If StoreAttachToFile=true and content-disposition MIME header of attachment part = "attachment", we ALSO store to the directory specified in AttachDir
• property StoreInlineToFile as %Integer [ InitialExpression = 0 ];
We always store attachments as a part in the message. If StoreInlineToFile=true and content-disposition MIME header of attachment part = "inline", we ALSO store to the directory specified in AttachDir

Methods

• method %OnClose() as %Status

Protect against terminating without doing a quit

• method Connect(PopServer As %String, UserName As %String, Password As %String) as %Status

Use to logon to your mail server using the username and password that are the parameters to this routine.

• method DeleteMessage(MessageNumber As %Integer) as %Status

This method deletes a single message. MessageNumber must be a valid message number and the message must not be currently marked for deletion.

• method Fetch(MessageNumber As %Integer, ByRef Msg As %Net.MailMessage, Delete As %Boolean, messageStream As %BinaryStream) as %Status

This method retrieves a single message. MessageNumber must be a valid message number and the message must not be currently marked for deletion.

Msg is a MailMessage (possibly multipart) and a return parameter. The fetched mail message is returned in this parameter

If Delete is 1, the message is deleted. If 0, it is not deleted.

If messageStream is specified, then the original message is written to this binary stream. messageStream needs to be a binary stream since mail messages may include binary data and multiple charsets.

• method FetchFromStream(messageStream As %BinaryStream, ByRef Msg As %Net.MailMessage) as %Status

This method retrieves a single eml format message from a binary stream. messageStream must be a binary stream containing the message.

Msg is a MailMessage (possibly multipart) and a return parameter. The fetched mail message is returned in this parameter

• method FetchMessage(MessageNumber As %Integer, ByRef From As %String, ByRef To As %String, ByRef Date As %String, ByRef Subject As %String, ByRef MessageSize As %Integer, ByRef MsgHeaders As %ArrayOfDataTypes, ByRef Msg As %Net.MailMessage, Delete As %Boolean) as %Status

This method retrieves a single message. MessageNumber must be a valid message number and the message must not be currently marked for deletion.

Msg is a MailMessage (possibly multipart) and a return parameter. The fetched mail message is returned in this parameter

If Delete is 1, the message is deleted. If 0, it is not deleted.

FetchMessage also returns selected headers in additional by reference parameters as well as the array of all headers.

• method FetchMessageInfo(MessageNumber As %Integer, Lines As %Integer, ByRef From As %String, ByRef To As %String, ByRef Date As %String, ByRef Subject As %String, ByRef MessageSize As %Integer, ByRef MsgHeaders As %ArrayOfDataTypes, ByRef MessageText As %String) as %Status

This method retrieves a single message. MessageNumber must be a valid message number and the message must not be currently marked for deletion.

An upper bound is put on number of lines of message text retrieved by Lines.

The text of the retrieved message is returned in the MessageText argument as a %String.

FetchMessageInfo is typically used to get From, Date, and other header information without actually getting the message text. This allows one to filter out messages from parties one wishes to exclude or to zero in on messages one particularly wants. Since getting message text is something that can happen over a slow modem, this is a desirable feature.

• method GetMailBoxStatus(ByRef NumberOfMessages As %Integer, ByRef NumberOfBytes As %Integer) as %Status

Get information about your mail box, the number of bytes it contains, and the number of messages;

• method GetMessageUID(MessageNumber As %Integer, ByRef UniqueID As %String) as %Status

For the message number singled out by MessageNumber, this function returns the corresponding unique id. The message number must not correspond to a non-existent message or a message already marked for deletion or an error message is returned.

The unique message identifier is at most 70 characters long and each character is ASCII and printable (0x21 to 0x7E).

Each identifier is unique within the mailbox and is persistent. If a given message has a particular unique identifier in one session, it must have the same unique ID in all sessions. Once used, a given UID can never be reused even if the corresponding message is deleted.

If a specified message (corresponding to MessageNumber) does not exist or is marked for deletion, the function returns an error %Status.

This command is used to implement a poor mans server-based message store. Basically, a client does not automatically delete messages, after getting messages, then at the start of each session, it calls GetMessageUIDs to obtain a list of all messages currently on the server. Any UIDs not currently known by the client are retrieved. That of course requires the client to keep track of the UIDs for all retrieved messages.

• method GetMessageUIDArray(MessageNumber As %String = "", ByRef ListOfUniqueIDs As %ArrayOfDataTypes) as %Status

If you pass in an empty string "", an array with an element for each of the messages not marked for deletion is returned. Each element of the array has the message number as its index and the unique message identifier (UID) as its value..

If you pass in a message number, a one element array is returned. The element has the message number as its index and unique message identifier (UID) as its value. An error status is returned if a message with this message number does not exist or has been marked for deletion.

The unique message identifier is at most 70 characters long and each character is ASCII and printable (0x21 to 0x7E).

Each identifier is unique within the mailbox and is persistent. If a given message has a particular unique identifier in one session, it must have the same unique ID in all sessions. Once used, a given UID can never be reused even if the corresponding message is deleted.

If a specified message (corresponding to MessageNumber) does not exist or is marked for deletion, the function returns an error status.

This command is used to implement a poor man's server-based message store. Basically, a client does not automatically delete messages, after getting messages, then at the start of each session, it calls GetMessageUIDArray to obtain an array of all messages currently on the server. Any UIDs not currently known by the client are retrieved. That of course requires the client to keep track of the UIDs for all retrieved messages.

• method GetSizeOfMessages(MessageNumber As %String = "", ByRef ListOfSizes As %ArrayOfDataTypes) as %Status

If you pass in an empty string "", an array with an element for each of the messages not marked for deletion is returned. Each element of the array has the message number as its index and the size of the message in bytes as its value..

If you pass in a message number, a one element array is returned. The element has the message number as its index and the size of the message in bytes as its value. An error status is returned if a message with this message number does not exist or has been marked for deletion.

• method Ping() as %Status

This function is used to prevent an autologout timer from expiring or to determine if the server is still functioning on the connection.

• method QuitAndCommit() as %Status

This method ends the session of this Protocl object with the mail server.

Also, as a side-effect, any messages marked for deletion are deleted.

This function (or its companion QuitAndRollback) must be executed before the process that issued a connect ends or havoc could be wreaked upon the mail server. (Mail servers do not have to bullet proof themselves against connects not followed by a quit.)

• method QuitAndRollback() as %Status

This function calls RollbackDeletes and then quits.

This method ends the session of this Protocl object with the mail server.

This function (or its companion QuitAndCommit) must be executed before the process that issued a connect ends or havoc could be wreaked upon the mail server. (Mail servers do not have to bullet proof themselves against connects not followed by a quit.)

• method RollbackDeletes() as %Status

This method unmarks any messages previously marked for deletion.



Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.