2010-04-18T17:36:40の更新内容

works/tools/junk/TundereBird/index.wiki.txt

current previous
21,13 21,6
 
-開発版
-開発版
 
--[[anonsvn]]よりチェックアウトできます
--[[anonsvn]]よりチェックアウトできます
 
-0.3x
-0.3x
+
--${smdncms:distfilelink,TundereBird-0.31.tar.bz2}
+
---下記ライブラリのソースを同梱しています
+
----[[works/libs/Smdn.Net.Imap4]] 0.31
+
----[[works/libs/Smdn.Net.Pop3]] 0.91
+
----[[works/libs/Smdn.Security.Authentication.Sasl]] 0.28
+
----[[works/libs/Smdn.Formats.Mime]] 0.19
+
----[[works/libs/Smdn.Formats.Ini]] 0.17
 
--${smdncms:distfilelink,TundereBird-0.30.tar.bz2}
--${smdncms:distfilelink,TundereBird-0.30.tar.bz2}
 
---下記ライブラリのソースを同梱しています
---下記ライブラリのソースを同梱しています
 
----[[works/libs/Smdn.Net.Imap4]] 0.30
----[[works/libs/Smdn.Net.Imap4]] 0.30
136,10 129,6
 
不具合の報告、ライブラリに対する要望や提案、使い方の質問などは[[掲示板>misc/forum/libs]]へどうぞ。
不具合の報告、ライブラリに対する要望や提案、使い方の質問などは[[掲示板>misc/forum/libs]]へどうぞ。
 

                

                
 
*変更履歴
*変更履歴
+
**0.31 (2010-04-18)
+
-修正・改善
+
--ライブラリのインターフェイス変更にあわせて実装を修正
+

                  
 
**0.30 (2010-04-04)
**0.30 (2010-04-04)
 
-機能追加
-機能追加
 
--TungireBird
--TungireBird

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

current previous
4,7 4,6
 

                

                
 
*リリース一覧
*リリース一覧
 
-0.3x
-0.3x
+
--${smdncms:distfilelink,../Smdn.Net.Imap4.Client-0.31.tar.bz2}
 
--${smdncms:distfilelink,../Smdn.Net.Imap4.Client-0.30.tar.bz2}
--${smdncms:distfilelink,../Smdn.Net.Imap4.Client-0.30.tar.bz2}
 
-0.2x
-0.2x
 
--${smdncms:distfilelink,../Smdn.Net.Imap4.Client-0.29.tar.bz2}
--${smdncms:distfilelink,../Smdn.Net.Imap4.Client-0.29.tar.bz2}
23,28 22,6
 
0.20以降はMIT X11ライセンスでのリリースとなります。 0.20より前のバージョンについては特に使用条件を定めていません。
0.20以降はMIT X11ライセンスでのリリースとなります。 0.20より前のバージョンについては特に使用条件を定めていません。
 

                

                
 
*変更履歴
*変更履歴
+
**0.31 (2010-04-18)
+
主に若干のパフォーマンス改善、実装の細かい修正等。
+
-機能追加
+
--ImapClient
+
---ImapMessageInfo.WriteTo(Stream)を追加
+
---コンストラクタでもSSL/TLSを用いた接続を使用するかどうか、およびタイムアウト時間を指定できるようにした
+
-修正・改善
+
--上位ライブラリのインターフェイス変更にあわせて実装を修正
+
--StringComparerの指定があいまいだった部分で明示的に指定するようにした
+
--ImapSession.ServerIDのComparerをStringComparer.OrdinalIgnoreCaseに変更
+
--例外を再スローしている箇所でスタックトレースを破棄しないように修正
+
--例外クラスのインターフェイスをカスタム例外のガイドラインに適合するように改善 (一部未完)
+
--いくつかの冗長な内部処理をデバッグ時のみ有効になるように修正
+
--.NET Framework 2.0 SP2以前などの環境でMissingMethodExceptionがスローされないようにメソッド呼び出しを修正
+
--ImapClient
+
---コンストラクタのauthTypeに指定した値が無視されていたのを修正
+
---ImapMessageInfo.Save()がArgumentExceptionをスローする場合、空のファイルが作成されないようにした
+
---動的属性を取得していない状態でImapMessageInfo.ToggleFlags(), ToggleKeywords()を呼び出そうとするとNullReferenceExceptionがスローされる不具合を修正
+
--WebClients
+
---ImapWebRequestDefaults.ClientIDのComparerをStringComparer.OrdinalIgnoreCaseに変更
+
---ImapWebResponse.ServerIDをIDictionaryに変更、常にread-onlyな同一インスタンスを返すようにした
+

                  
 
**0.30 (2010-04-04)
**0.30 (2010-04-04)
 
主にImapClientの機能強化・テストケースの追加と細かい修正等。
主にImapClientの機能強化・テストケースの追加と細かい修正等。
 

                

                

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

current previous
39,7 39,7
 

                

                
 
本ライブラリはMIT X11ライセンスでのリリースとなります。
本ライブラリはMIT X11ライセンスでのリリースとなります。
 

                

                
~
:最新版|${smdncms:distfilelink,Smdn.Net.Imap4.Client-0.31.tar.bz2}
:最新版|${smdncms:distfilelink,Smdn.Net.Imap4.Client-0.30.tar.bz2}
 
:開発版|[[anonsvn]]よりチェックアウトできます
:開発版|[[anonsvn]]よりチェックアウトできます
 

                

                
 
デモ用アプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。
デモ用アプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。

works/libs/Smdn.Formats.Mime/index.wiki.txt

current previous
21,7 21,6
 
-開発版
-開発版
 
--[[anonsvn]]よりチェックアウトできます
--[[anonsvn]]よりチェックアウトできます
 
-0.1x
-0.1x
+
--${smdncms:distfilelink,Smdn.Formats.Mime-0.19.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Formats.Mime-0.18.tar.bz2}
--${smdncms:distfilelink,Smdn.Formats.Mime-0.18.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Formats.Mime-0.17.tar.bz2}
--${smdncms:distfilelink,Smdn.Formats.Mime-0.17.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Formats.Mime-0.16.tar.bz2}
--${smdncms:distfilelink,Smdn.Formats.Mime-0.16.tar.bz2}
78,10 77,6
 
本ライブラリを使用したサンプルアプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。
本ライブラリを使用したサンプルアプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。
 

                

                
 
*変更履歴
*変更履歴
+
**0.19 (2010-04-18)
+
-修正・改善
+
--上位ライブラリのインターフェイス変更にあわせて実装を修正
+

                  
 
**0.18 (2010-03-22)
**0.18 (2010-03-22)
 
-修正・改善
-修正・改善
 
--StringComparison.Ordinal*の動作を期待していた箇所でInvariantCulture*を使用していたのを修正
--StringComparison.Ordinal*の動作を期待していた箇所でInvariantCulture*を使用していたのを修正

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

current previous
4,7 4,6
 

                

                
 
*リリース一覧
*リリース一覧
 
-0.9x
-0.9x
+
--${smdncms:distfilelink,../Smdn.Net.Pop3.Client-0.91.tar.bz2}
 
--${smdncms:distfilelink,../Smdn.Net.Pop3.Client-0.90.tar.bz2}
--${smdncms:distfilelink,../Smdn.Net.Pop3.Client-0.90.tar.bz2}
 
-0.2x
-0.2x
 
--${smdncms:distfilelink,../Smdn.Net.Pop3.Client-0.29.tar.bz2}
--${smdncms:distfilelink,../Smdn.Net.Pop3.Client-0.29.tar.bz2}
21,25 20,6
 
0.20以降はMIT X11ライセンスでのリリースとなります。 0.20より前のバージョンについては特に使用条件を定めていません。
0.20以降はMIT X11ライセンスでのリリースとなります。 0.20より前のバージョンについては特に使用条件を定めていません。
 

                

                
 
*変更履歴
*変更履歴
+
**0.91 (2010-04-18)
+
主に若干のパフォーマンス改善、実装の細かい修正等。
+

                  
+
-機能追加
+
--PopClient
+
---PopMessageInfo.WriteTo(Stream)を追加
+
---コンストラクタでもSSL/TLSを用いた接続を使用するかどうか、およびタイムアウト時間を指定できるようにした
+
-修正・改善
+
--StringComparerの指定があいまいだった部分で明示的に指定するようにした
+
--上位ライブラリのインターフェイス変更にあわせて実装を修正
+
--例外を再スローしている箇所でスタックトレースを破棄しないように修正
+
--例外クラスのインターフェイスをカスタム例外のガイドラインに適合するように改善 (一部未完)
+
--いくつかの冗長な内部処理をデバッグ時のみ有効になるように修正
+
--.NET Framework 2.0 SP2以前などの環境でMissingMethodExceptionがスローされないようにメソッド呼び出しを修正
+
--PopClient
+
---コンストラクタのauthTypeに指定した値が無視されていたのを修正
+
---PopMessageInfo.Save()がArgumentExceptionをスローする場合、空のファイルが作成されないようにした
+
---接続していない状態でPopClient.MessageCountおよびPopClient.TotalSizeプロパティを参照しようとした場合、PopProtocolViolationExceptionをスローするようにした
+

                  
 
**0.90 (2010-04-04)
**0.90 (2010-04-04)
 
主にPopClientの機能強化・テストケースの追加と細かい修正等。
主にPopClientの機能強化・テストケースの追加と細かい修正等。
 

                

                

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

current previous
1,615 1,237
 
${smdncms:title,ドキュメント・サンプル}
${smdncms:title,ドキュメント・サンプル}
 
