`
`
`
`
`
`Windows* Sockets 2
`Application Programming
`Interface
`
`An Interface for Transparent Network Programming
`Under Microsoft WindowsTM
`
`Revision 2.2.0
`May 10, 1996
`
`
`
`
`
`
`
`
`Subject to Change Without Notice
`
`
`
`
`
`Ex.1050.001
`
`DELL
`
`

`

`
`
` A
`
`
`
`
`
`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.
` 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.
`
`
`
`
`
`ii
`
`Ex.1050.002
`
` *
`
`
`
`
`
`DELL
`
`

`

`
`
`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.0 ................................................................................................... 3
`2. SUMMARY OF NEW CONCEPTS, ADDITIONS AND CHANGES FOR WINSOCK 2 ................ 6
`2.1. WinSock 2 Architecture ............................................................................................................................ 6
`2.1.1. Simultaneous Access to Multiple Transport Protocols ...................................................................... 6
`2.1.2. Backwards Compatibility For WinSock 1.1 Applications ................................................................. 7
`2.1.2.1. Source Code Compatibility ............................................................................................................................7
`2.1.2.2. Binary Compatibility ......................................................................................................................................7
`2.2. Making Transport Protocols Available To WinSock ................................................................................ 8
`2.2.1. Layered Protocols and Protocol Chains ............................................................................................. 9
`2.2.2. Using Multiple Protocols ................................................................................................................. 10
`2.2.3. Multiple Provider Restrictions on select() ....................................................................................... 10
`2.3. Function Extension Mechanism .............................................................................................................. 10
`2.4. Debug and Trace Facilities ..................................................................................................................... 11
`2.5. Protocol Independent Name Resolution ................................................................................................. 11
`2.6. Overlapped I/O and Event Objects ......................................................................................................... 11
`2.6.1. Event Objects ................................................................................................................................... 12
`2.6.2. Receiving Completion Indications ................................................................................................... 13
`2.6.2.1. Blocking and Waiting for Completion Indication ........................................................................................13
`2.6.2.2. Polling for Completion Indication ...............................................................................................................13
`2.6.2.3. Using socket I/O completion routines ..........................................................................................................13
`2.6.2.4. Summary of overlapped completion indication mechanisms ......................................................................13
`2.6.3. WSAOVERLAPPED Details .......................................................................................................... 14
`2.7. Asynchronous Notification Using Event Objects ................................................................................... 15
`2.8. Quality of Service ................................................................................................................................... 15
`2.8.1. The QOS Structure ........................................................................................................................... 16
`2.8.2. QOS Templates ................................................................................................................................ 19
`2.8.3. Default Values .................................................................................................................................. 19
`2.9. Socket Groups ......................................................................................................................................... 20
`2.10. Shared Sockets ...................................................................................................................................... 20
`2.11. Enhanced Functionality During Connection Setup and Teardown ....................................................... 21
`2.12. Extended Byte Order Conversion Routines .......................................................................................... 21
`2.13. Support for Scatter/Gather I/O .............................................................................................................. 22
`2.14. Protocol-Independent Multicast and Multipoint ................................................................................... 22
`2.15. Summary of New Socket Options ......................................................................................................... 22
`2.16. Summary of New Socket Ioctl Opcodes ............................................................................................... 23
`2.17. Summary of New Functions ................................................................................................................. 24
`2.17.1. Generic Data Transport Functions ................................................................................................. 24
`3. WINDOWS SOCKETS PROGRAMMING CONSIDERATIONS .................................................... 25
`3.1. Deviation from BSD Sockets .................................................................................................................. 25
`3.1.1. Socket Data Type ............................................................................................................................. 25
`3.1.2. select() and FD_* ............................................................................................................................. 25
`3.1.3. Error codes - errno, h_errno & WSAGetLastError() ....................................................................... 25
`3.1.4. Pointers ............................................................................................................................................. 26
`3.1.5. Renamed functions ........................................................................................................................... 26
`3.1.5.1. close() and closesocket() ..............................................................................................................................26
`3.1.5.2. ioctl() and ioctlsocket()/WSAIoctl() ............................................................................................................26
`3.1.6. Maximum number of sockets supported .......................................................................................... 27
`
`
`
`iii
`
`Ex.1050.003
`
`DELL
`
`

