Fungsi NetWkstaUserEnum (lmwksta.h)
Fungsi NetWkstaUserEnum mencantumkan informasi tentang semua pengguna yang saat ini masuk ke stasiun kerja. Daftar ini mencakup masuk interaktif, layanan, dan batch.
Sintaks
NET_API_STATUS NET_API_FUNCTION NetWkstaUserEnum(
[in] LMSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] LPDWORD resumehandle
);
Parameter
[in] servername
Penunjuk ke string yang menentukan nama DNS atau NetBIOS dari server jarak jauh tempat fungsi dijalankan. Jika parameter ini NULL, komputer lokal akan digunakan.
[in] level
Menentukan tingkat informasi data. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Mengembalikan nama pengguna yang saat ini masuk ke stasiun kerja. Parameter bufptr menunjuk ke array struktur WKSTA_USER_INFO_0 . |
|
Mengembalikan nama pengguna saat ini dan domain yang diakses oleh stasiun kerja. Parameter bufptr menunjuk ke array struktur WKSTA_USER_INFO_1 . |
[out] bufptr
Arahkan ke buffer yang menerima data. Format data ini tergantung pada nilai parameter tingkat . Buffer ini dialokasikan oleh sistem dan harus dikosongkan menggunakan fungsi NetApiBufferFree . Perhatikan bahwa Anda harus membebaskan buffer meskipun fungsi gagal dengan ERROR_MORE_DATA.
[in] prefmaxlen
Menentukan panjang maksimum data yang dikembalikan, dalam byte. 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 akan mengembalikan ERROR_MORE_DATA. Untuk informasi selengkapnya, lihat Buffer Fungsi Manajemen Jaringan dan Panjang Buffer Fungsi Manajemen Jaringan.
[out] entriesread
Pointer ke nilai yang menerima hitungan elemen yang benar-benar dijumlahkan.
[out] totalentries
Penunjuk ke nilai yang menerima jumlah total entri yang bisa dijumlahkan dari posisi resume saat ini. Perhatikan bahwa aplikasi harus mempertimbangkan nilai ini hanya sebagai petunjuk.
[in, out] resumehandle
Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian yang sudah ada. Handel harus nol pada panggilan pertama dan dibiarkan tidak berubah untuk panggilan berikutnya. Jika parameter ini NULL, tidak ada handel resume yang disimpan.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan NERR_Success.
Jika fungsi gagal, nilai yang dikembalikan bisa menjadi salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Pengguna tidak memiliki akses ke informasi yang diminta. |
|
Entri lainnya tersedia. Tentukan buffer yang cukup besar untuk menerima semua entri. |
|
Parameter tingkat tidak valid. |
Keterangan
Perhatikan bahwa karena fungsi NetWkstaUserEnum mencantumkan entri untuk layanan dan masuk batch, serta untuk masuk interaktif, fungsi dapat mengembalikan entri untuk pengguna yang telah keluar dari stasiun kerja. Ini dapat terjadi, misalnya, ketika pengguna memanggil layanan yang meniru pengguna. Dalam hal ini, NetWkstaUserEnum mengembalikan entri untuk pengguna hingga layanan berhenti meniru pengguna.
Windows Server 2003 dan Windows XP: Jika Anda memanggil fungsi ini pada pengendali domain yang menjalankan Direktori Aktif, akses diizinkan atau ditolak berdasarkan ACL untuk objek yang dapat diamankan. Untuk mengaktifkan akses anonim, pengguna Anonim harus menjadi anggota grup "Akses kompatibel Pra-Windows 2000". Ini karena token anonim tidak menyertakan SID grup Semua Orang secara default. Jika Anda memanggil fungsi ini di server anggota atau stasiun kerja, semua pengguna yang diautentikasi dapat melihat informasi. Akses anonim juga diizinkan jika pengaturan kebijakan RestrictAnonymous mengizinkan akses anonim. Jika pengaturan kebijakan RestrictAnonymous tidak mengizinkan akses anonim, hanya administrator yang berhasil menjalankan fungsi. Anggota Administrator, dan grup lokal Server, Sistem, dan Operator Cetak juga dapat melihat informasi. Untuk informasi selengkapnya tentang membatasi akses anonim, lihat Persyaratan Keamanan untuk Fungsi Manajemen Jaringan. Untuk informasi selengkapnya tentang ACL, ACL, dan token akses, lihat Model Access Control.
Windows 2000: Jika Anda memanggil fungsi ini pada pengendali domain yang menjalankan Direktori Aktif, akses diizinkan atau ditolak berdasarkan daftar kontrol akses (ACL) untuk objek yang dapat diamankan. ACL default mengizinkan semua pengguna dan anggota yang diautentikasi dari grup " Akses pra-Windows 2000 kompatibel" untuk melihat informasi. Secara default, grup "Akses pra-windows 2000 kompatibel" menyertakan Semua Orang sebagai anggota. Ini memungkinkan akses anonim ke informasi jika sistem mengizinkan akses anonim. Jika Anda memanggil fungsi ini di server anggota atau stasiun kerja, semua pengguna yang diautentikasi dapat melihat informasi. Akses anonim juga diizinkan jika pengaturan kebijakan RestrictAnonymous memungkinkan akses anonim.
Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan makro _WIN32_WINNT sebagai 0x0400 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
Contoh
Sampel kode berikut menunjukkan cara mencantumkan informasi tentang semua pengguna yang saat ini masuk ke stasiun kerja menggunakan panggilan ke fungsi NetWkstaUserEnum . Sampel memanggil NetWkstaUserEnum, menentukan informasi tingkat 0 ( WKSTA_USER_INFO_0). Sampel mengulang entri dan mencetak nama pengguna yang masuk ke stasiun kerja. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer informasi, dan mencetak jumlah total pengguna yang dijumlahkan.
#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[])
{
LPWKSTA_USER_INFO_0 pBuf = NULL;
LPWKSTA_USER_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = argv[1];
fwprintf(stderr, L"\nUsers currently logged on %s:\n", pszServerName);
//
// Call the NetWkstaUserEnum function, specifying level 0.
//
do // begin do
{
nStatus = NetWkstaUserEnum( pszServerName,
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
//
// Only members of the Administrators local group
// can successfully execute NetWkstaUserEnum
// locally and on a remote server.
//
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the user logged on to the workstation.
//
wprintf(L"\t-- %s\n", pTmpBuf->wkui0_username);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, indicate a system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
//
// Continue to call NetWkstaUserEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
//
// Check again for allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of workstation users.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
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 | lmwksta.h (termasuk Lm.h) |
| Pustaka | Netapi32.lib |
| DLL | Netapi32.dll |