Fungsi GetAddressByNameA (nspapi.h)

Artikel
03/15/2023

[GetAddressByName tidak lagi tersedia untuk digunakan pada Windows Sockets 2. Sebagai gantinya, gunakan fungsi yang terperinci dalam Resolusi Nama Independen Protokol.]

Fungsi GetAddressByName meminta namespace layanan, atau sekumpulan namespace default, untuk mengambil informasi alamat jaringan untuk layanan jaringan tertentu. Proses ini dikenal sebagai resolusi nama layanan. Layanan jaringan juga dapat menggunakan fungsi untuk mendapatkan informasi alamat lokal yang dapat digunakan dengan fungsi ikatan .

Sintaks

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

Parameter

[in] dwNameSpace

Namespace layanan, atau sekumpulan namespace default, yang harus dikueri sistem operasi untuk informasi alamat jaringan.

Gunakan salah satu konstanta berikut untuk menentukan namespace.

Nilai	Makna
NS_DEFAULT	Sekumpulan namespace default. Fungsi ini mengkueri setiap namespace dalam set ini. Kumpulan namespace default biasanya mencakup semua namespace layanan yang diinstal pada sistem. Namun, administrator sistem dapat mengecualikan namespace tertentu dari set. Ini adalah nilai yang harus digunakan sebagian besar aplikasi untuk dwNameSpace.
NS_DNS	Sistem Nama Domain (DNS) yang digunakan di Internet untuk resolusi nama host.
NS_NETBT	NetBIOS melalui lapisan TCP/IP. Semua sistem operasi mendaftarkan nama komputer mereka dengan NetBIOS. Namespace ini digunakan untuk mengonversi nama komputer ke alamat IP yang menggunakan pendaftaran ini. Perhatikan bahwa NS_NETBT dapat mengakses server WINS untuk melakukan resolusi.
NS_SAP	Protokol Iklan Layanan NetWare. Ini dapat mengakses bindery NetWare jika sesuai. NS_SAP adalah namespace dinamis yang memungkinkan pendaftaran layanan.
NS_TCPIP_HOSTS	Nilai pencarian dalam <file systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Mekanisme resolusi nama TCP/IP lokal, termasuk perbandingan dengan nama host lokal dan mencari nama host dan alamat IP dalam cache pemetaan host ke alamat IP.

Sebagian besar panggilan ke GetAddressByName harus menggunakan nilai khusus NS_DEFAULT. Ini memungkinkan klien mendapatkan dengan tanpa pengetahuan tentang namespace layanan mana yang tersedia di internetwork. Administrator sistem menentukan akses namespace layanan. Namespace dapat datang dan pergi tanpa klien harus mengetahui perubahan.

[in] lpServiceType

Penunjuk ke pengidentifikasi unik global (GUID) yang menentukan jenis layanan jaringan. File header Svcguid.h menyertakan definisi dari beberapa jenis layanan GUID, dan makro untuk bekerja dengannya.

File header Svcguid.h tidak secara otomatis disertakan oleh file header Winsock2.h.

[in, optional] lpServiceName

Penunjuk ke string yang dihentikan nol yang secara unik mewakili nama layanan. Misalnya, "SERVER SNA SAYA".

Mengatur lpServiceName ke NULL setara dengan pengaturan dwResolution ke RES_SERVICE. Fungsi ini beroperasi dalam mode kedua, mendapatkan alamat lokal tempat layanan dari jenis yang ditentukan harus mengikat. Fungsi ini menyimpan alamat lokal dalam anggota LocalAddr dari struktur CSADDR_INFO yang disimpan ke dalam *lpCsaddrBuffer.

Jika dwResolution diatur ke RES_SERVICE, fungsi akan mengabaikan parameter lpServiceName .

Jika dwNameSpace diatur ke NS_DNS, *lpServiceName adalah nama host.

[in, optional] lpiProtocols

