Fungsi GetServiceA (nspapi.h)

Artikel
03/15/2023

Fungsi GetService mengambil informasi tentang layanan jaringan dalam konteks sekumpulan namespace default atau namespace layanan tertentu. Layanan jaringan ditentukan oleh jenis dan namanya. Informasi tentang layanan diperoleh sebagai sekumpulan struktur data NS_SERVICE_INFO .

Catatan Fungsi GetService adalah ekstensi khusus Microsoft untuk spesifikasi Windows Sockets 1.1. Fungsi ini usang. Untuk kenyamanan pengembang Windows Sockets 1.1, materi referensi ini disertakan.

Catatan Fungsi yang dirinci dalam Resolusi Nama Independen Protokol menyediakan fungsionalitas yang setara di Windows Sockets 2.

Sintaks

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

Parameter

[in] dwNameSpace

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

Gunakan salah satu konstanta berikut untuk menentukan namespace.

Nilai	Makna
NS_DEFAULT	Sekumpulan namespace default. Sistem operasi meminta 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. NS_DEFAULT adalah nilai yang harus digunakan sebagian besar aplikasi untuk dwNameSpace.
NS_DNS	Sistem Nama Domain 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 menyelesaikan nama komputer ke alamat IP 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	Mencari nama host dan alamat IP di <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 GetService harus menggunakan nilai khusus NS_DEFAULT. Ini memungkinkan klien mendapatkan dengan tanpa mengetahui namespace yang tersedia di internetwork. Administrator sistem menentukan akses namespace layanan. Namespace dapat datang dan pergi tanpa klien harus mengetahui perubahan.

[in] lpGuid

Penunjuk ke pengidentifikasi unik global (GUID) yang menentukan jenis layanan jaringan. File header Svcguid.h menyertakan jenis layanan GUID dari banyak layanan terkenal dalam namespace DNS dan SAP.

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

[in] lpServiceName

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

[in] dwProperties

Sekumpulan bendera bit yang menentukan informasi layanan yang diambil fungsi. Masing-masing konstanta bendera bit ini, selain PROP_ALL, sesuai dengan anggota tertentu dari struktur data SERVICE_INFO . Jika bendera diatur, fungsi menempatkan informasi ke dalam anggota struktur data yang sesuai yang disimpan di *lpBuffer. Bendera bit berikut didefinisikan.

Nilai	Makna
PROP_COMMENT	Jika bendera ini diatur, fungsi menyimpan data di anggota lpComment dari struktur data yang disimpan di *lpBuffer.
PROP_LOCALE	Jika bendera ini diatur, fungsi menyimpan data di anggota lpLocale dari struktur data yang disimpan di *lpBuffer.
PROP_DISPLAY_HINT	Jika bendera ini diatur, fungsi menyimpan data di anggota dwDisplayHint dari struktur data yang disimpan di *lpBuffer.
PROP_VERSION	Jika bendera ini diatur, fungsi menyimpan data di anggota dwVersion dari struktur data yang disimpan di *lpBuffer.
PROP_START_TIME	Jika bendera ini diatur, fungsi menyimpan data di anggota dwTime struktur data yang disimpan di *lpBuffer.
PROP_MACHINE	Jika bendera ini diatur, fungsi menyimpan data di anggota lpMachineName dari struktur data yang disimpan di *lpBuffer.
PROP_ADDRESSES	Jika bendera ini diatur, fungsi menyimpan data di anggota lpServiceAddress dari struktur data yang disimpan di *lpBuffer.
PROP_SD	Jika bendera ini diatur, fungsi menyimpan data di anggota ServiceSpecificInfo dari struktur data yang disimpan di *lpBuffer.
PROP_ALL	Jika bendera ini diatur, fungsi menyimpan data di semua anggota struktur data yang disimpan di *lpBuffer.

[out] lpBuffer

Penunjuk ke buffer untuk menerima array struktur NS_SERVICE_INFO dan informasi layanan terkait. Setiap struktur NS_SERVICE_INFO berisi informasi layanan dalam konteks namespace layanan tertentu. Perhatikan bahwa jika dwNameSpace NS_DEFAULT, fungsi menyimpan lebih dari satu struktur ke dalam buffer; jika tidak, hanya satu struktur yang disimpan.

Setiap struktur NS_SERVICE_INFO berisi struktur SERVICE_INFO . Anggota struktur SERVICE_INFO ini akan berisi data yang valid berdasarkan bendera bit yang diatur dalam parameter dwProperties . Jika bendera bit anggota yang sesuai tidak diatur dalam dwProperties, nilai anggota tidak ditentukan.

Fungsi ini menyimpan struktur NS_SERVICE_INFO dalam array berturut-turut, dimulai di awal buffer. Penunjuk dalam struktur SERVICE_INFO yang terkandung menunjuk ke informasi yang disimpan dalam buffer antara akhir struktur NS_SERVICE_INFO dan akhir buffer.

[in, out] lpdwBufferSize

Penunjuk ke variabel yang, pada input, berisi ukuran, dalam byte, dari buffer yang ditujukkan oleh lpBuffer. Pada output, variabel ini berisi jumlah byte yang diperlukan untuk menyimpan informasi yang diminta. Jika nilai output ini lebih besar dari nilai input, fungsi telah gagal karena ukuran buffer yang tidak mencukup.

[in, optional] lpServiceAsyncInfo

Disiapkan untuk penggunaan masa mendatang. Harus diatur ke NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah struktur NS_SERVICE_INFO yang disimpan dalam *lpBuffer. Nol menunjukkan bahwa tidak ada struktur yang disimpan.

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

Kode kesalahan	Makna
ERROR_INSUFFICIENT_BUFFER	Buffer yang ditujukkan oleh lpBuffer terlalu kecil untuk menerima semua informasi yang diminta. Panggil fungsi dengan buffer setidaknya sebesar nilai yang dikembalikan dalam *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND	Layanan yang ditentukan tidak ditemukan, atau namespace yang ditentukan tidak digunakan. Nilai pengembalian fungsi adalah nol dalam kasus ini.

Keterangan

Catatan

Header nspapi.h mendefinisikan GetService sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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