第五章 向邮件添加附件

向邮件添加附件

可以将附件添加到电子邮件或消息部分(具体地说，是添加到%Net.MailMessagePart或%Net.MailMessage的实例)。要执行此操作，请使用以下方法：

这些方法中的每一种都会将附件添加到原始邮件(或邮件部分)的Parts数组中，并自动将IsMultiPart属性设置为1。

AttachFile()

method AttachFile(Dir As %String, 
                  File As %String, 
                  isBinary As %Boolean = 1, 
                  charset As %String = "", 
                  ByRef count As %Integer) as %Status
复制代码

将给定文件附加到电子邮件。默认情况下，文件以二进制附件的形式发送，但您可以将其指定为文本。如果文件是文本，还可以指定该文件使用的字符集。

具体地说，此方法创建%Net.MailMessagePart的实例，并根据需要将文件内容放在BinaryData或TextData属性中，并根据需要设置CharSet属性和TextData.TranslateTable属性。该方法通过引用返回一个整数，该整数指示此新消息部分在部件数组中的位置。

此方法还设置消息或消息部分的Dir和FileName属性。

AttachStream()

method AttachStream(stream As %Stream.Object, 
                    Filename As %String, 
                    isBinary As %Boolean = 1, 
                    charset As %String = "", 
                    ByRef count As %Integer) as %Status
复制代码

将给定流附加到电子邮件。如果指定了Filename，则附件被视为文件附件。否则，它将被视为内联附件。

AttachNewMessage()

method AttachNewMessage() as %Net.MailMessagePart

复制代码

创建%Net.MailMessage的新实例，将其添加到消息中，并返回新修改的父消息或消息部分。

AttachEmail()
复制代码

给定一封电子邮件(%Net.MailMessage的实例)，此方法会将其添加到邮件中。此方法还设置消息或消息部分的Dir和FileName属性。

注意：此方法将contentType设置为"message/rfc822"。在这种情况下，不能添加任何其他附件。

示例：MessageWithAttach()

以下示例生成一封带有一个硬编码附件的简单电子邮件。它不为邮件提供任何地址；可以在实际发送邮件时提供该信息

/// w ##class(PHA.TEST.HTTP).MessageWithAttachment()
ClassMethod MessageWithAttachment() As %Net.MailMessage
{
	Set msg = ##class(%Net.MailMessage).%New()
	Set msg.Subject="Message with attachment "_$h
	Set msg.IsBinary=0
	Set msg.IsHTML=0
	Do msg.TextData.Write("This is the main message body.")

	//add an attachment
	Set status=msg.AttachFile("E:\", "HttpDemo.pdf")
	If $$$ISERR(status) {
		Do $System.Status.DisplayError(status)
		Quit $$$NULLOREF
	}
	b
	Quit msg
}

复制代码

使用SMTP服务器发送电子邮件

如果有权访问SMTP服务器，则可以发送电子邮件。SMTP服务器必须正在运行，并且必须具有使用它所需的权限。要发送电子邮件，请执行以下操作：

1. 创建%Net.SMTP实例并根据需要设置其属性，特别是以下属性：

• Smtpserver是正在使用的SMTP服务器的名称。
• 端口是在SMTP服务器上使用的端口；默认值为25。
• 时区指定RFC 822指定的服务器时区，例如 "EST" 或 "-0400" 或 "LOCAL"。如果未设置，消息将使用世界时。

此对象描述将使用的SMTP服务器。

2. 如果SMTP服务器需要身份验证，请指定必要的凭据。为此：

a. 创建%Net.Authenticator的实例。

b. 设置此对象的用户名和密码属性。

c. 将%Net.SMTP实例的验证器属性设置为等于此对象。

d. 如果邮件本身具有授权发件人，请设置%Net.SMTP实例的AuthFrom属性。

3. 要使用到SMTP服务器的SSL/TLS连接，请执行以下操作：

a. 将SSLConfiguration属性设置为要使用的已激活SSL/TLS配置的名称。

SSL/TLS配置包括一个名为Configuration Name的选项，该选项是在此设置中使用的字符串。

b. 将UseSTARTTLS属性设置为0或1。

在大多数情况下，使用值0。如果服务器交互在普通TCP套接字上开始，然后在与普通套接字相同的端口上切换到TLS，则使用值1。

或者，将SSLCheckServerIdentity属性设置为1。如果要验证证书中的主机服务器名称，请执行此操作。

4. 创建要发送的电子邮件(如“创建单部分电子邮件”和“创建多部分电子邮件”中所述)。
5. 调用SMTP实例的send()方法。此方法返回一个状态，应该检查该状态。
6. 如果返回的状态指示错误，请检查Error属性，该属性包含错误消息本身。
7. 检查FailedSend属性，该属性包含发送操作失败的电子邮件地址列表。

以下各节中的示例使用了两种不同的免费SMTP服务，这些服务在编写本手册时是可用的。选择这些服务并不意味着特别认可。还要注意的是，这些示例并没有显示实际的密码。

Samples命名空间中还有其他示例。要查找它们，请在该命名空间中搜索%Net.SMTP。

重要提示：%Net.SMTP将邮件正文写入临时文件流。默认情况下，该文件被写入命名空间目录，如果该目录需要特殊的写入权限，则不会创建该文件，并且您会得到一个空的消息正文。

可以为这些临时文件定义新路径，并选择不限制写访问的路径(例如，/tmp)。为此，请设置全局节点%SYS("StreamLocation",namespace)，其中NAMESPACE是运行代码的名称空间。例如：

Set ^%SYS("StreamLocation","SAMPLES")="/tmp" 
复制代码

如果%SYS("StreamLocation",namespace)为NULL，则InterSystems IRIS使用%SYS("TempDir",namespace)指定的目录。如果未设置%SYS("TempDir",namespace)，则IRIS使用 %SYS("TempDir")指定的目录

示例1：HotPOPAsSMTP()和SendSimpleMessage()

此示例由一起使用的两个方法组成。第一个创建%Net.SMTP的实例，该实例使用已在HotPOP SMTP服务器上设置的测试帐户：

/// w ##class(PHA.TEST.HTTP).HotPOPAsSMTP()
ClassMethod HotPOPAsSMTP() As %Net.SMTP
{
  Set server=##class(%Net.SMTP).%New()
  Set server.smtpserver="smtp.hotpop.com"
  //HotPOP SMTP服务器使用默认端口(25)
  Set server.port=25
  
  //创建对象以进行身份验证
  Set auth=##class(%Net.Authenticator).%New()
  Set auth.UserName="isctest@hotpop.com"
  Set auth.Password="123pass"
  
  Set server.authenticator=auth
  Set server.AuthFrom=auth.UserName
  b
  Quit server
}

复制代码

下一个方法使用提供的SMTP服务器作为参数发送一条简单、唯一的消息：

ClassMethod SendSimpleMessage(server As %Net.SMTP) As %List
{
  Set msg = ##class(%Net.MailMessage).%New()
  Set From=server.authenticator.UserName
  Set:From="" From="xxx@xxx.com"
  Set msg.From = From
  
  Do msg.To.Insert("xxx@xxx.com")
  //Do msg.Cc.Insert("yyy@yyy.com")
  //Do msg.Bcc.Insert("zzz@zzz.com")
  Set msg.Subject="Unique subject line here "_$H
  Set msg.IsBinary=0
  Set msg.IsHTML=0
  Do msg.TextData.Write("This is the message.")
  
  Set status=server.Send(msg)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status)
    Write server.Error
    Quit ""
  }
  Quit server.FailedSend
}
复制代码

