2012-09-26T21:50:28の更新内容

works/libs/Smdn.Net.Pop3.Client/docs/index.wiki.txt

current previous
2,7 2,7
 
${smdncms:keywords,}
${smdncms:keywords,}
 
${smdncms:document_versions,codelang=cs,codelang=vb}
${smdncms:document_versions,codelang=cs,codelang=vb}
 
${pragma,parser-options,non-limited-list}
${pragma,parser-options,non-limited-list}
~
[[works/libs/Smdn.Net.Pop3.Client]]のドキュメントとサンプルです。 ここに記載されているものはversion 1.11時点のもので、記載不備などがあるかもしれません。
[[works/libs/Smdn.Net.Pop3.Client]]のドキュメントとサンプルです。 ここに記載されているものはversion 1.10時点のもので、記載不備などがあるかもしれません。
 

        

        
 
サンプルコードは[[このページの最後>#samples]]にあります。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
サンプルコードは[[このページの最後>#samples]]にあります。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
 

        

        
98,8 98,98
 
**接続と認証 [#login]
**接続と認証 [#login]
 
ここでは接続時と認証時の動作について解説します。
ここでは接続時と認証時の動作について解説します。
 

        

        
-
***接続・切断・サーバ情報に関するメンバ
-
以下は接続・切断・サーバ情報に関するメソッドとプロパティです。
-

          
-
|*PopClientクラスのメソッド
-
|~メソッド|~解説|~対応するPOPコマンド|h
-
|Connect(string)&br;Connect(ICredentialsByHost)|PopClient.Profileプロパティで指定された内容、および引数で指定されたパスワード(もしくはICredentialsByHost)を使って接続・認証を試みます。&br;接続・認証できた場合は、サーバの能力も取得します。|USER/PASS, STLS, APOP, AUTH, CAPA|
-
|BeginConnect(string)&br;BeginConnect(string, AsyncCallback, object)&br;BeginConnect(ICredentialsByHost)&br;BeginConnect(ICredentialsByHost, AsyncCallback, object)|Connect()メソッドと同じ処理を非同期的に実行します。 オプションでコールバックメソッドを指定できます。|USER/PASS, STLS, APOP, AUTH, CAPA|
-
|EndConnect(IAsyncResult)|BeginConnecto()で開始した非同期接続を完了します。 BeginConnect()を呼び出した場合、EndConnect()で操作を完了する必要があります。|-|
-
|Logout()|ログアウトします。 削除マークが付けられているメッセージは削除されます。|QUIT|
-
|Disconnect()&br;IDisposable.Dispose()|ログアウトせずに切断します。 削除マークが付けられているメッセージがあっても削除されません。|-|
-
|KeepAlive()|自動ログアウトタイマの更新、セッションの接続性確認などに使います。|NOOP|
-

          
-
|*PopClientクラスのプロパティ
-
|~プロパティ|~解説|h
-
|Profile|接続先のホスト・ポート・ユーザ名などを取得/設定します。 コンストラクタで指定した内容はこのプロパティに反映されます。|
-
|Timeout|コマンド処理のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|SendTimeout|ソケット送信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|ReceiveTimeout|ソケット受信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|IsConnected|接続中かどうかを表す値を取得します。|
-
|ServerCapabilities|サーバがサポートする機能の一覧(CAPAコマンドの結果)を取得します。 サーバがCAPAコマンドをサポートしていない場合は、空のインスタンスを返します。|
-

          
-
:IDisposable.Dispose()|PopClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
-
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度PopClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
-
:Timeout, SendTimeout, ReceiveTimeout|これらのプロパティはそれぞれPopClient.Profile.Timeout, PopClient.Profile.SendTimeout, PopClient.Profile.RecieveTimeoutを設定することと同じですが、接続後はPopClient.Profileの値を変更してもPopClientの動作には反映されません。 接続後はPopClient.Timeout, PopClient.SendTimeout, PopClient.ReceiveTimeoutプロパティを設定してください。
-
:ServerCapabilities|切断されている状態で取得しようとした場合(PopClient.IsConnectedがfalseの場合)、例外をスローします。
-

          
-
***接続に関するパラメータと動作 [#connect]
-
接続時の動作は、接続時のパラメータにより次のように変わります。
-

          
-
:SSL/TLSを使用する (POP over SSL)|常にSSL/TLSを使用して接続を試みます。 デフォルトのポート番号は995です。
-
接続先URL&sub{*1};のスキームに''"pops"''を指定した場合、SecurePortプロパティ&sub{*2};に''true''を指定した場合はこの動作になります。
-
:可能ならSSL/TLSを使用する (STLS)|SSL/TLSを使用せず接続を試み、サーバが&urn2url(urn:ietf:rfc:2595){STLS};をサポートしていれば認証を開始する前にSSL/TLSへのアップグレードを試みます。 デフォルトのポート番号は110です。
-
接続先URL&sub{*1};のスキームに''"pop"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''true''を指定した場合はこの動作になります。
-
:SSL/TLSを使用しない|常にSSL/TLSを使用せずに接続を試みます。 サーバがSTLSをサポートしていてもSSL/TLSへのアップグレードはしません。 デフォルトのポート番号は110です。
-
接続先URL&sub{*1};のスキームに''"pop"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''false''を指定した場合はこの動作になります。
-

          
-
これら接続時のパラメータは次の箇所で指定します。
-
:接続先URL&sup{*1};|PopClientクラスのコンストラクタで指定する引数authority
-
:SecurePortプロパティ&sup{*2};|PopClientクラスのコンストラクタで指定する引数securePort、もしくはPopClient.Profile.SecurePortプロパティ
-
:UseTlsIfAvailableプロパティ&sup{*3};|PopClient.Profile.UseTlsIfAvailableプロパティ
-

          
-
接続先URLもしくはパラメータでポート番号を明示的に指定しない限り、デフォルトポートへの接続を試みます。 なお、ポート番号の指定ではSSL/TLSを使用するかどうかの動作は変わりません((ポート番号に995を指定してもURLのスキームが"pop"なら、接続時にSSL/TLSは使用しません))。
-

          
-
例として接続先のURLと接続時の動作を表にまとめると以下のようになります。
-

          
-
|*URLと接続動作の例
-
|~接続先URL|~接続ポート|~SSL/TLS|h
-
|pops://user@pop.example.net/|995|SSL/TLSを使用|
-
|pops://user@pop.example.net:10110/|10110|SSL/TLSを使用|
-
|pop://user@pop.example.net/|110|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
-
|pop://user@pop.example.net:995/|995|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
-

          
-
***認証に関するパラメータと動作 [#auth]
-
接続にPOP URLを用いる場合、認証に用いるユーザ名と認証方式はURLから取得します。 パスワードはImapClient.Connect()メソッドに指定する引数credentials(ICredentialsByHostインターフェイス)を参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 POP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、URLからはパスワードを取得しません(指定されていてもパスワードとしては解釈しません)。
-

          
-
認証方式にAPOPを使用する場合は、"APOP"ではなく"+APOP"を指定してください。 認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
-
+AUTHコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
-
+APOPコマンド (サーバがサポートしている場合のみ)
-
+USER/PASSコマンド
-

          
-
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。 認証方式にANONYMOUSを指定して認証を行う場合、ユーザ名の部分をログイントークンとして送信します。 ユーザ名が指定されていない場合は"anonymous@"をログイントークンとして送信します。 ログイントークンに@などの記号を含める場合はURLエスケープする必要があります。
-

          
-
認証方式の大文字小文字の違いは無視します(POP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
-

          
-
例として接続先のURLと認証時の動作を表にまとめると以下のようになります。
-

          
-
|*URLと認証動作の例
-
|~接続先URL|~認証に使用するユーザ名|~使用する認証メカニズム|h
-
|pop://user;AUTH=+APOP@pop.example.net/|user|APOP|
-
|pop://user;AUTH=DIGEST-MD5@pop.example.net/|user|DIGEST-MD5|
-
|pop://;AUTH=DIGEST-MD5@pop.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
-
|pop://user;AUTH=*@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
-
|pop://user@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
-
|pop://;AUTH=ANONYMOUS@pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
-
|pop://user@localhost;AUTH=ANONYMOUS@pop.example.net/|匿名ユーザ&br;(ログイントークン: user@localhost)|ANONYMOUS|
-
|pop://pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはUSER/PASSコマンドを使用|
-

          
-
試行する認証メカニズムを制御するには、PopClient.Profile.UsingSaslMechanismsプロパティの値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 PopClient.Profile.AllowInsecureLoginプロパティにfalseを指定した場合で、かつ現在の接続がSSL/TLSで保護されていない場合、平文およびAPOPによる認証は試行されません(デフォルトはfalseです)。
-

          
-
|*サーバが対応している認証方式と認証試行順の例
-
|~サーバが対応している認証方式|~UsingSaslMechanismsの値|~試行順序&br;(接続がSSL/TLSで保護されている、もしくはAllowInsecureLoginがtrueの場合)|~試行順序&br;(接続がSSL/TLSで保護されていない、かつAllowInsecureLoginがfalseの場合)|h
-
|DIGEST-MD5&br;CRAM-MD5&br;APOP&br;USER/PASS|{"DIGEST-MD5", "CRAM-MD5"}|1.DIGEST-MD5&br;2.CRAM-MD5&br;3.APOP&br;4.USER/PASS|1.DIGEST-MD5&br;2.CRAM-MD5|
-
|DIGEST-MD5&br;CRAM-MD5&br;PLAIN&br;|{"PLAIN", "DIGEST-MD5"}|1.PLAIN&br;2.DIGEST-MD5|1.DIGEST-MD5|
-
|PLAIN&br;APOP&br;USER/PASS|null|1.APOP&br;2.USER/PASS|PopAuthenticationExceptionをスロー&br;(試行できる認証方式なし)|
-

          
-
APOPを使用した認証については脆弱性が指摘されているため、本ライブラリではAPOPは平文による認証と同程度のものとして扱います。 参考:[[情報処理推進機構:情報セキュリティ:脆弱性関連情報取扱い:APOP方式におけるセキュリティ上の弱点(脆弱性)の注意喚起について:http://www.ipa.go.jp/security/vuln/200704_APOP.html]]
-

          
-
***認証時に参照する資格情報 [#creds]
-
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
-

          
 
***接続・認証のコードと動作の例
***接続・認証のコードと動作の例
~
以下は接続・認証処理の記述例です。 個々のパラメータの指定方法と動作の詳細についてはこの後順に解説していきます。 なお、実際にSSL/TLSを使用する場合は[[証明書の検証等>#ssl]]が必要になります。
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#ssl]]が必要になります。
 

        

        
 
#tabpage(C#)
#tabpage(C#)
 
#code(cs,PopClient){{
#code(cs,PopClient){{
219,97 309,6
 
}}
}}
 
#tabpage-end
#tabpage-end
 

        

        
+
***接続・切断・サーバ情報に関するメンバ
+
以下は接続・切断・サーバ情報に関するメソッドとプロパティです。
+

          
+
|*PopClientクラスのメソッド
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|Connect(string)&br;Connect(ICredentialsByHost)|PopClient.Profileプロパティで指定された内容、および引数で指定されたパスワード(もしくはICredentialsByHost)を使って接続・認証を試みます。&br;接続・認証できた場合は、サーバの能力も取得します。|USER/PASS, STLS, APOP, AUTH, CAPA|
+
|BeginConnect(string)&br;BeginConnect(string, AsyncCallback, object)&br;BeginConnect(ICredentialsByHost)&br;BeginConnect(ICredentialsByHost, AsyncCallback, object)|Connect()メソッドと同じ処理を非同期的に実行します。 オプションでコールバックメソッドを指定できます。|USER/PASS, STLS, APOP, AUTH, CAPA|
+
|EndConnect(IAsyncResult)|BeginConnecto()で開始した非同期接続を完了します。 BeginConnect()を呼び出した場合、EndConnect()で操作を完了する必要があります。|-|
+
|ConnectAsync(string)&br;ConnectAsync(ICredentialsByHost)|[.NET 4.0]&br;Connect()メソッドと同じ処理を非同期的に実行し、非同期操作を表すTaskを返します。|USER/PASS, STLS, APOP, AUTH, CAPA|
+
|Logout()|ログアウトします。 削除マークが付けられているメッセージは削除されます。|QUIT|
+
|Disconnect()&br;IDisposable.Dispose()|ログアウトせずに切断します。 削除マークが付けられているメッセージがあっても削除されません。|-|
+
|KeepAlive()|自動ログアウトタイマの更新、セッションの接続性確認などに使います。|NOOP|
+

          
+
|*PopClientクラスのプロパティ
+
|~プロパティ|~解説|h
+
|Profile|接続先のホスト・ポート・ユーザ名などを取得/設定します。 コンストラクタで指定した内容はこのプロパティに反映されます。|
+
|Timeout|コマンド処理のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|SendTimeout|ソケット送信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|ReceiveTimeout|ソケット受信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|IsConnected|接続中かどうかを表す値を取得します。|
+
|ServerCapabilities|サーバがサポートする機能の一覧(CAPAコマンドの結果)を取得します。 サーバがCAPAコマンドをサポートしていない場合は、空のインスタンスを返します。|
+

          
+
:IDisposable.Dispose()|PopClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
+
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度PopClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
+
:Timeout, SendTimeout, ReceiveTimeout|これらのプロパティはそれぞれPopClient.Profile.Timeout, PopClient.Profile.SendTimeout, PopClient.Profile.RecieveTimeoutを設定することと同じですが、接続後はPopClient.Profileの値を変更してもPopClientの動作には反映されません。 接続後はPopClient.Timeout, PopClient.SendTimeout, PopClient.ReceiveTimeoutプロパティを設定してください。
+
:ServerCapabilities|切断されている状態で取得しようとした場合(PopClient.IsConnectedがfalseの場合)、例外をスローします。
+

          
+
***接続に関するパラメータと動作 [#connect]
+
接続時の動作は、接続時のパラメータにより次のように変わります。
+

          
+
:SSL/TLSを使用する (POP over SSL)|常にSSL/TLSを使用して接続を試みます。 デフォルトのポート番号は995です。
+
接続先URL&sub{*1};のスキームに''"pops"''を指定した場合、SecurePortプロパティ&sub{*2};に''true''を指定した場合はこの動作になります。
+
:可能ならSSL/TLSを使用する (STLS)|SSL/TLSを使用せず接続を試み、サーバが&urn2url(urn:ietf:rfc:2595){STLS};をサポートしていれば認証を開始する前にSSL/TLSへのアップグレードを試みます。 デフォルトのポート番号は110です。
+
接続先URL&sub{*1};のスキームに''"pop"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''true''を指定した場合はこの動作になります。
+
:SSL/TLSを使用しない|常にSSL/TLSを使用せずに接続を試みます。 サーバがSTLSをサポートしていてもSSL/TLSへのアップグレードはしません。 デフォルトのポート番号は110です。
+
接続先URL&sub{*1};のスキームに''"pop"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''false''を指定した場合はこの動作になります。
+

          
+
これら接続時のパラメータは次の箇所で指定します。
+
:接続先URL&sup{*1};|PopClientクラスのコンストラクタで指定する引数authority
+
:SecurePortプロパティ&sup{*2};|PopClientクラスのコンストラクタで指定する引数securePort、もしくはPopClient.Profile.SecurePortプロパティ
+
:UseTlsIfAvailableプロパティ&sup{*3};|PopClient.Profile.UseTlsIfAvailableプロパティ
+

          
+
接続先URLもしくはパラメータでポート番号を明示的に指定しない限り、デフォルトポートへの接続を試みます。 なお、ポート番号の指定ではSSL/TLSを使用するかどうかの動作は変わりません((ポート番号に995を指定してもURLのスキームが"pop"なら、接続時にSSL/TLSは使用しません))。
+

          
+
例として接続先のURLと接続時の動作を表にまとめると以下のようになります。
+

          
+
|*URLと接続動作の例
+
|~接続先URL|~接続ポート|~SSL/TLS|h
+
|pops://user@pop.example.net/|995|SSL/TLSを使用|
+
|pops://user@pop.example.net:10110/|10110|SSL/TLSを使用|
+
|pop://user@pop.example.net/|110|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
+
|pop://user@pop.example.net:995/|995|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
+

          
+
***認証に関するパラメータと動作 [#auth]
+
接続にPOP URLを用いる場合、認証に用いるユーザ名と認証方式はURLから取得します。 パスワードはImapClient.Connect()メソッドに指定する引数credentials(ICredentialsByHostインターフェイス)を参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 POP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、URLからはパスワードを取得しません(指定されていてもパスワードとしては解釈しません)。
+

          
+
認証方式にAPOPを使用する場合は、"APOP"ではなく"+APOP"を指定してください。 認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
+
+AUTHコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
+
+APOPコマンド (サーバがサポートしている場合のみ)
+
+USER/PASSコマンド
+

          
+
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。 認証方式にANONYMOUSを指定して認証を行う場合、ユーザ名の部分をログイントークンとして送信します。 ユーザ名が指定されていない場合は"anonymous@"をログイントークンとして送信します。 ログイントークンに@などの記号を含める場合はURLエスケープする必要があります。
+

          
+
認証方式の大文字小文字の違いは無視します(POP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
+

          
+
例として接続先のURLと認証時の動作を表にまとめると以下のようになります。
+

          
+
|*URLと認証動作の例
+
|~接続先URL|~認証に使用するユーザ名|~使用する認証メカニズム|h
+
|pop://user;AUTH=+APOP@pop.example.net/|user|APOP|
+
|pop://user;AUTH=DIGEST-MD5@pop.example.net/|user|DIGEST-MD5|
+
|pop://;AUTH=DIGEST-MD5@pop.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
+
|pop://user;AUTH=*@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|pop://user@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|pop://;AUTH=ANONYMOUS@pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
+
|pop://user@localhost;AUTH=ANONYMOUS@pop.example.net/|匿名ユーザ&br;(ログイントークン: user@localhost)|ANONYMOUS|
+
|pop://pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはUSER/PASSコマンドを使用|
+

          
+
試行する認証メカニズムを制御するには、PopClient.Profile.UsingSaslMechanismsプロパティの値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 PopClient.Profile.AllowInsecureLoginプロパティにfalseを指定した場合で、かつ現在の接続がSSL/TLSで保護されていない場合、平文およびAPOPによる認証は試行されません(デフォルトはfalseです)。
+

          
+
|*サーバが対応している認証方式と認証試行順の例
+
|~サーバが対応している認証方式|~UsingSaslMechanismsの値|~試行順序&br;(接続がSSL/TLSで保護されている、もしくはAllowInsecureLoginがtrueの場合)|~試行順序&br;(接続がSSL/TLSで保護されていない、かつAllowInsecureLoginがfalseの場合)|h
+
|DIGEST-MD5&br;CRAM-MD5&br;APOP&br;USER/PASS|{"DIGEST-MD5", "CRAM-MD5"}|1.DIGEST-MD5&br;2.CRAM-MD5&br;3.APOP&br;4.USER/PASS|1.DIGEST-MD5&br;2.CRAM-MD5|
+
|DIGEST-MD5&br;CRAM-MD5&br;PLAIN&br;|{"PLAIN", "DIGEST-MD5"}|1.PLAIN&br;2.DIGEST-MD5|1.DIGEST-MD5|
+
|PLAIN&br;APOP&br;USER/PASS|null|1.APOP&br;2.USER/PASS|PopAuthenticationExceptionをスロー&br;(試行できる認証方式なし)|
+

          
+
APOPを使用した認証については脆弱性が指摘されているため、本ライブラリではAPOPは平文による認証と同程度のものとして扱います。 参考:[[情報処理推進機構:情報セキュリティ:脆弱性関連情報取扱い:APOP方式におけるセキュリティ上の弱点(脆弱性)の注意喚起について:http://www.ipa.go.jp/security/vuln/200704_APOP.html]]
+

          
+
***認証時に参照する資格情報 [#creds]
+
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
+

          
 
**SSL/TLSを使用した接続 [#ssl]
**SSL/TLSを使用した接続 [#ssl]
 
***証明書の選択と検証 [#certs]
***証明書の選択と検証 [#certs]
 
SSL/TLS接続時に使用する証明書は&msdn(netfx,type,System.Security.Cryptography.X509Certificates.X509Certificate2Collection){X509Certificate2Collection};で設定できます。 また、証明書の選択と検証には&msdn(netfx,type,System.Net.Security.RemoteCertificateValidationCallback){RemoteCertificateValidationCallbackデリゲート};と&msdn(netfx,type,System.Net.Security.LocalCertificateSelectionCallback){LocalCertificateSelectionCallbackデリゲート};を指定できます。 デフォルトの状態では、SSL/TLS接続時にこれらのコールバックメソッドを呼び出して証明書の検証と選択を行い、&msdn(netfx,type,System.Net.Security.SslStream){SslStream};を作成します。
SSL/TLS接続時に使用する証明書は&msdn(netfx,type,System.Security.Cryptography.X509Certificates.X509Certificate2Collection){X509Certificate2Collection};で設定できます。 また、証明書の選択と検証には&msdn(netfx,type,System.Net.Security.RemoteCertificateValidationCallback){RemoteCertificateValidationCallbackデリゲート};と&msdn(netfx,type,System.Net.Security.LocalCertificateSelectionCallback){LocalCertificateSelectionCallbackデリゲート};を指定できます。 デフォルトの状態では、SSL/TLS接続時にこれらのコールバックメソッドを呼び出して証明書の検証と選択を行い、&msdn(netfx,type,System.Net.Security.SslStream){SslStream};を作成します。
575,41 574,32
 
DownloadMessageAsText(long, Encoding)
DownloadMessageAsText(long, Encoding)
 
DownloadFirstMessageAsText(Encoding)
DownloadFirstMessageAsText(Encoding)
 
DownloadLastMessageAsText(Encoding)
DownloadLastMessageAsText(Encoding)
~
DownloadAllMessagesAsText(Encoding)
}}|指定された番号の/最初の/最後のメッセージの本文をstringで取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAllText(Encoding)の呼び出しの組み合わせと同等です。|RETR|
+
}}|(指定された番号の/最初の/最後の/すべての)メッセージの本文をstringで取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAllText(Encoding)の呼び出しの組み合わせと同等です。|RETR|
 
|{{
|{{
 
DownloadMessageAsByteArray(long)
DownloadMessageAsByteArray(long)
 
DownloadFirstMessageAsByteArray()
DownloadFirstMessageAsByteArray()
 
DownloadLastMessageAsByteArray()
DownloadLastMessageAsByteArray()
~
}}|(指定された番号の/最初の/最後の)メッセージの本文をbyte[]で取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAllBytes()の呼び出しの組み合わせと同等です。|RETR|
}}|指定された番号の/最初の/最後のメッセージの本文をbyte[]で取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAllBytes()の呼び出しの組み合わせと同等です。|RETR|
 
|{{
|{{
 
DownloadMessageAsStream(long)
DownloadMessageAsStream(long)
 
DownloadFirstMessageAsStream()
DownloadFirstMessageAsStream()
 
DownloadLastMessageAsStream()
DownloadLastMessageAsStream()
~
}}|(指定された番号の/最初の/最後の)メッセージの本文を読み込むためのStreamを取得します。&br;PopClient.GetMessage()等とPopMessageInfo.OpenRead()の呼び出しの組み合わせと同等です。|RETR|
}}|指定された番号の/最初の/最後のメッセージの本文を読み込むためのStreamを取得します。&br;PopClient.GetMessage()等とPopMessageInfo.OpenRead()の呼び出しの組み合わせと同等です。|RETR|
 
|{{
|{{
 
DownloadMessageAs<TOutput>(long, Converter<Stream, TOutput>)
DownloadMessageAs<TOutput>(long, Converter<Stream, TOutput>)
 
DownloadFirstMessageAs<TOutput>(Converter<Stream, TOutput>)
DownloadFirstMessageAs<TOutput>(Converter<Stream, TOutput>)
 
DownloadLastMessageAs<TOutput>(Converter<Stream, TOutput>)
DownloadLastMessageAs<TOutput>(Converter<Stream, TOutput>)
~
DownloadAllMessageAs<TOutput>(Converter<Stream, TOutput>)
}}|指定された番号の/最初の/最後のメッセージの本文を読み込むためのStreamを取得し、指定されたConverter<Stream, TOutput>で変換された結果を取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAs<TOutput>(Converter<Stream, TOutput>)の呼び出しの組み合わせと同等です。|RETR|
+
}}|(指定された番号の/最初の/最後の/すべての)メッセージの本文を読み込むためのStreamを取得し、指定されたConverter<Stream, TOutput>で変換された結果を取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAs<TOutput>(Converter<Stream, TOutput>)の呼び出しの組み合わせと同等です。|RETR|
 
|{{
|{{
 
DownloadMessageAs<T, TResult>(long, Func<Stream, T, TResult>, T)
DownloadMessageAs<T, TResult>(long, Func<Stream, T, TResult>, T)
 
DownloadFirstMessageAs<T, TResult>(Func<Stream, T, TResult>, T)
DownloadFirstMessageAs<T, TResult>(Func<Stream, T, TResult>, T)
 
DownloadLastMessageAs<T, TResult>(Func<Stream, T, TResult>, T)
DownloadLastMessageAs<T, TResult>(Func<Stream, T, TResult>, T)
~
DownloadAllMessageAs<T, TResult>(Func<Stream, T, TResult>, T)
}}|指定された番号の/最初の/最後のメッセージの本文を読み込むためのStreamを取得し、指定されたFunc<Stream, T, TResult>で変換された結果を取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAs<T, TResult>(Func<Stream, T, TResult>, T)の呼び出しの組み合わせと同等です。|RETR|
+
}}|(指定された番号の/最初の/最後の/すべての)メッセージの本文を読み込むためのStreamを取得し、指定されたFunc<Stream, T, TResult>で変換された結果を取得します。&br;PopClient.GetMessage()等とPopMessageInfo.ReadAs<T, TResult>(Func<Stream, T, TResult>, T)の呼び出しの組み合わせと同等です。|RETR|
 
|{{
|{{
 
DownloadMessageToFile(long, string)
DownloadMessageToFile(long, string)
 
DownloadFirstMessageToFile(string)
DownloadFirstMessageToFile(string)
 
DownloadLastMessageToFile(string)
DownloadLastMessageToFile(string)
~
}}|(指定された番号の/最初の/最後の)メッセージの本文を指定されたファイルに保存します。&br;PopClient.GetMessage()等とPopMessageInfo.Save(string)の呼び出しの組み合わせと同等です。|RETR|
}}|指定された番号の/最初の/最後のメッセージの本文を指定されたファイルに保存します。&br;PopClient.GetMessage()等とPopMessageInfo.Save(string)の呼び出しの組み合わせと同等です。|RETR|
+
|{{
+
DownloadAllMessagesToDirectory(string)
+
}}|すべてのメッセージの本文を指定されたディレクトリに保存します。 個々のメッセージは "&var{(メッセージ番号)};.eml" のファイル名で保存されます。&br;PopClient.GetMessage()等とPopMessageInfo.Save(string)の呼び出しの組み合わせと同等です。|RETR|
+
|{{
+
DownloadAllMessagesToFiles(Func<PopMessageInfo, string>)
+
}}|すべてのメッセージの本文を指定されたデリゲートが返すファイル名で保存します。&br;PopClient.GetMessage()等とPopMessageInfo.Save(string)の呼び出しの組み合わせと同等です。|RETR|
 

        

        
 
|*PopClientクラスのプロパティ
|*PopClientクラスのプロパティ
 
|~プロパティ|~解説|h
|~プロパティ|~解説|h
622,8 612,7
 
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティを呼び出そうとした場合、PopProtocolViolationExceptionをスローします。
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティを呼び出そうとした場合、PopProtocolViolationExceptionをスローします。
 
-OpenText(), ReadAllLines()などのメソッドは、既定ではstringへのデコードにISO-8859-1を使用します。
-OpenText(), ReadAllLines()などのメソッドは、既定ではstringへのデコードにISO-8859-1を使用します。
 
Encodingを引数に取るバージョンのオーバーロードを使用することで、指定したエンコーディングでデコードすることもできます。
Encodingを引数に取るバージョンのオーバーロードを使用することで、指定したエンコーディングでデコードすることもできます。
~
これらのメソッドは''Content-Typeヘッダのcharsetパラメータや、Content-Transfer-Encodingヘッダなどに指定されている値は考慮せずに''デコードを行います。 MIMEメッセージとしてパース・デコードするには、OpenRead()やReadAllBytes()などのメソッドで本文を取得した後、[[works/libs/Smdn.Formats.Mime]]に渡してデコードするなど、別途適切な処理を施してください。
これらのメソッドは''Content-Typeヘッダのcharsetパラメータや、Content-Transfer-Encodingヘッダなどに指定されている値は考慮せずに''デコードを行います。 MIMEメッセージとしてパース・デコードするには、OpenRead()やReadAllBytes()などのメソッドで本文を取得した後、適切な処理を施してください。
+
-DownloadAllMessagesToDirectory()メソッドおよびDownloadAllMessagesToFiles()メソッドは保存先のディレクトリを作成しません。 ディレクトリが存在しない場合例外をスローするので、あらかじめディレクトリを作成するか、既存のディレクトリを指定してください。
 

        

        
 
**メールボックスに対する操作
**メールボックスに対する操作
 
以下はメールボックス操作に関するメソッドです。
以下はメールボックス操作に関するメソッドです。
677,77 666,6
 
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティの値を参照しようとした場合、PopProtocolViolationExceptionをスローします。
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティの値を参照しようとした場合、PopProtocolViolationExceptionをスローします。
 

        

        
 

        

        
+
**POP操作を行う静的メソッド
+
PopClientクラスではいくつかの静的メソッドを用意しています。 これらのメソッドはサーバへの接続・メッセージ本文の取得などの操作・切断および後処理を一度のメソッド呼び出しで行えるようにしたものです。 これらのメソッドでは呼び出しの度にサーバへの接続・切断が行われる点に注意してください。
+

          
+
これらのメソッドは、いずれも共通して以下の引数を取ります。
+

          
+
:第一引数 popUrl (Uri)|接続先サーバを[[POP URL形式>#login]]で指定します。 ユーザ名・認証方式を指定する場合は、このURLに含めてください。
+
:第二引数 password (string)|接続時のパスワードを指定します。
+
:第三引数 deleteAfterDownload (bool)|(メッセージ本文の取得を行うメソッドのみ) メッセージ本文が正常に取得できた場合、メッセージを削除するかどうかを指定します。
+

          
+
以下はPopClientクラスに用意されている静的メソッドの一覧です。 具体的な動作については、対応する各インスタンスメンバの解説を参照してください。
+

          
+
|*PopClientクラスの静的メソッド
+
|~メソッド|~解説|~対応するインスタンスメンバ|h
+
|GetMessageCount|メールボックスに存在するメッセージの数を取得します。|PopClient.MessageCount|
+
|{{
+
DownloadFirstMessageAsText
+
DownloadLastMessageAsText
+
DownloadAllMessagesAsText
+
}}|(最初の/最後の/すべての)メッセージの本文をstringで取得します。|{{
+
PopClient.DownloadFirstMessageAsText()
+
PopClient.DownloadLastMessageAsText()
+
PopClient.DownloadAllMessageAsText()
+
}}|
+
|{{
+
DownloadFirstMessageAsByteArray
+
DownloadLastMessageAsByteArray
+
}}|(最初の/最後の)メッセージの本文をbyte[]で取得します。|{{
+
PopClient.DownloadFirstMessageAsByteArray()
+
PopClient.DownloadLastMessageAsByteArray()
+
}}|
+
|{{
+
DownloadFirstMessageAsStream
+
DownloadLastMessageAsStream
+
}}|(最初の/最後の)メッセージの本文を読み込むためのStreamを取得します。|{{
+
PopClient.DownloadFirstMessageAsStream()
+
PopClient.DownloadLastMessageAsStream()
+
}}|
+
|{{
+
DownloadFirstMessageAs<TOutput>
+
DownloadLastMessageAs<TOutput>
+
DownloadAllMessagesAs<TOutput>
+
}}|(最初の/最後の/すべての)メッセージの本文を読み込むためのStreamを取得し、指定されたConverter<Stream, TOutput>で変換された結果を取得します。|{{
+
PopClient.DownloadFirstMessageAs<TOutput>()
+
PopClient.DownloadLastMessageAs<TOutput>()
+
PopClient.DownloadAllMessagesAs<TOutput>()
+
}}|
+
|{{
+
DownloadFirstMessageAs<T, TResult>
+
DownloadLastMessageAs<T, TResult>
+
DownloadAllMessagesAs<T, TResult>
+
}}|(最初の/最後の/すべての)メッセージの本文を読み込むためのStreamを取得し、指定されたFunc<Stream, T, TResult>で変換された結果を取得します。|{{
+
PopClient.DownloadFirstMessageAs<T, TResult>()
+
PopClient.DownloadLastMessageAs<T, TResult>()
+
PopClient.DownloadAllMessagesAs<T, TResult>()
+
}}|
+
|{{
+
DownloadFirstMessageToFile
+
DownloadLastMessageToFile
+
}}|(最初の/最後の)メッセージの本文を指定されたファイルに保存します。|{{
+
PopClient.DownloadFirstMessageToFile()
+
PopClient.DownloadLastMessageToFile()
+
}}|
+
|{{
+
DownloadAllMessagesToDirectory
+
DownloadAllMessagesToFiles
+
}}|すべてのメッセージの本文を指定されたディレクトリ、もしくはデリゲートが返すファイル名で保存します。&br;なお、deleteAfterDownloadにtrueを指定した場合、すべてのメッセージ本文の取得に成功した場合のみメッセージの削除が行われます。 (途中で失敗した場合は、メッセージは削除されません)|{{
+
PopClient.DownloadAllMessagesToDirectory()
+
PopClient.DownloadAllMessagesToFiles()
+
}}|
+

          
+

          
 
#hr
#hr
 

        

        
 

        

        
915,7 833,7
 
    using (var client = new PopClient(new Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))) {
    using (var client = new PopClient(new Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))) {
 
      client.Connect("pass");
      client.Connect("pass");
 

        

        
~
      // メールボックスにある1件目のメッセージをダウンロードしてファイル"sample.eml"に保存
      // メールボックスにある1件目のメッセージをダウンロードしてファイルに保存
 
      client.DownloadFirstMessageToFile("sample.eml");
      client.DownloadFirstMessageToFile("sample.eml");
 
    }
    }
 
  }
  }
933,7 851,7
 
    Using client As New PopClient(New Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))
    Using client As New PopClient(New Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))
 
      client.Connect("pass")
      client.Connect("pass")
 

        

        
~
      ' メールボックスにある1件目のメッセージをダウンロードしてファイル"sample.eml"に保存
      ' メールボックスにある1件目のメッセージをダウンロードしてファイルに保存
 
      client.DownloadFirstMessageToFile("sample.eml")
      client.DownloadFirstMessageToFile("sample.eml")
 
    End Using
    End Using
 
  End Sub
  End Sub
941,50 859,6
 
}}
}}
 
#tabpage-end
#tabpage-end
 

        

        
+
静的メソッドを使って次のようにすることもできます。
+

          
+
#tabpage(C#)
+
#code(cs){{
+
using System;
+

          
+
using Smdn.Net.Pop3;
+
using Smdn.Net.Pop3.Client;
+

          
+
class SaveToFile {
+
  public static void Main(string[] args)
+
  {
+
    const bool deleteAfterDownload = false;
+

          
+
    // メールボックスにある1件目のメッセージをダウンロードしてファイル"sample.eml"に保存
+
    PopClient.DownloadFirstMessageToFile(new Uri("pop://user;AUTH=DIGEST-MD5@localhost/"),
+
                                         "pass",
+
                                         deleteAfterDownload,
+
                                         "sample.eml");
+
  }
+
}
+
}}
+
#tabpage(VB)
+
#code(vb){{
+
Imports System
+

          
+
Imports Smdn.Net.Pop3
+
Imports Smdn.Net.Pop3.Client
+

          
+
Class SaveToFile
+
  Public Shared Sub Main(ByVal args As String())
+
    Const deleteAfterDownload As Boolean = False
+

          
+
    ' メールボックスにある1件目のメッセージをダウンロードしてファイル"sample.eml"に保存
+
    PopClient.DownloadFirstMessageToFile(New Uri("pop://user;AUTH=DIGEST-MD5@localhost/"), _
+
                                         "pass", _
+
                                         deleteAfterDownload, _
+
                                         "sample.eml")
+
  End Sub
+
End Class
+
}}
+
#tabpage-end
+

          
+

          
 
***Gmailアカウントのメールボックスから、最新のメッセージをダウンロードする [#PopClient.sample2]
***Gmailアカウントのメールボックスから、最新のメッセージをダウンロードする [#PopClient.sample2]
 
#tabpage(C#)
#tabpage(C#)
 
#code(cs){{
#code(cs){{
1177,78 1051,6
 
}}
}}
 
#tabpage-end
#tabpage-end
 

        

        
+
さらに、静的メソッドを使うことで次のようにすることもできます。 ただし、この例ではUniqueIdプロパティを参照する度にIDを取得するコマンド(UIDL)が送信される点に注意が必要です。 先の例ではPopClient.GetMessages(true)で全メッセージとそのIDを同時に取得しているため、送信されるコマンドの総数は先の例の方が少なくなります。
+

          
+
#tabpage(C#)
+
#code(cs){{
+
using System;
+

          
+
using Smdn.Net.Pop3;
+
using Smdn.Net.Pop3.Client;
+
using Smdn.Net.Pop3.Protocol.Client;
+

          
+
class SaveAndDelete {
+
  private static string SelectFileNameOf(PopMessageInfo message)
+
  {
+
    // IDをファイル名として使用 (IDがファイル名として妥当かどうかのチェックは省略)
+
    return message.UniqueId + ".eml";
+
  }
+

          
+
  public static void Main(string[] args)
+
  {
+
    PopConnection.ServerCertificateValidationCallback += delegate {
+
      // 証明書の検証は省略 (エラーを無視してすべて受け入れる)
+
      return true;
+
    };
+

          
+
    // メールボックスにあるすべてのメッセージを取得して指定したファイル名で保存
+
    PopClient.DownloadAllMessagesToFiles(new Uri("pops://user;auth=ntlm@localhost/"),
+
                                         "pass",
+
                                         true,
+
                                         SelectFileNameOf);
+
  }
+
}
+
}}
+
#tabpage(VB)
+
#code(vb){{
+
Imports System
+
Imports System.Net
+
Imports System.Net.Security
+
Imports System.Security.Cryptography.X509Certificates
+
Imports System.Text
+

          
+
Imports Smdn.Net.Pop3
+
Imports Smdn.Net.Pop3.Client
+
Imports Smdn.Net.Pop3.Protocol.Client
+

          
+
Class SaveAndDelete
+
  Private Shared Function ValidateRemoteCertificate(ByVal sender As Object, _
+
                                                    ByVal certificate As X509Certificate, _
+
                                                    ByVal chain As X509Chain, _
+
                                                    ByVal sslPolicyErrors As SslPolicyErrors) As Boolean