${smdncms:keywords,}
${smdncms:keywords,}
~
${smdncms:parser_options,non-limited-list}
[[works/libs/Smdn.Net.Pop3]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.27時点のもので、記載不備などがあるかもしれません。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
+
[[works/libs/Smdn.Net.Pop3]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.91時点のもので、記載不備などがあるかもしれません。
 

                

                
~
サンプルコードは[[このページの最後>#samples]]にあります。 ご質問などありましたら[[掲示板>misc/forum/libs]]へどうぞ。
*使用例
-
個々のサンプルの詳細については、後述するSmdn.Net.Pop3.WebClients名前空間およびSmdn.Net.Pop3.Client名前空間の説明を参照してください。
 

                

                
~
*用語と表記
**メッセージのダウンロード
~
このドキュメントでは、以下の表記を用いています。
localhostのメールボックスから1番目のメッセージをダウンロードし、sample.emlとして保存するサンプル。 ログインユーザ名にuser、パスワードにpassを使用し、認証方式にDIGEST-MD5を使用。
~
:メッセージ|POPサーバ上のメールボックスにある個々のメールの本文または/および属性を表す意味で用いています。
#code(cs,WebClientクラスを使う場合){{
~
:メッセージ本文|POPサーバ上のメールボックスにある個々のメールの本文のみを表す意味で用いています。
using System;
~
:SSL/TLS|SSLおよびTLSを特に区別なく表す場合、SSL/TLSと表記しています。
using System.Net;
+
:認証方式|認証に用いるメカニズムを表す意味で用いています。 ほとんどの場合、&urn2url(urn:ietf:rfc:2222){SASLメカニズム};を表す意味で用いていますが、場合によってはPOP標準の平文による認証も含みます。
+
:クライアント|ほとんどの場合、本ライブラリに含まれるクライアント実装を表す意味で用いていますが、場合によっては一般的なPOPクライアントを含みます。
+
:一覧|リスト(IList)・コレクション(ICollection)・その他の集合(IEnumerable等)を表す意味で用いている場合があります。
+

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

                  
+
*ライブラリの構成
+
**アセンブリ構成
+
本ライブラリはいくつかのアセンブリに分かれています。
+
|*アセンブリに含まれる型と用途
+
|~アセンブリ|~含まれる型|h
+
|Smdn.dll|他のアセンブリで共通して使用される型、ユーティリティクラス、.NET Framework 4.x, 3.x互換の型など|
+
|Smdn.Core.Standards.dll|MIMEエンコード/デコード、URLエンコード/デコード等の標準に関するクラス群|
+
|Smdn.Net.MessageAccessProtocols.dll|[[works/libs/Smdn.Net.Pop3]]および[[works/libs/Smdn.Net.Imap4]]で共通して使用されるクラス群|
+
|Smdn.Security.Authentication.Sasl.dll|[[works/libs/Smdn.Security.Authentication.Sasl]](SASLクライアントの実装)|
+
|Smdn.Net.Pop3.dll|POP3で使用される基本型等の定義|
+
|Smdn.Net.Pop3.Client.dll|[[PopClient>#PopClient]], [[PopSession>#PopSession]]を含むPOP3クライアント実装|
+
|Smdn.Net.Pop3.WebClients.dll|[[PopWebRequest/PopWebResponse>#PopWebRequest]]を含むPOP3クライアント実装|
+

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

                  
+
**&name(clients){クライアント実装};
+
クライアントの実装は次の3種類があります。
+
|*クライアント実装の種類と概要
+
|~名前空間|~クラス|~概要|~解説|h
+
|Smdn.Net.Pop3.Client&br;(Smdn.Net.Pop3.Client.dll)|PopClient&br;PopMessageInfo|POPの操作を抽象化したクラスです。 メッセージに対する操作をSystem.IO.FileInfoクラスに似たインターフェイスで行えるようにしてあります。|[[PopClient>#PopClient]]|
+
|Smdn.Net.Pop3.WebClients&br;(Smdn.Net.Pop3.WebClients.dll)|PopWebRequest&br;PopWebResponse|POP URL(&urn2url(urn:ietf:rfc:2384,short);)を用いたクライアントの実装です。 &msdn(netfx,type,System.Net.WebRequest);/&msdn(netfx,type,System.Net.WebResponse);を継承しているので、メッセージのダウンロードにWebClientクラスのメソッドを使うこともできます。&br;&msdn(netfx,type,System.Net.FtpWebRequest);等と同様、WebRequest.Methodプロパティで送信するコマンドを制御できます。|[[PopWebRequest/PopWebResponse>#PopWebRequest]]|
+
|Smdn.Net.Pop3.Client.Session&br;(Smdn.Net.Pop3.Client.dll)|PopSession|POPコマンドと1対1に対応するメソッドを持つクラスです。 POPの操作は抽象化していません。 仕様と1対1で対応するような実装にしてあります。 このクラスは上記2種類のクライアント実装で内部的に使用しています。&br;直接使用することもできますが、インターフェイスを変更することがあるので推奨はできません。|-|
+

                  
+
*共通事項
+
ここでは各クライアント実装に共通する部分について解説します。 各クライアント実装の詳細については個別の解説を参照してください。
+

                  
+
**&aname(login){接続と認証};
+
PopClientクラスおよびPopWebRequestクラスは&urn2url(urn:ietf:rfc:2384){POP URL};を使った接続に対応しています。 接続時の動作は、基本的にPOP URLの仕様に準じた動作となるようにしています((ただし、popsスキームを使用した場合にSSL/TLSでの接続を試みる動作は、仕様には無い、本ライブラリ独自の拡張です))。
+

                  
+
ここでは接続時と認証時の動作について解説します。
+

                  
+
***&aname(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もしくはパラメータでポート番号を明示的に指定しない限り、デフォルトポートへの接続を試みます。 なお、ポート番号の指定では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へアップグレード|
+

                  
+
これら接続時のパラメータは次の箇所で指定します。
+
:URLのスキーム&sub{*1};|[[PopClientクラス>#PopClient.login]]のコンストラクタに指定するURLのスキーム、もしくは[[PopWebRequestクラス>#PopWebRequest.login]]に指定するリクエストURL
+
:SecurePortプロパティ&sub{*2};|[[PopClientクラス>#PopClient.login]]のコンストラクタで指定する引数securePort、もしくはPopClient.Profile.SecurePortプロパティ
+
:UseTlsIfAvailableプロパティ&sub{*3};|[[PopClient.Profile.UseTlsIfAvailableプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.UseTlsIfAvailableプロパティ>#PopWebRequest.login]]
 

                

                
~
***&aname(auth){認証};
using Smdn.Net.Pop3.WebClients;
+
接続にPOP URLを用いる場合、認証に用いるユーザ名と認証方式はURLから取得します。 パスワードはICredentialsByHostインターフェイス&sub{*1};を参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 POP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、URLからはパスワードを取得しません(指定されていても無視します)。
 

                

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

                

                
~
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。
    using (var client = new WebClient()) {
-
      client.Credentials = new NetworkCredential("user", "pass");
-
      client.DownloadFile("pop://user;AUTH=DIGEST-MD5@localhost/;MSG=1", "sample.eml");
-
    }
-
  }
-
}
-
}}
 

                

                
~
認証方式の大文字小文字の違いは無視します(POP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
#code(cs,PopClientクラスを使う場合){{
-
using System;
-
using System.IO;
-
using System.Net;
 

                

                
~
例として接続先のURLと認証時の動作を表にまとめると以下のようになります。
using Smdn.Net.Pop3;
-
using Smdn.Net.Pop3.Client;
 

                

                
~
|*URLと認証動作の例
class Sample {
~
|~URL|~ユーザ名|~使用する認証メカニズム|h
  public static void Main(string[] args)
~
|pop://user;AUTH=+APOP@pop.example.net/|user|APOP|
  {
~
|pop://user;AUTH=DIGEST-MD5@pop.example.net/|user|DIGEST-MD5|
    using (var client = new PopClient(new Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))) {
~
|pop://;AUTH=DIGEST-MD5@pop.example.net/|Credentialsプロパティより取得|DIGEST-MD5|
      client.Connect("pass");
+
|pop://user;AUTH=*@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|pop://user@pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|pop://;AUTH=ANONYMOUS@pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
+
|pop://pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはUSER/PASSコマンドを使用|
 

                

                
~
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
      var message = client.GetMessage(1);
 

                

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

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

                  
+
PopWebRequest.CredentialsプロパティはWebRequestから継承しているためICredentialsインターフェイスを実装していることを要求しますが、設定されるインスタンスはICredentialsByHostも実装している必要があります。
+

                  
+
**&aname(ssl){SSL/TLSを使用した接続};
+
***&aname(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};を作成します。
+

                  
+
具体的な記述例は[[PopClientでの例>#PopClient.certs]]および[[PopWebRequestでの例>#PopWebRequest.certs]]を参照してください。
+

                  
+
***&aname(sslcallback){SSL/TLS接続のカスタマイズ};
+
(このドキュメントは作成中です)
+
SslStream以外の実装を使いたい場合や、より高度な検証が必要な場合など、SSL/TLS接続時にデフォルトの動作を変更してカスタマイズする場合は、UpgradeConnectionStreamCallbackデリゲートを使用してコールバックメソッドを指定してください。
+
コールバックメソッドはPopClient.Connect()メソッドの引数、またはPopSessionManager.CreateSslStreamCallbackプロパティに指定してください。 実装例はPopConnection.CreateSslStreamメソッドを参照してください。
+

                  
+
**&aname(exception){例外};
+
ライブラリからは主に以下の例外をスローします。 InnerExceptionプロパティに原因となった例外を設定した状態でスローする場合もあります。
+
|*ライブラリがスローする例外
+
|~例外クラス|~スローされる状況|h
+
|PopInvalidOperationException&br;および派生クラス (Smdn.Net.Pop3)|プロトコル上不正な操作を行おうとした場合&br;サーバに不正な要求を行おうとした場合はPopProtocolViolationException&br;サーバがエラー応答を返した場合はPopErrorResponseException|
+
|PopConnectionException&br;および派生クラス (Smdn.Net.Pop3.Protocol)|接続に失敗した場合、ソケットエラーが発生した場合など&br;SSL/TLSに起因するエラーの場合はPopUpgradeConnectionException|
+
|TimeoutException (System)|ソケット送受信中やコマンド処理中にタイムアウトした場合|
+
|ArgumentException&br;および派生クラス (System)|nullや値域外の値など、メソッド呼び出し時の引数が不正な場合|
+
|WebException&br;またはProtocolViolationException (System.Net)|Smdn.Net.Pop3.WebClients名前空間で発生した例外は、これらの例外に変換した上でスローされます|
+

                  
+
サーバ/クライアントのバグなどにより上記以外の例外がスローされる可能性もあります。 [[ログ出力>#logging]]を有効にしている場合、発生した例外はログに記録されます。
+

                  
+
**&aname(logging){ログ};
+
シンボルTRACEを有効にしてビルドした場合、トレースにログを出力します。 ログ出力に使用する&msdn(netfx,type,System.Diagnostics.TraceSource){TraceSource};の名前と、出力内容は次のとおりです。
+

                  
+
|*ログ出力に使用するTraceSourceの名前と出力内容
+
|~TraceSourceの名前|~出力内容|h
+
|"Smdn.Net.Pop3.Client"|コマンドの送受信結果とセッション毎の動作ログ|
+
|"POP"|送信するコマンドと受信したレスポンスの内容|
+

                  
+
ログ出力先などの設定を行う場合は、以下の例のような&msdn(netfx,id,ms229689){アプリケーション構成ファイル};を作成してください。
+

                  
+
#code(xml,アプリケーション構成ファイルの例){{
+
<?xml version="1.0" encoding="utf-8" ?>
+
<configuration>
+
  <system.diagnostics>
+
    <sources>
+
      <source name="Smdn.Net.Pop3.Client" switchValue="Verbose">
+
        <listeners>
+
          <add name="console" type="System.Diagnostics.ConsoleTraceListener"/>
+
          <remove name="Default"/>
+
        </listeners>
+
      </source>
+
      <source name="POP" switchValue="Verbose">
+
        <listeners>
+
          <add name="log" type="System.Diagnostics.TextWriterTraceListener" initializeData="pop.log"/>
+
          <remove name="Default"/>
+
        </listeners>
+
      </source>
+
    </sources>
+
    <switches>
+
      <add name="switch" value="All"/>
+
    </switches>
+
  </system.diagnostics>
+
</configuration>
 
}}
}}
 

                

                
~
なお、SSL/TLSを使用しているかどうかに関わらず、ログには''パスワードを含む内容を平文で''出力します。 ログの出力が不要な場合はTRACEを無効にしてリビルドするか、Trace.csなどを削除してください。
**メッセージ一覧の取得
-
Gmailアカウントのメールボックスからメールの一覧を取得し、もっとも最近のメールをダウンロード・表示する例。
-
#code(cs,WebRequestクラスを使う場合){{
-
using System;
-
using System.IO;
-
using System.Text;
-
using System.Net;
 

                

                
-
using Smdn.Net.Pop3;
-
using Smdn.Net.Pop3.WebClients;
 

                

                
-
class Sample {
-
  public static void Main(string[] args)
-
  {
-
    PopWebRequestCreator.RegisterPrefix();
-
    PopSessionManager.ServerCertificateValidationCallback += delegate {
-
      return true;
-
    };
 

                

                
~
*&aname(PopClient){PopClientクラス (Smdn.Net.Pop3.Client.dll)};
    var baseUrl = new Uri("pops://user@pop.gmail.com/");
~
PopClientクラスおよびSmdn.Net.Pop3.Client名前空間のクラスの使い方。
    var credential = new NetworkCredential("user", "pass");
 

                

                
~
**概説
    var request = WebRequest.Create(baseUrl) as PopWebRequest;
+
基本的には、
+
+PopClientクラスのインスタンスを作成
+
+PopClient.Connect()メソッドでサーバに接続
+
+PopClient.GetMessage(), GetMessages()などのメソッドでPopMessageInfoクラスのインスタンスを取得
+
+PopMessageInfo.Open*(), Read*(), Save()などのメソッドでメッセージ本文を取得
 

                

                
~
の順でサーバ上のメッセージの取得と操作を行います。 以下でPopClientクラスの使い方について解説します。
    request.Credentials = credential;
-
    request.Method = "LIST";
-
    request.KeepAlive = true;
 

                

                
~
**接続・認証とSSL/TLS
    PopScanListing[] scanLists;
+
***&aname(PopClient.login){接続と認証};
+
接続・認証時の動作は、[[接続と認証>#login]]で解説したとおりPOP URLに記述されるスキーム・ホスト名・ポート・認証方式・ユーザ名に基づいて決まります。 PopClientクラスではPOP URLは用いず、ホスト・ポート・認証方式・ユーザ名等を個々に指定することもできます。
 

                

                
~
以下はコード上での記述と接続・認証時の動作の例です。 実際にSSL/TLSを使用する場合は[[証明書の検証等>#PopClient.certs]]が必要になります。
    using (var response = request.GetResponse() as PopWebResponse) {
~
#code(cs,PopClient){{
      scanLists = response.ScanLists;
~
/*
    }
+
 * ホスト"pop.example.net"のPOPSデフォルトポート(995)にSSL/TLSを用いて接続。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式は対応しているものを順に試行。
+
 */
+
var client1 = new PopClient(new Uri("pops://user@pop.example.net/"));
 

                

                
~
client1.Connect("pass");
    var recentMessageUrl = string.Format("./;MSG={0}", scanLists[scanLists.Length - 1].MessageNumber);
 

                

                
~
/*
    request = WebRequest.Create(new Uri(baseUrl, recentMessageUrl)) as PopWebRequest;
+
 * ホスト"pop.example.net"のポート10110に接続、可能ならSSL/TLSにアップグレード。
+
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はAPOPを試行。
+
 */
+
var client2 = new PopClient(new Uri("pop://user;AUTH=+APOP@pop.example.net:10110/"));
 

                

                
~
client2.Profile.UseTlsIfAvailable = true;
    request.Credentials = credential;
~
client2.Connect(new NetworkCredential("user", "pass"));
    request.Method = "RETR";
-
    request.KeepAlive = false;
 

                

                
~
/*
    using (var response = request.GetResponse()) {
~
 * ホスト"pop.example.net"のポート10110にSSL/TLSを用いて接続。
      using (var stream = response.GetResponseStream()) {
~
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はDIGEST-MD5を試行。
        var reader = new StreamReader(stream, Encoding.GetEncoding("iso-2022-jp"));
+
 */
+
var client3 = new PopClient("pop.example.net", 10110, true, "user", "DIGEST-MD5");
 

                

                
~
client3.Connect("pass");
        Console.WriteLine(reader.ReadToEnd());
~

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

                  
+
client4.Profile.UseTlsIfAvailable = false;
+
client4.Profile.UsingSaslMechanisms = new[] {"DIGEST-MD5", "CRAM-MD5", "+APOP"};
+

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

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

                  
+
client5.Connect("pass");
 
}}
}}
 

                

                
~
***&aname(PopClient.certs){証明書の選択と検証};
#code(cs,PopClientクラスを使う場合){{
+
デフォルトでは、接続・認証時にPopConnectionクラス(Smdn.Net.Pop3.Protocol.Client名前空間)の以下のメンバを参照して証明書の選択と検証を行います。
+

                  
+
|*SSL/TLS接続時に参照するメンバ(いずれもクラスプロパティ)
+
|~型|~PopClientクラスが参照するメンバ|h
+
|X509Certificate2Collection|PopConnection.ClientCertificates|
+
|RemoteCertificateValidationCallback|PopConnection.ServerCertificateValidationCallback|
+
|RemoteCertificateValidationCallback|PopConnection.ClientCertificateSelectionCallback|
+

                  
+
以下は証明書の検証を行う簡単な例です。
+

                  
+
#code(cs,証明書の検証を行う例){{
 
using System;
using System;
-
using System.Collections.Generic;
-
using System.IO;
 
using System.Net;
using System.Net;
~
using System.Net.Security;
using System.Text;
~
using System.Security.Cryptography.X509Certificates;

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

                

                
~
public class ValidateServerCerts {
class Sample {
 
  public static void Main(string[] args)
  public static void Main(string[] args)
 
  {
  {
~
    // 証明書の検証を行うコールバックメソッドを指定
    PopConnection.ServerCertificateValidationCallback += delegate {
~
    PopConnection.ServerCertificateValidationCallback += ValidateRemoteCertificate;
      return true;
-
    };
 

                

                
~
    using (var client = new PopClient(new Uri("pops://user@localhost/"))) {
    using (var client = new PopClient(new Uri("pops://user@pop.gmail.com/"))) {
 
      client.Connect("pass");
      client.Connect("pass");
+
    }
+
  }
 

                

                
~
  private static bool ValidateRemoteCertificate(object sender,
      var messages = new List<PopMessageInfo>(client.GetMessages());
~
                                                X509Certificate certificate,
      var recentMessage = messages[messages.Count - 1];
+
                                                X509Chain chain,
+
                                                SslPolicyErrors sslPolicyErrors)
+
  {
+
#if DEBUG
+
    // デバッグ時のみSslPolicyErrors.RemoteCertificateNameMismatchを無視
+
    if ((int)(sslPolicyErrors & SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
+
      sslPolicyErrors &= ~SslPolicyErrors.RemoteCertificateNameMismatch;
+
#endif
 

                

                
~
    if (sslPolicyErrors == SslPolicyErrors.None) {
      using (var reader = recentMessage.OpenText(Encoding.GetEncoding("iso-2022-jp"))) {
~
      return true;
        Console.WriteLine(reader.ReadToEnd());
~
    }
      }
+
    else {
+
      // エラーがあれば標準エラーに表示
+
      Console.Error.WriteLine(sslPolicyErrors);
+
      return false;
 
    }
    }
 
  }
  }
 
}
}
 
}}
}}
 

                

                
~
SSL/TLS接続時の動作をデフォルトからカスタマイズしたい場合は、PopClient.Connect()メソッドの引数に適切なコールバックメソッドを指定してください。
*ライブラリの設計と実装の概要
~
(このドキュメントは作成中です)
このドキュメントは作成中です。
 

                

                
~
**操作
[[works/libs/Smdn.Net.Imap4]]の[[works/libs/Smdn.Net.Imap4/doc]]を参照してください。 プロトコルに固有な部分をのぞき、設計・実装は[[works/libs/Smdn.Net.Imap4]]と同様です。
+
接続・切断およびメールボックスに対する操作はPopClientクラス、個々のメッセージに対する操作はPopMessageInfoクラスのインスタンスを用いて行います。 PopMessageInfoクラスのインスタンスは、PopClient.GetMessage()メソッドなどで取得します(直接インスタンスを作成することはできません)。
 

                

                
~
***接続・切断
*Smdn.Net.Pop3.WebClients名前空間
~
以下は接続・切断に関するメソッドとプロパティです。
ここではSmdn.Net.Pop3.WebClients名前空間のクラスの詳細と使い方を紹介します。 基本的にはHttpWebRequest/ResponseやFtpWebRequest/Responseと同様で、
~
|*メソッド
+URLを指定してWebRequest.CreateでWebRequestのインスタンスを作成
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|PopClient.Connect(string)&br;PopClient.Connect(ICredentialsByHost)|PopClient.Profileプロパティで指定された内容、および引数で指定されたパスワード(もしくはICredentialsByHost)を使って接続・認証を試みます。&br;接続・認証できた場合は、サーバの能力とメールボックスにあるメッセージの数を取得します。|USER/PASS, STLS, APOP, AUTH, CAPA, STATなど|
+
|PopClient.Logout()|ログアウトします。 削除マークが付けられているメッセージは削除されます。|QUIT|
+
|PopClient.Disconnect()&br;PopClient.IDisposable.Dispose()|ログアウトせずに切断します。 削除マークが付けられているメッセージがあっても削除されません。|-|
+
|PopClient.KeepAlive()|自動ログアウトタイマの更新、セッションの接続性確認などに使います。|NOOP|
+

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

                  
+
***メールボックスに対する操作
+
以下はメールボックス操作に関するメソッドとプロパティです。
+
|*メソッド
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|PopClient.CancelDelete()|すべてのメッセージに対して削除マークを元に戻し、削除要求をキャンセルします。 PopMessageInfo.MarkAsDeleted()で行った操作がキャンセルされます。|RSET|
+

                  
+
|*プロパティ
+
|~プロパティ|~解説|h
+
|PopClient.MessageCount|メールボックスに存在するメッセージの数(STATコマンドの結果)を取得します。|
+
|PopClient.TotalSize|メールボックスに存在するメッセージの総サイズ(STATコマンドの結果)をバイト単位で取得します。|
+

                  
+
:MessageCount, TotalSize|切断されている状態で取得しようとした場合(PopClient.IsConnectedがfalseの場合)、例外をスローします。
+

                  
+
***メッセージの取得
+
以下はメールボックスにあるメッセージを取得するメソッドの一覧です。
+
|*メソッド
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|PopClient.GetMessage(long)&br;PopClient.GetMessage(long, bool)|指定された番号のメッセージを取得します。 オプションでメッセージのIDも取得します。 最初の番号は1です。|LIST, UIDL|
+
|PopClient.GetMessage(string)|指定されたIDを持つメッセージを取得します。|LIST, UIDL|
+
|PopClient.GetMessages()&br;PopClient.GetMessages(bool)|メールボックスにあるすべてのメッセージを取得します。 オプションでメッセージのIDも取得します。|LIST, UIDL|
+

                  
+
-これらのメソッドは、接続してから切断するまでの間、同じ番号のメッセージに対しては常に同じPopMessageInfoインスタンスを返します。
+
-これらのメソッドを呼び出し、PopMessageInfoインスタンスを取得した時点では''メッセージの本文は取得しません''。 メッセージ本文を取得するには、取得したPopMessageInfoインスタンスに対してOpen*(), Read*(), Save()などのメソッドを呼び出す必要があります。
+
-これらのメソッドを呼び出す際、該当するメッセージ存在しない場合はPopMessageNotFoundException、削除マークが付けられている場合はPopMessageDeletedExceptionをスローします。
+
-メールボックスにあるメッセージが0件の場合でも、PopClient.GetMessages()は例外をスローせず空のIEnumerable<PopMessageInfo>を返します。
+

                  
+
***メッセージ本文の取得
+
以下はメッセージ本文の取得に関するメソッド・プロパティの一覧です。
+
|*メソッド
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|PopMessageInfo.OpenRead()&br;およびオーバーロード|メッセージ本文を読み込むためのStreamを取得します。|RETRまたはTOP|
+
|PopMessageInfo.OpenText()&br;およびオーバーロード|メッセージ本文を読み込むためのStreamReaderを取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadAllBytes()&br;およびオーバーロード|メッセージ本文をbyte[]で取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadAllLines()&br;およびオーバーロード|メッセージ本文をstring[]で取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadAllText()&br;およびオーバーロード|メッセージ本文をstringで取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadLines()&br;およびオーバーロード|メッセージ本文をIEnumerable<string>で取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadAs<TOutput>(Converter<Stream, TOutput>)&br;およびオーバーロード|メッセージ本文を読み込むためのStreamを取得し、指定されたConverter<Stream, TOutput>で変換された結果を取得します。|RETRまたはTOP|
+
|PopMessageInfo.ReadAs<TOutput>(Converter<StreamReader, TOutput>)&br;およびオーバーロード|メッセージ本文を読み込むためのStreamReaderを取得し、指定されたConverter<StreamReader, TOutput>で変換された結果を取得します。|RETRまたはTOP|
+
|PopMessageInfo.Save(string)&br;およびオーバーロード|メッセージ本文を指定されたファイルに保存します。|RETRまたはTOP|
+
|PopMessageInfo.WriteTo(Stream)&br;およびオーバーロード|メッセージ本文を指定されたStreamに書き込みます。|RETRまたはTOP|
+

                  
+
|*プロパティ
+
|~プロパティ|~解説|h
+
|PopClient.DeleteAfterRetrieve|PopMessageInfoクラスでメッセージ本文を取得する際、正常に取得できたらメッセージを削除マーク済みにするかどうかを取得/設定します。 このプロパティの値は、上記のメソッドの動作を変更します。|
+

                  
+
-PopClient.DeleteAfterRetrieveプロパティにtrueが指定されている場合、メッセージの取得に成功した時点で自動的にMarkAsDeleted()メソッドが呼び出され、メッセージは削除マーク済みにされます。
+
-すべてのメソッドは、既定ではRETRコマンドを用いてメッセージ本文全体を取得します。
+
maxLinesを引数に取るバージョンのオーバーロードを使用することで、TOPコマンドを用いてメッセージ本文のうちヘッダ部分とボディ部分の指定した行数のみを取得することもできます。
+
-OpenText(), ReadAllLines()などのメソッドは、既定ではstringへのデコードにISO-8859-1を使用します。
+
Encodingを引数に取るバージョンのオーバーロードを使用することで、指定したエンコーディングでデコードすることもできます。
+
これらのメソッドは''Content-Typeヘッダのcharsetパラメータや、Content-Transfer-Encodingヘッダなどに指定されている値は考慮せずに''デコードを行います。 MIMEメッセージとしてパース・デコードするには、OpenRead()やReadAllBytes()などのメソッドで本文を取得した後、適切な処理を施してください。
+

                  
+
***メッセージに対する操作
+
以下はメッセージの操作に関するメソッドとプロパティです。
+

                  
+
|*メソッド
+
|~メソッド|~解説|~対応するPOPコマンド|h
+
|PopMessageInfo.MarkAsDeleted()|メッセージを削除マーク済みにします。 すでに削除マーク済み(IsMarkedAsDeletedがtrue)の場合は何もしません。|DELE|
+

                  
+
|*プロパティ
+
|~プロパティ|~解説|h
+
|PopMessageInfo.IsMarkedAsDeleted|メッセージが削除マーク済みかどうかを表す値を取得します。|
+
|PopMessageInfo.MessageNumber|メッセージの番号を取得します。|
+
|PopMessageInfo.Length|メッセージのサイズをバイト単位で取得します。|
+
|PopMessageInfo.UniqueId|メッセージのID(UIDLコマンドの結果)を取得します。|
+

                  
+
:UniqueId|PopClient.GetMessage()等のメソッドでIDを取得するように指定しなかった場合、プロパティの値を参照する際にコマンドを発行してから結果を返します。
+

                  
+
**例外
+
PopClientクラスおよびPopMessageInfoクラスからは以下の例外をスローします。 ここに明記している以外の例外クラス・状況でスローされる場合があります。
+

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

                  
+
それぞれの例外クラスの継承関係は次のとおりです。
+
-System.SystemException
+
--Smdn.Net.Pop3.PopExcetion
+
---Smdn.Net.Pop3.Protocol.PopConnectionException
+
----Smdn.Net.Pop3.Protocol.PopUpgradeConnectionException
+
---Smdn.Net.Pop3.PopInvalidOperationException
+
----Smdn.Net.Pop3.PopErrorResponseException
+
----Smdn.Net.Pop3.PopProtocolViolationException
+
-----Smdn.Net.Pop3.Client.PopMessageDeletedException
+
---Smdn.Net.Pop3.Client.PopMessageNotFoundException
+

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

                  
+
なお、アプリケーションドメインをまたがる使用については全く考慮していません。
+

                  
+
*&aname(PopWebRequest){PopWebRequest/PopWebResponseクラス (Smdn.Net.Pop3.WebClients.dll)};
+
ここではPopWebRequest/PopWebResponseクラスおよびSmdn.Net.Pop3.WebClients名前空間のクラスの詳細と使い方を紹介します。
+

                  
+
**概説
+
基本的にはHttpWebRequest/HttpWebResponseやFtpWebRequest/FtpWebResponseを用いた操作と同様で、
+
+リクエストURLを指定して&msdn(netfx,method,System.Net.WebRequest.Create){WebRequest.Createメソッド};でPopWebRequestのインスタンスを作成
 
+Method、Credentialsなどのプロパティを指定
+Method、Credentialsなどのプロパティを指定
~
+PopWebRequest.GetResponseでリクエストを実行、レスポンスを取得
+WebRequest.GetResponseでリクエストを実行、レスポンスを取得
~
+取得したPopWebResponseインスタンスを参照、必要に応じてPopWebResponse.GetResponseStreamメソッドを呼び出す
+取得したWebResponseインスタンスを参照、必要に応じてWebResponse.GetResponseStreamメソッドを呼び出す
 

                

                
~
の順でPOPコマンドを実行、レスポンスを取得します。 以下でPopWebRequest/PopWebResponseクラスに固有な部分について解説します。
の順でPOPコマンドを実行、レスポンスを取得できます。 以下でSmdn.Net.Pop3.WebClientsに固有な部分について解説します。
 

                

                
 
**pop, popsスキームの登録
**pop, popsスキームの登録
~
WebRequestクラスがpopスキームおよびpopsスキームのURLを処理できるように、PopWebRequest/PopWebResponseクラスを使う前にPopWebRequestCreator.RegisterPrefixメソッドを呼び出しておく必要があります。
Smdn.Net.Pop3.WebClients名前空間のクラスを使う場合には、WebRequestクラスがpopスキームおよびpopsスキームのURLを処理できるようにPopWebRequestCreator.RegisterPrefixメソッドを呼び出しておく必要があります。
 

                

                
 
このメソッドはWebRequest.RegisterPrefixメソッドを呼び出し、popスキームおよびpopsスキームに対してPopWebRequestCreatorを関連付けます。
このメソッドはWebRequest.RegisterPrefixメソッドを呼び出し、popスキームおよびpopsスキームに対してPopWebRequestCreatorを関連付けます。
 

                

                
~
#code(cs,記述例){{
**リクエストURLと接続時の動作
~
using System;
接続時の動作は&urn2url(urn:ietf:rfc:2384);に記述されている内容に準じた動作となるようにしています。 (ただしpopsスキームを使用した場合にSSL/TLSでの接続を試みる動作は本ライブラリ固有の動作です)
+
using System.Net;
+
using Smdn.Net.Pop3;
+
using Smdn.Net.Pop3.WebClients;
+

                  
+
  :
+
  :
+
// popおよびpopsスキームの登録
+
PopWebRequestCreator.RegisterPrefix();
+

                  
+
// PopWebRequestインスタンスの作成
+
var request = WebRequest.Create("pop://user@pop.example.net/");
+
  :
+
  :
+
}}
 

                

                
~
**リクエストURLと接続・認証時の動作
***SSL/TLS・接続ポート
~
***&aname(PopWebRequest.login){接続と認証};
リクエストURLのスキームがpopsの場合は、常にSSL/TLSでの接続を試みます。 スキームがpopの場合は、PopWebRequest.UseTlsIfAvailableプロパティがtrueで、かつサーバがSTLSに対応している場合、認証を開始する前にSSL/TLSを使用した接続にアップグレードします。 URLでポート番号を指定しない場合、デフォルトのポート(popは110、popsは995)に接続します。
+
接続・認証時の動作は、[[接続と認証>#login]]で解説したとおりリクエストURLに記述されるスキーム・ホスト名・ポート・認証方式・ユーザ名に基づいて決まります。
+

                  
+
リクエストURLで記述されない接続・認証時の動作は、PopWebRequestクラスのプロパティで指定できます(([[PopWebRequestのプロパティ>#PopWebRequest.properties]]も合わせて参照してください))。
+
|*接続・認証時の動作を指定するPopWebRequestクラスのプロパティ
+
|~プロパティ|~解説|h
+
|Credentials|認証時に使用する資格情報(パスワード等)を指定します|
+
|UseTlsIfAvailable|認証を開始する前に、可能ならSSL/TLSへアップグレードするかどうかを指定します|
+
|UsingSaslMechanisms|認証時に試行する認証メカニズムを指定します|
+

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

                  
+
#code(cs,記述例){{
+
// popおよびpopsスキームの登録
+
PopWebRequestCreator.RegisterPrefix();
+

                  
+
/*
+
 * ホスト"pop.example.net"のPOPSデフォルトポート(995)にSSL/TLSを用いて接続。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式は対応しているものを順に試行。
+
 */
+
var request1 = WebRequest.Create(new Uri("pops://user@pop.example.net/"));
+

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

                  
+
/*
+
 * ホスト"pop.example.net"のポート10110に接続、可能ならSSL/TLSにアップグレード。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はAPOPを試行。
+
 */
+
var request2 = WebRequest.Create(new Uri("pop://user;AUTH=+APOP@pop.example.net:10110/")) as PopWebRequest;
+

                  
+
request2.UseTlsIfAvailable = true;
+
request2.Credentials = new NetworkCredential("user", "pass");
+

                  
+
/*
+
 * ホスト"pop.example.net"のポート10110にSSL/TLSを用いて接続。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はDIGEST-MD5を試行。
+
 */
+
var request3 = WebRequest.Create(new Uri("pops://user;AUTH=DIGEST-MD5@pop.example.net:10110/")) as PopWebRequest;
+

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

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

                  
+
request4.UseTlsIfAvailable = false;
+
request4.UsingSaslMechanisms = new[] {"DIGEST-MD5", "CRAM-MD5", "+APOP"};
+
request4.Credentials = new NetworkCredential("user", "pass");
+

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

                

                
~
request5.Credentials = new NetworkCredential("user", "pass");
|*リクエストURLの形式と接続動作の例
~
}}
|リクエストURLの形式|接続ポート|SSL/TLS|h
-
|pop://pop.example.net/|110|可能ならSSL/TLSへのアップグレードを試行|
-
|pop://pop.example.net:995/|995|可能ならSSL/TLSへのアップグレードを試行|
-
|pops://pop.example.net/|995|常にSSL/TLSで接続|
-
|pops://pop.example.net:10110/|10143|常にSSL/TLSで接続|
 

                

                
~
***&aname(PopWebRequest.certs){証明書の選択と検証};
***認証
~
デフォルトでは、接続・認証時にPopSessionManagerクラスの以下のメンバを参照して証明書の選択と検証を行います。
認証に用いるユーザ名は、リクエストURLから取得します。 パスワードはWebRequest.Credentialsプロパティを参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 POP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、リクエストURLからはパスワードを取得しません(指定されていても無視します)。
 

                

                
~
|*SSL/TLS接続時に参照するメンバ(いずれもクラスプロパティ)
使用する認証メカニズムもユーザ名同様にURLから取得します。 APOPを使用する場合は、"AUTH=+APOP"を指定してください。 認証メカニズムを省略した場合、もしくは"AUTH=*"が指定されている場合は次の順で認証を試行します。
~
|~型|~PopWebRequestクラスが参照するメンバ|h
+AUTHコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
~
|X509Certificate2Collection|PopSessionManager.ClientCertificates|
+APOPコマンド (サーバがサポートしている場合のみ)
~
|RemoteCertificateValidationCallback|PopSessionManager.ServerCertificateValidationCallback|
+USER/PASSコマンド
+
|RemoteCertificateValidationCallback|PopSessionManager.ClientCertificateSelectionCallback|
 

                

                
~
以下は証明書の検証を行う簡単な例です。
リクエストURLにユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。
 

                

                
~
#code(cs,証明書の検証を行う例){{
|*リクエストURLの形式と認証動作の例
~
using System;
|リクエストURLの形式|ユーザ名|使用する認証メカニズム|h
~
using System.Net;
|pop://user;AUTH=+APOP&#x40;pop.example.net/|user|APOP|
~
using System.Net.Security;
|pop://user;AUTH=DIGEST-MD5&#x40;pop.example.net/|user|DIGEST-MD5|
~
using System.Security.Cryptography.X509Certificates;
|pop://;AUTH=DIGEST-MD5&#x40;pop.example.net/|WebRequest.Credentialsより取得|DIGEST-MD5|
~
using Smdn.Net.Pop3;
|pop://user;AUTH=*&#x40;pop.example.net/&br;pop://user&#x40;pop.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
~
using Smdn.Net.Pop3.WebClients;
|pop://;AUTH=ANONYMOUS&#x40;pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
~

                  
|pop://pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはUSER/PASSコマンドを使用|
+
public class ValidateServerCerts {
+
  public static void Main(string[] args)
+
  {
+
    PopWebRequestCreator.RegisterPrefix();
+

                  
+
    // 証明書の検証を行うコールバックメソッドを指定
+
    PopSessionManager.ServerCertificateValidationCallback += ValidateRemoteCertificate;
+

                  
+
    using (var client = new WebClient()) {
+
      client.Credentials = new NetworkCredential("user", "pass");
+
      client.DownloadFile("pops://user@localhost/;MSG=1", "sample.eml");
+
    }
+
  }
 

                

                
~
  private static bool ValidateRemoteCertificate(object sender,
試行する認証メカニズムを制御するには、後述するPopWebRequest.UsingSaslMechanismsプロパティの値を変更してください。
+
                                                X509Certificate certificate,
+
                                                X509Chain chain,
+
                                                SslPolicyErrors sslPolicyErrors)
+
  {
+
#if DEBUG
+
    // デバッグ時のみSslPolicyErrors.RemoteCertificateNameMismatchを無視
+
    if ((int)(sslPolicyErrors & SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
+
      sslPolicyErrors &= ~SslPolicyErrors.RemoteCertificateNameMismatch;
+
#endif
+

                  
+
    if (sslPolicyErrors == SslPolicyErrors.None) {
+
      return true;
+
    }
+
    else {
+
      // エラーがあれば標準エラーに表示
+
      Console.Error.WriteLine(sslPolicyErrors);
+
      return false;
+
    }
+
  }
+
}
+
}}
+

                  
+
SSL/TLS接続時の動作をデフォルトからカスタマイズしたい場合は、PopSessionManager.CreateSslStreamCallbackに適切なコールバックメソッドを指定してください。
 

                

                
 
**リクエストURLとリクエスト・レスポンスの動作
**リクエストURLとリクエスト・レスポンスの動作
 
POP URL(&urn2url(urn:ietf:rfc:2384,short);)ではPOPサーバ(メールボックス)を表す形式しか規定されていませんが、本ライブラリでは独自の拡張としてメッセージ番号を指定してリクエストできるようにしてあります。 リクエストURLにメッセージ番号(;MSG=x)が含まれているかどうかでリクエストの対象が変わります。
POP URL(&urn2url(urn:ietf:rfc:2384,short);)ではPOPサーバ(メールボックス)を表す形式しか規定されていませんが、本ライブラリでは独自の拡張としてメッセージ番号を指定してリクエストできるようにしてあります。 リクエストURLにメッセージ番号(;MSG=x)が含まれているかどうかでリクエストの対象が変わります。
 
|*リクエストURLの形式とリクエストの対象
|*リクエストURLの形式とリクエストの対象
~
|~リクエストURLの形式|~リクエストの対象|h
|リクエストURLの形式|リクエストの対象|h
 
|pop://pop.example.net/|URLで指定されたメールボックス|
|pop://pop.example.net/|URLで指定されたメールボックス|
 
|pop://pop.example.net/;MSG=1|URLで指定されたメールボックスにあるメッセージのうち、メッセージ番号に該当する特定のメッセージ|
|pop://pop.example.net/;MSG=1|URLで指定されたメールボックスにあるメッセージのうち、メッセージ番号に該当する特定のメッセージ|
 

                

                
 
WebRequest.Createメソッドが返すWebRequestインスタンスのMethodプロパティにデフォルトで設定される値は、リクエストURLの形式によって決まります。
WebRequest.Createメソッドが返すWebRequestインスタンスのMethodプロパティにデフォルトで設定される値は、リクエストURLの形式によって決まります。
 

                

                
~
PopWebRequest.GetResponseの動作は、リクエストURLで表されるリクエストの対象と、WebRequest.Methodプロパティに設定する値によって変わります。 以下でリクエストURLの形式とMethodプロパティに指定可能な値、リクエストとレスポンスについて解説します。 PopWebRequestクラスのプロパティのうち、リクエストに影響するその他のプロパティについては[[PopWebRequestのプロパティ>#PopWebRequest.properties]]で説明します。
PopWebRequest.GetResponseの動作は、リクエストURLで表されるリクエストの対象と、WebRequest.Methodプロパティに設定する値によって変わります。 以下でリクエストURLの形式とMethodプロパティに指定可能な値、リクエストとレスポンスについて解説します。 PopWebRequestクラスのプロパティのうち、リクエストに影響するその他のプロパティについては別項で説明します。
 

                

                
 
***メールボックスに対するリクエスト
***メールボックスに対するリクエスト
 
リクエストURLがメールボックスを表す場合(pop://pop.example.net/の形式)のリクエストとレスポンスの動作は次のとおりです。
リクエストURLがメールボックスを表す場合(pop://pop.example.net/の形式)のリクエストとレスポンスの動作は次のとおりです。
 

                

                
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|PopWebRequestMethods.List, "LIST"&br;(デフォルト)|LISTコマンドを送信してメールボックスにあるメッセージの一覧を取得します。|-|取得したメッセージの一覧は、PopWebResponse.ScanListsプロパティに設定されます。|
|PopWebRequestMethods.List, "LIST"&br;(デフォルト)|LISTコマンドを送信してメールボックスにあるメッセージの一覧を取得します。|-|取得したメッセージの一覧は、PopWebResponse.ScanListsプロパティに設定されます。|
 
|PopWebRequestMethods.Rset, "RSET"|RSETコマンドを送信してDELEコマンドの操作をキャンセルします。|-||
|PopWebRequestMethods.Rset, "RSET"|RSETコマンドを送信してDELEコマンドの操作をキャンセルします。|-||
 
|PopWebRequestMethods.Stat, "STAT"|STATコマンドを送信してメールボックスにあるメッセージの数と総サイズを取得します。|-|取得したメッセージ数と総サイズは、PopWebResponse.DropListプロパティに設定されます。|
|PopWebRequestMethods.Stat, "STAT"|STATコマンドを送信してメールボックスにあるメッセージの数と総サイズを取得します。|-|取得したメッセージ数と総サイズは、PopWebResponse.DropListプロパティに設定されます。|
 
|PopWebRequestMethods.Uidl, "UIDL"|UIDLコマンドを送信してメールボックスにあるメッセージのIDの一覧を取得します。|-|取得したIDの一覧は、PopWebResponse.UniqueIdListsプロパティに設定されます。|
|PopWebRequestMethods.Uidl, "UIDL"|UIDLコマンドを送信してメールボックスにあるメッセージのIDの一覧を取得します。|-|取得したIDの一覧は、PopWebResponse.UniqueIdListsプロパティに設定されます。|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
 

                

                
 
***特定のメッセージに対するリクエスト
***特定のメッセージに対するリクエスト
 
リクエストURLが特定のメッセージを表す場合(pop://pop.example.net/;MSG=1の形式)のリクエストとレスポンスの動作は次のとおりです。
リクエストURLが特定のメッセージを表す場合(pop://pop.example.net/;MSG=1の形式)のリクエストとレスポンスの動作は次のとおりです。
 

                

                
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|PopWebRequestMethods.Retr, "RETR"&br;(デフォルト)|RETRコマンドを送信してメッセージの本文を取得します。|-|メッセージ本文はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 取得したメッセージのサイズはWebResponse.ContentLengthプロパティに設定されます。|
|PopWebRequestMethods.Retr, "RETR"&br;(デフォルト)|RETRコマンドを送信してメッセージの本文を取得します。|-|メッセージ本文はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 取得したメッセージのサイズはWebResponse.ContentLengthプロパティに設定されます。|
 
|PopWebRequestMethods.Dele, "DELE"|DELEコマンドを送信してメッセージを削除します。|-|-|
|PopWebRequestMethods.Dele, "DELE"|DELEコマンドを送信してメッセージを削除します。|-|-|
 
|PopWebRequestMethods.List, "LIST"|LISTコマンドを送信してメッセージの番号とサイズを取得します。|-|取得したメッセージ番号とサイズは、PopWebResponse.ScanListsプロパティに設定されます。|
|PopWebRequestMethods.List, "LIST"|LISTコマンドを送信してメッセージの番号とサイズを取得します。|-|取得したメッセージ番号とサイズは、PopWebResponse.ScanListsプロパティに設定されます。|
 
|PopWebRequestMethods.Top, "TOP"|TOPコマンドを送信してメッセージをヘッダ部分を取得します。|現時点ではTOPで取得するボディ部分の行数は指定できません(常に0を指定します)。|メッセージのヘッダ部分はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 取得したヘッダ部分のサイズはWebResponse.ContentLengthプロパティに設定されます。|
|PopWebRequestMethods.Top, "TOP"|TOPコマンドを送信してメッセージをヘッダ部分を取得します。|現時点ではTOPで取得するボディ部分の行数は指定できません(常に0を指定します)。|メッセージのヘッダ部分はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 取得したヘッダ部分のサイズはWebResponse.ContentLengthプロパティに設定されます。|
 
|PopWebRequestMethods.Uidl, "UIDL"|UIDLコマンドを送信してメッセージの番号とIDを取得します。|-|取得したメッセージ番号とIDは、PopWebResponse.UniqueIdListsプロパティに設定されます。|
|PopWebRequestMethods.Uidl, "UIDL"|UIDLコマンドを送信してメッセージの番号とIDを取得します。|-|取得したメッセージ番号とIDは、PopWebResponse.UniqueIdListsプロパティに設定されます。|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
 

                

                
 
***リクエスト対象に制限されないリクエスト
***リクエスト対象に制限されないリクエスト
 
リクエストURLの形式によらず使用可能なコマンドのリクエストとレスポンスの動作は次のとおりです。
リクエストURLの形式によらず使用可能なコマンドのリクエストとレスポンスの動作は次のとおりです。
 

                

                
~
|~Methodプロパティに指定可能な値|~リクエスト|~解説|~レスポンス|h
|Methodプロパティに指定可能な値|リクエスト|解説|レスポンス|h
 
|PopWebRequestMethods.NoOp, "NOOP"|NOOPコマンドを送信します。|このコマンドは何もしません。 自動ログアウトタイマの更新、セッションの接続性確認などに使います。|-|
|PopWebRequestMethods.NoOp, "NOOP"|NOOPコマンドを送信します。|このコマンドは何もしません。 自動ログアウトタイマの更新、セッションの接続性確認などに使います。|-|
~
|~Methodプロパティに指定可能な値|~リクエスト|~解説|~レスポンス|f
|Methodプロパティに指定可能な値|リクエスト|解説|レスポンス|f
 

                

                
~
***&aname(PopWebRequest.properties){PopWebRequestクラスのプロパティ};
***PopWebRequestクラスのプロパティ
 
PopWebRequestクラスにはMethodプロパティ以外にもコマンド送信時の動作を制御するためのプロパティを用意してあります。 プロパティの値によってリクエスト内容と動作が変わります。
PopWebRequestクラスにはMethodプロパティ以外にもコマンド送信時の動作を制御するためのプロパティを用意してあります。 プロパティの値によってリクエスト内容と動作が変わります。
 

                

                
 
|*PopWebRequestクラスのプロパティ
|*PopWebRequestクラスのプロパティ
~
|~プロパティ|~デフォルト|~対象となるコマンド|~解説|h
|プロパティ|デフォルト|対象となるコマンド|解説|h
 
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
~
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にSSL/TLSを使用した接続にアップグレードします。|
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にTLSを使用した接続にアップグレードします。|
 
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
|UsingSaslMechanisms|{"DIGEST-MD5", "CRAM-MD5", "NTLM"}|全て(認証時)|認証メカニズムが指定されていない場合に、試行する認証メカニズムとその順番を配列で指定します。 サーバ・クライアントの両方がサポートするメカニズム以外が指定されている場合は無視します。|
 
|DeleteAfterRetrieve|false|RETR|RETRコマンドでのメッセージの受信が成功した場合、同じメッセージに対して自動的にDELEコマンドを発行します。|
|DeleteAfterRetrieve|false|RETR|RETRコマンドでのメッセージの受信が成功した場合、同じメッセージに対して自動的にDELEコマンドを発行します。|
 
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
617,7 239,7
 
WebRequestクラスから継承されるプロパティのうち、以下のプロパティは使用することができます。
WebRequestクラスから継承されるプロパティのうち、以下のプロパティは使用することができます。
 

                

                
 
|*WebRequestクラスから継承されるプロパティ
|*WebRequestクラスから継承されるプロパティ
~
|~プロパティ|~デフォルト|~対象となるコマンド|~解説|h
|プロパティ|デフォルト|対象となるコマンド|解説|h
 
|Timeout|-1|全て|リクエストを開始してからレスポンスを取得するまでのタイムアウト時間を指定します。|
|Timeout|-1|全て|リクエストを開始してからレスポンスを取得するまでのタイムアウト時間を指定します。|
 
|ReadWriteTimeout|300000|全て|ソケット送受信のタイムアウト時間を指定します。|
|ReadWriteTimeout|300000|全て|ソケット送受信のタイムアウト時間を指定します。|
 

                

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

                

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

                

                
 
**アプリケーション構成ファイルでの設定
**アプリケーション構成ファイルでの設定
659,7 281,7
 
      <add key="keepAlive" value="true"/>
      <add key="keepAlive" value="true"/>
 
      <add key="anonymousToken" value="anonymous"/>
      <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="expectedErrorResponseCodes" value="SYS/TEMP"/>
      <add key="expectedErrorResponseCodes" value="ALREADYEXISTS, NONEXISTENT"/>
 
    </webRequestDefaults>
    </webRequestDefaults>
 
  </smdn.net.pop3.client>
  </smdn.net.pop3.client>
 
</configuration>
</configuration>
667,323 289,14
 

                

                
 
記述内容については[[ネットワーク設定スキーマ:http://msdn.microsoft.com/ja-jp/library/dacty7ed%28VS.80%29.aspx]]および[[構成セクション スキーマ:http://msdn.microsoft.com/ja-jp/library/0hyxd0xc%28VS.80%29.aspx]]も合わせて参照してください。
記述内容については[[ネットワーク設定スキーマ:http://msdn.microsoft.com/ja-jp/library/dacty7ed%28VS.80%29.aspx]]および[[構成セクション スキーマ:http://msdn.microsoft.com/ja-jp/library/0hyxd0xc%28VS.80%29.aspx]]も合わせて参照してください。
 

                

                
~
**例外
*Smdn.Net.Pop3.Client名前空間
~
(このドキュメントは作成中です)
Smdn.Net.Pop3.Client名前空間のクラスの使い方。 このドキュメントは作成中です。 前述のサンプルおよび[[works/tools/junk/TundereBird]]の実装を参照してください。
+

                  
+
**スレッドセーフティ
+
(このドキュメントは作成中です)
+

                  
+
*&aname(samples){サンプルコード};
+
各クライアント実装を用いたサンプルコードを例示します。 証明書の検証を省略している箇所がありますが、実際に使用するコードでは必ず適切な検証を行うように書き換えてください。
+

                  
+
**PopClient
+
***&aname(PopClient.sample1){メッセージをダウンロードしてファイルに保存する};
+
#code(cs){{
+
using System;
+

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

                  
+
class SaveToFile {
+
  public static void Main(string[] args)
+
  {
+
    using (var client = new PopClient(new Uri("pop://user;AUTH=DIGEST-MD5@localhost/"))) {
+
      client.Connect("pass");
 

                

                
~
      // メールボックスにある1件目のメッセージをダウンロード
*Smdn.Net.Pop3.Client.Session名前空間
~
      var message = client.GetMessage(1);
Smdn.Net.Pop3.Client.Session名前空間のクラスの使い方。 このドキュメントは作成中です。 [[works/tools/junk/TundereBird]]およびSmdn.Net.Pop3.WebClientsの各クラスの実装を参照してください。
+

                  
+
      // ファイルsample.emlに保存
+
      message.Save("sample.eml");
+
    }
+
  }
+
}
+
}}
 

                

                
~
同じ処理を[[PopWebRequestで記述した例>#PopWebRequest.sample1]]
**Gmail
~

                  
Gmailに接続し、メッセージの一覧を取得した後、一番最後のメッセージを取得し、表示するサンプル。
+
***&aname(PopClient.sample2){Gmailアカウントのメールボックスから、最新のメッセージをダウンロードする};
+
#code(cs){{
+
using System;
+
using System.Net;
+
using System.Text;
+

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

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

                  
+
    using (var client = new PopClient(new Uri("pops://user@pop.gmail.com/"))) {
+
      client.Connect("pass");
+

                  
+
      if (client.MessageCount == 0) {
+
        // メールボックスにメッセージがない
+
        Console.WriteLine("no messages");
+
        return;
+
      }
+

                  
+
      // メールボックスにある最後のメッセージを取得
+
      var recentMessageNumber = client.MessageCount;
+
      var recentMessage = client.GetMessage(recentMessageNumber);
+

                  
+
      // メッセージ本文をダウンロードし、iso-2022-jpでデコードして表示
+
      Console.WriteLine(recentMessage.ReadAllText(Encoding.GetEncoding("iso-2022-jp")));
+
    }
+
  }
+
}
+
}}
+

                  
+
同じ処理を[[PopWebRequestで記述した例>#PopWebRequest.sample2]]
+

                  
+
***メールボックスにあるすべてメッセージをダウンロードしてファイルに保存する
+
#code(cs){{
+
using System;
+

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

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

                  
+
    using (var client = new PopClient(new Uri("pops://user;auth=ntlm@localhost/"))) {
+
      client.Connect("pass");
+

                  
+
      // メッセージ本文を取得したら削除する
+
      client.DeleteAfterRetrieve = true;
+

                  
+
      // メールボックスにあるすべてのメッセージとIDを取得
+
      foreach (var message in client.GetMessages(true)) {
+
        // IDをファイル名として保存 (IDがファイル名として妥当かどうかのチェックは省略)
+
        message.Save(message.UniqueId + ".eml");
+
      }
+

                  
+
      // ログアウトしてメッセージを削除
+
      client.Logout();
+
    }
+
  }
+
}
+
}}
+

                  
+
上記のコードは、次のコードと等価です。
+
#code(cs){{
+
        :
+
      client.DeleteAfterRetrieve = false;
+

                  
+
      // メールボックスにあるすべてのメッセージとIDを取得
+
      foreach (var message in client.GetMessages(true)) {
+
        // IDをファイル名として保存 (IDがファイル名として妥当かどうかのチェックは省略)
+
        message.Save(message.UniqueId + ".eml");
+
        // 保存できたら削除マークを付ける
+
        message.MarkAsDeleted();
+
      }
+
        :
+
        :
+
}}
+

                  
+
***メッセージのIDを使って新着メッセージをチェックする
+
#code(cs){{
+
using System;
+
using System.Collections.Generic;
+
using System.Threading;
+

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

                  
+
class CheckRecent {
+
  public static void Main(string[] args)
+
  {
+
    // 既知のメッセージID
+
    var ids = new List<string>();
+

                  
+
    using (var client = new PopClient(new Uri("pop://user;auth=ntlm@localhost/"))) {
+
      client.Profile.UseTlsIfAvailable = false;
+

                  
+
      for (;;) {
+
        client.Connect("pass");
+

                  
+
        if (!client.ServerCapabilities.Has(PopCapability.Uidl))
+
          // サーバがUIDLをサポートしていない
+
          throw new ApplicationException("UIDL incapable");
+

                  
+
        // メールボックスにあるすべてのメッセージを取得
+
        foreach (var message in client.GetMessages(true)) {
+
          // 既知のメッセージIDかどうかチェック
+
          if (ids.Contains(message.UniqueId)) {
+
            // 既知の場合は何もしない
+
          }
+
          else {
+
            // 新着の場合は、メッセージ本文のヘッダのみを取得
+
            foreach (var line in message.ReadLines(0)) {
+
              // ヘッダのうち"Subject:"で始まる行のみを表示
+
              if (line.StartsWith("Subject:", StringComparison.OrdinalIgnoreCase))
+
                Console.WriteLine("{0}: {1}", message.UniqueId, line);
+
            }
+

                  
+
            // 既知のメッセージIDとして追加
+
            ids.Add(message.UniqueId);
+
          }
+
        }
+

                  
+
        // いったん切断
+
        client.Disconnect();
+

                  
+
        // 5分後に再接続する
+
        Thread.Sleep(TimeSpan.FromMinutes(5.0));
+
      }
+
    }
+
  }
+
}
+
}}
+

                  
+
この例において、初回の接続の時点ではidsは空なので、メールボックスにあるメッセージはすべて新着として扱われます。
+

                  
+
***メッセージをダウンロードしてパース・デコードする
+
メッセージをダウンロードした後、[[works/libs/Smdn.Formats.Mime]]を使ってパース・デコードする例。
+
#code(cs){{
+
using System;
+

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

                  
+
class DecodeMime {
+
  public static void Main(string[] args)
+
  {
+
    using (var client = new PopClient(new Uri("pop://user;auth=ntlm@localhost/"))) {
+
      client.Profile.UseTlsIfAvailable = false;
+

                  
+
      client.Connect("pass");
+

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

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

                  
+
        // デコードした本文を表示
+
        if (parsedMessage.MimeType.TypeEqualsIgnoreCase("text"))
+
          Console.WriteLine(decodedMessage.ReadContentAsText());
+
        else
+
          Console.WriteLine("非テキストメッセージです");
+
      }
+
    }
+
  }
+
}
+
}}
+

                  
+
**PopWebRequest/PopWebResponse
+
***&aname(PopWebRequest.sample1){メッセージをダウンロードしてファイルに保存する};
+
#code(cs){{
+
using System;
+
using System.Net;
+

                  
+
using Smdn.Net.Pop3.WebClients;
+

                  
+
class SaveToFile {
+
  public static void Main(string[] args)
+
  {
+
    PopWebRequestCreator.RegisterPrefix();
+

                  
+
    using (var client = new WebClient()) {
+
      client.Credentials = new NetworkCredential("user", "pass");
+

                  
+
      // メールボックスにある1件目のメッセージをダウンロードしてファイルsample.emlに保存
+
      client.DownloadFile("pop://user;AUTH=DIGEST-MD5@localhost/;MSG=1", "sample.eml");
+
    }
+
  }
+
}
+
}}
+

                  
+
同じ処理を[[PopClientで記述した例>#PopClient.sample1]]
+

                  
+
***&aname(PopWebRequest.sample2){Gmailアカウントのメールボックスから、最新のメッセージをダウンロードする};
+
#code(cs){{
+
using System;
+
using System.IO;
+
using System.Text;
+
using System.Net;
+

                  
+
using Smdn.Net.Pop3;
+
using Smdn.Net.Pop3.WebClients;
+

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

                  
+
    var baseUrl = new Uri("pops://user@pop.gmail.com/");
+
    var credential = new NetworkCredential("user", "pass");
+

                  
+
    // STATコマンドでメールボックスにあるメッセージの数を取得
+
    var request = WebRequest.Create(baseUrl) as PopWebRequest;
+

                  
+
    request.Credentials = credential;
+
    request.Method = "STAT";
+
    request.KeepAlive = true; // リクエストが完了しても接続したままにする
+

                  
+
    long recentMessageNumber;
+

                  
+
    using (var response = request.GetResponse() as PopWebResponse) {
+
      recentMessageNumber = response.DropList.MessageCount;
+
    }
+

                  
+
    if (recentMessageNumber == 0) {
+
      // メールボックスにメッセージがない
+
      Console.WriteLine("no messages");
+
      return;
+
    }
+

                  
+
    // 取得するメッセージ番号を含む相対URLを作成
+
    var recentMessageUrl = string.Format("./;MSG={0}", recentMessageNumber);
+

                  
+
    // RETRコマンドでメッセージの本文を取得
+
    request = WebRequest.Create(new Uri(baseUrl, recentMessageUrl)) as PopWebRequest;
+

                  
+
    request.Credentials = credential;
+
    request.Method = "RETR";
+
    request.KeepAlive = false; // リクエストが完了したら切断する
+

                  
+
    using (var response = request.GetResponse()) {
+
      using (var stream = response.GetResponseStream()) {
+
        // メッセージ本文をiso-2022-jpでデコードして表示
+
        var reader = new StreamReader(stream, Encoding.GetEncoding("iso-2022-jp"));
+

                  
+
        Console.WriteLine(reader.ReadToEnd());
+
      }
+
    }
+
  }
+
}
+
}}
+

                  
+
同じ処理を[[PopClientで記述した例>#PopClient.sample2]]
+

                  
+
**PopSession
+
このクラスを直接使用することはできますが推奨はしません。 また、ドキュメントを用意する予定はありません。 内部実装の参照や改変などの参考程度に掲載します。
+

                  
+
***メッセージをダウンロード・削除する
+
Gmailに接続し、最新のメッセージを取得し、表示したあと削除するサンプル。
 
#code(cs){{
#code(cs){{
 
using System;
using System;
 
using System.IO;
using System.IO;
998,62 311,28
 
  public static void Main(string[] args)
  public static void Main(string[] args)
 
  {
  {
 
    PopConnection.ServerCertificateValidationCallback += delegate {
    PopConnection.ServerCertificateValidationCallback += delegate {
+
      // 証明書の検証は省略 (エラーを無視してすべて受け入れる)
 
      return true;
      return true;
 
    };
    };
 

                

                
 
    using (var session = new PopSession("pop.gmail.com", 995, PopConnection.CreateSslStream)) {
    using (var session = new PopSession("pop.gmail.com", 995, PopConnection.CreateSslStream)) {
~
      var cred = new NetworkCredential("user", "pass");
      session.Credentials = new NetworkCredential("user", "pass");
 

                

                
~
      // 利用可能ならAPOP、そうでなければUSER/PASSでログイン
      if (session.Login().Failed) {
+
      var authenticationResult = session.ApopAvailable
+
        ? session.Apop(cred)
+
        : session.Login(cred);
+

                  
+
      if (authenticationResult.Failed) {
 
        Console.Error.WriteLine("authentication failed");
        Console.Error.WriteLine("authentication failed");
 
        return;
        return;
 
      }
      }
 

                

                
~
      // STATコマンドを発行
      PopScanListing[] scanLists;
+
      PopDropListing dropList;
 

                

                
~
      if (session.Stat(out dropList).Failed) {
      session.List(out scanLists);
+
        Console.Error.WriteLine("STAT failed");
+
        return;
+
      }
 

                

                
+
      if (dropList.MessageCount == 0L) {
+
        // メールボックスにメッセージがない
+
        Console.Error.WriteLine("no message exists");
+
        return;
+
      }
+

                  
+
      // RETRコマンドでメッセージ本文を取得・表示
 
      PopMessage message;
      PopMessage message;
 

                

                
~
      if (session.Retr(dropList.MessageCount, out message).Failed) {
      session.Retr(scanLists[scanLists.Length - 1].MessageNumber, out message);
+
        Console.Error.WriteLine("RETR failed");
+
        return;
+
      }
 

                

                
 
      var reader = new StreamReader(message.Body, Encoding.GetEncoding("iso-2022-jp"));
      var reader = new StreamReader(message.Body, Encoding.GetEncoding("iso-2022-jp"));
 

                

                
 
      Console.WriteLine(reader.ReadToEnd());
      Console.WriteLine(reader.ReadToEnd());
+

                  
+
      message.Dispose();
+

                  
+
      // DELEコマンドでメッセージを削除マーク済みにする
+
      if (session.Dele(message.Number).Failed) {
+
        Console.Error.WriteLine("DELE failed");
+
        return;
+
      }
+

                  
+
      // QUITコマンドでメッセージを削除してログアウト
+
      if (session.Quit().Failed) {
+
        Console.Error.WriteLine("QUIT failed");
+
        return;
+
      }
 
    }
    }
 
  }
  }
 
}
}

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

current previous
19,7 19,7
 
その他、サポートしている機能の詳細は「実装済み機能一覧」の項をご覧ください。
その他、サポートしている機能の詳細は「実装済み機能一覧」の項をご覧ください。
 

                

                
 
**クライアント実装
**クライアント実装
~
クライアント実装として以下の3つのクラスを用意しています。
クライアント実装として以下の2つのクラスを用意しています。
 
:PopSessionクラス|POPコマンドと1対1に対応するメソッドを持つクライアント
:PopSessionクラス|POPコマンドと1対1に対応するメソッドを持つクライアント
 
:PopClientクラス|メッセージをSystem.IO.FileInfoクラスに似たインターフェイスで操作できるようにPOP操作を抽象化したクライアント
:PopClientクラス|メッセージをSystem.IO.FileInfoクラスに似たインターフェイスで操作できるようにPOP操作を抽象化したクライアント
 
:PopWebRequest/PopWebResponseクラス|WebRequest/WebResponseクラスから派生し、POP URL(&urn2url(urn:ietf:rfc:2384,short);)での操作に対応したクライアント
:PopWebRequest/PopWebResponseクラス|WebRequest/WebResponseクラスから派生し、POP URL(&urn2url(urn:ietf:rfc:2384,short);)での操作に対応したクライアント
36,7 36,7
 

                

                
 
本ライブラリはMIT X11ライセンスでのリリースとなります。
本ライブラリはMIT X11ライセンスでのリリースとなります。
 

                

                
~
:最新版|${smdncms:distfilelink,Smdn.Net.Pop3.Client-0.91.tar.bz2}
:最新版|${smdncms:distfilelink,Smdn.Net.Pop3.Client-0.90.tar.bz2}
 
:開発版|[[anonsvn]]よりチェックアウトできます
:開発版|[[anonsvn]]よりチェックアウトできます
 

                

                
 
デモ用アプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。
デモ用アプリケーション[[works/tools/junk/TundereBird]]もあわせてご覧ください。

works/libs/Smdn.Security.Authentication.Sasl/index.wiki.txt

current previous
38,7 38,6
 
-開発版
-開発版
 
--[[anonsvn]]よりチェックアウトできます
--[[anonsvn]]よりチェックアウトできます
 
-0.2x
-0.2x
+
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.28.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.27.tar.bz2}
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.27.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.26.tar.bz2}
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.26.tar.bz2}
 
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.25.tar.bz2}
--${smdncms:distfilelink,Smdn.Security.Authentication.Sasl-0.25.tar.bz2}
50,14 49,6
 
不具合の報告、ライブラリに対する要望や提案、使い方の質問などは[[掲示板>misc/forum/libs]]へどうぞ。
不具合の報告、ライブラリに対する要望や提案、使い方の質問などは[[掲示板>misc/forum/libs]]へどうぞ。
 

                

                
 
*変更履歴
*変更履歴
+
**0.28 (2010-04-18)
+
-機能追加
+
--現在の状態を取得するためのプロパティSaslClientMechanism.ExchangeStatusを追加
+
--SaslClientMechanism.ExchangeStatusがSucceededもしくはFailedの時にExchange()を呼ぼうとした場合にInvalidOperationExceptionをスローするようにした
+
-修正・改善
+
--上位ライブラリのインターフェイス変更にあわせて実装および参照アセンブリを修正
+
--例外クラスのインターフェイスをカスタム例外のガイドラインに適合するように改善
+

                  
 
**0.27 (2010-04-04)
**0.27 (2010-04-04)
 
-機能追加
-機能追加
 
--例外クラスにSerializableAttributeを設定
--例外クラスにSerializableAttributeを設定