Metode IWbemLocator::ConnectServer (wbemcli.h)

Artikel
08/27/2023

Metode IWbemLocator::ConnectServer membuat koneksi melalui DCOM ke namespace WMI pada komputer yang ditentukan dalam parameter strNetworkResource .

SWbemLocator.ConnectServer dapat terhubung dengan komputer yang menjalankan IPv6 menggunakan alamat IPv6 di parameter strNetworkResource . Untuk informasi selengkapnya, lihat Dukungan IPv6 dan IPv4 di WMI.

Sintaks

HRESULT ConnectServer(
  [in]  const BSTR    strNetworkResource,
  [in]  const BSTR    strUser,
  [in]  const BSTR    strPassword,
  [in]  const BSTR    strLocale,
  [in]  long          lSecurityFlags,
  [in]  const BSTR    strAuthority,
  [in]  IWbemContext  *pCtx,
  [out] IWbemServices **ppNamespace
);

Parameter

[in] strNetworkResource

Penunjuk ke BSTR valid yang berisi jalur objek namespace WMI yang benar. Untuk akses lokal ke namespace default, gunakan jalur objek sederhana: "root\default" atau "\.\root\default". Untuk akses ke namespace layanan default pada komputer jarak jauh menggunakan jaringan yang kompatibel dengan COM atau Microsoft, sertakan nama komputer: "\myserver\root\default". Untuk informasi selengkapnya, lihat Menjelaskan Jalur Objek Namespace WMI. Nama komputer juga bisa menjadi nama DNS atau alamat IP. Dimulai dengan Windows Vista, SWbemLocator.ConnectServer dapat terhubung dengan komputer yang menjalankan IPv6 menggunakan alamat IPv6. Untuk informasi selengkapnya, lihat Dukungan IPv6 dan IPv4 di WMI.

[in] strUser

Penunjuk ke BSTR yang valid, yang berisi nama pengguna yang Anda butuhkan untuk koneksi. Nilai NULL menunjukkan konteks keamanan saat ini. Jika nama pengguna berasal dari domain yang berbeda dari domain saat ini, string mungkin berisi nama domain dan nama pengguna yang dipisahkan oleh garis miring terbelakang.

StrUserName = SysAllocString(L"Domain\UserName");

Parameter strUser tidak boleh berupa string kosong. Perhatikan bahwa jika domain ditentukan dalam strAuthority, maka domain tersebut tidak boleh ditentukan di sini. Menentukan domain di kedua parameter menghasilkan kesalahan parameter yang tidak valid.

Anda dapat menggunakan format nama prinsipal pengguna (UPN), yang Username@DomainName untuk menentukan strUser.

[in] strPassword

Penunjuk ke BSTR valid yang berisi kata sandi yang Anda butuhkan untuk koneksi. Nilai NULL menunjukkan konteks keamanan saat ini. String kosong "" menentukan kata sandi panjang nol yang valid.

[in] strLocale

Jika NULL, lokal saat ini digunakan. Jika bukan NULL, parameter ini harus BSTR yang valid, yang menunjukkan lokal yang benar untuk pengambilan informasi. Untuk pengidentifikasi lokal Microsoft, format string adalah "MS_xxx", di mana xxx adalah string dalam bentuk heksadesimal yang menunjukkan Identifikasi Lokal (LCID), misalnya, bahasa Inggris Amerika akan muncul sebagai "MS_409". Jika lokal yang tidak valid ditentukan, maka metode mengembalikan WBEM_E_INVALID_PARAMETER.

Windows 7: Jika lokal yang tidak valid ditentukan, maka lokal default server digunakan kecuali ada lokal yang didukung server yang disediakan oleh aplikasi pengguna.

[in] lSecurityFlags

Nilai panjang digunakan untuk meneruskan nilai bendera ke ConnectServer. Nilai nol (0) untuk parameter ini menghasilkan panggilan ke ConnectServer yang hanya kembali setelah koneksi ke server dibuat. Hal ini dapat mengakibatkan program Anda berhenti merespons tanpa batas waktu jika server rusak. Daftar berikut mencantumkan nilai valid lainnya untuk lSecurityFlags.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Dicadangkan untuk penggunaan internal. Jangan gunakan.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

Panggilan ConnectServer kembali dalam 2 menit atau kurang. Gunakan bendera ini untuk mencegah program Anda berhenti merespons tanpa batas waktu jika server rusak.

[in] strAuthority

Parameter ini berisi nama domain pengguna untuk diautentikasi.

