Fungsi EnumProtocolsA (nspapi.h)
Fungsi EnumProtocols mengambil informasi tentang sekumpulan protokol jaringan tertentu yang aktif pada host lokal.
Sintaks
INT EnumProtocolsA(
[in, optional] LPINT lpiProtocols,
[out] LPVOID lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
Parameter
[in, optional] lpiProtocols
Penunjuk ke array pengidentifikasi protokol yang dihentikan null. Fungsi EnumProtocols mengambil informasi tentang protokol yang ditentukan oleh array ini.
Jika lpiProtocolsadalah NULL, fungsi mengambil informasi tentang semua protokol yang tersedia.
Nilai pengidentifikasi protokol berikut ditentukan.
[out] lpProtocolBuffer
Penunjuk ke buffer yang diisi fungsi dengan array struktur data PROTOCOL_INFO .
[in, out] lpdwBufferLength
Penunjuk ke variabel yang, pada input, menentukan ukuran, dalam byte, dari buffer yang diacu oleh lpProtocolBuffer.
Pada output, fungsi mengatur variabel ini ke ukuran buffer minimum yang diperlukan untuk mengambil semua informasi yang diminta. Agar fungsi berhasil, buffer harus setidaknya berukuran ini.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah PROTOCOL_INFO struktur data yang ditulis ke buffer yang ditujukkan oleh lpProtocolBuffer.
Jika fungsi gagal, nilai yang dikembalikan adalah SOCKET_ERROR(–1). Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError, yang mengembalikan kode kesalahan yang diperluas berikut.
| Kode kesalahan | Makna |
|---|---|
|
Buffer yang ditujukkan oleh lpProtocolBuffer terlalu kecil untuk menerima semua struktur PROTOCOL_INFO yang relevan. Panggil fungsi dengan buffer setidaknya sebesar nilai yang dikembalikan dalam *lpdwBufferLength. |
Keterangan
Dalam kode sampel berikut, fungsi EnumProtocols mengambil informasi tentang semua protokol yang tersedia di sistem. Kode kemudian memeriksa setiap protokol secara lebih rinci.
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <Nspapi.h>
#include <stdlib.h>
#include <stdio.h>
// Need to link with Ws2_32.lib and Mswsock.lib
#pragma comment (lib, "Ws2_32.lib")
#pragma comment (lib, "Mswsock.lib")
int FindProtocol(BOOL Reliable,
BOOL MessageOriented, BOOL StreamOriented,
BOOL Connectionless, DWORD *ProtocolUsed);
int __cdecl main(int argc, char **argv)
{
WSADATA wsaData;
int ProtocolError = SOCKET_ERROR;
int iResult;
BOOLEAN bReliable = FALSE;
BOOLEAN bMessageOriented = FALSE;
BOOLEAN bStreamOriented = TRUE;
BOOLEAN bConnectionless = FALSE;
DWORD *pProtocols = NULL;
// Validate the parameters
if (argc != 2) {
printf("usage: %s servicename\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
if (iResult != 0) {
printf("WSAStartup failed with error: %d\n", iResult);
return 1;
}
ProtocolError = FindProtocol( bReliable, bMessageOriented,
bStreamOriented, bConnectionless, pProtocols);
if (ProtocolError == SOCKET_ERROR) {
printf("Unable to find a protocol to support the parameters requested\n");
return 1;
}
// Connect to the servicename ...
return 0;
}
#define MAX_PROTOCOLS 1024
int FindProtocol (
BOOL Reliable,
BOOL MessageOriented,
BOOL StreamOriented,
BOOL Connectionless,
DWORD *ProtocolUsed
)
{
// local variables
INT protocols[MAX_PROTOCOLS+1];
BYTE buffer[2048];
DWORD bytesRequired;
INT err;
PPROTOCOL_INFO protocolInfo;
INT protocolCount;
INT i;
DWORD protocolIndex;
// PCSADDR_INFO csaddrInfo;
// INT addressCount;
// SOCKET s;
// First look up the protocols installed on this computer.
//
bytesRequired = sizeof(buffer);
err = EnumProtocols( NULL, buffer, &bytesRequired );
if ( err <= 0 )
return SOCKET_ERROR;
// Walk through the available protocols and pick out the ones which
// support the desired characteristics.
//
protocolCount = err;
protocolInfo = (PPROTOCOL_INFO)buffer;
for ( i = 0, protocolIndex = 0;
i < protocolCount && protocolIndex < MAX_PROTOCOLS;
i++, protocolInfo++ ) {
// If connection-oriented support is requested, then check if
// supported by this protocol. We assume here that connection-
// oriented support implies fully reliable service.
//
if ( Reliable ) {
// Check to see if the protocol is reliable. It must
// guarantee both delivery of all data and the order in
// which the data arrives.
//
if ( (protocolInfo->dwServiceFlags &
XP_GUARANTEED_DELIVERY) == 0
||
(protocolInfo->dwServiceFlags &
XP_GUARANTEED_ORDER) == 0 ) {
continue;
}
// Check to see that the protocol matches the stream/message
// characteristics requested.
//
if ( StreamOriented &&
(protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)
!= 0 &&
(protocolInfo->dwServiceFlags & XP_PSEUDO_STREAM)
== 0 ) {
continue;
}
if ( MessageOriented &&
(protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)
== 0 ) {
continue;
}
}
else if ( Connectionless ) {
// Make sure that this is a connectionless protocol.
//
if ( (protocolInfo->dwServiceFlags & XP_CONNECTIONLESS)
!= 0 )
continue;
}
// This protocol fits all the criteria. Add it to the list of
// protocols in which we're interested.
//
protocols[protocolIndex++] = protocolInfo->iProtocol;
}
*ProtocolUsed = (INT) protocolIndex;
return 0;
}
Catatan
Header nspapi.h mendefinisikan EnumProtocols 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 |