プログラムでのライブラリの使用

このトピックでは、プログラムでライブラリを使用する際に考慮すべき事項について説明します。

このトピックの内容:

• ライブラリ プログラミングの概要
• ライブラリを使用したプログラミング
  • 既知のフォルダーからライブラリへの移動
  • HomeGroup と共有ライブラリ
• ライブラリでの共通ファイル ダイアログ ボックスの使用
• ユーザー インターフェイスからのライブラリ選択の有効化
• プログラム内のライブラリ コンテンツへのアクセス
  • IShellLibrary インターフェイスを使用したライブラリ コンテンツへのアクセス
  • シェル API を使用したライブラリ コンテンツへのアクセス
• ライブラリにユーザー コンテンツを保存する
• ライブラリでのドラッグ アンド ドロップ操作のサポート
• ライブラリとの同期を維持する
  • 一括更新
  • シェル API 通知
  • ファイル システム API 通知
• 関連トピック

ライブラリ プログラミングの概要

ライブラリを使用すると、ファイル システムのorganizationに限定されず、ユーザーにとって意味のある方法でファイル ベースのコンテンツを整理できます。 プログラムがライブラリをサポートしている場合、ユーザーは、Windows 7 のユーザー エクスペリエンスと一致するユーザー インターフェイスを提示しながら、ユーザーに理にかなった方法でコンテンツを見つけることができます。 また、ライブラリを使用すると、異なるフォルダーまたは異なるマシンに格納されているファイル ベースのコンテンツをプログラムで簡単に見つけることができます。

このセクションのトピックでは、プログラムにライブラリ サポートを追加し、ライブラリが提供する新機能を利用する方法について説明します。 Windows 7 では、このサポートの一部が既定で提供されています。 プログラムが現在使用している一般的なファイル ダイアログ ボックスを変更しない場合は、ライブラリをサポートするために追加のプログラミングはほとんど必要ない場合があります。

このセクションでは、ライブラリが提供する主要な機能の一部と、プログラムでそれらをサポートする方法について説明します。 この情報を使用すると、プログラムから最適なユーザー エクスペリエンスを提供する機能を決定できます。 プログラムで共通ファイル ダイアログ ボックスをカスタマイズする場合、このセクションの情報は、新しい共通ファイル ダイアログ ボックスを使用してライブラリを使用し、Windows 7 で同等の機能を提供する方法を決定するのに役立ちます。

ライブラリを使用したプログラミング

Windows Shell プログラミング モデルでは、プログラムが Windows Shell プログラミング オブジェクトとどのように対話するかを説明します。 ファイルやディレクトリなどのファイル システム オブジェクトは Windows シェル オブジェクトで表されますが、すべての Windows シェル オブジェクトがファイル システムによって表されるわけではありません。 たとえば、ライブラリは、ファイル システムに相当するものがない Windows シェル オブジェクトです。 プログラムで Windows Shell オブジェクトを使用すると、プログラムはファイル システム オブジェクトだけでなく、すべてのシェル オブジェクトにアクセスできます。

最適な結果を得るために、プログラムでは シェル ライブラリ API を使用してライブラリを操作し、その内容にアクセスします。 ライブラリにはフォルダーやファイルなどのファイル システム項目が含まれていますが、ライブラリはファイル システム項目ではありません。 そのため、ファイル システム API を使用してライブラリの機能やライブラリコンテンツにアクセスすることはできません。

現在多くのファイル システム API を使用している既存のプログラムがある場合でも、プログラムはライブラリ機能を利用できます。 シェル ライブラリ API は、ライブラリ内にある項目へのファイル システム参照を提供でき、これらのファイル システム参照 (ファイル名やパスなど) は、既存のプログラムにある既存のファイル システム API に渡すことができます。

既知のフォルダーからライブラリへの移動

Windows 7 より前は、ファイルの保存またはファイルを開く操作の既定のフォルダーとして、My Documents フォルダーなどの既知のフォルダーを使用するのが一般的でした。 Windows 7 では、ユーザーが Windows エクスプローラーなどの他の Windows 7 プログラムと同じエクスペリエンスをプログラムで使用できるように、対応するライブラリを使用する必要があります。

現在、プログラムで Windows シェル API を使用している場合は、ライブラリのサポートを追加するのは簡単です。 たとえば、 現在 SHGetKnownFolderItem 関数を呼び出して My Documents フォルダーの場所を取得している場合、My Documents 既知のフォルダーの KNOWNFOLDERID 値を、対応するライブラリの KNOWNFOLDERID 値に置き換えることができます。

次の表は、既知のフォルダーの KNOWNFOLDERID 値と、Windows 7 の対応するライブラリの KNOWNFOLDERID 値の関係を示しています。

既知のフォルダー KNOWNFOLDERID 値	ライブラリ KNOWNFOLDERID 値
FOLDERID_Documents	FOLDERID_DocumentsLibrary
FOLDERID_Pictures	FOLDERID_PicturesLibrary
FOLDERID_Music	FOLDERID_MusicLibrary
FOLDERID_RecordedTV	FOLDERID_RecordedTVLibrary

 

HomeGroup と共有ライブラリ

プログラムにライブラリ のサポートを追加すると、HomeGroup の共有ライブラリのサポートが有効になります。 HomeGroup は、 KNOWNFOLDERID 値 の FOLDERID_HomeGroup によって識別されます。 プログラムは、IShellLibrary::GetDefaultSaveFolder メソッドの呼び出しで DEFAULTSAVEFOLDERTYPE 値を設定することで、ユーザーのプライベートまたは共有の既定の保存場所を特定できます。

ライブラリでの共通ファイル ダイアログ ボックスの使用

ライブラリでの共通ファイル ダイアログ ボックスの使用 Windows 7 のライブラリをサポートするように共通ファイル ダイアログ ボックスが更新されました。 次の図は、Windows 7 のユーザーに共通のファイル ダイアログ ボックスがどのように表示されるかを示しています。

Windows 7 では、プログラムに現在共通のファイル ダイアログ ボックスが表示されており、ダイアログ ボックス テンプレートを変更したり、イベントをフックしたりしていない場合は、新しい Windows 7 バージョンのダイアログ ボックスが自動的に表示されます。 具体的には、共通ファイル ダイアログ ボックス関数の呼び出しでは、OPENFILENAME 構造体の lpfnHook、hInstance、lpTemplatename メンバーは NULL である必要があり、OFN_ENABLEHOOKおよびOFN_ENABLETEMPLATE フラグはクリアである必要があります。

Windows 7 では、 IFileDialog 関連のインターフェイスは、以前のバージョンの Windows で使用されていた一般的なファイル ダイアログ ボックス関数を置き換えます。 以前の一般的なファイル ダイアログ ボックス関数は、Windows 7 では引き続きサポートされていますが、完全な Windows 7 ユーザー エクスペリエンスは提供されず、ライブラリはサポートされていません。 IFileDialog 関連のインターフェイスでサポートされる新機能の一部を次に示します。

• ユーザーは、Windows 7 Windows エクスプローラーでサポートされているファイル プロパティにアクセスして、ファイルを検索して選択できます。
• プログラムでは、シェル名前空間 API のインターフェイスとメソッドを使用して項目を操作できます。
• プログラムでは、リソース ファイル駆動型カスタマイズ モデルの代わりにデータドリブン カスタマイズ モデルを使用して、共通のファイル ダイアログ ボックスに新しいコントロールを追加できます。

IFileDialog 関連のインターフェイスは、次の場合に使用する必要があります。

• Windows 7 でプログラムの共通ファイル ダイアログ ボックスをカスタマイズする必要があります。 これにより、プログラムはライブラリを操作でき、ダイアログ ボックスのカスタマイズがサポートされます。
• ユーザーが共通のファイル ダイアログ ボックスから複数のファイルを選択できるようにする場合。 これにより、ライブラリに異なるフォルダーに格納されているコンテンツを含めることができるため、選択したオブジェクトへの正しいパスが確実に取得されます。

IFileDialog 関連のインターフェイスの詳細については、次を参照してください。

• IFileDialog
• IFileOpenDialog
• IFileSaveDialog
• IFileDialogCustomize
• IFileDialogEvents
• IFileDialogControlEvents

ユーザー インターフェイスからのライブラリ選択の有効化

プログラムで、Windows 7 でインポートやエクスポート機能などのフォルダーを選択できる場合は、ユーザーもライブラリを選択できるようにする必要があります。 IFileOpenDialog インターフェイスと SHBrowseForFolder 関数を使用すると、フォルダーの選択を求められたときにライブラリを選択できます。 IFileOpenDialog は Windows 7 ユーザー インターフェイスをサポートしているため、IFileOpenDialog インターフェイスは SHBrowseForFolder 関数よりも優先されます。

IFileOpenDialog インターフェイスを使用するときにユーザーがフォルダーを選択できるようにするには、FOS_PICKFOLDERS フラグを設定して SetOptions を呼び出し、FOS_FORCEFILESYSTEM フラグがクリアされていることを確認します。

FILEOPENDIALOGOPTIONS fileOptions;

hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);

ユーザーが SHBrowseForFolder 関数を呼び出すときにフォルダーを選択できるようにするには、 BROWSEINFO 構造体の ulFlags メンバーで、BIF_USENEWUI フラグを設定し、BIF_RETURNONLYFSDIRS フラグをクリアします。

BROWSEINFO    browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);

プログラム内のライブラリ コンテンツへのアクセス

ライブラリの内容にアクセスするには、Windows シェル API を使用する必要があります。 ライブラリはファイル システム オブジェクトではないので、ファイル システム API の関数を使用してライブラリコンテンツにアクセスすることはできません。 プログラムでファイル システム API に基づくカスタム ファイル ブラウザーを使用している場合、ライブラリを参照したり、ライブラリのコンテンツにアクセスしたりすることはできません。

このセクションでは、ライブラリを操作するようにプログラムを更新する最適な方法を選択できるように、ライブラリ コンテンツにアクセスする方法について説明します。

IShellLibrary インターフェイスを使用したライブラリ コンテンツへのアクセス

プログラムがライブラリ コンテンツにアクセスする最も簡単な方法は、 シェル ライブラリ API を使用することです。 ファイル システム API を使用するプログラムで作業している場合、 シェル ライブラリ API はライブラリのファイル システム フォルダーを返すことができます。これにより、既存のプログラム コードの変更が最小限に抑えられます。

IShellLibrary *picturesLibrary;

hr = SHLoadLibraryFromKnownFolder(FOLDERID_PicturesLibrary, 
                                  STGM_READ, 
                                  IID_PPV_ARGS(&picturesLibrary));

// picturesLibrary now points to the user's picture library
    
IShellItemArray *pictureFolders; 

hr = pslLibrary->GetFolders(LFF_FORCEFILESYSTEM, IID_PPV_ARGS(&pictureFolders));

// pictureFolders now contains an array of Shell items that
// represent the folders found in the user's pictures library

シェル API を使用したライブラリ コンテンツへのアクセス

ライブラリ オブジェクトはシェル プログラミング モデルの一部であるため、他の Windows シェル API と共に使用できます。 たとえば、 IShellItem インターフェイスと IShellFolder インターフェイスを、関連するヘルパー関数と共に使用して、フォルダーとフォルダーの内容を列挙してファイル システム API を使用してコンテンツにアクセスするのと同じ方法でライブラリの内容にアクセスできます。

Windows シェル API では、ライブラリの内容にアクセスするための 2 つの列挙モードがサポートされています。

• 列挙を参照する

  参照列挙は既定の列挙モードであり、ライブラリ フォルダーの内容を列挙します。 このモードを使用するには、SHCONTF_NAVIGATION_ENUM フラグをクリアします。

• ナビゲーション列挙

  ナビゲーション列挙は、ライブラリ フォルダーを列挙します。 このモードを使用するには、SHCONTF_NAVIGATION_ENUM フラグを設定します。

プログラムでカスタム ツリー コントロールを使用してユーザーのフォルダーを移動する場合、ナビゲーション列挙モードでフォルダーを列挙すると、Windows エクスプローラーが Windows 7 のフォルダーを列挙する方法と一致するライブラリのフォルダーの一覧が表示されます。

プログラムでこれらの機能を使用する方法の例については、Windows SDK の ShellStorage サンプルを参照してください。

ライブラリにユーザー コンテンツを保存する

プログラムでは、ユーザー コンテンツをライブラリとライブラリ内のフォルダーに保存できます。 同様に、ユーザーはライブラリ内の特定のフォルダーに保存することも、ライブラリに保存することもできます。

