2010-04-25T22:14:17の更新内容

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

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

        

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

        

        
~
#hr
**メッセージのダウンロード
-
localhostのINBOXメールボックスからUIDが1のメールをダウンロードし、sample.emlとして保存するサンプル。 ログインユーザ名にuser、パスワードにpassを使用し、認証方式にDIGEST-MD5を使用。
-
#code(cs,WebClientクラスを使う場合){{
-
using System;
-
using System.Net;
 

        

        
~
*用語と表記
using Smdn.Net.Imap4.WebClients;
+
このドキュメントでは、以下の表記を用いています。
+
:メッセージ|IMAPサーバ上のメールボックスにある個々のメールの本文または/および属性を表す意味で用いています。
+
:メッセージ本文|IMAPサーバ上のメールボックスにある個々のメールの本文のみを表す意味で用いています。
+
:メールボックス|IMAPサーバ上のメールボックス(フォルダ)を表す意味で用いています。
+
:SSL/TLS|SSLおよびTLSを特に区別なく表す場合、SSL/TLSと表記しています。
+
:認証方式|認証に用いるメカニズムを表す意味で用いています。 ほとんどの場合、&urn2url(urn:ietf:rfc:2222){SASLメカニズム};を表す意味で用いていますが、場合によってはIMAP標準の平文による認証も含みます。
+
:クライアント|ほとんどの場合、本ライブラリに含まれるクライアント実装を表す意味で用いていますが、場合によっては一般的なIMAPクライアントを含みます。
+
:一覧|リスト(IList)・コレクション(ICollection)・その他の集合(IEnumerable等)を表す意味で用いている場合があります。
+

          
+
上記以外は、&urn2url(urn:ietf:rfc:3501,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.Imap4]]および[[works/libs/Smdn.Net.Pop3]]で共通して使用されるクラス群|
+
|Smdn.Security.Authentication.Sasl.dll|[[works/libs/Smdn.Security.Authentication.Sasl]](SASLクライアントの実装)|
+
|Smdn.Net.Imap4.dll|IMAP4で使用される基本型等の定義|
+
|Smdn.Net.Imap4.Client.dll|[[ImapClient>#ImapClient]], [[ImapSession>#ImapSession]]を含むIMAP4クライアント実装|
+
|Smdn.Net.Imap4.WebClients.dll|[[ImapWebRequest/ImapWebResponse>#ImapWebRequest]]を含むIMAP4クライアント実装|
 

        

        
~
本ライブラリを使用する場合は、上記アセンブリへの参照を追加してください(ImapWebRequest/ImapWebResponseを使用しない場合は、Smdn.Net.Imap4.WebClients.dllへの参照は不要です)。
class Sample {
-
  public static void Main(string[] args)
-
  {
-
    ImapWebRequestCreator.RegisterPrefix();
 

        

        
~
**&name(clients){クライアント実装};
    using (var client = new WebClient()) {
~
クライアントの実装は次の3種類があります。
      client.Credentials = new NetworkCredential("user", "pass");
~
|*クライアント実装の種類と概要
      client.DownloadFile("imap://user;AUTH=DIGEST-MD5@localhost/INBOX/;UID=1", "sample.eml");
~
|~名前空間|~クラス|~概要|~解説|h
    }
~
|Smdn.Net.Imap4.Client&br;(Smdn.Net.Imap4.Client.dll)|ImapClient&br;ImapMailboxInfo&br;ImapOpenedMailboxInfo&br;ImapMessageInfo&br;ImapMessageInfoList|IMAPの操作を抽象化したクラスです。 メッセージに対する操作をSystem.IO.FileInfo, DirectoryInfoクラスに似たインターフェイスで行えるようにしてあります。|[[ImapClient>#ImapClient]]|
  }
~
|Smdn.Net.Imap4.WebClients&br;(Smdn.Net.Imap4.WebClients.dll)|ImapWebRequest&br;ImapWebResponse|IMAP URL(&urn2url(urn:ietf:rfc:5092,short);)を用いたクライアントの実装です。 &msdn(netfx,type,System.Net.WebRequest);/&msdn(netfx,type,System.Net.WebResponse);を継承しているので、メッセージのダウンロードにWebClientクラスのメソッドを使うこともできます。&br;&msdn(netfx,type,System.Net.FtpWebRequest);等と同様、WebRequest.Methodプロパティで送信するコマンドを制御できます。|[[ImapWebRequest/ImapWebResponse>#ImapWebRequest]]|
}
~
|Smdn.Net.Imap4.Client.Session&br;(Smdn.Net.Imap4.Client.dll)|ImapSession|IMAPコマンドと1対1に対応するメソッドを持つクラスです。 IMAPの操作は抽象化していません。 仕様と1対1で対応するような実装にしてあります。 このクラスは上記2種類のクライアント実装で内部的に使用しています。&br;直接使用することもできますが、インターフェイスを変更することがあるので推奨はできません。|-|
}}
 

        

        
~
#hr
#code(cs,ImapClientクラスを使う場合){{
-
using System;
-
using System.IO;
-
using System.Net;
 

        

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

        

        
~
**&aname(login){接続と認証};
class Sample {
~
ImapClientクラスおよびImapWebRequestクラスは&urn2url(urn:ietf:rfc:5092){IMAP URL};を使った接続に対応しています。 接続時の動作は、基本的にIMAP URLの仕様に準じた動作となるようにしています((ただし、imapsスキームを使用した場合にSSL/TLSでの接続を試みる動作は、仕様には無い、本ライブラリ独自の拡張です))。
  public static void Main(string[] args)
-
  {
-
    using (var client = new ImapClient(new Uri("imap://user;AUTH=DIGEST-MD5@localhost/"))) {
-
      client.Connect("pass");
 

        

        
~
ここでは接続時と認証時の動作について解説します。
      using (var inbox = client.OpenInbox()) {
-
        var message = inbox.GetMessageByUid(1);
 

        

        
~
***&aname(connect){接続};
        File.WriteAllBytes("sample.eml", message.ReadAllBytes());
~
接続時の動作は、接続時のパラメータにより次のように変わります。
      }
-
    }
-
  }
-
}
-
}}
 

        

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

        

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

        

        
~
例として接続先のURLと接続時の動作を表にまとめると以下のようになります。
class Sample {
-
  public static void Main(string[] args)
-
  {
-
    ImapWebRequestCreator.RegisterPrefix();
 

        

        
~
|*URLと接続動作の例
    using (var client = new WebClient()) {
~
|~URL|~接続ポート|~SSL/TLS|h
      client.Credentials = new NetworkCredential("user", "pass");
~
|imaps://user@imap.example.net/|993|SSL/TLSを使用|
      client.UploadData("imap://user;AUTH=DIGEST-MD5@localhost/INBOX", ImapWebRequestMethods.Append, File.ReadAllBytes("sample.eml"));
~
|imaps://user@imap.example.net:10143/|10143|SSL/TLSを使用|
    }
~
|imap://user@imap.example.net/|143|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
  }
~
|imap://user@imap.example.net:993/|993|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
}
-
}}
 

        

        
~
これら接続時のパラメータは次の箇所で指定します。
#code(cs,ImapClientクラスを使う場合){{
~
:URLのスキーム&sup{*1};|[[ImapClientクラス>#ImapClient.login]]のコンストラクタに指定するURLのスキーム、もしくは[[ImapWebRequestクラス>#ImapWebRequest.login]]に指定するリクエストURL
using System;
~
:SecurePortプロパティ&sup{*2};|[[ImapClientクラス>#ImapClient.login]]のコンストラクタで指定する引数securePort、もしくはImapClient.Profile.SecurePortプロパティ
using System.IO;
~
:UseTlsIfAvailableプロパティ&sup{*3};|[[ImapClient.Profile.UseTlsIfAvailableプロパティ>#ImapClient.login]]、もしくは[[ImapWebRequest.UseTlsIfAvailableプロパティ>#ImapWebRequest.login]]
using System.Net;
 

        

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

        

        
~
認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
class Sample {
~
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
  public static void Main(string[] args)
~
+LOGINコマンド (サーバが許可している場合のみ)
  {
-
    using (var client = new ImapClient("localhost", 143, "user", "DIGEST-MD5")) {
-
      client.Connect("pass");
 

        

        
~
URLもしくはパラメータでユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。
      using (var inbox = client.OpenInbox()) {
-
        using (var messageStream = File.OpenRead("sample.eml")) {
-
          inbox.AppendMessage(messageStream);
-
        }
-
      }
-
    }
-
  }
-
}
-
}}
 

        

        
~
認証方式の大文字小文字の違いは無視します(IMAP URLの場合は';AUTH='の部分も大文字小文字を無視します)。
**メッセージの検索
-
Gmailアカウントのメールボックスからタイトルに[Mono-dev]を含むメールの一覧を取得する例。
-
#code(cs,WebRequestクラスを使う場合){{
-
using System;
-
using System.Net;
 

        

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

        

        
~
|*URLと認証動作の例
class Sample {
~
|~URL|~ユーザ名|~使用する認証メカニズム|h
  public static void Main(string[] args)
~
|imap://user;AUTH=DIGEST-MD5@imap.example.net/|user|DIGEST-MD5|
  {
~
|imap://;AUTH=DIGEST-MD5@imap.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
    ImapWebRequestCreator.RegisterPrefix();
~
|imap://user;AUTH=*@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
    ImapSessionManager.ServerCertificateValidationCallback = delegate { return true; };
+
|imap://user@imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
+
|imap://;AUTH=ANONYMOUS@imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
+
|imap://imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはLOGINコマンドを使用|
 

        

        
~
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
    var request = WebRequest.Create("imaps://user@imap.gmail.com/INBOX?SUBJECT \"[Mono-dev]\"");
 

        

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

        

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

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

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

          
}
+
**&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};を作成します。
+

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

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

          
+
**IMAPコマンドの引数およびレスポンスのデータ型
+
(このドキュメントは作成中です)
+
-ImapStoreDataItem
+
-ImapSearchCriteria
+
-ImapSortCriteria
+
-IImapBodyStructure
+
-IImapMessageFlagSet
+
-IImapMailboxFlagSet
+

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

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

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

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

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

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

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

          
+
#hr
+

          
+
*&aname(ImapClient){ImapClientクラス (Smdn.Net.Imap4.Client.dll)};
+
ImapClientクラスおよびSmdn.Net.Imap4.Client名前空間のクラスの使い方。
+

          
+
**概説
+
基本的には、
+
+ImapClientクラスのインスタンスを作成
+
+ImapClient.Connect()メソッドでサーバに接続
+
+ImapClient.GetInbox(), GetMailbox(), CreateMailbox()などのメソッドでImapMailboxクラスのインスタンスを取得
+
+ImapClient.OpenInbox(), OpenMailbox()もしくはImapMailbox.Open()などのメソッドでImapOpenedMailboxInfoクラスのインスタンスを取得
+
+ImapOpenedMailboxInfo.GetMessage(), GetMessages()などのメソッドでImapMessageInfoクラスのインスタンスを取得
+
+ImapMessageInfo.Open*(), Read*(), Save()などのメソッドでメッセージ本文を取得
+

          
+
の順でサーバ上のメールボックス・メッセージの取得と操作を行います。 以下でImapClientと関連するクラスの使い方について解説します。
+

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

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

          
+
client1.Connect("pass");
+

          
+
/*
+
 * ホスト"imap.example.net"のポート10143に接続、可能ならSSL/TLSにアップグレード。
+
 * ユーザ名に"user"を使用、パスワードはNetworkCredentialから取得。 認証方式はCRAM-MD5を試行。
+
 */
+
var client2 = new ImapClient(new Uri("imap://user;AUTH=CRAM-MD5@imap.example.net:10143/"));
+

          
+
client2.Profile.UseTlsIfAvailable = true;
+
client2.Connect(new NetworkCredential("user", "pass"));
+

          
+
/*
+
 * ホスト"imap.example.net"のポート10143にSSL/TLSを用いて接続。
+
 * ユーザ名に"user"、パスワードに"pass"を使用。 認証方式はDIGEST-MD5を試行。
+
 */
+
var client3 = new ImapClient("imap.example.net", 10143, true, "user", "DIGEST-MD5");
+

          
+
client3.Connect("pass");
+

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

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

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

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

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

        

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

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

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

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

          
+
using System.Security.Cryptography.X509Certificates;
 
using Smdn.Net.Imap4;
using Smdn.Net.Imap4;
 
using Smdn.Net.Imap4.Client;
using Smdn.Net.Imap4.Client;
 
using Smdn.Net.Imap4.Protocol.Client;
using Smdn.Net.Imap4.Protocol.Client;
 

        

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

        

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

        

        
~
  private static bool ValidateRemoteCertificate(object sender,
      using (var inbox = client.OpenInbox()) {
~
                                                X509Certificate certificate,
        foreach (var message in inbox.GetMessages(ImapSearchCriteria.Subject("[Mono-dev]"))) {
~
                                                X509Chain chain,
          Console.WriteLine("UID {0}: {1}", message.Uid, message.Envelope.Subject);
~
                                                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接続時の動作をデフォルトからカスタマイズしたい場合は、ImapClient.Connect()メソッドの引数に適切なコールバックメソッドを指定してください。
*ライブラリの設計と実装の概要
~
(このドキュメントは作成中です)
クライアントの実装は次の3種類があります。
-
+Smdn.Net.Imap4.Client.Session名前空間のImapSessionクラス
-
+Smdn.Net.Imap4.Client名前空間のImapClientクラス
-
+Smdn.Net.Imap4.WebClients名前空間のImapWebRequest/ImapWebResponseクラス
-

          
-
三つのクライアントのモデルと概要は次の通りです。
-

          
-
:ImapSessionクラス|IMAPのコマンドとほぼ1対1で対応するメソッドを持つクラスです。 IMAPの操作は抽象化していません。 仕様と1対1で対応するような実装にしてあります。
-
切断する/されるまで選択済みメールボックス・メールボックス毎のフラグ・サーバの能力・名前空間等のセッションの状態を保持します。 このクラスは他の2種類のクライアント実装で使用しています。
-
:ImapClientクラス|IMAPの操作を抽象化したクラスです。 メールボックス/メッセージをSystem.IO.DirectoryInfo/FileInfoクラスに似たインターフェイスで操作できるようにしてあります。
-
:ImapWebRequest/ImapWebResponseクラス|IMAP URL(&urn2url(urn:ietf:rfc:5092,short);)を用いたクライアントの実装です。 IMAP URLの形式でIMAPの操作を行うので、送信されるIMAPコマンドをあまり意識せずに扱えます。 System.Net.WebRequest/System.Net.WebResponseを継承しているので、メッセージのダウンロード・アップロードにWebClientクラスのメソッドを使うこともできます。
-
FtpWebRequest等と同様、WebRequest.Methodプロパティで送信するコマンドを制御できます。
 

        

        
~
**操作
以下でクライアント実装に共通する部分について解説します。 個々のクライアント実装の詳細については各項を参照してください。
+
Smdn.Net.Imap4.Client名前空間のクラスを使ったIMAPの操作は、それぞれ以下のクラスのインスタンスを用いて行います。
+
(このドキュメントは作成中です)
+

          
+
:ImapClient|クライアント本体のクラス。
+
:ImapMailboxInfo|単一のメールボックスを表すクラス。
+
:ImapOpenedMailboxInfo|選択済みメールボックスを表すクラス。 ImapMailboxInfoから派生。
+
:ImapMessageInfoBase|単一もしくは複数のメッセージに対する操作を定義したクラス。
+
:ImapMessageInfo|単一のメッセージを表すクラス。 ImapMessageInfoBaseから派生。
+
:ImapMailboxInfoList|複数のメッセージを表すクラス。 ImapMessageInfoBaseから派生。 IEnumerable<ImapMessageInfo>を実装。
+

          
+
ImapClient以外のクラスのインスタンスは直接作成することはできません。
+

          
+
***接続・切断
+
以下は接続・切断に関するメソッドとプロパティです。
+
(このドキュメントは作成中です)
+

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

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

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

          
+
***メールボックスの取得と作成
+
以下はメールボックスの取得と作成に関するメソッドです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapClientクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetInbox()&br;GetInbox(ImapMailboxListOptions)|INBOXを取得します。|LIST/LSUB|
+
|GetMailbox(string)&br;GetMailbox(string, ImapMailboxListOptions)|指定した名前のメールボックスを取得します。|LIST/LSUB|
+
|GetMailboxes()&br;GetMailboxes(ImapMailboxListOptions)|すべてのメールボックスを取得します。|LIST/LSUB|
+
|GetOrCreateMailbox(string)&br;GetOrCreateMailbox(string, ImapMailboxListOptions)&br;GetOrCreateMailbox(string, bool)&br;GetOrCreateMailbox(string, bool, ImapMailboxListOptions)|指定した名前のメールボックスを取得します。 存在しない場合は作成します。 オプションで、メールボックスを作成した場合に購読するかどうか指定できます。|LIST/LSUB, CREATE, SUBSCRIBE|
+
|CreateMailbox(string)&br;CreateMailbox(string, bool)|指定した名前のメールボックスを作成します。|CREATE, SUBSCRIBE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetMailboxes()&br;GetMailboxes(ImapMailboxListOptions)|現在のメールボックスの下位にあるすべてのメールボックスを取得します。|LIST/LSUB|
+
|GetParent()&br;GetParent(ImapMailboxListOptions)|現在のメールボックスの上位のメールボックスを取得します。|LIST/LSUB|
+
|GetOrCreateParent()&br;GetOrCreateParent(ImapMailboxListOptions)&br;GetOrCreateParent(bool)&br;GetOrCreateParent(bool, ImapMailboxListOptions)|現在のメールボックスの上位のメールボックスを取得します。 存在しない場合は作成します。|LIST/LSUB, CREATE, SUBSCRIBE|
+
|GetOrCreateChild(string)&br;GetOrCreateChild(string, ImapMailboxListOptions)&br;GetOrCreateChild(string, bool)&br;GetOrCreateChild(string, bool, ImapMailboxListOptions)|現在のメールボックスの下位にある指定した名前のメールボックスを取得します。 存在しない場合は作成します。 オプションで、メールボックスを作成した場合に購読するかどうか指定できます。|LIST/LSUB, CREATE, SUBSCRIBE|
+
|CreateChild(string)&br;CreateChild(string, bool)|現在のメールボックスの下位に指定した名前でメールボックスを作成します。|CREATE, SUBSCRIBE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
:すべてのメソッド|これらのメソッドは、メールボックスを表すImapMailboxInfoクラスのインスタンス、もしくはIEnumerable<ImapMailboxInfo>を返します。
+
:ImapClient.GetMailboxes(), ImapMailboxInfo.GetMailboxes()|これらのメソッドは、このメソッドは遅延実行を使用して実装されます。 実際に列挙を開始するまで、コマンドの送受信は行われません。
+
:メールボックスの取得オプション(ImapMailboxListOptions)|これらのメソッドには、ImapMailboxListOptionsを引数にとるバージョンのオーバーロードを用意してあります。 ImapMailboxListOptionsを指定することで、メールボックスの取得時の動作を変更することができます。 以下の値を組み合わせて指定できます。
+
::SubscribedOnly|存在するメールボックスのうち、購読中のメールボックスのみを取得します。 このオプションを指定しない場合は、購読中かどうかを区別せずに取得します。
+
::TopLevelOnly|存在するメールボックスのうち、直下の階層にあるメールボックスのみを取得します。 このオプションを指定しない場合は、すべての階層にあるメールボックスを取得します。
+
::Remote|存在するメールボックスのうち、リモートサーバ上にあるメールボックスのみを取得します。 このオプションを指定しない場合は、リモートサーバ上のメールボックスかどうか区別せずに取得します。 サーバがMAILBOX REFERRALSに対応している場合のみ有効です。
+
::RequestStatus|メールボックスの取得と同時に、メールボックスのメッセージ数などのステータスも取得します。 このオプションを指定しない場合は、ステータスは取得しません。
+
::Default|オプションのデフォルト値です。 上記オプションのいずれも指定しない場合と同値です。
+

          
+
***メールボックスの選択
+
以下はメールボックスの選択に関するメソッドです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapClientクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|OpenInbox()&br;OpenInbox(bool)|INBOXを開きます。 オプションで読み取り専用で開くかどうかを指定できます。|SELECT/EXAMINE|
+
|OpenMailbox(ImapMailboxInfo)&br;OpenMailbox(ImapMailboxInfo, bool)|指定したインスタンスが表すメールボックスを開きます。 オプションで読み取り専用で開くかどうかを指定できます。|SELECT/EXAMINE|
+
|OpenMailbox(string)&br;OpenMailbox(string, bool)&br;OpenMailbox(string, ImapMailboxListOptions)&br;OpenMailbox(string, ImapMailboxListOptions, bool)|指定した名前のメールボックスを開きます。 オプションで読み取り専用で開くかどうかを指定できます。|SELECT/EXAMINE|
+

          
+
|*ImapMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|Open()&br;Open(bool)|インスタンスが表すメールボックスを開きます。  オプションで読み取り専用で開くかどうかを指定できます。|SELECT/EXAMINE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapClientクラスのプロパティ
+
|~プロパティ|~解説|h
+
|OpenedMailbox|現在開いているメールボックスのインスタンスを取得します。 開いていない場合はnullを返します。|
+

          
+
:すべてのメソッド|これらのメソッドは、選択済みメールボックスを表すImapOpenedMailboxInfoクラスのインスタンスを返します。
+

          
+
***メールボックスの操作
+
以下はメールボックスの操作に関するメソッドとプロパティです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|Refresh()|メールボックスのステータスを更新します。|STATUS|
+
|Delete()&br;Delete(bool)|メールボックスが存在する場合、削除します。 オプションで購読解除するかどうか指定できます。|DELETE, UNSUBSCRIBE|
+
|Create()&br;Create(bool)|メールボックスが存在しない場合、作成します。 オプションで購読するかどうか指定できます。|CREATE, SUBSCRIBE|
+
|MoveTo(ImapMailboxInfo)&br;MoveTo(ImapMailboxInfo, bool)|メールボックスを指定したメールボックスの下位に移動します。|RENAME, SUBSCRIBE, UNSUBSCRIBE|
+
|MoveTo(string)&br;MoveTo(string, bool)|メールボックスを指定した名前に変更します。|RENAME, SUBSCRIBE, UNSUBSCRIBE|
+
|Subscribe()&br;Subscribe(bool)|メールボックスを購読します。 オプションで、下位にあるすべてのメールボックスも購読するかどうか指定できます。|SUBSCRIBE, LIST/LSUB|
+
|Unsubscribe()&br;Unsubscribe(bool)|メールボックスを購読解除します。 オプションで、下位にあるすべてのメールボックスも購読解除するかどうか指定できます。|UNSUBSCRIBE, LIST/LSUB|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapMailboxInfoクラスのプロパティ
+
|~プロパティ|~解説|h
+
|FullName|階層を含むメールボックスの完全な名前を返します。|
+
|Name|階層を含まないメールボックスの名前を返します。|
+
|ParentMailboxName|上位のメールボックスを返します。 インスタンスが最上位のメールボックスを表す場合、空の文字列を返します。|
+
|MailboxSeparator|メールボックスの階層区切り文字を返します。 メールボックスが階層構造を持たない場合、空の文字列を返します。|
+
|Url|メールボックスを表すIMAP URLを返します。|
+
|Exists|メールボックスが存在するかどうかを表す値を返します。|
+
|Flags|メールボックスの属性を表すフラグを返します。|
+
|IsUnselectable|メールボックスが選択不可とされているかどうかを表す値を返します。 値がtrueの場合、Open()などのメソッドでメールボックスを選択することはできません。 値がfalseの場合でも、選択できないか選択に失敗する可能性があります。|
+
|IsOpen|メールボックスが選択中であるかどうかを表す値を返します。|
+
|IsInbox|メールボックスがINBOXであるかどうかを表す値を返します。|
+
|CanHaveChild|下位のメールボックスを作成できるか(メールボックスが階層構造を持つことができるか)どうかを表す値を返します。 値がfalseの場合、CreateChild()などのメソッドで下位のメールボックスを作成することはできません。|
+
|UnseenMessageCount|メールボックスにある未読のメッセージ数を返します。 ステータスを取得していない場合、0を返します。|
+
|ExistMessageCount|メールボックスに存在するすべてのメッセージ数を返します。 ステータスを取得していない場合、0を返します。|
+
|RecentMessageCount|メールボックスにある新着のメッセージ数を返します。 ステータスを取得していない場合、0を返します。|
+
|UidValidity|メールボックスのUIDVALIDITY値を返します。 UIDが永続的でない場合などは、0を返します。|
+
|NextUid|メールボックスの次のメッセージに付与されるUIDを返します。 UIDが永続的でない場合などは、0を返します。|
+
|~プロパティ|~解説|f
+

          
+
***選択済みメールボックスの操作
+
以下は選択済みメールボックスの操作に関するメソッドとプロパティです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapOpenedMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|Refresh()|メールボックスの状態を更新します。 サーバからメールボックスの状態に関する通知があった場合はイベントを発生させます。|NOOP|
+
|Expunge()|メールボックスにある削除フラグが設定されているメッセージをすべて削除します。|EXPUNGE|
+
|Close()&br;IDisposable.Dispose()|メールボックスを閉じます。|CLOSE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapClientクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|CloseMailbox()|選択済みのメールボックスがある場合、メールボックスを閉じます。 ない場合は何もしません。|CLOSE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapOpenedMailboxInfoクラスのプロパティ
+
|~プロパティ|~解説|h
+
|IsReadOnly|メールボックスを読み取り専用で選択したかどうかを表す値を返します。|
+
|IsUidPersistent|メールボックス内の各メッセージに割り当てられているUIDが永続的かどうかを表す値を返します。|
+
|IsAllowedToCreateKeywords|メールボックス内の各メッセージに、ユーザ定義のキーワードを設定できるかどうかを表す値を返します。|
+
|ApplicableFlags|メールボックス内の各メッセージに設定できるフラグ・キーワードの一覧を返します。|
+
|PermanentFlags|メールボックス内で永続的に保持されるフラグ・キーワードの一覧を返します。|
+
|FirstUnseenMessageNumber|メールボックスを選択した時点で最初の未読メッセージの通番を返します。 未読メッセージがない場合は0を返します。|
+
|~プロパティ|~解説|f
+

          
+
***メッセージの取得
+
以下はメッセージの取得に関するメソッドです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapOpenedMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetMessages()&br;GetMessages(ImapMessageFetchAttributeOptions)|メールボックスにあるすべてのメッセージを取得します。|FETCH|
+
|GetMessages(long, params long[])&br;GetMessages(ImapMessageFetchAttributeOptions, long, params long[])|メールボックスにあるメッセージのうち、指定したUIDを持つ1つ以上のメッセージを取得します。|FETCH|
+
|GetMessageByUid(long)&br;GetMessageByUid(long, ImapMessageFetchAttributeOptions)|メールボックスにあるメッセージのうち、指定したUIDを持つ1つのメッセージを取得します。|FETCH|
+
|GetMessageBySequence(long)&br;GetMessageBySequence(long, ImapMessageFetchAttributeOptions)|メールボックスにあるメッセージのうち、指定した通番を持つ1つのメッセージを取得します。|FETCH|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapMessageInfoListクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetEnumerator()|ImapMessageInfoListインスタンスに対して列挙操作を行うことにより、ImapMessageInfoインスタンスを取得できます。|FETCH|
+

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

          
+
//:ImapClient.GetMailboxes(), ImapMailboxInfo.GetMailboxes()|これらのメソッドは、このメソッドは遅延実行を使用して実装されます。 実際に列挙を開始するまで、コマンドの送受信は行われません。
+

          
+
:メッセージ属性の取得オプション(ImapMessageFetchAttributeOptions)|これらのメソッドには、ImapMessageFetchAttributeOptionsを引数にとるバージョンのオーバーロードを用意してあります。 ImapMessageFetchAttributeOptionsを指定することで、メッセージ取得時に取得する属性を指定することができます。 以下の値を組み合わせて指定できます。
+
::StaticAttributes|メッセージに設定される静的な属性のみを取得します。
+
::DynamicAttributes|メッセージに設定される動的な属性のみを取得します。
+
::AllAttributes|メッセージに設定されるすべての属性を取得します。 StaticAttributesとDynamicAttributesの組み合わせと同値です。
+
::Default, None|オプションのデフォルト値です。 上記オプションのいずれも指定しない場合と同値です。
+
:ImapMessageInfoList.GetEnumerator()|このメソッドは、このメソッドは遅延実行を使用して実装されます。 実際に列挙を開始するまで、コマンドの送受信は行われません。
 

        

        
~
***メッセージの検索
**資格情報
~
以下はメッセージの検索に関するメソッドです。
認証時に必要なユーザ名・パスワードはSystem.Net.ICredentialsByHostインターフェイスを通して取得します。 ICredentialsインターフェイスではなく、ICredentialsByHostインターフェイスを実装していて、GetCredentialメソッドが適切なSystem.Net.NetworkCredentialを返すクラスなら何でも設定できます。
+
(このドキュメントは作成中です)
 

        

        
~
|*ImapOpenedMailboxInfoクラスのメソッド
ImapWebRequest.CredentialsプロパティはWebRequestから継承しているためICredentialsインターフェイスを実装していることを要求しますが、設定されるインスタンスはICredentialsByHostも実装している必要があります。
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetMessages(ImapSearchCriteria)&br;GetMessages(ImapSearchCriteria, ImapMessageFetchAttributeOptions)&br;GetMessages(ImapSearchCriteria, Encoding)&br;GetMessages(ImapSearchCriteria, Encoding, ImapMessageFetchAttributeOptions)|指定した検索条件にマッチするメッセージを取得します。 オプションでエンコーディングを指定できます。|SEARCH|
+
|GetSortedMessages(ImapSortCriteria, ImapSearchCriteria)&br;GetSortedMessages(ImapSortCriteria, ImapSearchCriteria, ImapMessageFetchAttributeOptions)&br;GetSortedMessages(ImapSortCriteria, ImapSearchCriteria, Encoding)&br;GetSortedMessages(ImapSortCriteria, ImapSearchCriteria, Encoding, ImapMessageFetchAttributeOptions)|指定した検索条件にマッチするメッセージを、指定したソート条件でソート済みの状態で取得します。 オプションでエンコーディングを指定できます。&br;サーバがSORTコマンドをサポートしていない場合は、失敗します。|SORT|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
***メッセージ本文の取得
+
以下はメッセージ本文の取得に関するメソッドです。
+
(このドキュメントは作成中です)
+

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

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

          
+
***メッセージの操作
+
以下はメッセージの操作に関するメソッドです。 これらのメソッドは、ImapMessageInfoBaseクラスから派生したImapMessageInfoクラスおよびImapMessageInfoListクラスで使用できます。
+
(このドキュメントは作成中です)
+

          
+
|*ImapMessageInfoBaseクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|AddFlags(IImapMessageFlagSet)&br;AddFlags(ImapMessageFlag, params ImapMessageFlag[])&br;AddKeywords(string, params string[])|1つまたは複数のメッセージに対して、指定したフラグ・キーワードを追加します。|STORE|
+
|RemoveFlags(IImapMessageFlagSet)&br;RemoveFlags(ImapMessageFlag, params ImapMessageFlag[])&br;RemoveKeywords(string, params string[])|1つまたは複数のメッセージから、指定したフラグ・キーワードを削除します。|STORE|
+
|ReplaceFlags(IImapMessageFlagSet)&br;ReplaceFlags(ImapMessageFlag, params ImapMessageFlag[])&br;ReplaceKeywords(string, params string[])|1つまたは複数のメッセージに設定されているフラグ・キーワードを、指定したフラグ・キーワードに置き換えます。|STORE|
+
|Store(ImapStoreDataItem)|1つまたは複数のメッセージに対して、指定したフラグ・キーワードの追加/削除/置き換えを行います。|STORE|
+
|MarkAsDeleted()|1つまたは複数のメッセージに削除フラグを設定します。|STORE|
+
|MarkAsSeen()|1つまたは複数のメッセージを既読にします。|STORE|
+
|Delete()|1つまたは複数のメッセージを完全に削除します。&br;サーバがUID EXPUNGEをサポートしていない場合、''既に削除フラグが設定されている他のメッセージも同時に削除されます''。|STORE, EXPUNGE/UID EXPUNGE|
+
|CopyTo(ImapMailboxInfo)|1つまたは複数のメッセージを、指定したメールボックスにコピーします。|COPY|
+
|CopyTo(string)&br;CopyTo(string, bool)|1つまたは複数のメッセージを、指定した名前のメールボックスにコピーします。 オプションで、メールボックスが存在しない場合に作成するかどうかを指定できます。|COPY|
+
|MoveTo(ImapMailboxInfo)|1つまたは複数のメッセージを、指定したメールボックスに移動します。&br;サーバがUID EXPUNGEをサポートしていない場合、移動と同時に''既に削除フラグが設定されている他のメッセージも削除されます''。|COPY, EXPUNGE/UID EXPUNGE|
+
|MoveTo(string)&br;MoveTo(string, bool)|1つまたは複数のメッセージを、指定した名前のメールボックスに移動します。 オプションで、メールボックスが存在しない場合に作成するかどうかを指定できます。&br;サーバがUID EXPUNGEをサポートしていない場合、移動と同時に''既に削除フラグが設定されている他のメッセージも削除されます''。|COPY, EXPUNGE/UID EXPUNGE|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
***単一メッセージの操作
+
以下は単一のメッセージの操作に関するメソッドとプロパティです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapMessageInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|Refresh()|メッセージの動的属性を更新します。|FETCH|
+
|ToggleFlags(IImapMessageFlagSet)&br;ToggleFlags(ImapMessageFlag, params ImapMessageFlag[])&br;ToggleKeywords(string, params string[])|メッセージに設定されているフラグ・キーワードを反転します。&br;例として、メッセージに削除フラグが設定されている場合はフラグを削除し、設定されていない場合は追加します。|STORE|
+
|GetStructureOf(string)&br;GetStructureOf<TBodyStructure>(string)&br;GetStructureOf(params int[])&br;GetStructureOf<TBodyStructure>(params int[])|指定したセクションに該当するBODYSTRUCTUREを取得します。&br;文字列"1.2.3"の指定と数値{1,2,3}の指定は等価です。 また、文字列""の指定と数値{}の指定は等価です。|FETCH|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapMessageInfoクラスのプロパティ
+
|~プロパティ|~解説|h
+
|Uid|メッセージに割り当てられているUIDを返します。|
+
|Sequence|メッセージに割り当てられている現在の通番を返します。 削除されている場合(IsDeletedがtrueの場合)は0を返します。|
+
|UidValidity|メッセージを取得した時点でのメールボックスのUIDVALIDITY値を返します。 UIDが永続的でない場合(ImapOpenedMailboxInfo.IsUidPersistentがfalseの場合)などは、0を返します。|
+
|Url|メッセージをIMAP URLを返します。|
+
|Mailbox|メッセージが属するメールボックスを表すインスタンスを返します。|
+
|IsDeleted|メッセージが完全に削除されているかどうかを表す値を返します。|
+
|IsAnswered|メッセージが返信済みかどうかを表す値を返します。 \Answeredフラグが設定されている場合trueを返します。|
+
|IsDraft|メッセージが下書きかどうかを表す値を返します。 \Draftフラグが設定されている場合trueを返します。|
+
|IsFlagged|メッセージが「フラグ済み」かどうかを表す値を返します。 \Flaggedフラグが設定されている場合trueを返します。|
+
|IsMarkedAsDeleted|メッセージが削除予定かどうかを表す値を返します。 \Deletedフラグが設定されている場合trueを返します。|
+
|IsRecent|メッセージが新着かどうかを表す値を返します。 \Recentフラグが設定されている場合trueを返します。|
+
|IsSeen|メッセージが既読かどうかを表す値を返します。 \Seenフラグが設定されている場合trueを返します。|
+
|Flags|メッセージに設定されているフラグ・キーワードの一覧を返します。|
+
|IsMultiPart|メッセージがマルチパート形式のメッセージかどうかを表す値を返します。|
+
|MediaType|メッセージのメディアタイプを返します。|
+
|Length|メッセージのサイズをバイト単位で返します。|
+
|Envelope|メッセージのエンベロープを表すImapEnvelopeのインスタンスを返します。|
+
|EnvelopeDate|メッセージのDateヘッダをパースした値をNullable<DateTimeOffset>で返します。 パースに失敗した場合は、DateTimeOffsetのデフォルト値を返します。 Dateヘッダがない場合などは、nullを返します。|
+
|EnvelopeSubject|メッセージのSubjectヘッダをデコードした値をstringで返します。 デコードに失敗した場合は、デコードされていない状態で返します。 Subjectヘッダがない場合などは、nullを返します。|
+
|InternalDate|メッセージがメールボックスに追加された(受信もしくはアップロードした)日時をDateTimeOffsetで返します。|
+
|BodyStructure|メッセージのBODYSTRUCTUREを表すIImapBodyStructureのインスタンスを返します。|
+
|~プロパティ|~解説|f
+
//|ModSeq||
+

          
+
:動的属性を表すプロパティ|メッセージ取得時に動的属性を取得するように指定しなかった場合、プロパティの値を参照する際、コマンドを発行してから結果を返します。
+
::該当するプロパティ|IsAnswered, IsDraft, IsFlagged, IsMarkedAsDeleted, IsRecent, IsSeen, Flags
+
:静的属性を表すプロパティ|メッセージ取得時に静的属性を取得するように指定しなかった場合、プロパティの値を参照する際、コマンドを発行してから結果を返します。
+
::該当するプロパティ|BodyStructure, Envelope, EnvelopeDate, EnvelopeSubject, InternalDate, Length, MediaType, IsMultiPart
+

          
+
***メッセージのアップロード(メールボックスへの追加)
+
以下はメールボックスにメッセージをアップロードするためのメソッドです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|AppendMessage(Stream)&br;AppendMessage(Stream, DateTimeOffset)&br;AppendMessage(Stream, IImapMessageFlagSet)&br;AppendMessage(Stream, DateTimeOffset, IImapMessageFlagSet)|指定したStreamの内容をメールボックスにアップロードします。 オプションでメッセージに設定するINTERNALDATE, フラグ・キーワードを指定できます。|APPEND|
+
|AppendMessage(IImapAppendMessage message)|指定したIImapAppendMessageで表されるメッセージをメールボックスにアップロードします。|APPEND|
+
|AppendMessages(IEnumerable<IImapAppendMessage>)|指定したIImapAppendMessageで表される複数のメッセージをメールボックスにアップロードします。|APPENDもしくはMULTIAPPEND|
+
|WriteMessage(Action<Stream>)&br;WriteMessage(DateTimeOffset, Action<Stream>)&br;WriteMessage(IImapMessageFlagSet, Action<Stream>)&br;WriteMessage(DateTimeOffset, IImapMessageFlagSet flags, Action<Stream>)|メッセージを書き込むためのStreamを取得し、書き込んだ内容をメールボックスにアップロードします。 オプションでメッセージに設定するINTERNALDATE, フラグ・キーワードを指定できます。|APPEND|
+
|WriteMessage(long, Action<Stream>)&br;WriteMessage(long, DateTimeOffset, Action<Stream>)&br;WriteMessage(long, IImapMessageFlagSet, Action<Stream>)&br;WriteMessage(long, DateTimeOffset, IImapMessageFlagSet, Action<Stream>)|指定したサイズのメッセージを書き込むためのStreamを取得し、書き込んだ内容をメールボックスにアップロードします。 オプションでメッセージに設定するINTERNALDATE, フラグ・キーワードを指定できます。|APPEND|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
***サーバからの通知
+
以下はサーバからの通知をハンドリングするためのイベントです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapClientクラスのイベント
+
|~イベント|~解説|h
+
|ExistMessageCountChanged|現在選択しているメールボックスにあるすべてのメッセージの数が変わった場合に発生します。&br;イベント発生前後のメッセージ数と、現在選択しているメールボックスのImapOpenedMailboxInfoを含むImapMailboxSizeChangedEventArgsが送られます。|
+
|RecentMessageCountChanged|現在選択しているメールボックスにある新着メッセージの数が変わった場合に発生します。&br;イベント発生前後のメッセージ数と、現在選択しているメールボックスのImapOpenedMailboxInfoを含むImapMailboxSizeChangedEventArgsが送られます。|
+
|MessageDeleted|現在選択しているメールボックスにあるメッセージが削除された場合に発生します。&br;削除されたメッセージのImapMessageInfo[]を含むImapMessageStatusChangedEventArgsが送られます。|
+
|MessageStatusChanged|現在選択しているメールボックスにあるメッセージの動的属性が変更された場合に発生します。&br;属性が変更されたメッセージのImapMessageInfo[]を含むImapMessageStatusChangedEventArgsが送られます。|
+
|~メソッド|~解説|f
+

          
+
***クォータ
+
以下はクォータに関するメソッドです。
+
(このドキュメントは作成中です)
+

          
+
|*ImapClientクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetQuota(string)|指定した名前のクォータルートの状態を取得します。 サーバがQUOTAをサポートしていない場合はnullを返します。|GETQUOTA|
+
|GetQuotaUsage(string, string)|指定した名前のクォータルートのうち、指定したリソースの使用率を0.0から1.0までのdouble値で返します。 サーバがQUOTAをサポートしていない場合、上限が0の場合は0.0を返します。|GETQUOTA|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
|*ImapMailboxInfoクラスのメソッド
+
|~メソッド|~解説|~対応するIMAPコマンド|h
+
|GetQuota()|メールボックスに割り当てられているクォータの一覧をIEnumerable<ImapQuota>で返します。 サーバがQUOTAをサポートしていない場合は、空のIEnumerable<ImapQuota>を返します。|GETQUOTAROOT|
+
|~メソッド|~解説|~対応するIMAPコマンド|f
+

          
+
**例外
+
(このドキュメントは作成中です)
+

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

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

          
+
なお、アプリケーションドメインをまたがる使用については全く考慮していないため、動作および安全性の保証はできません。
+

          
+
#hr
+

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

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

        

        
~
の順でIMAPコマンドを実行、レスポンスを取得します。 以下でImapWebRequest/ImapWebResponseクラスに固有な部分について解説します。
**証明書の選択と検証
-
SSL/TLS接続時に使用する証明書はX509Certificate2Collectionで設定できます。 また、証明書の選択と検証にはRemoteCertificateValidationCallbackデリゲートとLocalCertificateSelectionCallbackデリゲートを使用できます。
 

        

        
~
**imap, imapsスキームの登録
|*証明書に関する型と該当するメンバ(いずれもクラス・プロパティ)
~
WebRequestクラスがimapスキームおよびimapsスキームのURLを処理できるように、ImapWebRequest/ImapWebResponseクラスを使う前にImapWebRequestCreator.RegisterPrefixメソッドを呼び出しておく必要があります。
|~証明書に関する型|>|~該当するメンバ|h
-
|~|~Smdn.Net.Imap4.Protocol.Client名前空間|~Smdn.Net.Imap4.WebClients名前空間|
-
|X509Certificate2Collection|ImapConnection.ClientCertificates|ImapSessionManager.ClientCertificates|
-
|RemoteCertificateValidationCallback|ImapConnection.ServerCertificateValidationCallback|ImapSessionManager.ServerCertificateValidationCallback|
-
|LocalCertificateSelectionCallback|ImapConnection.ClientCertificateSelectionCallback|ImapSessionManager.ClientCertificateSelectionCallback|
 

        

        
~
このメソッドはWebRequest.RegisterPrefixメソッドを呼び出し、imapスキームおよびimapsスキームに対してImapWebRequestCreatorを関連付けます。
**操作とデータ構造
-
ImapSessionクラスには、IMAPコマンドと1対1に対応するメソッドが用意されています。 また、すべてのコマンドの引数とレスポンスのデータ構造は、それに対応する型が定義されています。 これらの型は出来る限り仕様と1対1で対応するように実装してあり、IMAPの詳細が分からなくても使えることを目的とするような抽象化はしていません。
 

        

        
~
#code(cs,記述例){{
**メールボックスのインスタンス
~
using System;
メールボックスの情報はImapMailboxクラスに保持されます。 このクラスのインスタンスは、LIST/SELECT/CREATEコマンド等により作成された後は、ログアウトするまでライブラリ側で管理されます。 同じメールボックスに対してSELECTしたりRENAMEした場合はインスタンスの値のみが更新され、常に同じインスタンスが返されます。
+
using System.Net;
+
using Smdn.Net.Imap4;
+
using Smdn.Net.Imap4.WebClients;
 

        

        
~
  :
**ログ
~
  :
シンボルTRACEを有効にしてビルドした場合、トレースにログを出力します。 ログにはパスワードを含む内容を平文で出力します。 ログの出力が不要な場合はTrace.csを削除するか、TRACEを無効にしてリビルドしてください。
+
// imapおよびimapsスキームの登録
+
ImapWebRequestCreator.RegisterPrefix();
 

        

        
~
// ImapWebRequestインスタンスの作成
|*ログ出力に使用するTraceSourceの名前と出力内容
~
var request = WebRequest.Create("imap://user@imap.example.net/");
|TraceSourceの名前|出力内容|h
~
  :
|Smdn.Net.Imap4.Client|コマンドの送受信結果とセッション毎の動作ログを出力します。|
~
  :
|Smdn.Net.MessageAccessProtocols|送信するコマンドと受信したレスポンスの内容を出力します。|
~
}}

          
-
*Smdn.Net.Imap4.WebClients名前空間
-
ここではSmdn.Net.Imap4.WebClients名前空間のクラスの詳細と使い方を紹介します。 基本的にはHttpWebRequest/ResponseやFtpWebRequest/Responseと同様で、
-
+URLを指定してWebRequest.CreateでWebRequestのインスタンスを作成
-
+Method、Credentialsなどのプロパティを指定
-
+WebRequest.GetResponseでリクエストを実行、レスポンスを取得
-
+取得したWebResponseインスタンスを参照、必要に応じてWebResponse.GetResponseStreamメソッドを呼び出す
 

        

        
~
**リクエストURLと接続・認証時の動作
の順でIMAPコマンドを実行、レスポンスを取得できます。 以下でSmdn.Net.Imap4.WebClientsに固有な部分について解説します。
+
***&aname(ImapWebRequest.login){接続と認証};
+
接続・認証時の動作は、[[接続と認証>#login]]で解説したとおりリクエストURLに記述されるスキーム・ホスト名・ポート・認証方式・ユーザ名に基づいて決まります。
+

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

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

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

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

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

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

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

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

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

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

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

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

        

        
~
request5.Credentials = new NetworkCredential("user", "pass");
**imap, imapsスキームの登録
~
}}
Smdn.Net.Imap4.WebClients名前空間のクラスを使う場合には、WebRequestクラスがimapスキームおよびimapsスキームのURLを処理できるようにImapWebRequestCreator.RegisterPrefixメソッドを呼び出しておく必要があります。
 

        

        
~
***&aname(ImapWebRequest.certs){証明書の選択と検証};
このメソッドはWebRequest.RegisterPrefixメソッドを呼び出し、imapスキームおよびimapsスキームに対してImapWebRequestCreatorを関連付けます。
+
デフォルトでは、接続・認証時にImapSessionManagerクラスの以下のメンバを参照して証明書の選択と検証を行います。
 

        

        
~
|*SSL/TLS接続時に参照するメンバ(いずれもクラスプロパティ)
**リクエストURLと接続時の動作
~
|~型|~ImapWebRequestクラスが参照するメンバ|h
接続時の動作は&urn2url(urn:ietf:rfc:5092);に記述されている内容に準じた動作となるようにしています。 (ただしimapsスキームを使用した場合にSSL/TLSでの接続を試みる動作は本ライブラリ固有の動作です)
+
|X509Certificate2Collection|ImapSessionManager.ClientCertificates|
+
|RemoteCertificateValidationCallback|ImapSessionManager.ServerCertificateValidationCallback|
+
|RemoteCertificateValidationCallback|ImapSessionManager.ClientCertificateSelectionCallback|
 

        

        
~
以下は証明書の検証を行う簡単な例です。
***SSL/TLS・接続ポート
-
リクエストURLのスキームがimapsの場合は、常にSSL/TLSでの接続を試みます。 スキームがimapの場合は、ImapWebRequest.UseTlsIfAvailableプロパティがtrueで、かつサーバがSTARTTLSに対応している場合、認証を開始する前にSSL/TLSを使用した接続にアップグレードします。 URLでポート番号を指定しない場合、デフォルトのポート(imapは143、imapsは993)に接続します。
 

        

        
~
#code(cs,証明書の検証を行う例){{
|*リクエストURLの形式と接続動作の例
~
using System;
|リクエストURLの形式|接続ポート|SSL/TLS|h
~
using System.Net;
|imap://imap.example.net/|143|可能ならSSL/TLSへのアップグレードを試行|
~
using System.Net.Security;
|imap://imap.example.net:993/|993|可能ならSSL/TLSへのアップグレードを試行|
~
using System.Security.Cryptography.X509Certificates;
|imaps://imap.example.net/|993|常にSSL/TLSで接続|
~
using Smdn.Net.Imap4;
|imaps://imap.example.net:10143/|10143|常にSSL/TLSで接続|
+
using Smdn.Net.Imap4.WebClients;
 

        

        
~
public class ValidateServerCerts {
***認証
~
  public static void Main(string[] args)
認証に用いるユーザ名は、リクエストURLから取得します。 パスワードはWebRequest.Credentialsプロパティを参照し、接続しようとしているホスト名・ポート番号および指定された認証メカニズムをもとに適切なものを取得します。 IMAP URLではFTPやHTTPのURLとは異なり、URLに平文パスワードを含めることが許可されていないので、リクエストURLからはパスワードを取得しません(指定されていても無視します)。
+
  {
+
    ImapWebRequestCreator.RegisterPrefix();
 

        

        
~
    // 証明書の検証を行うコールバックメソッドを指定
使用する認証メカニズムもユーザ名同様にURLから取得します。 省略した場合、もしくは"AUTH=*"が指定されている場合は次の順で認証を試行します。
~
    ImapSessionManager.ServerCertificateValidationCallback += ValidateRemoteCertificate;
+AUTHENTICATEコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
-
+LOGINコマンド (サーバが許可している場合のみ)
 

        

        
~
    using (var client = new WebClient()) {
リクエストURLにユーザ名・認証メカニズムの両方とも指定されていない場合は、ANONYMOUS認証を行います。
+
      client.Credentials = new NetworkCredential("user", "pass");
+
      client.DownloadFile("imaps://user@localhost/INBOX/;UID=1", "sample.eml");
+
    }
+
  }
 

        

        
~
  private static bool ValidateRemoteCertificate(object sender,
|*リクエストURLの形式と認証動作の例
~
                                                X509Certificate certificate,
|リクエストURLの形式|ユーザ名|使用する認証メカニズム|h
~
                                                X509Chain chain,
|imap://user;AUTH=DIGEST-MD5&#x40;imap.example.net/|user|DIGEST-MD5|
~
                                                SslPolicyErrors sslPolicyErrors)
|imap://;AUTH=DIGEST-MD5&#x40;imap.example.net/|WebRequest.Credentialsより取得|DIGEST-MD5|
~
  {
|imap://user;AUTH=*&#x40;imap.example.net/&br;imap://user&#x40;imap.example.net/|user|サーバ・クライアントが対応しているものを順に試行|
~
#if DEBUG
|imap://;AUTH=ANONYMOUS&#x40;imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
~
    // デバッグ時のみSslPolicyErrors.RemoteCertificateNameMismatchを無視
|imap://imap.example.net/|匿名ユーザ(anonymous)|ANONYMOUSもしくはLOGINコマンドを使用|
+
    if ((int)(sslPolicyErrors & SslPolicyErrors.RemoteCertificateNameMismatch) != 0)
+
      sslPolicyErrors &= ~SslPolicyErrors.RemoteCertificateNameMismatch;
+
#endif
 

        

        
~
    if (sslPolicyErrors == SslPolicyErrors.None) {
試行する認証メカニズムを制御するには、後述するImapWebRequest.UsingSaslMechanismsプロパティの値を変更してください。
+
      return true;
+
    }
+
    else {
+
      // エラーがあれば標準エラーに表示
+
      Console.Error.WriteLine(sslPolicyErrors);
+
      return false;
+
    }
+
  }
+
}
+
}}
+

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

        

        
 
**リクエストURLとリクエスト・レスポンスの動作
**リクエストURLとリクエスト・レスポンスの動作
 
HTTPと異なり、IMAP URLではリクエストURLの形式によりリクエストの対象が変わります。
HTTPと異なり、IMAP URLではリクエストURLの形式によりリクエストの対象が変わります。
 
|*リクエストURLの形式とリクエストの対象
|*リクエストURLの形式とリクエストの対象
~
|~リクエストURLの形式|~リクエストの対象|h
|リクエストURLの形式|リクエストの対象|h
 
|imap://imap.example.net/|URLで指定されたサーバ・アカウント|
|imap://imap.example.net/|URLで指定されたサーバ・アカウント|
 
|imap://imap.example.net/mailbox|URLで指定されたメールボックス|
|imap://imap.example.net/mailbox|URLで指定されたメールボックス|
 
|imap://imap.example.net/mailbox?...|URLで指定されたメールボックスにあるメッセージのうち、検索クエリに該当する全てのメッセージ|
|imap://imap.example.net/mailbox?...|URLで指定されたメールボックスにあるメッセージのうち、検索クエリに該当する全てのメッセージ|
811,17 259,15
 
***サーバ・アカウントに対するリクエスト
***サーバ・アカウントに対するリクエスト
 
リクエストURLがサーバ・アカウントを表す場合(imap://imap.example.net/の形式)のリクエストとレスポンスの動作は次のとおりです。
リクエストURLがサーバ・アカウントを表す場合(imap://imap.example.net/の形式)のリクエストとレスポンスの動作は次のとおりです。
 

        

        
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|ImapWebRequestMethods.Lsub, "LSUB"&br;(デフォルト)|LSUBコマンドを送信して購読中のメールボックスの一覧を取得します。|-|取得したメールボックスの一覧は、ImapWebResponse.Mailboxesプロパティに設定されます。|
|ImapWebRequestMethods.Lsub, "LSUB"&br;(デフォルト)|LSUBコマンドを送信して購読中のメールボックスの一覧を取得します。|-|取得したメールボックスの一覧は、ImapWebResponse.Mailboxesプロパティに設定されます。|
 
|ImapWebRequestMethods.List, "LIST"|LISTコマンドを送信して全てのメールボックスの一覧を取得します。|-|取得したメールボックスの一覧は、ImapWebResponse.Mailboxesプロパティに設定されます。|
|ImapWebRequestMethods.List, "LIST"|LISTコマンドを送信して全てのメールボックスの一覧を取得します。|-|取得したメールボックスの一覧は、ImapWebResponse.Mailboxesプロパティに設定されます。|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
+

          
+
ImapWebResponse.Mailboxesプロパティに設定されるImapMailboxインスタンスは、ログアウトするまでの間ライブラリ側で管理されます。 同じメールボックスに対して操作を行った場合は、インスタンスの値のみが更新され、常に同じインスタンスが返されます。
 

        

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

        

        
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|ImapWebRequestMethods.Fetch, "FETCH"&br;(デフォルト)|FETCHコマンドを送信してメールボックスにあるメッセージの一覧を取得します。|取得するのはメッセージの属性のみです。 メッセージ本文は取得しません。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
|ImapWebRequestMethods.Fetch, "FETCH"&br;(デフォルト)|FETCHコマンドを送信してメールボックスにあるメッセージの一覧を取得します。|取得するのはメッセージの属性のみです。 メッセージ本文は取得しません。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
 
|ImapWebRequestMethods.Append, "APPEND"|APPENDコマンドを送信してメールボックスにメッセージをアップロードします。|アップロードするメッセージはWebRequest.GetRequestStreamメソッドが返すStreamに書き込みます。 現在の実装では、リクエスト開始時にContentLengthの値が指定されているか、GetRequestStreamメソッドが返すStreamを閉じるまでアップロードは保留されます。 メッセージはMIME形式であるべきですが、ライブラリ側ではアップロードする内容をチェックしません。|サーバがアップロードしたメッセージのUIDを返す場合は、アップロードしたメッセージのURLがWebResponse.ResponseUriに設定されます。|
|ImapWebRequestMethods.Append, "APPEND"|APPENDコマンドを送信してメールボックスにメッセージをアップロードします。|アップロードするメッセージはWebRequest.GetRequestStreamメソッドが返すStreamに書き込みます。 現在の実装では、リクエスト開始時にContentLengthの値が指定されているか、GetRequestStreamメソッドが返すStreamを閉じるまでアップロードは保留されます。 メッセージはMIME形式であるべきですが、ライブラリ側ではアップロードする内容をチェックしません。|サーバがアップロードしたメッセージのUIDを返す場合は、アップロードしたメッセージのURLがWebResponse.ResponseUriに設定されます。|
 
|ImapWebRequestMethods.Expunge, "EXPUNGE"|EXPUNGEコマンドを送信してメールボックスから\Deletedフラグの付いたメッセージを削除します。|-|-|
|ImapWebRequestMethods.Expunge, "EXPUNGE"|EXPUNGEコマンドを送信してメールボックスから\Deletedフラグの付いたメッセージを削除します。|-|-|
834,44 280,42
 
|ImapWebRequestMethods.Status, "STATUS"|STATUSコマンドを送信してメールボックスの状態を取得します。|取得する情報は、ImapWebRequest.StatusDataItemプロパティで指定します。&br;既にメールボックスを選択している状態で、他のメールボックスの状態を取得する場合に使います。|状態を取得したメールボックスは、ImapWebResponse.Mailboxesプロパティに設定されます。|
|ImapWebRequestMethods.Status, "STATUS"|STATUSコマンドを送信してメールボックスの状態を取得します。|取得する情報は、ImapWebRequest.StatusDataItemプロパティで指定します。&br;既にメールボックスを選択している状態で、他のメールボックスの状態を取得する場合に使います。|状態を取得したメールボックスは、ImapWebResponse.Mailboxesプロパティに設定されます。|
 
|ImapWebRequestMethods.Subscribe, "SUBSCRIBE"|SUBSCRIBEコマンドを送信してメールボックスの購読を開始します。|-|-|
|ImapWebRequestMethods.Subscribe, "SUBSCRIBE"|SUBSCRIBEコマンドを送信してメールボックスの購読を開始します。|-|-|
 
|ImapWebRequestMethods.Unsubscribe, "UNSUBSCRIBE"|UNSUBSCRIBEコマンドを送信してメールボックスの購読を解除します。|-|-|
|ImapWebRequestMethods.Unsubscribe, "UNSUBSCRIBE"|UNSUBSCRIBEコマンドを送信してメールボックスの購読を解除します。|-|-|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
+

          
+
ImapWebResponse.Mailboxesプロパティに設定されるImapMailboxインスタンスは、ログアウトするまでの間ライブラリ側で管理されます。 同じメールボックスに対して操作を行った場合は、インスタンスの値のみが更新され、常に同じインスタンスが返されます。
 

        

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

        

        
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|ImapWebRequestMethods.Search, "SEARCH"&br;(デフォルト)|SEARCHコマンドを送信して検索クエリに該当するメッセージの一覧を取得します。|取得するのはメッセージの属性のみです。 メッセージ本文は取得しません。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
|ImapWebRequestMethods.Search, "SEARCH"&br;(デフォルト)|SEARCHコマンドを送信して検索クエリに該当するメッセージの一覧を取得します。|取得するのはメッセージの属性のみです。 メッセージ本文は取得しません。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
 
|ImapWebRequestMethods.Copy, "COPY"|COPYコマンドを送信して検索クエリに該当するメッセージを別のメールボックスにコピーします。|コピー先のメールボックスはImapWebRequest.DestinationUriプロパティで指定します。|サーバがCOPYUIDレスポンスコードを返した場合は、コピーしたメッセージのURLがWebResponse.ResponseUriに設定されます。 また、コピー先のメールボックスを自動的に作成した場合、作成したメールボックスはImapWebResponse.Mailboxesプロパティに設定されます。|
|ImapWebRequestMethods.Copy, "COPY"|COPYコマンドを送信して検索クエリに該当するメッセージを別のメールボックスにコピーします。|コピー先のメールボックスはImapWebRequest.DestinationUriプロパティで指定します。|サーバがCOPYUIDレスポンスコードを返した場合は、コピーしたメッセージのURLがWebResponse.ResponseUriに設定されます。 また、コピー先のメールボックスを自動的に作成した場合、作成したメールボックスはImapWebResponse.Mailboxesプロパティに設定されます。|
 
|ImapWebRequestMethods.Expunge, "EXPUNGE"|STOREコマンドを送信して検索クエリに該当するメッセージに\Deletedフラグを追加した後、EXPUNGEコマンドを送信してメッセージを削除します。|サーバが&urn2url(urn:ietf:rfc:4315,#2.1){UID EXPUNGE};に対応していない場合、検索クエリに該当したメッセージだけでなく''既に\Deletedフラグが設定されている他のメッセージも同時に削除されます''。|-|
|ImapWebRequestMethods.Expunge, "EXPUNGE"|STOREコマンドを送信して検索クエリに該当するメッセージに\Deletedフラグを追加した後、EXPUNGEコマンドを送信してメッセージを削除します。|サーバが&urn2url(urn:ietf:rfc:4315,#2.1){UID EXPUNGE};に対応していない場合、検索クエリに該当したメッセージだけでなく''既に\Deletedフラグが設定されている他のメッセージも同時に削除されます''。|-|
 
|ImapWebRequestMethods.Store, "STORE"|STOREコマンドを送信して検索クエリに該当するメッセージにフラグを追加・削除・設定します。|追加・削除・設定するフラグはImapWebRequest.StoreDataItemプロパティで指定します。|-|
|ImapWebRequestMethods.Store, "STORE"|STOREコマンドを送信して検索クエリに該当するメッセージにフラグを追加・削除・設定します。|追加・削除・設定するフラグはImapWebRequest.StoreDataItemプロパティで指定します。|-|
 
|ImapWebRequestMethods.Sort, "SORT"|SORTコマンドを送信して検索クエリに該当するメッセージの一覧をソート済みの形式で取得します。|ソート方法はImapWebRequest.SortCriteriaプロパティで指定します。&br;サーバがSORTコマンドをサポートするかどうかはチェックせずにリクエストを実行します。&br;SEARCH同様、取得するのはメッセージの属性のみです。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したソート済みメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
|ImapWebRequestMethods.Sort, "SORT"|SORTコマンドを送信して検索クエリに該当するメッセージの一覧をソート済みの形式で取得します。|ソート方法はImapWebRequest.SortCriteriaプロパティで指定します。&br;サーバがSORTコマンドをサポートするかどうかはチェックせずにリクエストを実行します。&br;SEARCH同様、取得するのはメッセージの属性のみです。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したソート済みメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
 
|ImapWebRequestMethods.Thread, "THREAD"|THREADコマンドを送信して検索クエリに該当するメッセージの一覧をスレッド形式で取得します。|スレッド形式のアルゴリズムはImapWebRequest.ThreadingAlgorithmプロパティで指定します。&br;サーバがTHREADコマンドをサポートするかどうかはチェックせずにリクエストを実行します。&br;SEARCH同様、取得するのはメッセージの属性のみです。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したスレッド形式の一覧は、ImapWebResponse.ThreadTreeプロパティに設定されます。 また、個々のメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
|ImapWebRequestMethods.Thread, "THREAD"|THREADコマンドを送信して検索クエリに該当するメッセージの一覧をスレッド形式で取得します。|スレッド形式のアルゴリズムはImapWebRequest.ThreadingAlgorithmプロパティで指定します。&br;サーバがTHREADコマンドをサポートするかどうかはチェックせずにリクエストを実行します。&br;SEARCH同様、取得するのはメッセージの属性のみです。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|取得したスレッド形式の一覧は、ImapWebResponse.ThreadTreeプロパティに設定されます。 また、個々のメッセージの一覧は、ImapWebResponse.MessageAttributesプロパティに設定されます。|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
 

        

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

        

        
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|h
|Methodプロパティ|リクエスト|解説|レスポンス|h
 
|ImapWebRequestMethods.Fetch, "FETCH"&br;(デフォルト)|FETCHコマンドを送信してメッセージの本文を取得します。|取得の際にBODY[]とBODY.PEEK[]のどちらを使用するかはImapWebRequest.FetchPeekプロパティで指定します。&br;URLにSECTION/PARTIALのいずれも指定していない場合は、メッセージの本文だけでなく属性も取得します。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|メッセージ本文はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 URLでSECTION/PARTIALを指定している場合は、メッセージ本文のうち、該当する部分のみ取得されます。&br;URLにSECTION/PARTIALのいずれも指定していない場合のみ、取得するメッセージのサイズがWebResponse.ContentLength、Content-TypeがWebResponse.ContentTypeプロパティに設定されます。&br;UID/SECTION/PARTIALに該当するメッセージがない場合、WebExceptionStatus.SuccessのWebExceptionをスローします。|
|ImapWebRequestMethods.Fetch, "FETCH"&br;(デフォルト)|FETCHコマンドを送信してメッセージの本文を取得します。|取得の際にBODY[]とBODY.PEEK[]のどちらを使用するかはImapWebRequest.FetchPeekプロパティで指定します。&br;URLにSECTION/PARTIALのいずれも指定していない場合は、メッセージの本文だけでなく属性も取得します。 取得するメッセージ属性は、ImapWebRequest.FetchDataItemプロパティで指定します。|メッセージ本文はWebResponse.GetResponseStreamメソッドが返すStreamから読み込めます。 URLでSECTION/PARTIALを指定している場合は、メッセージ本文のうち、該当する部分のみ取得されます。&br;URLにSECTION/PARTIALのいずれも指定していない場合のみ、取得するメッセージのサイズがWebResponse.ContentLength、Content-TypeがWebResponse.ContentTypeプロパティに設定されます。&br;UID/SECTION/PARTIALに該当するメッセージがない場合、WebExceptionStatus.SuccessのWebExceptionをスローします。|
 
|ImapWebRequestMethods.Copy, "COPY"|COPYコマンドを送信してメッセージを別のメールボックスにコピーします。|コピー先のメールボックスはImapWebRequest.DestinationUriプロパティで指定します。|サーバがCOPYUIDレスポンスコードを返した場合は、コピーしたメッセージのURLがWebResponse.ResponseUriに設定されます。 また、コピー先のメールボックスを自動的に作成した場合、作成したメールボックスはImapWebResponse.Mailboxesプロパティに設定されます。|
|ImapWebRequestMethods.Copy, "COPY"|COPYコマンドを送信してメッセージを別のメールボックスにコピーします。|コピー先のメールボックスはImapWebRequest.DestinationUriプロパティで指定します。|サーバがCOPYUIDレスポンスコードを返した場合は、コピーしたメッセージのURLがWebResponse.ResponseUriに設定されます。 また、コピー先のメールボックスを自動的に作成した場合、作成したメールボックスはImapWebResponse.Mailboxesプロパティに設定されます。|
 
|ImapWebRequestMethods.Expunge, "EXPUNGE"|STOREコマンドを送信して\Deletedフラグを追加した後、EXPUNGEコマンドを送信してメッセージを削除します。|サーバが&urn2url(urn:ietf:rfc:4315,#2.1){UID EXPUNGE};に対応していない場合、URLで指定されたメッセージだけでなく''既に\Deletedフラグが設定されている他のメッセージも同時に削除されます''。|-|
|ImapWebRequestMethods.Expunge, "EXPUNGE"|STOREコマンドを送信して\Deletedフラグを追加した後、EXPUNGEコマンドを送信してメッセージを削除します。|サーバが&urn2url(urn:ietf:rfc:4315,#2.1){UID EXPUNGE};に対応していない場合、URLで指定されたメッセージだけでなく''既に\Deletedフラグが設定されている他のメッセージも同時に削除されます''。|-|
 
|ImapWebRequestMethods.Store, "STORE"|STOREコマンドを送信してメッセージにフラグを追加・削除・設定します。|追加・削除・設定するフラグはImapWebRequest.StoreDataItemプロパティで指定します。|-|
|ImapWebRequestMethods.Store, "STORE"|STOREコマンドを送信してメッセージにフラグを追加・削除・設定します。|追加・削除・設定するフラグはImapWebRequest.StoreDataItemプロパティで指定します。|-|
~
|~Methodプロパティ|~リクエスト|~解説|~レスポンス|f
|Methodプロパティ|リクエスト|解説|レスポンス|f
 

        

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

        

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

        

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

        

        
 
|*ImapWebRequestクラスのプロパティ
|*ImapWebRequestクラスのプロパティ
~
|~プロパティ|~デフォルト|~対象となるコマンド|~解説|h
|プロパティ|デフォルト|対象となるコマンド|解説|h
 
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
|KeepAlive|true|全て|リクエストが終了した後もセッションを維持するかどうかを指定します。 trueの場合はリクエストが終了してもセッションは維持し、falseの場合はリクエストの度にセッションを開きリクエスト終了と同時にセッションを閉じます。|
 
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
|ExpectedErrorResponseCodes|null|全て|サーバから返されることが予期されるエラーレスポンスコードの配列を指定します。 サーバからこれらのレスポンスコードが返された場合は、エラーレスポンスでもWebExceptionがスローされません。|
 
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にTLSを使用した接続にアップグレードします。|
|UseTlsIfAvailable|true|全て(認証時)|サーバがサポートしている場合、認証を行う前にTLSを使用した接続にアップグレードします。|
887,11 331,10
 
|ThreadingAlgorithm|null|THREAD|THREADコマンドで使用するスレッド形式のアルゴリズムを指定します。|
|ThreadingAlgorithm|null|THREAD|THREADコマンドで使用するスレッド形式のアルゴリズムを指定します。|
 
|FetchBlockSize|10240|FETCH|FETCHコマンドでメッセージ本文を取得する際に、1回のFETCHコマンドで取得するブロックのサイズをバイト単位で指定します。|
|FetchBlockSize|10240|FETCH|FETCHコマンドでメッセージ本文を取得する際に、1回のFETCHコマンドで取得するブロックのサイズをバイト単位で指定します。|
 
|FetchPeek|true|FETCH|FETCHコマンドでメッセージ本文を取得する際に、BODY.PEEK[]とBODY[]のどちらを使用するかを指定します。 trueの場合はBODY.PEEK[]が使用され、取得したメッセージは未読のままになります。|
|FetchPeek|true|FETCH|FETCHコマンドでメッセージ本文を取得する際に、BODY.PEEK[]とBODY[]のどちらを使用するかを指定します。 trueの場合はBODY.PEEK[]が使用され、取得したメッセージは未読のままになります。|
+
|~プロパティ|~デフォルト|~対象となるコマンド|~解説|f
 

        

        
 
ImapWebRequest.FetchDataItemプロパティに指定できるマクロの値と、取得する属性の種類は次のとおりです。
ImapWebRequest.FetchDataItemプロパティに指定できるマクロの値と、取得する属性の種類は次のとおりです。
 
|*ImapWebRequest.FetchDataItemプロパティに指定できる値
|*ImapWebRequest.FetchDataItemプロパティに指定できる値
~
|~値|~取得される属性|
|値|取得される属性|
 
|ImapFetchDataItemMacro.All|ALLマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZE、ENVELOPEです。|
|ImapFetchDataItemMacro.All|ALLマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZE、ENVELOPEです。|
 
|ImapFetchDataItemMacro.Fast|FASTマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZEです。|
|ImapFetchDataItemMacro.Fast|FASTマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZEです。|
 
|ImapFetchDataItemMacro.Full|FULLマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZE、ENVELOPE、BODYです。|
|ImapFetchDataItemMacro.Full|FULLマクロで表される属性を取得します。 取得するのはFLAGS、INTERNALDATE、RFC822.SIZE、ENVELOPE、BODYです。|
900,14 343,14
 
WebRequestクラスから継承されるプロパティのうち、以下のプロパティは使用することができます。
WebRequestクラスから継承されるプロパティのうち、以下のプロパティは使用することができます。
 

        

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

        

        
 
以下のプロパティは、未テスト・不完全な実装に関連するプロパティです。 使用はできますが、今後廃止する可能性もあるので、現時点では使用を推奨できません。
以下のプロパティは、未テスト・不完全な実装に関連するプロパティです。 使用はできますが、今後廃止する可能性もあるので、現時点では使用を推奨できません。
 
|*ImapWebRequestクラスのプロパティ
|*ImapWebRequestクラスのプロパティ
~
|~プロパティ|~デフォルト|~対象となるコマンド|~解説|h
|プロパティ|デフォルト|対象となるコマンド|解説|h
 
|UseDeflateIfAvailable|false|全て|サーバがサポートしている場合、DEFLATE圧縮アルゴリズムを使用した接続に変更します。 (この機能は現在動作しません。 trueにした場合、NotImplementedExceptionがスローされます)|
|UseDeflateIfAvailable|false|全て|サーバがサポートしている場合、DEFLATE圧縮アルゴリズムを使用した接続に変更します。 (この機能は現在動作しません。 trueにした場合、NotImplementedExceptionがスローされます)|
 

        

        
 
***ImapWebRequestクラスのデフォルト値の変更
***ImapWebRequestクラスのデフォルト値の変更
916,7 359,7
 
ImapWebRequestDefaultsクラスにはImapWebRequestプロパティと同名のプロパティを用意してありますが、以下の一覧にあるプロパティはImapWebRequestでは設定できないプロパティです。
ImapWebRequestDefaultsクラスにはImapWebRequestプロパティと同名のプロパティを用意してありますが、以下の一覧にあるプロパティはImapWebRequestでは設定できないプロパティです。
 

        

        
 
|*ImapWebRequestDefaultsクラスのプロパティ
|*ImapWebRequestDefaultsクラスのプロパティ
~
|~プロパティ|~デフォルト|~解説|h
|プロパティ|デフォルト|解説|h
 
|AnonymousToken|"anonymous"|匿名ユーザでログインする場合に使用されるユーザ名を指定します。|
|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を指定します。|
965,198 408,10
 
</configuration>
</configuration>
 
}}
}}
 

        

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

          
+
**例外
+
(このドキュメントは作成中です)
+

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

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

          
+
#hr
+

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

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

          
+
using Smdn.Net.Imap4;
+
using Smdn.Net.Imap4.Client;
+

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

          
+
      // INBOXを開く
+
      using (var inbox = client.OpenInbox()) {
+
        // UIDが1のメッセージを取得
+
        var message = inbox.GetMessageByUid(1);
+

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

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

          
+
***&aname(ImapClient.sample2){メッセージをアップロードする};
+
#code(cs){{
+
using System;
+
using System.IO;
 

        

        
~
using Smdn.Net.Imap4;
**サンプル
~
using Smdn.Net.Imap4.Client;
***メッセージのコピー
+

          
+
class Sample {
+
  public static void Main(string[] args)
+
  {
+
    using (var client = new ImapClient("localhost", 143, "user", "DIGEST-MD5")) {
+
      client.Connect("pass");
+

          
+
      // INBOXを取得
+
      var inbox = client.GetInbox();
+

          
+
      // ファイルsample.emlを開く
+
      using (var messageStream = File.OpenRead("sample.eml")) {
+
        // Streamの内容をINBOXにアップロード
+
        inbox.AppendMessage(messageStream);
+
      }
+
    }
+
  }
+
}
+
}}
+

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

          
+
***&aname(ImapClient.sample3){メッセージの検索};
+
#code(cs){{
+
using System;
+

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

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

          
+
    // Gmailのアカウントに接続
+
    using (var client = new ImapClient(new Uri("imaps://user@imap.gmail.com/"))) {
+
      client.Connect("pass");
+

          
+
      // INBOXを開く
+
      using (var inbox = client.OpenInbox()) {
+
        // タイトルに[Mono-dev]を含むメールの一覧を取得する
+
        foreach (var message in inbox.GetMessages(ImapSearchCriteria.Subject("[Mono-dev]"))) {
+
          // 取得したメッセージのUIDと件名を表示
+
          Console.WriteLine("UID {0}: {1}", message.Uid, message.EnvelopeSubject);
+
        }
+
      }
+
    }
+
  }
+
}
+
}}
+

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

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

          
+
using Smdn.Net.Imap4.WebClients;
+

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

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

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

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

          
+
***&aname(ImapWebRequest.sample2){メッセージをアップロードする};
+
#code(cs){{
+
using System;
+
using System.IO;
+
using System.Net;
+

          
+
using Smdn.Net.Imap4.WebClients;
+

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

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

          
+
      // ファイルsample.emlの内容をINBOXにアップロード
+
      client.UploadData("imap://user;AUTH=DIGEST-MD5@localhost/INBOX", ImapWebRequestMethods.Append, File.ReadAllBytes("sample.eml"));
+
    }
+
  }
+
}
+
}}
+

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

          
+
***&aname(ImapWebRequest.sample3){メッセージの検索};
+
#code(cs){{
+
using System;
+
using System.Net;
+

          
+
using Smdn.Net.Imap4.WebClients;
+

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

          
+
    // GmailアカウントのINBOXから、件名に[Mono-dev]を含むメールの一覧を取得する
+
    var request = WebRequest.Create("imaps://user@imap.gmail.com/INBOX?SUBJECT \"[Mono-dev]\"");
+

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

          
+
    using (var response = request.GetResponse() as ImapWebResponse) {
+
      foreach (var message in response.MessageAttributes) {
+
        // 取得したメッセージのURLを表示
+
        Console.WriteLine(message.Url);
+
      }
+
    }
+
  }
+
}
+
}}
+

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

          
+
***&aname(ImapWebRequest.sample4){メッセージのコピー};
 
INBOXにあるメッセージすべてをINBOX.backupにコピーする例。 AllowCreateMailboxプロパティをtrueにしておくことで、サーバがレスポンスコードTRYCREATEを返した場合は自動的にメールボックスを作成します。
INBOXにあるメッセージすべてをINBOX.backupにコピーする例。 AllowCreateMailboxプロパティをtrueにしておくことで、サーバがレスポンスコードTRYCREATEを返した場合は自動的にメールボックスを作成します。
 
