Windows* Sockets 2
Application Programming Interface
An Interface for Transparent Network Programming
Under Microsoft WindowsTM
Revision 2.2.2
August 7, 1997
Subject to Change Without Notice
Disclaimer and License
THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE.
A LICENSE IS HEREBY GRANTED TO REPRODUCE THIS SPECIFICATION, BUT ONLY IN ITS ENTIRETY AND WITHOUT MODIFICATION. NO OTHER LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY OTHER INTELLECTUAL PROPERTY RIGHTS IS GRANTED HEREIN.
INTEL, MICROSOFT, STARDUST, AND THE OTHER COMPANIES WHOSE CONTRIBUTIONS 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 SUCH IMPLEMENTATION(S) WILL NOT INFRINGE SUCH RIGHTS.
* Third-party trademarks are the property of their respective owners.
Table of Contents
1. Introduction 1
1.1. Intended Audience 2
1.2. Document Organization 2
1.3. Status of This Specification 2
1.4. Document Version Conventions 3
1.5. New And/Or Different in Version 2.2.1 3
1.6. New And/Or Different in Version 2.2.2 3
2. Summary of New Concepts, Additions and Changes for WinSock 2 4
2.1. WinSock 2 Architecture 4
2.1.1. Simultaneous Access to Multiple Transport Protocols 4
2.1.2. Backwards Compatibility For WinSock 1.1 Applications 4
2.1.2.1. Source Code Compatibility 4
2.1.2.2. Binary Compatibility 5
2.2. Making Transport Protocols Available To WinSock 5
2.2.1. Layered Protocols and Protocol Chains 6
2.2.2. Using Multiple Protocols 6
2.2.3. Multiple Provider Restrictions on select() 7
2.3. Function Extension Mechanism 7
2.4. Debug and Trace Facilities 8
2.5. Protocol Independent Name Resolution 8
2.6. Overlapped I/O and Event Objects 8
2.6.1. Event Objects 9
2.6.2. Receiving Completion Indications 10
2.6.2.1. Blocking and Waiting for Completion Indication 10
2.6.2.2. Polling for Completion Indication 10
2.6.2.3. Using socket I/O completion routines 10
2.6.2.4. Summary of overlapped completion indication mechanisms 10
2.6.3. WSAOVERLAPPED Details 11
2.7. Asynchronous Notification Using Event Objects 11
2.8. Quality of Service 12
2.8.1. The QOS Structure 13
2.8.2. QOS Templates 16
2.8.3. Default Values 16
2.9. Socket Groups 16
2.10. Shared Sockets 17
2.11. Enhanced Functionality During Connection Setup and Teardown 17
2.12. Extended Byte Order Conversion Routines 18
2.13. Support for Scatter/Gather I/O 18
2.14. Protocol-Independent Multicast and Multipoint 19
2.15. Summary of New Socket Options 19
2.16. Summary of New Socket Ioctl Opcodes 20
2.17. Summary of New Functions 22
2.17.1. Generic Data Transport Functions 22
2.17.2. Name Registration and Resolution Functions 22
3. Windows Sockets Programming Considerations 24
3.1. Deviation from BSD Sockets 24
3.1.1. Socket Data Type 24
3.1.2. select() and FD_* 24
3.1.3. Error codes - errno, h_errno & WSAGetLastError() 24
3.1.4. Pointers 25
3.1.5. Renamed functions 25
3.1.5.1. close() and closesocket() 25
3.1.5.2. ioctl() and ioctlsocket()/WSAIoctl() 25
3.1.6. Maximum number of sockets supported 26
3.1.7. Include files 26
3.1.8. Return values on function failure 26
3.1.9. Raw Sockets 26
3.2. Byte Ordering 26
3.3. WinSock 1.1 Compatibility Issues 27
3.3.1. Default state for a socket’s overlapped attribute 27
3.3.2. Winsock 1.1 Blocking routines & EINPROGRESS 27
3.4. Graceful shutdown, linger options and socket closure 29
3.5. Out-Of-Band data 30
3.5.1. Protocol Independent OOB data 30
3.5.2. OOB data in TCP 31
3.6. Summary of WinSock 2 Functions 32
3.6.1. BSD Socket Functions 32
3.6.2. Microsoft Windows-specific Extension Functions 33
4. SOCKET LIBRARY REFERENCE 36
4.1. accept() 36
4.2. bind() 38
4.3. closesocket() 40
4.4. connect() 42
4.5. getpeername() 46
4.6. getsockname() 47
4.7. getsockopt() 49
4.8. htonl() 54
4.9. htons() 55
4.10. ioctlsocket() 56
4.11. listen() 58
4.12. ntohl() 60
4.13. ntohs() 61
4.14. recv() 62
4.15. recvfrom() 65
4.16. select() 68
4.17. send() 71
4.18. sendto() 74
4.19. setsockopt() 78
4.20. shutdown() 83
4.21. socket() 85
4.22. WSAAccept() 88
4.23. WSAAsyncSelect() 92
4.24. WSACancelBlockingCall() 100
4.25. WSACleanup() 102
4.26. WSACloseEvent() 103
4.27. WSAConnect() 104
4.28. WSACreateEvent() 109
4.29. WSADuplicateSocket() 110
4.30. WSAEnumNetworkEvents() 113
4.31. WSAEnumProtocols() 116
4.32. WSAEventSelect() 121
4.33. WSAGetLastError() 127
4.34. WSAGetOverlappedResult() 128
4.35. WSAGetQOSByName() 130
4.36. WSAHtonl() 131
4.37. WSAHtons() 132
4.38. WSAIoctl() 133
4.39. WSAIsBlocking() 143
4.40. WSAJoinLeaf() 144
4.41. WSANtohl() 149
4.42. WSANtohs() 150
4.43. WSARecv() 151
4.44. WSARecvDisconnect() 157
4.45. WSARecvFrom() 159
4.46. WSAResetEvent() 165
4.47. WSASend() 166
4.48. WSASendDisconnect() 171
4.49. WSASendTo() 173
4.50. WSASetBlockingHook() 179
4.51. WSASetEvent() 181
4.52. WSASetLastError() 182
4.53. WSASocket() 183
4.54. WSAStartup() 187
4.55. WSAUnhookBlockingHook() 191
4.56. WSAWaitForMultipleEvents() 192
4.57. WSAProviderConfigChange() 194
5. Name Resolution and Registration 196
5.1. Protocol-Independent Name Resolution 196
5.1.1. Name Resolution Model 196
5.1.1.1. Types of Name Spaces 196
5.1.1.2. Name Space Organization 197
5.1.1.3. Name Space Provider Architecture 197
5.1.2. Summary of Name Resolution Functions 198
5.1.2.1. Service Installation 198
5.1.2.2. Client Query 199
5.1.2.3. Helper Functions 199
5.1.3. Name Resolution Data Structures 200
5.1.3.1. Query-Related Data Structures 200
5.1.3.2. Service Class Data Structures 201
5.2. Name Resolution Function Reference 203
5.2.1. WSAAddressToString() 203
5.2.2. WSAEnumNameSpaceProviders() 205
5.2.3. WSAGetServiceClassInfo 207
5.2.4. WSAGetServiceClassNameByClassId() 208
5.2.5. WSAInstallServiceClass() 209
5.2.6. WSALookupServiceBegin() 210
5.2.7. WSALookupServiceEnd() 213
5.2.8. WSALookupServiceNext() 214
5.2.9. WSARemoveServiceClass() 217
4.2.10. WSASetService() 218
5.2.10. WSAStringToAddress() 221
5.3. WinSock 1.1 Compatibile Name Resolution for TCP/IP 222
5.3.1. Introduction 222
5.3.2. Basic Approach 222
5.3.3. getprotobyname and getprotobynumber 222
5.3.4. getservbyname() and getservbyport() 223
5.3.5. gethostbyname() 223
5.3.6. gethostbyaddr() 223
5.3.7. gethostname() 223
5.4. WinSock 1.1 Compatible Name Resolution Reference 224
5.4.1. gethostbyaddr() 224
5.4.2. gethostbyname() 226
5.4.3. gethostname() 228
5.4.4. getprotobyname() 229
5.4.5. getprotobynumber() 231
5.4.6. getservbyname() 232
5.4.7. getservbyport() 234
5.4.8. inet_addr() 236
5.4.9. inet_ntoa() 237
5.4.10. WSAAsyncGetHostByAddr() 238
5.4.11. WSAAsyncGetHostByName() 241
5.4.12. WSAAsyncGetProtoByName() 244
5.4.13. WSAAsyncGetProtoByNumber() 247
5.4.14. WSAAsyncGetServByName() 250
5.4.15. WSAAsyncGetServByPort() 253
5.4.16. WSACancelAsyncRequest() 256
Appendix A. Error Codes and Header Files and Data Types 258
A.1 Error Codes 258
A.1.1 Error Codes - Brief Description 258
A.1.2 Error Codes - Extended Description 260
A.2 Header Files 266
A.2.1 Berkeley Header Files 266
A.2.2 WinSock Header File - Winsock2.h 267
A.2.3 Sizes of Data Types 268
Appendix B. Multipoint and Multicast Semantics 269
B.1. Multipoint and Multicast Introduction 269
B.2 Multipoint Taxonomy 269
B.3 WinSock 2 Interface Elements for Multipoint and Multicast 270
B.3.1. Attributes in WSAPROTOCOL_INFO struct 270
B.3.2. Flag bits for WSASocket() 270
B.3.3. SIO_MULTIPOINT_LOOP command code for WSAIoctl() 271
B.3.4. SIO_MULTICAST_SCOPE command code for WSAIoctl() 271
B.3.5. WSAJoinLeaf() 271
B.4. Semantics for joining multipoint leaves 271
B.4.1. Using WSAJoinLeaf() 272
B.5. Semantic differences between multipoint sockets and regular sockets 273
B.6. How existing multipoint protocols support these extensions 273
B.6.1. IP multicast 273
B.6.2. ATM Point to Multipoint 274
Appendix C. The Lame List 275
Appendix D. For Further Reference 283
D.1 Networking books: 283
D.2 Windows Sockets programming books: 283
Acknowledgments
Windows Sockets Version 2
Since The WinSock Group started the Version 2 specification process in May 1994, hundreds of people, companies and organizations have cooperated and contributed to its design and specification. Several meetings, many emails and telephone conversations later, it’s appropriate to acknowledge the part played by everyone and certain contributors in particular.
Many individuals too numerous to mention have given time to the project and all of them are owed a debt of thanks for the roles they played in creating the most comprehensive open transport API designed to date. The commitment, dedication and energy of the following individuals and companies should be singled out for special attention.
First, the design of WinSock 2 was based on the input of multiple “Functionality Groups” whose leaders cajoled, steered, defined and refined each of their group’s technical proposals. Consequently, we’d like to recognize the following individuals and their employers for the time and effort they have given. It’s appropriate to thank Dave Andersen for the challenge he undertook, met and surpassed in defining the generic API set and pulling together the contributions of all the various Functionality Groups.
Functionality Group / Leader(s) / Email / CompanyGeneric API / Dave Andersen / / Intel
Operating Framework / Keith Moore / / Microsoft
Specification Clarifications / Bob Quinn / / sockets.com
Vikas Garg / / Distinct
Paul Brooks / / Turbosoft
Name Resolution / Margaret Johnson
Cameron Ferroni
Paul Drews /
/ Microsoft
Microsoft
Intel
Connection-Oriented Media / Charlie Tai / / Intel
Sanjay Agrawal Kumar / / Microsoft
Wireless / Dale Buchholz / / Motorola
TCP/IP / Michael Khalandovsky / / FTP Software
IPX/SPX / Tim Delaney / / Novell
DECnet / Cathy Bence / / DEC
OSI / Adrian Dawson / / ICL
The following individuals moderated the WinSock 2 effort as a whole and provided the framework, technical guidance and administrative mechanisms for WinSock Version 2.
Moderator / Email / CompanyMartin Hall / / Stardust Technologies
Dave Treadwell / / Microsoft
Mark Towfiq / / SunSoft
Special thanks to Microsoft and Intel for the amount of time these companies gave to the specification and especially to Dave Treadwell and Keith Moore at Microsoft and Dave Andersen and Charlie Tai at Intel for their considerable editorial efforts on the WinSock 2 specifications.
The SDK for Windows NT and Windows 95 was a project in its own right and was brought about by a joint effort between Microsoft and the Intel Architecture Labs. The Microsoft team included Dave Treadwell, Steve Firebaugh, Keith Moore, Arnold Miller, Francis X. Langlois, Mosin Ahmed, Chris Steck and Dave Beaver. The Intel team included Dave Andersen, Dave Doerner, Paul Drews, Charlie Tai, Dirk Brandewie, Dan Chou, Michael Grafton and Dan Ohlemacher.
This version would not, of course, have been possible without the effort of the contributors to WinSock Version 1.1 and the numerous products that implement and use it. Of special significance to the success of WinSock are the hundreds of shareware and freeware applications that have been developed and continue to emerge. The authors of these packages are some of WinSock’s unsung heroes. It’s fitting to recognize, at least, the role of and contribution made by Peter Tattam’s “Trumpet” WinSock implementation.
We’d like to thank Interop for hosting the kick-off meeting for WinSock Version 2, and Novell for kindly providing the facilities for the meeting that marked the consolidation effort which brought together the work of different groups into a coordinated API and SPI definition.
Sincerely,
Martin Hall
Stardust Technologies
v
Introduction 3
Introduction
This document specifies the Windows Sockets 2 programming interface. Windows Sockets 2 utilizes the sockets paradigm as first popularized in BSD UNIX[1] and as adapted for Microsoft Windows in the Windows Sockets 1.1 specification. While historically sockets programming in general and Windows Sockets programming in particular has been TCP/IP-centric, this is no longer the case. Consequently, it is important to realize that Windows Sockets 2 is an interface and not a protocol. As an interface it is used to discover and utilize the communications capabilities of any number of underlying transport protocols. Because it is not a protocol, it does not in any way affect the “bits on the wire”, and does not need to be utilized on both ends of a communications link.
The motivation in creating version 2 of Windows Sockets was primarily to provide a protocol-independent transport interface that is fully capable of supporting emerging networking capabilities including real-time multimedia communications. Thus Windows Sockets 2 is a true superset of the widely deployed Windows Sockets 1.1 interface. While maintaining full backwards compatibility it extends the Windows Sockets interface in a number of areas including
· Access to protocols other than TCP/IP: WinSock 2 allows an application to use the familiar socket interface to achieve simultaneous access to any number of installed transport protocols.
· Protocol-independent name resolution facilities: WinSock 2 includes a standardized set of APIs for querying and working with the myriad of name resolution domains that exist today (e.g. DNS, SAP, X.500, etc.)
· Overlapped I/O with scatter/gather: following the model established in Win32 environments, WinSock 2 incorporates the overlapped paradigm for socket I/O and incorporates scatter/gather capabilities as well.
· Quality of service: WinSock 2 establishes conventions for applications to negotiate required service levels for parameters such as bandwidth and latency. Other QOS-related enhancements include socket grouping and prioritization, and mechanisms for network-specific QOS extensions.
· Protocol-independent multicast and multipoint: applications can discover what type of multipoint or multicast capabilities a transport provides and use these facilities in a generic manner.
· Other frequently requested extensions: shared sockets, conditional acceptance, exchange of user data at connection setup/teardown time, protocol-specific extension mechanisms.
It is almost always the case that adding more capability and functionality also increases the level of complexity, and Windows Sockets 2 is no exception. We have attempted to mitigate this as much as possible by extending the familiar sockets interface as opposed to starting from scratch. While this approach offers significant benefit to experienced socket programmers, it may occasionally vex them as well since certain widely held assumptions are no longer valid. For example, many sockets programmers assume that all connectionless protocols use SOCK_DGRAM sockets and all connection-oriented protocols use SOCK_STREAM sockets. In WinSock 2 SOCK_DGRAM and SOCK_STREAM are only two of many possible socket types, and programmers should no longer rely on socket type to describe all of the essential attributes of a transport protocol.
With its vastly larger scope, Windows Sockets 2 takes the socket paradigm considerably beyond what it’s original designers contemplated. As a consequence, a number of new functions have been added, all of which are assigned names that are prefixed with “WSA”. In all but a few instances these new functions are expanded versions of an existing function from BSD sockets. The need to retain backwards compatibility mandates that we retain both the “just plain” BSD functions and the new “WSA” versions, which in turn amplifies the perception of WinSock 2 as being large and complex. This stretching of the sockets paradigm also requires us to occasionally dance around areas where the original sockets architecture is on shaky ground. A telling example of this is the unfortunate, but now irrevocable, decision to combine the notions of address family and protocol family.