すべてのライブラリには、既定の保存場所として指定されたフォルダーがあります。 既定の保存場所は、ライブラリの作成時に定義されます。ただし、ユーザーは既定の保存場所をライブラリ内の任意のフォルダーに再割り当てできます。 ユーザーは既定の保存場所を構成する必要はありませんが、変更することもできます。 ユーザーが既定の保存場所として現在設定されているフォルダーを削除すると、ライブラリ内の次のフォルダーが既定の保存場所として自動的に構成されます。

ユーザー コンテンツをライブラリに保存するには、いくつかの方法があります。

• シェル API

  シェル プログラミング モデルを使用し、 IShellItem、IStorage、または IStream で表されるシェル項目をライブラリ オブジェクトに保存すると、シェル項目は自動的にライブラリの既定の保存場所に格納されます。

• ファイル システム API

  多数のファイル システム API 呼び出しを使用する既存のプログラムがある場合は、ライブラリの既定の保存場所として定義されているフォルダーへのパスを取得できます。 その後、フォルダー パスをファイル システム API に渡すことができます。

プログラムでこれらの機能を使用する方法の例については、Windows SDK の ShellStorage サンプルを参照してください。

ライブラリでのドラッグ アンド ドロップ操作のサポート

プログラムでドラッグ アンド ドロップ アクションがサポートされている場合は、適切なライブラリ操作をサポートするように更新する必要があります。 ファイルがライブラリにドロップされた場合、ドロップされたファイルは既定の保存場所に保存されます。 フォルダーがライブラリにドロップされた場合は、ドロップされたフォルダーをライブラリに新しいフォルダーとして追加する必要があります。 既定の保存場所ではない既存のフォルダーにファイルがドロップされた場合は、選択したフォルダーにファイルを追加する必要があります。

プログラムのドラッグ アンド ドロップ機能のライブラリ サポートを追加する方法の例については、Windows SDK の ShellLibraryCommandLine サンプルを参照してください。

ライブラリとの同期を維持する

このトピックでは、プログラムがライブラリのコンテンツのビューを最新の状態に保つ方法について説明します。

一括更新

プログラムが実行されていない場合、ユーザーはライブラリのフォルダーを対話的に変更できるため、ライブラリに対する変更の検出と保存を開始するときに、プログラムで SHResolveLibrary を呼び出す必要があります。 シェル API は SHResolveLibrary 関数を提供し、プログラムがライブラリの現在のコンテンツと、ライブラリに含まれる可能性のあるフォルダーの現在の場所を取得できるようにします。

SHResolveLibrary はブロック関数であり、ライブラリの変更に応じて、戻り時間が長くなる可能性があることに注意してください。 そのため、UI スレッドから呼び出さないでください。

プログラムが最新の状態に更新されると、変更通知に登録して現在のビューを維持できます。

シェル API 通知

Windows シェル API には SHChangeNotifyRegister 関数が用意されています。これは、非サービス プロセスにライブラリの変更を通知する推奨される方法です。

Windows シェル API を使用してライブラリ内のアイテムの変更を検出するには、 SHChangeNotifyRegister を呼び出して、ライブラリ フォルダー内のアイテムに対する変更の通知用にプログラムを登録します。 この関数は、任意のライブラリまたは特定のライブラリに変更があった場合にプログラムに通知できます。 通知は、ライブラリが変更されるとすぐに送信されます。

ファイル システム API 通知

ファイル システム通知は、サービス プロセスで使用する必要があります。

ファイル システム API を使用してライブラリ内のアイテムの変更を検出するには、ライブラリ内のフォルダーを列挙し、監視する各フォルダーに対して FindFirstChangeNotification を呼び出します。 監視対象フォルダーが変更されると、プログラムは通知を受け取ります。 フォルダー内で変更されたファイルの特定のファイルを検索するには、 ReadDirectoryChangesW を呼び出します。 ライブラリ記述ファイルの変更を検出するには、そのファイルを含むフォルダーを監視します。 ライブラリ記述ファイルは 、FOLDERID_Libraries フォルダーにあります。 ただし、ライブラリ記述ファイルを開いたり変更したりしないでください。

関連トピック

ライブラリについて

IShellLibrary

シェル リンク

既知のフォルダー

ライブラリ記述スキーマ

IID_PPV_ARGS