Transcription
Windows* Sockets 2Application ProgrammingInterfaceAn Interface for Transparent Network ProgrammingUnder Microsoft WindowsTMRevision 2.2.2August 7, 1997Subject to Change Without Notice
Disclaimer and LicenseTHIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIESWHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY,FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISEARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE.A LICENSE IS HEREBY GRANTED TO REPRODUCE THIS SPECIFICATION, BUTONLY IN ITS ENTIRETY AND WITHOUT MODIFICATION. NO OTHERLICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANYOTHER INTELLECTUAL PROPERTY RIGHTS IS GRANTED HEREIN.INTEL, MICROSOFT, STARDUST, AND THE OTHER COMPANIES WHOSECONTRIBUTIONS ARE ACKNOWLEDGED BELOW DISCLAIM ALL LIABILITY,INCLUDING LIABILITY FOR INFRINGEMENT OF ANY PROPRIETARY RIGHTS,RELATING TO IMPLEMENTATION OF INFORMATION IN THIS SPECIFICATION.SAID COMPANIES DO NOT WARRANT OR REPRESENT THAT SUCHIMPLEMENTATION(S) WILL NOT INFRINGE SUCH RIGHTS.* Third-party trademarks are the property of their respective owners.ii
Table of Contents1. INTRODUCTION .11.1.1.2.1.3.1.4.1.5.1.6.Intended Audience .2Document Organization.2Status of This Specification .2Document Version Conventions .3New And/Or Different in Version 2.2.1.3New And/Or Different in Version 2.2.2.32. SUMMARY OF NEW CONCEPTS, ADDITIONS AND CHANGES FOR WINSOCK 2.42.1. WinSock 2 Architecture.42.1.1. Simultaneous Access to Multiple Transport Protocols .42.1.2. Backwards Compatibility For WinSock 1.1 Applications .42.1.2.1. Source Code Compatibility.42.1.2.2. Binary Compatibility.52.2. Making Transport Protocols Available To WinSock.52.2.1. Layered Protocols and Protocol Chains.62.2.2. Using Multiple Protocols .62.2.3. Multiple Provider Restrictions on select() .72.3. Function Extension Mechanism.72.4. Debug and Trace Facilities .82.5. Protocol Independent Name Resolution .82.6. Overlapped I/O and Event Objects .82.6.1. Event Objects.92.6.2. Receiving Completion king and Waiting for Completion Indication.10Polling for Completion Indication .10Using socket I/O completion routines.10Summary of overlapped completion indication mechanisms .102.6.3. WSAOVERLAPPED Details .112.7. Asynchronous Notification Using Event Objects .112.8. Quality of Service .122.8.1. The QOS Structure .132.8.2. QOS Templates.162.8.3. Default Values .162.9. Socket Groups.162.10. Shared Sockets.172.11. Enhanced Functionality During Connection Setup and Teardown .172.12. Extended Byte Order Conversion Routines .182.13. Support for Scatter/Gather I/O.182.14. Protocol-Independent Multicast and Multipoint .192.15. Summary of New Socket Options.192.16. Summary of New Socket Ioctl Opcodes .202.17. Summary of New Functions.222.17.1. Generic Data Transport Functions .222.17.2. Name Registration and Resolution Functions .223. WINDOWS SOCKETS PROGRAMMING CONSIDERATIONS.243.1. Deviation from BSD Sockets.243.1.1. Socket Data Type.243.1.2. select() and FD *.243.1.3. Error codes - errno, h errno & WSAGetLastError() .243.1.4. Pointers .25iii
3.1.5. Renamed functions.253.1.5.1. close() and closesocket().253.1.5.2. ioctl() and ioctlsocket()/WSAIoctl() .253.1.6. Maximum number of sockets supported .263.1.7. Include files .263.1.8. Return values on function failure.263.1.9. Raw Sockets.263.2. Byte Ordering .263.3. WinSock 1.1 Compatibility Issues.273.3.1. Default state for a socket’s overlapped attribute.273.3.2. Winsock 1.1 Blocking routines & EINPROGRESS .273.4. Graceful shutdown, linger options and socket closure.293.5. Out-Of-Band data .303.5.1. Protocol Independent OOB data.303.5.2. OOB data in TCP.313.6. Summary of WinSock 2 Functions .323.6.1. BSD Socket Functions .323.6.2. Microsoft Windows-specific Extension Functions .334. SOCKET LIBRARY REFERENCE.364.1. accept() .364.2. bind() .384.3. closesocket() .404.4. connect() .424.5. getpeername() .464.6. getsockname().474.7. getsockopt() .494.8. htonl() .544.9. htons().554.10. ioctlsocket() .564.11. listen().584.12. ntohl() .604.13. ntohs().614.14. recv() .624.15. recvfrom().654.16. select() .684.17. send() .714.18. sendto() .744.19. setsockopt().784.20. shutdown() .834.21. socket() .854.22. WSAAccept() .884.23. WSAAsyncSelect().924.24. WSACancelBlockingCall().1004.25. WSACleanup() .1024.26. WSACloseEvent() .1034.27. WSAConnect() .1044.28. WSACreateEvent() .1094.29. WSADuplicateSocket() .1104.30. WSAEnumNetworkEvents().1134.31. WSAEnumProtocols() .1164.32. WSAEventSelect().1214.33. WSAGetLastError().1274.34. WSAGetOverlappedResult() .1284.35. WSAGetQOSByName() .130iv
4.56.4.57.WSAHtonl().131WSAHtons() .132WSAIoctl() .133WSAIsBlocking() .143WSAJoinLeaf().144WSANtohl().149WSANtohs() .150WSARecv() SASendTo() .173WSASetBlockingHook() .179WSASetEvent() .181WSASetLastError() .182WSASocket().183WSAStartup() vents() .192WSAProviderConfigChange().1945. NAME RESOLUTION AND REGISTRATION .1965.1. Protocol-Independent Name Resolution .1965.1.1. Name Resolution Model .1965.1.1.1. Types of Name Spaces .1965.1.1.2. Name Space Organization.1975.1.1.3. Name Space Provider Architecture .1975.1.2. Summary of Name Resolution Functions.1985.1.2.1. Service Installation.1985.1.2.2. Client Query.1995.1.2.3. Helper Functions.1995.1.3. Name Resolution Data Structures .2005.1.3.1. Query-Related Data Structures.2005.1.3.2. Service Class Data Structures .2015.2. Name Resolution Function Reference .2035.2.1. WSAAddressToString().2035.2.2. WSAEnumNameSpaceProviders() .2055.2.3. WSAGetServiceClassInfo.2075.2.4. WSAGetServiceClassNameByClassId().2085.2.5. WSAInstallServiceClass() .2095.2.6. WSALookupServiceBegin() .2105.2.7. WSALookupServiceEnd() .2135.2.8. WSALookupServiceNext().2145.2.9. WSARemoveServiceClass() .2174.2.10. WSASetService().2185.2.10. WSAStringToAddress().2215.3. WinSock 1.1 Compatibile Name Resolution for TCP/IP.2225.3.1. Introduction .2225.3.2. Basic Approach.2225.3.3. getprotobyname and getprotobynumber.2225.3.4. getservbyname() and getservbyport() .2235.3.5. gethostbyname().2235.3.6. gethostbyaddr() .223v
5.3.7. gethostname() .2235.4. WinSock 1.1 Compatible Name Resolution Reference .2245.4.1. gethostbyaddr() .2245.4.2. gethostbyname().2265.4.3. gethostname() .2285.4.4. getprotobyname().2295.4.5. getprotobynumber() .2315.4.6. getservbyname().2325.4.7. getservbyport().2345.4.8. inet addr() .2365.4.9. inet ntoa().2375.4.10. WSAAsyncGetHostByAddr().2385.4.11. WSAAsyncGetHostByName() .2415.4.12. WSAAsyncGetProtoByName() .2445.4.13. WSAAsyncGetProtoByNumber().2475.4.14. WSAAsyncGetServByName().2505.4.15. WSAAsyncGetServByPort() .2535.4.16. WSACancelAsyncRequest() .256APPENDIX A. ERROR CODES AND HEADER FILES AND DATA TYPES .258A.1 Error Codes.258A.1.1 Error Codes - Brief Description.258A.1.2 Error Codes - Extended Description .260A.2 Header Files .266A.2.1 Berkeley Header Files.266A.2.2 WinSock Header File - Winsock2.h.267A.2.3 Sizes of Data Types .268APPENDIX B. MULTIPOINT AND MULTICAST SEMANTICS.269B.1. Multipoint and Multicast Introduction .269B.2 Multipoint Taxonomy .269B.3 WinSock 2 Interface Elements for Multipoint and Multicast.270B.3.1. Attributes in WSAPROTOCOL INFO struct.270B.3.2. Flag bits for WSASocket().270B.3.3. SIO MULTIPOINT LOOP command code for WSAIoctl() .271B.3.4. SIO MULTICAST SCOPE command code for WSAIoctl().271B.3.5. WSAJoinLeaf() .271B.4. Semantics for joining multipoint leaves .271B.4.1. Using WSAJoinLeaf().272B.5. Semantic differences between multipoint sockets and regular sockets.273B.6. How existing multipoint protocols support these extensions .273B.6.1. IP multicast .273B.6.2. ATM Point to Multipoint .274APPENDIX C. THE LAME LIST .
Application Programming Interface An Interface for Transparent Network Programming Under Microsoft WindowsTM Revision 2.2.2 August 7, 1997 Subject to Change Without Notice. ii Disclaimer and License THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTI
