2010-05-15T18:52:11の更新内容

works/libs/Smdn.Net.Imap4/doc/index.wiki.txt

current previous
20,7 20,7
 
上記以外は、&urn2url(urn:ietf:rfc:3501,short);および.NET Frameworkの用語に準じます。
上記以外は、&urn2url(urn:ietf:rfc:3501,short);および.NET Frameworkの用語に準じます。
 

        

        
 
*ライブラリの構成
*ライブラリの構成
~
**&aname(assemblies){アセンブリ構成};
**アセンブリ構成
 
本ライブラリはいくつかのアセンブリに分かれています。
本ライブラリはいくつかのアセンブリに分かれています。
 
|*アセンブリに含まれる型と用途
|*アセンブリに含まれる型と用途
 
|~アセンブリ|~含まれる型|h
|~アセンブリ|~含まれる型|h
34,7 34,7
 

        

        
 
本ライブラリを使用する場合は、上記アセンブリへの参照を追加してください(ImapWebRequest/ImapWebResponseを使用しない場合は、Smdn.Net.Imap4.WebClients.dllへの参照は不要です)。
本ライブラリを使用する場合は、上記アセンブリへの参照を追加してください(ImapWebRequest/ImapWebResponseを使用しない場合は、Smdn.Net.Imap4.WebClients.dllへの参照は不要です)。
 

        

        
~
**&aname(clients){クライアント実装};
**&name(clients){クライアント実装};
 
クライアントの実装は次の3種類があります。
クライアントの実装は次の3種類があります。
 
|*クライアント実装の種類と概要
|*クライアント実装の種類と概要
 
|~名前空間|~クラス|~概要|~解説|h
|~名前空間|~クラス|~概要|~解説|h
85,7 85,7
 
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
 
+LOGINコマンド (サーバが許可している場合のみ)
+LOGINコマンド (サーバが許可している場合のみ)
 

        

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

        

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

        

        
97,22 97,14
 
|imap://;AUTH=DIGEST-MD5@imap.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
|imap://;AUTH=DIGEST-MD5@imap.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
 
|imap://user;AUTH=*@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
|imap://user;AUTH=*@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
 
|imap://user@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
|imap://user@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
~
|imap://;AUTH=ANONYMOUS@imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
|imap://;AUTH=ANONYMOUS@imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
~
|imap://user@localhost;AUTH=ANONYMOUS@imap.example.net/|匿名ユーザ&br;(ログイントークン: user@localhost)|ANONYMOUS|
|imap://imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはLOGINコマンドを使用|
~
|imap://imap.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはIMAP LOGINコマンドを使用|

          
~

          
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
+
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 AllowInsecureLogin&sub{*3};プロパティに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;(試行できる認証方式なし)|
 

        

        
 
これら認証時のパラメータは次の箇所で指定します。
これら認証時のパラメータは次の箇所で指定します。
 
