Fungsi NetValidateName (lmjoin.h)

Artikel
08/24/2023

Fungsi NetValidateName memverifikasi bahwa nama valid untuk jenis nama yang ditentukan (nama komputer, nama grup kerja, nama domain, atau nama komputer DNS).

Sintaks

NET_API_STATUS NET_API_FUNCTION NetValidateName(
  [in] LPCWSTR            lpServer,
  [in] LPCWSTR            lpName,
  [in] LPCWSTR            lpAccount,
  [in] LPCWSTR            lpPassword,
  [in] NETSETUP_NAME_TYPE NameType
);

Parameter

[in] lpServer

Penunjuk ke string konstanta yang menentukan nama DNS atau NetBIOS komputer untuk memanggil fungsi. Jika parameter ini NULL, komputer lokal akan digunakan.

[in] lpName

Penunjuk ke string konstanta yang menentukan nama untuk divalidasi. Bergantung pada nilai yang ditentukan dalam parameter NameType , parameter lpName dapat menunjuk ke nama komputer, nama grup kerja, nama domain, atau nama komputer DNS.

[in] lpAccount

Jika parameter lpName adalah nama domain, parameter ini menunjuk ke nama akun yang akan digunakan saat menyambungkan ke pengendali domain. String harus menentukan nama domain NetBIOS dan akun pengguna (misalnya, "REDMOND\user") atau nama prinsipal pengguna (UPN) pengguna dalam bentuk nama login gaya Internet (misalnya, "someone@example.com"). Jika parameter ini NULL, konteks pemanggil akan digunakan.

[in] lpPassword

Jika parameter lpAccount menentukan nama akun, parameter ini harus menunjuk ke kata sandi yang akan digunakan saat menyambungkan ke pengendali domain. Jika tidak, parameter ini harus NULL.

[in] NameType

Jenis nama yang diteruskan dalam parameter lpName untuk divalidasi. Parameter ini dapat menjadi salah satu nilai dari jenis enumerasi NETSETUP_NAME_TYPE yang ditentukan dalam file header Lmjoin.h .

Perhatikan bahwa header Lmjoin.h secara otomatis disertakan oleh file header Lm.h . File header Lmjoin.h tidak boleh digunakan secara langsung.

Daftar berikut menunjukkan nilai yang mungkin untuk parameter ini.

Nilai	Makna
NetSetupUnknown 0	Tipe nama tidak diketahui. Jika nilai ini digunakan, fungsi NetValidateName gagal dengan ERROR_INVALID_PARAMETER.
NetSetupMachine 1	Verifikasi bahwa nama komputer NetBIOS valid dan tidak digunakan.
NetSetupWorkgroup 2	Verifikasi bahwa nama grup kerja valid.
NetSetupDomain 3	Verifikasi bahwa nama domain ada dan itu adalah domain.
NetSetupNonExistentDomain 4	Verifikasi bahwa nama domain tidak digunakan.
NetSetupDnsMachine 5	Verifikasi bahwa nama komputer DNS valid. Nilai ini didukung pada Windows 2000 dan yang lebih baru. Aplikasi harus dikompilasi dengan _WIN32_WINNT >= 0x0500 untuk menggunakan nilai ini.

Mengembalikan nilai

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
DNS_ERROR_INVALID_NAME_CHAR	Nama DNS berisi karakter yang tidak valid. Kesalahan ini dikembalikan jika parameter NameType yang ditentukan adalah NetSetupDnsMachine dan nama DNS dalam parameter lpName berisi karakter yang tidak valid.
DNS_ERROR_NON_RFC_NAME	Nama DNS tidak mematuhi spesifikasi RFC. Kesalahan ini dikembalikan jika parameter NameType yang ditentukan adalah NetSetupDnsMachine dan nama DNS dalam parameter lpName tidak mematuhi spesifikasi RFC.
ERROR_DUP_NAME	Nama duplikat sudah ada di jaringan.
ERROR_INVALID_COMPUTERNAME	Format nama komputer yang ditentukan tidak valid.
ERROR_INVALID_PARAMETER	Parameter salah. Kesalahan ini dikembalikan jika parameter lpName adalah NULL atau parameter NameType ditentukan sebagai NetSetupUnknown atau nametype yang tidak diketahui.
ERROR_NO_SUCH_DOMAIN	Domain yang ditentukan tidak ada.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika komputer jarak jauh ditentukan dalam parameter lpServer dan panggilan ini tidak didukung pada komputer jarak jauh.
NERR_InvalidComputer	Nama komputer yang ditentukan tidak valid. Kesalahan ini dikembalikan jika parameter NameType yang ditentukan adalah NetSetupDnsMachine atau NetSetupMachine dan nama komputer yang ditentukan tidak valid.
NERR_InvalidWorkgroupName	Nama grup kerja yang ditentukan tidak valid. Kesalahan ini dikembalikan jika parameter NameType yang ditentukan adalah NetSetupWorkgroup dan nama grup kerja yang ditentukan tidak valid.
RPC_S_SERVER_UNAVAILABLE	Server RPC tidak tersedia. Kesalahan ini dikembalikan jika komputer jarak jauh ditentukan dalam parameter lpServer dan server RPC tidak tersedia.
RPC_E_REMOTE_DISABLED	Panggilan jarak jauh tidak diperbolehkan untuk proses ini. Kesalahan ini dikembalikan jika komputer jarak jauh ditentukan dalam parameter lpServer dan panggilan jarak jauh tidak diizinkan untuk proses ini.

