----------------------------------------------------------------------- メールチェッカプラグイン for Chararina 取扱説明書 Copyright(C) 2001-2004 Praesens, Inc. All rights reserved. http://www.praesens.co.jp/pws/ ----------------------------------------------------------------------- 1.はじめに メールチェッカプラグインをダウンロードいただきありがとうございます． メールチェッカプラグイン(以下本プラグイン)はChararina(キャラリナ)上 で動作するキャラクターと連動することが可能なプラグインです． 2,3章でキャラクターとの連携に用いるプラグイン関数の使用方法について 説明しますので，本プラグインに対応したキャラクターを作成する方はご覧 下さい． 2.プラグイン関数 本プラグインは常駐プラグインです．キャラクターからLoadPlugin関数を用 いる必要はありません． メールチェッカプラグインは綾織から呼び出せる下記のプラグイン関数を 実装しています．キャラクターからこれらのプラグイン関数を呼び出すこと で，キャラクターからメールチェッカプラグインを操作できます ・import int LF_MAILCHECKER_CheckMail() 機能 メールチェックを開始する． 引数 なし 戻り値 -3 オフラインである． -2 メールチェック中． 0 メールチェックの設定ができており，メールチェックを開始した． それ以外のエラーならそれ以外を返します． ・戻り値が0だった場合，プラグインは以下の動作を行います． 1.設定ダイアログの「巡回チェックの指定」で指定されたアカウン ト全てについて，メールチェックを行う． 2.サーバに残っていたメール一覧の情報を，プロパティの \Plugin\mailchecker\lines に入れる． ・linesは\nで区切られた複数の行からなる． ・4行で1つのメール(本文の先頭3行,Subject,From,設定名をくっ つけたもの)を表す． ・メールが複数あった場合は，この4行が繰り返される． 3.export void LF_MAILCHECKER_cCheckMail( int ret, string lines ) を呼ぶ． ・retは，成功(新着あり)なら0，成功(新着なし)なら1，エラーなら それ以外である． ・linesは，プロパティに入れたlinesと同じ． ・起動している全てのキャラクターで呼ばれる． 4.if ( まだメール一覧ウィンドウで表示していないメールが届いた && 設定ダイアログの「別ウィンドウ表示する」がonである && ( 全てのキャラクターで綾織の関数 LF_MAILCHECKER_cCheckMailが存在しない && LF_MAILCHECKER_GetMailCheckStatusが1回も呼ばれていない || 設定ダイアログの「メールチェッカに未対応の…」がonである) ) メール一覧ウィンドウを開く． 5.メール一覧ウィンドウが開かれていれば，それを更新する． ・メールチェックの結果を取得するには、以下の2つの方式があります． 方式1. コールバック関数LF_MAILCHECKER_cCheckMail()を使う 方式2. LF_MAILCHECKER_GetMailCheckStatus()を使う 方式1は当初用いられていた方法ですが、方式2と比べて以下のような欠点 があります． ・アクションを実行中は、この関数が呼ばれない ・どのメールが新着であるのか、判断しにくい ですので、できればこの方式を用いないようお願いします．代わりに方式 2を用いてください． ・import int LF_MAILCHECKER_SendMail( string addrs, string names, string subj, string text ) 機能 メールの送信を開始する． 引数 addrs メールアドレス．全てToに書かれる．Cc, Bccには対応していない． names メールアドレスに対応した名前．不要ならNULLか""を指定して下さい． subj サブジェクト． text 本文(テキスト形式，改行は\nか\r\n)． 複数のアドレスに送る場合は，addrs, namesを\nあるいは\r\nで区切って下さい． 例 fooさん(foo@foo.com)，barさん(bar@bar.com)，foobarさん (foobar@foobar.com)の3人にメールを送る場合 LF_MAILCHECKER_SendMail( "foo@foo.com" + "\n" + "bar@bar.com" + "\n" + "foobar@foobar.com", "foo" + "\n" + "bar" + "\n" + "foobar", "The Next Meeting of the Board", "The next meeting of the board of directors will be on Tuesday.\n" ) 戻り値 0 現在の設定でメール送信が許可されており，メール送信を開始した． -3 オフラインである． それ以外のエラーならそれ以外を返します． ・戻り値が0だった場合，プラグインは以下の動作を行います． 1.メールを送信する． 2.export void LF_MAILCHECKER_cSendMail( int ret )を呼ぶ． retは，成功なら0，失敗ならそれ以外である． ・import boolean LF_MAILCHECKER_CanCheckMail() 機能 メールチェックの設定がなされているかどうかを調べる． 引数 なし 戻り値 true メールチェックの設定がなされている． false メールチェックの設定がなされていない． ・import boolean LF_MAILCHECKER_CanSendMail() 機能 メール送信の設定がなされているかどうかを調べる． 引数 なし 戻り値 true メール送信の設定がなされている． false メール送信の設定がなされていない． ・import void LF_MAILCHECKER_OpenForm() 機能 メール一覧ウィンドウを開く． 既にメールチェックが行われていれば，その時の結果が一覧表示され る． 引数 なし 戻り値 なし ・import void LF_MAILCHECKER_CloseForm() 機能 メール一覧ウィンドウを閉じる． 引数 なし 戻り値 なし ・import void LF_MAILCHECKER_Config() 機能 設定ダイアログ(モーダル)を開く． 引数 なし 戻り値 なし ・この関数は，ユーザがダイアログを閉じるまで終わらないので注意 してください． ※Ver1.1(for pws1.50)より，新しく8つの関数が追加されました．これにより， 最後にメールチェックを行った時に得た情報を取得することができます． GetMailCheckStatus GetMailCount GetNewMailCount GetLastCheckTime GetConfigName GetContent GetHeader GetReceiveTime IsNewMail 以下，これらについて説明します． ・import int LF_MAILCHECKER_GetMailCheckStatus() 機能 メールチェックの結果を得る． 引数 なし 戻り値 0: 以前この関数を呼んでから1度もメールチェックを行わなかった． 1: 以前この関数を呼んだ後にメールチェックを行った．(正常にメールチェックができた) それ以外: 以前この関数を呼んだ後にメールチェックを行った．(エラーだった)(注5) ・import int LF_MAILCHECKER_GetMailCount() 機能 サーバに残っていたメールの数を得る． 引数 なし 戻り値 最後にメールチェックを行ったときにサーバに残っていたメールの数 を返します． ・import int LF_MAILCHECKER_GetNewMailCount() 機能 サーバに残っていたメールのうち，新着であるメールの数を得る． 引数 なし 戻り値 最後にメールチェックを行ったときにサーバに残っていたメールの中 で，新着(注3)であるようなメールの数を返します． ・この関数は，メールチェック後にLF_MAILCHECKER_GetMailCheckStatusを 呼んでからでないと，正しい値を返しません． ・import int LF_MAILCHECKER_GetLastCheckTime() 機能 最後にメールチェックを行った時刻を得る． 引数 なし 戻り値 最後にメールチェックを行った時刻(注2)を返します． キャラクターを再起動すると，0にリセットされます． ・import string LF_MAILCHECKER_GetConfigName( int index ) 機能 メールの設定名を得る． 引数 index メールの番号(注1) 戻り値 メールの設定名(設定ダイアログの「アカウント」ページの「設定名」 で指定した項目)を返します． indexが無効なら，NULLを返します． ・import string LF_MAILCHECKER_GetContent( int index ) 機能 メールの先頭3行を得る． 引数 index メールの番号(注1) 戻り値 メールの先頭3行を返します．改行は，\nになります． indexが無効なら，NULLを返します． 設定ダイアログの「キャラクターに受信内容を通知する」がoffなら， NULLを返します． ・MIMEのマルチパートには対応していません． ・import string LF_MAILCHECKER_GetHeader( int index, string fieldname ) 機能 メールのヘッダのフィールドボディを得る． 引数 index メールの番号(注1) fieldname: ヘッダのフィールド名("from"とか"subject"とか) 戻り値 メールのヘッダのフィールドボディを返します(MIMEエンコードされて いた場合は，自動でデコードされます)． indexが無効なら，NULLを返します． 設定ダイアログの「キャラクターに受信内容を通知する」がoffなら， NULLを返します． ・import int LF_MAILCHECKER_GetReceiveTime( int index ) 機能 メールを検出した時刻を得ます． 引数 index メールの番号(注1) 戻り値 メールを検出した時刻(注2)を返します． indexが無効なら，0を返します． ・import boolean LF_MAILCHECKER_IsNewMail( int index ) 機能 メールが新着かどうかを得ます． 引数 index メールの番号(注1) 戻り値 メールが新着(注3)ならtrueを，新着でないならfalseを返します． indexが無効なら，falseを返します． ・import boolean LF_MAILCHECKER_IsChecking(); 機能 メールチェック中かどうかを判断します． 戻り値 メールチェック中ならtrueを、そうでなければfalseを返します． ・import boolean LF_MAILCHECKER_SetConfig( int index, string key, string value ); 機能 メールチェッカの設定を書きかえます． 引数 index 設定を保存する領域．0〜9を指定可能． (現在のメールチェッカは，最大10個しか設定を記憶できません) key 以下の文字列を指定することが可能です．(大文字小文字の区別なし) "ConfigName" 設定名 "UserName" ユーザ名 "Password" パスワード "SavePassword" パスワードを保存するか("1"で保存，"0"で非保存) "PopServer" POPサーバ "PopPort" POPポート "Apop" APOPで認証するか("1"でAPOP認証，"0"で普通(POP3)の認証) value 設定すべき値 戻り値 設定が成功すればtrueを、失敗すればfalseを返します． ・keyを"ConfigName"にしてvalueをNULLか""にすると、設定を消すことができます． ・keyを"ConfigName"にしてvalueを新しい設定名にすると，新しく設定を作ることができます． 設定名のない領域に，"ConfigName"以外のkeyを指定して書き込むことはできません． ・import string LF_MAILCHECKER_GetConfig( int index, string key ); 機能 メールチェッカの設定を読み取ります． 引数 index 設定を保存する領域．0〜9を指定可能． key LF_MAILCHECKER_SetConfigのkeyと同じ． 但し，"Password"は指定できない． 戻り値 成功すれば、設定されている値を文字列にして返します． 失敗なら，NULLを返します． (注1) indexは，0からLF_MAILCHECKER_GetMailCount()-1までの値のみ有効です． (注2) 時刻は，1970/1/1からの秒数で表されます． (注3) 「新着である」とは？ メールチェッカが初めて検出したメールは「新着である」とみなされます． その後、あるキャラクターがLF_MAILCHECKER_GetMailCheckStatusを2回呼ぶ と，2回目のLF_MAILCHECKER_GetMailCheckStatusの直前に「そのキャラクター にとっては新着でない」とみなされるようになります． これは，新着メールの情報を以下のように取得することを想定した仕様です． ・まず，LF_MAILCHECKER_GetMailCheckStatusでメールチェックを行った かどうかを判断する． ・メールチェックを行ったなら，LF_MAILCHECKER_GetNewMailCountで新着 メールの有無を判断する． ・新着メールがあるなら，次にLF_MAILCHECKER_IsNewMailでどのメールが 新着であるかを判断する． ・新着と判断されたメールの情報を，LF_MAILCHECKER_GetHeaderなどで取 得する． ※Ver1.22(for pws2.04?)より，新しく2つの関数が追加されました． OpenMailer CanOpenMailer 以下，これらについて説明します． ・import int LF_MAILCHECKER_OpenMailer() 機能 メーラを起動する． 引数 なし 戻り値 0: メーラの起動に成功した． それ以外: メーラの起動に失敗した． ・import boolean LF_MAILCHECKER_CanOpenMailer() 機能 メーラを起動できるかどうかを調べる 引数 なし 戻り値 true: メーラを起動できる． false: メーラを起動できない． 3.コールバック関数 ・export void LF_MAILCHECKER_cCheckMail( int errorcode, string lines ) LF_MAILCHECKER_CheckMailが呼ばれてメールチェックが行われた場合， あるいはユーザが右クリックメニューからメールチェックを行った場合， あるいは自動メールチェックで新着メールがあった場合に、 起動中の全てのキャラクターでこの関数が呼ばれます． 引数 lines LF_MAILCHECKER_CheckMailでプロパティに入れたlinesと同 じ． errorcode 成功(新着あり)なら0，成功(新着なし)なら1，エラーなら それ以外(注5)である． ・この関数が呼ばれるべき時に何らかのアクションを実行している場合は， この関数は呼ばれません． ・export void LF_MAILCHECKER_cSendMail( int errorcode ) LF_MAILCHECKER_SendMailが呼ばれてメール送信が行われると，この 関数が呼ばれます． 引数 errorcode 成功なら0，エラーならそれ以外(注5)である． 4.著作権，免責事項など 知的財産権 ・本ソフトウェア(画像・ドキュメントを含む)に関する一切の著作権その他 の無体財産権は，プラエセンス株式会社が所有します． 禁止事項 ・お客様は，本ソフトウェアについて，変更，改変，複製を行うことはでき ません． ・お客様は，本ソフトウェアについて，リバースエンジニアリング，逆コン パイル・逆アセンブル，その他の方法でソースコードを解析することはで きません．また，本ソフトウェアが生成するデータファイルについて，リ バースエンジニアリングすることはできません． 免責事項 ・本ソフトウェアは現状のままで提供されるものであり，当社は，本ソフト ウェアに関して，完全性・正確性・有用性・第三者の権利不侵害性・その 他一切の保証を致しません． ・当社は，本ソフトウェアの瑕疵，不具合等ならびに本ソフトウェアを使用 した結果および使用不可につき，修補義務・保守義務・その他いかなる責 任も負いません． 5. 変更履歴 2001/6/30 for 1.50β1 ・プロトタイプ完成 2001/7/17 for 1.50β2 ・IE3の環境で巡回チェックの設定ができなかったバグを修正． ・キャラクタを切り替えるとメールチェッカが使えなくなるバグを修正． ・通信中に回線が切れるとアクセス違反が出るバグを修正． ・「パスワードを保存する」の設定を付加． ・右クリックメニューからメールチェックを行った場合，新着が無くてもメー ル一覧ウィンドウを出すようにした． ・メールチェック中・オフライン中は，メールチェック要求を拒否するように した． ・自動チェックで新着が無い場合，結果を通知しないようにした． ・DLLサイズを減らした． 2001/7/31 for 1.50β3 ・メールチェック時，最後にサーバにQUITを送ってなかったのを修正. ・6個目のアカウントを入力しようとするとバグが出るのを修正. ・tooltipでのヘルプを設定ダイアログに付加． ・「受信したメールの内容をキャラクタに通知しない」の設定を付加． ・DLLサイズを減らした． 2001/9/19 Ver1.1 (for pws1.50) ・メール一覧ウィンドウを開いたままキャラクタを終了すると例外が出るのを修 正． ・LF_MAILCHECKER_cCheckMailが呼ばれる条件を修正． ・プロパティの\Plugin\mailchecker\linesにデータが書かれていなかったの を修正． ・以下の9つの関数を追加． GetMailCheckStatus GetMailCount GetNewMailCount GetLastCheckTime GetConfigName GetContent GetHeader GetReceiveTime IsNewMail ・設定ダイアログに，「メールチェッカに未対応のキャラクタでも表示」を追加． ・メール一覧ウィンドウに，「新着(注4)」と「日時」(メールが作成された日 時)の欄を追加． 2001/10/2 for pws1.51β1 ・プロパティーに入れていたlinesの中身の行を反転した． 設定名,From,Subject,本文の先頭3行 の順だったのを， 本文の先頭3行,Subject,From,設定名 の順にした． 2001/10/26 Ver1.12 (for pws1.51β2) ・サーバが3分間反応しない場合はタイムアウトするように修正． ・右クリックメニューからメールチェックを行ったとき，オフライン中あるい は既にメールチェック中であった場合はエラーダイアログを出すように修正． ・既知のメールと同じSubjectのメールが新しく届いた場合，それを新着と判 断していなかったのを修正． ・メールチェック中にキャラクタを切り替えると例外が出るのを修正． 2001/10/30 Ver1.13 ・以下の3つの関数を追加． IsChecking GetConfig SetConfig 2001/11/22 Ver1.14 (for pws1.51β3) ・（内部修正） ・設定ダイアログのtooltipでのヘルプを、微妙に修正． 2001/11/27 Ver1.15 ・メールチェック時に認証に失敗するバグ(Ver1.14)を修正． ・エラーダイアログは、右クリックからのチェック時のみ出すように修正． ・エラーダイアログの文面の修正． 2001/12/3 Ver1.16 ・tooltipでのヘルプが出るまでの時間が短くなるように修正． 2001/12/12 Ver1.17 (for pws1.51β4) ・cCheckMail, cSendMail, GetMailCheckStatusでエラーコード(注5)を返すよ うに修正． ・エラーメッセージをoutlook風に修正． 2002/1/15 Ver1.18 ・キャラクタを「常に手前に表示」にしていると、設定ダイアログがキャラクタの 後ろに隠れてしまうのを修正. 2002/3/4 Ver1.19 ・メールの一覧表示で，3月と5月が逆になっていたのを修正． 2002/6/12 Ver1.20 ・関数を呼ぶタイミングによって新着の判断を誤るバグを修正. 2002/8/24 ver1.21 ・メール中に長さが約1000文字以上の行があるとメールチェックに失敗するの を修正. 2003/2/21 ver1.22 ・キャラクタ、メール一覧ウィンドウからメーラを起動できるようにした． ・以下の2つの関数を追加． OpenMailer CanOpenMailer 2003/3/25 ver1.23 ・設定ダイアログにアクセラレータキーをつけた 2003/5/6 ver1.24 ・GetContentの戻り値の中の改行が消えているバグを修正． 2003/7/27 ver1.25 ・デコードに失敗することがあるのを修正． (注4) メール一覧ウィンドウに表示される「新着」は，注3で述べた新着と同 じではありません． メール一覧ウィンドウは，メールチェックで新しいメールを検出すると，そ のメールを新着であるとみなします．一度新着とみなされると，新しいメー ルが検出されるまで新着のままです． (注5) よくあるエラーコードは、以下のとおりです． -1: 内部エラー(バグ報告をお願いします) -10: サーバがAPOPに対応していませんでした -14: POPサーバがエラーを返しました -16: POP認証に失敗しました(ユーザ名・パスワードが違う?) -17: APOP認証に失敗しました(ユーザ名・パスワードが違う?) -18: サーバから切断されました(サーバが混んでいる??) -19: サーバの応答が異常だ(POPサーバではない?ポートが違う?) -20: 認証に失敗しました(ユーザ名が違う?) -21,-22: 送受信中にタイムアウトしました (サーバ・ネットワークが混んでいる??) 10053: (サーバ・ネットワークが混んでいる??) 10054: サーバとの接続がリセットされました(サーバが混んでいる??) 10060: タイムアウトしました(サーバ・ネットワークが混んでいる?? サーバの指定が間違っている?) 10061: サーバへの接続が拒否されました (ポートの指定が間違っている? サーバの指定が間違っている? サーバが稼動していない?) 10065, 11001, 11002, 11004: サーバが見つかりませんでした (サーバの指定が間違っている? ネットワークに接続されていない?)