Win32 API 日本語リファレンス
ホームSystem.AddressBook › IAddrBook

IAddrBook

COM
継承元IMAPIProp自前メソッド開始 vtbl14

公式ドキュメント

使用しないでください。(IAddrBook)

メソッド 18

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 14 HRESULT OpenEntry(DWORD cbEntryID, ENTRYID* lpEntryID, GUID* lpInterface, DWORD ulFlags, DWORD* lpulObjType, IUnknown** lppUnk)
cbEntryIDDWORDinlpEntryID が指すエントリ ID のバイト数を指定する。
lpEntryIDENTRYID*inout開くオブジェクトを識別するエントリ ID へのポインタである。NULL を渡すとアドレス帳のルートコンテナを開く。
lpInterfaceGUID*inout返されるオブジェクトに対して要求するインターフェイスの IID へのポインタである。NULL の場合は既定のインターフェイスを返す。
ulFlagsDWORDinオープン動作を制御するフラグを指定する。
lpulObjTypeDWORD*inout開かれたオブジェクトの種類 (MAPI_FOLDER、MAPI_MESSAGE 等) を受け取る変数へのポインタである。
lppUnkIUnknown**out開かれたオブジェクトへのインターフェイスポインタを受け取る変数へのポインタである。
vtbl 15 HRESULT CompareEntryIDs(DWORD cbEntryID1, ENTRYID* lpEntryID1, DWORD cbEntryID2, ENTRYID* lpEntryID2, DWORD ulFlags, DWORD* lpulResult)

2つのエントリ識別子を比較します。

cbEntryID1DWORDinlpEntryID1 パラメーターが指すエントリ識別子のバイト数を指定する ULONG 型の値。
lpEntryID1ENTRYID*inout比較する最初のエントリ識別子を指定する ENTRYID 型の変数へのポインター。
cbEntryID2DWORDinlpEntryID2 パラメーターが指すエントリ識別子のバイト数を指定する ULONG 型の値。
lpEntryID2ENTRYID*inout比較する最初のエントリ識別子を指定する ENTRYID 型の変数へのポインター。
ulFlagsDWORDin予約済み。0 に設定する必要があります。
lpulResultDWORD*inout比較結果を受け取る ULONG 型の変数へのポインター。2つのエントリ識別子が同じオブジェクトを参照している場合、lpulResult の内容は TRUE に設定され、そうでない場合は FALSE に設定されます。

戻り値

HRESULT

vtbl 16 HRESULT Advise(DWORD cbEntryID, ENTRYID* lpEntryID, DWORD ulEventMask, IMAPIAdviseSink* lpAdviseSink, DWORD* lpulConnection)

通知を受け取るために、呼び出し元を Windows アドレス帳 (WAB) に登録します。

cbEntryIDDWORDin予約済み。0 に設定する必要があります。
lpEntryIDENTRYID*inout予約済み。NULL に設定する必要があります。
ulEventMaskDWORDinイベントマスクを指定する ULONG 型の値。fnevObjectModified に設定します。その他のイベントマスクはすべて拒否されます。
lpAdviseSinkIMAPIAdviseSink*in通知を送信するために Windows アドレス帳 (WAB) が呼び出すオブジェクトを指定する IUnknown インターフェイスへのポインター。
lpulConnectionDWORD*inoutWindows アドレス帳 (WAB) が返す接続番号を受け取る ULONG 型の変数へのポインター。IAddrBook::Unadvise を呼び出すときにこの番号を使用します。

戻り値

HRESULT

解説(Remarks)

現時点では、Windows アドレス帳 (WAB) はストア内の全般的な変更に対する通知のみを提供します。クライアントは、エントリ識別子ごとに提供される通知を登録することはできません。Windows アドレス帳 (WAB) ストアが変更されると、Windows アドレス帳 (WAB) はこの関数に渡された lpAdviseSink ポインターに対して IMAPIAdviseSink::OnNotify メソッドを呼び出します。

**OnNotify メソッドに渡される NOTIFICATION 構造体には、次の有効なメンバーがあります。