Keterangan

Fungsi NetValidateName memvalidasi nama berdasarkan jenis nama yang ditentukan.

Jika parameter NameType adalah NetSetupMachine, nama yang diteruskan dalam parameter lpName harus secara sintaksis benar sebagai nama NetBIOS dan nama saat ini tidak boleh digunakan di jaringan.

Jika parameter NameType adalah NetSetupWorkgroup, nama yang diteruskan dalam parameter lpName harus secara sintaksis benar sebagai nama NetBIOS, nama saat ini tidak boleh digunakan di jaringan sebagai nama unik, dan nama harus berbeda dari nama komputer.

Jika parameter NameType adalah NetSetupDomain, nama yang diteruskan dalam parameter lpName harus secara sintaksis benar sebagai nama NetBIOS atau DNS dan nama saat ini harus terdaftar sebagai nama domain.

Jika parameter NameType adalah NetSetupNonExistentDomain, nama yang diteruskan dalam parameter lpName harus secara sintaksis benar sebagai nama NetBIOS atau DNS dan nama saat ini tidak boleh didaftarkan sebagai nama domain.

Jika parameter NameType adalah NetSetupDnsMachine, nama yang diteruskan dalam parameter lpName harus benar secara sintaksis sebagai nama DNS.

Nama NetBIOS dibatasi hingga panjang maksimum 16 karakter.

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

Contoh

Contoh berikut memvalidasi nama untuk jenis tertentu.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

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

    NET_API_STATUS nStatus;

    LPCWSTR lpServer = NULL;
    LPCWSTR lpName = NULL;
    LPCWSTR lpAccount = NULL;
    LPCWSTR lpPassword = NULL;
    DWORD dwNameType = NetSetupUnknown; // unknown name type

    if (argc != 3 && argc != 4 && argc != 6) {
        wprintf(L"Usage: %ws Server Name AccountName Password> nametype\n",
                argv[0]);
        wprintf(L"Usage: %ws Server Name nametype\n", argv[0]);
        wprintf(L"Usage: %ws Name nametype\n", argv[0]);
        wprintf(L"     %ws Client2 2\n", argv[0]);
        wprintf(L"     %ws Myserver Client2 3\n", argv[0]);
        wprintf(L"     %ws Myserver Client2 domain\\user password 3\n", argv[0]);
        exit(1);
    }
    // The request is not for the primary domain.
    //
    if (argc == 3) {
        lpName = argv[1];
        dwNameType = _wtoi(argv[2]);
    }

    if (argc == 4) {
        lpServer = argv[1];
        lpName = argv[2];
        dwNameType = _wtoi(argv[3]);
    }

    if (argc == 6) {
        lpServer = argv[1];
        lpName = argv[2];
        lpAccount = argv[3];
        lpPassword = argv[4];
        dwNameType = _wtoi(argv[5]);
    }

    wprintf(L"Calling NetValidateName with parameters\n");
    wprintf(L"    lpServer = %ws\n", lpServer);
    wprintf(L"    lpName = %ws\n", lpName);
    wprintf(L"    lpAccount = %ws\n", lpAccount);
    wprintf(L"    lpPassword = %ws\n", lpPassword);
    wprintf(L"    NameType  = %d ", dwNameType);
    switch (dwNameType) {
    case NetSetupUnknown:
        wprintf(L"(NetSetupUnknown)\n");
        break;
    case NetSetupMachine:
        wprintf(L"(NetSetupMachine)\n");
        break;
    case NetSetupWorkgroup:
        wprintf(L"(NetSetupWorkgroup)\n");
        break;
    case NetSetupDomain:
        wprintf(L"(NetSetupDomain)\n");
        break;
    case NetSetupNonExistentDomain:
        wprintf(L"(NetSetupNonExistentDomain)\n");
        break;
#if(_WIN32_WINNT >= 0x0500)
    case NetSetupDnsMachine:
        wprintf(L"(NetSetupDnsMachine)\n");
        break;
#endif
    default:
        wprintf(L"Other unknown nametype)\n");
        break;
    }

    //
    // Call the NetValidateName function to validate the name
    //
    nStatus = NetValidateName(lpServer,
                              lpName, lpAccount, lpPassword, (NETSETUP_NAME_TYPE) dwNameType);
    //
    // If the call succeeds,
    //
    if ((nStatus == NERR_Success)) {
        wprintf(L"NetValidateName was successful\n", nStatus);
    } else {
        wprintf(L"NetValidateName 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_DUP_NAME:
            wprintf(L"ERROR_DUP_NAME\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_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 NERR_InvalidComputer:
            wprintf(L"NERR_InvalidComputer\n");
            break;
        case NERR_InvalidWorkgroupName:
            wprintf(L"NERR_InvalidWorkgroupName\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	lmjoin.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll