Fungsi MsiFormatRecordA (msiquery.h)

  • Artikel

Fungsi MsiFormatRecord memformat data bidang rekaman dan properti menggunakan string format.

Sintaks

UINT MsiFormatRecordA(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPSTR     szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

Parameter

[in] hInstall

Tangani penginstalan. Ini dapat dihilangkan, dalam hal ini hanya parameter bidang rekaman yang diproses dan properti tidak tersedia untuk penggantian.

[in] hRecord

Tangani ke rekaman untuk diformat. String templat harus disimpan di bidang rekaman 0 diikuti dengan parameter data yang direferensikan.

[out] szResultBuf

Penunjuk ke buffer yang menerima string berformat null yang dihentikan. Jangan mencoba menentukan ukuran buffer dengan meneruskan null (value=0) untuk szResultBuf. Anda bisa mendapatkan ukuran buffer dengan meneruskan string kosong (misalnya ""). Fungsi kemudian mengembalikan ERROR_MORE_DATA dan pcchResultBuf berisi ukuran buffer yang diperlukan dalam TCHARs, tidak termasuk karakter null yang mengakhiri. Saat pengembalian ERROR_SUCCESS, pcchResultBuf berisi jumlah TCHARyang ditulis ke buffer, tidak termasuk karakter null yang mengakhiri.

[in, out] pcchResultBuf

Arahkan ke variabel yang menentukan ukuran, dalam TCHARs, dari buffer yang diacu oleh variabel szResultBuf. Ketika fungsi mengembalikan ERROR_SUCCESS, variabel ini berisi ukuran data yang disalin ke szResultBuf, tidak termasuk karakter null yang mengakhiri. Jika szResultBuf tidak cukup besar, fungsi mengembalikan ERROR_MORE_DATA dan menyimpan ukuran yang diperlukan, tidak termasuk karakter null yang mengakhiri, dalam variabel yang ditunjukkan oleh pcchResultBuf.

Menampilkan nilai

Fungsi MsiFormatRecord mengembalikan salah satu nilai berikut:

Keterangan

Fungsi MsiFormatRecord menggunakan proses format berikut.

Parameter yang akan diformat diapit dalam tanda kurung siku [...]. Kurung siku dapat diulang karena substitusi diselesaikan dari dalam ke luar.

Jika bagian dari string diapit kurung kurawal { } dan tidak berisi tanda kurung siku, maka dibiarkan tidak berubah, termasuk kurung kurawal.

Jika bagian dari string diapit kurung kurawal { } dan berisi satu atau beberapa nama properti, dan jika semua properti ditemukan, teks (dengan substitusi yang diselesaikan) ditampilkan tanpa kurung kurawal. Jika salah satu properti tidak ditemukan, semua teks dalam kurung kurawal dan kurung kurawal itu sendiri akan dihapus.

Catatan dalam kasus tindakan kustom eksekusi yang ditangguhkan, MsiFormatRecord hanya mendukung properti CustomActionData dan ProductCode . Untuk informasi selengkapnya, lihat Mendapatkan Informasi Konteks untuk Tindakan Kustom Eksekusi yang Ditangguhkan.

Langkah-langkah berikut menjelaskan cara memformat string menggunakan fungsi MsiFormatRecord :

Untuk memformat string menggunakan fungsi MsiFormatRecord

  1. Parameter numerik diganti dengan mengganti penanda dengan nilai bidang rekaman terkait, dengan nilai hilang atau null tidak menghasilkan teks.
  2. String yang dihasilkan diproses dengan mengganti parameter nonrecord dengan nilai yang sesuai, dijelaskan berikutnya.
    • Jika substring formulir "[propertyname]" ditemukan, substring akan digantikan oleh nilai properti .
    • Jika substring formulir "[%environmentvariable]" ditemukan, nilai variabel lingkungan diganti.
    • Jika substring formulir" [#filekey]" ditemukan, substring digantikan oleh jalur lengkap file, dengan kunci file nilai yang digunakan sebagai kunci ke dalam tabel File. Nilai "[#filekey]" tetap kosong dan tidak digantikan oleh jalur sampai alat penginstal menjalankan tindakan CostInitialize, tindakan FileCost, dan tindakan CostFinalize. Nilai "[#filekey]" tergantung pada status penginstalan komponen tempat file berada. Jika komponen dijalankan dari sumber, nilainya adalah jalur ke lokasi sumber file. Jika komponen dijalankan secara lokal, nilainya adalah jalur ke lokasi target file setelah penginstalan. Jika komponen tidak ada, jalur kosong. Untuk informasi selengkapnya tentang memeriksa status penginstalan komponen, lihat Memeriksa Instalasi Fitur, Komponen, File.
    • Jika substring formulir "[$componentkey]" ditemukan, substring digantikan oleh direktori penginstalan komponen, dengan kunci komponen nilai yang digunakan sebagai kunci ke dalam tabel Komponen. Nilai "[$componentkey]" tetap kosong dan tidak digantikan oleh direktori sampai alat penginstal menjalankan tindakan CostInitialize, tindakan FileCost, dan tindakan CostFinalize. Nilai "[$componentkey]" tergantung pada status penginstalan komponen. Jika komponen dijalankan dari sumber, nilainya adalah direktori sumber file. Jika komponen dijalankan secara lokal, nilainya adalah direktori target setelah penginstalan. Jika komponen tidak ada, nilainya dibiarkan kosong. Untuk informasi selengkapnya tentang memeriksa status penginstalan komponen, lihat Memeriksa Instalasi Fitur, Komponen, File.
    • Perhatikan bahwa jika komponen sudah diinstal, dan tidak diinstal ulang, dihapus, atau dipindahkan selama penginstalan saat ini, status tindakan komponen null dan oleh karena itu string "[$componentkey]" mengevaluasi ke Null.
    • Jika substring formulir "[\c]" ditemukan, substring akan digantikan oleh karakter tanpa pemrosesan lebih lanjut. Hanya karakter pertama setelah garis miring terbelakang yang disimpan; segala sesuatu yang lain dihapus.
Jika ERROR_MORE_DATA dikembalikan, parameter yang merupakan penunjuk memberikan ukuran buffer yang diperlukan untuk menahan string. Jika ERROR_SUCCESS dikembalikan, maka akan memberikan jumlah karakter yang ditulis ke buffer string. Oleh karena itu Anda bisa mendapatkan ukuran buffer dengan meneruskan string kosong (misalnya "") untuk parameter yang menentukan buffer. Jangan mencoba menentukan ukuran buffer dengan meneruskan Null (value=0).

Catatan

Header msiquery.h mendefinisikan MsiFormatRecord sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

   
Klien minimum yang didukung Windows Installer 5.0 di Windows Server 2012, Windows 8, Windows Server 2008 R2 atau Windows 7. Windows Installer 4.0 atau Windows Installer 4.5 di Windows Server 2008 atau Windows Vista.
Target Platform Windows
Header msiquery.h
Pustaka Msi.lib
DLL Msi.dll

Lihat juga

Meneruskan Null sebagai Argumen Fungsi Pemasang Windows