Fungsi DoEnvironmentSubstA (shellapi.h)

Artikel
03/15/2023

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

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

Sintaks

DWORD DoEnvironmentSubstA(
  [in, out] LPSTR 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 formulir berikut. Kasus diabaikan.

%VariableName%

Karakter apa pun 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 pas di buffer, TRUE dikembalikan dalam HIWORD dan panjangnya, dalam karakter, pszSrc baru dikembalikan dalam LOWORD.

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

Keterangan

Parameter harus berisi nilai non-NULL yang valid. 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 menahan versi string yang diperluas. Ukuran buffer cchSrc yang dialokasikan untuk string ANSI harus satu lebih besar dari buffer untuk string Unicode. Saat berhadapan dengan string ANSI, gunakan ukuran buffer rumus = panjang string + mengakhiri karakter null + 1 untuk menentukan ukuran buffer minimum yang benar.

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

ALLUSERSPROFILE
APPDATA
COMPUTERNAME
LOCALAPPDATA
NUMBER_OF_PROCESSORS
OS
PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER
PROCESSOR_LEVEL
PROCESSOR_REVISION
ProgramData
ProgramFiles
PUBLIC
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 atau KNOWNFOLDERID yang setara 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;
}

Catatan

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

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	shellapi.h
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 4.0 atau yang lebih baru)

Bagikan melalui