:ICredentialsByHostインターフェイス&sup{*1};|[[ImapClient.Connect()メソッド>#ImapClient.login]]に指定する引数credentials、もしくは[[ImapWebRequest.Credentialsプロパティ>#ImapWebRequest.login]]
:ICredentialsByHostインターフェイス&sup{*1};|[[ImapClient.Connect()メソッド>#ImapClient.login]]に指定する引数credentials、もしくは[[ImapWebRequest.Credentialsプロパティ>#ImapWebRequest.login]]
 
:UsingSaslMechanismsプロパティ&sup{*2};|[[ImapClient.Profile.UsingSaslMechanismsプロパティ>#ImapClient.login]]、もしくは[[ImapWebRequest.UsingSaslMechanismsプロパティ>#ImapWebRequest.login]]
:UsingSaslMechanismsプロパティ&sup{*2};|[[ImapClient.Profile.UsingSaslMechanismsプロパティ>#ImapClient.login]]、もしくは[[ImapWebRequest.UsingSaslMechanismsプロパティ>#ImapWebRequest.login]]
+
:AllowInsecureLoginプロパティ&sup{*3};|[[ImapClient.Profile.AllowInsecureLoginプロパティ>#ImapClient.login]]、もしくは[[ImapWebRequest.AllowInsecureLoginプロパティ>#ImapWebRequest.login]]
 

        

        
 
***&aname(creds){資格情報};
***&aname(creds){資格情報};
 
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
145,10 137,9
 
ライブラリからは主に以下の例外をスローします。 InnerExceptionプロパティに原因となった例外を設定した状態でスローする場合もあります。
ライブラリからは主に以下の例外をスローします。 InnerExceptionプロパティに原因となった例外を設定した状態でスローする場合もあります。
 
|*ライブラリがスローする例外
|*ライブラリがスローする例外
 
|~例外クラス|~スローされる状況|h
|~例外クラス|~スローされる状況|h
~
|ImapInvalidOperationException&br;および派生クラス (Smdn.Net.Imap4)|プロトコル上不正な操作を行おうとした場合&br;認証に失敗した場合はImapAuthenticationException&br;サーバに不正な要求を行おうとした場合はImapProtocolViolationException&br;サーバがエラー応答を返した場合はImapErrorResponseException|
|ImapInvalidOperationException&br;および派生クラス (Smdn.Net.Imap4)|プロトコル上不正な操作を行おうとした場合&br;サーバに不正な要求を行おうとした場合はImapProtocolViolationException&br;サーバがエラー応答を返した場合はImapErrorResponseException|
 
|ImapConnectionException&br;および派生クラス (Smdn.Net.Imap4.Protocol)|接続に失敗した場合、ソケットエラーが発生した場合など&br;SSL/TLSに起因するエラーの場合はImapSecureConnectionException|
|ImapConnectionException&br;および派生クラス (Smdn.Net.Imap4.Protocol)|接続に失敗した場合、ソケットエラーが発生した場合など&br;SSL/TLSに起因するエラーの場合はImapSecureConnectionException|
 
|TimeoutException (System)|ソケット送受信中やコマンド処理中にタイムアウトした場合|
|TimeoutException (System)|ソケット送受信中やコマンド処理中にタイムアウトした場合|
+
|InvalidOperationException (System)|現在のクライアントの状態に対して無効な操作を行おうとした場合|
 
|ArgumentException&br;および派生クラス (System)|nullや値域外の値など、メソッド呼び出し時の引数が不正な場合|
|ArgumentException&br;および派生クラス (System)|nullや値域外の値など、メソッド呼び出し時の引数が不正な場合|
 
|WebException&br;またはProtocolViolationException (System.Net)|Smdn.Net.Imap4.WebClients名前空間で発生した例外は、これらの例外に変換した上でスローされます|
|WebException&br;またはProtocolViolationException (System.Net)|Smdn.Net.Imap4.WebClients名前空間で発生した例外は、これらの例外に変換した上でスローされます|
 

        

        
191,73 182,6
 

        

        
 
なお、SSL/TLSを使用しているかどうかに関わらず、ログには''パスワードを含む内容を平文で''出力します。 ログの出力が不要な場合はTRACEを無効にしてリビルドするか、Trace.csなどを削除してください。
なお、SSL/TLSを使用しているかどうかに関わらず、ログには''パスワードを含む内容を平文で''出力します。 ログの出力が不要な場合はTRACEを無効にしてリビルドするか、Trace.csなどを削除してください。
 

        

        
+
***トレース内容のカスタマイズ
+
トレースにログを出力する際、出力内容はSmdn.Net.MessageAccessProtocols.Diagnosticsの各クラスのインスタンスとしてTraceSource.TraceData()メソッドに渡します。 トレース内容をカスタマイズする場合は、これらのクラスを使うことができます。
+

          
+
#code(cs,カスタマイズしたトレースリスナを使う例){{
+
using System;
+
using System.Diagnostics;
+
using System.Text;
+

          
+
using Smdn.Net;
+
using Smdn.Net.MessageAccessProtocols.Diagnostics;
+
using Smdn.Net.Imap4.Protocol.Client;
+

          
+
public class CustomTraceListener : TraceListener {
+
  public CustomTraceListener(string name)
+
    : base(name)
+
  {
+
  }
+

          
+
  public override void TraceData(TraceEventCache eventCache, string source, TraceEventType eventType, int id, object data)
+
  {
+
    if (data is ReceiveTraceData) {
+
      var received = data as ReceiveTraceData;
+
      var recv = Encoding.ASCII.GetString(received.Data.Array, received.Data.Offset, received.Data.Count);
+

          
+
      Write("受信内容:\t");
+
      WriteLine(recv);
+
    }
+
    else if (data is SendTraceData) {
+
      var sent = data as SendTraceData;
+
      var snt = Encoding.ASCII.GetString(sent.Data.Array, sent.Data.Offset, sent.Data.Count);
+

          
+
      Write("送信内容:\t");
+
      WriteLine(snt);
+
    }
+
    else if (data is MessageTraceData) {
+
      WriteLine((data as MessageTraceData).Message);
+
    }
+
    else if (data is ExceptionTraceData) {
+
      WriteLine((data as ExceptionTraceData).Exception);
+
    }
+
    else {
+
      base.TraceData(eventCache, source, eventType, id, data);
+
    }
+
  }
+

          
+
  public override void Write(string message)
+
  {
+
    // TODO
+
  }
+

          
+
  public override void WriteLine(string message)
+
  {
+
    // TODO
+
  }
+
}
+

          
+
public static class Test {
+
  [STAThread]
+
  public static void Main(string[] args) {
+
    // カスタマイズしたトレースリスナを追加
+
    ImapConnection.TraceSource.Listeners.Add(new CustomTraceListener("log"));
+
      :
+
      :
+
  }
+
}
+
}}
+

          
 
#hr
#hr
 

        

        
 
*&aname(ImapClient){ImapClientクラス (Smdn.Net.Imap4.Client.dll)};
*&aname(ImapClient){ImapClientクラス (Smdn.Net.Imap4.Client.dll)};
307,7 231,7
 

        

        
 
/*
/*
 
 * ホスト"imap.example.net"のIMAPデフォルトポート(143)に接続、SSL/TLSは使用しない。
 * ホスト"imap.example.net"のIMAPデフォルトポート(143)に接続、SSL/TLSは使用しない。
~
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はDIGEST-MD5, CRAM-MD5, IMAP LOGINの順に試行。
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はDIGEST-MD5, CRAM-MD5の順に試行。
 
 */
 */
 
var client4 = new ImapClient("imap.example.net", -1, false, null, "*");
var client4 = new ImapClient("imap.example.net", -1, false, null, "*");
 

        

        
317,24 241,11
 
client4.Connect(new NetworkCredential("user", "pass"));
client4.Connect(new NetworkCredential("user", "pass"));
 

        

        
 
/*
/*
+
 * ホスト"imap.example.net"のIMAPデフォルトポート(143)に接続、可能ならSSL/TLSを使用する。
+
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。
+
 * 認証方式はCRAM-MD5, PLAIN, IMAP LOGINの順に試行。 ただしSSL/TLSが使用できない場合、平文による認証を許可しない。
+
 */
+
var client5 = new ImapClient(new Uri("imap://user@imap.example.net/"));
+

          
+
client5.Profile.UseTlsIfAvailable = true;
+
client5.Profile.UsingSaslMechanisms = new[] {"CRAM-MD5", "PLAIN"};
+
client5.Profile.AllowInsecureLogin = false;
+

          
+
client5.Connect(new NetworkCredential("user", "pass"));
+

          
+
/*
 
 * GMailのアカウント"user"にIMAPで接続。 パスワードは"pass"を使用。
 * GMailのアカウント"user"にIMAPで接続。 パスワードは"pass"を使用。
 
 */
 */
~
var client6 = new ImapClient(new Uri("imaps://user@imap.gmail.com/"));
var client5 = new ImapClient(new Uri("imaps://user@imap.gmail.com/"));
 

        

        
~
client6.Connect("pass");
client5.Connect("pass");
 
}}
}}
 

        

        
 
***&aname(ImapClient.certs){証明書の選択と検証};
***&aname(ImapClient.certs){証明書の選択と検証};
719,36 630,7
 
|~メソッド|~解説|~対応するIMAPコマンド|f
|~メソッド|~解説|~対応するIMAPコマンド|f
 

        

        
 
**例外
**例外
~
ImapClientクラスおよびその他のクラスからは以下の例外をスローします。 ここに明記している以外の例外クラス・状況でスローされる場合があります。
(このドキュメントは作成中です)
+

          
+
|*スローする例外と状況
+
|~例外クラス|~状況|~スローする可能性のあるメソッド|h
+
|ImapConnectionException|接続に失敗した|ImapClient.Connect()|
+
|ImapUpgradeConnectionException|SSL/TLSへのアップグレードに失敗した&br;証明書を検証した結果無効と判断した|ImapClient.Connect()|
+
|ImapAuthenticationException|認証に失敗した&br;試行できる認証メカニズムが無い|ImapClient.Connect()|
+
|ImapErrorResponseException|サーバがエラー応答を返した|ImapClientおよび各クラスのメソッド・プロパティ|
+
|ImapProtocolViolationException|プロトコル上不正な操作を行おうとした|ImapClientおよび各クラスのメソッド・プロパティ|
+
|ImapMailboxClosedException|メールボックスが選択されていない、もしくは既に閉じてる状態で操作を行おうとした|ImapOpenedMailboxInfoクラス・ImapMessageInfoクラスの各メソッド・プロパティ|
+
|ImapMessageDeletedException|削除マーク済み(ImapMessageInfo.IsMarkedAsDeletedがtrue)のメッセージに対して操作を行おうとした|ImapMessageInfoクラスの各メソッド・プロパティ|
+
|ImapMailboxNotFoundException|指定された名前のメールボックスが見つからない|ImapClient.GetMailbox()&br;ImapMessageInfo.CopyTo()など|
+
|ImapMessageNotFoundException|指定されたUIDもしくは通番を持つメッセージが存在しない|ImapOpenedMailboxInfo.GetMessageByUid()&br;ImapOpenedMailboxInfo.GetMessageBySequence()|
+
|InvalidOperationException|切断された状態(ImapClient.IsConnectedがfalse)で操作を行おうとした&br;非同期接続中に新たに接続を開始しようとした|ImapClientおよび各クラスのメソッド・プロパティ|
+
|TimeoutException (System)|ImapClient.Timeout, SendTimeout, ReceiveTimeoutプロパティで指定されている時間内に操作が完了しなかった|ImapClientおよび各クラスのメソッド・プロパティ|
+

          
+
それぞれの例外クラスの継承関係は次のとおりです。
+
-System.SystemException
+
--Smdn.Net.Imap4.ImapExcetion
+
---Smdn.Net.Imap4.Protocol.ImapConnectionException
+
----Smdn.Net.Imap4.Protocol.ImapUpgradeConnectionException
+
-----Smdn.Net.Imap4.Protocol.ImapSecureConnectionException
+
---Smdn.Net.Imap4.ImapInvalidOperationException
+
----Smdn.Net.Imap4.ImapErrorResponseException
+
-----Smdn.Net.Imap4.ImapAuthenticationException
+
----Smdn.Net.Imap4.ImapProtocolViolationException
+
-----Smdn.Net.Imap4.Client.ImapMailboxClosedException
+
-----Smdn.Net.Imap4.Client.ImapMessageDeletedException
+
---Smdn.Net.Imap4.Client.ImapMailboxNotFoundException
+
---Smdn.Net.Imap4.Client.ImapMessageNotFoundException
 

        

        
 
**非同期操作・スレッドセーフティ
**非同期操作・スレッドセーフティ
 
現時点で非同期操作をサポートするメソッドは、ImapClient.BeginConnect()/EndConnect()のみです。
現時点で非同期操作をサポートするメソッドは、ImapClient.BeginConnect()/EndConnect()のみです。
803,7 685,6
 
|Credentials|認証時に使用する資格情報(パスワード等)を指定します|
|Credentials|認証時に使用する資格情報(パスワード等)を指定します|
 
|UseTlsIfAvailable|認証を開始する前に、可能ならSSL/TLSへアップグレードするかどうかを指定します|
|UseTlsIfAvailable|認証を開始する前に、可能ならSSL/TLSへアップグレードするかどうかを指定します|
 
|UsingSaslMechanisms|認証時に試行する認証メカニズムを指定します|
|UsingSaslMechanisms|認証時に試行する認証メカニズムを指定します|
+
|AllowInsecureLogin|接続がSSL/TLSで保護されていない場合でも、平文による認証を許可するかどうか指定します|
 

        

        
 
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#ImapWebRequest.certs]]が必要になります。
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#ImapWebRequest.certs]]が必要になります。
 

        

        
847,23 728,11
 
request4.Credentials = new NetworkCredential("user", "pass");
request4.Credentials = new NetworkCredential("user", "pass");
 

        

        
 
/*
/*
~
 * ホスト"imap.example.net"のIMAPデフォルトポート(143)に接続、可能ならSSL/TLSを使用する。
 * GMailのアカウント"user"にIMAPで接続。 パスワードは"pass"を使用。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。
+
 * 認証方式はCRAM-MD5, PLAIN, IMAP LOGINの順に試行。 ただしSSL/TLSが使用できない場合、平文による認証を許可しない。
 
 */
 */
~
var request5 = WebRequest.Create(new Uri("imap://user@imap.example.net/")) as ImapWebRequest;
var request5 = WebRequest.Create(new Uri("imaps://user@imap.gmail.com/"));
 

        

        
+
request5.UseTlsIfAvailable = true;
+
request5.UsingSaslMechanisms = new[] {"CRAM-MD5", "PLAIN"};
+
request5.AllowInsecureLogin = false;
 
request5.Credentials = new NetworkCredential("user", "pass");
request5.Credentials = new NetworkCredential("user", "pass");
+

          
+
/*
+
 * GMailのアカウント"user"にIMAPで接続。 パスワードは"pass"を使用。
+
 */
+
var request6 = WebRequest.Create(new Uri("imaps://user@imap.gmail.com/"));
+

          
+
request6.Credentials = new NetworkCredential("user", "pass");
 
}}
}}
 

        

        
 
