Fungsi WSAEnumProtocolsA (winsock2.h)
Fungsi WSAEnumProtocols mengambil informasi tentang protokol transportasi yang tersedia.
Sintaks
int WSAAPI WSAEnumProtocolsA(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOA lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
Parameter
[in] lpiProtocols
Array nilai iProtocol yang dihentikan NULL. Parameter ini bersifat opsional; jika lpiProtocolsadalah NULL, informasi tentang semua protokol yang tersedia dikembalikan. Jika tidak, informasi hanya diambil untuk protokol yang tercantum dalam array.
[out] lpProtocolBuffer
Penunjuk ke buffer yang diisi dengan struktur WSAPROTOCOL_INFO .
[in, out] lpdwBufferLength
Pada input, jumlah byte dalam buffer lpProtocolBuffer diteruskan ke WSAEnumProtocols. Pada output, ukuran buffer minimum yang dapat diteruskan ke WSAEnumProtocols untuk mengambil semua informasi yang diminta. Rutinitas ini tidak memiliki kemampuan untuk menghitung melalui beberapa panggilan; buffer yang diteruskan harus cukup besar untuk menyimpan semua entri agar rutinitas berhasil. Ini mengurangi kompleksitas API dan seharusnya tidak menimbulkan masalah karena jumlah protokol yang dimuat di komputer biasanya kecil.
Nilai kembali
Jika tidak ada kesalahan yang terjadi, WSAEnumProtocols mengembalikan jumlah protokol yang akan dilaporkan. Jika tidak, nilai SOCKET_ERROR dikembalikan dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.
| Kode kesalahan | Makna |
|---|---|
| Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini. | |
| Subsistem jaringan gagal. | |
| Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung. | |
| Menunjukkan bahwa salah satu parameter yang ditentukan tidak valid. | |
| Panjang buffer terlalu kecil untuk menerima semua struktur WSAPROTOCOL_INFO yang relevan dan informasi terkait. Teruskan buffer setidaknya sebesar nilai yang dikembalikan dalam lpdwBufferLength. | |
| Satu atau beberapa parameter lpiProtocols, lpProtocolBuffer, atau lpdwBufferLength bukan bagian yang valid dari ruang alamat pengguna. |
Keterangan
Fungsi WSAEnumProtocols digunakan untuk menemukan informasi tentang pengumpulan protokol transportasi yang diinstal di komputer lokal. Protokol berlapis hanya dapat digunakan oleh aplikasi ketika diinstal dalam rantai protokol. Informasi tentang protokol berlapis tidak dikembalikan kecuali untuk penyedia layanan berlapis dummy (LSP) yang diinstal dengan panjang rantai nol di lpProtocolBuffer.
Fungsi WSAEnumProtocols berbeda dari fungsi WSCEnumProtocols dan WSCEnumProtocols32 karena fungsi WSAEnumProtocols tidak mengembalikan struktur WSAPROTOCOL_INFO untuk semua protokol yang diinstal. Fungsi WSAEnumProtocols mengecualikan protokol yang telah ditetapkan penyedia layanan dengan bendera PFL_HIDDEN di anggota dwProviderFlags dari struktur WSAPROTOCOL_INFO untuk menunjukkan kepada Ws2_32.dll bahwa protokol ini tidak boleh dikembalikan dalam buffer hasil yang dihasilkan oleh fungsi WSAEnumProtocols . Selain itu, fungsi WSAEnumProtocols tidak mengembalikan data untuk struktur WSAPROTOCOL_INFO yang memiliki panjang rantai satu atau lebih besar (penyedia LSP). WSAEnumProtocols hanya mengembalikan informasi tentang protokol dasar dan rantai protokol yang tidak memiliki bendera PFL_HIDDEN dan tidak memiliki panjang rantai protokol nol.
Struktur WSAPROTOCOL_INFO disediakan dalam buffer yang diacu oleh lpProtocolBuffer untuk setiap protokol yang diminta. Jika buffer yang ditentukan tidak cukup besar (seperti yang ditunjukkan oleh nilai input lpdwBufferLength ), nilai yang ditunjukkan oleh lpdwBufferLength akan diperbarui untuk menunjukkan ukuran buffer yang diperlukan. Aplikasi kemudian harus mendapatkan buffer yang cukup besar dan memanggil WSAEnumProtocols lagi.
Urutan di mana struktur WSAPROTOCOL_INFO muncul di buffer bertepatan dengan urutan di mana entri protokol didaftarkan oleh penyedia layanan menggunakan WS2_32.DLL, atau dengan penyusunan ulang berikutnya yang terjadi melalui aplikasi Windows Sockets atau DLL yang disediakan untuk membuat penyedia TCP/IP default.
Windows Phone 8: Fungsi WSAEnumProtocolsW didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.
Windows 8.1 dan Windows Server 2012 R2: Fungsi WSAEnumProtocolsW didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Contoh
Contoh berikut menunjukkan penggunaan fungsi WSAEnumProtocols untuk mengambil array struktur WSAPROTOCOL_INFO untuk protokol transportasi yang tersedia.
#ifndef UNICODE
#define UNICODE 1
#endif
#include <winsock2.h>
#include <ws2tcpip.h>
#include <objbase.h>
#include <stdio.h>
// Link with ws2_32.lib and ole32.lib
#pragma comment (lib, "Ws2_32.lib")
#pragma comment (lib, "ole32.lib")
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
// Note: could also use malloc() and free()
int wmain()
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult = 0;
int iError = 0;
INT iNuminfo = 0;
int i;
// Allocate a 16K buffer to retrieve all the protocol providers
DWORD dwBufferLen = 16384;
LPWSAPROTOCOL_INFO lpProtocolInfo = NULL;
// variables needed for converting provider GUID to a string
int iRet = 0;
WCHAR GuidString[40] = { 0 };
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
wprintf(L"WSAStartup failed: %d\n", iResult);
return 1;
}
lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation for providers buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
if (iNuminfo == SOCKET_ERROR) {
iError = WSAGetLastError();
if (iError != WSAENOBUFS) {
wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSAEnumProtocols failed with error: WSAENOBUFS (%d)\n",
iError);
wprintf(L" Increasing buffer size to %d\n\n", dwBufferLen);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation increase for buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
if (iNuminfo == SOCKET_ERROR) {
iError = WSAGetLastError();
wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSAEnumProtocols succeeded with protocol count = %d\n\n",
iNuminfo);
for (i = 0; i < iNuminfo; i++) {
wprintf(L"Winsock Catalog Provider Entry #%d\n", i);
wprintf
(L"----------------------------------------------------------\n");
wprintf(L"Entry type:\t\t\t ");
if (lpProtocolInfo[i].ProtocolChain.ChainLen == 1)
wprintf(L"Base Service Provider\n");
else
wprintf(L"Layered Chain Entry\n");
wprintf(L"Protocol:\t\t\t %ws\n", lpProtocolInfo[i].szProtocol);
iRet =
StringFromGUID2(lpProtocolInfo[i].ProviderId,
(LPOLESTR) & GuidString, 39);
if (iRet == 0)
wprintf(L"StringFromGUID2 failed\n");
else
wprintf(L"Provider ID:\t\t\t %ws\n", GuidString);
wprintf(L"Catalog Entry ID:\t\t %u\n",
lpProtocolInfo[i].dwCatalogEntryId);
wprintf(L"Version:\t\t\t %d\n", lpProtocolInfo[i].iVersion);
wprintf(L"Address Family:\t\t\t %d\n",
lpProtocolInfo[i].iAddressFamily);
wprintf(L"Max Socket Address Length:\t %d\n",
lpProtocolInfo[i].iMaxSockAddr);
wprintf(L"Min Socket Address Length:\t %d\n",
lpProtocolInfo[i].iMinSockAddr);
wprintf(L"Socket Type:\t\t\t %d\n", lpProtocolInfo[i].iSocketType);
wprintf(L"Socket Protocol:\t\t %d\n", lpProtocolInfo[i].iProtocol);
wprintf(L"Socket Protocol Max Offset:\t %d\n",
lpProtocolInfo[i].iProtocolMaxOffset);
wprintf(L"Network Byte Order:\t\t %d\n",
lpProtocolInfo[i].iNetworkByteOrder);
wprintf(L"Security Scheme:\t\t %d\n",
lpProtocolInfo[i].iSecurityScheme);
wprintf(L"Max Message Size:\t\t %u\n", lpProtocolInfo[i].dwMessageSize);
wprintf(L"ServiceFlags1:\t\t\t 0x%x\n",
lpProtocolInfo[i].dwServiceFlags1);
wprintf(L"ServiceFlags2:\t\t\t 0x%x\n",
lpProtocolInfo[i].dwServiceFlags2);
wprintf(L"ServiceFlags3:\t\t\t 0x%x\n",
lpProtocolInfo[i].dwServiceFlags3);
wprintf(L"ServiceFlags4:\t\t\t 0x%x\n",
lpProtocolInfo[i].dwServiceFlags4);
wprintf(L"ProviderFlags:\t\t\t 0x%x\n",
lpProtocolInfo[i].dwProviderFlags);
wprintf(L"Protocol Chain length:\t\t %d\n",
lpProtocolInfo[i].ProtocolChain.ChainLen);
wprintf(L"\n");
}
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 0;
}
Catatan
Header winsock2.h mendefinisikan WSAEnumProtocols 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 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winsock2.h |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.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