NetGetDCName 函式 (lmaccess.h)

發行項
03/05/2024

NetGetDCName 函式會傳回主要域控制器的名稱， (PDC) 。它不會傳回指定網域的備份域控制器名稱 (BDC) 。此外，您無法將此函式遠端至非 PDC 伺服器。

支援 DNS 樣式名稱的應用程式應該呼叫 DsGetDcName 函式。這種類型的環境中的域控制器具有多宿主目錄複寫關聯性。因此，您的應用程式使用不是 PDC 的 DC 可能會有好處。您可以呼叫 DsGetDcName 函式來找出網域中的任何 DC; NetGetDCName 只會傳回 PDC 的名稱。

語法

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

參數

ServerName

常數位符串的指標，指定要執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 NULL，則會使用本機電腦。

DomainName

指定定義域名稱之常數位符串的指標。功能變數名稱必須是 NetBIOS 功能變數名稱 (，例如 microsoft) 。 NetGetDCName 不支援 DNS 樣式的名稱 (例如，microsoft.com) 。如果此參數為 NULL，函式會傳回主要網域的域控制器名稱。

Buffer

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	Description
NERR_DCNotFound	找不到 domainname 參數中指定的網域域控制器。
ERROR_BAD_NETPATH	找不到網路路徑。如果找不到 servername 參數中指定的電腦，就會傳回此錯誤。
ERROR_INVALID_NAME	名稱語法不正確。如果 servername 參數中指定的名稱包含不合法的字元，就會傳回此錯誤。
ERROR_NOT_SUPPORTED	不支援此要求。

備註

成功執行 NetGetDCName 函式不需要特殊群組成員資格。

範例

下列程式代碼範例示範如何使用擷取主要域控制器
NetGetDCName 函式。此範例會呼叫指定 servername 和 domainname 參數的 NetGetDCName 。如果呼叫成功，程式代碼會將資訊列印出主要域控制器的名稱。最後，此範例會釋放針對傳回域控制器名稱之緩衝區所配置的記憶體。

#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;
}

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmaccess.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll