電子メールの送受信
このトピックでは、InterSystems IRIS を使用して、MIME 電子メール・メッセージを送受信する方法について説明します。
例や広範なコメントについては、クラス・ドキュメントも参照してください。
Note:
このトピックの例は、テストやデモンストレーションの際に便利なように、電子メール・メッセージを管理するためのメソッドを異なる電子メール・サーバで使用できるようにまとめられています。必ずしも運用のニーズに最適なコード編成ではありません。
サポートされている電子メール・プロトコル
電子メールは、標準プロトコルを使用して、インターネット上でメッセージを送信します。InterSystems IRIS は、これらのプロトコルのうちの 3 つを以下のようにサポートします。
-
InterSystems IRIS は、MIME 電子メール・メッセージのオブジェクト表現を提供します。テキストおよびテキスト以外の添付、シングルパートまたはマルチパートのメッセージ本文、および ASCII および非 ASCII 文字セットのヘッダをサポートします (MIME 部分のより一般的なサポートについては、“MIME メッセージの作成、記述および読み取り” のトピックを参照)。
-
電子メールを SMTP サーバにより送信できます。SMTP (Simple Mail Transport Protocol) は、電子メールを送信するためのインターネット標準です。
-
POP3 により電子メール・サーバから電子メールを受信することもできます。PSP3 は、電子メールをリモート・サーバから取得するための最も一般的な標準です。
Note:
InterSystems IRIS は、メール・サーバを提供していません。その代わり、メール・サーバと接続し、やり取りする機能を提供します。
InterSystems IRIS で MIME 電子メール・メッセージを表す方法
まず、InterSystems IRIS で MIME 電子メール・メッセージを表す方法について理解すると便利です。
通常、マルチパート MIME メッセージは、以下の部分で構成されています。
-
メッセージ・ヘッダ のセット。各メッセージ・ヘッダには、メッセージ送信先アドレスなどの情報が含まれています。これには、メッセージ全体の Mime-Type ヘッダおよび Content-Type ヘッダも含まれています。
マルチパート・メッセージの場合、Content-Type ヘッダは、multipart/mixed または multipart のその他のサブタイプである必要があります。MIME 標準には、多くの異形があります。
-
それぞれが複数の部分からなる、複数のメッセージ部分。
InterSystems IRIS は、%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab (%Net.MailMessageOpens in a new tab のスーパークラス) の2 つのクラスを使用して、電子メール・メッセージを表します。以下のグラフィックに、これらのクラスの関係を示します。
一般に、
以下のセクションで詳細を説明します。
シングルパートの電子メール・メッセージの作成
シングルパート電子メール・メッセージを作成するには、%Net.MailMessageOpens in a new tab クラスを使用します。メール・メッセージを作成する手順は以下のとおりです。
-
%Net.MailMessageOpens in a new tab のインスタンスを作成します。
Tip:
%New() への引数として文字セットを指定できます。このようにした場合、メッセージに対して Charset プロパティが設定されます。このメッセージへの影響については、“自動エンコードと文字変換” を参照してください。
-
インスタンスの To プロパティ、From プロパティ、および Subject プロパティを設定します。
-
To — このメッセージの送信先の電子メール・アドレスのリスト。このプロパティは、標準の InterSystems IRIS リスト・クラスです。これを使用するには、標準のリスト・メソッドである Insert()、GetAt()、RemoveAt()、Count()、および Clear() を使用します。
-
From — このメッセージの送信元の電子メール・アドレス。
-
Subject — 使用している SMTP サーバで必要な場合、メッセージの件名。
-
オプションで、Date プロパティ、Cc プロパティ、Bcc プロパティ、およびその他のプロパティを設定します。詳細は、“基本的な電子メール・ヘッダの指定” を参照してください。
-
メッセージが平文でない場合、以下のプロパティを設定して、作成しているメッセージの種類を示します。
-
メッセージおよびそのヘッダの文字セットを指定するには、必要に応じて、Charset プロパティを設定します (このメッセージへの影響については、“自動エンコードと文字変換” を参照してください)。
Important:
メッセージ・コンテンツを追加する前に文字セットを指定することが重要です。
-
メッセージ・コンテンツを追加します。
Tip:
ストリームの Filename プロパティを指定する際は、必ず、ユーザが書き込みアクセス権を持つディレクトリを使用してください。
これらのプロパティを使用するには、標準ストリーム・メソッドである Write()、WriteLine()、Read()、ReadLine()、Rewind()、MoveToEnd()、および Clear() を使用します。ストリームの Size プロパティも使用もできます。これによりメッセージ・コンテンツのサイズが分かります。
Note:
使用している SMTP サーバの要件を理解しておく必要があります。例えば、SMTP サーバの中には、Subject ヘッダを含める必要があるものがあります。同様に、SMTP サーバの中には、任意の From ヘッダを許可しないものもあります。
同様に、SMTP サーバの中には、Priority ヘッダを認識するものもあれば、代わりに X-Priority を認識するものもあります。
“マルチパートの電子メール・メッセージの作成” を参照してください。
例 1 : CreateTextMessage()
以下のメソッドは、単純なメッセージを作成し、そのアドレスを指定します。
ClassMethod CreateTextMessage() As %Net.MailMessage
{
Set msg = ##class(%Net.MailMessage).%New()
set msg.From = "test@test.com"
Do msg.To.Insert("xxx@xxx.com")
Do msg.Cc.Insert("yyy@yyy.com")
Do msg.Bcc.Insert("zzz@zzz.com")
Set msg.Subject="subject line here"
Set msg.IsBinary=0
Set msg.IsHTML=0
Do msg.TextData.Write("This is the message.")
Quit msg
}
例 2 : SimpleMessage()
実際にメッセージを送信するときにアドレスを指定したい場合もあります (“SMTP サーバを使用した電子メールの送信” にある “例 3 : SendMessage()” を参照)。前の例の以下のバリエーションでは、アドレスのないテキスト・メッセージが生成されます。
ClassMethod SimpleMessage() As %Net.MailMessage
{
Set msg = ##class(%Net.MailMessage).%New()
Set msg.Subject="Simple message "_$h
Set msg.IsBinary=0
Set msg.IsHTML=0
Do msg.TextData.Write("This is the message.")
Quit msg
}
SAMPLES ネームスペースにその他の例があります。このネームスペースで、%Net.MailMessage を検索して見つけてください。
マルチパートの電子メール・メッセージの作成
マルチパートの電子メール・メッセージを作成する手順は以下のとおりです。
-
%Net.MailMessageOpens in a new tab のインスタンスを作成し、その To プロパティ、From プロパティ、および Subject プロパティを設定します。オプションで、その他のプロパティを設定し、その他のメッセージ・ヘッダを指定します。
-
IsMultiPart プロパティを 1 に設定します。
-
MultiPartType プロパティを "related"、"alternative"、"mixed" のいずれかに設定します。これは、メッセージ全体の Content-Type ヘッダに影響します。
-
メッセージに含まれる各部分について、%Net.MailMessagePartOpens in a new tab のインスタンスを作成し、“シングルパートの電子メール・メッセージの作成” の説明のとおり (手順 4 から開始)、そのプロパティを指定します。
-
親電子メール・メッセージの場合は、Parts プロパティを設定します。これは配列です。各子メッセージ部分をこの配列に挿入します。
メッセージを送信するときに、%Net.SMTPOpens in a new tab クラスは、必要に応じて (MultiPartType プロパティの値がある場合) 自動的にメッセージに対して Content-Type ヘッダを設定します。
メッセージへの添付の追加
添付を電子メール・メッセージまたはメッセージの部分 (具体的には、%Net.MailMessagePartOpens in a new tab または %Net.MailMessageOpens in a new tab のインスタンス) に追加できます。この操作には、以下のメソッドを使用します。
これらのメソッドは、それぞれ、添付を元のメッセージ (またはメッセージの部分) の 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.MailMessagePartOpens in a new tab のインスタンスを作成し、適宜、ファイルのコンテンツを BinaryData プロパティまたは TextData プロパティに配置し、必要に応じて、Charset プロパティおよび TextData.TranslateTable プロパティを設定します。メソッドは、Parts 配列内のこの新規メッセージ部分の位置を示す整数を参照によって返します。
このメソッドは、メッセージまたはメッセージの部分の 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 が指定されている場合、この添付はファイル添付と見なされます。指定されていない場合、インライン添付と見なされます。AttachFile() の説明を参照してください。
AttachEmail()
method AttachEmail(mailmsg As %Net.MailMessage)
電子メール・メッセージ (%Net.MailMessageOpens in a new tab のインスタンス) がある場合、このメソッドは、それをメッセージに追加します。このメソッドは、メッセージまたはメッセージの部分の Dir プロパティおよび FileName プロパティも設定します。
Note:
このメソッドは、ContentType を "message/rfc822" に設定します。この場合、その他の添付は追加できません。
例 : MessageWithAttachment()
以下の例は、ハードコードされた添付が 1 つある簡単な電子メール・メッセージを生成します。メッセージのアドレスは提供しません。実際にメッセージを送信するときにこの情報を設定できます (“SMTP サーバを使用して電子メールを送信” の “例 3 : SendMessage()” を参照)。
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("c:\", "GNET.pdf")
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Quit msg
}
その他の例については、%Net.MailMessagePartOpens in a new tab クラスのクラス・リファレンスを参照してください。
SMTP サーバを使用した電子メールの送信
SMTP サーバにアクセスできる場合、電子メール・メッセージを送信できます。SMTP サーバが稼動しており、それを使用するために必要な権限を持っている必要があります。電子メールを送信するには、以下の手順を実行します。
-
%Net.SMTPOpens in a new tab のインスタンスを作成し、必要に応じてそのプロパティを設定します。特に、以下のプロパティを設定します。
-
smtpserver は、使用している SMTP サーバの名前です。
-
port は、SMTP サーバで使用しているポートです。既定値は、25 です。
-
timezone では、RFC 822Opens in a new tab によって指定されたとおりに、サーバのタイム・ゾーンを指定します。例えば、"EST"、"-0400"、"LOCAL" などです。これを設定しない場合、メッセージは協定世界時を使用します。
このオブジェクトは、使用する SMTP サーバを記述します。
-
SMTP サーバが認証を必要とする場合、必要な資格情報を指定します。そのためには、以下の操作を実行します。
-
%Net.AuthenticatorOpens in a new tab のインスタンスを作成します。
-
このオブジェクトの UserName プロパティおよび Password プロパティを設定します。
-
%Net.SMTPOpens in a new tab インスタンスの authenticator プロパティをこのオブジェクトと等しくなるように設定します。
-
メッセージ自体に許可されたセンダがある場合、%Net.SMTPOpens in a new tab インスタンスの AuthFrom プロパティを設定します。
-
MechanismList を設定します。ここでは、試行する認証方法を指定します。メール・サーバには使用できる認証メカニズムのリストが保持されていて、MechanismList にある最初のメカニズムがメール・サーバとの接続に使用されます。アプリケーションの要件とサーバの設定に適した MechanismList を定義します。
-
SMTP サーバへの SSL/TLS 接続を使用するには
-
SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。
SSL/TLS 構成の作成と管理の詳細は、インターシステムズの "TLS ガイド" を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。
-
UseSTARTTLS プロパティを 0 か 1 に設定します。
ほとんどの場合、0 の値を使用します。通常の TCP ソケットでサーバのやり取りが開始した後、通常のソケットとして同じポートの TLS に切り替わる場合、1 の値を使用します。詳細は、"RFC 3207Opens in a new tab" を参照してください。
-
必要に応じて、SSLCheckServerIdentity プロパティを 1 に設定します。これは、証明書のホスト・サーバ名を確認する場合に設定します。
-
送信する電子メール・メッセージを作成します (手順については、“シングルパートの電子メール・メッセージの作成” および “マルチパートの電子メール・メッセージの作成” を参照)。
-
SMTP インスタンスの Send() メソッドを呼び出します。このメソッドはステータスを返すので、それを確認する必要があります。
-
返されたステータスがエラーを示している場合、エラー・メッセージを含んでいる Error プロパティを確認します。
-
送信アクションに失敗した電子メールのアドレスのリストを含んでいる FailedSend プロパティを確認します。
以下のセクションの例は、このドキュメント執筆時点で使用可能な 2 つの異なる無料 SMTP サービスを使用しています。これらのサービスの選択は、特に推奨を意味しているわけではありません。また、例で示しているのは、実際のパスワードではありません。
SAMPLES ネームスペースにその他の例があります。このネームスペースで、%Net.SMTP を検索して見つけてください。%Net.SMTPOpens in a new tab のクラス・ドキュメントも参照してください。
Important:
%Net.SMTPOpens in a new tab は、メッセージ本文を一時ファイル・ストリームに書き込みます。既定では、このファイルはネームスペースのディレクトリに書き込まれますが、ディレクトリで特別な書き込み許可が必要な場合、ファイルは作成されずに空のメッセージ本文を取得することになります。
これらの一時ファイルに新規のパスを定義して、書き込みアクセスを制限しないパスを選択することができます (/tmp など)。そのためには、グローバル・ノード %SYS("StreamLocation",namespace) を設定します。ここで、namespace はお使いのコードが実行されているネームスペースです。以下はその例です。
Set ^%SYS("StreamLocation","SAMPLES")="/tmp"
%SYS("StreamLocation",namespace) が NULL の場合は、InterSystems IRIS では %SYS("TempDir",namespace) で指定されたディレクトリが使用されます。%SYS("TempDir",namespace) が設定されていない場合は、InterSystems IRIS では %SYS("TempDir") で指定されたディレクトリが使用されます。
例 1 : HotPOPAsSMTP() および SendSimpleMessage()
この例は、一緒に使用する 2 つのメソッドで構成されます。最初のメソッドは、HotPOP SMTP サーバで既に設定されているテスト・アカウントを使用する %Net.SMTPOpens in a new tab のインスタンスを作成します。
ClassMethod HotPOPAsSMTP() As %Net.SMTP
{
Set server=##class(%Net.SMTP).%New()
Set server.smtpserver="smtp.hotpop.com"
//HotPOP SMTP server uses the default port (25)
Set server.port=25
//Create object to carry authentication
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
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()
この例は、Yahoo 電子メール・アカウントへの SMTP および POP3 アクセスを提供するクライアント・ソフトウェアである YPOP を使用する %Net.SMTPOpens in a new tab のインスタンスを作成します。これは、この目的で既に設定されているテスト・アカウントを使用します。
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
}
この例は、“メッセージへの添付の追加” で説明されている SimpleMessage メソッド例および MessageWithAttachment メソッド例と共に使用するためのものです。
%Net.SMTP のその他のプロパティ
%Net.SMTPOpens in a new tab クラスには、使用している SMTP サーバによっては必要な場合がある以下のプロパティもあります。
-
AllowHeaderEncoding は、Send() メソッドが非 ASCII ヘッダ・テキストをエンコードするかどうかを指定します。既定値は 1 で、これは、非 ASCII ヘッダ・テキストが RFC 2047Opens in a new tab によって指定されたとおりにエンコードされることを意味します。
-
ContinueAfterBadSend は、送信に失敗した電子メール・アドレスを検出した後、メッセージの送信を継続して試行するかどうかを指定します。ContinueAfterBadSend が 1 の場合、システムは、送信に失敗した電子メール・アドレスを FailedSend プロパティのリストに追加します。既定値は 0 です。
-
ShowBcc は、Bcc ヘッダを電子メール・メッセージに記述するかどうかを指定します。これらは通常、SMTP サーバによって、フィルタで除外されます。
POP3 サーバからの電子メールのフェッチ
このセクションでは、%Net.POP3Opens in a new tab クラスを使用して、電子メール・メッセージをフェッチする方法について説明します。ここでは、以下のトピックについて説明します。
例や広範なコメントについては、%Net.FetchMailProtocolOpens in a new tab のクラス・ドキュメントも参照してください。%Net.FetchMailProtocolOpens in a new tab は、%Net.POP3Opens in a new tab の抽象スーパークラスです。
POP3 サーバとの通信
必要な権限があり、メール・サーバが稼動している場合、POP3 プロトコルを使用して、メール・サーバから電子メール・メッセージをダウンロードし、処理することができます。一般に、POP3 サーバと通信するには、ログインし、メールボックスに影響を与える一連のアクションを実行し、変更をコミットまたはロールバックします。InterSystems IRIS 内でこれを行うには、以下を実行します。
-
%Net.POP3Opens in a new tab のインスタンスを作成します。このオブジェクトは、使用する POP3 サーバを記述します。
-
オプションで、%Net.POP3Opens in a new tab のインスタンスの以下のプロパティを指定します。
-
port — 使用するポートを指定します。既定値は 110 です。
-
timeout — 読み取りタイムアウトを秒単位で指定します。既定値は 30 秒です。
-
StoreAttachToFile — メッセージを読み取る際に、各添付をファイルに保存するかどうかを指定します (メッセージが content-disposition; attachment ヘッダを含んでいる場合)。既定値は False です。
この設定は、AttachDir も設定しないと、何も実行しないことに注意してください。
-
StoreInlineToFile — メッセージを読み取る際に、各インライン添付をファイルに保存するかどうかを指定します (メッセージが content-disposition; inline ヘッダを含んでいる場合)。既定値は False です。
この設定は、AttachDir も設定しないと、何も実行しないことに注意してください。
-
AttachDir — 添付を保存するディレクトリを指定します。既定値はありません。ディレクトリの名前は、オペレーティング・システムに応じて適切に、スラッシュ (/) またはバックスラッシュ (\) で終わるようにします。また、これが既に存在するディレクトリで、ユーザがこれに対するアクセス権を持っていることを確認してください。
-
IgnoreInvalidBase64Chars — Base-64 デコード中に検出された無効な文字を無視するかどうかを指定します。既定値は false です (無効な文字ではエラーが発生します)。RFC 2045Opens in a new tab では、Base-64 デコード中に予期しない文字を無視するか、エラーを発生させるかは曖昧です。
-
POP3 サーバへの SSL/TLS 接続を使用するには
-
SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。
SSL/TLS 構成の作成と管理の詳細は、インターシステムズの "TLS ガイド" を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。
-
UseSTARTTLS プロパティを 0 か 1 に設定します。
ほとんどの場合、0 の値を使用します。通常の TCP ソケットでサーバのやり取りが開始した後、通常のソケットとして同じポートの TLS に切り替わる場合、1 の値を使用します。詳細は、"RFC 2595Opens in a new tab" を参照してください。
UseSTATRTLS を 1 に設定している場合は、既定のポート 995 ではなく、ポート 110 にサーバを接続します。
-
必要に応じて、SSLCheckServerIdentity プロパティを 1 に設定します。これは、証明書のホスト・サーバ名を確認する場合に設定します。
-
インスタンスの Connect() メソッドを呼び出します。このメソッドは、3 つの引数を以下の順番で取ります。
-
POP3 サーバの名前
-
ユーザ名
-
パスワード
-
インスタンスのメソッドを使用して、メールボックスを調べ、メッセージを取得し、メッセージを削除します。以下のセクションで詳細を説明します。
-
オプションで、接続がタイムアウトするのを防ぐため、%Net.POP3Opens in a new tab インスタンスの Ping() メソッドを呼び出します。
-
オプションで、削除するようメッセージにマーク付けしたものの、やはり削除しないことにした場合は、%Net.POP3Opens in a new tab インスタンスの RollbackDeletes() メソッドを呼び出します。
-
メールボックスへの変更が完了したら、以下のメソッドのいずれかを呼び出します。
これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。完全なメソッドのシグニチャについては、%Net.POP3Opens in a new tab のクラス・リファレンスも参照してください。
以下のセクションの例は、このドキュメント執筆時点で使用可能な 2 つの異なる無料 POP3 サービスを使用しています。これらのサービスの選択は、特に推奨を意味しているわけではありません。また、例で示しているのは、実際のパスワードではありません。
例 1 : HotPOPAsPOP3()
以下のメソッドがこの目的で既に設定されているアカウントを使用して、HotPOP POP3 サーバにログインします。
ClassMethod HotPOPAsPOP3() As %Net.POP3
{
Set server=##class(%Net.POP3).%New()
//HotPOP POP3 server uses the default port
//but let's set it anyway
Set server.port=110
//just in case we plan to fetch any messages
//that have attachments
Set server.StoreAttachToFile=1
Set server.StoreInlineToFile=1
Set server.AttachDir="c:\DOWNLOADS\"
Set servername="pop.hotpop.com"
Set user="isctest@hotpop.com"
Set pass="123pass"
Set status=server.Connect(servername,user,pass)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Quit server
}
このメソッドは、%Net.POP3Opens in a new tab サーバ・インスタンスを返します。このトピックで後述する例の多くは、%Net.POP3Opens in a new tab インスタンスを引数として受け入れます。
例 2 : YPOPsAsPOP3()
以下のメソッドも、%Net.POP3Opens in a new tab サーバ・インスタンスを返します。この場合、Yahoo 電子メール・アカウントへの SMTP および POP3 アクセスを提供するクライアント・ソフトウェアである YPOP を使用しています。これは、この目的で既に設定されているテスト・アカウントを使用します。
ClassMethod YPOPsAsPOP3() As %Net.POP3
{
Set server=##class(%Net.POP3).%New()
//YPOPs uses the default port
//but let's set it anyway
Set server.port=110
//just in case we plan to fetch any messages
//that have attachments
Set server.StoreAttachToFile=1
Set server.StoreInlineToFile=1
Set server.AttachDir="c:\DOWNLOADS\"
//local host acts as the server
Set servername="127.0.0.1"
//YPOPs works with a Yahoo email account
Set user="isc.test@yahoo.com"
Set pass="123pass"
Set status=server.Connect(servername,user,pass)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Quit server
}
メールボックスに関する情報の取得
POP3 サーバに接続している間、ユーザ・アカウントにログインし、そのユーザ・アカウントのメールボックスにアクセスできます。以下のメソッドを使用して、メールボックスに何が含まれているのかを検索します。
GetMailBoxStatus()
メールボックス内のメッセージ数およびメールボックスが使用するバイト数を、参照によって返します。
GetMessageUIDArray()
最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。
配列キー |
配列項目 |
現在の状態でのメールボックス内のメッセージの番号。最初のメッセージが 1 番で、以降順次番号が割り当てられます。
指定したメッセージのメッセージ番号がすべてのセッションで同じであることは保証されません。 |
すべてのセッションで使用できる、このメッセージの永久の識別子である、一意のメッセージ識別子 (UID)。
UID は、各メールボックスに対して一意です。 |
GetSizeOfMessages()
最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。
配列キー |
配列項目 |
現在の状態でのメールボックス内のメッセージの番号。 |
このメッセージのサイズ (単位はバイト)。 |
これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。これらのメソッドの詳細は、“その他のメッセージ取得メソッド” も参照してください。
例 : ShowMailbox()
例えば、以下のメソッドは、現在アクセスしているメールボックスについての情報を記述します。
ClassMethod ShowMailbox(server as %Net.POP3)
{
Set status=server.GetMailBoxStatus(.count,.size)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit
}
Write "Mailbox information *****",!
Write "Number of messages in mailbox: ",count,!
Write "Size of messages: ",size,!
Set status=server.GetMessageUIDArray(,.uids)
Set status=server.GetSizeOfMessages(,.sizes)
//iterate through messages, get info, and write it
For i=1:1:count {
Set uid=uids.GetAt(i)
Set size=sizes.GetAt(i)
Write "Msg number:", i," UID:",uid, " size:",size,!
}
}
このメソッドは、以下のような出力を生成します。
Mailbox information *****
Number of messages in mailbox: 4
Size of messages: 18634
Msg number:1 UID:6ef78df6fd660391 size:7245
Msg number:2 UID:7410041a6faf4a87 size:5409
Msg number:3 UID:5555af7fa489e406 size:5121
Msg number:4 UID:299ad2b54c01a6be size:859
メールボックスからのメッセージのフェッチ
単にメッセージを取得するには、%Net.POP3Opens in a new tab クラスの以下のメソッドのいずれかを使用します。
FetchMessage()
最初の引数としてメッセージ番号が指定されている場合、このメソッドは、From や To およびその他の共通ヘッダなどの情報、すべてのヘッダ (共通ヘッダを含む) を含む配列、およびメッセージ・コンテンツ自体を (参照によって) 返します。
これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。メッセージが現在削除するようマーク付けされている場合、これらのメソッドは、エラー・ステータスを返します。
Fetch() および FetchMessage() のメソッド・シグニチャ一覧については、“その他のメッセージ取得メソッド” も参照してください。
例 : FetchMailbox()
以下の例は、“メールボックスに関する情報の取得” で説明されている ShowMailbox の例のバリエーションです。このメソッドは、Fetch() メソッドを使用し、各メッセージを調べ、各メッセージの件名行を記述します。
ClassMethod FetchMailbox(server As %Net.POP3)
{
Set status=server.GetMailBoxStatus(.count,.size)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Write "Mailbox information *****",!
Write "Number of messages in mailbox: ",count,!
Write "Size of messages: ",size,!
Set status=server.GetMessageUIDArray(,.uids)
Set status=server.GetSizeOfMessages(,.sizes)
//iterate through messages, get info, and write it
For i=1:1:count {
Set uid=uids.GetAt(i)
Set size=sizes.GetAt(i)
Set status=server.Fetch(i,.msg)
If $$$ISERR(status) {
Set subj="***error***"
} else{
Set subj=msg.Subject
}
Write "Msg number:", i," UID:",uid, " Size:",size
Write " Subject: ",subj,!
}
}
ファイルとしての添付の保存
Content-Disposition ヘッダにより、ファイル名を付加、あるいは付加せずに attachment を指定する場合があります。以下はその例です。
Content-Disposition: attachment; filename=genome.jpeg;
Content-Disposition ヘッダで attachment を指定した場合、ユーザの %Net.POP3Opens in a new tab インスタンスでメッセージ内のすべての添付をファイルに保存できます。この機能を有効にするには、以下を行います。
-
%Net.POP3Opens in a new tab のインスタンスの以下のプロパティを指定します。
-
StoreAttachToFile を 1 に設定します。
-
StoreInlineToFile を 1 に設定します。
-
AttachDir に有効なディレクトリを指定します。ディレクトリの名前は、オペレーティング・システムに応じて適切に、スラッシュ (/) またはバックスラッシュ (\) で終わるようにします。また、これが既に存在するディレクトリで、ユーザがこれに対するアクセス権を持っていることを確認してください。
-
ユーザの %Net.POP3Opens in a new tab インスタンスの Fetch() または FetchMessage() を呼び出します。
各ファイル名は、以下のとおり決定されます。
-
Content-Disposition ヘッダでファイル名が指定されている場合、そのファイル名が使用されます。
-
それ以外の場合、Content-Type ヘッダでファイル名が指定されていれば、そのファイル名が使用されます。
-
それ以外の場合、システムは、ATTxxxxxx.dat の形式の名前を作成します。
以下の点に注意してください。
-
ファイルが既に存在する場合、添付はダウンロードされません。
-
AttachDir には、既定値はありません。
-
添付のサイズは、InterSystems IRIS によっては制限されませんが、ファイル・システムによって制限される場合があります。
-
ここでは、Dir および FileName プロパティは使用されていません。これらのプロパティは、“メッセージへの添付の追加” で説明したとおり、添付をメール・メッセージにアップロードする場合にのみ関係します。
例 : GetMsg()
以下のメソッド例は、%Net.POP3Opens in a new tab のインスタンスおよびメッセージ番号を指定すると、メッセージ全体を取得します。
ClassMethod GetMsg(server as %Net.POP3,msgno as %Integer) as %Net.MailMessage
{
Set status=server.Fetch(msgno,.msg)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Quit msg
}
メッセージに添付があり、%Net.POP3Opens in a new tab サーバの StoreAttachToFile、StoreInlineToFile、および AttachDir の各プロパティを指定した場合、それらの添付は、このメソッドを呼び出したときに指定のディレクトリに保存されます。
その他のメッセージ取得メソッド
このセクションでは、メッセージを調べ、取得する際に使用できる %Net.POP3Opens in a new tab のメソッドをすべてリストします。
Fetch()
method Fetch(MessageNumber As %Integer,
ByRef MailMsg As %Net.MailMessage,
Delete As %Boolean = 0,
messageStream As %BinaryStream) as %Status
MessageNumber によって指定されたメッセージを (参照によって) 返し、オプションでそのメッセージに削除するようマーク付けします。メッセージが既に削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
messageStream が指定された場合、元のメッセージはこのバイナリ・ストリームに書き込まれます。
FetchFromStream()
method FetchFromStream(messageStream As %BinaryStream, ByRef Msg As %Net.MailMessage) as %Status
このメソッドは、Fetch() に messageStream 引数を指定した場合に使用します。
単一の電子メール・メッセージを指定されたバイナリ・ストリームから取得します。messageStream は、メッセージを含んだバイナリ・ストリームである必要があります。 このメッセージは Msg の参照によって返されます。これはマルチパート・メッセージとなる可能性があります。
FetchMessage()
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 MailMsg As %Net.MailMessage,
Delete As %Boolean = 0) as %Status
特定のメッセージ・ヘッダ、メッセージ・サイズ、メッセージ・ヘッダ配列、およびメッセージ自体を (参照によって) 返し、オプションでメッセージに削除するようマーク付けします。メッセージが既に削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
FetchMessageHeaders()
method FetchMessageHeaders(MessageNumber As %Integer,
ByRef MsgHeadersArray As %String) as %Status
メッセージ番号を指定すると、このメソッドは、そのメッセージのすべてのヘッダを含む配列を (参照によって) 返します。メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
FetchMessageInfo()
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
メッセージ番号を指定すると、このメソッドは、特定のメッセージ・ヘッダ、メッセージ・サイズ、メッセージ・ヘッダの配列、およびこのメッセージのテキストの指定の行数を (参照によって) 返します。 メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
GetAttachedEmail()
method GetAttachedEmail(msgpart As %Net.MailMessagePart,
Output mailmsg As %Net.MailMessage) as %Status
メッセージ部分を指定すると、このメソッドは、メッセージ部分からのデータで初期化されたシングルパートの電子メール・メッセージを (出力パラメータとして) 返します。
GetMessageUID()
method GetMessageUID(MessageNumber As %Integer,
ByRef UniqueID As %String) as %Status
メッセージ番号を指定すると、メッセージの UID を (参照によって) 返します。メッセージ番号およびUID についての詳細は、前のセクションを参照してください。 メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
GetMessageUIDArray()
method GetMessageUIDArray(MessageNumber As %String = "",
ByRef ListOfUniqueIDs As %ArrayOfDataTypes) as %Status
最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。
配列キー |
配列項目 |
現在の状態でのメールボックス内のメッセージの番号。最初のメッセージが 1 番で、以降順次番号が割り当てられます。
指定したメッセージのメッセージ番号がすべてのセッションで同じであることは保証されません。 |
すべてのセッションで使用できる、このメッセージの永久の識別子である、一意のメッセージ識別子 (UID)。
UID は、各メールボックスに対して一意です。 |
あるいは、メッセージ番号を指定すると、このメソッドは、そのメッセージの UID を含む 1 要素の配列を返します。この場合、メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
GetSizeOfMessages()
method GetSizeOfMessages(MessageNumber As %String = "",
ByRef ListOfSizes As %ArrayOfDataTypes) as %Status
最初の引数として空の文字列が指定されている場合、このメソッドは、メールボックス内のメッセージについての情報の配列を、参照によって返します (現在削除するようマーク付けされているものを除く)。この配列の各要素には、1 つのメッセージについての以下の情報が含まれています。
配列キー |
配列項目 |
現在の状態でのメールボックス内のメッセージの番号。 |
このメッセージのサイズ (単位はバイト)。 |
あるいは、メッセージ番号を指定すると、このメソッドは、そのメッセージのサイズ (バイト単位) を含む 1 要素の配列を返します。この場合、メッセージが現在削除するようマーク付けされている場合、このメソッドは、エラー・ステータスを返します。
メッセージの削除
メールボックスに接続している間は、ログインしているメールボックス内で削除するようメッセージにマーク付けすることができます。これは、以下の 2 つの方法で行うことができます。
以下の点に留意してください。
-
これらのメソッドは、メッセージを削除しません。削除するようこれにマーク付けします。メッセージは、QuitAndCommit() によって POP3 トランザクションを完了するまで削除されません。単にサーバから切断すると、変更は破棄されます。
-
RollbackDeletes() メソッドを呼び出してメッセージを変更し、削除のマーク付けを解除することができます。
-
これらの各メッセージはステータスを返すので、それを確認する必要があります。
例 : GetMsgAndDelete() および CommitChanges()
以下の例は、メッセージを取得し、削除するようマーク付けします。
ClassMethod GetMsgAndDelete(ByRef server As %Net.POP3, msgno As %Integer) As %Net.MailMessage
{
//third argument to Fetch says whether to
//mark for deletion
Set status=server.Fetch(msgno,.msg,1)
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$NULLOREF
}
Quit msg
}
このメッセージは、%Net.POP3Opens in a new tab の変更バージョンを (参照によって) 返します。変更バージョンには、どのメッセージが削除するようマーク付けされているかについての情報が含まれています。
前述のメソッドを以下のようなメソッドと共に使用します。
ClassMethod CommitChanges(server As %Net.POP3) As %Status
{
//commit all changes and log out
Set status=server.QuitAndCommit()
If $$$ISERR(status) {
Do $System.Status.DisplayError(status)
Quit $$$ERROR($$$GeneralError,"Failed to commit changes")
}
Quit $$$OK
}
または、RollbackDeletes() や QuitAndRollback() によって変更をロールバックします。
受信電子メール・メッセージでの作業
このセクションでは、%Net.POP3Opens in a new tab によって取得した電子メール・メッセージ (%Net.MailMessageOpens in a new tab) での作業方法について説明します。
メッセージ・コンテンツ
一般的なメッセージの構造について理解したら、以下のテクニックを使用して、コンテンツを取得します。
メッセージを送信する電子メール・クライアントがメッセージ内のラップを決定します。メール・サーバも InterSystems IRIS も、これを制御できません。
その他のメッセージ情報
MessageSize プロパティは、添付された電子メール・メッセージ以外に、メッセージ長の合計を示します。
以下のメソッドは、メッセージについての追加情報を提供します。
GetLocalDateTime()
メッセージが取得された日付と時刻を、$HOROLOG 形式のローカル時間に変換して返します。
GetUTCDateTime()
メッセージが取得された日付と時刻を、$HOROLOG 形式の UTC に変換して返します。
GetUTCSeconds()
メッセージが取得された日付と時刻を 12/31/1840 からの秒数で返します。
日付/時刻変換では、次のクラス・メソッドも使用できます。
HToSeconds()
$HOROLOG 形式の日付および時刻を 12/31/1840 からの秒数に変換するクラス・メソッド。
SecondsToH()
12/31/1840 からの秒数を $HOROLOG 形式の日付および時刻に変換するクラス・メソッド。
例 1 : ShowMsgInfo()
%Net.MailMessageOpens in a new tab のインスタンスを指定すると、以下のメソッドは、メッセージについての情報を現在のデバイスに書き込みます。
ClassMethod ShowMsgInfo(msg as %Net.MailMessage)
{
Write "Message details *****",!
Write "To (count): ", msg.To.Count(),!
Write "From: ", msg.From,!
Write "Cc (count): ", msg.Cc.Count(),!
Write "Bcc (count): ", msg.Bcc.Count(),!
Write "Date: ", msg.Date,!
Write "Subject: ", msg.Subject,!
Write "Sender: ", msg.Sender,!
Write "IsMultipart: ", msg.IsMultiPart,!
Write "Number of parts: ", msg.Parts.Count(),!
Write "Number of headers: ", msg.Headers.Count(),!
Write "IsBinary: ", msg.IsBinary,!
Write "IsHTML: ", msg.IsHTML,!
Write "TextData: ", msg.TextData.Read(),!
Write "BinaryData: ", msg.BinaryData.Read(),!
}
このメソッドは、以下のような出力を生成します。
Message details *****
To (count): 1
From: "XXX XXX" <XXX@XXX.com>
Cc (count): 0
Bcc (count): 0
Date: Fri, 16 Nov 2007 11:57:46 -0500
Subject: test 5
Sender:
IsMultipart: 0
Number of parts: 0
Number of headers: 16
IsBinary: 0
IsHTML: 0
TextData: This is test number 5, which is plain text.
BinaryData:
例 2 : ShowMsgPartInfo()
以下のメソッドは、メッセージの部分についての情報を記述します。
ClassMethod ShowMsgPartInfo(msg as %Net.MailMessage, partno as %Integer)
{
Set part=msg.Parts.GetAt(partno)
Write "Message part details *****",!
Write "Message part: ", partno,!
Write "IsMultipart: ", part.IsMultiPart,!
Write "Number of parts: ", part.Parts.Count(),!
Write "Number of headers: ", part.Headers.Count(),!
Write "IsBinary: ", part.IsBinary,!
Write "IsHTML: ", part.IsHTML,!
Write "TextData: ", part.TextData.Read(),!
Write "BinaryData: ", part.BinaryData.Read(),!
}
これは、以下のような出力を生成します (前に示したメッセージとは異なるメッセージを指定した場合)。
Message part details *****
Message part: 1
IsMultipart: 0
Number of parts: 0
Number of headers: 2
IsBinary: 0
IsHTML: 0
TextData: 1 test string
BinaryData:
例 3 : ShowMsgHeaders()
以下のメソッドは、メッセージのヘッダについての情報を記述します。メッセージ部分に対して同じことを行う同様のメソッドを記述することができます。
ClassMethod ShowMsgHeaders(msg as %Net.MailMessage)
{
Set headers=msg.Headers
Write "Number of headers: ", headers.Count(),!
//iterate through the headers
Set key=""
For {
Set value=headers.GetNext(.key)
Quit:key=""
Write "Header:",key,!
Write "Value: ",value,!!
}
}
これは、以下のような出力を生成します。
Number of headers: 16
Header: content-class
Value: urn:content-classes:message
Header: content-type
Value: multipart/alternative; boundary="----_=_NextPart_001_01C8286D.D9A7F3B1"
Header: date
Value: Fri, 16 Nov 2007 11:29:24 -0500
Header: from
Value: "XXX XXX" <XXX@XXX.com>
Header: message-id
Value: <895A9EF10DBA1F46A2DDB3AAF061ECD501801E86@Exchange1_backup>
Header: mime-version
Value: 1.0
...
自動エンコードと文字変換
電子メールのメッセージ部分には、使用されている文字セットおよび使用されている Content-Transfer-Encoding (存在する場合) の両方についての情報が含まれています。参照のため、このセクションでは、この情報の使用方法について説明します。
InterSystems IRIS の文字変換に関する背景情報は、"サーバ側プログラミングの入門ガイド" の “ローカライズのサポート” を参照してください。
送信メール
%Net.SMTPOpens in a new tab は、各部分の Charset プロパティを確認し、適切な変換テーブルを適用します。
指定した部分に対して Charset プロパティを指定しない場合、InterSystems IRIS では UTF-8 が使用されます。
%Net.SMTPOpens in a new tab も ContentTransferEncoding プロパティを確認します。このプロパティが "base64" または "quoted-printable" の場合、メッセージを作成するときに、%Net.SMTPOpens in a new tab が、必要に応じて本文をエンコードします。(コンテンツ転送エンコードが "7bit" または "7bit" の場合、エンコードは必要ありません。)
Important:
コンテンツを "base64" でエンコードする場合、Unicode 文字を含めることはできません。送信するコンテンツに Unicode 文字が含まれている場合は必ず、$ZCONVERT を使用してコンテンツを UTF-8 に変換してください。