Penunjuk ke array pengidentifikasi protokol yang dihentikan nol. Fungsi ini membatasi upaya resolusi nama untuk penyedia namespace layanan yang menawarkan protokol ini. Ini memungkinkan penelepon membatasi cakupan pencarian.

Jika lpiProtocols diatur ke NULL, fungsi mengambil informasi tentang semua protokol yang tersedia.

[in] dwResolution

Sekumpulan bendera bit yang menentukan aspek proses resolusi nama layanan. Bendera bit berikut didefinisikan.

Nilai	Makna
RES_SERVICE	Jika diatur, fungsi mengambil alamat tempat layanan dari jenis yang ditentukan harus mengikat. Ini setara dengan mengatur parameter lpServiceName ke NULL. Jika bendera ini jelas, resolusi nama normal terjadi.
RES_FIND_MULTIPLE	Jika bendera ini diatur, sistem operasi melakukan pencarian ekstensif dari semua namespace layanan untuk layanan. Ini meminta setiap namespace layanan yang sesuai untuk menyelesaikan nama layanan. Jika bendera ini jelas, sistem operasi berhenti mencari alamat layanan segera setelah ditemukan.
RES_SOFT_SEARCH	Bendera ini valid jika namespace mendukung beberapa tingkat pencarian. Jika bendera ini valid dan diatur, sistem operasi melakukan pencarian namespace layanan yang sederhana dan cepat. Ini berguna jika aplikasi hanya perlu mendapatkan alamat yang mudah ditemukan untuk layanan. Jika bendera ini valid dan jelas, sistem operasi melakukan pencarian namespace yang lebih luas.

Nilai

Makna

RES_SERVICE

Jika diatur, fungsi mengambil alamat tempat layanan dari jenis yang ditentukan harus mengikat. Ini setara dengan mengatur parameter lpServiceName ke NULL.

Jika bendera ini jelas, resolusi nama normal terjadi.

RES_FIND_MULTIPLE

Jika bendera ini diatur, sistem operasi melakukan pencarian ekstensif dari semua namespace layanan untuk layanan. Ini meminta setiap namespace layanan yang sesuai untuk menyelesaikan nama layanan. Jika bendera ini jelas, sistem operasi berhenti mencari alamat layanan segera setelah ditemukan.

RES_SOFT_SEARCH

Bendera ini valid jika namespace mendukung beberapa tingkat pencarian.

Jika bendera ini valid dan diatur, sistem operasi melakukan pencarian namespace layanan yang sederhana dan cepat. Ini berguna jika aplikasi hanya perlu mendapatkan alamat yang mudah ditemukan untuk layanan.

Jika bendera ini valid dan jelas, sistem operasi melakukan pencarian namespace yang lebih luas.

[in, optional] lpServiceAsyncInfo

Dicadangkan untuk digunakan di masa mendatang; harus diatur ke NULL.

[out] lpCsaddrBuffer

Penunjuk ke buffer untuk menerima satu atau beberapa struktur data CSADDR_INFO . Jumlah struktur yang ditulis ke buffer tergantung pada jumlah informasi yang ditemukan dalam upaya resolusi. Anda harus berasumsi bahwa beberapa struktur akan ditulis, meskipun dalam banyak kasus hanya akan ada satu.

[in, out] lpdwBufferLength

Penunjuk ke variabel yang, setelah input, menentukan ukuran, dalam byte, dari buffer yang ditunjukkan oleh lpCsaddrBuffer.

Setelah output, variabel ini berisi jumlah total byte yang diperlukan untuk menyimpan array struktur CSADDR_INFO . Jika nilai ini kurang dari atau sama dengan nilai input *lpdwBufferLength, dan fungsi berhasil, ini adalah jumlah byte yang benar-benar disimpan dalam buffer. Jika nilai ini lebih besar dari nilai input *lpdwBufferLength, buffer terlalu kecil, dan nilai output *lpdwBufferLength adalah ukuran buffer minimal yang diperlukan.