+
    ' 証明書の検証は省略 (エラーを無視してすべて受け入れる)
+
    Return True
+
  End Function
+

          
+
  Private Shared Function SelectFileNameOf(ByVal message As PopMessageInfo) As String
+
    ' IDをファイル名として使用 (IDがファイル名として妥当かどうかのチェックは省略)
+
    Return message.UniqueId + ".eml"
+
  End Function
+

          
+
  Public Shared Sub Main(ByVal args As String())
+
    PopConnection.ServerCertificateValidationCallback = New RemoteCertificateValidationCallback(AddressOf ValidateRemoteCertificate)
+

          
+
      ' メールボックスにあるすべてのメッセージを取得して指定したファイル名で保存
+
    PopClient.DownloadAllMessagesToFiles(New Uri("pops://user;auth=ntlm@localhost/"), _
+
                                         "pass", _
+
                                         True, _
+
                                         AddressOf SelectFileNameOf)
+
  End Sub
+
End Class
+
}}
+
#tabpage-end
+

          
+

          
 
***メッセージのIDを使って新着メッセージをチェックする
***メッセージのIDを使って新着メッセージをチェックする
 
#tabpage(C#)
#tabpage(C#)
 
#code(cs){{
#code(cs){{
1356,7 1158,7
 
また、サーバがUIDLコマンドをサポートしていない場合は、client.GetMessages(true)の時点で例外が発生し、プログラムが停止します。 サーバがUIDLコマンドをサポートしていない可能性がある場合は、PopClient.GetMessages()にはfalseを指定してIDを取得しないようにし、代わりにPopMessageInfo.TryGetUniqueId()メソッドを使ってIDの取得を試みるようにすることができます(ただし、メッセージ一つ一つに対してUIDLコマンドを発行するようになる点には留意が必要です)。
また、サーバがUIDLコマンドをサポートしていない場合は、client.GetMessages(true)の時点で例外が発生し、プログラムが停止します。 サーバがUIDLコマンドをサポートしていない可能性がある場合は、PopClient.GetMessages()にはfalseを指定してIDを取得しないようにし、代わりにPopMessageInfo.TryGetUniqueId()メソッドを使ってIDの取得を試みるようにすることができます(ただし、メッセージ一つ一つに対してUIDLコマンドを発行するようになる点には留意が必要です)。
 

        

        
 