<![CDATA[Notification.ulEventType = fnevObjectModified
Notification.info.obj.ulObjType = MAPI_ADDRBOOK]]>

構造体内のその他のメンバーはすべて NULL またはゼロになります。クライアントは、この通知を UI の更新にのみ使用する必要があります。Windows アドレス帳 (WAB) 内の個々のオブジェクトへの変更に関する詳細情報は、現在利用できません。

vtbl 17 HRESULT Unadvise(DWORD ulConnection)

通知に関して、呼び出し元を Windows アドレス帳 (WAB) から登録解除します。

ulConnectionDWORDin対応する IAddrBook::Advise の呼び出しが返した接続番号を指定する ULONG 型の値。

戻り値

HRESULT

vtbl 18 HRESULT CreateOneOff(CHAR* lpszName, CHAR* lpszAdrType, CHAR* lpszAddress, DWORD ulFlags, DWORD* lpcbEntryID, ENTRYID** lppEntryID)

1回限り (one-off) のアドレスのエントリ識別子を作成します。

lpszNameCHAR*inout受信者の表示名を指定する文字列へのポインター。lpszName パラメーターは NULL にすることができます。
lpszAdrTypeCHAR*inoutFAX や SMTP など、受信者のアドレスの種類を指定する文字列へのポインター。lpszAdrType パラメーターを NULL にすることはできません。
lpszAddressCHAR*inout受信者のアドレスを指定する文字列へのポインター。lpszAddress パラメーターを NULL にすることはできません。
ulFlagsDWORDin

1回限り (one-off) の受信者に影響するフラグのビットマスクを指定する ULONG 型の値。次のフラグは Windows アドレス帳 (WAB) で有効です。

フラグ 説明
MAPI_SEND_NO_RICH_INFO 受信者が書式設定されたメッセージコンテンツを処理できないことを示します。MAPI_SEND_NO_RICH_INFO が設定されている場合、MAPI は受信者の PR_SEND_RICH_INFO プロパティを FALSE に設定します。MAPI_SEND_NO_RICH_INFO が設定されていない場合、MAPI はこのプロパティを TRUE に設定します。ただし、受信者のメッセージングアドレス (lpszAddress が指すアドレス) がインターネットアドレスと解釈される場合を除きます。この場合、MAPI は PR_SEND_RICH_INFO を FALSE に設定します。
MAPI_UNICODE 名前、アドレスの種類、アドレスを Unicode 形式で表示します。MAPI_UNICODE フラグが設定されていない場合、これらの文字列は ANSI 形式で表示されます。
lpcbEntryIDDWORD*inoutlppEntryID パラメーターが指すエントリ識別子のバイト数を指定する ULONG 型の変数へのポインター。
lppEntryIDENTRYID**inout1回限り (one-off) の受信者のエントリ識別子を受け取る ENTRYID 型の変数へのポインターのアドレス。

戻り値

HRESULT

vtbl 19 HRESULT NewEntry(DWORD ulUIParam, DWORD ulFlags, DWORD cbEIDContainer, ENTRYID* lpEIDContainer, DWORD cbEIDNewEntryTpl, ENTRYID* lpEIDNewEntryTpl, DWORD* lpcbEIDNewEntry, ENTRYID** lppEIDNewEntry)

ユーザーが新しいエントリを作成できる空のダイアログボックスを表示します。

ulUIParamDWORDinダイアログボックスの親ウィンドウハンドルを指定する ULONG_PTR 型の値。
ulFlagsDWORDin予約済み。0 に設定する必要があります。
cbEIDContainerDWORDinlpEIDContainer のサイズを指定する ULONG 型の値。
lpEIDContainerENTRYID*inout新しいアドレスを作成するコンテナーのエントリ識別子を指定する ENTRYID 型の変数へのポインター。このパラメーターの値が NULL の場合、メソッドはルートコンテナーにエントリを作成します。これは NewEntry の MAPI 実装とは異なる点に注意してください。
cbEIDNewEntryTplDWORDin作成するオブジェクトを決定するために使用されるテンプレートエントリ識別子を指定する ULONG 型の値。
lpEIDNewEntryTplENTRYID*inout作成するオブジェクトを決定するために使用されるテンプレートエントリ識別子を指定する ENTRYID 型の変数へのポインター。
lpcbEIDNewEntryDWORD*inoutlppEIDNewEntry の内容の返されるサイズを指定する ULONG 型の変数へのポインター。
lppEIDNewEntryENTRYID**inout新しいエントリの返されるエントリ識別子を受け取る ENTRYID 型の変数へのポインターのアドレス。

