Fungsi PSFormatForDisplayAlloc (propsys.h)
Mendapatkan representasi string Unicode yang diformat dari nilai properti yang disimpan dalam struktur PROPVARIANT . Fungsi ini mengalokasikan memori untuk string output.
Sintaks
PSSTDAPI PSFormatForDisplayAlloc(
[in] REFPROPERTYKEY key,
[in] REFPROPVARIANT propvar,
[in] PROPDESC_FORMAT_FLAGS pdff,
[out] PWSTR *ppszDisplay
);
Parameter
[in] key
Jenis: REFPROPERTYKEY
Referensi ke PROPERTYKEY yang menamai properti yang nilainya sedang diambil.
[in] propvar
Jenis: REFPROPVARIANT
Referensi ke struktur PROPVARIANT yang berisi jenis dan nilai properti.
[in] pdff
Jenis: PROPDESC_FORMAT_FLAGS
Satu atau beberapa bendera yang menentukan format yang akan diterapkan ke string properti. Lihat PROPDESC_FORMAT_FLAGS untuk nilai yang mungkin.
[out] ppszDisplay
Jenis: PWSTR*
Saat fungsi kembali, berisi penunjuk ke representasi untai (karakter) Unicode yang dihentikan null dari nilai properti yang diminta.
Nilai kembali
Jenis: HRESULT
Mengembalikan salah satu nilai berikut.
Menampilkan kode | Deskripsi |
---|---|
|
String yang diformat berhasil dibuat. S_OK bersama dengan string pengembalian kosong menunjukkan bahwa ada string input kosong atau nilai tidak kosong yang diformat sebagai string kosong. |
|
String yang diformat tidak dibuat. S_FALSE bersama dengan string pengembalian kosong menunjukkan bahwa string kosong dihasilkan dari VT_EMPTY. |
|
Menunjukkan alokasi gagal. |
Keterangan
Fungsi ini memanggil implementasi subsistem skema dari IPropertySystem::FormatForDisplayAlloc. Panggilan tersebut menyediakan representasi string Unicode dari nilai properti, dengan pemformatan tambahan berdasarkan satu atau beberapa PROPDESC_FORMAT_FLAGS. Jika PROPERTYKEY tidak dikenali oleh subsistem skema, IPropertySystem::FormatForDisplayAlloc mencoba memformat nilai sesuai dengan VARTYPE nilai.
Anda harus menginisialisasi Model Objek Komponen (COM) dengan CoInitialize atau OleInitialize sebelum memanggil PSFormatForDisplayAlloc.
Fungsi ini mengalokasikan memori melalui CoTaskMemAlloc dan mengembalikan pointer ke memori tersebut melalui parameter ppszDisplay . Aplikasi panggilan harus menggunakan CoTaskMemFree untuk merilis sumber daya tersebut ketika tidak lagi diperlukan.
Tujuan dari fungsi ini adalah untuk mengonversi data menjadi string yang cocok untuk ditampilkan kepada pengguna. Nilai diformat sesuai dengan lokal saat ini, bahasa pengguna, PROPDESC_FORMAT_FLAGS, dan deskripsi properti yang ditentukan oleh kunci properti. Untuk informasi tentang bagaimana skema deskripsi properti memengaruhi pemformatan nilai, lihat topik berikut ini:
Biasanya, PROPDESC_FORMAT_FLAGS digunakan untuk memodifikasi format yang ditentukan oleh deskripsi properti.String output dapat berisi karakter arah Unicode. Karakter nonspacing ini memengaruhi algoritma dua arah Unicode sehingga nilai muncul dengan benar saat bahasa kiri-ke-kanan (LTR) digambar pada jendela kanan-ke-kiri (RTL), atau RTL digambar pada jendela LTR. Karakter-karakter ini mencakup yang berikut ini: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".
Properti berikut menggunakan format khusus dan tidak terpengaruh oleh PROPDESC_FORMAT_FLAGS. Perhatikan bahwa contoh yang dikutip adalah untuk string dengan lokal saat ini yang diatur ke bahasa Inggris; biasanya, output dilokalkan kecuali jika dicatat.
Properti | Format |
---|---|
System.FileAttributes | Atribut file berikut dikonversi menjadi huruf dan ditambahkan untuk membuat string (misalnya, nilai 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) dikonversi ke "RCO"):
|
System.Photo.ISOSpeed | Misalnya, "ISO-400". |
System.Photo.ShutterSpeed |
Nilai APEX dikonversi ke waktu pencahayaan menggunakan rumus ini:
Misalnya, "2 detik." atau "1/125 detik.". |
System.Photo.ExposureTime | Misalnya, "2 detik." atau "1/125 detik." |
System.Photo.Aperture |
Nilai APEX dikonversi ke angka F menggunakan rumus ini:
Misalnya, "f/5.6". |
System.Photo.FNumber | Misalnya, "f/5.6". |
System.Photo.SubjectDistance | Misalnya, "15 m"atau "250 mm". |
System.Photo.FocalLength | Misalnya, "50 mm". |
System.Photo.FlashEnergy | Misalnya, "500 bpcs". |
System.Photo.ExposureBias | Misalnya, "-2 langkah", " 0 langkah", atau "+3 langkah". |
System.Computer.DecoratedFreeSpace | Misalnya, "105 MB gratis 13,2 GB". |
System.ItemType | Misalnya, "Aplikasi" atau "Gambar JPEG". |
System.ControlPanel.Category | Misalnya, "Penampilan dan Personalisasi". |
System.ComputerName | Misalnya, "LITWARE05 (komputer ini)" atau "testbox07". |
Jika kunci properti tidak sesuai dengan deskripsi properti di salah satu skema properti terdaftar, maka fungsi ini memilih format berdasarkan jenis nilai.
Jenis nilai | Format |
---|---|
VT_BOOLEAN | Tidak didukung. |
VT_FILETIME | String tanggal/waktu seperti yang ditentukan oleh PROPDESC_FORMAT_FLAGS dan lokal saat ini. PDFF_SHORTTIME dan PDFF_SHORTDATE adalah default. Misalnya, "13/11/2006 15:22". |
VARTYPE Numerik | String desimal di lokal saat ini. Misalnya, "42". |
VT_LPWSTR atau lainnya | Dikonversi menjadi string. Urutan "\r", "\t", atau "\n" diganti dengan satu spasi. |
VT_VECTOR | Apa pun | Nilai yang dipisahkan titik koma. Titik koma digunakan terlepas dari lokal. |
Contoh
Contoh berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PSFormatForDisplayAlloc untuk memformat nilai peringkat.
PROPVARIANT propvar;
HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);
if (SUCCEEDED(hr))
{
PWSTR pszValue;
hr = PSFormatForDisplayAlloc(PKEY_Rating, propvar, PDFF_DEFAULT, &pszValue);
if (SUCCEEDED(hr))
{
// pszValue contains a formatted string similar to "3 stars".
CoTaskMemFree(pszValue);
}
PropVariantClear(&propvar);
}
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
Target Platform | Windows |
Header | propsys.h |
Pustaka | Propsys.lib |
DLL | Propsys.dll (versi 6.0 atau yang lebih baru) |
Redistribusi | Windows Desktop Search (WDS) 3.0 |