Bagikan melalui

Fungsi DoEnvironmentSubstW (shellapi.h)

[Fungsi ini hanya dipertahankan untuk kompatibilitas mundur. Gunakan ExpandEnvironmentStrings.]

Mengurai string input yang berisi referensi ke satu atau beberapa variabel lingkungan dan menggantinya dengan nilai yang sepenuhnya diperluas.

Sintaksis

DWORD DoEnvironmentSubstW(
  [in, out] LPWSTR pszSrc,
            UINT   cchSrc
);

Parameter

[in, out] pszSrc

Jenis: LPTSTR

Penunjuk ke string yang dihentikan null yang berisi referensi ke satu atau beberapa variabel lingkungan, masing-masing dalam bentuk berikut. Kasus diabaikan.

%VariableName%

Setiap karakter dalam string yang tidak diapit dalam karakter '%' diabaikan dan dikembalikan tidak berubah. Oleh karena itu, jika string Anda berisi beberapa variabel lingkungan, Anda dapat menggunakan karakter apa pun selain '%' sebagai pemisah, termasuk spasi atau tanpa pemisah.

Ketika fungsi ini berhasil dikembalikan, setiap %VariableName% diganti dengan nilai yang diperluas. Aturan penggantian sama dengan yang digunakan oleh penerjemah perintah. Jika nama variabel tidak ditemukan pada sistem, %variableName% dibiarkan seperti yang dikirimkan pada entri.

Jika fungsi ini gagal karena string yang diperluas terlalu besar untuk buffer, konten buffer ini dibiarkan tidak berubah.

cchSrc

Jenis: UINT

Ukuran, dalam karakter, dari buffer yang ditujukkan oleh pszSrc. Perhatikan bahwa buffer harus cukup besar untuk menahan string yang dikembalikan.

Mengembalikan nilai

Jenis: DWORD

Jika string yang diperluas cocok di buffer, TRUE dikembalikan dalam HIWORD dan panjangnya, dalam karakter, baru pszSrc dikembalikan dalam LOWORD.

Jika string yang diperluas terlalu besar untuk buffer, FALSE dikembalikan dalam HIWORD dan cchSrc di LOWORD.

Komentar

Parameter harus berisi nilai NULL yang valid dan tidak. Anda harus memvalidasi nilai-nilai ini. Kegagalan untuk melakukannya dapat memberikan hasil yang tidak terduga.

Karena string yang dikembalikan dalam pszSrc biasanya akan lebih panjang dari string input, pastikan bahwa buffer cukup besar untuk menyimpan versi string yang diperluas. Ukuran yang dialokasikan dari cchSrc buffer untuk string ANSI harus satu lebih besar dari buffer untuk string Unicode. Saat berhadapan dengan string ANSI, gunakan rumus ukuran buffer = panjang string + mengakhiri karakter null + 1 untuk menentukan ukuran buffer minimum yang benar.

Karena variabel lingkungan dapat ditambahkan oleh pengguna atau aplikasi, daftar lengkapnya bergantung pada sistem. Variabel lingkungan berikut adalah standar dan tersedia untuk aplikasi dan layanan interaktif.

  • ALLUSERSPROFILE
  • APPDATA
  • NAMA KOMPUTER
  • LOCALAPPDATA
  • NUMBER_OF_PROCESSORS
  • Sistem operasi
  • PROCESSOR_ARCHITECTURE
  • PROCESSOR_IDENTIFIER
  • PROCESSOR_LEVEL
  • PROCESSOR_REVISION
  • ProgramData
  • ProgramFiles
  • UMUM
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • windir
Berikut ini hanya tersedia untuk aplikasi interaktif.
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • NAMA PENGGUNA
Variabel lingkungan yang sesuai dengan folder sistem file dapat dipetakan ke nilai CSIDL yang setara atau nilai KNOWNFOLDERID dapat diperoleh melalui SHGetFolderLocation atau SHGetKnownFolderPath. CSIDL dan KNOWNFOLDERIDs lebih dapat diandalkan daripada nama variabel lingkungan dan harus digunakan jika memungkinkan.

Contoh

Aplikasi konsol berikut menunjukkan penggunaan DoEnvironmentSubstW.


#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "shellapi.h"

int _tmain(int argc, _TCHAR* argv[])
{
	WCHAR szSrc[MAX_PATH] = L"%OS%;%HOMEPATH%";

	DWORD result = DoEnvironmentSubstW(szSrc, MAX_PATH);

	WORD success = HIWORD(result);
	WORD string_length = LOWORD(result);

	return 0;
}

Nota

Header shellapi.h mendefinisikan DoEnvironmentSubst sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosem 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

Syarat Nilai
klien minimum yang didukung Windows XP [hanya aplikasi desktop]
server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Platform Target Windows
Header shellapi.h
Pustaka Shell32.lib
DLL Shell32.dll (versi 4.0 atau yang lebih baru)
  • Last updated on