Bagikan melalui

Menggunakan Pustaka di Program Anda

  • Artikel

Topik ini menjelaskan beberapa hal yang perlu dipertimbangkan saat menggunakan pustaka dalam program Anda.

Dalam topik ini:

Gambaran umum pemrograman pustaka

Pustaka memungkinkan pengguna untuk mengatur konten berbasis file mereka dengan cara yang bermakna bagi mereka dan tidak dibatasi oleh organisasi sistem file. Ketika program Anda mendukung pustaka, ini memungkinkan pengguna untuk menemukan konten mereka dengan cara yang masuk akal bagi mereka saat menyajikan antarmuka pengguna yang konsisten dengan pengalaman pengguna Windows 7. Pustaka juga memudahkan program Anda menemukan konten berbasis file yang disimpan di folder yang berbeda atau di komputer yang berbeda.

Topik di bagian ini menjelaskan bagaimana Anda dapat menambahkan dukungan pustaka ke program Anda dan memanfaatkan kemampuan baru yang ditawarkan pustaka. Windows 7 menyediakan beberapa dukungan ini secara default. Jika program Anda tidak mengubah kotak dialog file umum yang saat ini digunakan, program mungkin memerlukan sedikit pemrograman tambahan untuk mendukung pustaka.

Bagian ini menjelaskan beberapa fitur utama yang disediakan pustaka dan cara mendukungnya dalam program Anda. Dengan informasi ini, Anda dapat memutuskan fitur mana yang akan memberikan pengalaman pengguna terbaik dari program Anda. Jika program Anda mengkustomisasi kotak dialog file umum, informasi di bagian ini dapat membantu Anda menentukan cara menggunakan kotak dialog file umum baru untuk menggunakan pustaka dan menyediakan fungsionalitas yang setara di Windows 7.

Pemrograman dengan Pustaka

Model pemrograman Windows Shell menjelaskan bagaimana program berinteraksi dengan objek pemrograman Windows Shell. Sementara objek sistem file, seperti file dan direktori, diwakili oleh objek Windows Shell, tidak semua objek Windows Shell diwakili oleh sistem file. Pustaka, misalnya, adalah objek Windows Shell yang tidak memiliki sistem file yang setara. Menggunakan objek Windows Shell dalam program Anda memungkinkan program Anda mengakses semua objek Shell dan bukan hanya objek sistem file.

Untuk hasil terbaik, program Anda akan menggunakan Shell Library API untuk berinteraksi dengan pustaka dan mengakses kontennya. Meskipun pustaka berisi item sistem file seperti folder dan file, pustaka bukan item sistem file. Dengan demikian, API sistem file tidak dapat digunakan untuk mengakses fitur pustaka atau konten pustaka.

Jika Anda memiliki program yang saat ini menggunakan banyak API sistem file, program Anda masih dapat memanfaatkan fitur pustaka. Shell Library API dapat memberikan referensi sistem file ke item yang ditemukan di pustaka dan referensi sistem file ini, seperti nama dan jalur file, dapat diteruskan ke API sistem file yang ada yang ada dalam program Anda yang ada.

Berpindah dari Folder yang Dikenal ke Pustaka

Sebelum Windows 7, biasanya menggunakan folder yang diketahui, seperti folder Dokumen Saya, sebagai folder default dalam operasi penyimpanan file atau buka file. Di Windows 7, pustaka yang sesuai harus digunakan sehingga pengguna akan memiliki pengalaman yang sama dalam program Anda seperti yang mereka lakukan dengan program Windows 7 lainnya, seperti Windows Explorer.

Jika saat ini Anda menggunakan Windows Shell API dalam program Anda, menambahkan dukungan pustaka sangat mudah. Misalnya, jika saat ini Anda memanggil fungsiSHGetKnownFolderItem untuk mendapatkan lokasi folder Dokumen Saya, Anda dapat mengganti nilai KNOWNFOLDERID folder Dokumen Saya yang diketahui dengan nilai KNOWNFOLDERID pustaka yang sesuai.