***メッセージをダウンロードしてパース・デコードする
***メッセージをダウンロードしてパース・デコードする
~
メッセージをダウンロードした後、[[works/libs/Smdn.Formats.Mime]]のMailクラスを使ってパース・デコードする例。
メッセージをダウンロードした後、[[works/libs/Smdn.Formats.Mime]]を使ってパース・デコードする例。
 
#tabpage(C#)
#tabpage(C#)
 
#code(cs){{
#code(cs){{
 
using System;
using System;
1375,18 1177,18
 

        

        
 
      // すべてのメッセージを取得
      // すべてのメッセージを取得
 
      foreach (var message in client.GetMessages()) {
      foreach (var message in client.GetMessages()) {
~
        // メッセージの本文を取得し、Mail.Loadメソッドでパース・デコードした結果を得る
        // メッセージの本文を取得し、MimeMessage.Loadメソッドでパース・デコードした結果を得る
~
        var mail = message.ReadAs<Mail>(Mail.Load);
        var decodedMessage = message.ReadAs<MimeMessage>(MimeMessage.Load);
 

        

        
 
        // デコードしたメッセージの件名を表示
        // デコードしたメッセージの件名を表示
 
        Console.WriteLine("====[{0}: {1}]{2}",
        Console.WriteLine("====[{0}: {1}]{2}",
 
                          message.MessageNumber,
                          message.MessageNumber,
~
                          mail.Subject,
                          decodedMessage.Headers["Subject"].Value,
 
                          new string('=', 32));
                          new string('=', 32));
 

        

        
 
        // デコードした本文を表示
        // デコードした本文を表示
~
        if (mail.MimeType.TypeEqualsIgnoreCase("text"))
        if (decodedMessage.MimeType.TypeEqualsIgnoreCase("text"))
~
          Console.WriteLine(mail.ReadContentAsText());
          Console.WriteLine(decodedMessage.ReadContentAsText());
 
        else
        else
 
          Console.WriteLine("非テキストメッセージです");
          Console.WriteLine("非テキストメッセージです");
 
      }
      }
1412,16 1214,16
 
      ' すべてのメッセージを取得
      ' すべてのメッセージを取得
 
      For Each message As PopMessageInfo In client.GetMessages()
      For Each message As PopMessageInfo In client.GetMessages()
 
        ' メッセージの本文を取得し、MimeMessage.Loadメソッドでパース・デコードした結果を得る
        ' メッセージの本文を取得し、MimeMessage.Loadメソッドでパース・デコードした結果を得る
~
        Dim mail As Mail = message.ReadAs(Of Mail)(AddressOf Mail.Load)
        Dim decodedMessage As MimeMessage = message.ReadAs(Of MimeMessage)(AddressOf MimeMessage.Load)
 

        

        
 
        ' デコードしたメッセージの件名を表示
        ' デコードしたメッセージの件名を表示
~
        Console.WriteLine("====[{0}: {1}]{2}", _
        Console.WriteLine("====[{0}: {1}]{2}",
~
                          message.MessageNumber, _
                          message.MessageNumber,
~
                          mail.Subject, _
                          decodedMessage.Headers("Subject").Value,
 
                          New String("="c, 32))
                          New String("="c, 32))
 

        

        
 
        ' デコードした本文を表示
        ' デコードした本文を表示
~
        If mail.MimeType.TypeEqualsIgnoreCase("text") Then
        If decodedMessage.MimeType.TypeEqualsIgnoreCase("text") Then
 
          Console.WriteLine(decodedMessage.ReadContentAsText())
          Console.WriteLine(decodedMessage.ReadContentAsText())
 
        Else
        Else
 
          Console.WriteLine("非テキストメッセージです")
          Console.WriteLine("非テキストメッセージです")

works/libs/Smdn.Net.Imap4.Client/docs/index.wiki.txt

current previous
2,7 2,7
 
${smdncms:keywords,}
${smdncms:keywords,}
 
${smdncms:document_versions,codelang=cs,codelang=vb}
${smdncms:document_versions,codelang=cs,codelang=vb}
 
${pragma,parser-options,non-limited-list}
${pragma,parser-options,non-limited-list}
~
[[works/libs/Smdn.Net.Imap4.Client]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.82時点のもので、記載不備などがあるかもしれません。
[[works/libs/Smdn.Net.Imap4.Client]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.80時点のもので、記載不備などがあるかもしれません。
 

        

        
 
サンプルコードは[[このページの最後>#samples]]にあります。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
サンプルコードは[[このページの最後>#samples]]にあります。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
 

        

        
111,8 111,98
 
**接続と認証 [#login]
**接続と認証 [#login]
 
ここでは接続時と認証時の動作について解説します。
ここでは接続時と認証時の動作について解説します。
 

        

        
-
***接続・切断・サーバ情報に関するメンバ
-
以下は接続・切断・サーバ情報に関するメソッドとプロパティです。
-

          
-
|*ImapClientクラスのメソッド
-
|~メソッド|~解説|~対応するIMAPコマンド|h
-
|Connect(string)&br;Connect(ICredentialsByHost)|ImapClient.Profileプロパティで指定された内容、および引数で指定されたパスワード(もしくはICredentialsByHost)を使って接続・認証を試みます。&br;接続・認証できた場合は、サーバの能力(サポートしている場合はID・名前空間も)を取得します。|LOGIN, AUTHENTICATE, STARTTLS, CAPABILITY&br;(サポートしている場合はID, NAMESPACEも)|
-
|BeginConnect(string)&br;BeginConnect(string, AsyncCallback, object)&br;BeginConnect(ICredentialsByHost)&br;BeginConnect(ICredentialsByHost, AsyncCallback, object)|Connect()メソッドと同じ処理を非同期的に実行します。 オプションでコールバックメソッドを指定できます。|LOGIN, AUTHENTICATE, STARTTLS, CAPABILITY&br;(サポートしている場合はID, NAMESPACEも)|
-
|EndConnect(IAsyncResult)|BeginConnect()で開始した非同期接続を完了します。 BeginConnect()を呼び出した場合、EndConnect()で操作を完了する必要があります。|-|
-
|Logout()|ログアウトします。 選択済みメールボックスの削除フラグが設定されているメッセージは削除されます。|CLOSE, LOGOUT|
-
|Disconnect()&br;IDisposable.Dispose()|ログアウトせずに切断します。 削除フラグが設定されているメッセージがあっても削除されません。|-|
-
|Refresh()|自動ログアウトタイマの更新、セッションの接続性確認などに使います。 メールボックスを選択している場合は、メールボックスの状態も更新します。 サーバからメールボックスの状態に関する通知があった場合はイベントを発生させます。|NOOP|
-

          
-
|*ImapClientクラスのプロパティ
-
|~プロパティ|~解説|h
-
|Profile|接続先のホスト・ポート・ユーザ名などを取得/設定します。 コンストラクタで指定した内容はこのプロパティに反映されます。|
-
|Timeout|コマンド処理のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|SendTimeout|ソケット送信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|ReceiveTimeout|ソケット受信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
-
|IsConnected|接続中かどうかを表す値を取得します。|
-
|ServerCapabilities|サーバがサポートする機能の一覧(CAPABILITYコマンドの結果)を取得します。|
-
|ServerID|サーバがサポートしている場合、サーバのID(IDコマンドの結果)を返します。 サポートしていない場合は、空のインスタンスを返します。|
-
|ServerNamespace|サーバがサポートしている場合、サーバの名前空間(NAMESPACEコマンドの結果)を返します。 サポートしていない場合は、空のインスタンスを返します。|
-

          
-
:IDisposable.Dispose()|ImapClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
-
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度ImapClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
-
:Timeout, SendTimeout, ReceiveTimeout|これらのプロパティはそれぞれImapClient.Profile.Timeout, ImapClient.Profile.SendTimeout, ImapClient.Profile.RecieveTimeoutを設定することと同じですが、接続後はImapClient.Profileの値を変更してもImapClientの動作には反映されません。 接続後はImapClient.Timeout, ImapClient.SendTimeout, ImapClient.ReceiveTimeoutプロパティを設定してください。
-
:ServerCapabilities, ServerID, ServerNamespace|切断されている状態で取得しようとした場合(ImapClient.IsConnectedがfalseの場合)、例外をスローします。
-

          
-
***接続に関するパラメータと動作 [#connect]
-
接続時の動作は、接続時のパラメータにより次のように変わります。
-

          
-
:SSL/TLSを使用する (IMAP over SSL)|常にSSL/TLSを使用して接続を試みます。 デフォルトのポート番号は993です。
-
接続先URL&sub{*1};のスキームに''"imaps"''を指定した場合、SecurePortプロパティ&sub{*2};に''true''を指定した場合はこの動作になります。
-
:可能ならSSL/TLSを使用する (STARTTLS)|SSL/TLSを使用せず接続を試み、サーバが&urn2url(urn:ietf:rfc:2595){STARTTLS};をサポートしていれば認証を開始する前にSSL/TLSへのアップグレードを試みます。 デフォルトのポート番号は143です。
-
接続先URL&sub{*1};のスキームに''"imap"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''true''を指定した場合はこの動作になります。
-
:SSL/TLSを使用しない|常にSSL/TLSを使用せずに接続を試みます。 サーバがSTARTTLSをサポートしていてもSSL/TLSへのアップグレードはしません。 デフォルトのポート番号は143です。
-
接続先URL&sub{*1};のスキームに''"imap"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''false''を指定した場合はこの動作になります。
-

          
-
これら接続時のパラメータは次の箇所で指定します。
-
:接続先URL&sup{*1};|ImapClientクラスのコンストラクタで指定する引数authority
-
:SecurePortプロパティ&sup{*2};|ImapClientクラスのコンストラクタで指定する引数securePort、もしくはImapClient.Profile.SecurePortプロパティ
-
:UseTlsIfAvailableプロパティ&sup{*3};|ImapClient.Profile.UseTlsIfAvailableプロパティ
-

          
-
接続先URLもしくはパラメータでポート番号を明示的に指定しない限り、デフォルトポートへの接続を試みます。 なお、ポート番号の指定ではSSL/TLSを使用するかどうかの動作は変わりません((ポート番号に993を指定してもURLのスキームが"imap"なら、接続時にSSL/TLSは使用しません))。
-

          
-
例として接続先のURLと接続時の動作を表にまとめると以下のようになります。
-

          
-
|*URLと接続動作の例
-
|~接続先URL|~接続ポート|~SSL/TLS|h
-
|imaps://user&#x40;imap.example.net/|993|SSL/TLSを使用|
-
|imaps://user&#x40;imap.example.net:10143/|10143|SSL/TLSを使用|
-
|imap://user&#x40;imap.example.net/|143|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
-
|imap://user&#x40;imap.example.net:993/|993|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
-

          
-
***認証に関するパラメータと動作 [#auth]
-
接続にIMAP URLを用いる場合、認証に用いるユーザ名と認証方式はURLから取得します。 パスワードはImapClient.Connect()メソッドに指定する引数credentials(ICredentialsByHostインターフェイス)を参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 IMAP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、URLからはパスワードを取得しません(指定されていてもパスワードとしては解釈しません)。
-

          
-
認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
-
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
-
+LOGINコマンド (サーバが許可している場合のみ)
-

          
-
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。 認証方式にANONYMOUSを指定して認証を行う場合、ユーザ名の部分をログイントークンとして送信します。 ユーザ名が指定されていない場合は"anonymous@"をログイントークンとして送信します。 ログイントークンに@などの記号を含める場合はURLエスケープする必要があります。
-

          
-
認証方式の大文字小文字の違いは無視します(IMAP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
-

          
-
例として接続先のURLと認証時の動作を表にまとめると以下のようになります。
-

          
-
|*URLと認証動作の例
-
|~接続先URL|~認証に使用するユーザ名|~使用する認証メカニズム|h
-
|imap://user;AUTH=DIGEST-MD5&#x40;imap.example.net/|user|DIGEST-MD5|
-
|imap://;AUTH=DIGEST-MD5&#x40;imap.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
-
|imap://user;AUTH=*&#x40;imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
-
|imap://user&#x40;imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
-
|imap://;AUTH=ANONYMOUS&#x40;imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
-
|imap://user&amp;#x40;localhost;AUTH=ANONYMOUS&#x40;imap.example.net/|匿名ユーザ&br;(ログイントークン: user&#x40;localhost)|ANONYMOUS|
-
|imap://imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはIMAP LOGINコマンドを使用|
-

          
-
試行する認証メカニズムを制御するには、ImapClient.Profile.UsingSaslMechanismsプロパティの値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 ImapClient.Profile.AllowInsecureLoginプロパティにfalseを指定した場合で、かつ現在の接続がSSL/TLSで保護されていない場合、平文による認証は試行されません(デフォルトはfalseです)。
-

          
-
|*サーバが対応している認証方式と認証試行順の例
-
|~サーバが対応している認証方式|~UsingSaslMechanismsの値|~試行順序&br;(接続がSSL/TLSで保護されている、もしくはAllowInsecureLoginがtrueの場合)|~試行順序&br;(接続がSSL/TLSで保護されていない、かつAllowInsecureLoginがfalseの場合)|h
-
|DIGEST-MD5&br;CRAM-MD5&br;IMAP LOGIN|{"DIGEST-MD5", "CRAM-MD5"}|1.DIGEST-MD5&br;2.CRAM-MD5&br;3.IMAP LOGIN|1.DIGEST-MD5&br;2.CRAM-MD5|
-
|DIGEST-MD5&br;CRAM-MD5&br;PLAIN&br;|{"PLAIN", "DIGEST-MD5"}|1.PLAIN&br;2.DIGEST-MD5|1.DIGEST-MD5|
-
|PLAIN&br;IMAP LOGIN|null|1.IMAP LOGIN|ImapAuthenticationExceptionをスロー&br;(試行できる認証方式なし)|
-

          
-
***認証時に参照する資格情報 [#creds]
-
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
-

          
-
//現時点ではSecureStringに格納されたパスワードには対応していません。 &msdn(netfx,member,System.Net.NetworkCredential.SecurePassword){NetworkCredential.SecurePasswordプロパティ};にパスワードが設定されていても無視します。
-

          
 
***接続・認証のコードと動作の例
***接続・認証のコードと動作の例
~
以下は接続・認証処理の記述例です。 個々のパラメータの指定方法と動作の詳細についてはこの後順に解説していきます。 なお、実際にSSL/TLSを使用する場合は[[証明書の検証等>#ssl]]が必要になります。
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#ssl]]が必要になります。
 

        

        
 
#tabpage(C#)
#tabpage(C#)
 
#code(cs,ImapClient){{
#code(cs,ImapClient){{
232,97 322,6
 
}}
}}
 
#tabpage-end
#tabpage-end
 

        

        
+
***接続・切断・サーバ情報に関するメンバ
+
以下は接続・切断・サーバ情報に関するメソッドとプロパティです。
+

          
+
|*ImapClientクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|Connect(string)&br;Connect(ICredentialsByHost)|ImapClient.Profileプロパティで指定された内容、および引数で指定されたパスワード(もしくはICredentialsByHost)を使って接続・認証を試みます。&br;接続・認証できた場合は、サーバの能力(サポートしている場合はID・名前空間も)を取得します。|LOGIN, AUTHENTICATE, STARTTLS, CAPABILITY&br;(サポートしている場合はID, NAMESPACEも)|
+
|BeginConnect(string)&br;BeginConnect(string, AsyncCallback, object)&br;BeginConnect(ICredentialsByHost)&br;BeginConnect(ICredentialsByHost, AsyncCallback, object)|Connect()メソッドと同じ処理を非同期的に実行します。 オプションでコールバックメソッドを指定できます。|LOGIN, AUTHENTICATE, STARTTLS, CAPABILITY&br;(サポートしている場合はID, NAMESPACEも)|
+
|EndConnect(IAsyncResult)|BeginConnect()で開始した非同期接続を完了します。 BeginConnect()を呼び出した場合、EndConnect()で操作を完了する必要があります。|-|
+
|ConnectAsync(string)&br;ConnectAsync(ICredentialsByHost)|[.NET 4.0]&br;Connect()メソッドと同じ処理を非同期的に実行し、非同期操作を表すTaskを返します。|LOGIN, AUTHENTICATE, STARTTLS, CAPABILITY&br;(サポートしている場合はID, NAMESPACEも)|
+
|Logout()|ログアウトします。 選択済みメールボックスの削除フラグが設定されているメッセージは削除されます。|CLOSE, LOGOUT|
+
|Disconnect()&br;IDisposable.Dispose()|ログアウトせずに切断します。 削除フラグが設定されているメッセージがあっても削除されません。|-|
+
|Refresh()|自動ログアウトタイマの更新、セッションの接続性確認などに使います。 メールボックスを選択している場合は、メールボックスの状態も更新します。 サーバからメールボックスの状態に関する通知があった場合はイベントを発生させます。|NOOP|
+

          
+
|*ImapClientクラスのプロパティ
+
|~プロパティ|~解説|h
+
|Profile|接続先のホスト・ポート・ユーザ名などを取得/設定します。 コンストラクタで指定した内容はこのプロパティに反映されます。|
+
|Timeout|コマンド処理のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|SendTimeout|ソケット送信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|ReceiveTimeout|ソケット受信時のタイムアウト時間をミリ秒単位で取得/設定します。 Timeout.Infinite(-1)を指定した場合はタイムアウトしません。|
+
|IsConnected|接続中かどうかを表す値を取得します。|
+
|ServerCapabilities|サーバがサポートする機能の一覧(CAPABILITYコマンドの結果)を取得します。|
+
|ServerID|サーバがサポートしている場合、サーバのID(IDコマンドの結果)を返します。 サポートしていない場合は、空のインスタンスを返します。|
+
|ServerNamespace|サーバがサポートしている場合、サーバの名前空間(NAMESPACEコマンドの結果)を返します。 サポートしていない場合は、空のインスタンスを返します。|
+

          
+
:IDisposable.Dispose()|ImapClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
+
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度ImapClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
+
:Timeout, SendTimeout, ReceiveTimeout|これらのプロパティはそれぞれImapClient.Profile.Timeout, ImapClient.Profile.SendTimeout, ImapClient.Profile.RecieveTimeoutを設定することと同じですが、接続後はImapClient.Profileの値を変更してもImapClientの動作には反映されません。 接続後はImapClient.Timeout, ImapClient.SendTimeout, ImapClient.ReceiveTimeoutプロパティを設定してください。
+
:ServerCapabilities, ServerID, ServerNamespace|切断されている状態で取得しようとした場合(ImapClient.IsConnectedがfalseの場合)、例外をスローします。
+

          
+
***接続に関するパラメータと動作 [#connect]
+
接続時の動作は、接続時のパラメータにより次のように変わります。
+

          
+
:SSL/TLSを使用する (IMAP over SSL)|常にSSL/TLSを使用して接続を試みます。 デフォルトのポート番号は993です。
+
接続先URL&sub{*1};のスキームに''"imaps"''を指定した場合、SecurePortプロパティ&sub{*2};に''true''を指定した場合はこの動作になります。
+
:可能ならSSL/TLSを使用する (STARTTLS)|SSL/TLSを使用せず接続を試み、サーバが&urn2url(urn:ietf:rfc:2595){STARTTLS};をサポートしていれば認証を開始する前にSSL/TLSへのアップグレードを試みます。 デフォルトのポート番号は143です。
+
接続先URL&sub{*1};のスキームに''"imap"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''true''を指定した場合はこの動作になります。
+
:SSL/TLSを使用しない|常にSSL/TLSを使用せずに接続を試みます。 サーバがSTARTTLSをサポートしていてもSSL/TLSへのアップグレードはしません。 デフォルトのポート番号は143です。
+
接続先URL&sub{*1};のスキームに''"imap"''を指定した場合、SecurePortプロパティ&sub{*2};に''false''を指定した場合で、UseTlsIfAvailableプロパティ&sub{*3};に''false''を指定した場合はこの動作になります。
+

          
+
これら接続時のパラメータは次の箇所で指定します。
+
:接続先URL&sup{*1};|ImapClientクラスのコンストラクタで指定する引数authority
+
:SecurePortプロパティ&sup{*2};|ImapClientクラスのコンストラクタで指定する引数securePort、もしくはImapClient.Profile.SecurePortプロパティ
+
:UseTlsIfAvailableプロパティ&sup{*3};|ImapClient.Profile.UseTlsIfAvailableプロパティ
+

          
+
接続先URLもしくはパラメータでポート番号を明示的に指定しない限り、デフォルトポートへの接続を試みます。 なお、ポート番号の指定ではSSL/TLSを使用するかどうかの動作は変わりません((ポート番号に993を指定してもURLのスキームが"imap"なら、接続時にSSL/TLSは使用しません))。
+

          
+
例として接続先のURLと接続時の動作を表にまとめると以下のようになります。
+

          
+
|*URLと接続動作の例
+
|~接続先URL|~接続ポート|~SSL/TLS|h
+
|imaps://user&#x40;imap.example.net/|993|SSL/TLSを使用|
+
|imaps://user&#x40;imap.example.net:10143/|10143|SSL/TLSを使用|
+
|imap://user&#x40;imap.example.net/|143|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
+
|imap://user&#x40;imap.example.net:993/|993|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
+

          
+
***認証に関するパラメータと動作 [#auth]
+
接続にIMAP URLを用いる場合、認証に用いるユーザ名と認証方式はURLから取得します。 パスワードはImapClient.Connect()メソッドに指定する引数credentials(ICredentialsByHostインターフェイス)を参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 IMAP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、URLからはパスワードを取得しません(指定されていてもパスワードとしては解釈しません)。
+

          
+
認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
+
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
+
+LOGINコマンド (サーバが許可している場合のみ)
+

          
+
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。 認証方式にANONYMOUSを指定して認証を行う場合、ユーザ名の部分をログイントークンとして送信します。 ユーザ名が指定されていない場合は"anonymous@"をログイントークンとして送信します。 ログイントークンに@などの記号を含める場合はURLエスケープする必要があります。
+

          
+
認証方式の大文字小文字の違いは無視します(IMAP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
+

          
+
例として接続先のURLと認証時の動作を表にまとめると以下のようになります。
+

          
+
|*URLと認証動作の例
+
|~接続先URL|~認証に使用するユーザ名|~使用する認証メカニズム|h
+
|imap://user;AUTH=DIGEST-MD5&#x40;imap.example.net/|user|DIGEST-MD5|
+
|imap://;AUTH=DIGEST-MD5&#x40;imap.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
+
|imap://user;AUTH=*&#x40;imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|imap://user&#x40;imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|imap://;AUTH=ANONYMOUS&#x40;imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
+
|imap://user&amp;#x40;localhost;AUTH=ANONYMOUS&#x40;imap.example.net/|匿名ユーザ&br;(ログイントークン: user&#x40;localhost)|ANONYMOUS|
+
|imap://imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはIMAP LOGINコマンドを使用|
+

          
+
試行する認証メカニズムを制御するには、ImapClient.Profile.UsingSaslMechanismsプロパティの値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 ImapClient.Profile.AllowInsecureLoginプロパティにfalseを指定した場合で、かつ現在の接続がSSL/TLSで保護されていない場合、平文による認証は試行されません(デフォルトはfalseです)。
+

          
+
|*サーバが対応している認証方式と認証試行順の例
+
|~サーバが対応している認証方式|~UsingSaslMechanismsの値|~試行順序&br;(接続がSSL/TLSで保護されている、もしくはAllowInsecureLoginがtrueの場合)|~試行順序&br;(接続がSSL/TLSで保護されていない、かつAllowInsecureLoginがfalseの場合)|h
+
|DIGEST-MD5&br;CRAM-MD5&br;IMAP LOGIN|{"DIGEST-MD5", "CRAM-MD5"}|1.DIGEST-MD5&br;2.CRAM-MD5&br;3.IMAP LOGIN|1.DIGEST-MD5&br;2.CRAM-MD5|
+
|DIGEST-MD5&br;CRAM-MD5&br;PLAIN&br;|{"PLAIN", "DIGEST-MD5"}|1.PLAIN&br;2.DIGEST-MD5|1.DIGEST-MD5|
+
|PLAIN&br;IMAP LOGIN|null|1.IMAP LOGIN|ImapAuthenticationExceptionをスロー&br;(試行できる認証方式なし)|
+

          
+
***認証時に参照する資格情報 [#creds]
+
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
+

          
+
//現時点ではSecureStringに格納されたパスワードには対応していません。 &msdn(netfx,member,System.Net.NetworkCredential.SecurePassword){NetworkCredential.SecurePasswordプロパティ};にパスワードが設定されていても無視します。
+

          
 
**SSL/TLSを使用した接続 [#ssl]
**SSL/TLSを使用した接続 [#ssl]
 
***証明書の選択と検証 [#certs]
***証明書の選択と検証 [#certs]
 
SSL/TLS接続時に使用する証明書は&msdn(netfx,type,System.Security.Cryptography.X509Certificates.X509Certificate2Collection){X509Certificate2Collection};で設定できます。 また、証明書の選択と検証には&msdn(netfx,type,System.Net.Security.RemoteCertificateValidationCallback){RemoteCertificateValidationCallbackデリゲート};と&msdn(netfx,type,System.Net.Security.LocalCertificateSelectionCallback){LocalCertificateSelectionCallbackデリゲート};を指定できます。 デフォルトの状態では、SSL/TLS接続時にこれらのコールバックメソッドを呼び出して証明書の検証と選択を行い、&msdn(netfx,type,System.Net.Security.SslStream){SslStream};を作成します。
SSL/TLS接続時に使用する証明書は&msdn(netfx,type,System.Security.Cryptography.X509Certificates.X509Certificate2Collection){X509Certificate2Collection};で設定できます。 また、証明書の選択と検証には&msdn(netfx,type,System.Net.Security.RemoteCertificateValidationCallback){RemoteCertificateValidationCallbackデリゲート};と&msdn(netfx,type,System.Net.Security.LocalCertificateSelectionCallback){LocalCertificateSelectionCallbackデリゲート};を指定できます。 デフォルトの状態では、SSL/TLS接続時にこれらのコールバックメソッドを呼び出して証明書の検証と選択を行い、&msdn(netfx,type,System.Net.Security.SslStream){SslStream};を作成します。
794,7 793,7
 
以下はメッセージ本文の取得に関するメソッドです。
以下はメッセージ本文の取得に関するメソッドです。
 

        

        
 
|*ImapMessageInfoクラスのメソッド
|*ImapMessageInfoクラスのメソッド
~
|~メソッド|~解説|~対応するIMAPコマンド|h
|~メソッド|~解説|~対応するPOPコマンド|h
 
|{{
|{{
 
OpenRead()
OpenRead()
 
およびオーバーロード
およびオーバーロード
850,7 849,7
 
WriteTo(BinaryWriter)
WriteTo(BinaryWriter)
 
およびオーバーロード
およびオーバーロード
 
}}|メッセージ本文を指定されたBinaryWriterに書き込みます。|FETCH|
}}|メッセージ本文を指定されたBinaryWriterに書き込みます。|FETCH|
~
|~メソッド|~解説|~対応するIMAPコマンド|f
|~メソッド|~解説|~対応するPOPコマンド|f
 

        

        
 
:すべてのメソッド|これらすべてのメソッドは、取得したメッセージ本文をキャッシュしません。 ''メソッド呼び出しの度にメッセージ本文のダウンロードを行います。'' 同じメッセージを何度も処理する必要がある場合は、WriteTo()メソッドでMemoryStream等に書き出すか、Save()メソッドでファイルに保存するなどしてください。
:すべてのメソッド|これらすべてのメソッドは、取得したメッセージ本文をキャッシュしません。 ''メソッド呼び出しの度にメッセージ本文のダウンロードを行います。'' 同じメッセージを何度も処理する必要がある場合は、WriteTo()メソッドでMemoryStream等に書き出すか、Save()メソッドでファイルに保存するなどしてください。
 
:メッセージ本文の取得オプション(ImapMessageFetchBodyOptions)|これらのメソッドには、ImapMessageFetchBodyOptionsを引数にとるバージョンのオーバーロードを用意してあります。 ImapMessageFetchBodyOptionsを指定することで、メッセージ本文取得時の動作を指定することができます。 以下の値を組み合わせて指定できます。
:メッセージ本文の取得オプション(ImapMessageFetchBodyOptions)|これらのメソッドには、ImapMessageFetchBodyOptionsを引数にとるバージョンのオーバーロードを用意してあります。 ImapMessageFetchBodyOptionsを指定することで、メッセージ本文取得時の動作を指定することができます。 以下の値を組み合わせて指定できます。
860,20 859,6
 
:::サポートされる文字コード(Content-Typeのcharsetパラメータ)|utf-8, shift_jis, iso-2022-jpほか、ランタイムがサポートする文字コード
:::サポートされる文字コード(Content-Typeのcharsetパラメータ)|utf-8, shift_jis, iso-2022-jpほか、ランタイムがサポートする文字コード
 
::Default|オプションのデフォルト値です。 上記オプションのいずれも指定しない場合と同値です。
::Default|オプションのデフォルト値です。 上記オプションのいずれも指定しない場合と同値です。
 

        

        
+
***メッセージヘッダの取得
+
以下はメッセージヘッダ(From, Subject, Content-Type等)の取得に関するメソッドです。
+

          
+
|*ImapMessageInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|{{
+
GetHeader()
+
およびオーバーロード
+
}}|メッセージのヘッダ部分のみを取得し、ヘッダ名と値に分離したKeyValuePairの配列で返します。 オプションで取得するヘッダや、ヘッダの値をデコードするかどうかを指定できます。|FETCH|
+
|{{
+
GetRawHeader()
+
およびオーバーロード
+
}}|メッセージのヘッダ部分のみを取得し、単一の文字列として返します。 オプションで取得するヘッダを指定できます。|FETCH|
+

          
 
***メッセージの操作
***メッセージの操作
 
以下はメールボックスにあるメッセージの移動・削除・コピー・フラグの変更等の操作に関するメソッドです。
以下はメールボックスにあるメッセージの移動・削除・コピー・フラグの変更等の操作に関するメソッドです。
 

        

        
1147,7 1132,7
 
}}
}}
 

        

        
 
*非同期操作・スレッドセーフティ
*非同期操作・スレッドセーフティ
~
現時点で非同期操作をサポートするメソッドは、ImapClient.BeginConnect()/EndConnect()、ImapClient.ConnectAsync()のみです。
現時点で非同期操作をサポートするメソッドは、ImapClient.BeginConnect()/EndConnect()のみです。
 

        

        
 
また現時点では、上記の非同期操作用のメソッドを除き、ImapClientなどのクラスはスレッドセーフではありません。 内部で使用している実装はスレッドセーフなので、処理内容によっては問題なく動作するかもしれませんが、保証はできません。 個々のインスタンスは同一スレッド内で使用してください。 今後のバージョンでスレッドセーフティを保証した実装に改善する予定です。
また現時点では、上記の非同期操作用のメソッドを除き、ImapClientなどのクラスはスレッドセーフではありません。 内部で使用している実装はスレッドセーフなので、処理内容によっては問題なく動作するかもしれませんが、保証はできません。 個々のインスタンスは同一スレッド内で使用してください。 今後のバージョンでスレッドセーフティを保証した実装に改善する予定です。