示例2：YPOPsAsSMTP()

此示例创建使用YPOPS的%Net.SMTP实例的实例，YPOPS是一种客户端软件，提供对Yahoo电子邮件帐户的SMTP和POP3访问。它使用已为此目的设置的测试帐户：

ClassMethod YPOPsAsSMTP() As %Net.SMTP
{
  Set server=##class(%Net.SMTP).%New()
  //local host acts as the server
  Set server.smtpserver="127.0.0.1"
  //YPOPs uses default port, apparently
  Set server.port=25
  
  //Create object to carry authentication
  Set auth=##class(%Net.Authenticator).%New()
  //YPOPs works with a Yahoo email account
  Set auth.UserName="isc.test@yahoo.com"
  Set auth.Password="123pass"
  
  Set server.authenticator=auth
  Set server.AuthFrom=auth.UserName
  Quit server
}
复制代码

可以将其与上例中所示的SendSimpleMessage方法一起使用。

示例3：SendMessage()

以下更灵活的方法同时接受SMTP服务器和电子邮件。电子邮件应已包含主题行(如果SMTP服务器要求)，但不必包含地址。然后，此方法将电子邮件发送到一组硬编码的测试目的地：

ClassMethod SendMessage(server As %Net.SMTP, msg As %Net.MailMessage) As %Status
{
  Set From=server.authenticator.UserName
  //make sure From: user is same as used in authentication
  Set msg.From = From
  
  //finish addressing the message
  Do msg.To.Insert("xxx@xxx.com")
  //send the message to various test email addresses
  Do msg.To.Insert("isctest@hotpop.com")
  Do msg.To.Insert("isc_test@hotmail.com")
  Do msg.To.Insert("isctest001@gmail.com")
  Do msg.To.Insert("isc.test@yahoo.com")
  
  Set status=server.Send(msg)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status)
    Write server.Error
    Quit $$$ERROR($$$GeneralError,"Failed to send message")
  }
  Quit $$$OK
}
复制代码

%Net.SMTP的其他属性

%Net.SMTP类还具有一些您可能需要的其他属性，具体取决于使用的SMTP服务器：

• AllowHeaderEncoding指定Send()方法是否对非ASCII标头文本进行编码。默认值为1，这意味着非ASCII标头文本按照RFC 2047指定的方式进行编码。
• ContinueAfterBadSend指定在检测到失败的电子邮件地址后是否继续尝试发送邮件。如果ContinueAfterBadSend为1，系统会将失败的电子邮件地址添加到FailedSend属性的列表中。默认值为0。
• ShowBcc指定是否将密件抄送标头写入电子邮件。这些通常会被SMTP服务器过滤掉。