Fungsi WSCEnumProtocols32 (ws2spi.h)
Fungsi WSCEnumProtocols32 mengambil informasi tentang protokol transportasi yang tersedia.
Sintaks
int WSCEnumProtocols32(
[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 null, informasi tentang semua protokol yang tersedia dikembalikan. Jika tidak, informasi hanya diambil untuk protokol yang tercantum dalam array.
[out] lpProtocolBuffer
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
Arahkan ke kode kesalahan.
Mengembalikan nilai
Jika tidak ada kesalahan yang terjadi, WSCEnumProtocols32 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
WSCEnumProtocols32 adalah WSCEnumProtocols versi 32-bit. Pada komputer 64-bit, semua panggilan tidak secara khusus 32-bit (misalnya, semua fungsi yang tidak berakhiran "32") beroperasi pada katalog 64-bit asli. Proses yang dijalankan pada komputer 64-bit harus menggunakan panggilan fungsi 32-bit tertentu untuk beroperasi pada katalog 32-bit yang ketat dan mempertahankan kompatibilitas. Definisi dan semantik panggilan 32-bit tertentu sama dengan rekan-rekan aslinya.
Fungsi ini 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 bahwa penyedia layanan telah menetapkan 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, WSCEnumProtocols32 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 ditujukkan 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 WSCEnumProtocols32 tidak dapat menghitung beberapa panggilan; buffer yang diteruskan harus cukup besar untuk menahan semua entri yang diharapkan agar fungsi berhasil. Ini mengurangi kompleksitas fungsi dan tidak boleh menimbulkan masalah karena jumlah protokol yang dimuat pada komputer 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 membuat penyedia transportasi default.
Contoh
Contoh berikut menunjukkan penggunaan fungsi WSCEnumProtocols32 untuk digunakan pada platform 64-bit untuk mengambil array struktur WSAPROTOCOL_INFOW untuk protokol yang diinstal pada komputer lokal dalam katalog 32-bit.
#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 = WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols32 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 =
WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols32 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 Vista, Windows XP Professional x64 Edition [hanya aplikasi desktop] |
Server minimum yang didukung | Windows Server 2008, Windows Server 2003 x64 Edition [hanya aplikasi desktop] |
Target Platform | Windows |
Header | ws2spi.h |
Pustaka | Ws2_32.lib |
DLL | Ws2_32.dll |