メインコンテンツまでスキップ
バージョン: 20 R9 BETA

IMAPTransporter

IMAPTransporter クラスを使って、IMAP メールサーバーからメッセージを取得することができます。

IMAP Transporter オブジェクト

IMAP Transporter オブジェクトは IMP New transporter コマンドによってインスタンス化されます。 これらは、次のプロパティや関数を持ちます:

.acceptUnsecureConnection : Boolean
暗号化されていない接続の確立が許可されてれば true
.addFlags( msgIDs : Collection ; keywords : Object ) : Object
.addFlags( msgIDs : Text ; keywords : Object ) : Object
.addFlags( msgIDs : Longint ; keywords : Object ) : Object

msgIDs のメッセージに対して、keywords で指定したフラグを追加します
.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object
destinationBox に指定したメールボックスに、mailObj のメールを追加します
.authenticationMode : Text
メールサーバーのセッションを開くのに使用される認証モード
.checkConnection() : Object
transporter オブジェクトが保存する情報を使用して接続をチェックします
.checkConnectionDelay : Integer
サーバー接続をチェックするまでの最長時間 (秒単位)
.connectionTimeOut : Integer
サーバー接続の確立までに待機する最長時間 (秒単位)
.copy( msgsIDs : Collection ; destinationBox : Text ) : Object
.copy( allMsgs : Integer ; destinationBox : Text ) : Object

msgsIDs または allMsgs で定義されたメッセージを IMAP サーバーの destinationBox へとコピーします
.createBox( name : Text ) : Object
name に指定した名称の新規メールボックスを作成します
.delete( msgsIDs : Collection ) : Object
.delete( allMsgs : Integer ) : Object

msgsIDs または allMsgs が指定するメッセージに対して "削除済み" フラグを設定します
.deleteBox( name : Text ) : Object
name に指定した名称のメールボックスを IMAPサーバーから完全に削除します
.expunge() : Object
removes all messages with the "deleted" flag from the IMAP mail server.
.getBoxInfo( { name : Text }) : Object
カレントメールボックス、または name が指定するメールボックスに対応する boxInfo オブジェクトを返します
.getBoxList( { parameters : Object } ) : Collection
利用可能なメールボックスの情報を mailbox オブジェクトのコレクションとしてを返します
.getDelimiter() : Text
メールボックス名で階層レベルを区切るのに使用される文字を返します
.getMail( msgNumber: Integer { ; options : Object } ) : Object
.getMail( msgID: Text { ; options : Object } ) : Object

IMAP_transporter が指定するメールボックス内の、msgNumber または msgID に対応するメールを Email オブジェクトとして返します
.getMails( ids : Collection { ; options : Object } ) : Object
.getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object

Email オブジェクトのコレクションを格納したオブジェクトを返します
.getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob
.getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob

IMAP_transporter が指定するメールボックス内の、msgNumber または msgID に対応するメッセージの MIMEコンテンツを格納した BLOB を返します
.host : Text
ホストサーバーの名前または IPアドレス
.logFile : Text
メール接続に対して定義された拡張ログファイル (あれば) へのフルパス
.move( msgsIDs : Collection ; destinationBox : Text ) : Object
.move( allMsgs : Integer ; destinationBox : Text ) : Object

msgsIDs または allMsgs で定義されたメッセージを IMAP サーバーの destinationBox へと移動します
.numToID( startMsg : Integer ; endMsg : Integer ) : Collection
startMsg および endMsg で指定された連続した範囲のメッセージのシーケンス番号を IMAP固有IDへと変換します
.removeFlags( msgIDs : Collection ; keywords : Object ) : Object
.removeFlags( msgIDs : Text ; keywords : Object ) : Object
.removeFlags( msgIDs : Longint ; keywords : Object ) : Object

msgIDs のメッセージに対して、keywords で指定したフラグを削除します
.renameBox( currentName : Text ; newName : Text ) : Object
IMAPサーバー上でメールボックスの名称を変更します
.port : Integer
メール通信に使用されるポート番号
.searchMails( searchCriteria : Text ) : Collection
カレントメールボックスにおいて searchCriteria の検索条件に合致するメッセージを検索します
.selectBox( name : Text { ; state : Integer } ) : Object
name に指定したメールボックスをカレントメールボックスとして選択します
.subscribe( name : Text ) : Object
IMAPサーバーの購読メールボックスとして任意のメールボックスを追加します
.unsubscribe( name : Text ) : Object
指定したメールボックスを購読メールボックスから削除します
.user : Text
メールサーバーでの認証に使用されたユーザー名

4D.IMAPTransporter.new()

4D.IMAPTransporter.new( server : Object ) : 4D.IMAPTransporter

引数説明
serverObject->メールサーバー情報
戻り値4D.IMAPTransporter<-IMAP transporter オブジェクト

説明

4D.IMAPTransporter.new() 関数は、新規の 4D.IMAPTransporter型オブジェクトを作成して返します。 この関数の機能は、IMAP New transporter コマンドと同一です。

.acceptUnsecureConnection

履歴
リリース内容
17 R4追加

.acceptUnsecureConnection : Boolean

説明

.acceptUnsecureConnection プロパティは、暗号化された接続が不可能な場合に、 暗号化されていない接続の確立が許可されてれば true を格納します。

暗号化されていない接続が許可されていない場合には false が格納されており、その場合に暗号化された接続が不可能な場合にはエラーが返されます。

使用可能なセキュアなポートは次のとおりです:

  • SMTP

    • 465: SMTPS
    • 587 または 25: STARTTLS アップグレードがされた SMTP (サーバーがサポートしていれば)
  • IMAP

    • 143: IMAP 非暗号化ポート
    • 993: STARTTLS アップグレードがされた IMAP (サーバーがサポートしていれば)
  • POP3

    • 110: POP3 非暗号化ポート
    • 995: STARTTLS アップグレードがされた POP3 (サーバーがサポートしていれば)

.addFlags()

履歴
リリース内容
20カスタムキーワードをサポート
18 R6追加

.addFlags( msgIDs : Collection ; keywords : Object ) : Object
.addFlags( msgIDs : Text ; keywords : Object ) : Object
.addFlags( msgIDs : Longint ; keywords : Object ) : Object

引数説明
msgIDsCollection->文字列のコレクション: メッセージの固有ID (テキスト型)
テキスト: メッセージの固有ID
倍長整数 (IMAP all): 選択されたメールボックス内の全メッセージ
keywordsObject->追加するキーワードフラグ
戻り値Object<-addFlags処理のステータス

説明

.addFlags() 関数は、 msgIDs のメッセージに対して、keywords で指定したフラグを追加します。

msgIDs には、以下のいずれかを渡すことができます:

  • 指定するメッセージの固有ID を格納した コレクション
  • 単一のメッセージの固有ID (テキスト)
  • 以下の定数 (longint) を使用することで、選択されているメールボックスの全メッセージを指定することができます:
定数説明
IMAP all1選択されたメールボックスの全メッセージを選択します

keywords を使って、msgIDs 引数で指定したメッセージに対して追加するフラグを定義します。 以下の標準フラグおよびカスタムフラグを使用することができます (カスタムフラグのサポートはサーバーの実装に依存します)。

プロパティ説明
$draftBooleanメッセージに "draft" フラグを追加するには true
$seenBooleanメッセージに "seen" フラグを追加するには true
$flaggedBooleanメッセージに "flagged" フラグを追加するには true
$answeredBooleanメッセージに "answered" フラグを追加するには true
$deletedBooleanメッセージに "deleted" フラグを追加するには true
<custom flag>Booleanメッセージにカスタムフラグを追加するには true

カスタムフラグ名は、次の規則に従う必要があります: キーワードは、制御文字とスペースを含まない、文字の大小を区別する文字列であり、次の文字は使用できません: ( ) { ] % * " \

  • キーワードが考慮されるためには、その値が true でなければなりません。
  • キーワードフラグの解釈は、メールクライアントごとに異なる可能性があります。

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題

var $options;$transporter;$boxInfo;$status : Object

$options:=New object
$options.host:="imap.gmail.com"
$options.port:=993
$options.user:="4d@gmail.com"
$options.password:="xxxxx"

// transporter を作成します
$transporter:=IMAP New transporter($options)

// メールボックスを選択します
$boxInfo:=$transporter.selectBox("INBOX")

// INBOXの全メッセージを既読に設定します
$flags:=New object
$flags["$seen"]:=True
$status:=$transporter.addFlags(IMAP all;$flags)

.append()

履歴
リリース内容
18 R6追加

.append( mailObj : Object ; destinationBox : Text ; options : Object ) : Object

引数説明
mailObjObject->Email オブジェクト
destinationBoxText->Emailオブジェクトを受信するメールボックス
optionsObject->文字セット情報を格納したオブジェクト
戻り値Object<-append処理のステータス

説明

.append() 関数は、destinationBox に指定したメールボックスに、mailObj のメールを追加します。

mailObj には、Email オブジェクトを渡します。 メールプロパティに関する包括的な詳細については、Email オブジェクト を参照ください。 .append() 関数は Email オブジェクトの keywords 属性内のキーワードタグをサポートします。

任意の destinationBox には、mailObj が追加されるメールボックスの名前を指定することができます。 省略した場合は、カレントメールボックスが使用されます。

任意の options には、メールの特定部分の文字セットやエンコーディングを定義するオブジェクトを渡すことができます。 次のプロパティを含みます:

プロパティ説明
headerCharsetTextメールの以下の部分で使用される文字セットとエンコーディング: 件名、添付ファイル名、メール名の属性。 取り得る値: 以下の可能な文字セットテーブルを参照ください。
bodyCharsetTextメールの HTML およびテキスト本文コンテンツで使用される文字セットとエンコーディング。 取り得る値: 以下の可能な文字セットテーブルを参照ください。

使用可能な文字セット:

定数説明
mail mode ISO2022JPUS-ASCII_ISO-2022-JP_UTF8_QP
  • headerCharset: 可能なら US-ASCII、次に可能なら Japanese (ISO-2022-JP) & Quoted-printable、それも不可なら UTF-8 & Quoted-printable
  • bodyCharset: 可能なら US-ASCII、次に可能なら Japanese (ISO-2022-JP) & 7-bit、それも不可なら UTF-8 & Quoted-printable
mail mode ISO88591ISO-8859-1
  • headerCharset: ISO-8859-1 & Quoted-printable
  • bodyCharset: ISO-8859-1 & 8-bit
mail mode UTF8US-ASCII_UTF8_QPheaderCharset & bodyCharset: 可能なら US-ASCII、それが不可なら UTF-8 & Quoted-printable (デフォルト値)
mail mode UTF8 in base64US-ASCII_UTF8_B64headerCharset & bodyCharset: 可能な場合は US-ASCII、それ以外は UTF-8 & base64

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題

Drafts メールボックスにメールを保存します:

var $settings; $status; $msg; $imap: Object

$settings:=New object("host"; "domain.com"; "user"; "xxxx"; "password"; "xxxx"; "port"; 993)

$imap:=IMAP New transporter($settings)

$msg:=New object
$msg.from:="xxxx@domain.com"
$msg.subject:="Lorem Ipsum"
$msg.textBody:="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
$msg.keywords:=New object
$msg.keywords["$seen"]:=True // メッセージに既読フラグをつけます
$msg.keywords["$draft"]:=True // メッセージに下書きフラグをつけます

$status:=$imap.append($msg; "Drafts")

.authenticationMode

履歴
リリース内容
17 R4追加

.authenticationMode : Text

説明

.authenticationMode プロパティは、 メールサーバーのセッションを開くのに使用される認証モードを格納します。

デフォルトでは、サーバーによってサポートされている最も安全なモードが使用されます。

とりうる値:

定数説明
CRAM-MD5IMAP authentication CRAM MD5CRAM-MD5 プロトコルを使用した認証
LOGINIMAP authentication loginLOGIN プロトコルを使用した認証
OAUTH2IMAP authentication OAUTH2OAuth2 プロトコルを使用した認証
PLAINIMAP authentication plainPLAIN プロトコルを使用した認証

.checkConnection()

履歴
リリース内容
17 R4追加

.checkConnection() : Object

引数説明
戻り値Object<-transporter オブジェクト接続のステータス

説明

.checkConnection() 関数は、transporter オブジェクトが保存する情報を使用して接続をチェックします。必要なら再接続をし、そのステータスを返します。 この関数を使用して、ユーザーから提供された値が有効かどうかを検証することができます。

返されるオブジェクト

この関数はメールサーバーにリクエストを送信し、メールステータスを表すオブジェクトを返します。 このオブジェクトには、次のプロパティが格納されることがあります:

プロパティ説明
successbooleanチェックが成功した場合には true、それ以外は false
statusnumber(SMTPのみ) メールサーバーから返されたコード (メール処理に関係ない問題の場合には 0)
statusTexttextメールサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorscollection4Dエラースタック (メールサーバーレスポンスが受信できた場合には返されません)
[ ].errCodenumber4Dエラーコード
[ ].messagetext4Dエラーの詳細
[ ].componentSignaturetextエラーを返した内部コンポーネントの署名

.checkConnectionDelay

履歴
リリース内容
18 R4追加

.checkConnectionDelay : Integer

説明

.checkConnectionDelay 関数は、サーバー接続をチェックするまでの最長時間 (秒単位) を格納します。 関数呼び出しの間隔がこの時間を超過する場合、サーバー接続が確認されます。 プロパティが server オブジェクトによって設定されていない場合は、デフォルトで 300 という値が使用されます。

警告: 定義されたタイムアウトが、サーバータイムアウトより短いようにしてください。そうでない場合、クライアントタイムアウトは無意味になります。

.connectionTimeOut

履歴
リリース内容
17 R5追加

.connectionTimeOut : Integer

説明

.connectionTimeOut プロパティは、サーバー接続の確立までに待機する最長時間 (秒単位)を格納します。 SMTP New transporterPOP3 New transporterIMAP New transporter のコマンドで transporter オブジェクトを作成する際に使用される server オブジェクトにおいて、 このプロパティが指定されなかった場合のデフォルトは 30 です。

.copy()

履歴
リリース内容
18 R5追加

.copy( msgsIDs : Collection ; destinationBox : Text ) : Object
.copy( allMsgs : Integer ; destinationBox : Text ) : Object

引数説明
msgsIDsCollection->メッセージの固有ID のコレクション (テキスト)
allMsgsInteger->IMAP all: 選択されたメールボックスの全メッセージ
destinationBoxText->メッセージのコピー先のメールボックス
戻り値Object<-copy処理のステータス

説明

.copy() 関数は、msgsIDs または allMsgs で定義されたメッセージを IMAP サーバーの destinationBox へとコピーします。

以下のものを渡すことができます:

  • msgsIDs には、コピーするメッセージの固有ID を格納したコレクション
  • allMsgs には、選択されているメールボックスの全メッセージをコピーするための定数 (倍長整数型):

destinationBox には、メッセージのコピー先メールボックスの名称をテキスト値で渡すことができます。

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題 1

