Fungsi NetGetDCName (lmaccess.h)

Artikel
03/09/2023

Fungsi NetGetDCName mengembalikan nama pengendali domain utama (PDC). Ini tidak mengembalikan nama pengendali domain cadangan (BDC) untuk domain yang ditentukan. Selain itu, Anda tidak dapat melakukan remote fungsi ini ke server non-PDC.

Aplikasi yang mendukung nama gaya DNS harus memanggil fungsi DsGetDcName . Pengendali domain dalam jenis lingkungan ini memiliki hubungan replikasi direktori multi-master. Oleh karena itu, mungkin menguntungkan bagi aplikasi Anda untuk menggunakan DC yang bukan PDC. Anda dapat memanggil fungsi DsGetDcName untuk menemukan DC apa pun di domain; NetGetDCName hanya mengembalikan nama PDC.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetGetDCName(
        LPCWSTR ServerName,
        LPCWSTR DomainName,
        LPBYTE  *Buffer
);

Parameter

ServerName

Penunjuk ke string konstanta yang menentukan nama DNS atau NetBIOS dari server jarak jauh tempat fungsi dijalankan. Jika parameter ini NULL, komputer lokal akan digunakan.

DomainName

Penunjuk ke string konstanta yang menentukan nama domain. Nama domain harus berupa nama domain NetBIOS (misalnya, microsoft). NetGetDCName tidak mendukung nama gaya DNS (misalnya, microsoft.com). Jika parameter ini NULL, fungsi mengembalikan nama pengendali domain untuk domain utama.

Buffer

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan dapat menjadi salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
NERR_DCNotFound	Tidak dapat menemukan pengendali domain untuk domain yang ditentukan dalam parameter nama domain .
ERROR_BAD_NETPATH	Jalur jaringan tidak ditemukan. Kesalahan ini dikembalikan jika komputer yang ditentukan dalam parameter nama server tidak dapat ditemukan.
ERROR_INVALID_NAME	Sintaks nama salah. Kesalahan ini dikembalikan jika nama yang ditentukan dalam parameter nama server berisi karakter ilegal.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung.

Keterangan

Tidak ada keanggotaan grup khusus yang diperlukan untuk berhasil menjalankan fungsi NetGetDCName .

Contoh

Sampel kode berikut menunjukkan cara mengambil pengendali domain utama menggunakan
Fungsi NetGetDCName . Sampel memanggil NetGetDCName yang menentukan parameter nama server dan nama domain. Jika panggilan berhasil, kode akan mencetak informasi nama pengendali domain utama. Terakhir, sampel membebaskan memori yang dialokasikan untuk buffer tempat nama pengontrol domain dikembalikan.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <stdlib.h>  // for _wtoi function
#include <assert.h>
#include <windows.h>
#include <lm.h>

// Need to link with netapi32.lib
#pragma comment(lib, "netapi32.lib")

int wmain(int argc, wchar_t * argv[])
{

    NET_API_STATUS nStatus;

    LPCWSTR lpServer = NULL;
    LPCWSTR lpDomain = NULL;

    LPCWSTR lpDcName = NULL;
    
    if (argc != 3 ) {
        wprintf(L"Usage: %ws <ServerName> <DomainName>\n",
                argv[0]);
        wprintf(L"     %ws Myserver Domain\n", argv[0]);
        exit(1);
    }

    lpServer = argv[1];
    lpDomain = argv[2];

    wprintf(L"Calling NetGetDCName with parameters\n");
    wprintf(L"    lpServer = %ws\n", lpServer);
    wprintf(L"    lpDomain = %ws\n", lpDomain);

    //
    // Call the NetGetDCName function
    //
    nStatus = NetGetDCName(lpServer, lpDomain, (LPBYTE *) &lpDcName);
    //
    // If the call succeeds,
    //
    if (nStatus == NERR_Success) {
        wprintf(L"NetGetDCName was successful\n", nStatus);
        wprintf(L"DC Name = %ws\n", lpDcName);
        // Need to free the returned buffer
        nStatus = NetApiBufferFree( (LPVOID) lpDcName);
        if (nStatus != NERR_Success)
            wprintf(L"NetApiBufferFree failed with error: %lu (0x%lx)\n",
                nStatus, nStatus);
    } else {
        wprintf(L"NetGetDCName failed with error: %lu (0x%lx)\n", nStatus,
                nStatus);
        wprintf(L"   Error = ");
        switch (nStatus) {
        case ERROR_INVALID_PARAMETER:
            wprintf(L"ERROR_INVALID_PARAMETER\n");
            break;
        case ERROR_NO_SUCH_DOMAIN:
            wprintf(L"ERROR_NO_SUCH_DOMAIN\n");
            break;
        case ERROR_NOT_SUPPORTED:
            wprintf(L"ERROR_NOT_SUPPORTED\n");
            break;
        case ERROR_BAD_NETPATH:
            wprintf(L"ERROR_BAD_NETPATH\n");
            break;
        case ERROR_INVALID_COMPUTERNAME:
            wprintf(L"ERROR_INVALID_COMPUTERNAME\n");
            break;
        case DNS_ERROR_INVALID_NAME_CHAR:
            wprintf(L"DNS_ERROR_INVALID_NAME_CHAR\n");
            break;
        case DNS_ERROR_NON_RFC_NAME:
            wprintf(L"DNS_ERROR_NON_RFC_NAME\n");
            break;
        case ERROR_INVALID_NAME:
            wprintf(L"ERROR_INVALID_NAME\n");
            break;
        case NERR_DCNotFound:
            wprintf(L"NERR_DCNotFound\n");
            break;
        case NERR_WkstaNotStarted:
            wprintf(L"NERR_WkstaNotStarted\n");
            break;
        case RPC_S_SERVER_UNAVAILABLE:
            wprintf(L"RPC_S_SERVER_UNAVAILABLE\n");
            break;
        case RPC_E_REMOTE_DISABLED:
            wprintf(L"RPC_E_REMOTE_DISABLED\n");
            break;
        default:
            wprintf(L"Other error, see Winerror.h or lmerr.h)\n");
            break;
        }
    }

    return nStatus;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	lmaccess.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll