Fungsi WNetGetUniversalNameA (winnetwk.h)
Fungsi WNetGetUniversalName mengambil jalur berbasis drive untuk sumber daya jaringan dan mengembalikan struktur informasi yang berisi bentuk nama yang lebih universal.
Sintaks
DWORD WNetGetUniversalNameA(
[in] LPCSTR lpLocalPath,
[in] DWORD dwInfoLevel,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpBufferSize
);
Parameter
[in] lpLocalPath
Penunjuk ke string konstanta yang dihentikan null yang merupakan jalur berbasis drive untuk sumber daya jaringan.
Misalnya, jika drive H telah dipetakan ke berbagi drive jaringan, dan sumber daya jaringan yang menarik adalah file bernama Sample.doc di direktori \Win32\Contoh pada berbagi tersebut, jalur berbasis drive H:\Win32\Examples\Sample.doc.
[in] dwInfoLevel
Jenis struktur yang disimpan fungsi dalam buffer yang diacu oleh parameter lpBuffer . Parameter ini dapat menjadi salah satu nilai berikut yang ditentukan dalam file header Winnetwk.h .
| Nilai | Makna |
|---|---|
|
Fungsi ini menyimpan struktur UNIVERSAL_NAME_INFO di buffer. |
|
Fungsi ini menyimpan struktur REMOTE_NAME_INFO di buffer. |
Struktur UNIVERSAL_NAME_INFO menunjuk ke string nama Universal Naming Convention (UNC).
Struktur REMOTE_NAME_INFO menunjuk ke string nama UNC dan dua string informasi koneksi tambahan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[out] lpBuffer
Penunjuk ke buffer yang menerima struktur yang ditentukan oleh parameter dwInfoLevel .
[in, out] lpBufferSize
Penunjuk ke variabel yang menentukan ukuran, dalam byte, dari buffer yang diacu oleh parameter lpBuffer .
Jika fungsi berhasil, ia mengatur variabel yang diacu oleh lpBufferSize ke jumlah byte yang disimpan dalam buffer. Jika fungsi gagal karena buffer terlalu kecil, lokasi ini menerima ukuran buffer yang diperlukan, dan fungsi mengembalikan ERROR_MORE_DATA.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.
Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem, seperti salah satu nilai berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
String yang ditujukan oleh parameter lpLocalPath tidak valid. |
|
Tidak ada koneksi saat ini ke perangkat jarak jauh, tetapi ada koneksi yang diingat (persisten) ke perangkat tersebut. |
|
Terjadi kesalahan khusus jaringan. Gunakan fungsi WNetGetLastError untuk mendapatkan deskripsi kesalahan. |
|
Buffer yang diacu oleh parameter lpBuffer terlalu kecil. Fungsi mengatur variabel yang ditunjukkan oleh parameter lpBufferSize ke ukuran buffer yang diperlukan. Entri lainnya tersedia dengan panggilan berikutnya. |
|
Parameter dwInfoLevel diatur ke UNIVERSAL_NAME_INFO_LEVEL, tetapi penyedia jaringan tidak mendukung nama UNC. (Tidak ada penyedia jaringan yang mendukung fungsi ini.) |
|
Tidak ada penyedia jaringan yang mengenali nama lokal yang memiliki koneksi. Namun, jaringan tidak tersedia untuk setidaknya satu penyedia yang mungkin memiliki koneksi. |
|
Jaringan tidak tersedia. |
|
Perangkat yang ditentukan oleh parameter lpLocalPath tidak dialihkan. |
Keterangan
Bentuk universal jalur berbasis drive lokal mengidentifikasi sumber daya jaringan dengan cara yang tidak ambigu dan independen komputer. Nama kemudian dapat diteruskan ke proses di komputer lain, memungkinkan proses tersebut untuk mendapatkan akses ke sumber daya.
Fungsi WNetGetUniversalName saat ini mendukung satu bentuk nama universal: nama konvensi penamaan universal (UNC), yang terlihat seperti berikut:
\\servername\sharename\path\file
Menggunakan contoh dari deskripsi sebelumnya dari parameter lpLocalPath , jika drive jaringan bersama berada di server bernama COOLSERVER, dan nama berbaginya adalah HOTSHARE, nama UNC untuk sumber daya jaringan yang nama berbasis drivenya H:\Win32\Examples\Sample.doc adalah sebagai berikut:
\\coolserver\hotshare\win32\examples\sample.doc
Struktur UNIVERSAL_NAME_INFO berisi penunjuk ke string nama UNC. Struktur REMOTE_NAME_INFO juga berisi penunjuk ke string nama UNC serta pointer ke dua string berguna lainnya. Misalnya, proses dapat meneruskan anggota lpszConnectionInfo struktur REMOTE_NAME_INFO ke fungsi WNetAddConnection2 untuk menyambungkan perangkat lokal ke sumber daya jaringan. Kemudian proses dapat menambahkan string yang ditujukan oleh anggota lpszRemainingPath ke string perangkat lokal. String yang dihasilkan dapat diteruskan ke fungsi yang memerlukan jalur berbasis drive.
Parameter lpLocalPath tidak harus menentukan jalur atau sumber daya yang sudah ada pada sumber daya jarak jauh. Misalnya, parameter lpLocalPath dapat menentukan folder dan , hierarki folder, atau file yang saat ini tidak ada. Fungsi WNetGetUniversalName mengembalikan bentuk nama yang lebih universal dalam kasus ini.
Ukuran buffer yang diacu oleh parameter lpBuffer dan ditentukan dalam parameter lpBufferSize harus jauh lebih besar dari ukuran struktur REMOTE_NAME_INFO atau UNIVERSAL_NAME_INFO . Buffer yang ditunjukkan oleh parameter lpBuffer harus cukup besar untuk menyimpan string UNC yang ditunjukkan oleh anggota dalam struktur REMOTE_NAME_INFO atau UNIVERSAL_NAME_INFO . Jika ukuran buffer terlalu kecil, maka fungsi gagal dengan ERROR_MORE_DATA dan variabel yang ditunjukkan oleh parameter lpBufferSize menunjukkan ukuran buffer yang diperlukan.
Windows Server 2003 dan Windows XP: Fungsi ini meminta namespace perangkat MS-DOS yang terkait dengan sesi masuk karena perangkat MS-DOS diidentifikasi oleh AuthenticationID. (AuthenticationID adalah pengidentifikasi unik lokal, atau LUID, yang terkait dengan sesi masuk.) Ini dapat memengaruhi aplikasi yang memanggil salah satu fungsi WNet untuk membuat huruf kandar jaringan di bawah satu masuk pengguna, tetapi kueri untuk huruf drive jaringan yang ada di bawah masuk pengguna yang berbeda. Contoh situasi ini bisa jadi ketika masuk kedua pengguna dibuat dalam sesi masuk, misalnya, dengan memanggil fungsi CreateProcessAsUser , dan masuk kedua menjalankan aplikasi yang memanggil fungsi GetLogicalDrives . GetLogicalDrives tidak mengembalikan huruf kandar jaringan yang dibuat oleh fungsi WNet di bawah masuk pertama. Perhatikan bahwa dalam contoh sebelumnya sesi masuk pertama masih ada, dan contohnya dapat berlaku untuk sesi masuk apa pun, termasuk sesi Layanan Terminal. Untuk informasi selengkapnya, lihat Menentukan Nama Perangkat MS-DOS.
Contoh
Sampel kode berikut menggambarkan cara menggunakan fungsi WNetGetUniversalName untuk mengambil string nama UNC universal yang terkait dengan jalur berbasis drive untuk sumber daya jaringan.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
WCHAR Buffer[1024];
DWORD dwBufferLength = 1024;
UNIVERSAL_NAME_INFO * unameinfo;
REMOTE_NAME_INFO *remotenameinfo;
wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);
unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,
(LPVOID) remotenameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
}
Catatan
Header winnetwk.h mendefinisikan WNetGetUniversalName sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winnetwk.h |
| Pustaka | Mpr.lib |
| DLL | Mpr.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk