Fungsi NetConnectionEnum (lmshare.h)

Artikel
08/24/2023

Mencantumkan semua koneksi yang dibuat ke sumber daya bersama pada server atau semua koneksi yang dibuat dari komputer tertentu. Jika ada lebih dari satu pengguna yang menggunakan koneksi ini, maka dimungkinkan untuk mendapatkan lebih dari satu struktur untuk koneksi yang sama, tetapi dengan nama pengguna yang berbeda.

Sintaks

NET_API_STATUS NET_API_FUNCTION NetConnectionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   qualifier,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

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.

String ini adalah Unicode jika _WIN32_WINNT atau FORCE_UNICODE ditentukan.

[in] qualifier

Penunjuk ke string yang menentukan nama berbagi atau nama komputer untuk koneksi yang diminati. Jika itu adalah nama berbagi, maka semua koneksi yang dibuat ke nama berbagi tersebut akan dicantumkan. Jika itu adalah nama komputer (misalnya, itu dimulai dengan dua karakter garis miring terbelakang), maka NetConnectionEnum mencantumkan semua koneksi yang dibuat dari komputer tersebut ke server yang ditentukan.

String ini adalah Unicode jika _WIN32_WINNT atau FORCE_UNICODE ditentukan.

[in] level

Menentukan tingkat informasi data. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
0	Mengembalikan pengidentifikasi koneksi. Parameter bufptr adalah penunjuk ke array struktur CONNECTION_INFO_0 .
1	Mengembalikan pengidentifikasi koneksi dan informasi koneksi. Parameter bufptr adalah penunjuk ke array struktur CONNECTION_INFO_1 .

[out] bufptr

Arahkan ke alamat buffer yang menerima informasi. 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] resume_handle

Penunjuk ke nilai yang berisi handel resume yang digunakan untuk melanjutkan pencarian koneksi yang ada. Handel harus nol pada panggilan pertama dan dibiarkan tidak berubah untuk panggilan berikutnya. Jika parameter ini NULL, maka tidak ada handel resume yang disimpan.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah NERR_Success.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem. Untuk daftar kode kesalahan, lihat Kode Kesalahan Sistem.

Keterangan

Administrator, Operator Server atau Cetak, atau keanggotaan grup Power User diperlukan untuk berhasil menjalankan fungsi NetConnectionEnum .

Contoh

Sampel kode berikut menunjukkan cara mencantumkan koneksi yang dibuat ke sumber daya bersama dengan panggilan ke fungsi NetConnectionEnum . Sampel memanggil NetConnectionEnum, menentukan informasi tingkat 1 (CONNECTION_INFO_1). Jika ada entri yang akan dikembalikan, entri akan mencetak nilai anggota coni1_username dan coni1_netname . Jika tidak ada entri untuk dikembalikan, sampel akan mencetak pesan yang sesuai. Terakhir, sampel kode membebaskan memori yang dialokasikan untuk buffer informasi.

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print user name and network name.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether 
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')  
               printf("No connection to %S from %S\n", 
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else                       
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }        
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	lmshare.h (termasuk Lm.h)
Pustaka	Netapi32.lib
DLL	Netapi32.dll