Caché インターネット・ユーティリティの使用法
電子メールの送受信
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

この章では、Caché を使用して、MIME 電子メール・メッセージを送受信する方法について説明します。以下のトピックについて説明します。

例や広範なコメントについては、クラス・ドキュメントも参照してください。
Note:
この章の例は、テストやデモンストレーションの際に便利なように、電子メール・メッセージを管理するためのメソッドを異なる電子メール・サーバで使用できるようにまとめられています。必ずしも運用のニーズに最適なコード編成ではありません。
サポートされている電子メール・プロトコル
電子メールは、標準プロトコルを使用して、インターネット上でメッセージを送信します。Caché は、これらのプロトコルのうちの 3 つを以下のようにサポートします。
Note:
Caché は、メール・サーバを提供していません。その代わり、メール・サーバと接続し、やり取りする機能を提供します。
Caché で MIME 電子メール・メッセージを表す方法
まず、Caché で MIME 電子メール・メッセージを表す方法について理解すると便利です。
通常、マルチパート MIME メッセージは、以下の部分で構成されています。
Caché は、%Net.MailMessage、および %Net.MailMessage のスーパークラスである %Net.MailMessagePart の2 つのクラスを使用して、電子メール・メッセージを表します。以下のグラフィックに、これらのクラスの関係を示します。
一般に、
以下のセクションで詳細を説明します。
シングルパートの電子メール・メッセージの作成
シングルパート電子メール・メッセージを作成するには、%Net.MailMessage クラスを使用します。メール・メッセージを作成する手順は以下のとおりです。
  1. %Net.MailMessage のインスタンスを作成します。
    Tip:
    %New() への引数として文字セットを指定できます。このようにした場合、メッセージに対して Charset プロパティが設定されます。このメッセージへの影響については、自動エンコードと文字変換 を参照してください。
  2. インスタンスの To プロパティ、From プロパティ、および Subject プロパティを設定します。
  3. オプションで、Date プロパティ、Cc プロパティ、Bcc プロパティ、およびその他のプロパティを設定します。詳細は、基本的な電子メール・ヘッダの指定 を参照してください。
  4. メッセージが平文でない場合、以下のプロパティを設定して、作成しているメッセージの種類を示します。
  5. メッセージおよびそのヘッダの文字セットを指定するには、必要に応じて、Charset プロパティを設定します (このメッセージへの影響については、自動エンコードと文字変換 を参照してください)。
    Important:
    メッセージ・コンテンツを追加する前に文字セットを指定することが重要です。
  6. メッセージ・コンテンツを追加します。
    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 を検索して見つけてください。
マルチパートの電子メール・メッセージの作成
マルチパートの電子メール・メッセージを作成する手順は以下のとおりです。
  1. %Net.MailMessage のインスタンスを作成し、その To プロパティ、From プロパティ、および Subject プロパティを設定します。オプションで、その他のプロパティを設定し、その他のメッセージ・ヘッダを指定します。
  2. IsMultiPart プロパティを 1 に設定します。
  3. MultiPartType プロパティを "related""alternative""mixed" のいずれかに設定します。これは、メッセージ全体の Content-Type ヘッダに影響します。
  4. メッセージに含まれる各部分について、%Net.MailMessagePart のインスタンスを作成し、シングルパートの電子メール・メッセージの作成 の説明のとおり (手順 4 から開始)、そのプロパティを指定します。
  5. 親電子メール・メッセージの場合は、Parts プロパティを設定します。これは配列です。各子メッセージ部分をこの配列に挿入します。