戻り値

HRESULT

解説(Remarks)

ダイアログボックスを一切表示せずに Windows アドレス帳 (WAB) に新しいエントリを作成するには、CreateEntry を使用します。cbEIDNewEntryTpllpEIDNewEntryTpl は、作成するオブジェクトの種類を定義するテンプレートエントリ識別子です。テンプレートエントリ識別子を取得するには、任意の Windows アドレス帳 (WAB) コンテナーを開き、IMAPIProp::GetProps を呼び出してコンテナーから PR_DEF_CREATE_MAILUSER または PR_DEF_CREATE_DL プロパティを要求します。結果として得られるバイナリプロパティが、対応するテンプレート識別子です。

vtbl 20 HRESULT ResolveName(UINT_PTR ulUIParam, DWORD ulFlags, CHAR* lpszNewEntryTitle, ADRLIST* lpAdrList)

部分的な受信者リストを完全なアドレスに解決します。

ulUIParamUINT_PTRin親ウィンドウハンドルを指定する ULONG_PTR 型の値。
ulFlagsDWORDin

動作に影響するフラグを指定する ULONG 型の値。

フラグ 説明
MAPI_DIALOG 追加の名前解決情報の入力をユーザーに求めるダイアログボックスを表示します。このフラグが設定されていない場合、ダイアログボックスは表示されません。
WAB_RESOLVE_ALL_EMAILS エントリの既定の電子メールアドレスと照合するのではなく、すべてのエントリのすべての電子メールアドレスと照合して名前解決を行います。これにより名前解決が遅くなります。速度が重要な場合はこのフラグの使用を避けてください。
WAB_RESOLVE_NO_ONE_OFFS 最初の解決の試行が失敗した後、Windows アドレス帳 (WAB) が有効な電子メールアドレスまたは名前/電子メールアドレスのペアを 1回限り (one-off) のアドレスとして解決しないようにします。解決に失敗すると、既定の動作では有効な名前/電子メールのペアまたは電子メールアドレスの情報が 1回限り (one-off) のアドレスに変換されます。
WAB_RESOLVE_NEED_CERT 一致するエントリに解決時に返すことができる証明書データがある場合にのみ、名前解決が成功するようにします。
WAB_RESOLVE_NO_NOT_FOUND_UI 通常、名前解決の失敗後に表示される Windows アドレス帳 (WAB) の UI を抑制します。
WAB_RESOLVE_USE_CURRENT_PROFILE プロファイルまたは Identity が有効な Windows アドレス帳 (WAB) セッションで、名前解決を現在の Identity に対応する連絡先のみに制限します。名前解決では、まず Identity のプライベートフォルダーのリスト内で完全一致を探します。Identity のフォルダーに一致するものが見つからない場合、Windows アドレス帳 (WAB) はすべての共有フォルダーを検索し、続いて LDAP を検索します。このフラグが指定されていない場合、Windows アドレス帳 (WAB) はプロファイルが有効かどうかに関係なく、すべてのコンテンツに対して検索を行います。
WAB_RESOLVE_FIRST_MATCH Windows アドレス帳 (WAB) が指定された条件に一致する最初のエントリを返すようにします。Windows アドレス帳 (WAB) は最初のエントリを見つけると、それ以外の一致を探しません。
WAB_RESOLVE_LOCAL_ONLY LDAP サーバーが名前解決用に構成されている場合でも、Windows アドレス帳 (WAB) がそれらの LDAP サーバーでの名前解決をスキップするようにします。このフラグは、解決または検索を Windows アドレス帳 (WAB) 内のコンテンツに制限したい場合に便利です。
lpszNewEntryTitleCHAR*inoutIAddrBook::NewEntry ダイアログボックスのタイトルを指定する文字列へのポインター。
lpAdrListADRLIST*inout照合するプロパティリストを含むアドレスリストを指定する ADRLIST 型の変数へのポインター。出力時に、lpAdrList は解決された受信者のアドレスリストを含む変数へのポインターを受け取ります。

