LPMAPIADDRESS

コールバック

シグネチャ

DWORD LPMAPIADDRESS(
    UINT_PTR lhSession,
    UINT_PTR ulUIParam,
    LPSTR lpszCaption,
    DWORD nEditFields,
    LPSTR lpszLabels,
    DWORD nRecips,
    MapiRecipDesc* lpRecips,
    DWORD flFlags,
    DWORD ulReserved,
    DWORD* lpnNewRecips,
    MapiRecipDesc** lppNewRecips
);

パラメーター

フィールド

型

説明

lhSession

UINT_PTR

Simple MAPI セッションを表すセッションハンドル、または 0。lhSession パラメーターの値が 0 の場合、MAPI はユーザーをログオンさせ、この呼び出しの間だけ存在するセッションを作成します。この一時的なセッションは、既存の共有セッションである場合も、新しいセッションである場合もあります。必要に応じて、ログオンダイアログボックスが表示されます。

ulUIParam

UINT_PTR

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

lpszCaption

LPSTR

アドレス一覧ダイアログボックスのキャプションへのポインター、NULL、または空の文字列。lpszCaption パラメーターが NULL であるか空の文字列を指している場合、MAPIAddress は既定のキャプション "Address Book" を使用します。

nEditFields

DWORD

アドレス一覧に表示する編集コントロールの数。0 から 4 までの値が有効です。nEditFields パラメーターの値が 4 の場合、基になるメッセージングシステムがサポートする受信者クラスごとに編集コントロールが 1 つ用意されます。nEditFields の値が 0 の場合は、アドレス一覧の参照のみが可能です。1、2、3 の値は、表示される編集コントロールの数を制御します。ただし、lpRecips パラメーターが指す配列内の受信者クラスの数が nEditFields の値より多い場合は、nEditFields の値ではなく lpRecips 内のクラス数が編集コントロールの数として使用されます。nEditFields の値が 1 で、lpRecips に複数の種類のエントリが存在する場合、lpszLabels パラメーターは無視されます。異なるコントロールに対して選択されたエントリは、返される受信者構造体の ulRecipClass メンバーによって区別されます。

lpszLabels

LPSTR

アドレス一覧ダイアログボックスで編集コントロールのラベルとして使用する文字列へのポインター。nEditFields パラメーターに 1 以外の値が設定されている場合、lpszLabels パラメーターは無視されるため、NULL にするか空の文字列を指す必要があります。また、呼び出し元が既定のコントロールラベル "To" を必要とする場合も、lpszLabels は NULL にするか空の文字列を指す必要があります。

nRecips

DWORD

lpRecips パラメーターが示す配列内のエントリの数。nRecips パラメーターの値が 0 の場合、lpRecips は無視されます。

lpRecips

MapiRecipDesc*

アドレス一覧ダイアログボックスに初期表示する受信者エントリを定義する MapiRecipDesc 構造体の配列へのポインター。エントリを受信者クラスごとにグループ化する必要はありません。エントリは、配列内の MapiRecipDesc 構造体の ulRecipClass メンバーの値によって区別されます。異なる受信者クラスの数が nEditFields パラメーターで示される値より多い場合、nEditFields パラメーターと lpszLabels パラメーターは無視されます。

flFlags

DWORD

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

値	意味
MAPI_LOGON_UI	必要に応じて、ユーザーにログオンを求めるダイアログボックスを表示します。MAPI_LOGON_UI フラグが設定されていない場合、クライアントアプリケーションはログオンダイアログボックスを表示せず、ユーザーがログオンしていないときはエラー値を返します。
MAPI_NEW_SESSION	環境の共有セッションを取得するのではなく、新しいセッションの作成を試みます。MAPI_NEW_SESSION フラグが設定されていない場合、MAPIAddress は既存の共有セッションを使用します。

ulReserved

DWORD

予約済みです。0 にする必要があります。

lpnNewRecips

DWORD*

lppNewRecips 受信者出力配列内のエントリ数へのポインター。lpnNewRecips パラメーターの値が 0 の場合、lppNewRecips パラメーターは無視されます。

lppNewRecips

MapiRecipDesc**

公式ドキュメント

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

MAPIAddress 関数は、アドレス一覧のエントリのセットを作成または変更します。

戻り値

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

戻り値	説明
MAPI_E_FAILURE	メッセージのアドレス指定中に、1 つ以上の原因不明のエラーが発生しました。受信者エントリの一覧は返されませんでした。
MAPI_E_INSUFFICIENT_MEMORY	処理を続行するためのメモリが不足していました。受信者エントリの一覧は返されませんでした。
MAPI_E_INVALID_EDITFIELDS	nEditFields パラメーターの値が 0 から 4 の範囲外でした。受信者エントリの一覧は返されませんでした。
MAPI_E_INVALID_RECIPS	アドレス一覧内の 1 つ以上の受信者が無効でした。受信者エントリの一覧は返されませんでした。
MAPI_E_INVALID_SESSION	lhSession パラメーターに無効なセッションハンドルが使用されました。受信者エントリの一覧は返されませんでした。
MAPI_E_LOGIN_FAILURE	既定のログオンが存在せず、ログオンダイアログボックスが表示されたときにユーザーがログオンに成功しませんでした。受信者エントリの一覧は返されませんでした。
MAPI_E_NOT_SUPPORTED	この操作は、基になるメッセージングシステムでサポートされていませんでした。
MAPI_E_USER_ABORT	ユーザーがいずれかのダイアログボックスをキャンセルしました。受信者エントリの一覧は返されませんでした。
SUCCESS_SUCCESS	呼び出しは成功し、受信者エントリの一覧が返されました。

解説(Remarks)

MAPIAddress 関数は、標準のアドレス一覧ダイアログボックスを表示し、0 個以上の受信者からなる初期セットを示します。ユーザーは、このセットに追加する新しいエントリを選択したり、既存のエントリを変更したりできます。このダイアログボックスを抑制することはできませんが、呼び出し元はダイアログボックスの特性を設定できます。変更後の受信者のセットが呼び出し元に返されます。

MAPIAddress は、新規または変更された受信者情報を書き込む前に、その情報を格納する構造体配列用のメモリを割り当てる必要があります。また、新規または変更された受信者データが書き込まれるかどうかにかかわらず、アドレス帳の事前読み込みの一環としてもメモリが割り当てられます。クライアントアプリケーションは、MAPIAddress から制御が戻った後に MAPIFreeBuffer 関数を呼び出して、このメモリを解放する必要があります。エラーが発生した場合はメモリが割り当てられていないため、クライアントが MAPIFreeBuffer を呼び出す必要はありません。

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