Tabel berikut ini memperlihatkan hubungan antara nilai KNOWNFOLDERID folder yang dikenal dan nilai KNOWNFOLDERID pustaka terkait di Windows 7.

Nilai KNOWNFOLDERID Folder yang diketahui Nilai KNOWNFOLDERID untuk Pustaka
FOLDERID_Documents FOLDERID_DocumentsLibrary
FOLDERID_Foto FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_MusicLibrary
FOLDERID_RecordedTV Perpustakaan TV Tercatat (FOLDERID_RecordedTVLibrary)

 

Grup Rumah dan pustaka bersama

Menambahkan dukungan perpustakaan ke dalam program Anda akan memungkinkan dukungan untuk perpustakaan bersama di HomeGroup. HomeGroup diidentifikasi oleh nilai KNOWNFOLDERID dari FOLDERID_HomeGroup. Program Anda dapat menemukan lokasi penyimpanan default pribadi atau bersama pengguna dengan mengatur nilaiDEFAULTSAVEFOLDERTYPEdalam panggilan ke IShellLibrary::GetDefaultSaveFolder metode.

Menggunakan kotak dialog file umum dengan pustaka

Menggunakan kotak dialog file umum dengan pustaka Kotak dialog file umum telah diperbarui untuk mendukung pustaka di Windows 7. Ilustrasi berikut menunjukkan bagaimana kotak dialog file umum muncul untuk pengguna di Windows 7.

cuplikan layar kotak dialog file umum yang memperlihatkan pustaka

Di Windows 7, jika program Anda saat ini menampilkan kotak dialog file umum dan tidak mengubah templat kotak dialog atau menghubungkan salah satu peristiwanya, itu akan menampilkan versi Windows 7 baru dari kotak dialog secara otomatis. Secara khusus, dalam fungsi kotak dialog panggilan ke file umum, lpfnHook, hInstance, lpTemplatename anggota strukturOPENFILENAMEharus NULL dan bendera OFN_ENABLEHOOK dan OFN_ENABLETEMPLATE harus jelas.

Di Windows 7, antarmuka IFileDialog-related menggantikan fungsi kotak dialog file umum yang digunakan di versi Windows sebelumnya. Fungsi kotak dialog file umum sebelumnya masih didukung di Windows 7 tetapi tidak memberikan pengalaman pengguna Windows 7 lengkap dan tidak mendukung pustaka. Beberapa fitur baru yang didukung oleh antarmuka terkait IFileDialog meliputi:

  • Pengguna dapat mengakses properti file yang didukung oleh Windows 7 Windows Explorer untuk mencari dan memilih file.
  • Program ini dapat menggunakan antarmuka dan metode dari API namespace Shell untuk bekerja dengan item.
  • Program ini dapat menggunakan model kustomisasi berbasis data alih-alih model kustomisasi berbasis file sumber daya untuk menambahkan kontrol baru ke kotak dialog file umum.

Anda harus menggunakan antarmuka IFileDialogsaat:

  • Anda perlu menyesuaikan kotak dialog file umum untuk program Anda di Windows 7. Ini akan memungkinkan program Anda bekerja dengan pustaka dan mendukung penyesuaian kotak dialog Anda.
  • Anda ingin pengguna dapat memilih beberapa file dari kotak dialog file umum. Ini akan memastikan Anda mendapatkan jalur yang benar ke objek yang dipilih karena pustaka dapat memiliki konten yang disimpan di folder yang berbeda.

Untuk informasi selengkapnya tentang antarmuka terkait IFileDialog , lihat:

Mengaktifkan pilihan pustaka dari antarmuka pengguna

Jika program Anda memungkinkan pengguna untuk memilih folder, seperti untuk fungsi impor atau ekspor, di Windows 7, itu harus memungkinkan pengguna untuk memilih pustaka juga. AntarmukaIFileOpenDialog dan fungsiSHBrowseForFolder memungkinkan pengguna untuk memilih pustaka saat diminta untuk memilih folder. Antarmuka IFileOpenDialog lebih disukai daripada fungsi SHBrowseForFolder karena IFileOpenDialog mendukung antarmuka pengguna Windows 7.

Untuk mengizinkan pengguna memilih folder saat menggunakan antarmukaIFileOpenDialog, panggil SetOptions dengan set bendera FOS_PICKFOLDERS dan pastikan bendera FOS_FORCEFILESYSTEM jelas.

FILEOPENDIALOGOPTIONS fileOptions;

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

Untuk memungkinkan pengguna memilih folder saat memanggil fungsi SHBrowseForFolder, pada anggota ulFlags dalam struktur BROWSEINFO, tetapkan bendera BIF_USENEWUI dan kosongkan bendera BIF_RETURNONLYFSDIRS.

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

Mengakses isi pustaka dalam program

Untuk mengakses konten pustaka, Anda harus menggunakan Windows Shell API. Fungsi API sistem file tidak dapat digunakan untuk mengakses konten pustaka karena pustaka bukan objek sistem file. Jika program Anda menggunakan browser file kustom yang didasarkan pada API sistem file, program tidak akan dapat menelusuri pustaka atau mengakses konten pustaka.

Bagian ini menjelaskan cara mengakses konten pustaka sehingga Anda bisa memilih cara terbaik untuk memperbarui program agar berfungsi dengan pustaka.

Mengakses konten pustaka dengan antarmuka IShellLibrary

Cara term mudah bagi program untuk mengakses konten pustaka adalah dengan menggunakan Shell Library API. Jika Anda mengerjakan program yang menggunakan API sistem berkas, Shell Library API dapat mengembalikan lokasi folder sistem berkas dalam pustaka, sehingga meminimalkan perubahan pada kode program yang ada.

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

Mengakses konten pustaka dengan API Shell

Karena objek pustaka adalah bagian dari model pemrograman Shell, objek tersebut dapat digunakan dengan API Windows Shell lainnya. Misalnya Anda dapat menggunakanIShellItemdan antarmukaIShellFolderdalam program Anda, bersama dengan fungsi pembantu terkait, untuk mengakses konten pustaka dengan cara yang sama seperti Anda akan menghitung folder dan konten folder untuk mengakses konten dengan API sistem file.

API Windows Shell mendukung dua mode enumerasi untuk mengakses konten pustaka:

  • Telusuri penghitungan

    Enumerasi penelusuran adalah mode enumerasi default dan mengenumerasi konten folder pustaka. Hapus bendera SHCONTF_NAVIGATION_ENUM untuk menggunakan mode ini.

  • enumerasi Navigasi

    Enumerasi navigasi menghitung folder pustaka. Atur bendera SHCONTF_NAVIGATION_ENUM untuk menggunakan mode ini.

Jika program Anda menggunakan kontrol pohon kustom untuk menavigasi folder pengguna, menghitung folder dalam mode enumerasi navigasi akan memberi Anda daftar folder pustaka yang konsisten dengan bagaimana Windows Explorer menghitung folder di Windows 7.

Untuk contoh cara menggunakan fitur ini dalam program, lihat sampel ShellStorage di Windows SDK.

Menyimpan konten pengguna di pustaka

Program Anda bisa menyimpan isi pengguna ke pustaka serta ke folder dalam pustaka. Demikian juga, pengguna dapat menyimpan ke folder tertentu di pustaka atau mereka hanya dapat menyimpan ke pustaka.

Setiap pustaka memiliki folder yang ditetapkan sebagai lokasi penyimpanan default. Lokasi penyimpanan default ditentukan saat pustaka dibuat; namun, pengguna dapat menetapkan ulang lokasi penyimpanan default menjadi folder apa pun di pustaka. Meskipun pengguna tidak perlu mengonfigurasi lokasi penyimpanan default, mereka memiliki opsi untuk mengubahnya. Jika pengguna menghapus folder yang saat ini ditetapkan sebagai lokasi penyimpanan default, pustaka akan secara otomatis mengonfigurasi folder berikutnya di pustaka untuk menjadi lokasi penyimpanan default.

Ada beberapa cara untuk menyimpan konten pengguna ke pustaka.

  • Shell API

    Jika Anda menggunakan model pemrograman Shell dan menyimpan item Shell, seperti yang diwakili oleh IShellItem, IStorage, atau IStream, ke objek pustaka, item Shell akan secara otomatis disimpan di lokasi penyimpanan default pustaka.

  • API sistem file

    Jika Anda memiliki program yang sudah ada yang menggunakan banyak panggilan API sistem file, Anda bisa mendapatkan jalur ke folder yang didefinisikan sebagai lokasi penyimpanan default pustaka. Jalur folder kemudian dapat diteruskan ke API sistem file.

Untuk contoh cara menggunakan fitur ini dalam program, lihat sampel ShellStorage di Windows SDK.

Mendukung operasi seret dan letakkan di pustaka

Jika program Anda mendukung tindakan seret dan letakkan, tindakan tersebut harus diperbarui untuk mendukung interaksi perpustakaan yang sesuai. Jika file dihilangkan ke pustaka, file yang dihilangkan harus disimpan di lokasi penyimpanan default. Jika folder dijatuhkan ke pustaka, folder yang dijatuhkan harus ditambahkan sebagai folder baru ke pustaka. Jika file dihilangkan ke folder yang sudah ada yang bukan lokasi penyimpanan default, file harus ditambahkan ke folder yang dipilih.

Untuk contoh cara menambahkan dukungan terhadap pustaka untuk fungsionalitas seret dan letakkan pada program Anda, lihat sampel ShellLibraryCommandLine di Windows SDK.

Menjaga sinkronisasi dengan perpustakaan

Topik ini menjelaskan bagaimana program dapat menyimpan tampilan konten pustaka up-to-date.

Pembaruan Sekaligus

Karena pengguna dapat mengubah folder pustaka secara interaktif ketika program Anda tidak berjalan, program Anda harus memanggil SHResolveLibrary ketika mulai menemukan dan menyimpan perubahan apa pun ke pustaka. Shell API menyediakan fungsi SHResolveLibrary untuk memungkinkan program mendapatkan konten pustaka saat ini dan lokasi folder mana pun yang mungkin dimiliki pustaka.

Perhatikan bahwa SHResolveLibrary adalah fungsi pemblokiran yang dapat memakan waktu lama untuk dikembalikan tergantung pada apa yang telah berubah di pustaka. Dengan demikian, ini tidak boleh dipanggil dari utas UI.

Setelah program dibawa up-to-date, program kemudian dapat mendaftar untuk pemberitahuan perubahan untuk mempertahankan tampilan saat ini.

Pemberitahuan API Shell

Windows Shell API menyediakan fungsi SHChangeNotifyRegister, yang merupakan cara yang diutamakan bagi proses non-layanan untuk diberi tahu tentang perubahan di perpustakaan.

Untuk mendeteksi perubahan pada item dalam pustaka menggunakan Windows Shell API, panggil SHChangeNotifyRegister mendaftarkan program Anda untuk pemberitahuan perubahan pada item di folder pustaka. Fungsi ini dapat memberi tahu program Anda jika ada perubahan pada pustaka apa pun atau hanya di pustaka tertentu. Pemberitahuan segera dikirim saat pustaka diubah.

Pemberitahuan API sistem file

Pemberitahuan sistem file harus digunakan dalam proses layanan.

Untuk mendeteksi perubahan pada item di pustaka menggunakan API sistem file, hitung folder di pustaka dan panggil FindFirstChangeNotification untuk setiap folder untuk dipantau. Program Anda akan menerima pemberitahuan ketika folder yang dipantau berubah. Untuk menemukan file file tertentu yang diubah di folder, panggil ReadDirectoryChangesW. Untuk mendeteksi perubahan dalam file deskripsi pustaka, pantau folder yang berisinya. File deskripsi pustaka dapat ditemukan di folder FOLDERID_Libraries. Namun, file deskripsi pustaka tidak boleh dibuka atau dimodifikasi.

Tentang Pustaka

IShellLibrary

Shell Links

Folder yang Diketahui

Skema Deskripsi Pustaka

IID_PPV_ARGS