LPMAPIFINDNEXT

コールバック

シグネチャ

DWORD LPMAPIFINDNEXT(
    UINT_PTR lhSession,
    UINT_PTR ulUIParam,
    LPSTR lpszMessageType,
    LPSTR lpszSeedMessageID,
    DWORD flFlags,
    DWORD ulReserved,
    LPSTR lpszMessageID
);

パラメーター

フィールド

型

説明

lhSession

UINT_PTR

Simple MAPI セッションを表すセッションハンドル。lhSession パラメーターの値は有効なセッションを表している必要があり、0 にすることはできません。

ulUIParam

UINT_PTR

親ウィンドウのハンドル、または 0。0 の場合、ダイアログボックスが表示されるときはアプリケーションモーダルになります。ulUIParam パラメーターに親ウィンドウのハンドルが格納されている場合、その型は HWND (ULONG_PTR にキャストしたもの) です。呼び出し中にダイアログボックスが表示されない場合、ulUIParam は無視されます。

lpszMessageType

LPSTR

検索するメッセージクラスを示す文字列へのポインター。個人間メッセージ (IPM) を検索するには、lpszMessageType パラメーターに NULL を指定するか、空の文字列を指すようにします。サポートするメッセージクラスが IPM のみであるメッセージングシステムは、このパラメーターを無視できます。

lpszSeedMessageID

LPSTR

要求のシードとなるメッセージ識別子を格納した文字列へのポインター。lpszSeedMessageID パラメーターが NULL であるか空の文字列を指している場合、MAPIFindNext は lpszMessageType パラメーターで指定された種類に一致する最初のメッセージを取得します。

flFlags

DWORD

オプションフラグのビットマスク。次のフラグを設定できます。

値	意味
MAPI_GUARANTEE_FIFO	返されるメッセージ識別子を受信時刻順にします。このフラグを設定すると、MAPIFindNext の呼び出しに時間がかかることがあります。実装によってはこの要求に対応できず、MAPI_E_NO_SUPPORT 値を返します。
MAPI_LONG_MSGID	返されるメッセージ識別子は最大 512 文字になることがあります。このフラグを設定する場合、lpszMessageID パラメーターは 512 文字を格納できる大きさである必要があります。以前のバージョンの MAPI は、より短いメッセージ識別子 (64 バイト) をサポートしており、このフラグはありませんでした。lpszMessageID がメッセージ識別子を格納できる大きさであれば、このフラグを設定しなくても MAPIFindNext は成功します。lpszMessageID がメッセージ識別子を格納できない場合、MAPIFindNext は失敗します。
MAPI_UNREAD_ONLY	指定した種類の未読メッセージのみを列挙します。このフラグを設定しない場合、MAPIFindNext は指定した種類の任意のメッセージを返すことがあります。

ulReserved

DWORD

予約済み。0 を指定する必要があります。

lpszMessageID

LPSTR

返されるメッセージ識別子へのポインター。メモリの割り当ては呼び出し元の責任です。互換性を確保するには、512 文字分を割り当て、flFlags パラメーターに MAPI_LONG_MSGID を設定します。これより小さいバッファーで十分なのは、返されるメッセージ識別子が常に 64 文字以下である場合のみです。

公式ドキュメント

[この関数の使用は推奨されません。今後のバージョンの Windows では、変更されたり利用できなくなったりする可能性があります。]

MAPIFindNext 関数は、指定した種類の受信メッセージについて、次の (または最初の) メッセージ識別子を取得します。

戻り値

この関数は、次のいずれかの値を返します。

戻り値	説明
MAPI_E_FAILURE	メッセージの種類を照合する際に、1 つ以上の不特定のエラーが発生しました。メッセージの種類の照合が行われる前に呼び出しが失敗しました。
MAPI_E_INSUFFICIENT_MEMORY	処理を続行するためのメモリが不足していました。メッセージは見つかりませんでした。
MAPI_E_INVALID_MESSAGE	lpszSeedMessageID パラメーターに無効なメッセージ識別子が渡されました。メッセージは見つかりませんでした。
MAPI_E_INVALID_SESSION	lhSession パラメーターに無効なセッションハンドルが渡されました。メッセージは見つかりませんでした。
MAPI_E_NO_MESSAGES	一致するメッセージが見つかりませんでした。
SUCCESS_SUCCESS	呼び出しが成功し、メッセージ識別子が返されました。

解説(Remarks)

MAPIFindNext 関数を使用すると、クライアントアプリケーションは指定した種類のメッセージを列挙できます。この関数を繰り返し呼び出すことで、フォルダー内のすべてのメッセージを列挙できます。MAPIFindNext から返されたメッセージ識別子は、メッセージの内容の取得やメッセージの削除など、他の Simple MAPI の呼び出しで使用できます。この関数は受信メッセージを処理するためのものであり、受信済みメッセージを管理するためのものではありません。

MAPIFindNext は、指定した種類の新着メッセージが配信されるフォルダー内でメッセージを検索します。MAPIFindNext の呼び出しは、MAPILogon 関数で確立した有効な Simple MAPI セッションのコンテキストでのみ行えます。

lpszSeedMessageID パラメーターが NULL であるか空の文字列を指している場合、MAPIFindNext は lpszMessageType パラメーターで指定された種類の最初のメッセージの識別子を返します。lpszSeedMessageID に有効な識別子が格納されている場合、この関数は lpszMessageType で指定された種類の次の一致するメッセージを返します。MAPIFindNext を繰り返し呼び出すと、最終的に MAPI_E_NO_MESSAGES 値が返され、列挙が完了したことを示します。

メッセージの種類の照合は、メッセージクラスの文字列に対して行われます。(lpszMessageType で指定された長さまでの範囲で) 名前が一致するすべてのメッセージの種類が返されます。

メッセージ識別子はメッセージングシステムに固有であり、いつでも無効になる可能性があるため、現在のセッションでのみ有効です。lpszSeedMessageID に渡されたメッセージ識別子が無効な場合、MAPIFindNext は MAPI_E_INVALID_MESSAGE 値を返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)