戻り値

HRESULT

説明
S_OK 名前解決処理が成功しました。
MAPI_E_AMBIGUOUS_RECIP lpAdrList パラメーター内の少なくとも1つの受信者が、アドレス帳内の複数のエントリと一致しました。通常、この値は MAPI_DIALOG フラグが設定されておらず、ダイアログボックスの表示が禁止されている場合に返されます。
MAPI_E_NOT_FOUND lpAdrList パラメーター内の少なくとも1つの受信者を解決できません。通常、この値は MAPI_DIALOG フラグが設定されておらず、ダイアログボックスの表示が禁止されている場合に返されます。

解説(Remarks)

ResolveName は、あいまいな一致が見つかった場合に、オプションでダイアログボックスを表示します。ResolveNamelpAdrList で渡されたアドレスリストを走査し、未解決の名前をすべて見つけて解決し、適切に変更されたアドレスリストを返します。渡すアドレスリストは、IAddrBook::Address メソッドを使用して作成されたリストにすることができます。

受信者があいまいで、MAPI_DIALOG フラグが指定されていない場合、ResolveNameMAPI_E_AMBIGUOUS_RECIPIENT を返します。

メモ

ADRLIST 内の ADRENTRY 項目は、AllocateMore で割り当てるのではなく、個別に割り当てる必要があります。

ResolveName がエントリを置き換えるとき、ADRENTRYFreeBuffer の動作によって解放されます。 新しいエントリは AllocateMore によって割り当てられます。

vtbl 21 HRESULT Address(DWORD* lpulUIParam, ADRPARM* lpAdrParms, ADRLIST** lppAdrList)

IAddrBook::Address は、共通のアドレス帳ダイアログボックスを表示します。

lpulUIParamDWORD*inoutダイアログボックスの親ウィンドウのハンドルを指定する ULONG_PTR 型の変数へのポインター。入力時には、常にウィンドウハンドルを渡す必要があります。出力時に、lpAdrParms パラメーターの ADRPARM 構造体に DIALOG_SDI フラグが設定されている場合、モードレスダイアログボックスのウィンドウハンドルが返されます。
lpAdrParmsADRPARM*inoutアドレス指定ダイアログボックスの表示と動作を指定する ADRPARM 型の変数へのポインター。
lppAdrListADRLIST**inout現在の受信者リストを指定する ADRLIST 型の変数へのポインターのアドレス。出力時に、lppAdrListIAddrBook::Address が格納される ADRLIST へのポインターのアドレスを受け取ります。ユーザーは入力時に lppAdrListNULL に設定できます。

戻り値

HRESULT

解説(Remarks)

アドレス指定ダイアログボックスの動作は、lpAdrParms 内のフラグとパラメーターによって指定されます。Windows アドレス帳 (WAB) は、MAPI の Address メソッドの一部のカスタマイズ機能をサポートしていません。また、Windows アドレス帳 (WAB) は MAPI の送信オプションダイアログボタンもサポートしていません。

vtbl 22 HRESULT Details(UINT_PTR* lpulUIParam, LPFNDISMISS lpfnDismiss, void* lpvDismissContext, DWORD cbEntryID, ENTRYID* lpEntryID, LPFNBUTTON lpfButtonCallback, void* lpvButtonContext, CHAR* lpszButtonText, DWORD ulFlags)

Windows アドレス帳 (WAB) 内の特定のエントリの詳細を表示し、編集を可能にするダイアログボックスを表示します。