選択されたメッセージをコピーします:

 var $server;$boxInfo;$status : Object
var $mailIds : Collection
var $transporter : 4D.IMAPTransporter

$server:=New object
$server.host:="imap.gmail.com" // 必須
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"

$transporter:=IMAP New transporter($server)

// メールボックスを選択します
$boxInfo:=$transporter.selectBox("inbox")

// メッセージの固有ID のコレクションを取得します
$mailIds:=$transporter.searchMails("subject \"4D new feature:\"")

// 見つかったメッセージを "documents" メールボックスへコピーします
$status:=$transporter.copy($mailIds;"documents")

例題 2

カレントメールボックスの全メッセージをコピーします:

 var $server;$boxInfo;$status : Object
var $transporter : 4D.IMAPTransporter

$server:=New object
$server.host:="imap.gmail.com" // 必須
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"

$transporter:=IMAP New transporter($server)

// メールボックスを選択します
$boxInfo:=$transporter.selectBox("inbox")

// 全メッセージを "documents" メールボックスへコピーします
$status:=$transporter.copy(IMAP all;"documents")

.createBox()

履歴
リリース内容
19追加

.createBox( name : Text ) : Object

引数説明
nameText->新規メールボックスの名称
戻り値Object<-createBox処理のステータス

説明

.createBox() 関数は、name に指定した名称の新規メールボックスを作成します。 IMAPサーバーの階層区切り文字がメールボックス名内に含まれる場合、IMAPサーバーは指定のメールボックスを作成するのに必要な親階層を作成します。

たとえば、"/" が階層区切り文字として使われるサーバーにおいて、"Projects/IMAP/Doc" を作成しようとした場合:

  • "Projects" & "IMAP" がすでに存在する場合は "Doc" メールボックスのみを作成します。
  • “Projects” のみが存在する場合は、"IMAP" & "Doc" メールボックスを作成します。
  • いずれも存在しない場合には、"Projects" & "IMAP" & "Doc" メールボックスをそれぞれ作成します。

name には、新しいメールボックスの名前を渡します。

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題

新しい “Invoices” メールボックスを作成します:

var $pw : text
var $options; $transporter; $status : object

$options:=New object

$pw:=Request("パスワードを入力してください:")
If(OK=1)
$options.host:="imap.gmail.com"
$options.user:="test@gmail.com"
$options.password:=$pw

$transporter:=IMAP New transporter($options)

$status:=$transporter.createBox("Invoices")

If ($status.success)
ALERT("メールボックスが作成できました。")
Else
ALERT("エラー: "+$status.statusText)
End if
End if

.delete()

履歴
リリース内容
18 R5追加

.delete( msgsIDs : Collection ) : Object
.delete( allMsgs : Integer ) : Object

引数説明
msgsIDsCollection->メッセージの固有ID のコレクション (テキスト)
allMsgsInteger->IMAP all: 選択されたメールボックスの全メッセージ
戻り値Object<-delete処理のステータス

説明

.delete() 関数は、 msgsIDs または allMsgs が指定するメッセージに対して "削除済み" フラグを設定します。

以下のものを渡すことができます:

  • msgsIDs には、削除するメッセージの固有ID を格納したコレクション
  • allMsgs には、選択されているメールボックスの全メッセージを削除するための定数 (倍長整数型):

この関数を実行しても、メールが実際に削除される訳ではありません。 "削除済み" フラグがつけられたメッセージも引き続き .searchMails() 関数によって検索可能です。 フラグがつけられたメッセージは、.expunge() を実行したときか、別のメールボックスを選択したとき、あるいは(IMAP New transporter で作成された) transporter オブジェクト が消去されたときにのみ、IMAPサーバーから削除されます。

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題 1

選択されたメッセージを削除します:

 var $server;$boxInfo;$status : Object
var $mailIds : Collection
var $transporter : 4D.IMAPTransporter

$server:=New object
$server.host:="imap.gmail.com" // 必須
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"

$transporter:=IMAP New transporter($server)

// メールボックスを選択します
$boxInfo:=$transporter.selectBox("Inbox")

// メッセージの固有ID のコレクションを取得します
$mailIds:=$transporter.searchMails("subject \"Reports\"")

// 選択されたメッセージを削除します
$status:=$transporter.delete($mailIds)

例題 2

カレントメールボックスの全メッセージを削除します:

 var $server;$boxInfo;$status : Object
var $transporter : 4D.IMAPTransporter

$server:=New object
$server.host:="imap.gmail.com" // 必須
$server.port:=993
$server.user:="4d@gmail.com"
$server.password:="XXXXXXXX"

$transporter:=IMAP New transporter($server)

//メールボックスを選択します
$boxInfo:=$transporter.selectBox("Junk Email")

// カレントメールボックスの全メッセージを削除します
$status:=$transporter.delete(IMAP all)

.deleteBox()

履歴
リリース内容
19追加

.deleteBox( name : Text ) : Object

引数説明
nameText->削除するメールボックスの名称
戻り値Object<-deleteBox処理のステータス

説明

.deleteBox() 関数は、 name に指定した名称のメールボックスを IMAPサーバーから完全に削除します。 存在しないメールボックス、または INBOX を削除しようとして場合には、エラーが生成されます。

name には、削除するメールボックスの名前を渡します。

  • 子メールボックスを持つ親メールボックスが "\Noselect" 属性を持っている場合、そのメールボックスは削除できません。
  • 削除されるメールボックス内のメッセージもすべて削除されます。
  • メールボックス削除の可否はメールサーバーに依存します。

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題

"Bills" メールボックスの階層から、"Nova Orion Industries" の子メールボックスを削除します:

var $pw; $name : text
var $options; $transporter; $status : object

$options:=New object

$pw:=Request("パスワードを入力してください:")

If(OK=1) $options.host:="imap.gmail.com"
$options.user:="test@gmail.com"
$options.password:=$pw

$transporter:=IMAP New transporter($options)

// delete mailbox
$name:="Bills"+$transporter.getDelimiter()+"Nova Orion Industries"
$status:=$transporter.deleteBox($name)

If ($status.success)
ALERT("メールボックスが削除されました。")
Else
ALERT("エラー: "+$status.statusText)
End if
End if

.expunge()

履歴
リリース内容
18 R6追加

.expunge() : Object

引数説明
戻り値Object<-expunge処理のステータス

説明

The .expunge() function removes all messages with the "deleted" flag from the IMAP mail server. The "deleted" flag can be set with the .delete() or .addFlags() methods.

返されるオブジェクト

この関数は、IMAP ステータスを表すオブジェクトを返します:

プロパティ説明
successBoolean処理が正常に終わった場合には true、それ以外は false
statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
[].errcodeNumber4Dエラーコード
[].messageText4Dエラーの詳細
[].componentSignatureTextエラーを返した内部コンポーネントの署名

例題

var $options;$transporter;$boxInfo;$status : Object
var $ids : Collection

$options:=New object
$options.host:="imap.gmail.com"
$options.port:=993
$options.user:="4d@gmail.com"
$options.password:="xxxxx"

// transporter を作成します
$transporter:=IMAP New transporter($options)

// メールボックスを選択します
$boxInfo:=$transporter.selectBox("INBOX")

// INBOX の既読メッセージに削除フラグを立てます
$ids:=$transporter.searchMails("SEEN")
$status:=$transporter.delete($ids)

// "deleted" フラグがついたメッセージをすべて消去します
$status:=$transporter.expunge()

.getBoxInfo()

履歴
リリース内容
20id が返されます
18 R5name は任意です
18 R4追加

.getBoxInfo( { name : Text }) : Object

引数説明
nameText->メールボックスの名称
戻り値Object<-boxInfo オブジェクト

説明

.getBoxInfo() 関数は、カレントメールボックス、または name が指定するメールボックスに対応する boxInfo オブジェクトを返します。 この関数は、.selectBox() と同じ情報を返しますが、カレントメールボックスは変えません。

任意の name パラメーターには、アクセスするメールボックスの名称を渡します。 この名称は明確な左から右への階層を表し、特定の区切り文字でレベルを区分けします。 この区切り文字は .getDelimiter() 関数で調べることができます。

name のメールボックスが選択不可の場合、または見つからない場合には、関数はエラーを生成し、null を返します。

返されるオブジェクト

返される boxInfo オブジェクトには、以下のプロパティが格納されています:

プロパティ説明
nameTextメールボックスの名称
mailCountNumberメールボックス内のメッセージの数
mailRecentNumber(新しいメッセージであることを表す) "recent" フラグがついたメッセージの数
idtextメールボックスの固有ID
mailUnseenNumber"unseen" フラグがついたメッセージの数

例題

 var $transporter : 4D.IMAPTransporter
$transporter:=IMAP New transporter($server)

$info:=$transporter.getBoxInfo("INBOX")
ALERT("INBOX には "+String($info.mailRecent)+" 件の最近のメールがあります。")

.getBoxList()

履歴
リリース内容
18 R4追加
19isSubscribed を追加

.getBoxList( { parameters : Object } ) : Collection

引数説明
parametersObject->引数のオブジェクト
戻り値Collection<-mailbox オブジェクトのコレクション

説明

.getBoxList() 関数は、利用可能なメールボックスの情報を mailbox オブジェクトのコレクションとしてを返します。 この関数を使用すると、IMAPメールサーバー上にあるメッセージの一覧をローカルで管理することができるようになります。

任意の parameters パラメーターには、返されるメールボックスをフィルターするための値を格納したオブジェクトを渡すことができます。 以下のものを渡すことができます:

プロパティ説明
isSubscribedBoolean
  • True: 購読しているメールボックスのみを返します。
  • False: すべての利用可能なメールボックスを返します。
  • namesCollection"name" 属性を含むオブジェクトのコレクション、またはボックス名を含むテキストのコレクション
    withBoxPropertiesBooleantrue の場合 (デフォルト): 結果のオブジェクトに selectableinferiorinteresting 属性を追加します。 false の場合、これらの属性は省略されます。
    withBoxInfoBooleanデフォルト値は false です。 true の場合、結果のオブジェクトに mailCountmailRecent、および id 属性を追加します。

    戻り値

    返されるコレクションの各オブジェクトには、以下のプロパティが格納されています:

    プロパティ説明
    [].nameTextメールボックスの名称。 withBoxProperties=true または withBoxInfo=true の場合に返されます
    [].selectableBooleanアクセス権でメールボックスを選択できるかどうかを表します:
    • true - メールボックスは選択可能
    • false - メールボックスは選択不可能
    withBoxProperties=true の場合に返されます
    [].inferiorBooleanアクセス権でメールボックス内に下の階層レベルを作成できるかどうかを表します:
    • true - 下の階層レベルは作成可能
    • false - 下の階層レベルは作成不可能
    withBoxProperties=true の場合に返されます
    [].interestingBooleanサーバーがメールボックスに “interesting” のマーク付けをしているかどうかを表します:
    • true - メールボックスはサーバーから "interesting" のマーク付けをされています。 たとえば、メールボックスには新着メッセージが入っている場合が考えられます。
    • false - メールボックスはサーバーから "interesting" のマーク付けをされていません。
    withBoxProperties=true の場合に返されます
    [].mailCountNumber受信ボックス内のメッセージの数。 withBoxInfo=true の場合に返されます
    [].mailRecentNumber(新しいメッセージであることを表す) "recent" フラグがついたメッセージの数。 withBoxInfo=true の場合に返されます
    [].mailUnseenNumber"unseen" フラグがついたメッセージの数。 withBoxInfo=true の場合に返されます
    [].idText一意のメールボックス識別子。 withBoxInfo=true の場合に返されます

    アカウントにメールボックスが一つもない場合、空のコレクションが返されます。

    • 開いている接続がない場合、.getBoxList() は接続を開きます。
    • 接続が指定された時間 (IMAP New transporter 参照) 以上に使用されなかった場合には、.checkConnection( ) 関数が自動的に呼び出されます。

    例題

     var $transporter : 4D.IMAPTransporter
    $transporter:=IMAP New transporter($server)

    $boxList:=$transporter.getBoxList()

    For each($box;$boxList)
    If($box.interesting)
    $split:=Split string($box.name;$transporter.getDelimiter())
    ALERT("新規メールが届いています: "+$split[$split.length-1])
    End if
    End for each

    .getDelimiter()

    履歴
    リリース内容
    18 R4追加

    .getDelimiter() : Text

    引数説明
    戻り値Text<-階層区切り文字

    説明

    .getDelimiter() 関数は、メールボックス名で階層レベルを区切るのに使用される文字を返します。

    この区切り文字は以下のように使用することができます:

    • 下層レベルのメールボックスを作成する
    • メールボックスの階層内での上層・下層レベルを検索する

    戻り値

    メールボックス名の区切り文字

    • 開いている接続がない場合、.getDelimiter() は接続を開きます。
    • 接続が指定された時間 (IMAP New transporter 参照) 以上に使用されなかった場合には、.checkConnection() 関数が自動的に呼び出されます。

    例題

     var $transporter : 4D.IMAPTransporter
    $transporter:=IMAP New transporter($server)

    $boxList:=$transporter.getBoxList()

    For each($box;$boxList)
    If($box.interesting)
    $split:=Split string($box.name;$transporter.getDelimiter())
    ALERT("新規メールが届いています: "+$split[$split.length-1])
    End if
    End for each

    .getMail()

    履歴
    リリース内容
    18 R4追加

    .getMail( msgNumber: Integer { ; options : Object } ) : Object
    .getMail( msgID: Text { ; options : Object } ) : Object

    引数説明
    msgNumberInteger->メッセージのシーケンス番号
    msgIDText->メッセージの固有ID
    optionsObject->メッセージ管理オプション
    戻り値Object<-Email オブジェクト

    説明

    .getMail() 関数は、 IMAP_transporter が指定するメールボックス内の、msgNumber または msgID に対応するメールを Email オブジェクトとして返します。 この関すを使用すると、メールのコンテンツをローカルで管理できるようになります。

    最初の引数として、次のいずれかを渡すことができます:

    • msgNumber に、取得するメッセージのシーケンス番号 (倍長整数) を渡します。
    • msgIDに、取得するメッセージの固有ID (テキスト) を渡します。

    任意の options 引数として、メッセージの扱い方を定義する追加のオブジェクトを渡すことができます。 次のプロパティを利用することができます:

    プロパティ説明
    updateSeenbooleantrue 時には、メールボックス内でメッセージを "既読" にします。 false 時にはメッセージの状態は変化しません。 デフォルト値: true
    withBodybooleantrue を渡すとメッセージ本文を返します。 false 時には、メッセージヘッダーのみが返されます。 デフォルト値: true
    • msgID 引数が存在しないメッセージを指定した場合、関数はエラーを生成し Null を返します。
    • .selectBox() によって選択されたメールボックスがない場合、エラーが生成されます。
    • 開いている接続がない場合、.getMail().selectBox() で最後に指定されたメールボックスへの接続を開きます。

    戻り値

    .getMail() は、以下の IMAP特有のプロパティを持つ Email オブジェクトを返します: idreceivedAt、および size

    例題

    ID = 1のメッセージを取得します:

     var $server : Object
    var $info; $mail; $boxInfo : Variant
    var $transporter : 4D.IMAPTransporter

    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    // transporter を作成します
    $transporter:=IMAP New transporter($server)

    //メールボックスを選択します
    $boxInfo:=$transporter.selectBox("Inbox")

    // ID = 1 の Emailオブジェクトを取得します
    $mail:=$transporter.getMail(1)

    .getMails()

    履歴
    リリース内容
    18 R5追加

    .getMails( ids : Collection { ; options : Object } ) : Object
    .getMails( startMsg : Integer ; endMsg : Integer { ; options : Object } ) : Object

    引数説明
    idsCollection->メッセージID のコレクション
    startMsgInteger->先頭メッセージのシーケンス番号
    endMsgInteger->最後のメッセージのシーケンス番号
    optionsObject->メッセージ管理オプション
    戻り値Object<-次のコレクションを格納したオブジェクト:
    • Email オブジェクト のコレクション
    • 見つからなかったメッセージの ID または番号のコレクション

    説明

    .getMails() 関数は、Email オブジェクトのコレクションを格納したオブジェクトを返します。

    第一シンタックス:

    .getMails( ids { ; options } ) -> result

    第一シンタックスを使用すると、メッセージID に基づいてメッセージを取得することができます。

    ids 引数として、取得するメッセージID のコレクションを渡します。 これらの ID は .getMail() で取得することができます。

    任意の options 引数を渡すと、返されるメッセージのパートを定義することができます。 利用可能なプロパティについては、以下の オプション の表を参照ください。

    第二シンタックス:

    .getMails( startMsg ; endMsg { ; options } ) -> result

    第二シンタックスを使用すると、連続したレンジに基づいてメッセージを取得することができます。 渡される値はメールボックス内でのメッセージの位置を表します。

    startMsg には、連続したレンジの最初のメッセージの番号に対応する 倍長整数 の値を渡します。 負の値 (startMsg <= 0) を渡した場合、メールボックスの最初のメッセージが連続レンジの先頭メッセージとして扱われます。

    endMsg には、連続レンジに含める最後のメッセージの番号に対応する 倍長整数 の値を渡します。 負の値 (endMsg <= 0) を渡した場合、メールボックスの最後のメッセージが連続レンジの最終メッセージとして扱われます。

    任意の options 引数を渡すと、返されるメッセージのパートを定義することができます。

    Options

    プロパティ説明
    updateSeenBooleantrue 時には、指定されたメッセージを "既読" にします。 false 時にはメッセージの状態は変化しません。 デフォルト値: true
    withBodyBooleantrue を渡すと指定されたメッセージの本文を返します。 false 時には、メッセージヘッダーのみが返されます。 デフォルト値: true
    • .selectBox() によって選択されたメールボックスがない場合、エラーが生成されます。
    • 開いている接続がない場合、.getMails().selectBox() で最後に指定されたメールボックスへの接続を開きます。

    戻り値

    .getMails() は、以下のコレクションを格納したオブジェクトを返します。

    プロパティ説明
    listCollectionEmail オブジェクトのコレクション。 Email オブジェクトが見つからない場合、空のコレクションが返されます。
    notFoundCollection使用したシンタックスによって返されるものが異なります:
    • 第一シンタックス - 指定した ID のうち、存在しなかったメッセージの ID のコレクション
    • 第二シンタックス - startMsg と endMsg の間の番号のうち、存在しなかったメッセージのシーケンス番号のコレクション
    すべてのメッセージが見つかった場合には、空のコレクションが返されます。

    例題

    直近の 20件のメールを、"既読" ステータスを変更せずに取得します:

     var $server,$boxInfo,$result : Object
    var $transporter : 4D.IMAPTransporter

    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    //create transporter
    $transporter:=IMAP New transporter($server)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("INBOX")

    If($boxInfo.mailCount>0)
    // 直近20件のメッセージのヘッダーを、"既読" にせずに取得します
    $result:=$transporter.getMails($boxInfo.mailCount-20;$boxInfo.mailCount;\
    New object("withBody";False;"updateSeen";False))
    For each($mail;$result.list)
    // ...
    End for each
    End if

    .getMIMEAsBlob()

    履歴
    リリース内容
    18 R4追加

    .getMIMEAsBlob( msgNumber : Integer { ; updateSeen : Boolean } ) : Blob
    .getMIMEAsBlob( msgID : Text { ; updateSeen : Boolean } ) : Blob

    引数説明
    msgNumberInteger->メッセージのシーケンス番号
    msgIDText->メッセージの固有ID
    updateSeenBoolean->true 時には、メールボックス内でメッセージを "既読" にします。 false 時にはメッセージの状態は変化しません。
    戻り値BLOB<-メールサーバーから返された MIME文字列の BLOB

    説明

    .getMIMEAsBlob() 関数は、 IMAP_transporter が指定するメールボックス内の、msgNumber または msgID に対応するメッセージの MIMEコンテンツを格納した BLOB を返します。

    最初の引数として、次のいずれかを渡すことができます:

    • msgNumber に、取得するメッセージのシーケンス番号 (倍長整数) を渡します。
    • msgIDに、取得するメッセージの固有ID (テキスト) を渡します。

    任意の updateSeen 引数を渡すと、メールボックス内でメッセージが "既読" とマークされるかどうかを指定します。 以下のものを渡すことができます:

    • True - メッセージは "既読" とマークされます (このメッセージが読まれたことを表します)
    • False - メッセージの "既読" ステータスは変化しません。
    • msgNumber または msgID 引数が存在しないメッセージを指定した場合、関数は空の BLOB を返します。
    • .selectBox() によって選択されたメールボックスがない場合、エラーが生成されます。
    • 開いている接続がない場合、.getMIMEAsBlob().selectBox() で最後に指定されたメールボックスへの接続を開きます。

    戻り値

    .getMIMEAsBlob()BLOB を返します。この BLOB はデータベースにアーカイブしたり、MAIL Convert from MIME コマンドを使用して Email オブジェクト へと変換したりすることができます。

    例題

     var $server : Object
    var $boxInfo : Variant
    var $blob : Blob
    var $transporter : 4D.IMAPTransporter

    $server:=New object
    $server.host:="imap.gmail.com"
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    // transporter を作成します
    $transporter:=IMAP New transporter($server)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("Inbox")

    // BLOB を取得します
    $blob:=$transporter.getMIMEAsBlob(1)

    .host

    履歴
    リリース内容
    17 R5追加

    .host : Text

    説明

    .host プロパティは、ホストサーバーの名前または IPアドレスを格納します。 この情報はメール通信 (SMTP、POP3、IMAP) に使用されます。

    .logFile

    履歴
    リリース内容
    17 R5追加

    .logFile : Text

    説明

    .logFile プロパティは、 メール接続に対して定義された拡張ログファイル (あれば) へのフルパスを格納します。 パスは、カレント Logs フォルダーを基準とした相対パス、あるいは絶対パスを指定できます。

    SET DATABASE PARAMETER コマンドで有効化される通常のログファイルとは異なり、拡張ログファイルはすべての送信されたメールの MIMEコンテンツを保存し、サイズ制限がありません。 拡張ログファイルの詳細については、以下の章をそれぞれ参照ください:

    .move()

    履歴
    リリース内容
    18 R5追加

    .move( msgsIDs : Collection ; destinationBox : Text ) : Object
    .move( allMsgs : Integer ; destinationBox : Text ) : Object

    引数説明
    msgsIDsCollection->メッセージの固有ID のコレクション (テキスト)
    allMsgsInteger->IMAP all: 選択されたメールボックスの全メッセージ
    destinationBoxText->メッセージの移動先のメールボックス
    戻り値Object<-move処理のステータス

    説明

    .move() 関数は、msgsIDs または allMsgs で定義されたメッセージを IMAP サーバーの destinationBox へと移動します。

    以下のものを渡すことができます:

    • msgsIDs には、移動するメッセージの固有ID を格納したコレクション
    • allMsgs には、選択されているメールボックスの全メッセージを移動するための定数 (倍長整数型):

    destinationBox には、メッセージの移動先メールボックスの名称をテキスト値で渡すことができます。

    RFC 8474 に準拠している IMAPサーバーでのみ、この関数はサポートされます。

    返されるオブジェクト

    この関数は、IMAP ステータスを表すオブジェクトを返します:

    プロパティ説明
    successBoolean処理が正常に終わった場合には true、それ以外は false
    statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
    errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
    [].errcodeNumber4Dエラーコード
    [].messageText4Dエラーの詳細
    [].componentSignatureTextエラーを返した内部コンポーネントの署名

    例題 1

    選択されたメッセージを移動します:

     var $server;$boxInfo;$status : Object
    var $mailIds : Collection
    var $transporter : 4D.IMAPTransporter

    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    $transporter:=IMAP New transporter($server)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("inbox")

    // メッセージの固有IDのコレクションを取得します
    $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")

    // カレントメールボックス内で見つかったメッセージを "documents" メールボックスに移動します
    $status:=$transporter.move($mailIds;"documents")

    例題 2

    カレントメールボックスの全メッセージを移動します:

     var $server;$boxInfo;$status : Object
    var $transporter : 4D.IMAPTransporter

    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    $transporter:=IMAP New transporter($server)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("inbox")

    // カレントメールボックスの全メッセージを "documents" メールボックスに移動します
    $status:=$transporter.move(IMAP all;"documents")

    .numToID()

    履歴
    リリース内容
    18 R5追加

    .numToID( startMsg : Integer ; endMsg : Integer ) : Collection

    引数説明
    startMsgInteger->先頭メッセージのシーケンス番号
    endMsgInteger->最後のメッセージのシーケンス番号
    戻り値Collection<-固有ID のコレクション

    説明

    .numToID() 関数は、現在選択されているメールボックスにおいて、startMsg および endMsg で指定された連続した範囲のメッセージのシーケンス番号を IMAP固有IDへと変換します。

    startMsg には、連続したレンジの最初のメッセージの番号に対応する 倍長整数 の値を渡します。 負の値 (startMsg <= 0) を渡した場合、メールボックスの最初のメッセージが連続レンジの先頭メッセージとして扱われます。

    endMsg には、連続レンジに含める最後のメッセージの番号に対応する 倍長整数 の値を渡します。 負の値 (endMsg <= 0) を渡した場合、メールボックスの最後のメッセージが連続レンジの最終メッセージとして扱われます。

    戻り値

    メソッドは文字列 (固有ID) のコレクションを返します。

    例題

     var $transporter : 4D.IMAPTransporter
    var $server;$boxInfo;$status : Object
    var $mailIds : Collection

    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.port:=993
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    $transporter:=IMAP New transporter($server)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("inbox")

    // 最も古い 5通のメッセージID を取得します
    $mailIds:=$transporter.numToID(($boxInfo.mailCount-5);$boxInfo.mailCount)

    // カレントメールボックスからメッセージを削除します
    $status:=$transporter.delete($mailIds)

    .removeFlags()

    履歴
    リリース内容
    20カスタムキーワードをサポート
    18 R6追加

    .removeFlags( msgIDs : Collection ; keywords : Object ) : Object
    .removeFlags( msgIDs : Text ; keywords : Object ) : Object
    .removeFlags( msgIDs : Longint ; keywords : Object ) : Object

    引数説明
    msgIDsCollection->文字列のコレクション: メッセージの固有ID (テキスト型)
    テキスト: メッセージの固有ID
    倍長整数 (IMAP all): 選択されたメールボックス内の全メッセージ
    keywordsObject->削除するキーワードフラグ
    戻り値Object<-removeFlags処理のステータス

    説明

    .removeFlags() 関数は、msgIDs のメッセージに対して、keywords で指定したフラグを削除します。

    msgIDs には、以下のいずれかを渡すことができます:

    • 指定するメッセージの固有ID を格納した コレクション
    • 単一のメッセージの固有ID (テキスト)
    • 以下の定数 (longint) を使用することで、選択されているメールボックスの全メッセージを指定することができます:
    定数説明
    IMAP all1選択されたメールボックスの全メッセージを選択します

    keywords を使って、msgIDs 引数で指定したメッセージから削除するフラグを定義します。 以下の標準フラグおよびカスタムフラグを使用することができます:

    引数説明
    $draftBooleanメッセージの "draft" フラグを削除するには true
    $seenBooleanメッセージの "seen" フラグを削除するには true
    $flaggedBooleanメッセージの "flagged" フラグを削除するには true
    $answeredBooleanメッセージの "answered" フラグを削除するには true
    $deletedBooleanメッセージの "deleted" フラグを削除するには true
    <custom flag>Booleanメッセージのカスタムフラグを削除するには true

    カスタムフラグの詳細については、.addFlags() を参照ください。

    • キーワードが考慮されるためには、その値が true でなければなりません。

    返されるオブジェクト

    この関数は、IMAP ステータスを表すオブジェクトを返します:

    プロパティ説明
    successBoolean処理が正常に終わった場合には true、それ以外は false
    statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
    errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
    [].errcodeNumber4Dエラーコード
    [].messageText4Dエラーの詳細
    [].componentSignatureTextエラーを返した内部コンポーネントの署名

    例題

    var $options;$transporter;$boxInfo;$status : Object

    $options:=New object
    $options.host:="imap.gmail.com"
    $options.port:=993
    $options.user:="4d@gmail.com"
    $options.password:="xxxxx"

    // transporter を作成します
    $transporter:=IMAP New transporter($options)

    // メールボックスを選択します
    $boxInfo:=$transporter.selectBox("INBOX")

    // INBOX の全メッセージを未読にします
    $flags:=New object
    $flags["$seen"]:=True
    $status:=$transporter.removeFlags(IMAP all;$flags)

    .renameBox()

    履歴
    リリース内容
    19追加

    .renameBox( currentName : Text ; newName : Text ) : Object

    引数説明
    currentNameText->カレントメールボックスの名称
    newNameText->新しいメールボックス名
    戻り値Object<-renameBox処理のステータス

    説明

    .renameBox() 関数は、IMAPサーバー上でメールボックスの名称を変更します。 存在しないメールボックスの名称を変更しようとしたり、すでに使われているメールボックス名に変更しようとしたりすると、エラーが生成されます。

    currentName には、名称変更するメールボックスの名前を渡します。

    メールボックスの新しい名称は newName に渡します。

    返されるオブジェクト

    この関数は、IMAP ステータスを表すオブジェクトを返します:

    プロパティ説明
    successBoolean処理が正常に終わった場合には true、それ以外は false
    statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
    errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
    [].errcodeNumber4Dエラーコード
    [].messageText4Dエラーの詳細
    [].componentSignatureTextエラーを返した内部コンポーネントの署名

    例題

    “Invoices” メールボックスを “Bills” に名称変更します:

    var $pw : text
    var $options; $transporter; $status : object

    $options:=New object

    $pw:=Request("パスワードを入力してください:")

    If(OK=1) $options.host:="imap.gmail.com"

    $options.user:="test@gmail.com"
    $options.password:=$pw

    $transporter:=IMAP New transporter($options)

    // メールボックスの名称変更
    $status:=$transporter.renameBox("Invoices"; "Bills")

    If ($status.success)
    ALERT("メールボックスの名称が変更されました。")
    Else
    ALERT("エラー: "+$status.statusText)
    End if
    End if

    .port

    履歴
    リリース内容
    17 R4追加

    .port : Integer

    説明

    .port プロパティは、 メール通信に使用されるポート番号を格納します。 SMTP New transporterPOP3 New transporterIMAP New transporter のコマンドで transporter オブジェクトを作成する際に使用される server オブジェクトにおいて、 このプロパティが指定されなかった場合に使用されるポートは次のとおりです:

    • SMTP - 587
    • POP3 - 995
    • IMAP - 993

    .searchMails()

    履歴
    リリース内容
    18 R5追加

    .searchMails( searchCriteria : Text ) : Collection

    引数説明
    searchCriteriaText->検索条件
    戻り値Collection<-メッセージ番号のコレクション

    説明

    この関数は、IMAP プロトコル の仕様に基づいています。

    .searchMails() 関数は、カレントメールボックスにおいて searchCriteria の検索条件に合致するメッセージを検索します。 searchCriteria 引数には、一つ以上の検索キーを格納します。

    searchCriteria はテキスト型の引数で、一つ以上の検索キー (詳細は後述の 利用可能な検索キー 参照) を格納し、検索する値を渡します (渡さない場合もあります)。 検索キーは単一または複数の項目からなります。 例:

    SearchKey1 = FLAGGED
    SearchKey2 = NOT FLAGGED
    SearchKey3 = FLAGGED DRAFT

    文字の大小は通常区別されません。

    • searchCriteria 引数が null 文字列の場合、検索は "すべてを選択" と同等です。
    • 引数が複数の検索キーを格納している場合、それらすべてに合致する和集合 (AND) が検索結果になります。
    searchCriteria = FLAGGED FROM "SMITH"

    ... この検索結果は \Flagged フラグが設定されていて、かつ Smith から送られたメッセージをすべて返します。

    • OR および NOT 演算子を、以下のように使用することができます:
    searchCriteria = OR SEEN FLAGGED

    ... \Seen フラグが設定されている、あるいは \Flagged フラグが設定されているメッセージをすべて返します。

    searchCriteria = NOT SEEN

    ... \Seen フラグが設定されていないメッセージをすべて返します。

    searchCriteria = HEADER CONTENT-TYPE "MIXED" NOT HEADER CONTENT-TYPE "TEXT"...

    ... content-type ヘッダーが "Mixed" を格納しているもののうち、"Text" は格納していないメッセージを返します。

    searchCriteria = HEADER CONTENT-TYPE "E" NOT SUBJECT "o" NOT HEADER CONTENT-TYPE "MIXED"

    ... content-type ヘッダーが "e" を格納しているもののうち、Subject ヘッダーが "o" を格納していないもの、かつ content-type ヘッダーが "Mixed" でないメッセージを返します。

    最後の 2例については、最初の検索キーリストのカッコを取り除いてしまうと検索結果が異なることに注意してください。

    • searchCriteria 引数には任意の [CHARSET] 指定を含めることができます。 これは "CHARSET" という単語の後に実際の文字コード [CHARSET] (US ASCII, ISO-8859 など) が続きます。 これは searchCriteria 文字列の文字コードを指定します。 そのため、[CHARSET] 指定を使用する場合には searchCriteria 文字列を指定された文字コードへと変換する必要があります (詳細については CONVERT FROM TEXT または Convert to text コマンドを参照ください)。 デフォルトでは、searchCriteria 引数に拡張された文字列が含まれていた場合には4D はそれを Quotable Printable へとエンコードします。
    searchCriteria = CHARSET "ISO-8859" BODY "Help"

    ... これは、検索条件に iso-8859 文字コードを使用し、必要に応じてサーバーは検索前に検索条件をこの文字コードに変換しなければならない、ということを意味します。

    検索する値の型について

    検索キーによっては、次の型の検索値が必要となる場合があります:

    • 日付値の検索キー: date は日付を指定する文字列で、以下のようにフォーマットされている必要があります: date-day+"-"+date-month+"-"+date-year。ここでの date-day は日付の数値 (最大2桁) を意味し、date-month は月の名前 (Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Dec) を意味し、date-year は年 (4桁) を意味します。 例: searchCriteria = SENTBEFORE 1-Feb-2000 (日付は特殊文字を含まないため、通常は引用符でくくる必要はありません)

    • 文字列値の検索キー: string はあらゆる文字列を含みうるため、引用符でくくらなければなりません。 文字列が特殊文字 (スペース文字など) をまったく含まない場合には、引用符で括る必要はありません。 このような文字列を引用符でくくることは、渡した文字列値が正確に解釈されることを保証します。 例: searchCriteria = FROM "SMITH"
      文字列を使用するすべての検索キーに対し、フィールドの文字列に検索キーが含まれる場合には検索に合致したとみなされます。 合致は文字の大小を区別しません。

    • field-name 値の検索キー: field-name はヘッダーフィールドの名称です。 例: searchCriteria = HEADER CONTENT-TYPE "MIXED"

    • フラグ値の検索キー: flag は一つ以上のキーワードを (標準のフラグを含めて) 受け入れます。複数指定する場合にはスペースで区切ります。 例: searchCriteria = KEYWORD \Flagged \Draft

    • メッセージセット値の検索キー: 複数のメッセージを識別します。 メッセージシーケンス番号は、1 から始まりメールボックスのメッセージの総数までの連続した番号です。 個別の番号はカンマで区切ります。コロンは、その前後の番号を含めた連続した番号を指定します。 例:
      2,4:7,9,12:* は、15通あるメールボックスの場合に 2,4,5,6,7,9,12,13,14,15 を指定します。 searchCriteria = 1:5 ANSWERED は、メッセージシーケンス番号 1 から 5番のメッセージのうち、\Answered フラグが設定されているメッセージを検索します。 searchCriteria= 2,4 ANSWERED は、メッセージセレクション (メッセージ番号 2番と4番) のうち、\Answered フラグが設定されているメッセージを検索します。

    利用可能な検索キー

    ALL: メールボックスの全メッセージ
    ANSWERED: \Answered フラグが設定されたメッセージ
    UNANSWERED: \Answered フラグが設定されていないメッセージ
    DELETED: \Deleted フラグが設定されたメッセージ
    UNDELETED: \Deleted フラグが設定されていないメッセージ
    DRAFT: \Draft フラグが設定されているメッセージ
    UNDRAFT: \Draft フラグが設定されていないメッセージ
    FLAGGED: \Flagged フラグが設定されているメッセージ
    UNFLAGGED: \Flagged フラグが設定されていないメッセージ
    RECENT: \Recent フラグが設定されているメッセージ
    OLD: \Recent フラグが設定されていないメッセージ
    SEEN: \Seen フラグが設定されているメッセージ
    UNSEEN: \Seen フラグが設定されていないメッセージ
    NEW: \Recent フラグが設定されているが \Seen フラグが設定されていないメッセージ。 これは機能的には “(RECENT UNSEEN)” と同じです。
    KEYWORD flag**: 指定されたキーワードが設定されているメッセージ
    UNKEYWORD flag**: 指定されたキーワードが設定されていないメッセージ
    BEFORE date**: 内部の日付が指定日より前のメッセージ
    ON date**: 内部の日付が指定日に合致するメッセージ
    SINCE date**: 内部の日付が指定日より後のメッセージ
    SENTBEFORE date**: 日付ヘッダーが指定日より前のメッセージ
    SENTON date**: 日付ヘッダーが指定日に合致するメッセージ
    SENTSINCE date**: 日付ヘッダーが指定日以降のメッセージ
    TO string**: TO ヘッダーに指定文字列が含まれているメッセージ
    FROM string**: FROM ヘッダーに指定文字列が含まれているメッセージ
    CC string**: CC ヘッダーに指定文字列が含まれているメッセージ
    BCC string**: BCC ヘッダーに指定文字列が含まれているメッセージ
    SUBJECT string**: 件名ヘッダーに指定文字列が含まれているメッセージ
    BODY string**: メッセージ本文に指定文字列が含まれているメッセージ
    TEXT string**: ヘッダーまたはメッセージ本文に指定文字列が含まれているメッセージ
    HEADER field-name string: 指定フィールド名のヘッダーを持ち、そのフィールド内に指定文字列が含まれているメッセージ
    UID message-UID: 指定された固有識別子に対応する固有識別子を持つメッセージ
    LARGER n: 指定バイト数以上のサイズを持つメッセージ
    SMALLER n: 指定バイト数以下のサイズを持つメッセージ
    NOT search-key: 指定検索キーに合致しないメッセージ
    OR search-key1 search-key2: いずれかの検索キーに合致するメッセージ

    .selectBox()

    履歴
    リリース内容
    20id, flags, permanentFlags が返されます。
    18 R4追加

    .selectBox( name : Text { ; state : Integer } ) : Object

    引数説明
    nameText->メールボックスの名称
    stateInteger->メールボックスのアクセス状態
    戻り値Object<-boxInfo オブジェクト

    説明

    .selectBox() 関数は、 name に指定したメールボックスをカレントメールボックスとして選択します。 この関数を使用するとメールボックスに関する情報を取得することができます。

    カレントメールボックスを変更せずに、メールボックスから情報を取得するには、.getBoxInfo() を使用します。

    name には、アクセスするメールボックスの名前を渡します。 この名称は明確な左から右への階層を表し、特定の区切り文字でレベルを区分けします。 この区切り文字は .getDelimiter() 関数で調べることができます。

    任意の state 引数を渡すと、メールボックスへのアクセスタイプを定義できます。 取りうる値は以下の通りです:

    定数説明
    IMAP read only state1選択されたメールボックスは読み取り専用権限でアクセスされます。 新しいメッセージを表す "新着" フラグはそのまま変化しません。
    IMAP read write state0選択されたメールボックスは読み書き可能権限でアクセスされます。 メッセージは "既読" と判断され、"新着" フラグは失われます。 (デフォルト値)
    • name 引数が存在しないメールボックスを指定した場合、関数はエラーを生成し Null を返します。
    • 開いている接続がない場合、.selectBox() は接続を開きます。
    • 接続が指定された時間 (IMAP New transporter 参照) 以上に使用されなかった場合には、.checkConnection() 関数が自動的に呼び出されます。

    返されるオブジェクト

    返される boxInfo オブジェクトには、以下のプロパティが格納されています:

    プロパティ説明
    nameTextメールボックスの名称
    mailCountnumberメールボックス内のメッセージの数
    mailRecentnumber"recent" フラグがついたメッセージの数
    idtextメールボックスの固有ID
    flagstextメールボックスで現在使用されているフラグのリスト (スペース区切り)。
    permanentFlagstextクライアントが永続的に変更可能なフラグ (IMAPサーバーが管理する \Recent フラグを除く) の、スペース区切りのリスト。
    info

    permanentFlags の文字列に特別なフラグ * が含まれている場合、それは、サーバーが カスタムフラグ をサポートしていることを意味します。

    例題

     var $server; $boxinfo : Object
    $server:=New object
    $server.host:="imap.gmail.com" // 必須
    $server.user:="4d@gmail.com"
    $server.password:="XXXXXXXX"

    var $transporter : 4D.IMAPTransporter
    $transporter:=IMAP New transporter($server)
    $boxInfo:=$transporter.selectBox("INBOX")

    .subscribe()

    履歴
    リリース内容
    19追加

    .subscribe( name : Text ) : Object

    引数説明
    nameText->メールボックスの名称
    戻り値Object<-subscribe処理のステータス

    説明

    .subscribe() 関数は、IMAPサーバーの購読メールボックスとして任意のメールボックスを追加します。 利用可能なメールボックスが大量にある場合、すべてを取得するのを避けるため、確認したいメールボックスだけを購読することができます。

    name には、購読するメールボックスの名前を渡します。

    返されるオブジェクト

    この関数は、IMAP ステータスを表すオブジェクトを返します:

    プロパティ説明
    successBoolean処理が正常に終わった場合には true、それ以外は false
    statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
    errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
    [].errcodeNumber4Dエラーコード
    [].messageText4Dエラーの詳細
    [].componentSignatureTextエラーを返した内部コンポーネントの署名

    例題

    "Bills" 階層下の "Atlas Corp” メールボックスを購読します:

    var $pw; $name : text
    var $options; $transporter; $status : object

    $options:=New object

    $pw:=Request("パスワードを入力してください:")

    If(OK=1) $options.host:="imap.gmail.com"
    $options.user:="test@gmail.com"
    $options.password:=$pw

    $transporter:=IMAP New transporter($options)

    $name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
    $status:=$transporter.subscribe($name)

    If ($status.success)
    ALERT("メールボックスの購読に成功しました。")
    Else
    ALERT("エラー: "+$status.statusText)
    End if
    End if

    .unsubscribe()

    履歴
    リリース内容
    19追加

    .unsubscribe( name : Text ) : Object

    引数説明
    nameText->メールボックスの名称
    戻り値Object<-unsubscribe処理のステータス

    説明

    .unsubscribe() 関数は、指定したメールボックスを購読メールボックスから削除します。 これにより、確認するメールボックスの数を減らせます。

    name には、購読を解除するメールボックスの名前を渡します。

    返されるオブジェクト

    この関数は、IMAP ステータスを表すオブジェクトを返します:

    プロパティ説明
    successBoolean処理が正常に終わった場合には true、それ以外は false
    statusTextTextIMAPサーバーから返されたステータスメッセージ、または 4Dエラースタック内に返された最後のエラー
    errorsCollection4Dエラースタック (IMAPサーバーレスポンスが受信できた場合には返されません)
    [].errcodeNumber4Dエラーコード
    [].messageText4Dエラーの詳細
    [].componentSignatureTextエラーを返した内部コンポーネントの署名

    例題

    "Bills" 階層下の "Atlas Corp” メールボックスの購読を解除します:

    var $pw; $name : text
    var $options; $transporter; $status : object

    $options:=New object

    $pw:=Request("パスワードを入力してください:")

    If(OK=1) $options.host:="imap.gmail.com"
    $options.user:="test@gmail.com"
    $options.password:=$pw

    $transporter:=IMAP New transporter($options)

    $name:="Bills"+$transporter.getDelimiter()+"Atlas Corp"
    $status:=$transporter.unsubscribe($name)

    If ($status.success)
    ALERT("メールボックスの購読を解除しました。")
    Else
    ALERT("エラー: "+$status.statusText)
    End if
    End if

    .user

    履歴
    リリース内容
    17 R4追加

    .user : Text

    説明

    .user プロパティは、メールサーバーでの認証に使用されたユーザー名を格納します。