[in, out] lpAliasBuffer

Penunjuk ke buffer untuk menerima informasi alias untuk layanan jaringan.

Jika namespace mendukung alias, fungsi menyimpan array string nama nol yang dihentikan ke dalam buffer yang ditunjukkan oleh lpAliasBuffer. Ada terminator nol ganda di akhir daftar. Nama depan dalam array adalah nama utama layanan. Nama yang mengikuti adalah alias. Contoh namespace layanan yang mendukung alias adalah DNS.

Jika namespace tidak mendukung alias, namespace menyimpan terminator nol ganda ke dalam buffer.

Parameter ini bersifat opsional, dan dapat diatur ke NULL.

[in, out] lpdwAliasBufferLength

Penunjuk ke variabel yang, setelah input, menentukan ukuran, dalam elemen (karakter), dari buffer yang ditujukkan oleh lpAliasBuffer.

Setelah output, variabel ini berisi jumlah total elemen (karakter) yang diperlukan untuk menyimpan array string nama. Jika nilai ini kurang dari atau sama dengan nilai input *lpdwAliasBufferLength, dan fungsi berhasil, ini adalah jumlah elemen yang benar-benar disimpan dalam buffer. Jika nilai ini lebih besar dari nilai input *lpdwAliasBufferLength, buffer terlalu kecil, dan nilai output *lpdwAliasBufferLength adalah ukuran buffer minimal yang diperlukan.

Jika lpAliasBuffer adalah NULL, lpdwAliasBufferLength tidak ada artinya dan juga bisa NULL.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah struktur data CSADDR_INFO yang ditulis ke buffer yang ditunjukkan oleh lpCsaddrBuffer.

Jika fungsi gagal, nilai yang dikembalikan adalah SOCKET_ERROR( –1). Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError, yang mengembalikan nilai kesalahan yang diperluas berikut.

Kode kesalahan	Makna
ERROR_INSUFFICIENT_BUFFER	Buffer yang ditunjukkan oleh lpCsaddrBuffer terlalu kecil untuk menerima semua struktur CSADDR_INFO yang relevan. Panggil fungsi dengan buffer setidaknya sebesar nilai yang dikembalikan dalam *lpdwBufferLength.

Keterangan

Fungsi ini adalah versi yang lebih kuat dari fungsi gethostbyname . Fungsi GetAddressByName berfungsi dengan beberapa layanan nama.

Catatan Fungsi gethostbyname telah ditolak oleh pengenalan fungsi getaddrinfo . Pengembang yang membuat aplikasi Windows Sockets 2 didesak untuk menggunakan fungsi getaddrinfo alih-alih gethostbyname.

Fungsi GetAddressByName memungkinkan klien mendapatkan alamat Windows Sockets untuk layanan jaringan. Klien menentukan layanan yang diminati berdasarkan jenis layanan dan nama layanannya.

Banyak layanan nama mendukung awalan atau akhiran default yang dipertimbangkan penyedia layanan nama saat menyelesaikan nama layanan. Misalnya, di namespace DNS, jika domain diberi nama "nt.microsoft.com", dan "ftp millikan" disediakan sebagai input, perangkat lunak DNS gagal menyelesaikan "millikan", tetapi berhasil menyelesaikan "millikan.nt.microsoft.com".

Perhatikan bahwa fungsi GetAddressByName dapat mencari alamat layanan dengan dua cara: dalam namespace tertentu, atau dalam sekumpulan namespace default. Dengan menggunakan namespace default, administrator dapat menentukan bahwa namespace tertentu akan dicari untuk alamat layanan hanya jika ditentukan berdasarkan nama. Administrator atau namespace—program penyiapan juga dapat mengontrol urutan pencarian namespace.

Catatan

Header nspapi.h mendefinisikan GetAddressByName 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

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	nspapi.h
Pustaka	Mswsock.lib
DLL	Mswsock.dll

Lihat juga

Bagikan melalui