#code(cs){{
#code(cs){{
 
using System;
using System;
1178,7 433,7
 
}
}
 
}}
}}
 

        

        
~
***&aname(ImapWebRequest.sample5){メールボックスの削除};
***メールボックスの削除
 
メールボックスINBOX.oldを削除する例。 ExpectedErrorResponseCodesプロパティにImapResponseCode.NonExistentを指定しておくことで、メールボックスが存在しない場合(サーバがレスポンスコードNONEXISTENTを返した場合)でもWebExceptionをスローしないようにします。
メールボックスINBOX.oldを削除する例。 ExpectedErrorResponseCodesプロパティにImapResponseCode.NonExistentを指定しておくことで、メールボックスが存在しない場合(サーバがレスポンスコードNONEXISTENTを返した場合)でもWebExceptionをスローしないようにします。
 

        

        
 
#code(cs){{
#code(cs){{
1201,7 456,7
 
}
}
 
}}
}}
 

        

        
~
***&aname(ImapWebRequest.sample6){メールボックスの作成};
***メールボックスの作成
 
メールボックスINBOX.newを作成する例。 先の例と同様に、メールボックスがすでに存在する場合(サーバがレスポンスコードALREADYEXISTSを返した場合)でもWebExceptionをスローしないようにします。
メールボックスINBOX.newを作成する例。 先の例と同様に、メールボックスがすでに存在する場合(サーバがレスポンスコードALREADYEXISTSを返した場合)でもWebExceptionをスローしないようにします。
 

        

        
 
#code(cs){{
#code(cs){{
1224,7 479,7
 
}
}
 
}}
}}
 

        

        
~
***&aname(ImapWebRequest.sample7){メッセージの検索};
***メッセージの検索
 
ImapStyleUriBuilderを使って、複雑な検索クエリを含むリクエストを送信する例。
ImapStyleUriBuilderを使って、複雑な検索クエリを含むリクエストを送信する例。
 

        

        
 
#code(cs){{
#code(cs){{
1258,7 513,7
 

        

        
 
となる。
となる。
 

        

        
~
***&aname(ImapWebRequest.sample8){メッセージへのフラグの設定};
***メッセージへのフラグの設定
 
fromにspammer.example.comを含むメッセージをすべて既読にし、Thunderbirdの迷惑メールのマーク(Junk)を設定する例。 ImapStoreDataItem.ReplaceFlagsメソッドを使って新しく置き換える(設定する)フラグを作成し、StoreDataItemプロパティにしています。
fromにspammer.example.comを含むメッセージをすべて既読にし、Thunderbirdの迷惑メールのマーク(Junk)を設定する例。 ImapStoreDataItem.ReplaceFlagsメソッドを使って新しく置き換える(設定する)フラグを作成し、StoreDataItemプロパティにしています。
 

        

        
 
