IUrlAccessor

COM

IID0b63e318-9ccc-11d0-bcdb-00805fccce04継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

URL が gatherer からフィルターホストに提供されるコンテンツソース内の個々のアイテムを処理するためのメソッドを提供します。

解説(Remarks)

これは、コンテンツソースからデータを取得するための主要なインターフェイスです。Get... 系のメソッドは、フィルターホストが必要とする、あるいはフィルターホストにとって有用なプロパティを対象としています。すべてのデータソースがこれらのプロパティを備えているわけではありません。これらのメソッドが返すプロパティが対象のデータソースにとって意味を持たない場合、プロトコルハンドラーは E_NOTIMPL を返す必要があります。

Bind... 系のメソッドは、データへのアクセスを提供します。

プロトコルハンドラーはプロトコルホストのマルチスレッド環境で動作しますが、各プロトコルハンドラーはそれぞれ独自のスレッドで実行され、一度に 1 つの IUrlAccessor オブジェクトのみを使用します。

メソッド 13

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

vtbl 3 HRESULT AddRequestParameter(PROPSPEC* pSpec, PROPVARIANT* pVar)

プロパティと値の組を要求します。

pSpec	PROPSPEC*	in	要求するプロパティを格納した PROPSPEC 構造体へのポインター。
pVar	PROPVARIANT*	in	pSpec で指定されたプロパティの値を格納した PROPVARIANT 構造体へのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

コンテンツソースから追加情報 (たとえば HTTP 要求の If-Modified-Since ヘッダーなど) を取得するには、このメソッドを実装します。

vtbl 4 HRESULT GetDocFormat(LPWSTR wszDocFormat, DWORD dwSize, DWORD* pdwLength)

ドキュメント形式を Multipurpose Internet Mail Extensions (MIME) 文字列として取得します。

wszDocFormat	LPWSTR	out	現在のアイテムの MIME タイプを格納した、NULL 終端の Unicode 文字列へのポインターを受け取ります。
dwSize	DWORD	in	wszDocFormat のサイズ (TCHAR単位)。
pdwLength	DWORD*	out	wszDocFormat に書き込まれた TCHAR数 (終端の NULL を含まない) へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

wszDocFormat は、IUrlAccessor::BindToStream が返すストリームに対する適切な IFilter を特定するために使用されます。URL アイテムが、ファイル名の拡張子やコンテンツタイプから示されるものとは異なる関連付けを持つ場合に、このメソッドを実装します。たとえば、.doc アイテムが Microsoft Word に関連付けられていない場合、このメソッドは適切なドキュメントソースの CLSID Key キーを返す必要があります。

このメソッドまたは IUrlAccessor::GetCLSID メソッドの実装を提供しない場合、フィルターホストは IUrlAccessor::GetFileName の出力パラメーターを使用して Multipurpose Internet Mail Extensions (MIME) コンテンツタイプを判別します。

vtbl 5 HRESULT GetCLSID(GUID* pClsid)

処理中の URL アイテムのドキュメントタイプに対応する CLSID を取得します。

pClsid

GUID*

out

処理中の URL アイテムのドキュメントタイプに対応する CLSID へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

この情報が利用できない場合は、E_NOTIMPL または E_FAIL を返すことができます。

vtbl 6 HRESULT GetHost(LPWSTR wszHost, DWORD dwSize, DWORD* pdwLength)

該当する場合、コンテンツソースのホスト名を取得します。

wszHost	LPWSTR	out	コンテンツソースのファイルが存在するホストの名前を、NULL 終端の Unicode 文字列として受け取ります。
dwSize	DWORD	in	wszHost のサイズ (TCHAR単位、終端の NULL を含まない)。
pdwLength	DWORD*	out	wszHost に書き込まれた TCHAR数 (終端の NULL を含まない) へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 7 HRESULT IsDirectory()

アイテムの URL がディレクトリを指しているかどうかを判定します。

戻り値

型: HRESULT

URL がディレクトリの場合は S_OK を返し、それ以外の場合は S_FALSE を返します。

vtbl 8 HRESULT GetSize(ULONGLONG* pllSize)

URL が示すコンテンツのサイズを取得します。

pllSize

ULONGLONG*

out

URL に含まれるデータのバイト数へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドで算出される値は、IFilter の出力サイズの制限を決定する要素の 1 つになります。プロトコルの実装が階層型のコンテンツソースを対象とする場合、このメソッドはコンテナーに対して 0 を返す必要があります。

ファイル以外を対象とする場合は、インデックス付けするドキュメントのサイズを返すようにこのメソッドを実装します。たとえば、各行が 1 つのドキュメントに相当するデータベースをインデックス付けする場合は、その行のサイズの最も妥当な見積もり値を返します。

vtbl 9 HRESULT GetLastModified(FILETIME* pftLastModified)

URL が最後に変更された日時を示すタイムスタンプを取得します。

pftLastModified

FILETIME*

out

URL が最後に変更された日時のタイムスタンプを示す FILETIME 型の変数へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、前回インデックス付けされた時点から URL が変更されたかどうかを判断するために使用されます。最終更新日時が変わっていない場合、インデクサーはその URL のコンテンツを処理しません。

ディレクトリの URL は、このメソッドが返すタイムスタンプにかかわらず常に処理されます。

vtbl 10 HRESULT GetFileName(LPWSTR wszFileName, DWORD dwSize, DWORD* pdwLength)

フィルターホストがインデックス付けに使用する、アイテムのファイル名を取得します。アイテムがファイルシステム上に存在せず、IUrlAccessor::BindToStream メソッドが実装されている場合、このメソッドはそのアイテムに対するシェルの System.ParsingPath プロパティを返します。

wszFileName	LPWSTR	out	ファイル名を NULL 終端の Unicode 文字列として受け取ります。
dwSize	DWORD	in	wszFileName のサイズ ( TCHAR単位、終端の NULL を含まない)。
pdwLength	DWORD*	out	wszFileName に書き込まれた TCHAR数 ( NULL を含まない) へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドが実装されている場合、フィルターホストはファイル名を使用して、IUrlAccessor::BindToStream が返すストリームのコンテンツを解析するのに適切な IFilter を判別します。

vtbl 11 HRESULT GetSecurityDescriptor(BYTE* pSD, DWORD dwSize, DWORD* pdwLength)

URL アイテムのセキュリティ記述子を取得します。セキュリティはクエリ時に適用されるため、この記述子は読み取りアクセスに対するセキュリティを示します。

pSD	BYTE*	out	セキュリティ記述子へのポインターを受け取ります。
dwSize	DWORD	in	pSD 配列のサイズ (TCHAR単位)。
pdwLength	DWORD*	out	pSD に書き込まれた TCHAR数 (終端の NULL を含まない) へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドを使用すると、コンテンツソースに登録されているユーザーと、ドメインに登録されているユーザーが異なる場合に、両者の間で独自のマッピングを行えます。このメソッドで作成するセキュリティ記述子は、自己相対形式でなければなりません。

URL にユーザーのセキュリティ識別子 (SID) が含まれている場合、プロトコルハンドラーはそのユーザーのセキュリティコンテキストで呼び出されるため、このメソッドは E_NOTIMPL を返す必要があります。

URL にユーザー SID が含まれていない場合、プロトコルハンドラーはシステムサービスのセキュリティコンテキストで呼び出されます。その場合、このメソッドは読み取りアクセスを制限するためのアクセス制御リスト (ACL) を返すか、クエリ時に誰にでも読み取りアクセスを許可するために PRTH_S_ACL_IS_READ_EVERYONE を返すことができます。

注このメソッドが E_NOTIMPL を返し、かつ URL にユーザー SID が含まれていない場合、そのアイテムはすべてのユーザーのクエリで取得可能になります。

vtbl 12 HRESULT GetRedirectedURL(LPWSTR wszRedirectedURL, DWORD dwSize, DWORD* pdwLength)

現在のアイテムのリダイレクト先 URL を取得します。

wszRedirectedURL	LPWSTR	out	リダイレクト先の URL を Unicode 文字列として受け取ります (終端の NULL を含まない)。
dwSize	DWORD	in	wszRedirectedURL のサイズ (TCHAR単位、終端の NULL を含まない)。
pdwLength	DWORD*	out	wszRedirectedURL に書き込まれた TCHAR数 (終端の NULL を含まない) へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ファイル URL はリダイレクトされません。このメソッドは HTTP のコンテンツソースにのみ適用されます。