***&aname(ImapWebRequest.certs){証明書の選択と検証};
***&aname(ImapWebRequest.certs){証明書の選択と検証};
1007,7 876,6
 
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
 
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にTLSを使用した接続にアップグレードします。|
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にTLSを使用した接続にアップグレードします。|
 
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
+
|AllowInsecureLogin|false|全て(認証時)|接続がSSL/TLSで保護されていない場合でも、平文による認証を許可するかどうか指定します。|
 
|ReadOnly|false|FETCH, SEARCH等|メールボックスを選択する際に、SELECTコマンドの代わりにEXAMINEコマンドを送信するかどうかを指定します。 メッセージに対する操作を行うコマンドを送信する場合に有効になります。 EXAMINEコマンドで選択したメールボックスのメッセージに対する操作の結果はサーバの実装によります。 ReadOnlyがtrueでもDELETEなどのコマンドには影響しません。|
|ReadOnly|false|FETCH, SEARCH等|メールボックスを選択する際に、SELECTコマンドの代わりにEXAMINEコマンドを送信するかどうかを指定します。 メッセージに対する操作を行うコマンドを送信する場合に有効になります。 EXAMINEコマンドで選択したメールボックスのメッセージに対する操作の結果はサーバの実装によります。 ReadOnlyがtrueでもDELETEなどのコマンドには影響しません。|
 
