Fungsi DsGetDcNameA (dsgetdc.h)
Fungsi DsGetDcName mengembalikan nama pengendali domain dalam domain tertentu. Fungsi ini menerima kriteria pemilihan pengendali domain tambahan untuk menunjukkan preferensi pengontrol domain dengan karakteristik tertentu.
Sintaks
DSGETDCAPI DWORD DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *DomainControllerInfo
);
Parameter
[in] ComputerName
Penunjuk ke string yang dihentikan null yang menentukan nama server untuk memproses fungsi ini. Biasanya, parameter ini adalah NULL, yang menunjukkan bahwa komputer lokal digunakan.
[in] DomainName
Penunjuk ke string yang dihentikan null yang menentukan nama domain atau partisi aplikasi untuk dikueri. Nama ini bisa berupa nama gaya DNS, misalnya, fabrikam.com, atau nama gaya datar, misalnya, Fabrikam. Jika nama gaya DNS ditentukan, nama dapat ditentukan dengan atau tanpa periode berikutnya.
Jika parameter Bendera berisi bendera DS_GC_SERVER_REQUIRED , DomainName harus menjadi nama forest. Dalam hal ini, DsGetDcName gagal jika DomainName menentukan nama yang bukan akar forest.
Jika parameter Bendera berisi bendera DS_GC_SERVER_REQUIRED dan DomainName adalah NULL, DsGetDcName mencoba menemukan katalog global di forest komputer yang diidentifikasi oleh ComputerName, yang merupakan komputer lokal jika ComputerName adalah NULL.
Jika DomainNameadalah NULL dan parameter Bendera tidak berisi bendera DS_GC_SERVER_REQUIRED , ComputerName diatur ke nama domain default domain utama komputer yang diidentifikasi oleh ComputerName.
[in] DomainGuid
Penunjuk ke struktur GUID yang menentukan GUID domain yang dikueri. Jika DomainGuid bukan NULL dan domain yang ditentukan oleh DomainName atau ComputerName tidak dapat ditemukan, DsGetDcName mencoba menemukan pengendali domain di domain yang memiliki GUID yang ditentukan oleh DomainGuid.
[in] SiteName
Penunjuk ke string yang dihentikan null yang menentukan nama situs tempat pengendali domain yang dikembalikan harus ada secara fisik. Jika parameter ini ADALAH NULL, DsGetDcName mencoba mengembalikan pengendali domain di situs yang paling dekat dengan situs komputer yang ditentukan oleh ComputerName. Parameter ini harus NULL, secara default.
[in] Flags
Berisi sekumpulan bendera yang menyediakan data tambahan yang digunakan untuk memproses permintaan. Parameter ini bisa menjadi kombinasi dari nilai berikut.
DS_AVOID_SELF
Ketika dipanggil dari pengendali domain, menentukan bahwa nama pengendali domain yang dikembalikan tidak boleh menjadi komputer saat ini. Jika komputer saat ini bukan pengendali domain, bendera ini diabaikan. Bendera ini dapat digunakan untuk mendapatkan nama pengendali domain lain di domain.
DS_BACKGROUND_ONLY
Jika bendera DS_FORCE_REDISCOVERY tidak ditentukan, fungsi ini menggunakan data pengontrol domain yang di-cache. Jika data yang di-cache berusia lebih dari 15 menit, cache di-refresh dengan ping pengontrol domain. Jika bendera ini ditentukan, refresh ini dihindari meskipun data yang di-cache kedaluwarsa. Bendera ini harus digunakan jika fungsi DsGetDcName dipanggil secara berkala.
DS_DIRECTORY_SERVICE_PREFERRED
DsGetDcName mencoba menemukan pengendali domain yang mendukung fungsi layanan direktori. Jika pengendali domain yang mendukung layanan direktori tidak tersedia, DsGetDcName mengembalikan nama pengendali domain layanan non-direktori. Namun, DsGetDcName hanya mengembalikan pengontrol domain layanan non-direktori setelah upaya untuk menemukan pengontrol domain layanan direktori kehabisan waktu.
DS_DIRECTORY_SERVICE_REQUIRED
Mengharuskan pengontrol domain yang dikembalikan mendukung layanan direktori.
DS_DIRECTORY_SERVICE_6_REQUIRED
Mengharuskan pengendali domain yang dikembalikan menjalankan Windows Server 2008 atau yang lebih baru.
DS_DIRECTORY_SERVICE_8_REQUIRED
Mengharuskan pengendali domain yang dikembalikan menjalankan Windows Server 2012 atau yang lebih baru.
DS_FORCE_REDISCOVERY
Memaksa data pengontrol domain yang di-cache untuk diabaikan. Ketika bendera DS_FORCE_REDISCOVERY tidak ditentukan, DsGetDcName dapat mengembalikan data pengontrol domain yang di-cache. Jika bendera ini ditentukan, DsGetDcName tidak akan menggunakan informasi yang di-cache (jika ada) tetapi sebaliknya akan melakukan penemuan pengontrol domain baru.
Bendera ini tidak boleh digunakan dalam kondisi normal, karena menggunakan informasi pengontrol domain yang di-cache memiliki karakteristik performa yang lebih baik dan membantu memastikan bahwa pengendali domain yang sama digunakan secara konsisten oleh semua aplikasi. Bendera ini harus digunakan hanya setelah aplikasi menentukan bahwa pengendali domain yang dikembalikan oleh DsGetDcName (ketika dipanggil tanpa bendera ini) tidak dapat diakses. Dalam hal ini, aplikasi harus mengulangi panggilan DsGetDcName dengan bendera ini untuk memastikan bahwa informasi cache yang tidak digunakan (jika ada) diabaikan dan pengontrol domain yang dapat dijangkau ditemukan.
DS_GC_SERVER_REQUIRED
Mengharuskan pengendali domain yang dikembalikan menjadi server katalog global untuk forest domain dengan domain ini sebagai akar. Jika bendera ini diatur dan parameter DomainName bukan NULL, DomainName harus menentukan nama forest. Bendera ini tidak dapat digabungkan dengan bendera DS_PDC_REQUIRED atau DS_KDC_REQUIRED .
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName mencoba menemukan pengendali domain yang merupakan server waktu yang andal. Layanan Waktu Windows dapat dikonfigurasi untuk mendeklarasikan satu atau beberapa pengendali domain sebagai server waktu yang dapat diandalkan. Untuk informasi selengkapnya, lihat dokumentasi Layanan Waktu Windows . Bendera ini hanya dimaksudkan untuk digunakan oleh Layanan Waktu Windows.
DS_IP_REQUIRED
Parameter ini menunjukkan bahwa pengendali domain harus memiliki alamat IP. Dalam hal ini, DsGetDcName akan menempatkan alamat protokol Internet pengendali domain di anggota DomainControllerAddress dari DomainControllerInfo.
DS_IS_DNS_NAME
Menentukan bahwa parameter DomainName adalah nama DNS. Bendera ini tidak dapat digabungkan dengan bendera DS_IS_FLAT_NAME .
Tentukan DS_IS_DNS_NAME atau DS_IS_FLAT_NAME. Jika tidak ada bendera yang ditentukan, DsGetDcName mungkin membutuhkan waktu lebih lama untuk menemukan pengendali domain karena mungkin harus mencari gaya DNS dan nama datar.
DS_IS_FLAT_NAME
Menentukan bahwa parameter DomainName adalah nama datar. Bendera ini tidak dapat digabungkan dengan bendera DS_IS_DNS_NAME .
DS_KDC_REQUIRED
Mengharuskan pengendali domain yang dikembalikan saat ini menjalankan layanan Pusat Distribusi Kunci Kerberos. Bendera ini tidak dapat digabungkan dengan bendera DS_PDC_REQUIRED atau DS_GC_SERVER_REQUIRED .
DS_ONLY_LDAP_NEEDED
Menentukan bahwa server yang dikembalikan adalah server LDAP. Server yang dikembalikan belum tentu merupakan pengendali domain. Tidak ada layanan lain yang tersirat untuk hadir di server. Server yang dikembalikan tidak selalu memiliki kontainer konfigurasi bisa-tulis atau kontainer skema bisa-tulis. Server yang dikembalikan mungkin belum tentu digunakan untuk membuat atau memodifikasi prinsip keamanan. Bendera ini dapat digunakan dengan bendera DS_GC_SERVER_REQUIRED untuk mengembalikan server LDAP yang juga menghosting server katalog global. Server katalog global yang dikembalikan belum tentu merupakan pengendali domain. Tidak ada layanan lain yang tersirat untuk hadir di server. Jika bendera ini ditentukan, bendera DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED, dan DS_KDC_REQUIRED diabaikan.
DS_PDC_REQUIRED
Mengharuskan pengendali domain yang dikembalikan menjadi pengendali domain utama untuk domain tersebut. Bendera ini tidak dapat digabungkan dengan bendera DS_KDC_REQUIRED atau DS_GC_SERVER_REQUIRED .
DS_RETURN_DNS_NAME
Menentukan bahwa nama yang dikembalikan di anggota DomainControllerName dan DomainNamedomainControllerInfo harus berupa nama DNS. Jika nama DNS tidak tersedia, kesalahan akan ditampilkan. Bendera ini tidak dapat ditentukan dengan bendera DS_RETURN_FLAT_NAME . Bendera ini menyiratkan bendera DS_IP_REQUIRED .
DS_RETURN_FLAT_NAME
Menentukan bahwa nama yang dikembalikan di anggota DomainControllerName dan DomainNamedomainControllerInfo harus berupa nama datar. Jika nama datar tidak tersedia, kesalahan akan dikembalikan. Bendera ini tidak dapat ditentukan dengan bendera DS_RETURN_DNS_NAME .
DS_TIMESERV_REQUIRED
Mengharuskan pengendali domain yang dikembalikan saat ini menjalankan Layanan Waktu Windows.
DS_TRY_NEXTCLOSEST_SITE
Ketika bendera ini ditentukan, DsGetDcName mencoba menemukan pengendali domain di situs yang sama dengan pemanggil. Jika tidak ada pengendali domain yang ditemukan, pengontrol domain yang dapat memberikan informasi topologi dan memanggil DsBindToISTG untuk mendapatkan handel ikat, lalu panggil DsQuerySitesByCost melalui UDP untuk menentukan "situs terdekat berikutnya," dan akhirnya cache nama situs yang ditemukan. Jika tidak ada pengendali domain yang ditemukan di situs tersebut, maka DsGetDcName kembali ke metode default untuk menemukan pengendali domain.
Jika bendera ini digunakan bersama dengan nilai non-NULL dalam parameter input SiteName, maka ERROR_INVALID_FLAGS dilemparkan.
Selain itu, jenis pencarian yang digunakan dengan DS_TRY_NEXT_CLOSEST_SITE khusus situs, sehingga bendera ini diabaikan jika digunakan bersama dengan DS_PDC_REQUIRED. Akhirnya, DS_TRY_NEXTCLOSEST_SITE diabaikan ketika digunakan bersama dengan DS_RETURN_FLAT_NAME karena itu menggunakan NetBIOS untuk menyelesaikan nama, tetapi domain pengendali domain yang ditemukan tidak akan selalu cocok dengan domain tempat klien bergabung.
DS_WRITABLE_REQUIRED
Mengharuskan pengendali domain yang dikembalikan dapat ditulis; artinya, host salinan layanan direktori yang dapat ditulis.
DS_WEB_SERVICE_REQUIRED
Mengharuskan pengendali domain yang dikembalikan saat ini menjalankan layanan web Direktori Aktif.
[out] DomainControllerInfo
Penunjuk ke nilai PDOMAIN_CONTROLLER_INFO yang menerima penunjuk ke struktur DOMAIN_CONTROLLER_INFO yang berisi data tentang pengendali domain yang dipilih. Struktur ini dialokasikan oleh DsGetDcName. Pemanggil harus membebaskan struktur menggunakan fungsi NetApiBufferFree ketika tidak lagi diperlukan.
Mengembalikan nilai
Jika fungsi mengembalikan data pengendali domain, nilai yang dikembalikan ERROR_SUCCESS.
Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut.
Keterangan
Fungsi DsGetDcName dikirim ke layanan Netlogon pada komputer jarak jauh yang ditentukan oleh ComputerName. Jika ComputerNameNULL, fungsi diproses di komputer lokal.
DsGetDcName tidak memverifikasi bahwa nama pengendali domain yang dikembalikan adalah nama pengendali domain aktual atau katalog global. Jika autentikasi timbal balik diperlukan, pemanggil harus melakukan autentikasi.
DsGetDcName tidak memerlukan akses tertentu ke domain yang ditentukan. Secara default, fungsi ini tidak memastikan bahwa pengendali domain yang dikembalikan saat ini tersedia. Sebagai gantinya, pemanggil harus mencoba menggunakan pengendali domain yang dikembalikan. Jika pengendali domain tidak tersedia, pemanggil harus memanggil fungsi DsGetDcName lagi, menentukan bendera DS_FORCE_REDISCOVERY .
Waktu Respons
Saat menggunakan DsGetDcName , ketahui detail waktu berikut:- DsGetDcName melakukan panggilan jaringan dan dapat memakan waktu dari beberapa detik hingga satu menit, tergantung pada lalu lintas jaringan, topologi, beban DC, dan sebagainya.
- TIDAK disarankan untuk memanggil DsGetDcName dari UI atau utas kritis pengaturan waktu lainnya.
- Pencari Lokasi DC memang menggunakan logika yang dioptimalkan untuk memberikan informasi DC secepat mungkin. Ini juga menggunakan informasi cache di situs untuk menghubungi DC terdekat.
Catatan tentang Kelekatan Pengendali Domain
Dalam Active Directory Domain Services, fungsi pencari lokasi pengendali domain dirancang sehingga setelah klien menemukan pengontrol domain pilihan, klien tidak akan mencari yang lain kecuali pengendali domain tersebut berhenti merespons atau klien dimulai ulang. Ini disebut sebagai "Kelekatan Pengendali Domain." Karena stasiun kerja biasanya beroperasi selama berbulan-bulan tanpa masalah atau mulai ulang, salah satu konsekuensi yang tidak diinginkan dari perilaku ini adalah bahwa jika pengendali domain tertentu turun untuk pemeliharaan, semua klien yang terhubung ke dalamnya mengalihkan koneksi mereka ke pengontrol domain lain. Tetapi ketika pengendali domain muncul kembali, tidak ada klien yang pernah terhubung kembali ke sana karena klien tidak sering menghidupkan ulang. Hal ini dapat menyebabkan masalah penyeimbangan beban.Sebelumnya, solusi paling umum untuk masalah ini adalah menyebarkan skrip pada setiap komputer klien yang secara berkala disebut DsGetDcName menggunakan DS_FORCE_REDISCOVERY bendera . Ini adalah solusi yang agak rumit, sehingga Windows Server 2008 dan Windows Vista memperkenalkan mekanisme baru yang menyebabkan masalah dengan kelekatan pengendali domain.
Setiap kali DsGetDcName mengambil nama pengendali domain dari cache-nya, DsGetDcName memeriksa untuk melihat apakah entri cache ini kedaluwarsa, dan jika demikian, membuang nama pengendali domain tersebut dan mencoba menemukan kembali nama pengendali domain. Masa pakai entri yang di-cache dikendalikan oleh nilai dalam kunci registri berikut
\ HKEY_LOCAL_MACHINESISTEM\CurrentControlSet\Layanan\Netlogon\Parameter\ForceRediscoveryInterval
dan
\ HKEY_LOCAL_MACHINEPerangkat lunak\Kebijakan\Microsoft\Netlogon\Parameter\ForceRediscoveryInterval
Nilai dalam kunci registri ini berjenis REG_DWORD. Mereka menentukan panjang dalam detik sebelum DsGetDcName harus mencoba menemukan kembali nama pengontrol domain. Nilai defaultnya adalah 43200 detik (12 jam). Jika nilai entri registri ForceRediscoveryInterval diatur ke 0, klien selalu melakukan penemuan ulang. Jika nilai diatur ke 4294967295, cache tidak pernah kedaluwarsa, dan pengontrol domain yang di-cache terus digunakan. Kami menyarankan agar Anda tidak mengatur entri registri ForceRediscoveryInterval ke nilai yang kurang dari 3600 detik (60 menit).
Pelacakan ETW di DsGetDcName
Untuk mengaktifkan Pelacakan ETW untuk DsGetDcName, buat kunci registri berikut:\ HKEY_LOCAL_MACHINESistem\CurrentControlSet\Layanan\DCLocator\Menelusuri
Kunci akan memiliki struktur sebagai berikut:
String ProcessName
DWORD PID <optional>
ProcessName harus berupa nama lengkap termasuk ekstensi proses yang ingin Anda dapatkan informasi pelacakannya. PID hanya diperlukan ketika ada beberapa proses dengan nama yang sama. Jika ditentukan, maka hanya proses dengan PID tersebut yang akan diaktifkan untuk pelacakan. Tidak dimungkinkan untuk melacak hanya 2 dari 3 (atau lebih) proses dengan nama yang sama. Anda dapat mengaktifkan satu instans atau semua instans (ketika beberapa instans dengan nama proses yang sama ada dan PID tidak ditentukan, semua instans akan diaktifkan untuk pelacakan).
Misalnya, ini akan melacak semua instans App1.exe dan App2.exe, tetapi hanya instans App3.exe yang memiliki PID 999:
App1.exe
App2.exe
App3.exe
PID 999
Jalankan perintah berikut untuk memulai sesi pelacakan:
tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
sessionname adalah nama yang diberikan untuk sesi pelacakan. Guid untuk penyedia pelacakan DCLocator adalah "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". nama file adalah nama file log tempat peristiwa ditulis. traceFlags adalah satu atau beberapa bendera berikut yang menandakan area mana yang akan dilacak:
| Bendera | Nilai Hex | Deskripsi |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | Penelusuran kesalahan lain-lain |
| DCLOCATOR_MAILSLOT | 0x00000010 | Pesan mailslot |
| DCLOCATOR_SITE | 0x00000020 | Situs |
| DCLOCATOR_CRITICAL | 0x00000100 | Kesalahan penting |
| DCLOCATOR_SESSION_SETUP | 0x00000200 | Pemeliharaan Domain Tepercaya |
| DCLOCATOR_DNS | 0x00004000 | Pendaftaran Nama |
| DCLOCATOR_DNS_MORE | 0x00020000 | Pendaftaran Nama Verbose |
| DCLOCATOR_MAILBOX_TEXT | 0x02000000 | Pesan Kotak Surat Verbose |
| DCLOCATOR_SITE_MORE | 0x08000000 | Situs verbose |
Jalankan perintah berikut untuk menghentikan sesi pelacakan:
tracelog.exe -stop <sessionname>
sessionname adalah nama yang sama dengan nama yang Anda gunakan saat memulai sesi.
Catatan
Header dsgetdc.h mendefinisikan DsGetDcName sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor 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 Vista |
| Server minimum yang didukung | Windows Server 2008 |
| Target Platform | Windows |
| Header | dsgetdc.h |
| Pustaka | NetApi32.lib |
| DLL | NetApi32.dll |