#code(cs){{
#code(cs){{
1282,9 537,13
 
}
}
 
}}
}}
 

        

        
~
**ImapSession
*Smdn.Net.Imap4.Client名前空間
~
このクラスを直接使用することはできますが推奨はしません。 また、ドキュメントを用意する予定はありません。 内部実装の参照や改変などの参考程度に掲載します。
Smdn.Net.Imap4.Client名前空間のクラスの使い方。 このドキュメントは作成中です。 前述のサンプルおよび[[works/tools/junk/TundereBird]]の実装を参照してください。
 

        

        
-
*Smdn.Net.Imap4.Client.Session名前空間
-
Smdn.Net.Imap4.Client.Session名前空間のクラスの使い方。 このドキュメントは作成中です。 [[works/tools/junk/TundereBird]]およびSmdn.Net.Imap4.WebClientsの各クラスの実装を参照してください。
-

          
-
**サンプル
 
***ログインと各種コマンド送信の例
***ログインと各種コマンド送信の例
 
IDLEでメールボックス(INBOX)を監視し、新着メッセージが着たらサブジェクトを表示するサンプル。
IDLEでメールボックス(INBOX)を監視し、新着メッセージが着たらサブジェクトを表示するサンプル。
 

        

        
1384,4 643,3
 
  }
  }
 
}
}
 
}}
}}
+

          

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

current previous
1,12 1,10
 
${smdncms:title,ドキュメント・サンプル}
${smdncms:title,ドキュメント・サンプル}
 
${smdncms:keywords,}
${smdncms:keywords,}
 
${smdncms:parser_options,non-limited-list}
${smdncms:parser_options,non-limited-list}
~
[[works/libs/Smdn.Net.Pop3]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.92時点のもので、記載不備などがあるかもしれません。
[[works/libs/Smdn.Net.Pop3]]のドキュメントとサンプルです。 ここに記載されているものはversion 0.91時点のもので、記載不備などがあるかもしれません。
 

        

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

        

        
+
#hr
+

          
 
*用語と表記
*用語と表記
 
このドキュメントでは、以下の表記を用いています。
このドキュメントでは、以下の表記を用いています。
 
:メッセージ|POPサーバ上のメールボックスにある個々のメールの本文または/および属性を表す意味で用いています。
:メッセージ|POPサーバ上のメールボックスにある個々のメールの本文または/および属性を表す意味で用いています。
41,8 39,6
 
|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.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;直接使用することもできますが、インターフェイスを変更することがあるので推奨はできません。|-|
|Smdn.Net.Pop3.Client.Session&br;(Smdn.Net.Pop3.Client.dll)|PopSession|POPコマンドと1対1に対応するメソッドを持つクラスです。 POPの操作は抽象化していません。 仕様と1対1で対応するような実装にしてあります。 このクラスは上記2種類のクライアント実装で内部的に使用しています。&br;直接使用することもできますが、インターフェイスを変更することがあるので推奨はできません。|-|
 

        

        
+
#hr
+

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

        

        
73,12 69,12
 
|pop://user&#x40;pop.example.net:995/|995|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
|pop://user&#x40;pop.example.net:995/|995|SSL/TLSを使用しない&br;もしくは可能ならSSL/TLSへアップグレード|
 

        

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

        

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

        

        
 
認証方式にAPOPを使用する場合は、"APOP"ではなく"+APOP"を指定してください。 認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
認証方式にAPOPを使用する場合は、"APOP"ではなく"+APOP"を指定してください。 認証方式を指定しない場合、もしくは"*"が指定されている場合は次の順で認証を試行します。
 
+AUTHコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
+AUTHコマンド (サーバ・クライアントが対応している認証メカニズムを順に試行)
95,7 91,7
 
|~URL|~ユーザ名|~使用する認証メカニズム|h
|~URL|~ユーザ名|~使用する認証メカニズム|h
 
|pop://user;AUTH=+APOP&#x40;pop.example.net/|user|APOP|
|pop://user;AUTH=+APOP&#x40;pop.example.net/|user|APOP|
 
|pop://user;AUTH=DIGEST-MD5&#x40;pop.example.net/|user|DIGEST-MD5|
|pop://user;AUTH=DIGEST-MD5&#x40;pop.example.net/|user|DIGEST-MD5|
~
|pop://;AUTH=DIGEST-MD5&#x40;pop.example.net/|ICredentialsByHostインターフェイスより取得|DIGEST-MD5|
|pop://;AUTH=DIGEST-MD5&#x40;pop.example.net/|Credentialsプロパティより取得|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/|匿名ユーザ(anonymous)|ANONYMOUS|
|pop://;AUTH=ANONYMOUS&#x40;pop.example.net/|匿名ユーザ(anonymous)|ANONYMOUS|
104,16 100,14
 
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
試行する認証メカニズムを制御するには、UsingSaslMechanismsプロパティ&sub{*2};の値を変更してください。
 

        

        
 
これら認証時のパラメータは次の箇所で指定します。
これら認証時のパラメータは次の箇所で指定します。
~
:ICredentialsByHostインターフェイス&sup{*1};|[[PopClient.Connect()メソッド>#PopClient.login]]に指定する引数credentials、もしくは[[PopWebRequest.Credentialsプロパティ>#PopWebRequest.login]]
:ICredentialsByHostインターフェイス&sub{*1};|[[PopClient.Connect()メソッド>#PopClient.login]]に指定する引数credentials、もしくは[[PopWebRequest.Credentialsプロパティ>#PopWebRequest.login]]
~
:UsingSaslMechanismsプロパティ&sup{*2};|[[PopClient.Profile.UsingSaslMechanismsプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.UsingSaslMechanismsプロパティ>#PopWebRequest.login]]
:UsingSaslMechanismsプロパティ&sub{*2};|[[PopClient.Profile.UsingSaslMechanismsプロパティ>#PopClient.login]]、もしくは[[PopWebRequest.UsingSaslMechanismsプロパティ>#PopWebRequest.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);を返すクラスなら何でも設定できます。
 

        

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

        

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

          
 
**&aname(ssl){SSL/TLSを使用した接続};
**&aname(ssl){SSL/TLSを使用した接続};
 
***&aname(certs){証明書の選択と検証};
***&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};を作成します。
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};を作成します。
174,7 168,7
 

        

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

        

        
~
#hr

          
 

        

        
 
*&aname(PopClient){PopClientクラス (Smdn.Net.Pop3.Client.dll)};
*&aname(PopClient){PopClientクラス (Smdn.Net.Pop3.Client.dll)};
 
PopClientクラスおよびSmdn.Net.Pop3.Client名前空間のクラスの使い方。
PopClientクラスおよびSmdn.Net.Pop3.Client名前空間のクラスの使い方。
300,23 294,21
 

        

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

        

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

        

        
 
:IDisposable.Dispose()|PopClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
:IDisposable.Dispose()|PopClientクラスはIDisposableインターフェイスを実装しています。 IDisposable.Dispose()を呼び出した場合、削除マークが付けられているメッセージを削除せずに切断します。 usingステートメントを使って記述する場合でメッセージを削除したい場合は、切断する前にLogout()メソッド呼び出すようにしてください。
 
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度PopClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
:Logout(), Disconnect(), IDisposable.Dispose()|これらのメソッドのいずれかを呼び出した後でも、再度PopClient.Connect()を呼び出すことで同じインスタンスを使って再度接続することはできます。
325,58 317,52
 

        

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

        

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

        

        
~
:MessageCount, TotalSize|このプロパティは、値が未取得の場合、もしくはPopClient.CancelDelete()やPopMessageInfo.MarkAsDeleted()で状態が更新されている場合、STATコマンドを発行して最新の値を取得します。 切断されている状態で取得しようとした場合(PopClient.IsConnectedがfalseの場合)、例外をスローします。
:MessageCount, TotalSize|切断されている状態で取得しようとした場合(PopClient.IsConnectedがfalseの場合)、例外をスローします。
 

        

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

        

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

        

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

        

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

        

        
 
-PopClient.DeleteAfterRetrieveプロパティにtrueが指定されている場合、メッセージの取得に成功した時点で自動的にMarkAsDeleted()メソッドが呼び出され、メッセージは削除マーク済みにされます。
-PopClient.DeleteAfterRetrieveプロパティにtrueが指定されている場合、メッセージの取得に成功した時点で自動的にMarkAsDeleted()メソッドが呼び出され、メッセージは削除マーク済みにされます。
 
-すべてのメソッドは、既定ではRETRコマンドを用いてメッセージ本文全体を取得します。
-すべてのメソッドは、既定ではRETRコマンドを用いてメッセージ本文全体を取得します。
 
maxLinesを引数に取るバージョンのオーバーロードを使用することで、TOPコマンドを用いてメッセージ本文のうちヘッダ部分とボディ部分の指定した行数のみを取得することもできます。
maxLinesを引数に取るバージョンのオーバーロードを使用することで、TOPコマンドを用いてメッセージ本文のうちヘッダ部分とボディ部分の指定した行数のみを取得することもできます。
+
-すべてのメソッドは、取得したメッセージ本文をキャッシュしません。 ''メソッド呼び出しの度にメッセージ本文のダウンロードを行います。'' 同じメッセージを何度も処理する必要がある場合は、WriteTo()メソッドでMemoryStream等に書き出すか、Save()メソッドでファイルに保存するなどしてください。
+
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティを呼び出そうとした場合、PopProtocolViolationExceptionをスローします。
 
-OpenText(), ReadAllLines()などのメソッドは、既定ではstringへのデコードにISO-8859-1を使用します。
-OpenText(), ReadAllLines()などのメソッドは、既定ではstringへのデコードにISO-8859-1を使用します。
 
Encodingを引数に取るバージョンのオーバーロードを使用することで、指定したエンコーディングでデコードすることもできます。
Encodingを引数に取るバージョンのオーバーロードを使用することで、指定したエンコーディングでデコードすることもできます。
 
これらのメソッドは''Content-Typeヘッダのcharsetパラメータや、Content-Transfer-Encodingヘッダなどに指定されている値は考慮せずに''デコードを行います。 MIMEメッセージとしてパース・デコードするには、OpenRead()やReadAllBytes()などのメソッドで本文を取得した後、適切な処理を施してください。
これらのメソッドは''Content-Typeヘッダのcharsetパラメータや、Content-Transfer-Encodingヘッダなどに指定されている値は考慮せずに''デコードを行います。 MIMEメッセージとしてパース・デコードするには、OpenRead()やReadAllBytes()などのメソッドで本文を取得した後、適切な処理を施してください。
384,19 370,18
 
***メッセージに対する操作
***メッセージに対する操作
 
以下はメッセージの操作に関するメソッドとプロパティです。
以下はメッセージの操作に関するメソッドとプロパティです。
 

        

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

        

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

        

        
~
-PopClient.GetMessage()等のメソッドでIDを取得するように指定しなかった場合、UniqueIDプロパティの値を参照する際、コマンドを発行してから結果を返します。
:UniqueId|PopClient.GetMessage()等のメソッドでIDを取得するように指定しなかった場合、プロパティの値を参照する際にコマンドを発行してから結果を返します。
+
-インスタンスを作成したPopClientを切断した後にこれらのメソッド・プロパティの値を参照しようとした場合、PopProtocolViolationExceptionをスローします。
 

        

        
 
**例外
**例外
 
PopClientクラスおよびPopMessageInfoクラスからは以下の例外をスローします。 ここに明記している以外の例外クラス・状況でスローされる場合があります。
PopClientクラスおよびPopMessageInfoクラスからは以下の例外をスローします。 ここに明記している以外の例外クラス・状況でスローされる場合があります。
422,14 407,10
 
-----Smdn.Net.Pop3.Client.PopMessageDeletedException
-----Smdn.Net.Pop3.Client.PopMessageDeletedException
 
---Smdn.Net.Pop3.Client.PopMessageNotFoundException
---Smdn.Net.Pop3.Client.PopMessageNotFoundException
 

        

        
~
**非同期操作・スレッドセーフティ
**スレッドセーフティ
~
現時点で非同期操作をサポートするメソッドは、PopClient.BeginConnect()/EndConnect()のみです。 PopMessageInfo.OpenRead()については、今後のバージョンで非同期操作をサポートする予定ですが、それ以外については予定はありません。
現時点では、PopClientクラスおよびPopMessageInfoクラスはスレッドセーフではありません。 内部で使用している実装はスレッドセーフなので、処理内容によっては問題なく動作するかもしれませんが、保証はできません。 個々のインスタンスは同一スレッド内で使用してください。 今後のバージョンでスレッドセーフティを保証した実装に改善する予定です。
 

        

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

          
+
なお、アプリケーションドメインをまたがる使用については全く考慮していないため、動作および安全性の保証はできません。
+

          
+
#hr
 

        

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

        

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

        

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

        

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

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

        

        
+
#hr
+

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

        

        
714,7 691,7
 
      client.Connect("pass");
      client.Connect("pass");
 

        

        
 
      // メールボックスにある1件目のメッセージをダウンロード
      // メールボックスにある1件目のメッセージをダウンロード
~
      var message = client.GetFirstMessage();
      var message = client.GetMessage(1);
 

        

        
 
      // ファイルsample.emlに保存
      // ファイルsample.emlに保存
 
      message.Save("sample.eml");
      message.Save("sample.eml");
753,10 730,11
 
      }
      }
 

        

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

        

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