strAuthority dapat memiliki nilai berikut:

kosong
Jika Anda membiarkan parameter ini kosong, autentikasi NTLM digunakan dan domain NTLM pengguna saat ini digunakan. Jika domain ditentukan dalam strUser, yang merupakan lokasi yang direkomendasikan, maka domain tersebut tidak boleh ditentukan di sini. Menentukan domain di kedua parameter menghasilkan kesalahan parameter yang tidak valid.
Kerberos:<nama utama>
Autentikasi Kerberos digunakan dan parameter ini harus berisi nama utama Kerberos.
NTLMDOMAIN:<nama domain>
Autentikasi NT LAN Manager digunakan dan parameter ini harus berisi nama domain NTLM.

[in] pCtx

Biasanya, ini ADALAH NULL. Jika tidak, ini adalah penunjuk ke objek IWbemContext yang diperlukan oleh satu atau beberapa penyedia kelas dinamis. Nilai dalam objek konteks harus ditentukan dalam dokumentasi untuk penyedia yang bersangkutan. Untuk informasi selengkapnya tentang parameter ini, lihat Melakukan Panggilan ke WMI.

[out] ppNamespace

Menerima penunjuk ke objek IWbemServices yang terikat ke namespace yang ditentukan. Pointer ini memiliki jumlah referensi positif. Penelepon harus memanggil IWbemServices::Release pada pointer ketika tidak lagi diperlukan. Penunjuk ini diatur untuk menunjuk ke NULL ketika ada kesalahan.

Mengembalikan nilai

Metode ini mengembalikan HRESULT yang menunjukkan status panggilan metode. Daftar berikut mencantumkan nilai yang terkandung dalam HRESULT.

Kode kesalahan khusus COM dapat dikembalikan jika masalah jaringan menyebabkan Anda kehilangan koneksi jarak jauh ke WMI.

Kode pengembalian kesalahan ini didefinisikan dalam file Wbemcli.h di bagian WMI dari direktori PSDK \Include. Untuk informasi selengkapnya, lihat Konstanta Kesalahan WMI.

Keterangan

Jangan tentukan strUser, strPassword, atau strAuthority saat membuat koneksi ke namespace lokal. Untuk informasi selengkapnya, lihat Menyambungkan ke WMI di Komputer Jarak Jauh.

Untuk informasi selengkapnya tentang cara menggunakan ConnectServer, lihat Membuat Koneksi ke Namespace WMI. Perhatikan bahwa koneksi ke IWbemLocator adalah salah satu koneksi yang harus Anda matikan di akhir aplikasi Anda, seperti yang dijelaskan dalam Membersihkan dan Mematikan Aplikasi WMI.

Contoh

Untuk beberapa sampel yang menggunakan metode ConnectServer , lihat Contoh Aplikasi WMI C++.

Sampel kode C++ berikut menjelaskan cara menggunakan smi2smir.xml untuk menyambungkan ke namespace tertentu.

int _tmain(int argc, _TCHAR* argv[]) 
{ 
    // Initialize COM. ------------------------------------------ 
    HRESULT hres = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED); 
    if (FAILED(hres)) 
    { 
        wcout << "CoInitializeEx() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Obtain the initial locator to Windows Management 
    // on a particular host computer. 
    IWbemLocator *pLoc = NULL; 
    hres = CoCreateInstance(CLSID_WbemLocator, 0, CLSCTX_INPROC_SERVER,IID_IWbemLocator, (LPVOID *)&pLoc); 
    if (FAILED(hres)) 
    { 
        CoUninitialize(); 
        wcout << "CreateInstance failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Connect to WMI through the IWbemLocator::ConnectServer method 
    // Connect to the local ROOT\CIMV2 namespace 
    // and obtain pointer pSvc to make IWbemServices calls. 
    IWbemServices *pSvc = NULL;
    BSTR namespace = SysAllocString(L"ROOT\\CimV2");
    hres = pLoc->ConnectServer(namespace, NULL, NULL, 0, NULL, 0, 0, &pSvc);
    SysFreeString(namespace);
 
    if (FAILED(hres)) 
    { 
        pLoc->Release(); 
        CoUninitialize(); 
        wcout << "ConnectServer() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
    ...
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Server minimum yang didukung	Windows Server 2008
Target Platform	Windows
Header	wbemcli.h (termasuk Wbemidl.h)
Pustaka	Wbemuuid.lib
DLL	Wbemcore.dll