`

`
`
`3.1.7. Include files ...................................................................................................................................... 27
`3.1.8. Return values on function failure ..................................................................................................... 27
`3.1.9. Raw Sockets ..................................................................................................................................... 27
`3.2. Byte Ordering .......................................................................................................................................... 27
`3.3. WinSock 1.1 Compatibility Issues .......................................................................................................... 28
`3.3.1. Default state for a socket’s overlapped attribute .............................................................................. 28
`3.3.2. Winsock 1.1 Blocking routines & EINPROGRESS ........................................................................ 28
`3.4. Graceful shutdown, linger options and socket closure ........................................................................... 30
`3.5. Out-Of-Band data .................................................................................................................................... 31
`3.5.1. Protocol Independent OOB data ...................................................................................................... 31
`3.5.2. OOB data in TCP ............................................................................................................................. 33
`3.6. Summary of WinSock 2 Functions ......................................................................................................... 33
`3.6.1. BSD Socket Functions ..................................................................................................................... 33
`3.6.2. Microsoft Windows-specific Extension Functions .......................................................................... 34
`4. SOCKET LIBRARY REFERENCE ...................................................................................................... 37
`4.1. accept() .................................................................................................................................................... 37
`4.2. bind() ....................................................................................................................................................... 39
`4.3. closesocket() ............................................................................................................................................ 41
`4.4. connect() .................................................................................................................................................. 43
`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() ............................................................................................................................................ 82
`4.21. socket() .................................................................................................................................................. 84
`4.22. WSAAccept() ........................................................................................................................................ 86
`4.23. WSAAsyncSelect() ............................................................................................................................... 90
`4.24. WSACancelBlockingCall() ................................................................................................................... 97
`4.25. WSACleanup() ...................................................................................................................................... 99
`4.26. WSACloseEvent() ............................................................................................................................... 101
`4.27. WSAConnect() .................................................................................................................................... 102
`4.28. WSACreateEvent() ............................................................................................................................. 106
`4.29. WSADuplicateSocket() ....................................................................................................................... 107
`4.30. WSAEnumNetworkEvents() ............................................................................................................... 110
`4.31. WSAEnumProtocols() ........................................................................................................................ 113
`4.32. WSAEventSelect() .............................................................................................................................. 118
`4.33. WSAGetLastError() ............................................................................................................................ 123
`4.34. WSAGetOverlappedResult() .............................................................................................................. 124
`4.35. WSAGetQOSByName() ..................................................................................................................... 126
`4.36. WSAHtonl() ........................................................................................................................................ 127
`4.37. WSAHtons() ........................................................................................................................................ 128
`4.38. WSAIoctl() .......................................................................................................................................... 129
`4.39. WSAIsBlocking() ................................................................................................................................ 136
`4.40. WSAJoinLeaf() ................................................................................................................................... 137
`
`iv
`
`Ex.1050.004
`
`DELL
`
`

`

`
`
`4.41. WSANtohl() ........................................................................................................................................ 141
`4.42. WSANtohs() ........................................................................................................................................ 142
`4.43. WSARecv() ......................................................................................................................................... 143
`4.44. WSARecvDisconnect() ....................................................................................................................... 149
`4.45. WSARecvFrom() ................................................................................................................................ 151
`4.46. WSAResetEvent() ............................................................................................................................... 158
`4.47. WSASend() ......................................................................................................................................... 159
`4.48. WSASendDisconnect() ....................................................................................................................... 164
`4.49. WSASendTo() ..................................................................................................................................... 166
`4.50. WSASetBlockingHook() .................................................................................................................... 172
`4.51. WSASetEvent() ................................................................................................................................... 174
`4.52. WSASetLastError() ............................................................................................................................. 175
`4.53. WSASocket() ...................................................................................................................................... 176
`4.54. WSAStartup() ...................................................................................................................................... 180
`4.55. WSAUnhookBlockingHook() ............................................................................................................. 184
`4.56. WSAWaitForMultipleEvents() ........................................................................................................... 185
`5. NAME RESOLUTION AND REGISTRATION ................................................................................ 187
`5.1. Protocol-Independent Name Resolution ............................................................................................... 187
`5.1.1. Name Resolution Model ................................................................................................................ 187
`5.1.1.1. Types of Name Spaces ...............................................................................................................................187
`5.1.1.2. Name Space Organization ..........................................................................................................................188
`5.1.1.3. Name Space Provider Architecture ............................................................................................................188
`5.1.2. Summary of Name Resolution Functions ...................................................................................... 189
`5.1.2.1. Service Installation .....................................................................................................................................189
`5.1.2.2. Client Query ...............................................................................................................................................190
`5.1.2.3. Helper Functions ........................................................................................................................................190
`5.1.3. Name Resolution Data Structures .................................................................................................. 191
`5.1.3.1. Query-Related Data Structures ..................................................................................................................191
`5.1.3.2. Service Class Data Structures ....................................................................................................................193
`5.2. Name Resolution Function Reference .................................................................................................. 195
`5.2.1.5.2.1. WSAAddressToString() ....................................................................................................... 195
`5.2.2. WSAEnumNameSpaceProviders() ............................................................................................... 196
`5.2.3. WSAGetServiceClassInfo .............................................................................................................. 198
`5.2.4. WSAGetServiceClassNameByClassId() ...................................................................................... 199
`5.2.5. WSAInstallServiceClass() ............................................................................................................ 200
`5.2.6. WSALookupServiceBegin() ......................................................................................................... 201
`5.2.7. WSALookupServiceEnd() ............................................................................................................ 204
`5.2.8. WSALookupServiceNext() ........................................................................................................... 205
`5.2.9. WSARemoveServiceClass() ......................................................................................................... 207
`5.2.10. WSASetService() ........................................................................................................................ 208
`5.2.11. WSAStringToAddress() .............................................................................................................. 211
`5.3. ................................................................................................................................................................ 212
`5.4. WinSock 1.1 Compatibile Name Resolution for TCP/IP ..................................................................... 212
`5.4.1. Introduction .................................................................................................................................... 212
`5.4.2. Basic Approach .............................................................................................................................. 212
`5.4.3. getprotobyname and getprotobynumber ........................................................................................ 212
`5.4.4. getservbyname() and getservbyport() ............................................................................................ 213
`5.4.5. gethostbyname() ............................................................................................................................. 213
`5.4.6. gethostbyaddr() .............................................................................................................................. 213
`5.4.7. gethostname() ................................................................................................................................. 213
`5.5. WinSock 1.1 Compatible Name Resolution Reference ........................................................................ 214
`5.5.1. gethostbyaddr() .............................................................................................................................. 214
`5.5.2. gethostbyname() ............................................................................................................................. 216
`5.5.3. gethostname() ................................................................................................................................. 218
`5.5.4. getprotobyname() ........................................................................................................................... 219
`5.5.5. getprotobynumber() ....................................................................................................................... 221
`
`v
`
`Ex.1050.005
`
`DELL
`
`