|AllowCreateMailbox|true|COPY|COPYコマンドを送信した際にサーバがレスポンスコードTRYCREATEを返した場合、自動的にメールボックスを作成するかどうかを指定します。 現在の実装では、APPENDコマンドでTRYCREATEが返された場合でもメールボックスは作成せず、常にエラーとなります。|
|AllowCreateMailbox|true|COPY|COPYコマンドを送信した際にサーバがレスポンスコードTRYCREATEを返した場合、自動的にメールボックスを作成するかどうかを指定します。 現在の実装では、APPENDコマンドでTRYCREATEが返された場合でもメールボックスは作成せず、常にエラーとなります。|
 
|DestinationUri|null|COPY, RENAME|COPYの場合はメッセージのコピー先メールボックス名、RENAMEの場合は変更後のメールボックス名を含むURLを指定します。 URLはコピー元・変更前(WebRequest.RequestUri)と同一サーバ、同一ユーザである必要があります。 それ以外の場合、ArgumentExceptionをスローします。|
|DestinationUri|null|COPY, RENAME|COPYの場合はメッセージのコピー先メールボックス名、RENAMEの場合は変更後のメールボックス名を含むURLを指定します。 URLはコピー元・変更前(WebRequest.RequestUri)と同一サーバ、同一ユーザである必要があります。 それ以外の場合、ArgumentExceptionをスローします。|
1049,6 917,7
 

        

        
 
|*ImapWebRequestDefaultsクラスのプロパティ
|*ImapWebRequestDefaultsクラスのプロパティ
 
|~プロパティ|~デフォルト|~解説|h
|~プロパティ|~デフォルト|~解説|h
-
|AnonymousToken|"anonymous"|匿名ユーザでログインする場合に使用されるユーザ名を指定します。|
 
|Subscription|true|ImapWebRequest.Subscriptionプロパティと同様ですが、falseにした場合WebRequest.Methodのデフォルト値が"LSUB"から"LIST"に変わります。|
|Subscription|true|ImapWebRequest.Subscriptionプロパティと同様ですが、falseにした場合WebRequest.Methodのデフォルト値が"LSUB"から"LIST"に変わります。|
 
|ClientID|name=(現在実行中のアセンブリの名前)&br;version=(現在実行中のアセンブリのバージョン)&br;environment=(ランタイムの名前とバージョン)|サーバが&urn2url(urn:ietf:rfc:2971){ID extension};をサポートしている場合に送信されるIDを指定します。|
|ClientID|name=(現在実行中のアセンブリの名前)&br;version=(現在実行中のアセンブリのバージョン)&br;environment=(ランタイムの名前とバージョン)|サーバが&urn2url(urn:ietf:rfc:2971){ID extension};をサポートしている場合に送信されるIDを指定します。|
 

        

        
1087,8 956,8
 
      <add key="useTlsIfAvailable" value="true"/>
      <add key="useTlsIfAvailable" value="true"/>
 
      <add key="keepAlive" value="true"/>
      <add key="keepAlive" value="true"/>
 
      <add key="readOnly" value="false"/>
      <add key="readOnly" value="false"/>
-
      <add key="anonymousToken" value="anonymous"/>
 
      <add key="usingSaslMechanisms" value="DIGEST-MD5, CRAM-MD5, NTLM"/>
      <add key="usingSaslMechanisms" value="DIGEST-MD5, CRAM-MD5, NTLM"/>
+
      <add key="allowInsecureLogin" value="false"/>
 
      <add key="expectedErrorResponseCodes" value="ALREADYEXISTS, NONEXISTENT"/>
      <add key="expectedErrorResponseCodes" value="ALREADYEXISTS, NONEXISTENT"/>
 
      <add key="clientID" value="name=MyImapClient, support-url=http://imap.example.net/support/"/>
      <add key="clientID" value="name=MyImapClient, support-url=http://imap.example.net/support/"/>
 
    </webRequestDefaults>
    </webRequestDefaults>
1099,11 968,12
 
記述内容については&msdn(netfx,id,dacty7ed){ネットワーク設定スキーマ};および&msdn(netfx,id,0hyxd0xc){構成セクション スキーマ};も合わせて参照してください。
記述内容については&msdn(netfx,id,dacty7ed){ネットワーク設定スキーマ};および&msdn(netfx,id,0hyxd0xc){構成セクション スキーマ};も合わせて参照してください。
 

        

        
 
