Fungsi NetServerEnum (lmserver.h)
Fungsi NetServerEnum mencantumkan semua server dari jenis yang ditentukan yang terlihat di domain.
Sintaks
NET_API_STATUS NET_API_FUNCTION NetServerEnum(
[in, optional] LMCSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in] DWORD servertype,
[in, optional] LMCSTR domain,
[in, out, optional] LPDWORD resume_handle
);
Parameter
[in, optional] servername
Dipesan; harus NULL.
[in] level
Tingkat informasi data yang diminta. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Mengembalikan nama server dan informasi platform. Parameter bufptr menunjuk ke array struktur SERVER_INFO_100 . |
|
Mengembalikan nama server, jenis, dan data terkait. Parameter bufptr menunjuk ke array struktur SERVER_INFO_101 . |
[out] bufptr
Penunjuk ke buffer yang menerima data. Format data ini tergantung pada nilai parameter tingkat . Buffer ini dialokasikan oleh sistem dan harus dibebaskan menggunakan fungsi NetApiBufferFree . Perhatikan bahwa Anda harus membebaskan buffer meskipun fungsi gagal dengan ERROR_MORE_DATA.
[in] prefmaxlen
Panjang maksimum data yang dikembalikan, dalam byte yang disukai. Jika Anda menentukan MAX_PREFERRED_LENGTH, fungsi mengalokasikan jumlah memori yang diperlukan untuk data. Jika Anda menentukan nilai lain dalam parameter ini, nilai tersebut dapat membatasi jumlah byte yang dikembalikan fungsi. Jika ukuran buffer tidak cukup untuk menahan semua entri, fungsi mengembalikan ERROR_MORE_DATA. Untuk informasi selengkapnya, lihat Buffer Fungsi Manajemen Jaringan dan Panjang Buffer Fungsi Manajemen Jaringan.
[out] entriesread
Penunjuk ke nilai yang menerima hitungan elemen yang benar-benar dijumlahkan.
[out] totalentries
Penunjuk ke nilai yang menerima jumlah total server dan stasiun kerja yang terlihat di jaringan. Perhatikan bahwa aplikasi harus mempertimbangkan nilai ini hanya sebagai petunjuk.
[in] servertype
Nilai yang memfilter entri server untuk dikembalikan dari enumerasi. Parameter ini dapat menjadi kombinasi dari nilai berikut yang ditentukan dalam file header Lmserver.h .
[in, optional] domain
Penunjuk ke string konstanta yang menentukan nama domain tempat daftar server akan dikembalikan. Nama domain harus berupa nama domain NetBIOS (misalnya, microsoft). Fungsi NetServerEnum tidak mendukung nama gaya DNS (misalnya, microsoft.com).
Jika parameter ini NULL, domain utama tersirat.
[in, out, optional] resume_handle
Dipesan; harus diatur ke nol.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan NERR_Success.
Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut:
| Mengembalikan kode/nilai | Deskripsi |
|---|---|
|
Akses ditolak. |
|
Parameter salah. |
|
Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri. |
|
Tidak ada server browser yang ditemukan. |
|
Permintaan tidak didukung. |
|
Terjadi kesalahan jarak jauh tanpa data yang dikembalikan oleh server. |
|
Layanan server tidak dimulai. |
|
Layanan belum dimulai. |
|
Layanan Stasiun Kerja belum dimulai. Layanan stasiun kerja lokal digunakan untuk berkomunikasi dengan server jarak jauh tingkat bawah. |
Keterangan
Fungsi NetServerEnum digunakan untuk mencantumkan semua server dari jenis yang ditentukan yang terlihat dalam domain. Misalnya, aplikasi dapat memanggil NetServerEnum untuk mencantumkan semua pengendali domain saja atau semua server yang menjalankan instans server SQL saja.
Aplikasi menggabungkan masker bit untuk berbagai jenis server dalam parameter jenis server untuk mencantumkan beberapa jenis. Misalnya, nilai SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) menggabungkan masker bit untuk SV_TYPE_WORKSTATION (0x00000001) dan SV_TYPE_SERVER (0x00000002).
Jika Anda memerlukan informasi lebih lanjut untuk server tertentu, panggil fungsi WNetEnumResource .
Tidak ada keanggotaan grup khusus yang diperlukan untuk berhasil menjalankan fungsi NetServerEnum .
Jika Anda menentukan nilai SV_TYPE_LOCAL_LIST_ONLY, fungsi NetServerEnum mengembalikan daftar server yang dikelola browser secara internal. Ini hanya memiliki arti pada browser master (atau di komputer yang telah menjadi browser master di masa lalu). Browser master adalah komputer yang saat ini memiliki hak untuk menentukan komputer mana yang dapat menjadi server atau stasiun kerja di jaringan.
Jika tidak ada server yang ditemukan yang cocok dengan jenis yang ditentukan dalam parameter jenis server , fungsi NetServerEnum mengembalikan parameter bufptr sebagai nilai NULL dan DWORD yang diacu oleh parameter entriesread dan totalentries diatur ke nol.
Fungsi NetServerEnum tergantung pada layanan browser yang diinstal dan dijalankan. Jika tidak ada server browser yang ditemukan, maka NetServerEnum gagal dengan ERROR_NO_BROWSER_SERVERS_FOUND.
Jika Anda memprogram Direktori Aktif, Anda mungkin dapat memanggil metode Antarmuka Layanan Direktori Aktif (ADSI) tertentu untuk mencapai fungsi yang sama yang dapat Anda capai dengan memanggil fungsi server manajemen jaringan. Untuk informasi selengkapnya, lihat IADsComputer.
Contoh
Sampel kode berikut menunjukkan cara mencantumkan semua server yang terlihat di domain dengan panggilan ke fungsi NetServerEnum . Sampel memanggil NetServerEnum, menentukan tingkat informasi 101 ( SERVER_INFO_101). Jika ada server yang ditemukan, kode sampel akan mengulang entri dan mencetak data yang diambil. Jika server adalah pengendali domain, server mengidentifikasi server sebagai pengendali domain utama (PDC) atau pengendali domain cadangan (BDC). Sampel juga mencetak jumlah total entri yang tersedia dan petunjuk tentang jumlah entri yang benar-benar dijumlahkan, memperingatkan pengguna jika semua entri tidak dijumlahkan. Terakhir, sampel membebaskan memori yang dialokasikan untuk buffer informasi.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t * argv[])
{
LPSERVER_INFO_101 pBuf = NULL;
LPSERVER_INFO_101 pTmpBuf;
DWORD dwLevel = 101;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwTotalCount = 0;
DWORD dwServerType = SV_TYPE_SERVER; // all servers
DWORD dwResumeHandle = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
LPWSTR pszDomainName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
exit(1);
}
// The request is not for the primary domain.
//
if (argc == 2)
pszDomainName = argv[1];
//
// Call the NetServerEnum function to retrieve information
// for all servers, specifying information level 101.
//
nStatus = NetServerEnum(pszServerName,
dwLevel,
(LPBYTE *) & pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
dwServerType,
pszDomainName,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
if ((pTmpBuf = pBuf) != NULL) {
//
// Loop through the entries and
// print the data for all server types.
//
for (i = 0; i < dwEntriesRead; i++) {
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL) {
fprintf(stderr, "An access violation has occurred\n");
break;
}
printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
wprintf(L"\tName: %s\n", pTmpBuf->sv101_name);
printf("\tVersion: %d.%d\n",
pTmpBuf->sv101_version_major,
pTmpBuf->sv101_version_minor);
printf("\tType: %d", pTmpBuf->sv101_type);
//
// Check to see if the server is a domain controller;
// if so, identify it as a PDC or a BDC.
//
if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
wprintf(L" (PDC)");
else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
wprintf(L" (BDC)");
printf("\n");
//
// Also print the comment associated with the server.
//
wprintf(L"\tComment: %s\n\n", pTmpBuf->sv101_comment);
pTmpBuf++;
dwTotalCount++;
}
// Display a warning if all available entries were
// not enumerated, print the number actually
// enumerated, and the total number available.
if (nStatus == ERROR_MORE_DATA) {
fprintf(stderr, "\nMore entries available!!!\n");
fprintf(stderr, "Total entries: %d", dwTotalEntries);
}
printf("\nEntries enumerated: %d\n", dwTotalCount);
} else {
printf("No servers were found\n");
printf("The buffer (bufptr) returned was NULL\n");
printf(" entriesread: %d\n", dwEntriesRead);
printf(" totalentries: %d\n", dwEntriesRead);
}
} else
fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
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 | lmserver.h (termasuk Lm.h) |
| Pustaka | Netapi32.lib |
| DLL | Netapi32.dll |