`

`
`
`5.5.6. getservbyname() ............................................................................................................................. 222
`5.5.7. getservbyport() ............................................................................................................................... 224
`5.5.8. inet_addr() ...................................................................................................................................... 226
`5.5.9. inet_ntoa() ...................................................................................................................................... 227
`5.5.10. WSAAsyncGetHostByAddr() ...................................................................................................... 228
`5.5.11. WSAAsyncGetHostByName() .................................................................................................... 231
`5.5.12. WSAAsyncGetProtoByName() ................................................................................................... 234
`5.5.13. WSAAsyncGetProtoByNumber() ................................................................................................ 237
`5.5.14. WSAAsyncGetServByName() ..................................................................................................... 240
`5.5.15. WSAAsyncGetServByPort() ....................................................................................................... 243
`5.5.16. WSACancelAsyncRequest() ........................................................................................................ 246
`APPENDIX A. ERROR CODES AND HEADER FILES AND DATA TYPES ................................. 248
`A.1 Error Codes ........................................................................................................................................... 248
`A.1.1 Error Codes - Brief Description ..................................................................................................... 248
`A.1.2 Error Codes - Extended Description .............................................................................................. 250
`A.2 Header Files .......................................................................................................................................... 256
`A.2.1 Berkeley Header Files .................................................................................................................... 256
`A.2.2 WinSock Header File - Winsock2.h ............................................................................................... 257
`A.2.3 Sizes of Data Types ........................................................................................................................ 258
`APPENDIX B. MULTIPOINT AND MULTICAST SEMANTICS ..................................................... 259
`B.1. Multipoint and Multicast Introduction ................................................................................................. 259
`B.2 Multipoint Taxonomy ............................................................................................................................ 259
`B.3 WinSock 2 Interface Elements for Multipoint and Multicast ............................................................... 260
`B.3.1. Attributes in WSAPROTOCOL_INFO struct ............................................................................... 260
`B.3.2. Flag bits for WSASocket() ............................................................................................................ 260
`B.3.3. SIO_MULTIPOINT_LOOP command code for WSAIoctl() ....................................................... 261
`B.3.4. SIO_MULTICAST_SCOPE command code for WSAIoctl() ...................................................... 261
`B.3.5. WSAJoinLeaf() ............................................................................................................................. 261
`B.4. Semantics for joining multipoint leaves ............................................................................................... 261
`B.4.1. Using WSAJoinLeaf() ................................................................................................................... 262
`B.5. Semantic differences between multipoint sockets and regular sockets ................................................ 263
`B.6. How existing multipoint protocols support these extensions ............................................................... 263
`B.6.1. IP multicast .................................................................................................................................... 263
`B.6.2. ATM Point to Multipoint .............................................................................................................. 264
`APPENDIX C. THE LAME LIST ........................................................................................................... 265
`APPENDIX D. FOR FURTHER REFERENCE ................................................................................... 272
`D.1 Networking books: ................................................................................................................................ 272
`D.2 Windows Sockets programming books: ................................................................................................ 272
`
`vi
`
`Ex.1050.006
`
`DELL
`
`

`

`
`
`Acknowledgements
`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 Lea