**例外
**例外
~
ImapWebRequestからは&msdn(netfx,type,System.Net.WebException);または&msdn(netfx,type,System.Net.ProtocolViolationException);をスローします。 WebExceptionをスローする場合は、エラーの状況によりWebException.StatusプロパティとInnerExceptionプロパティに値が設定されます。 また、サーバがエラー応答を返した場合は、Responseプロパティも設定されます。
(このドキュメントは作成中です)
+
InnerExceptionプロパティに設定される例外クラスについては、[[例外>#exception]]を参照してください。
 

        

        
 
**非同期操作・スレッドセーフティ
**非同期操作・スレッドセーフティ
~
WebRequestから継承されるBeginGetResponse()/EndGetResponse()メソッドは実装済みのため、これらのメソッドを使って非同期操作を行えます。 ただし、.NET Framework上では、WebClient.OpenReadAsync()、WebClient.Download*Async()などのメソッドを使用した非同期操作は正しく動作しないようなので、現時点では使用できません。
WebRequestから継承されるBeginGetResponse()/EndGetResponse()メソッドは実装済みのため、これらのメソッドを使って非同期操作を行えます。 また、WebClient.OpenReadAsync()、WebClient.Download*Async()などの非同期操作用のメソッドも使用できます。 ただし、現時点では予期しない例外がスローされる場合があるようなので、使用は推奨できません。
-

          
-
(このドキュメントは作成中です)
 

        

        
 
#hr
#hr
 

        

        

works/libs/Smdn.Net.Pop3/doc/index.wiki.txt

current previous
19,7 19,7
 
上記以外は、&urn2url(urn:ietf:rfc:1939,short);および.NET Frameworkの用語に準じます。
上記以外は、&urn2url(urn:ietf:rfc:1939,short);および.NET Frameworkの用語に準じます。
 

        

        
 
*ライブラリの構成
*ライブラリの構成
~
**&aname(assemblies){アセンブリ構成};
**アセンブリ構成
 
本ライブラリはいくつかのアセンブリに分かれています。
本ライブラリはいくつかのアセンブリに分かれています。
 
|*アセンブリに含まれる型と用途
|*アセンブリに含まれる型と用途
 
|~アセンブリ|~含まれる型|h
|~アセンブリ|~含まれる型|h
33,7 33,7
 

        

        
 
本ライブラリを使用する場合は、上記アセンブリへの参照を追加してください(PopWebRequest/PopWebResponseを使用しない場合は、Smdn.Net.Pop3.WebClients.dllへの参照は不要です)。
本ライブラリを使用する場合は、上記アセンブリへの参照を追加してください(PopWebRequest/PopWebResponseを使用しない場合は、Smdn.Net.Pop3.WebClients.dllへの参照は不要です)。
 

        

        
~
**&aname(clients){クライアント実装};
**&name(clients){クライアント実装};
 
クライアントの実装は次の3種類があります。
クライアントの実装は次の3種類があります。
 
|*クライアント実装の種類と概要
|*クライアント実装の種類と概要
 
|~名前空間|~クラス|~概要|~解説|h
|~名前空間|~クラス|~概要|~解説|h
85,7 85,7
 
+APOPコマンド (サーバがサポートしている場合のみ)
+APOPコマンド (サーバがサポートしている場合のみ)
 
+USER/PASSコマンド
+USER/PASSコマンド
 

        

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

        

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

        

        
98,24 98,14
 
|pop://;AUTH=DIGEST-MD5&#x40;pop.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
|pop://;AUTH=DIGEST-MD5&#x40;pop.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
 
|pop://user;AUTH=*&#x40;pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
|pop://user;AUTH=*&#x40;pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
 
|pop://user&#x40;pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
|pop://user&#x40;pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
~
|pop://;AUTH=ANONYMOUS&#x40;pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUS|
|pop://;AUTH=ANONYMOUS&#x40;pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
~
|pop://user&amp;#x40;localhost;AUTH=ANONYMOUS&#x40;pop.example.net/|匿名ユーザ&br;(ログイントークン: user&#x40;localhost)|ANONYMOUS|
|pop://pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはUSER/PASSコマンドを使用|
~
|pop://pop.example.net/|匿名ユーザ&br;(ログイントークン: anonymous@)|ANONYMOUSもしくはUSER/PASSコマンドを使用|

          
~

          
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
+
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。 UsingSaslMechanismsプロパティにANONYMOUSが含まれていても匿名ログインは試行しません。 AllowInsecureLogin&sub{*3};プロパティに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;(試行できる認証方式なし)|
 

        

        
 
これら認証時のパラメータは次の箇所で指定します。
これら認証時のパラメータは次の箇所で指定します。
 
:ICredentialsByHostインターフェイス&sup{*1};|[[PopClient.Connect()メソッド>#PopClient.login]]に指定する引数credentials、もしくは[[PopWebRequest.Credentialsプロパティ>#PopWebRequest.login]]
:ICredentialsByHostインターフェイス&sup{*1};|[[PopClient.Connect()メソッド>#PopClient.login]]に指定する引数credentials、もしくは[[PopWebRequest.Credentialsプロパティ>#PopWebRequest.login]]
 
:UsingSaslMechanismsプロパティ&sup{*2};|[[PopClient.Profile.UsingSaslMechanismsプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.UsingSaslMechanismsプロパティ>#PopWebRequest.login]]
:UsingSaslMechanismsプロパティ&sup{*2};|[[PopClient.Profile.UsingSaslMechanismsプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.UsingSaslMechanismsプロパティ>#PopWebRequest.login]]
+
:AllowInsecureLoginプロパティ&sup{*3};|[[PopClient.Profile.AllowInsecureLoginプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.AllowInsecureLoginプロパティ>#PopWebRequest.login]]
+

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

        

        
 
***&aname(creds){資格情報};
***&aname(creds){資格情報};
 
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
認証時に必要なユーザ名・パスワードは&msdn(netfx,type,System.Net.ICredentialsByHost);インターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切な&msdn(netfx,type,System.Net.NetworkCredential);を返すクラスなら何でも設定できます。
139,10 129,9
 
ライブラリからは主に以下の例外をスローします。 InnerExceptionプロパティに原因となった例外を設定した状態でスローする場合もあります。
ライブラリからは主に以下の例外をスローします。 InnerExceptionプロパティに原因となった例外を設定した状態でスローする場合もあります。
 
|*ライブラリがスローする例外
|*ライブラリがスローする例外
 
|~例外クラス|~スローされる状況|h
|~例外クラス|~スローされる状況|h
~
|PopInvalidOperationException&br;および派生クラス (Smdn.Net.Pop3)|プロトコル上不正な操作を行おうとした場合&br;認証に失敗した場合はPopAuthenticationException&br;サーバに不正な要求を行おうとした場合はPopProtocolViolationException&br;サーバがエラー応答を返した場合はPopErrorResponseException|
|PopInvalidOperationException&br;および派生クラス (Smdn.Net.Pop3)|プロトコル上不正な操作を行おうとした場合&br;サーバに不正な要求を行おうとした場合はPopProtocolViolationException&br;サーバがエラー応答を返した場合はPopErrorResponseException|
 
|PopConnectionException&br;および派生クラス (Smdn.Net.Pop3.Protocol)|接続に失敗した場合、ソケットエラーが発生した場合など&br;SSL/TLSに起因するエラーの場合はPopUpgradeConnectionException|
|PopConnectionException&br;および派生クラス (Smdn.Net.Pop3.Protocol)|接続に失敗した場合、ソケットエラーが発生した場合など&br;SSL/TLSに起因するエラーの場合はPopUpgradeConnectionException|
 
|TimeoutException (System)|ソケット送受信中やコマンド処理中にタイムアウトした場合|
|TimeoutException (System)|ソケット送受信中やコマンド処理中にタイムアウトした場合|
+
|InvalidOperationException (System)|現在のクライアントの状態に対して無効な操作を行おうとした場合|
 
|ArgumentException&br;および派生クラス (System)|nullや値域外の値など、メソッド呼び出し時の引数が不正な場合|
|ArgumentException&br;および派生クラス (System)|nullや値域外の値など、メソッド呼び出し時の引数が不正な場合|
 
|WebException&br;またはProtocolViolationException (System.Net)|Smdn.Net.Pop3.WebClients名前空間で発生した例外は、これらの例外に変換した上でスローされます|
|WebException&br;またはProtocolViolationException (System.Net)|Smdn.Net.Pop3.WebClients名前空間で発生した例外は、これらの例外に変換した上でスローされます|
 

        

        
185,73 174,6
 

        

        
 
なお、SSL/TLSを使用しているかどうかに関わらず、ログには''パスワードを含む内容を平文で''出力します。 ログの出力が不要な場合はTRACEを無効にしてリビルドするか、Trace.csなどを削除してください。
なお、SSL/TLSを使用しているかどうかに関わらず、ログには''パスワードを含む内容を平文で''出力します。 ログの出力が不要な場合はTRACEを無効にしてリビルドするか、Trace.csなどを削除してください。
 

        

        
+
***トレース内容のカスタマイズ
+
トレースにログを出力する際、出力内容はSmdn.Net.MessageAccessProtocols.Diagnosticsの各クラスのインスタンスとしてTraceSource.TraceData()メソッドに渡します。 トレース内容をカスタマイズする場合は、これらのクラスを使うことができます。
+

          
+
#code(cs,カスタマイズしたトレースリスナを使う例){{
+
using System;
+
using System.Diagnostics;
+
using System.Text;
+

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

          
+
public class CustomTraceListener : TraceListener {
+
  public CustomTraceListener(string name)
+
    : base(name)
+
  {
+
  }
+

          
+
  public override void TraceData(TraceEventCache eventCache, string source, TraceEventType eventType, int id, object data)
+
  {
+
    if (data is ReceiveTraceData) {
+
      var received = data as ReceiveTraceData;
+
      var recv = Encoding.ASCII.GetString(received.Data.Array, received.Data.Offset, received.Data.Count);
+

          
+
      Write("受信内容:\t");
+
      WriteLine(recv);
+
    }
+
    else if (data is SendTraceData) {
+
      var sent = data as SendTraceData;
+
      var snt = Encoding.ASCII.GetString(sent.Data.Array, sent.Data.Offset, sent.Data.Count);
+

          
+
      Write("送信内容:\t");
+
      WriteLine(snt);
+
    }
+
    else if (data is MessageTraceData) {
+
      WriteLine((data as MessageTraceData).Message);
+
    }
+
    else if (data is ExceptionTraceData) {
+
      WriteLine((data as ExceptionTraceData).Exception);
+
    }
+
    else {
+
      base.TraceData(eventCache, source, eventType, id, data);
+
    }
+
  }
+

          
+
  public override void Write(string message)
+
  {
+
    // TODO
+
  }
+

          
+
  public override void WriteLine(string message)
+
  {
+
    // TODO
+
  }
+
}
+

          
+
public static class Test {
+
  [STAThread]
+
  public static void Main(string[] args) {
+
    // カスタマイズしたトレースリスナを追加
+
    PopConnection.TraceSource.Listeners.Add(new CustomTraceListener("log"));
+
      :
+
      :
+
  }
+
}
+
}}
+

          
 
#hr
#hr
 

        

        
 
*&aname(PopClient){PopClientクラス (Smdn.Net.Pop3.Client.dll)};
*&aname(PopClient){PopClientクラス (Smdn.Net.Pop3.Client.dll)};
299,7 221,7
 

        

        
 
/*
/*
 
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、SSL/TLSは使用しない。
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、SSL/TLSは使用しない。
~
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はDIGEST-MD5, CRAM-MD5, APOP, USER/PASSの順に試行。
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はDIGEST-MD5, CRAM-MD5, APOPの順に試行。
 
 */
 */
 
var client4 = new PopClient("pop.example.net", -1, false, null, "*");
var client4 = new PopClient("pop.example.net", -1, false, null, "*");
 

        

        
309,24 231,11
 
client4.Connect(new NetworkCredential("user", "pass"));
client4.Connect(new NetworkCredential("user", "pass"));
 

        

        
 
/*
/*
+
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、可能ならSSL/TLSを使用する。
+
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。
+
 * 認証方式はCRAM-MD5, PLAIN, APOP, USER/PASSの順に試行。 ただしSSL/TLSが使用できない場合、平文による認証を許可しない。
+
 */
+
var client5 = new PopClient(new Uri("pop://user@pop.example.net/"));
+

          
+
client5.Profile.UseTlsIfAvailable = true;
+
client5.Profile.UsingSaslMechanisms = new[] {"CRAM-MD5", "PLAIN"};
+
client5.Profile.AllowInsecureLogin = false;
+

          
+
client5.Connect(new NetworkCredential("user", "pass"));
+

          
+
/*
 
 * GMailのアカウント"user"にPOPで接続。 パスワードは"pass"を使用。
 * GMailのアカウント"user"にPOPで接続。 パスワードは"pass"を使用。
 
 */
 */
~
var client6 = new PopClient(new Uri("pops://user@pop.gmail.com/"));
var client5 = new PopClient(new Uri("pops://user@pop.gmail.com/"));
 

        

        
~
client6.Connect("pass");
client5.Connect("pass");
 
}}
}}
 

        

        
 
***&aname(PopClient.certs){証明書の選択と検証};
***&aname(PopClient.certs){証明書の選択と検証};
496,12 405,10
 
|~例外クラス|~状況|~スローする可能性のあるメソッド|h
|~例外クラス|~状況|~スローする可能性のあるメソッド|h
 
|PopConnectionException|接続に失敗した|PopClient.Connect()|
|PopConnectionException|接続に失敗した|PopClient.Connect()|
 
|PopUpgradeConnectionException|SSL/TLSへのアップグレードに失敗した&br;証明書を検証した結果無効と判断した|PopClient.Connect()|
|PopUpgradeConnectionException|SSL/TLSへのアップグレードに失敗した&br;証明書を検証した結果無効と判断した|PopClient.Connect()|
+
|PopAuthenticationException|認証に失敗した&br;試行できる認証メカニズムが無い|PopClient.Connect()|
 
|PopErrorResponseException|サーバがエラー応答を返した|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
|PopErrorResponseException|サーバがエラー応答を返した|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
~
|PopProtocolViolationException|プロトコル上不正な操作を行おうとした|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
|PopProtocolViolationException|切断された状態(PopClient.IsConnectedがfalse)で操作を行おうとした&br;その他プロトコル上不正な操作を行おうとした|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
 
|PopMessageDeletedException|削除マーク済み(PopMessageInfo.IsMarkedAsDeletedがtrue)のメッセージに対して操作を行おうとした|PopClient.GetMessage()&br;PopMessageInfoの各メソッド・プロパティ|
|PopMessageDeletedException|削除マーク済み(PopMessageInfo.IsMarkedAsDeletedがtrue)のメッセージに対して操作を行おうとした|PopClient.GetMessage()&br;PopMessageInfoの各メソッド・プロパティ|
 
|PopMessageNotFoundException|指定された番号もしくはIDを持つメッセージが存在しない|PopClient.GetMessage()&br;PopClient.GetMessages()|
|PopMessageNotFoundException|指定された番号もしくはIDを持つメッセージが存在しない|PopClient.GetMessage()&br;PopClient.GetMessages()|
+
|InvalidOperationException|切断された状態(PopClient.IsConnectedがfalse)で操作を行おうとした&br;非同期接続中に新たに接続を開始しようとした|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
 
|TimeoutException (System)|PopClient.Timeout, SendTimeout, ReceiveTimeoutプロパティで指定されている時間内に操作が完了しなかった|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
|TimeoutException (System)|PopClient.Timeout, SendTimeout, ReceiveTimeoutプロパティで指定されている時間内に操作が完了しなかった|PopClientおよびPopMessageInfoの各メソッド・プロパティ|
 

        

        
 
それぞれの例外クラスの継承関係は次のとおりです。
それぞれの例外クラスの継承関係は次のとおりです。
511,7 418,6
 
----Smdn.Net.Pop3.Protocol.PopUpgradeConnectionException
----Smdn.Net.Pop3.Protocol.PopUpgradeConnectionException
 
---Smdn.Net.Pop3.PopInvalidOperationException
---Smdn.Net.Pop3.PopInvalidOperationException
 
----Smdn.Net.Pop3.PopErrorResponseException
----Smdn.Net.Pop3.PopErrorResponseException
+
-----Smdn.Net.Pop3.PopAuthenticationException
 
----Smdn.Net.Pop3.PopProtocolViolationException
----Smdn.Net.Pop3.PopProtocolViolationException
 
-----Smdn.Net.Pop3.Client.PopMessageDeletedException
-----Smdn.Net.Pop3.Client.PopMessageDeletedException
 
---Smdn.Net.Pop3.Client.PopMessageNotFoundException
---Smdn.Net.Pop3.Client.PopMessageNotFoundException
569,7 475,6
 
|Credentials|認証時に使用する資格情報(パスワード等)を指定します|
|Credentials|認証時に使用する資格情報(パスワード等)を指定します|
 
|UseTlsIfAvailable|認証を開始する前に、可能ならSSL/TLSへアップグレードするかどうかを指定します|
|UseTlsIfAvailable|認証を開始する前に、可能ならSSL/TLSへアップグレードするかどうかを指定します|
 
|UsingSaslMechanisms|認証時に試行する認証メカニズムを指定します|
|UsingSaslMechanisms|認証時に試行する認証メカニズムを指定します|
+
|AllowInsecureLogin|接続がSSL/TLSで保護されていない場合でも、平文またはAPOPによる認証を許可するかどうか指定します|
 

        

        
 
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#PopWebRequest.certs]]が必要になります。
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#PopWebRequest.certs]]が必要になります。
 

        

        
604,7 509,7
 

        

        
 
/*
/*
 
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、SSL/TLSは使用しない。
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、SSL/TLSは使用しない。
~
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はDIGEST-MD5, CRAM-MD5, APOP, USER/PASSの順に試行。
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はDIGEST-MD5, CRAM-MD5, APOPの順に試行。
 
 */
 */
 
var request4 = WebRequest.Create(new Uri("pop://;AUTH=*@pop.example.net/")) as PopWebRequest;
var request4 = WebRequest.Create(new Uri("pop://;AUTH=*@pop.example.net/")) as PopWebRequest;
 

        

        
613,23 518,11
 
request4.Credentials = new NetworkCredential("user", "pass");
request4.Credentials = new NetworkCredential("user", "pass");
 

        

        
 
/*
/*
~
 * ホスト"pop.example.net"のPOPデフォルトポート(110)に接続、可能ならSSL/TLSを使用する。
 * GMailのアカウント"user"にPOPで接続。 パスワードは"pass"を使用。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。
+
 * 認証方式はCRAM-MD5, PLAIN, APOP, USER/PASSの順に試行。 ただしSSL/TLSが使用できない場合、平文による認証を許可しない。
 
 */
 */
~
var request5 = WebRequest.Create(new Uri("pop://user@pop.example.net/")) as PopWebRequest;
var request5 = WebRequest.Create(new Uri("pops://user@pop.gmail.com/"));
 

        

        
+
request5.UseTlsIfAvailable = true;
+
request5.UsingSaslMechanisms = new[] {"CRAM-MD5", "PLAIN"};
+
request5.AllowInsecureLogin = false;
 
request5.Credentials = new NetworkCredential("user", "pass");
request5.Credentials = new NetworkCredential("user", "pass");
+

          
+
/*
+
 * GMailのアカウント"user"にPOPで接続。 パスワードは"pass"を使用。
+
 */
+
var request6 = WebRequest.Create(new Uri("pops://user@pop.gmail.com/"));
+

          
+
request6.Credentials = new NetworkCredential("user", "pass");
 
}}
}}
 

        

        
 
***&aname(PopWebRequest.certs){証明書の選択と検証};
***&aname(PopWebRequest.certs){証明書の選択と検証};
737,7 630,6
 
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
 
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にSSL/TLSを使用した接続にアップグレードします。|
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にSSL/TLSを使用した接続にアップグレードします。|
 
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
+
|AllowInsecureLogin|false|全て(認証時)|接続がSSL/TLSで保護されていない場合でも、平文またはAPOPによる認証を許可するかどうか指定します。|
 
|DeleteAfterRetrieve|false|RETR|RETRコマンドでのメッセージの受信が成功した場合、同じメッセージに対して自動的にDELEコマンドを発行します。|
|DeleteAfterRetrieve|false|RETR|RETRコマンドでのメッセージの受信が成功した場合、同じメッセージに対して自動的にDELEコマンドを発行します。|
 
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
 

        

        
751,7 643,11
 
***PopWebRequestクラスのデフォルト値の変更
***PopWebRequestクラスのデフォルト値の変更
 
PopWebRequestDefaultsクラスのプロパティの値を変更することにより、PopWebRequestクラスのプロパティに設定されるデフォルト値を一括して指定することができます。 全てのリクエストでデフォルトの値を変更したい場合は、PopWebRequestDefaultsクラスのプロパティの値を変更してください。
PopWebRequestDefaultsクラスのプロパティの値を変更することにより、PopWebRequestクラスのプロパティに設定されるデフォルト値を一括して指定することができます。 全てのリクエストでデフォルトの値を変更したい場合は、PopWebRequestDefaultsクラスのプロパティの値を変更してください。
 

        

        
~
PopWebRequestDefaultsクラスにはPopWebRequestプロパティと同名のプロパティを用意してあります。
PopWebRequestDefaultsクラスにはPopWebRequestプロパティと同名のプロパティを用意してありますが、以下の一覧にあるプロパティはPopWebRequestでは設定できないプロパティです。
-

          
-
|*PopWebRequestDefaultsクラスのプロパティ
-
|~プロパティ|~デフォルト|~解説|h
-
|AnonymousToken|"anonymous"|匿名ユーザでログインする場合に使用されるユーザ名を指定します。|
 

        

        
 
**アプリケーション構成ファイルでの設定
**アプリケーション構成ファイルでの設定
 
アプリケーション構成ファイルを記述することにより、pop, popsスキームの登録と、PopWebRequestDefaultsクラスのデフォルト値を変更することができます。 コード上での変更をしたくない場合、する必要がない場合などは、アプリケーション構成ファイルに設定を記述することができます。 以下はアプリケーション構成ファイルの記述例です。
アプリケーション構成ファイルを記述することにより、pop, popsスキームの登録と、PopWebRequestDefaultsクラスのデフォルト値を変更することができます。 コード上での変更をしたくない場合、する必要がない場合などは、アプリケーション構成ファイルに設定を記述することができます。 以下はアプリケーション構成ファイルの記述例です。
780,8 676,8
 
      <add key="useTlsIfAvailable" value="true"/>
      <add key="useTlsIfAvailable" value="true"/>
 
      <add key="deleteAfterRetrieve" value="false"/>
      <add key="deleteAfterRetrieve" value="false"/>
 
      <add key="keepAlive" value="true"/>
      <add key="keepAlive" value="true"/>
-
      <add key="anonymousToken" value="anonymous"/>
 
      <add key="usingSaslMechanisms" value="DIGEST-MD5, CRAM-MD5, NTLM"/>
      <add key="usingSaslMechanisms" value="DIGEST-MD5, CRAM-MD5, NTLM"/>
+
      <add key="allowInsecureLogin" value="false"/>
 
      <add key="expectedErrorResponseCodes" value="SYS/TEMP"/>
      <add key="expectedErrorResponseCodes" value="SYS/TEMP"/>
 
    </webRequestDefaults>
    </webRequestDefaults>
 
  </smdn.net.pop3.client>
  </smdn.net.pop3.client>
791,11 687,12
 
記述内容については&msdn(netfx,id,dacty7ed){ネットワーク設定スキーマ};および&msdn(netfx,id,0hyxd0xc){構成セクション スキーマ};も合わせて参照してください。
記述内容については&msdn(netfx,id,dacty7ed){ネットワーク設定スキーマ};および&msdn(netfx,id,0hyxd0xc){構成セクション スキーマ};も合わせて参照してください。
 

        

        
 
**例外
**例外
~
PopWebRequestからは&msdn(netfx,type,System.Net.WebException);または&msdn(netfx,type,System.Net.ProtocolViolationException);をスローします。 WebExceptionをスローする場合は、エラーの状況によりWebException.StatusプロパティとInnerExceptionプロパティに値が設定されます。 また、サーバがエラー応答を返した場合は、Responseプロパティも設定されます。
(このドキュメントは作成中です)
+
InnerExceptionプロパティに設定される例外クラスについては、[[例外>#exception]]を参照してください。
 

        

        
 
**非同期操作・スレッドセーフティ
**非同期操作・スレッドセーフティ
~
WebRequestから継承されるBeginGetResponse()/EndGetResponse()メソッドは実装済みのため、これらのメソッドを使って非同期操作を行えます。 ただし、.NET Framework上では、WebClient.OpenReadAsync()、WebClient.Download*Async()などのメソッドを使用した非同期操作は正しく動作しないようなので、現時点では使用できません。
WebRequestから継承されるBeginGetResponse()/EndGetResponse()メソッドは実装済みのため、これらのメソッドを使って非同期操作を行えます。 また、WebClient.OpenReadAsync()、WebClient.Download*Async()などの非同期操作用のメソッドも使用できます。 ただし、現時点では予期しない例外がスローされる場合があるようなので、使用は推奨できません。
-

          
-
(このドキュメントは作成中です)
 

        

        
 
#hr
#hr