lpulUIParamUINT_PTR*inout返されるダイアログボックスの、返される親ウィンドウハンドルを受け取る ULONG_PTR 型の変数へのポインター。
lpfnDismissLPFNDISMISSinDISMISSMODELESS 関数ポインター。この関数は、モードレスダイアログボックスが閉じられるときに呼び出されます。実装されていません。
lpvDismissContextvoid*inout実装されていません。
cbEntryIDDWORDinlpEntryID のサイズを指定する ULONG 型の値。
lpEntryIDENTRYID*inout詳細を表示するエントリのエントリ識別子を指定する ENTRYID 型の変数へのポインター。
lpfButtonCallbackLPFNBUTTONinWindows アドレス帳 (WAB) ではサポートされていません。NULL にする必要があります。
lpvButtonContextvoid*inoutWindows アドレス帳 (WAB) ではサポートされていません。NULL にする必要があります。
lpszButtonTextCHAR*inoutWindows アドレス帳 (WAB) ではサポートされていません。NULL にする必要があります。
ulFlagsDWORDinWindows アドレス帳 (WAB) ではサポートされていません。NULL にする必要があります。

戻り値

HRESULT

解説(Remarks)

Windows アドレス帳 (WAB) はボタンコールバックをサポートしていません。プロパティシートは、IWABExtInit および IShellPropSheetExt Interface インターフェイスを通じて拡張できます。

vtbl 23 HRESULT RecipOptions(DWORD ulUIParam, DWORD ulFlags, ADRENTRY* lpRecip)

このメソッドは実装されていません。(IAddrBook::RecipOptions)

ulUIParamDWORDin実装されていません。
ulFlagsDWORDin実装されていません。
lpRecipADRENTRY*inout実装されていません。
vtbl 24 HRESULT QueryDefaultRecipOpt(CHAR* lpszAdrType, DWORD ulFlags, DWORD* lpcValues, SPropValue** lppOptions)

このメソッドは実装されていません。(IAddrBook::QueryDefaultRecipOpt)

lpszAdrTypeCHAR*inout実装されていません。
ulFlagsDWORDin実装されていません。
lpcValuesDWORD*inout実装されていません。
lppOptionsSPropValue**inout実装されていません。
vtbl 25 HRESULT GetPAB(DWORD* lpcbEntryID, ENTRYID** lppEntryID)

既定の Windows アドレス帳 (WAB) コンテナーのエントリ識別子を返します。

lpcbEntryIDDWORD*inout返されるエントリ識別子のサイズを受け取る ULONG 型の変数へのポインター。
lppEntryIDENTRYID**inout既定の Windows アドレス帳 (WAB) コンテナーの、返されるエントリ識別子を受け取る ENTRYID 型の変数へのポインターのアドレス。

戻り値

HRESULT

解説(Remarks)

Internet Explorer 4 以前のバージョンの Windows アドレス帳 (WAB) では、既定の Windows アドレス帳 (WAB) コンテナーはアドレス帳全体を表しており、すべてのアドレス帳のコンテンツにこのコンテナーを通じてアクセスできました。

Internet Explorer 5 以降を使用してプロファイル対応の Windows アドレス帳 (WAB) セッションを指定する Windows アドレス帳 (WAB) クライアントの場合、既定の Windows アドレス帳 (WAB) コンテナーは現在の Identity の既定の連絡先フォルダーに対応します。アプリケーションが IAddrBook::GetPAB を呼び出して PAB コンテナー内のデータを操作する限り、すべてのデータは現在の Identity のフォルダー内で自動的に操作されます。

プロファイル対応セッションを要求しない Windows アドレス帳 (WAB) クライアントの場合、IAddrBook::GetPAB が返すコンテナーは、連絡先フォルダー (Identity Manager がない場合) または共有連絡先フォルダー (Identity が存在する場合) に対応します。このフォルダーは、すべての Windows アドレス帳 (WAB) ユーザーが利用できます。プロファイルに関心のないアプリケーション開発者は、PAB コンテナー内でのすべてのデータ操作がすべてのユーザーに利用可能であることが保証されます。

vtbl 26 HRESULT SetPAB(DWORD cbEntryID, ENTRYID* lpEntryID)

このメソッドは実装されていません。(IAddrBook::SetPAB)

cbEntryIDDWORDin実装されていません。
lpEntryIDENTRYID*inout実装されていません。
vtbl 27 HRESULT GetDefaultDir(DWORD* lpcbEntryID, ENTRYID** lppEntryID)