メッセージを送信するときに、%Net.SMTP クラスは、必要に応じて (MultiPartType プロパティの値がある場合) 自動的にメッセージに対して Content-Type ヘッダを設定します。
電子メール・メッセージ・ヘッダの指定
前述のように、メッセージ自体とメッセージの各部分の両方に、ヘッダのセットがあります。
%Net.MailMessage および %Net.MailMessagePart クラスは、最も一般的に使用されるヘッダに簡単にアクセスできるプロパティを提供しますが、必要な任意のヘッダを追加することもできます。このセクションでは、すべてのヘッダについて説明し、さらにカスタム・ヘッダを作成する方法についても説明します。
指定したメッセージの部分のヘッダは、その部分の Charset プロパティによって指定された文字セットを使用します。
Note:
使用している SMTP サーバの要件を理解しておく必要があります。例えば、SMTP サーバの中には、Subject ヘッダを含める必要があるものがあります。同様に、SMTP サーバの中には、任意の From ヘッダを許可しないものもあります。
同様に、SMTP サーバの中には、Priority ヘッダを認識するものもあれば、代わりに X-Priority を認識するものもあります。
基本的な電子メール・ヘッダの指定
以下のプロパティを設定して (%Net.MailMessage 内のみ)、メッセージ自体の最も一般的に使用されるヘッダを設定します。
Content-Type ヘッダ
メッセージを送信するときに、メッセージおよび各メッセージ部分の Content-Type ヘッダが、以下のとおりに自動的に設定されます。
%Net.MailMessage%Net.MailMessagePart にはどちらも ContentType プロパティが用意されており、Content-Type ヘッダにアクセスできます。
Content-Transfer-Encoding ヘッダ
%Net.MailMessage%Net.MailMessagePart にはどちらも、ContentTransferEncoding プロパティが用意されており、メッセージまたはメッセージの部分の Content-Transfer-Encoding ヘッダを簡単な方法で指定できます。
このプロパティは、"base64""quoted-printable""7bit""8bit" のいずれかです。
既定値は、以下のとおりです。
また、自動エンコードと文字変換 も参照してください。
カスタム・ヘッダ
%Net.MailMessage%Net.MailMessagePart の両方で、以下の構造を持つ配列である Headers プロパティにアクセスして、カスタム・ヘッダを設定または取得できます。
配列キー 配列値
"Priority" などのヘッダ名 ヘッダの値
このプロパティを使用して、X-Priority など、追加のヘッダを含めます。以下はその例です。
 do msg.Headers.SetAt(1,"X-Priority")
 do msg.Headers.SetAt("High","X-MSMail-Priority")
 do msg.Headers.SetAt("High","Importance")
各種の電子メール・クライアントおよびサーバでは認識するヘッダも異なるので、複数の類似ヘッダを設定して、確実に認識できるヘッダの付いたメッセージを受信したほうが便利となります。
メッセージへの添付の追加
添付を電子メール・メッセージまたはメッセージの部分 (具体的には、%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 プロパティを設定します。メソッドは、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() の説明を参照してください。
AttachNewMessage()
method AttachNewMessage() as %Net.MailMessagePart
%Net.MailMessage の新規インスタンスを作成し、それをメッセージに追加して、新たに変更された親メッセージまたはメッセージの部分を返します。
AttachEmail()
method AttachEmail(mailmsg As %Net.MailMessage)
電子メール・メッセージ (%Net.MailMessage のインスタンス) がある場合、このメソッドは、それをメッセージに追加します。このメソッドは、メッセージまたはメッセージの部分の 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.MailMessagePart クラスのクラス・リファレンスを参照してください。
SMTP サーバを使用した電子メールの送信
SMTP サーバにアクセスできる場合、電子メール・メッセージを送信できます。SMTP サーバが稼動しており、それを使用するために必要な権限を持っている必要があります。電子メールを送信するには、以下の手順を実行します。
  1. %Net.SMTP のインスタンスを作成し、必要に応じてそのプロパティを設定します。特に、以下のプロパティを設定します。
    このオブジェクトは、使用する SMTP サーバを記述します。
  2. SMTP サーバが認証を必要とする場合、必要な資格情報を指定します。そのためには、以下の操作を実行します。
    1. %Net.Authenticator のインスタンスを作成します。
    2. このオブジェクトの UserName プロパティおよび Password プロパティを設定します。
    3. %Net.SMTP インスタンスの authenticator プロパティをこのオブジェクトと等しくなるように設定します。
    4. メッセージ自体に許可されたセンダがある場合、%Net.SMTP インスタンスの AuthFrom プロパティを設定します。
  3. SMTP サーバへの SSL/TLS 接続を使用するには
    1. SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。
      SSL/TLS 構成の作成と管理の詳細は、"Caché セキュリティ管理ガイド" の Caché での SSL/TLS の使用法 を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。
    2. UseSTARTTLS プロパティを 0 か 1 に設定します。
      ほとんどの場合、0 の値を使用します。通常の TCP ソケットでサーバのやり取りが開始した後、通常のソケットとして同じポートの TLS に切り替わる場合、1 の値を使用します。詳細は、"RFC3207" を参照してください。
  4. 送信する電子メール・メッセージを作成します (手順については、シングルパートの電子メール・メッセージの作成 および マルチパートの電子メール・メッセージの作成 を参照)。
  5. SMTP インスタンスの Send() メソッドを呼び出します。このメソッドはステータスを返すので、それを確認する必要があります。
  6. 返されたステータスがエラーを示している場合、エラー・メッセージを含んでいる Error プロパティを確認します。
  7. 送信アクションに失敗した電子メールのアドレスのリストを含んでいる FailedSend プロパティを確認します。
以下のセクションの例は、このドキュメント執筆時点で使用可能な 2 つの異なる無料 SMTP サービスを使用しています。これらのサービスの選択は、特に推奨を意味しているわけではありません。また、例で示しているのは、実際のパスワードではありません。
SAMPLES ネームスペースにその他の例があります。このネームスペースで、%Net.SMTP を検索して見つけてください。%Net.SMTP のクラス・ドキュメントも参照してください。
Important:
%Net.SMTP は、メッセージ本文を一時ファイル・ストリームに書き込みます。既定では、このファイルはネームスペースのディレクトリに書き込まれますが、ディレクトリで特別な書き込み許可が必要な場合、ファイルは作成されずに空のメッセージ本文を取得することになります。
これらの一時ファイルに新規のパスを定義して、書き込みアクセスを制限しないパスを選択することができます (/tmp など)。そのためには、グローバル・ノード %SYS("StreamLocation",namespace) を設定します。ここで、namespace はお使いのコードが実行されているネームスペースです。以下はその例です。
Set ^%SYS("StreamLocation","SAMPLES")="/tmp" 
%SYS("StreamLocation",namespace) が NULL の場合は、Caché では %SYS("TempDir",namespace) で指定されたディレクトリが使用されます。%SYS("TempDir",namespace) が設定されていない場合は、Caché では %SYS("TempDir") で指定されたディレクトリが使用されます。
例 1 : HotPOPAsSMTP() および SendSimpleMessage()
この例は、一緒に使用する 2 つのメソッドで構成されます。最初のメソッドは、HotPOP SMTP サーバで既に設定されているテスト・アカウントを使用する %Net.SMTP のインスタンスを作成します。
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.SMTP のインスタンスを作成します。これは、この目的で既に設定されているテスト・アカウントを使用します。
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.SMTP クラスには、使用している SMTP サーバによっては必要な場合がある以下のプロパティもあります。
POP3 サーバからの電子メールのフェッチ
このセクションでは、%Net.POP3 クラスを使用して、電子メール・メッセージをフェッチする方法について説明します。ここでは、以下のトピックについて説明します。
例や広範なコメントについては、%Net.FetchMailProtocol のクラス・ドキュメントも参照してください。%Net.FetchMailProtocol は、%Net.POP3 の抽象スーパークラスです。
POP3 サーバとの通信
必要な権限があり、メール・サーバが稼動している場合、POP3 プロトコルを使用して、メール・サーバから電子メール・メッセージをダウンロードし、処理することができます。一般に、POP3 サーバと通信するには、ログインし、メールボックスに影響を与える一連のアクションを実行し、変更をコミットまたはロールバックします。Caché 内でこれを行うには、以下を実行します。
  1. %Net.POP3 のインスタンスを作成します。このオブジェクトは、使用する POP3 サーバを記述します。
  2. オプションで、%Net.POP3 のインスタンスの以下のプロパティを指定します。
  3. POP3 サーバへの SSL/TLS 接続を使用するには
    1. SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。
      SSL/TLS 構成の作成と管理の詳細は、"Caché セキュリティ管理ガイド" の Caché での SSL/TLS の使用法 を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。
    2. UseSTARTTLS プロパティを 0 か 1 に設定します。
      ほとんどの場合、0 の値を使用します。通常の TCP ソケットでサーバのやり取りが開始した後、通常のソケットとして同じポートの TLS に切り替わる場合、1 の値を使用します。詳細は、"RFC2595" を参照してください。
  4. インスタンスの Connect() メソッドを呼び出します。このメソッドは、3 つの引数を以下の順番でとります。
    1. POP3 サーバの名前
    2. ユーザ名
    3. パスワード
  5. インスタンスのメソッドを使用して、メールボックスを調べ、メッセージを取得し、メッセージを削除します。以下のセクションで詳細を説明します。
  6. オプションで、接続がタイムアウトするのを防ぐため、%Net.POP3 インスタンスの Ping() メソッドを呼び出します。
  7. オプションで、削除するようメッセージにマーク付けしたものの、やはり削除しないことにした場合は、%Net.POP3 インスタンスの RollbackDeletes() メソッドを呼び出します。
  8. メールボックスへの変更が完了したら、以下のメソッドのいずれかを呼び出します。
これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。完全なメソッドのシグニチャについては、%Net.POP3 のクラス・リファレンスも参照してください。
以下のセクションの例は、このドキュメント執筆時点で使用可能な 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.POP3 サーバ・インスタンスを返します。この章で後述する例の多くは、%Net.POP3 インスタンスを引数として受け入れます。
例 2 : YPOPsAsPOP3()
以下のメソッドも、%Net.POP3 サーバ・インスタンスを返します。この場合、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.POP3 クラスの以下のメソッドのいずれかを使用します。
Fetch()
最初の引数としてメッセージ番号が指定されている場合、このメソッドは (2 番目の引数として、参照によって) そのメッセージを含む %Net.MailMessage のインスタンスを返します。
FetchMessage()
最初の引数としてメッセージ番号が指定されている場合、このメソッドは、FromTo およびその他の共通ヘッダなどの情報、すべてのヘッダ (共通ヘッダを含む) を含む配列、およびメッセージ・コンテンツ自体を (参照によって) 返します。
これらの各メソッドはステータスを返すので、続行する前にそれを確認する必要があります。メッセージが現在削除するようマーク付けされている場合、これらのメソッドは、エラー・ステータスを返します。
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.POP3 インスタンスでメッセージ内のすべての添付をファイルに保存できます。この機能を有効にするには、以下を行います。
  1. %Net.POP3 のインスタンスの以下のプロパティを指定します。
  2. ユーザの %Net.POP3 インスタンスの Fetch() または FetchMessage() を呼び出します。
各ファイル名は、以下のとおり決定されます。
  1. Content-Disposition ヘッダでファイル名が指定されている場合、そのファイル名が使用されます。
  2. それ以外の場合、Content-Type ヘッダでファイル名が指定されていれば、そのファイル名が使用されます。
  3. それ以外の場合、システムは、ATTxxxxxx.dat の形式の名前を作成します。
以下の点に注意してください。
例 : GetMsg()
以下のメソッド例は、%Net.POP3 のインスタンスおよびメッセージ番号を指定すると、メッセージ全体を取得します。
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.POP3 サーバの StoreAttachToFileStoreInlineToFile、および AttachDir の各プロパティを指定した場合、それらの添付は、このメソッドを呼び出したときに指定のディレクトリに保存されます。
添付された電子メール・メッセージの取得
メールボックスに接続している間は、受信トレイ内の電子メール・メッセージに添付されている電子メール・メッセージをダウンロードできます。そのためには、%Net.POP3 インスタンスの GetAttachedEmail() メソッドを使用して、添付された電子メールのコンテンツを取得します。
%Net.MailMessagePart のインスタンスを指定した場合、このメソッドは、そのメッセージ部分のコンテンツを持つシングルパートのメッセージを返します。具体的には、添付された電子メール・メッセージから取られたデータで初期化された %Net.MailMessage のインスタンスを (出力パラメータとして) 返します。
その他のメッセージ取得メソッド
このセクションでは、メッセージを調べ、取得する際に使用できる %Net.POP3 のメソッドをすべてリストします。
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 つの方法で行うことができます。
以下の点に留意してください。
例 : 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.POP3 の変更バージョンを (参照によって) 返します。変更バージョンには、どのメッセージが削除するようマーク付けされているかについての情報が含まれています。
前述のメソッドを以下のようなメソッドと共に使用します。
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.POP3 によって取得した電子メール・メッセージ (%Net.MailMessage) での作業方法について説明します。
メッセージの基本
電子メール・メッセージ (%Net.MailMessage) を取得後、一般には、そのメッセージの種類とその読み取り方法 (それがマルチパート・メッセージであるかどうか、およびその部分がバイナリであるかどうか) をまず判断します。この手順では、ContentType プロパティを使用できます。あるいは、間接的に ContentType プロパティと同じ情報を提供する IsBinary プロパティ、IsHTML プロパティ、および IsMultiPart プロパティを使用することもできます。
メッセージがマルチパート・メッセージの場合、各部分は、%Net.MailMessagePart のインスタンスです。
メッセージ・ヘッダ
メッセージ自体およびメッセージの各部分にはどちらも、1 組みのヘッダがあります。
%Net.MailMessage クラスおよび %Net.MailMessagePart クラスは、最も一般的に使用されるヘッダに簡単にアクセスできるプロパティを提供します。例えば、%Net.MailMessage は、ToFromSubjectDate などのプロパティを提供します。Headers 配列プロパティによって、カスタム・ヘッダにアクセスできます。電子メール・メッセージ・ヘッダの指定 を参照してください。
また、%Net.POP3 によってメッセージを取得した場合、GetAttribute() メソッドを使用することができます。ヘッダ名と属性を指定すると、このメソッドは、その属性の値を返します。
メッセージ・コンテンツ
一般的なメッセージの構造について理解したら、以下のテクニックを使用して、コンテンツを取得します。
メッセージを送信する電子メール・クライアントがメッセージ内のラップを決定します。メール・サーバも Caché も、これを制御できません。
その他のメッセージ情報
MessageSize プロパティは、添付された電子メール・メッセージ以外に、メッセージ長の合計を示します。
以下のメソッドは、メッセージについての追加情報を提供します。
GetLocalDateTime()
メッセージが取得された日付と時刻を、$HOROLOG 形式のローカル時間に変換して返します。
GetUTCDateTime()
メッセージが取得された日付と時刻を、$HOROLOG 形式の UTC に変換して返します。
GetUTCSeconds()
メッセージが取得された日付と時刻を 12/31/1840 からの秒数で返します。
日付/時刻変換では、次のクラス・メソッドも使用できます。
HToSeconds()
$HOROLOG 形式の日付および時刻を 12/31/1840 からの秒数に変換するクラス・メソッド。
SecondsToH()
12/31/1840 からの秒数を $HOROLOG 形式の日付および時刻に変換するクラス・メソッド。
例 1 : ShowMsgInfo()
%Net.MailMessage のインスタンスを指定すると、以下のメソッドは、メッセージについての情報を現在のデバイスに書き込みます。
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 (存在する場合) の両方についての情報が含まれています。参照のため、このセクションでは、この情報の使用方法について説明します。
Caché の文字変換に関する背景情報は、"Caché プログラミング入門ガイド" の ローカライズのサポート を参照してください。
送信メール
%Net.SMTP は、各部分の Charset プロパティを確認し、適切な変換テーブルを適用します。
指定した部分に対して Charset プロパティを指定しない場合、メッセージを送信するときに、以下の既定値がその部分に対して使用されます。
%Net.SMTPContentTransferEncoding プロパティを確認します。このプロパティが "base64" または "quoted-printable" の場合、メッセージを作成するときに、%Net.SMTP が、必要に応じて本文をエンコードします。(コンテンツ転送エンコードが "7bit" または "7bit" の場合、エンコードは必要ありません。)
受信メール
%Net.POP3 は、各メッセージ部分の Content-Transfer-Encoding ヘッダを確認し、必要に応じて本文をデコードします。
その後、%Net.POP3 は、各メッセージ部分の Content-Type ヘッダを確認します。これは、メッセージ部分の Charset プロパティに影響を与え、また、メッセージ部分が Caché 内で作成されるときに使用される変換テーブルの制御も行います。