このメソッドが実装されている場合、ISearchProtocol::CreateAccessor に渡された URL は、このメソッドが返す値へリダイレクトされます。以降の相対 URL リンクはすべて、リダイレクト後の URL を基準に処理されます。

vtbl 13 HRESULT GetSecurityProvider(GUID* pSPClsid)

URL のセキュリティプロバイダーを取得します。

pSPClsid

GUID*

out

セキュリティプロバイダーの CLSID へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 14 HRESULT BindToStream(IStream** ppStream)

処理中のアイテムを IStream インターフェイス [構造化ストレージ] のデータストリームにバインドし、そのストリームへのポインターを取得します。

ppStream

IStream**

out

URL が表すアイテムを格納した IStream へのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

IUrlAccessor::GetFileName、IUrlAccessor::GetCLSID、および IUrlAccessor::GetDocFormat の各メソッドが返す情報を基に、適切なコンテンツ用の IFilter オブジェクトが作成され、IPersistStream インターフェイスによってこのストリームに渡されます。

vtbl 15 HRESULT BindToFilter(IFilter** ppFilter)

処理中のアイテムを適切な IFilter にバインドし、その IFilter へのポインターを取得します。

ppFilter

IFilter**

out

処理中のアイテムに関するメタデータを返すことができる IFilter へのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、指定された URL に関するプロトコルの情報に基づき、その URL に関連付けられたアイテムのプロパティを列挙するための IFilter を取得します。

URL のコンテンツが IUrlAccessor::BindToStream が返す IStream からもアクセス可能な場合は、追加のプロパティを取得するために、その IStream に対して別の IFilter が呼び出されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IUrlAccessor "{0B63E318-9CCC-11D0-BCDB-00805FCCCE04}"
#usecom global IUrlAccessor IID_IUrlAccessor "{}"
#comfunc global IUrlAccessor_AddRequestParameter    3 var,var
#comfunc global IUrlAccessor_GetDocFormat           4 var,int,var
#comfunc global IUrlAccessor_GetCLSID               5 var
#comfunc global IUrlAccessor_GetHost                6 var,int,var
#comfunc global IUrlAccessor_IsDirectory            7
#comfunc global IUrlAccessor_GetSize                8 var
#comfunc global IUrlAccessor_GetLastModified        9 var
#comfunc global IUrlAccessor_GetFileName            10 var,int,var
#comfunc global IUrlAccessor_GetSecurityDescriptor  11 var,int,var
#comfunc global IUrlAccessor_GetRedirectedURL       12 var,int,var
#comfunc global IUrlAccessor_GetSecurityProvider    13 var
#comfunc global IUrlAccessor_BindToStream           14 sptr
#comfunc global IUrlAccessor_BindToFilter           15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IUrlAccessor "{0B63E318-9CCC-11D0-BCDB-00805FCCCE04}"
#usecom global IUrlAccessor IID_IUrlAccessor "{}"
#comfunc global IUrlAccessor_AddRequestParameter    3 sptr,sptr
#comfunc global IUrlAccessor_GetDocFormat           4 sptr,int,sptr
#comfunc global IUrlAccessor_GetCLSID               5 sptr
#comfunc global IUrlAccessor_GetHost                6 sptr,int,sptr
#comfunc global IUrlAccessor_IsDirectory            7
#comfunc global IUrlAccessor_GetSize                8 sptr
#comfunc global IUrlAccessor_GetLastModified        9 sptr
#comfunc global IUrlAccessor_GetFileName            10 sptr,int,sptr
#comfunc global IUrlAccessor_GetSecurityDescriptor  11 sptr,int,sptr
#comfunc global IUrlAccessor_GetRedirectedURL       12 sptr,int,sptr
#comfunc global IUrlAccessor_GetSecurityProvider    13 sptr
#comfunc global IUrlAccessor_BindToStream           14 sptr
#comfunc global IUrlAccessor_BindToFilter           15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。