Fungsi WSCEnumProtocols (ws2spi.h)
Fungsi WSCEnumProtocols mengambil informasi tentang protokol transportasi yang tersedia.
Sintaks
int WSCEnumProtocols(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
Parameter
[in] lpiProtocols
Array nilai iProtocol yang dihentikan NULL. Parameter ini bersifat opsional; jika lpiProtocols adalah 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_INFOW .
[in, out] lpdwBufferLength
Pada input, ukuran buffer lpProtocolBuffer diteruskan ke WSCEnumProtocols, dalam byte. Pada output, ukuran buffer minimum, dalam byte, yang dapat diteruskan ke WSCEnumProtocols untuk mengambil semua informasi yang diminta.
[out] lpErrno
Penunjuk ke kode kesalahan.
Menampilkan nilai
Jika tidak ada kesalahan yang terjadi, WSCEnumProtocols mengembalikan jumlah protokol yang akan dilaporkan. Jika tidak, nilai SOCKET_ERROR dikembalikan dan kode kesalahan tertentu tersedia di lpErrno.
| Kode kesalahan | Makna |
|---|---|
| Salah satu argumen lainnya tidak berada di bagian ruang alamat pengguna yang valid. | |
| 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. |
Keterangan
Fungsi WSCEnumProtocols digunakan untuk menemukan informasi tentang pengumpulan protokol transportasi yang diinstal pada komputer lokal. Fungsi ini berbeda dari rekan API-nya (WSAEnumProtocols) dalam struktur WSAPROTOCOL_INFOW untuk semua protokol yang diinstal dikembalikan. Ini termasuk protokol yang telah ditetapkan penyedia layanan bendera PFL_HIDDEN di anggota dwProviderFlags dari struktur WSAPROTOCOL_INFOW untuk menunjukkan kepada Ws2_32.dll bahwa protokol ini tidak boleh dikembalikan dalam buffer hasil yang dihasilkan oleh fungsi WSAEnumProtocols . Selain itu, WSCEnumProtocols juga mengembalikan data untuk struktur WSAPROTOCOL_INFOW yang memiliki panjang rantai nol ( penyedia LSP dummy). 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_INFOW disediakan dalam buffer yang diacu oleh lpProtocolBuffer untuk setiap protokol yang diminta. Jika buffer yang disediakan tidak cukup besar (seperti yang ditunjukkan oleh nilai input lpdwBufferLength), nilai yang ditunjukkan oleh lpdwBufferLength akan diperbarui untuk menunjukkan ukuran buffer yang diperlukan. Klien Windows Sockets SPI kemudian harus mendapatkan buffer yang cukup besar dan memanggil fungsi ini lagi. Fungsi WSCEnumProtocols tidak dapat menghitung melalui beberapa panggilan; buffer yang diteruskan harus cukup besar untuk menyimpan semua entri yang diharapkan agar fungsi berhasil. Ini mengurangi kompleksitas fungsi dan seharusnya tidak menimbulkan masalah karena jumlah protokol yang dimuat di komputer lokal biasanya kecil.
Urutan di mana struktur WSAPROTOCOL_INFOW muncul di buffer bertepatan dengan urutan di mana entri protokol didaftarkan oleh penyedia layanan dengan WS2_32.dll, atau dengan penyusunan ulang berikutnya yang mungkin telah terjadi melalui applet Soket Windows yang disediakan untuk membangun penyedia transportasi default.
Contoh
Contoh berikut menunjukkan penggunaan fungsi WSCEnumProtocols untuk mengambil array struktur WSAPROTOCOL_INFOW untuk protokol yang diinstal di komputer lokal.
#ifndef UNICODE
#define UNICODE 1
#endif
#include <winsock2.h>
#include <ws2tcpip.h>
#include <ws2spi.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 iNuminfo = 0;
int i;
// Allocate a 16K buffer to retrieve all the protocol providers
DWORD dwBufferLen = 16384;
LPWSAPROTOCOL_INFOW lpProtocolInfo = NULL;
int iErrno = 0;
// 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_INFOW) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation for providers buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo = WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols failed with error: WSAENOBUFS (%d)\n",
iErrno);
wprintf(L" Increasing buffer size to %d\n\n", dwBufferLen);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
lpProtocolInfo = (LPWSAPROTOCOL_INFOW) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation increase for buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo =
WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols 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;
}
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 | ws2spi.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