Fungsi DsCrackNamesW (ntdsapi.h)

Artikel
11/20/2024

Fungsi DsCrackNames mengonversi array nama objek layanan direktori dari satu format ke format lainnya. Konversi nama memungkinkan aplikasi klien memetakan antara beberapa nama yang digunakan untuk mengidentifikasi berbagai objek layanan direktori. Misalnya, objek pengguna dapat diidentifikasi dengan nama akun SAM (Domain\UserName), nama prinsipal pengguna (UserName@Domain.com), atau nama khusus.

Sintaksis

NTDSAPI DWORD DsCrackNamesW(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCWSTR    *rpNames,
  [out] PDS_NAME_RESULTW *ppResult
);

Parameter

[in] hDS

Berisi handel layanan direktori yang diperoleh dari DSBind atau fungsi DSBindWithCred. Jika bendera berisi DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS dapat null.

[in] flags

Berisi satu atau beberapa nilai DS_NAME_FLAGS yang digunakan untuk menentukan bagaimana sintaks nama akan diretak.

[in] formatOffered

Berisi salah satu nilai DS_NAME_FORMAT yang mengidentifikasi format nama input.

Nilai DS_LIST_NCS juga dapat diteruskan untuk parameter ini. Hal ini menyebabkan DsCrackNames mengembalikan nama khusus dari semua konteks penamaan di forest saat ini. Parameter formatDesired diabaikan. cName harus setidaknya satu dan semua string dalam rpName harus memiliki panjang yang lebih besar dari nol karakter. Konten rpNames diabaikan.

CatatanDS_LIST_NCS tidak ditentukan dalam file header yang diterbitkan. Untuk menggunakan nilai ini, tentukan dalam format yang tepat yang ditunjukkan di bawah ini.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Berisi salah satu nilai DS_NAME_FORMAT yang mengidentifikasi format nama output. Nilai DS_SID_OR_SID_HISTORY_NAME tidak didukung.

[in] cNames

Berisi jumlah elemen dalam array rpNames .

[in] rpNames

Penunjuk ke array pointer ke string null-terminated yang berisi nama yang akan dikonversi.

[out] ppResult

Penunjuk ke nilai PDS_NAME_RESULT yang menerima struktur DS_NAME_RESULT yang berisi nama yang dikonversi. Pemanggil harus membebaskan memori ini, ketika tidak lagi diperlukan, dengan memanggil DsFreeNameResult.

Mengembalikan nilai

Mengembalikan nilai kesalahan Win32, nilai kesalahan RPC, atau salah satu dari yang berikut ini.

Komentar

Keberhasilan permintaan konversi nama tergantung pada tempat klien terikat. Klien mengikat instans tertentu dari layanan direktori menggunakan beberapa varian DsBind. Jika terikat ke katalog global, cakupan pemetaan nama adalah seluruh forest. Jika tidak terikat ke katalog global, cakupan pemetaan nama adalah domain yang tidak dicakup oleh katalog global untuk pengendali domain tersebut. Jika tidak terikat ke katalog global dan nama tidak ditemukan, tetapi nama input secara tidak ambigu mengidentifikasi domainnya dan domain ini berada di forest, maka data pengembalian mengidentifikasi nama domain DNS untuk domain yang menarik. Klien diharapkan menggunakan data ini untuk mengikat pengontrol domain atau katalog global yang benar dan memanggil DsCrackNames lagi dengan handel pengikatan baru.

Nilai pengembalian dari DsCrackNames menunjukkan kesalahan seperti parameter yang tidak valid atau memori yang tidak mencukupi. Namun, masalah dalam mengonversi nama individu dilaporkan dalam status anggota struktur DS_NAME_RESULT_ITEM yang dikembalikan untuk setiap nama input.

Catatan Jangan membingungkan nilai elemen format parameter format yang digunakan oleh fungsi DsCrackNames dengan elemen format bernama serupa seperti yang didefinisikan dalam enumerasi ADS_NAME_TYPE_ENUM yang digunakan oleh antarmuka IADsNameTranslate . Dua set format elemen tidak setara dan tidak dapat dipertukarkan.

Nota

Header ntdsapi.h mendefinisikan DsCrackNames 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

Syarat	Nilai
klien minimum yang didukung	Windows Vista
server minimum yang didukung	Windows Server 2008
Platform Target	Windows
Header	ntdsapi.h
Pustaka	Ntdsapi.lib
DLL	Ntdsapi.dll