このメソッドは実装されていません。(IAddrBook::GetDefaultDir)

lpcbEntryIDDWORD*inout実装されていません。
lppEntryIDENTRYID**inout実装されていません。
vtbl 28 HRESULT SetDefaultDir(DWORD cbEntryID, ENTRYID* lpEntryID)

このメソッドは実装されていません。(IAddrBook::SetDefaultDir)

cbEntryIDDWORDin実装されていません。
lpEntryIDENTRYID*inout実装されていません。
vtbl 29 HRESULT GetSearchPath(DWORD ulFlags, SRowSet** lppSearchPath)

IAddrBook::GetSearchPath は、IAddrBook::ResolveName メソッドによって開始される名前解決処理に含めるコンテナーのエントリ識別子の順序付きリストを返します。

ulFlagsDWORDin

検索パスで返される文字列の種類を制御するフラグのビットマスクを指定する ULONG 型の値。次のフラグは Windows アドレス帳 (WAB) で有効です。

フラグ 説明
MAPI_UNICODE 返される文字列が Unicode 形式であることを指定します。このフラグが設定されていない場合、文字列は ANSI 形式になります。
lppSearchPathSRowSet**inoutコンテナーのエントリ識別子の順序付きリストを指定する SRowSet 型の変数へのポインターのアドレス。IAddrBook::GetSearchPath は、順序付きリストを SRowSet 構造体に格納します。アドレス帳の階層にコンテナーがない場合、メソッドは SRowSet 構造体にゼロを返します。

戻り値

HRESULT

vtbl 30 HRESULT SetSearchPath(DWORD ulFlags, SRowSet* lpSearchPath)

このメソッドは実装されていません。(IAddrBook::SetSearchPath)

ulFlagsDWORDin実装されていません。
lpSearchPathSRowSet*inout実装されていません。

戻り値

実装されていません。

vtbl 31 HRESULT PrepareRecips(DWORD ulFlags, SPropTagArray* lpPropTagArray, ADRLIST* lpRecipList)

メッセージングシステムが後で使用するために受信者リストを準備します。

ulFlagsDWORDin予約済み。0 に設定する必要があります。
lpPropTagArraySPropTagArray*inout更新が必要なプロパティ (存在する場合) を示すプロパティタグの配列を指定する SPropTagArray 型の変数へのポインター。この変数は NULL にすることができます。
lpRecipListADRLIST*inout受信者のリストを保持する構造体を指定する ADRLIST 型の変数へのポインター。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"

出力引数:
#define global IID_IAddrBook "{}"
#usecom global IAddrBook IID_IAddrBook "{}"
#comfunc global IAddrBook_OpenEntry             14 int,var,var,int,var,sptr
#comfunc global IAddrBook_CompareEntryIDs       15 int,var,int,var,int,var
#comfunc global IAddrBook_Advise                16 int,var,int,sptr,var
#comfunc global IAddrBook_Unadvise              17 int
#comfunc global IAddrBook_CreateOneOff          18 var,var,var,int,var,var
#comfunc global IAddrBook_NewEntry              19 int,int,int,var,int,var,var,var
#comfunc global IAddrBook_ResolveName           20 sptr,int,var,var
#comfunc global IAddrBook_Address               21 var,var,var
#comfunc global IAddrBook_Details               22 var,sptr,sptr,int,var,sptr,sptr,var,int
#comfunc global IAddrBook_RecipOptions          23 int,int,var
#comfunc global IAddrBook_QueryDefaultRecipOpt  24 var,int,var,var
#comfunc global IAddrBook_GetPAB                25 var,var
#comfunc global IAddrBook_SetPAB                26 int,var
#comfunc global IAddrBook_GetDefaultDir         27 var,var
#comfunc global IAddrBook_SetDefaultDir         28 int,var
#comfunc global IAddrBook_GetSearchPath         29 int,var
#comfunc global IAddrBook_SetSearchPath         30 int,var
#comfunc global IAddrBook_PrepareRecips         31 int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。