{\rtf1\ansi \deff0\deflang1024{\fonttbl{\f0\froman Times;}{\f1\froman Symbol;}{\f2\fswiss Helvetica;}{\f3\fmodern Courier;}{\f4\froman Times New Roman;}{\f5\fmodern Courier New;}{\f6\fmodern MS LineDraw;}{\f7\fswiss Arial;} {\f8\fswiss Helvetica;}}{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue127;\red0\green127\blue127; \red0\green127\blue0;\red127\green0\blue127;\red127\green0\blue0;\red127\green127\blue0;\red127\green127\blue127;\red192\green192\blue192;}{\stylesheet{\s228\li2880\ri720\tldot\tx8280\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext0 toc 5;}{ \s229\li2160\ri720\tldot\tx8280\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext0 toc 4;}{\s230\li1440\ri720\tldot\tx8280\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext0 toc 3;}{\s231\li720\ri720\tldot\tx8280\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext0 toc 2;}{ \s232\ri720\tldot\tx8280\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext0 toc 1;}{\s233\li2160 \fs20\lang1033 \sbasedon0\snext0 index 7;}{\s234\li1800 \fs20\lang1033 \sbasedon0\snext0 index 6;}{\s235\li1440 \fs20\lang1033 \sbasedon0\snext0 index 5;}{ \s236\li1080 \fs20\lang1033 \sbasedon0\snext0 index 4;}{\s237\li720 \fs20\lang1033 \sbasedon0\snext0 index 3;}{\s238\li360 \fs20\lang1033 \sbasedon0\snext0 index 2;}{\s239 \fs20\lang1033 \sbasedon0\snext0 index 1;}{\s240 \fs20\lang1033 \sbasedon0\snext0 line number;}{\s241 \fs20\lang1033 \sbasedon0\snext239 index heading;}{\s242\tqc\tx4320\tqr\tx8640 \fs20\lang1033 \sbasedon0\snext242 footer;}{\s243\sa120\brdrb\brdrth\brdrw30\brsp20 \tqc\tx4320\tqr\tx8640 \b\f2\lang1033 \sbasedon0\snext243 header;}{\s244 \fs16\up6\lang1033 \sbasedon0\snext0 footnote reference;}{\s245 \fs20\lang1033 \sbasedon0\snext245 footnote text;}{\s246\li720 \i\fs20\lang1033 \sbasedon0\snext255 heading 9;}{\s247\li720 \i\fs20\lang1033 \sbasedon0\snext255 heading 8;}{\s248\li720 \i\fs20\lang1033 \sbasedon0\snext255 heading 7;}{\s249\li720 \fs20\ul\lang1033 \sbasedon0\snext255 heading 6;}{\s250\li720 \b\fs20\lang1033 \sbasedon0\snext255 heading 5;}{\s251\li360 \b\fs20\lang1033 \sbasedon0\snext255 heading 4;}{\s252\li360 \b\fs20\lang1033 \sbasedon0\snext255 heading 3;}{\s253\sb120 \b\f7\fs20\lang1033 \sbasedon0\snext0 heading 2;}{\s254\sb240 \b\f7\fs20\ul\lang1033 \sbasedon0\snext0 heading 1;}{\s255\li720 \fs20\lang1033 \sbasedon0\snext255 Normal Indent;}{\fs20\lang1033 \snext0 Normal;}{\s2\fi-1440\li1440 \fs20\lang1033 \sbasedon0\snext2 desc;}{\s3\fi-1080\li1080 \b\f7\fs20\lang1033 \sbasedon0\snext3 include;}{\s4\fi-1080\li1080 \b\f7\fs20\lang1033 \sbasedon0\snext4 syntax;}{\s5\fi-1440\li1440 \fs20\lang1033 \sbasedon0\snext12 descrip;}{\s6\fi-1440\li2880 \fs20\ul\lang1033 \sbasedon0\snext6 param;}{\s7\fi-1440\li1440 \fs20\lang1033 \sbasedon0\snext7 returns;}{\s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 \sbasedon0\snext11 errors;}{\s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 \sbasedon0\snext9 see;}{\s10\fi-1440\li2880 \fs20\lang1033 \sbasedon6\snext10 paramtext;}{\s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 \sbasedon8\snext11 errors2;}{\s12\li1440 \fs20\lang1033 \sbasedon5\snext12 descrip2;}{\s13\fi-1440\li2880 \fs20\lang1033 \sbasedon0\snext13 returns2;}{\s14\li1440 \fs20\lang1033 \sbasedon0\snext14 returns3;}{\s15\li2160 \fs20\lang1033 \sbasedon10\snext15 val;}{\s16\li2160 \fs20\ul\lang1033 \sbasedon0\snext16 val1;}{\s17\li2160 \fs20\lang1033 \sbasedon0\snext17 val2;}{\s18\fi-360\li1800\tx3600 \fs20\lang1033 \sbasedon12\snext18 descrip3;}{\s19\fi-2160\li3600\tx3600 \fs20\lang1033 \sbasedon18\snext19 descrip4;}{\s20\fi-1440\li3600 \fs20\ul\lang1033 \sbasedon16\snext20 val3;}{\s21\fi-1440\li3600 \fs20\lang1033 \sbasedon17\snext21 val4;}{\s22\fi-1440\li1440 \fs20\lang1033 \sbasedon0\snext22 notes;}{\s23\li1440 \fs20\lang1033 \sbasedon0\snext23 notes2;}{\s24\fi-2160\li3600 \fs20\ul\lang1033 \sbasedon0\snext24 Notes3;}{\s25\fi-2160\li3600\tx4320 \fs20\lang1033 \sbasedon0\snext25 Notes4;}{\s26\fi-1440\li1440 \fs20\lang1033 \sbasedon0\snext26 comments;}{ \s27\fi-2160\li3600\tx4140\tx5760 \fs20\ul\lang1033 \sbasedon0\snext27 errors3;}{\s28\li1440 \fs20\lang1033 \sbasedon0\snext28 errors4;}{\s29\li1440 \f5\fs20\lang1033 \sbasedon12\snext29 code;}{\s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 \sbasedon0\snext30 hdr-file-code;}{\s31\keep\keepn \f5\fs16\lang1033 \sbasedon30\snext31 err-table;}{\s32\fi-1440\li2880 \f5\fs20\lang1033 \sbasedon10\snext32 paramcode;}{\s33\keepn \b\fs20\lang1033 \snext33 NormalHead;}{\s34\qc\sa240 \b\f7\lang1033 \sbasedon252\snext34 Title;}{\s35\sa240 \b\f7\fs20\lang1033 \sbasedon34\snext35 Title2;}{\s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \sbasedon3\snext36 Function;}}{\info{\title WinSockAPI}{\subject WinSockAPI Specification Version 1.0} {\author Joel S Goldberger}{\operator Joel Goldberger}{\creatim\yr1992\mo6\dy10\hr20\min37}{\revtim\yr1993\mo2\dy8\hr22\min34}{\printim\yr1993\mo1\dy22\hr22\min21}{\version38}{\edmins1238}{\nofpages124}{\nofwords31477}{\nofchars219848}{\vern16431}} \paperw12240\paperh15840\margl1800\margr1800\margt1440\margb1440\gutter0 \facingp\widowctrl\ftnbj\revbar0\revprop0 \sectd \linex0\endnhere {\headerl \pard\plain \s243\sa120\tqc\tx4320\tqr\tx8640 \b\f2\lang1033 \par }{\headerr \pard\plain \s243\qr\sa120\brdrb\brdrth\brdrw30\brsp20 \tqc\tx4320\tqr\tx8640 \b\f2\lang1033 Appendix C: Background Information {\field{\*\fldinst PAGE}{\fldrslt 1}} \par }\pard\plain \s2\qc\fi-1440\li1440 \fs20\lang1033 {\f7\fs16\up6 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Index}}}{\f7 }{\f7\fs16\up6 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Windows Sockets Index}}}{\f7 }{\f7\fs16\up6 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0005}}}{\b\f7\fs32 Windows Sockets} \par \pard \s2\qc\fi-1440\li1440 {\b\f7\fs28 An Open Interface for \par }{\b\f7\fs28 Network Programming under \par }\pard \s2\qc\fi-1440\li1440 {\b\f7\fs28 Microsoft}{\field\flddirty{\*\fldinst {\b\f7\fs16 SYMBOL 226 \\f "Symbol"}}{\fldrslt }}{\b\f7\fs34 }{\b\f7\fs28 Windows}{\field\flddirty{\*\fldinst {\b\f7\fs16\dn6 SYMBOL 228 \\f }{\b\f7\fs16\dn6 "Symbol"} }{\fldrslt }}{\b\f7\fs16\dn6 \par }\pard \s2\qc\fi-1440\li1440 {\b\f7 \par }\pard \s2\qc\fi-1440\li1440 {\b\f7\fs28 Version 1.1 \par }\pard \s2\qc\fi-1440\li1440 {\plain \b\f7\lang1033 20 January 1993 \par }\pard \s2\qc\fi-1440\li1440 {\b\f7\fs28\ul \par }\pard\plain \li720 \fs20\lang1033 {\b\f8\ul Authors and Copyright}{\v\f8 WinSock_Authors}{\f8 \par }{\b\f8\uldb Acknowledgements}{\v\f8 WinSock_Acknowledgements}{\b\f8\uldb \par }{\b\f8\uldb Introduction}{\v\f8 WinSock_Intro}{\b\f7 \par }{\b\f8\uldb Programming with Sockets}{\v\f8 WinSock_ProgrammingWithSockets}{\b\f7 \par }{\b\f8\uldb Socket Library Overview}{\v\f8 WinSock_SocketLibraryOverview}{\b\f7 \par }{\b\f8\uldb Socket Library Reference}{\v\f8 WinSock_SocketLibraryReference}{\f8 \par }\pard \li720 {\b\f8 Appendices \par }\pard \li1080 {\b\f8 Error Codes and Header Files \par }\pard \li1440 {\b\f8\uldb Error Codes}{\v\f8 Winsock_ErrorCodes}{\b\f7 \par }{\b\f8\uldb Header Files}{\v\f8 Winsock_HeaderFiles}{\b\f7 \par }\pard \li1080 {\b\f8\uldb Notes for Windows Sockets Suppliers}{\v\f8 WinSock_NotesForSuppliers}{\f8 \par }{\b\f8\uldb For Further Reference}{\v\f8 Winso}{\v\f8 ck_FurtherReference}{\f8 \par }\pard \li1080 {\b\f8 Background Information \par }\pard \li1440 {\b\f8\uldb Origins of Windows Sockets}{\v\f8 Winsock_Origins}{\b\f7 \par }{\b\f8\uldb Legal Status of Windows Sockets}{\v\f8 Winsock_LegalStatus}{\f8 \par }{\b\f8\uldb The Story Behind the Windows Socket Icon}{\v\f8 Winsock_IconStory}{\f8 \par }\pard \li720 {\b\f8\ul Windows Sockets in Windows Help}{\v\f8 Winsock_WinHelp}{\f8 \par }\pard \li1440\ri1440 {\f8 \page }{\f2\fs16\up6 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\up6 #}{\f7 WinSock_WinHelp}}}{\f8\fs22 }{\f7 This Windows Help version of the Windows Socket 1.1 Specification is provided by InfoMagic, Inc. It may be freely redistributed, either as provided or in modified form. Winsock providers may integrate it into their product documentation without incurrin }{\f7 g any o}{\f7 bligation to InfoMagic, Inc. The source .rtf file is available from microdyne.com via anonymous FTP along with the other WIndows Sockets material.}{\b\f7 \par }\pard \qc {\b\f7\fs28\ul \page }{\f7\fs16\up6 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Authors}}}{\f7 Martin Hall \par }\pard \qc {\f7 Mark Towfiq \par }{\f7 Geoff Arnold \par }{\f7 David Treadwell \par }{\f7 Henry Sanders \par }\pard\plain \s2\qc\fi-1440\li1440 \fs20\lang1033 {\b\f7\fs28\ul \par }\pard\plain \qc \fs20\lang1033 {\f7 Copyright }{\field\flddirty{\*\fldinst {\f7 SYMBOL 211 \\f "Symbol"}}{\fldrslt }}{\f7 1992 by Martin Hall, Mark Towfiq \par }\pard \qc {\f7 Geoff Arnold, David Treadwell and Henry Sanders \par }{\f7 \par }{\f7 All rights reserved. \par }{\f7 \par }\pard \qj\li1440\ri1440 {\f7\revised This document may be freely redistributed in any form, electronic or otherwise, provided that it is distributed in its entirety and that the co}{\f7\revised pyright and this notice are included. Comments or questions may be submitted via electronic mail to winsock@microdyne.com. Requests to be added to the Windows Sockets mailing list should be addressed to winsock-request@microdyne.com. This specification }{\f7\revised , archives of the mailing list, and other information on Windows Sockets are available via anonymous FTP from the host microdyne.com, directory /pub/winsock. Questions about products conforming to this specification should be addressed to the vendors of }{\f7\revised th}{\f7\revised e products.}{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Acknowledgements}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Acknowledgements}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0007}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Acknowledgements}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised Acknowledgments \par }\pard\plain \fs20\lang1033 \par \pard {\f7\revised The authors would like to thank their companies for allowing them the time and resources to make this specification possible: JSB Corporation, Microdyne Corporation, FTP Software, Sun Microsystems, and Microsoft Corporation. \par }\pard {\f7 \par }\pard {\f7\revised Special thanks should also be extended to the other efforts contributing to the success of Windows Sockets. The original draft was heavily influenced by existing specifications offered and detailed by JSB Corporation and Net }{ \f7\revised Manage, Inc. The "version 1.0 debate" hosted by Microsoft in Seattle allowed many of the members of the working group to hash out final details for 1.0 vis-a-vis. \par }\pard {\f7 \par }\pard {\f7\revised Sun Microsystems was kind enough to allow first time implementors to "plug and play" beta software during the first Windows Sock-A-Thon of Windows Sockets applications and implementations at Interop Fall '92. Microsoft has shared WSAT (the Windows Socke }{\f7\revised ts API Tester) with other Windows Sockets implementors as a standard Windows Sockets test }{\f7\revised suite to aid in testing their implementations. Finally, Sun Microsystems and FTP Software plan to host the Windows Sock-A-Thon II in Boston February '93. \par }\pard {\f7 \par }\pard {\f7\revised Without the contributions of the individuals and corporations involved in the working group, Windows Sockets would never have been as thoroughly reviewed and completed as quickly. In just one year, several competitors in the networking business developed }{\f7\revised a useful specification with something to show for it! Many thanks to all which participated, either}{\f7\revised in person or on e-mail to the Windows Sockets effort. The authors would like to thank everyone who participated in any way, and apologize in advance for anyone we have omitted. \par }\pard {\f7 \par }{\f7\revised List of contributors: \par }{\f7 \par }\pard \tx1620\tx3240\tx5490 {\f7\revised Martin Hall \tab (Chairman)\tab JSB Corporation}{\f7 \tab }{\f7\revised martinh@jsbus.com \par }{\f7\revised Mark Towfiq \tab (Coordinator)\tab Microdyne Corporation\tab towfiq@microdyne.com \par }{\f7\revised Geoff Arnold \tab (Editor 1.0)\tab Sun Microsystems\tab geoff@east.sun.com \par }{\f7\revised David Treadwell\tab (Editor 1.1)\tab Microsoft Corporation\tab davidtr@microsoft.com \par }{\f7\revised Henry Sanders\tab \tab Microsoft Corporation\tab }{\f7\revised henrysa@microsoft.com \par }\pard {\f7 \par }\pard \tx2520\tqr\tx7200\tx8640 {\f7\revised J. Allard\tab }{\f7 Microsoft Corporation\tab jallard@microsoft.com \par }{\f7\revised Chris Arap-Bologna\tab Distinct\tab chris@distinct.com \par }{\f7\revised Larry Backman\tab }{\f7 FTP Software\tab }{\f7\revised backman@ftp.com \par }{\f7 Alistair Banks\tab Microsoft Corporation\tab alistair@microsoft.com \par }{\f7\revised Rob Barrow\tab }{\f7 JSB Corporation\tab }{\f7\revised robb@jsb.co.uk \par }{\f7 Carl Beame\tab Beame & Whiteside\tab beame@mcmaster,ca \par }{\f7\revised Dave Beaver\tab }{\f7 Microsoft Corporation\tab dbeaver@microsoft.com \par }{\f7 Amatzia BenArtzi\tab NetManage, Inc.\tab amatzia@netmanage.com \par }{\f7 Mark Beyer\tab Ungermann-Bass\tab mbeyer@ub.com \par }{\f7 Nelson Bolyard\tab Silicon Graphics, I}{\f7 nc.\tab nelson@sgi.com \par }{\f7 Pat Bonner\tab Hewlett-Packard\tab p_bonner@cnd.hp.com \par }{\f7\revised Derek Brown\tab }{\f7 FTP Software\tab }{\f7\revised db@wco.ftp.com \par }{\f7\revised Malcolm Butler\tab ICL\tab mcab@oasis.icl.co.uk \par }{\f7\revised Mike Calbaum\tab Fronteir Technologies\tab mike@frontiertech.com \par }{\f7 Isaac Chan\tab Microsoft Corporation\tab isaacc@microsoft.com \par }{\f7\revised Khoji Darbani\tab Informix\tab khoji@informix.com \par }{\f7 Nestor Fesas\tab Hughes LAN Systems\tab nestor@hls.com \par }{\f7\revised Karanja Gakio\tab }{\f7 FTP Software\tab }{\f7\revised karanja@ftp.com \par }{\f7\revised Vikas Garg\tab Distinct\tab vikas@distinct.com \par }{\f7 Gary Gere\tab Gupta\tab ggere@gupta.com \par }{\f7\revised Jim Gilroy\tab }{\f7 Microsoft Corporation\tab }{\f7\revised jamesg@m}{\f7\revised icrosoft.com \par }{\f7 Bill Hayes\tab Hewlett-Packard\tab billh@hpchdpc.cnd.hp.com \par }{\f7 Paul Hill\tab MIT\tab pbh@athena.mit.edu \par }{\f7\revised Tmima Koren\tab Net Manage, Inc.\tab tmima@netmanage.com \par }{\f7 Hoek Law\tab Citicorp\tab law@dcc.tti.com \par }{\f7 Graeme Le Roux\tab Moresdawn P/L\tab - \par }{\f7\revised Kevin Lewis\tab Novell\tab kevinl@novell.com \par }{\f7\revised Roger Lin\tab }{\f7 3Com\tab }{\f7\revised roger_lin@3mail.3com.com \par }{\f7 Terry Lister\tab Hewlett-Packard\tab tel@cnd.hp.com \par }{\f7\revised Jeng Long Jiang\tab }{\f7 Wollongong\tab }{\f7\revised long@twg.com \par }{\f7 Lee Murach\tab Network Research\tab lee@nrc.com \par }{\f7\revised Pete Ostenson\tab }{\f7 Microsoft Corporation\tab }{\f7\revised peteo@microsoft.com \par }{\f7 David Pool\tab Spry, Inc.\tab dave@spry}{\f7 .com \par }{\f7\revised Bob Quinn\tab }{\f7 FTP Software\tab }{\f7\revised rcq@ftp.com \par }{\f7\revised Glenn Reitsma\tab }{\f7 Hughes LAN Systems\tab }{\f7\revised glennr@hls.com \par }{\f7 Brad Rice\tab Age\tab rice@age.com \par }{\f7 Allen Rochkind\tab 3Com\tab - \par }{\f7\revised Jonathan Rosen\tab IBM\tab jrosen@vnet.ibm.com \par }{\f7\revised Steve Stokes\tab Novell\tab stoke@novell.com \par }{\f7\revised Joseph Tsai\tab }{\f7 3Com\tab }{\f7\revised joe_tsai@3mail.3com.com \par }{\f7 James Van Bokkelen\tab FTP Software\tab jbvb@ftp.com \par }{\f7 Miles Wu\tab Wollongong\tab wu@twg.com \par }{\f7 Boris Yanovsky\tab NetManage, Inc.\tab boris@netmanage.com \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Intro}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Introduction}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Introduction}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Introduction \par \pard\plain \fs20\lang1033 {\b\f7\uldb What is Windows Sockets}{\v\f7 WinSock_WhatIs}{\b\f7 \par }{\b\f7\uldb Berkeley Sockets}{\v\f7 WinSock_Berkeley}{\b\f7 \par }{\b\f7\uldb Micro}{\b\f7\uldb soft Windows and Windows-specific extensions}{\v\f7 WinSock_Windows}{\b\f7 \par }{\b\f7\uldb The Status of this Specification}{\v\f7 WinSock_Status}{\f7 \par }{\b\f7\uldb Revision History}{\v\f7 WinSock_Revision}{\b\f7 \par }\pard\plain \s254 \b\f7\fs20\ul\lang1033 \page {\plain \f7\fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_WhatIs}}}{\plain \b\f7\fs20\lang1033 }{\plain \f7\fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 What is Windows Socket}}}{\plain \b\f7\fs20\lang1033 }{\plain \f7\fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockIntro:0010}}}{\plain \b\f7\fs20\lang1033 Introduction \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 What is Windows Sockets \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets specification defines a network programming interface for Microsoft Windows which is based on the "socket" paradigm popularized in the Berkeley Software Distribution (BSD) from the University of California at Berkeley. It encompasses }{\f7 both familiar Berkeley socket style routines and a set of Windows-}{\f7 specific extensions designed to allow the programmer to take advantage of the message-driven nature of Windows. \par }\pard {\f7 \par }\pard {\f7 The Windows Sockets Specification is intended to provide a single API to which application developers can program and multiple network software vendors can conform. Furthermore, in the context of a particular version of Microsoft Windows, it defines a bi }{\f7 nary interface (ABI) such that an application written to the Windows Sockets API can work with a conformant protocol implementation from any n}{\f7 etwork software vendor. This specification thus defines the library calls and associated semantics to which an application developer can program and which a network software vendor can implement. \par }\pard {\f7 \par }\pard {\f7 Network software which conforms to this Windows Sockets specification will be considered "Windows Sockets Compliant". Suppliers of interfaces which are "Windows Sockets Compliant" shall be referred to as "Windows Sockets Suppliers". To be Windows Socket }{\f7 s Compliant, a vendor must implement 100% of this Windows}{\f7 Sockets specification. \par }\pard {\f7 \par }\pard {\f7 Applications which are capable of operating with any "Windows Sockets Compliant" protocol implementation will be considered as having a "Windows Sockets Interface" and will be referred to as "Windows Sockets Applications". \par }\pard {\f7 \par }\pard {\f7 This version of the Windows Sockets specification defines and documents the use of the API in conjunction with the Internet Protocol Suite (IPS, generally referred to as TCP/IP). Specifically, all Windows Sockets implementations support both stream (TCP) }{\f7 and}{\f7 datagram (UDP) sockets. \par }\pard {\f7 \par }\pard {\f7 While the use of this API with alternative protocol stacks is not precluded (and is expected to be the subject of future revisions of the specification), such usage is beyond the scope of this version of the specification. \par }\pard {\f7 \par }\pard\plain \s254 \b\f7\fs20\ul\lang1033 \page {\plain \f7\fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Berkeley}}}{\plain \b\f7\fs20\lang1033 }{\plain \f7\fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Berkeley Socket}}}{\plain \b\f7\fs20\lang1033 }{\plain \f7\fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockIntro:0020}}}{\plain \b\f7\fs20\lang1033 }{\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Berkeley Sockets}}}{\plain \b\f7\fs20\lang1033 Introduction \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 Berkeley Sockets \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets Specification has been built upon the Berkeley Sockets programming model which is the de facto standard for TCP/IP networking. It is intended to provide a high degree of familiarity for programm}{\f7 ers who are used to programming with sockets in UNIX and other environments, and to simplify the task of porting existing sockets-based source code. The Windows Sockets API is consistent with release 4.3 of the Berkeley Software Distribution (4.3BSD). \par }\pard {\f7 \par }\pard {\f7 Portions of the Windows Sockets specification are derived from material which is Copyright (c) 1982-1986 by the Regents of the University of California. All rights are reserved. The Berkeley Software License Agreement specifies the terms and conditions }{\f7 f}{\f7 or redistribution. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \f7\fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Windows}}} {\plain \f7\fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Microsoft Windows and Windows-specific extension}}} {\plain \f7\fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockIntro:0030}}} Introduction \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 Microsoft Windows and Windows-specific extensions \par \pard\plain \fs20\lang1033 {\f7 This API is intended to be usable within all implementations and versions of Microsoft Windows from Microsoft Windows Version 3.0 onwards. It thus provides for Windows Sockets implementations and Windows Sockets applications in both 16 and 32 bit operati }{\f7 ng environments. \par }\pard {\f7 \par }\pard {\f7 Windows Sockets makes provisions for multithreaded Windows processes. A process contains one or more threads of execution. In the Windows}{\f7 3.1 non-multithreaded world, a task corresponds to a process with a single thread. All references to threads in this document refer to actual "threads" in multithreaded Windows environments. In non multithreaded environments (such as Windows 3.0), use }{\f7 of the term thread refers to a Windows process. \par }\pard {\f7 \par }\pard {\f7 The Microsoft Windows extensions included in Windows Sockets are provided to allow application developers to create software which conforms to the Windows programming model. It is expected that this will f}{\f7 acilitate the creation of robust and high-performance applications, and will improve the cooperative multitasking of applications within non-preemptive versions of Windows. With the exception of }{\b\f7\uldb WSAStartup()}{\v\f7 WinSock_Startup}{\f7 and }{\b\f7\uldb WSACleanup()}{\v\f7 WinSock_Cleanup}{\f7 their use is not mandatory. \par }\pard {\f7 \par }\pard \sa240 \page {\b\fs16\up6 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Status}}} {\b\fs16\up6 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 The Status of this Specification}}} {\b\fs16\up6 + {\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockIntro:0040}}} {\fs16\up6 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Status of the Spec}}} {\b\f7 Introduction}{\f7 \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 The Status of this Specification \par \pard\plain \fs20\lang1033 {\f7\revised Windows Sockets is an independent specification which was created and exists for the benefit of application developers and network vendors and, indirectly, computer use}{\f7\revised rs. Each published (non-draft) version of this specification represents a fully workable API for implementation by network vendors and programming use by application developers. Discussion of this specification and suggested improvements continue and ar }{\f7\revised e welcomed. Such discussion occurs mainly via the Internet electronic mail forum winsock@microdyne.com. Meetings of interested parties occur on an irregular basis. Details of these meetings are publicized to the electronic mail forum. \par }\pard \sa240 {\f7 \page }{\b\fs16\up6 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Revision}}} {\b\fs16\up6 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Revision History}}} {\b\fs16\up6 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockIntro:0050}}} {\fs16\up6 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Revision History}}} {\b\f7 Introductio}{\b\f7 n}{\f7 \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 Revision History \par \pard\plain \s252\li360 \b\fs20\lang1033 {\f7\revised Windows Sockets Version 1.0 \par }\pard\plain \fs20\lang1033 {\f7\revised Windows Sockets Version 1.0 represented the results of considerable work within the vendor and user community as discussed in }{\f7 "}{\f7\uldb Origins of Windows Sockets}{\v\f7 Winsock_Origins}{\f7 "}{ \f7\revised . This version of the specification was released in order that network software suppliers and application developers could begin to construct implementations and applications which conformed to the Windows Sockets standard. \par }\pard {\f7 \par }\pard\plain \s252\li360 \b\fs20\lang1033 {\f7\revised Windows Sockets Version 1.1 \par }\pard\plain \fs20\lang1033 {\f7\revised Windows Sockets Version 1.1 follo}{\f7\revised ws the guidelines and structure laid out by version 1.0, making changes only where absolutely necessary as indicated by the experiences of a number of companies that created Windows Sockets implementations based on the version 1.0 specification. Version }{\f7\revised 1.1 contains several clarifications and minor fixes to version 1.0. Additionally, the following more significant changes were incorporated into version 1.1: \par }\pard\plain \s255\li720 \fs20\lang1033 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Inclusion of the }{\b\f7\uldb\revised gethostname()}{\v\f7 Winsock_gethostname}{\b\f7\revised }{\f7\revised routine to s}{ \f7\revised implify retrieval of the host's name and address. \par }\pard \s255\li720 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Definition of DLL ordinal values below 1000 as reserved for Windows Sockets and ordinals above 1000 as unrestricted. This allows Windows Sockets vendors to include private interfaces to their DLLs without risking that the ordinals choosen will conflict w }{\f7\revised ith a future version of Windows Sockets. \par }\pard \s255\li720 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Addition of a reference count to }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{\f7\revised and }{ \b\f7\uldb\revised WSACleanup()}{\v\f7 Winsock_Cleanup}{\f7\revised , requiring correspondences between the calls. This allows applications and third-party DLLs to make use of a Windows Sockets implementation without being concerned about the calls to these APIs made by the other. \par }\pard \s255\li720 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Change of return type of }{\b\f7\uldb\revised inet_addr()}{\v\f7 Winsock_InetAddr}{\b\f7\revised }{\f7\revised from }{ \b\f7\revised struct in_addr}{\f7\revised to }{\b\f7\revised unsigned long}{\f7\revised . This was required due to different handling of four-byte structure returns between the Microsoft and Borland C compilers. \par }\pard \s255\li720 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Change of}{\f7\revised }{\b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 Winsock_AsyncSelect}{\b\f7\revised }{\f7\revised semantics from "edge-triggerred" to "level-triggerred". The level-triggerred semantics significantly simplify an application's use of this routine. \par }\pard \s255\li720 {\f7 \par }\pard \s255\fi-360\li1080 {\field{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Change the }{\b\f7\uldb\revised ioctlsocket()}{\v\f7 Winsock_ioctlsocket}{\b\f7\revised }{\f7\revised FIONBIO semantics to fail if a }{\b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 Winsock_AsyncSelect}{\b\f7\revised }{\f7\revised call is outstanding on the socket.}{\f7 \par }\pard \s255\fi-360\li1080 {\f7 \par }{\field\flddirty{\*\fldinst {\f7 SYMBOL 183 \\f "Symbol" \\s 10 \\h}}{\fldrslt }}{\f7 \tab }{\f7\revised Addition of the TCP_NODELAY socket option for RFC 1122 conformance. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \f7\fs20\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_ProgrammingWithSockets}}}{\plain \f7\fs20\lang1033 }{\plain \f7\fs20\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Programming with Sockets}}}{\plain \f7\fs20\lang1033 }{\plain \f7\fs20\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0020}}}{\plain \f7\fs20\lang1033 } Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Programming with Sockets{\ul \par }\pard\plain \fs20\lang1033 {\b\f8\uldb Windows Sockets Stack Installation Checking}{\v\f8 WinSockProg_StackInstall}{\b\f7 \par }{\b\f8\uldb Sockets}{\v\f8 WinSockProg_Sockets}{\b\f7 \par }{\b\f8\uldb Byte Ordering}{\v\f8 WinSockProg_ByteOrdering}{\b\f7 \par }{\b\f8\uldb Socket Options}{\v\f8 WinSockProg_SocketOptions}{\b\f7 \par }{\b\f8\uldb Database Files}{\v\f8 WinSockProg_DatabaseFiles}{\b\f7 \par }{\b\f8\uldb Deviation from Berkeley Sockets}{\v\f8 WinSockProg_Deviation}{\f8 \par }{\b\f8\uldb Windows Sockets in Multithreaded Versions of Windows}{\v\f8 WinsockProg_MultithreadedWindows}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_StackInstall}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Windows Sockets Stack Installation Checking}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Installation Check}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Windows Sockets Stack Installation Checking \par \pard\plain \fs20\lang1033 {\f7 To detect the presence of one (or many) Windows Sockets i}{\f7 mplementations on a system, an application which has been linked with the Windows Sockets Import Library may simply call the }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 routine. If an application wishes to be a little more sophisticated it can examine the $PATH environment variable and search for instances of Windows Sockets implementations (WINSOCK.DLL). For each instance it can issue a }{\b\f7 LoadLibrary()}{\f7 call and use the }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 routine to discover implementation specific data. \par }\pard {\f7 \par }\pard {\f7 This version of the Win}{\f7 dows Sockets specification does not attempt to address explicitly the issue of multiple concurrent Windows Sockets implementations. Nothing in the specification should be interpreted as restricting multiple Windows Sockets DLLs from being present and use }{\f7 d concurrently by one or more Windows Sockets applications. \par }\pard {\f7 \par }\pard {\f7\revised For further details of where to obtain Windows Sockets components, see }{\f7 "}{\f7\uldb Windows Sockets Components}{\v\f7 WinSockNotes_WindowsComponents}{\f7 "}{\f7\revised . \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_Sockets}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 Sockets}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Berkeley Sockets}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Sockets \par \pard\plain \fs20\lang1033 {\f7 The following ma}{\f7 terial is derived from the document "An Advanced 4.3BSD Interprocess Communication Tutorial" by Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley, Steve Miller, and Chris Torek. \par }\pard {\f7 \par }\pard {\b\f8\uldb Basic concepts}{\v\f8 WinSockSockets_BasicConcepts}{\b\f7 \par }{\b\f8\uldb Client-server model}{\v\f8 WinSockSockets_ClientServer}{\b\f7 \par }{\b\f8\uldb Out-of-band data}{\v\f8 WinSockSockets_OutOfBand}{\b\f7 \par }{\b\f8\uldb Broadcasting}{\v\f8 WinSockSockets_Broadcasting}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockSockets_BasicConcepts}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Basic concepts}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSock:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets} }} Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Basic concepts \par \pard\plain \fs20\lang1033 {\f7 The basic building block for communication is the socket. A socket is an endpoint of communication to wh}{\f7 ich a name may be bound. Each socket in use has a type and an associated process. Sockets exist within communication domains. A communication domain is an abstraction introduced to bundle common properties of threads communicating through sockets. Soc }{\f7 kets normally exchange data only with sockets in the same domain (it may be possible to cross domain boundaries, but only if some translation process is performed). The Windows Sockets facilities support a single communication domain: the Internet domain }{\f7 , }{\f7 which is used by processes which communicate using the Internet Protocol Suite. (Future versions of this specification may include additional domains.) \par }\pard {\f7 \par }\pard {\f7 Sockets are typed according to the communication properties visible to a user. Applications are presumed to communicate only between sockets of the same type, although there is nothing that prevents communication between sockets of different types should }{\f7 the underlying communication protocols support this. \par }\pard {\f7 \par }\pard {\f7 Two types of sockets currently are availa}{\f7 ble to a user. A stream socket provides for the bi-directional, reliable, sequenced, and unduplicated flow of data without record boundaries. \par }\pard {\f7 \par }\pard {\f7 A datagram socket supports bi-directional flow of data which is not promised to be sequenced, reliable, or unduplicated. That is, a process receiving messages on a datagram socket may find messages duplicated, and, possibly, in an order different from th }{\f7 e order in which it was sent. An important characteristic of a datagram socket is that record boundaries in }{\f7 data are preserved. Datagram sockets closely model the facilities found in many contemporary packet switched networks such as Ethernet. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockSockets_ClientServer}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Client-server model}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSock:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Client-server model \par \pard\plain \fs20\lang1033 {\f7 The most commonly used paradigm in constructing distributed applications is the client/server model. In this scheme client applications request services from a server application. This implies an asymmetry in establishing communication between the clien }{\f7 t and server. \par }\pard {\f7 \par }\pard {\f7 The client and server require a well-known set of convent}{\f7 ions before service may be rendered (and accepted). This set of conventions comprises a protocol which must be implemented at both ends of a connection. Depending on the situation, the protocol may be symmetric or asymmetric. In a symmetric protocol, e }{\f7 ither side may play the master or slave roles. In an asymmetric protocol, one side is immutably recognized as the master, with the other as the slave. An example of a symmetric protocol is the TELNET protocol used in the Internet for remote terminal emu }{\f7 la}{\f7 tion. An example of an asymmetric protocol is the Internet file transfer protocol, FTP. No matter whether the specific protocol used in obtaining a service is symmetric or asymmetric, when accessing a service there is a "client process'' and a "server p }{\f7 rocess''. \par }\pard {\f7 \par }\pard {\f7 A server application normally listens at a well-known address for service requests. That is, the server process remains dormant until a connection is requested by a client's connection to the server's address. At such a time the server proc} {\f7 ess "wakes up'' and services the client, performing whatever appropriate actions the client requests of it. While connection-based services are the norm, some services are based on the use of datagram sockets. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockSockets_OutOfBand}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Out-of-band data}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSock:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Out-of-band data \par \pard\plain \box\brdrsh\brdrs\brdrw30\brsp40 \fs20\lang1033 {\f7 Note: The following discussion of out-of-band data, also referred to as TCP Urgent data, follows the model used in the Berkeley software distribution. Users and implementors should be aware of the fact that there are at present two conflicting interpret }{\f7 ation}{\f7 s of RFC 793 (in which the concept is introduced), and that the implementation of out-of-band data in the Berkeley Software Distribution does not conform to the Host Requirements laid down in RFC 1122. To minimize interoperability problems, applications }{\f7 writers are advised not to use out-of-band data unless this is required in order to interoperate with an existing service. Windows Sockets suppliers are urged to document the out-of-band semantics (BSD or RFC 1122) which their product implements. It is }{\f7 be}{\f7 yond the scope of this specification to mandate a particular set of semantics for out-of-band data handling. \par }\pard {\f7 \par }\pard {\f7 The stream socket abstraction includes the notion of "out of band'' data. Out-of-band data is a logically independent transmission channel associated with each pair of connected stream sockets. Out-of-band data is delivered to the user independently of }{\f7 normal data. The abstraction defines that the out-of-band data facilities must support the reliable delivery of at least one out-of-band message}{\f7 at a time. This message may contain at least one byte of data, and at least one message may be pending delivery to the user at any one time. For communications protocols which support only in-band signaling (i.e. the urgent data is delivered in sequen }{\f7 ce with the normal data), the system normally extracts the data from the normal data stream and stores it separately. This allows users to choose between receiving the urgent data in order and receiving it out of sequence without having to buffer all the }{\f7 i}{\f7 ntervening data. It is possible to "peek'' at out-of-band data. \par }\pard {\f7 \par }\pard {\f7 An application may prefer to process out-of-band data "in-line", as part of the normal data stream. This is achieved by setting the socket option SO_OOBINLINE (see }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 ). In this case, the application may wish to determine whether any of the unread data is "urgent" (the term usually applied to in-line out-of-band data). To facilitate this, the Windows Sockets implementation will maintain a logical "mark" in th}{\f7 e data stream to indicate the point at which the out-of-band data was sent. An application can use the SIOCATMARK }{\b\f7\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSocket}{\f7 command to determine whether there is any unread data preceding the mark. For example, it might use this to resynchronize with its peer by ensuring that all data up to the mark in the data stream is discarded when appropriate. \par }\pard {\f7 \par }\pard {\f7 The }{\b\f7\uldb WSAAsyncSelect()}{\v\f8 WinSock_AsyncSelect}{\f7 routine is particularly well suited to handling notification of the presence of out-of-band-d}{\f7 ata. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockSockets_Broadcasting}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Broadcasting}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSock:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Broadcasting \par \pard\plain \fs20\lang1033 {\f7 By using a datagram socket, it is possible to send broadcast packets on many networks supported by the system. The network itself must support broadcast: the system provides no simulation of broadcast in software. Broadcast messages can place a high loa }{\f7 d on a network, since they force every host on the network to service them. Consequently, the ability to send broadcast packets has been limited to sockets which are explicitly marked as allowing broadcasting. Broad}{\f7 cast is typically used for one of two reasons: it is desired to find a resource on a local network without prior knowledge of its address, or important functions such as routing require that information be sent to all accessible neighbors. \par }\pard {\f7 \par }\pard {\f7 The destination address of the message to be broadcast depends on the network(s) on which the message is to be broadcast. The Internet domain supports a shorthand notation for broadcast on the local network, the address INADDR_BROADCAST. Received broadc }{\f7 ast messages c}{\f7 ontain the senders address and port, as datagram sockets must be bound before use. \par }\pard {\f7 \par }\pard {\f7 Some types of network support the notion of different types of broadcast. For example, the IEEE 802.5 token ring architecture supports the use of link-level broadcast indicators, which control whether broadcasts are forwarded by bridges. The Windows Soc }{\f7 kets specification does not provide any mechanism whereby an application can determine the type of underlying network, nor any way to control the semantics of broadcasting}{\f7 . \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_ByteOrdering}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Byte Ordering}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}} } Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Byte Ordering \par \pard\plain \fs20\lang1033 {\f7 The Intel byte ordering is like that of the DEC VAX, and therefore differs from the Internet and 68000-type processor byte ordering. Thus care must be taken to ensure correct orientation. \par }\pard {\f7 \par }\pard {\f7\revised Any reference to IP addresses or port numbers passed to or from a Windows Sockets routine must be in network order. This includes the IP address and port fields of a }{\b\f7\revised struct sockaddr_in}{\f7\revised (but not the }{ \i\f7\revised sin_family}{\f7\revised field). \par }\pard {\f7 \par }\pard {\f7 Consider an application which normally conta}{\f7 cts a server on the TCP port corresponding to the "time" service, but which provides a mechanism for the user to specify that an alternative port is to be used. The port number returned by }{ \b\f7\uldb getservbyname()}{\v\f8 WinSock_GetServByName}{\f7 is already in network order, which is the format required constructing an address, so no translation is required. However if the user elects to use a different port, entered as an integer, the application must convert this from host to network order (us }{\f7 ing the }{\b\f7\uldb htons()}{\v\f8 WinSock_HtoNS}{\f7 fu}{\f7 nction) before using it to construct an address. Conversely, if the application wishes to display the number of the port within an address (returned via, e.g., }{\b\f7\uldb getpeername()}{\v\f8 WinSock_GetPeerName}{\f7 ), the port number must be converted from network to host order (using }{\b\f7\uldb ntohs()}{\v\f8 WinSock_NtoHS}{\f7 ) before it can be displayed. \par }\pard {\f7 \par }\pard {\f7 Since the Intel and Internet byte orders are different, the conversions described above are unavoidable. Application writers are cautioned that they should use the standard conversion functions }{\f7 provided as part of the Windows Sockets API rather than writing their own conversion code, since future implementations of Windows Sockets are likely to run on systems for which the host order is identical to the network byte order. Only applications whi }{\f7 ch use the standard conversion functions are likely to be portable. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_SocketOptions}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Socket Options}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets} }} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Socket Options \par \pard\plain \s15 \fs20\lang1033 {\f7 The socket options supported by Windows Sockets are listed in the pages describing }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 and }{\b\f7\uldb getsockopt()}{\v\f8 WinSo}{\v\f8 ck_GetSockOpt}{\f7 . A Windows Sockets implementation must recognize all of these options, and (for }{\b\f7\uldb getsockopt()}{\v\f8 WinSock_GetSockOpt}{\f7 ) return plausible values for each. The default value for each option is shown in the following table. \par }\pard \s15 {\f7 \par }\pard\plain \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 \fs20\lang1033 {\b\f7\ulw Value\tab Type\tab Meaning\tab Default\tab Note \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 SO_ACCEPTCON\tab BOOL\tab Socket is }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\f7 ing.\tab FALSE unless \par }{\f7 \tab \tab \tab a }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\f7 has \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 \tab \tab \tab been performed\tab \par }{\f7 SO_BROADCAST\tab BOOL\tab Socket is configured\tab FALSE \par }{\f7 \tab \tab for the transmission of \par }{\f7 \tab \tab broadcast messages.\tab \par }{\f7 SO_DEBUG\tab BOOL\tab Debugging is e}{\f7 nabled. \tab FALSE\tab (i) \par }{\f7 SO_DONTLINGER\tab BOOL\tab If true, the SO_LINGER\tab TRUE \par }{\f7 \tab \tab option is disabled..\tab \tab \par }{\f7 SO_DONTROUTE\tab BOOL\tab Routing is disabled.\tab FALSE\tab (i) \par }{\f7 SO_ERROR\tab int\tab Retrieve error status\tab 0 \par }{\f7 \tab \tab and clear.\tab \par }{\f7 SO_KEEPALIVE\tab BOOL\tab Keepalives are being\tab FALSE \par }{\f7 \tab \tab sent.\tab \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 SO_LINGER\tab struct linger FAR *\tab Returns the current\tab }{\i\f7 l_onoff}{\f7 is 0 \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 \tab \tab linger options.\tab }{\i\f7 \par }{\f7 SO_OOBINLINE\tab BOOL\tab Out-of-band data is\tab FALSE \par }{\f7 \tab \tab being received in the \par }{\f7 \tab \tab normal data stream.\tab \par }{\f7 SO_RCVBUF\tab int\tab Buffer size for receives\tab Implementation \par }{\f7 \tab \tab \tab dependant.\tab (i) \par }{\f7 SO_REU}{\f7 SEADDR\tab BOOL\tab The address to which\tab FALSE \par }{\f7 \tab \tab this socket is bound \par }{\f7 \tab \tab can be used by others.\tab \par }{\f7 SO_SNDBUF\tab int\tab Buffer size for sends\tab Implementation \par }{\f7 \tab \tab \tab dependant.\tab (i) \par }{\f7 SO_TYPE\tab int\tab The type of the socket\tab As created \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 \tab \tab (e.g. SOCK_STREAM). via }{\b\f7\uldb socket()}{\v\f8 WinSock_Socket}{\f7 \tab \par }\pard \fi-7114\li7474\tx2160\tx3960\tx6120\tx7470 {\f7 TCP_NODELAY\tab BOOL\tab Disables the Nagle\tab Implementation \par }{\f7 \tab \tab \tab dependant. \par }{\f7 \tab \tab algorithm for send \par }{\f7 \tab \tab coalescing. \par }\pard\plain \s15 \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\f7 Notes: \par }\pard \s22\fi-1440\li1440 {\f7 (i)\tab An implementation may silently ignore this option on }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 and return a constant value for }{\b\f7\uldb getsockopt()}{\v\f8 WinSoc}{\v\f8 k_GetSockOpt}{\f7 , or it may accept a value for }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 and return the corresponding value in }{\b\f7\uldb getsockopt()}{\v\f8 WinSock_GetSockOpt}{\f7 without using the value in any way. \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_Da}{\f7 tabaseFiles}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Database Files}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets} }} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Database Routines}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Database Files \par \pard\plain \fs20\lang1033 {\f7 The }{\b\f7\uldb getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 and }{\b\f7\uldb WSAAsyncGetXByY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 classes of routines are provided for retrieving network specific information. The }{\b\f7 getXbyY()}{\f7 routines were originally designed (in the first Berkeley UNIX releases) as mechani}{\f7 sms for looking up information in text databases. Although the information may be retrieved by the Windows Sockets implementation in different ways, a Windows Sockets application requests such information in a consistent manner through either the }{ \b\f7 getXbyY()}{\f7 or the }{\b\f7 WSAAsyncGetXByY()}{\f7 class of routines. \par }\pard {\b\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_Deviation}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Deviation from Berkeley Sockets}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Deviation from Berkeley Sockets \par \pard\plain \fs20\lang1033 {\f7 There are a few limited instances where the Windows Sockets API has had to divert from strict adherence to the Berkeley conventions, usuall}{\f7 y because of difficulties of implementation in a Windows environment. \par }\pard {\f7 \par }\pard {\b\f8\uldb socket data type and error values}{\v\f8 WinSockDeviation_DataType}{\b\f7 \par }{\b\f8\uldb select() and FD_*}{\v\f8 WinSockDeviation_Select}{\b\f7 \par }{\b\f8\uldb Error codes - errno, h_errno & WSAGetLastError()}{\v\f8 WinSockDeviation_ErrorCodes}{\b\f7 \par }{\b\f8\uldb Pointers}{\v\f8 WinSockDeviation_Pointers}{\b\f7 \par }{\b\f8\uldb Renamed functions}{\v\f8 WinSockDeviation_RenamedFunctions}{\b\f7 \par }{\b\f8\uldb Blocking routines & EINPROGRESS}{\v\f8 WinSockDeviation_BlockingRoutines}{\b\f7 \par }{\b\f8\uldb Maximum number of sockets supported}{\v\f8 WinSockDeviation_MaxSockets}{\b\f7 \par }{\b\f8\uldb Include files}{\v\f8 WinSockDeviation_IncludeFiles}{\b\f7 }{\b\f7 \par }{\b\f8\uldb Return values on API failure}{\v\f8 WinSockDeviation_ReturnValues}{\b\f7 \par }\pard \par \pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_DataType}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 socket data type and error values}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 socket data type and error values \par \pard\plain \fs20\lang1033 {\f7 A new data type, SOCKET, has been defined. The definition of this type was necessary for future enhancements to the Windows Sockets specification, such as being able to use sockets as file handles in Windows NT. Definition of this type also facilitates }{\f7 porting of applications to a Win/32 environment, as the type will automatically be promoted from 16 to 32 bits. \par }\pard {\f7 \par }\pard {\f7\revised I}{\f7\revised n UNIX, all handles, including socket handles, are small, non-negative intergers, and some applications make assumptions that this will be true. Windows Sockets handles have no restrictions, other than that the value INVALID_SOCKET is not a valid socket. }{\f7\revised Socket handles may take any value in the range 0 to INVALID_SOCKET-1.}{\f7 \par }\pard \par \pard {\f7 Because the SOCKET type is unsigned, compiling existing source code from, for example, a UNIX environment may lead to compiler warnings about signed/unsigned data type mismatches. \par }\pard {\f7 }{\f7 \par }\pard {\f7 This means, for example, that checking for errors when the }{\b\f7\uldb socket()}{\v\f8 WinSock_Socket}{\f7 and }{\b\f7\uldb accept()}{\v\f8 WinSock_Accept}{\f7 routines return should }{\f7\ul not}{\f7 be done by comparing the return value with -1, or seeing if the value is negative (both common, and legal, approaches in BSD). Instead, an application should use the manifest constant INVALID_SOCKET as defined in }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 . For example: \par }\pard {\f7 \tab }{\b\f7 TYPICAL BSD STYLE: \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 s = socket(...); \par if (s == -1)\tab /* or s < 0 */ \par \tab \{...\} \par \pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7 \tab }{\b\f7 PREFERRED STYLE:}{\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 s = socket(...); \par if (s == INVALID_SOCKET) \par \tab \{...\}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_Select}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 select() and FD_*}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 select() and FD_* \par \pard\plain \fs20\lang1033 {\f7 Because a SOCKET is no longer represented by the UNIX-style "small non-negative integer", the implementation of the }{\b\f7\uldb select()}{\v\f8 WinSock_Select}{\f7 function was changed in the Windows Sockets API. Each set of descriptors is still represented by the fd_set type, but instead of being stored as a bitmask the set is implemented as an array of SOCKETs.. To avoid potential problems, applications }{ \b\f7 must}{\f7 adhere to the use of the FD_}{\f7 XXX macros to set, initialize, clear, and check the fd_set structures. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_ErrorCodes}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Error codes - errno, h_errno & WSAGetLastError()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Error codes - errno, h_errno & WSAGetLastError() \par \pard\plain \fs20\lang1033 {\f7 Error codes set by the Windows Sockets implementation are }{\b\f7 NOT}{\f7 made available via the errno variable. Additionally, for the }{\b\f7\uldb getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 class of functions, error codes are }{\b\f7 NOT}{\f7 made available via the h_errno variable. Instead, error codes are accessed by using the }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 API. This f}{\f7 unction is provided in Windows Sockets as a precursor (and eventually an alias) for the Win32 function }{\b\f7 GetLastError()}{\f7 . This is intended to provide a reliable way for a thread in a multi-threaded process to obtain per-thread error information. \par }\pard {\f7 \par }{\f7 For compatibility with BSD, an application may choose to include a line of the form: \par }{\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 #define errno WSAGetLastError() \par \pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7 This will allow networking code which was written to use the global errno to work correctly in a single-threaded environment. There are, obvi}{\f7 ously, some drawbacks. If a source file includes code which inspects errno for both socket and non-socket functions, this mechanism cannot be used. Furthermore, it is not possible for an application to assign a new value to errno. (In Windows Sockets t }{\f7 he function }{\b\f7\uldb WSASetLastError()}{\v\f8 WinSock_SetLastError}{\f7 may be used for this purpose.) \par }\pard {\f7 \par }\pard {\f7 \tab }{\b\f7 TYPICAL BSD STYLE: \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 r = recv(...); \par if (r == -1 \par && errno == EWOULDBLOCK) \par \tab \{...\} \par \pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7 \tab }{\b\f7 PREFERRED STYLE:}{\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 r = recv(...); \par if (r == -1 /* (but see below) */ \par && WSAGetLastError() == EWOULDBLOCK) \par \pard \s29\li1440 \tab {\b \{}...{\b \}} \par \pard \s29\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 Although error constants consistent with 4.3 Berkeley Sockets are provided for compatibility purposes, applications should, where possible, use the "WSA" error code definitions. For example, a more accurate version of the above source code fragment is: \par }\pard {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 r = recv(...); \par if (r == -1 \par && WSAGetLastError() == WSAEWOULDBLOCK) \par \pard \s29\li1440 \tab {\b \{}...{\b \}}{\b\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_Pointers}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Pointers}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockD}{\f7 ev:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}} } Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Pointers \par \pard\plain \fs20\lang1033 {\f7 All pointers used by applications with Windows Sockets should be FAR. To }{\f7 facilitate this, data type definitions such as LPHOSTENT are provided. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_RenamedFunctions}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Renamed functions}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Renamed functions \par \pard\plain \fs20\lang1033 {\f7 In two cases it was necessary to rename functions which are used in Berkeley Sockets in order to avoid clashes with other APIs. \par }\pard {\b\f7 \par }\pard\plain \s33\li720\ri720 \b\fs20\lang1033 {\f7 close() & }{\f7\uldb closesocket()}{\plain \v\f8\fs20\lang1033 WinSock_CloseSocket}{\f7 \par }\pard\plain \li720\ri720 \fs20\lang1033 {\f7 In Berkeley Sockets, sockets are represented by standard file descriptors, and so the }{\b\f7 close()}{\f7 function can be used to close sockets as well as regular files. While nothing in the Windows Sockets API pr}{\f7 events an implementation from using regular file handles to identify sockets, nothing requires it either. Socket descriptors are not presumed to correspond to regular file handles, and file operations such as }{\b\f7 read()}{\f7 , }{\b\f7 write()}{\f7 , and }{\b\f7 close()}{\f7 cannot be assumed to work correctly when applied to socket descriptors.. Sockets must be closed by using the }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 routine. Using the }{\b\f7 close()}{\f7 routine to close a socket is incorrect and the effects of doing so are undefined by this specification}{\f7 . \par }\pard {\f7 \par }\pard \li720\ri720 {\b\f7 ioctl() & }{\b\f7\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSocket}{\f7 \par }{\f7 Various C language run-time systems use the }{\b\f7 ioctl()}{\f7 routine for purposes unrelated to Windows Sockets. For this reason we have defined the routine }{\b\f7\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSocket}{\f7 which is used to handle socket functions which in the Berkeley Software Distribution are performed using }{\b\f7 ioctl()}{\f7 and }{\b\f7 fcntl()}{\f7 . \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_BlockingRoutines}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Blocking routines & EINPROGRESS}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Blocking routines & EINPROGRESS \par \pard\plain \fs20\lang1033 {\f7 Although blocking operations on sockets are supported under Windows Sockets, t}{\f7 heir use is strongly discouraged. Programmers who are constrained to use blocking mode - for example, as part of an existing application which is to be ported - should be aware of the semantics of blocking operations in Windows Sockets. See }{\f7\uldb Blocking/Non blocking & Data Volatility}{\v\f7 WinSockOverview_BlockingNonBlocking}{\f7 for more details. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_MaxSockets}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Maximum number of sockets supported}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Maximum number of sockets supported \par \pard\plain \fs20\lang1033 {\f7 The maximum number of sockets supported by a particular Windows Sockets supplier is implementa}{\f7 tion specific. An application should make no assumptions about the availability of a certain number of sockets. This topic is addressed further in the section on }{\b\f7\uldb WSAStartup()}{\v\f7 Winsock_Startup}{\f7 . However, independent of the number of sockets supported by a particular implementation is the issue of the maximum number of sockets which an application can actually make use of. \par }\pard {\f7 \par }\pard {\f7 The maximum number of sockets which a Windows Sockets application can make use of is determined at compile time by the manifest constan}{\f7 t FD_SETSIZE. This value is used in constructing the fd_set structures used in }{\b\f7\uldb select()} {\v\f8 WinSock_Select}{\f7 . The default value in }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 is 64. If an application is designed to be capable of working with more than 64 sockets, the implementor should define the manifest FD_SETSIZE in every source file }{\f7\ulw before}{\f7 including }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 . One way of doing this may be to include the definition within the compiler options in the makefile, for example adding -DFD_SETSIZE=128 as an option t}{\f7 o the compiler command line for Microsoft C. It must be emphasized that defining FD_SETSIZE as a particular value has no effect on the actual number of sockets provided by a Windows Sockets implementation. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_IncludeFiles}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Include files}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0080}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Include files \par \pard\plain \fs20\lang1033 {\f7 For ease of portability of existing Berkeley sockets based source code, a number of standard Berkeley include files are supported. However, these Berkeley header files merely include the }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 include file, and it is therefo}{\f7 re sufficient (and recommended) that Windows Sockets application source files should simply include }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 . \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockDeviation_ReturnValues}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Return values on API failure}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0090}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{ \f7 Sockets}}} Deviation from Berkeley Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Return values on API failure \par \pard\plain \fs20\lang1033 {\f7 The manifest constant SOCKET_ERROR is provided for checking API failure. Although use of this constant is not mandatory, it is recommended. The following example illustrates the use of the SOCKET_ERROR constant: \par }\pard {\f7 \par }\pard {\b\f7 \tab TYPICAL BSD STYLE: \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 r = recv(...); \par if (r == -1 /* or r < 0 */ \par && errno == EWOULDBLOCK) \par \pard \s29\li1440 \tab {\b \{}...{\b \}} \par \pard\plain \fs20\lang1033 {\b\f7 \tab PREFERRED STYLE:}{\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 r = recv(...); \par if (r == SOCKET_ERROR \par && WSAGetLastError() == WSAEWOULDBLOCK) \par \pard \s29\li1440 \tab {\b \{}...{\b \}}{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \par \pard \s35\sa240 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_RawSockets}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Raw Sockets}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDev:0100}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 R{\revised aw Sockets \par }\pard\plain \fs20\lang1033 {\f7\revised The Windows Sockets specification does not mandate that a Windows Sockets DLL support raw sockets, that is, sockets opened with SOCK_RAW. However, a Windows Sockets DLL is allowed and encouraged to supply raw socket support. A Windows Sockets-compliant }{\f7\revised application that wishes to use raw sockets should attempt to open the socket with }{\f7\revised the }{\b\f7\revised socket()}{\f7\revised call (see section }{\field\flddirty{\*\fldinst {\f7\revised ref socket}}{\fldrslt {\f7\revised 4.1.23} }}{\f7\revised ), and if it fails either attempt to use another socket type or indicate the failure to the user.}{\revised \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockProg_MultithreadedWindows}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Windows Sockets in Multithreaded Versions of Windows}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockProg:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Sockets}}} Programming with Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised Windows Sockets in Multithreaded Versions of Windows \par }\pard\plain \fs20\lang1033 {\f7\revised The Windows Sockets interface is designed to work for both single-threaded versions of Windows (such as Windows 3.1) and future multithreaded versions of Windows (such as Windows NT). In a multithreaded environment the sockets interface is basically the }{\f7\revised same, but the autho}{\f7\revised r of a multithreaded application must be aware that it is the responsibility of the application, not the Windows Sockets implementation, to synchronize access to a socket between threads. This is the same rule as applies to other forms of I/O such as fil }{\f7\revised e I/O. Failure to synchronize calls on a socket leads to unpredictable results; for example if there are two simultaneous calls to send(), there is no guarantee as to the order in which the data will be sent. \par }\pard {\f7 \par }\pard {\f7\revised Closing a socket in one thread that has an}{\f7\revised outstanding blocking call on the same socket in another thread will cause the blocking call to fail with WSAEINTR, just as if the operation were cancelled. This also applies if there is a }{\f7\uldb\revised select()}{\v\f7 Winsock_Select}{\f7\revised call outstanding and the application closes one of the sockets being selected. \par }\pard {\f7 \par }\pard {\f7\revised There is no default blocking hook installed in preemptive multithreaded versions of Windows. This is because the machine will not be blocked if a single application is waiting for an operation to complete and hence n}{\f7\revised ot calling PeekMessage() or GetMessage() which cause the application to yield in nonpremptive Windows. However, for backwards compatibility the WSASetBlockingHook() call is implemented in multithreaded versions of Windows, and any application whose behav }{\f7\revised ior depends on the default blocking hook may install their own blocking hook which duplicates the default hook's semantics, if desired. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SocketLibraryOverview}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 SOCKET LIBRARY OVERVIEW}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0030}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Socket Library Overview \par {\ul \par }\pard\plain \fs20\lang1033 {\b\f8\uldb Socket Functions}{\v\f8 WinSockOverview_SocketFunctions}{\b\f7 \par }\pard \li360 {\b\f8\uldb Blocking/Non blockin}{\b\f8\uldb g & Data Volatility}{\v\f8 WinSockOverview_BlockingNonBlocking}{\b\f7 \par }\pard {\b\f8\uldb Database Functions}{\v\f8 WinSockOverview_DatabaseFunctions}{\b\f7 \par }{\b\f8\uldb Microsoft Windows-specific Extension Functions}{\v\f8 WinSockOverview_WindowsSpecific}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockOverview_SocketFunctions}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Socket Functions}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockOver:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Socket Functions}}} Socket Library Overview \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Socket Functions \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets specification includes the following Berkeley-style socket routines: \par }{\f7 \par }\pard \fi-2160\li2880\tx2880 {\b\f7\uldb accept()}{\v\f8 WinSock_Accept}{\f7 \tab An incoming connection is acknowledged and associated with an immediately created socket. The original socket is returned to the listening state. \par }{\b\f7\uldb bind()}{\v\f8 W}{\v\f8 inSock_Bind}{\f7 \tab Assign a local name to an unnamed socket. \par }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 \tab Remove a socket descriptor from the per-process object reference table. Only blocks if SO_LINGER is set. \par }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 \tab Initiate a connection on the specified socket. \par }{\b\f7\uldb getpeername()}{\v\f8 WinSock_GetPeerName}{\f7 \tab Retrieve the name of the peer connected to the specified socket descriptor. \par }{\b\f7\uldb getsockname()}{\v\f8 WinSock_GetSockName}{\f7 \tab Retrieve the current name for the specified socket \par }{\b\f7\uldb getsockopt()}{\v\f8 WinSock_GetSockOpt}{\f7 \tab Retrieve options a}{\f7 ssociated with the specified socket descriptor. \par }{\b\f7\uldb htonl()}{\v\f8 WinSock_HtoNL}{\f7 \tab Convert a 32-bit quantity from host byte order to network byte order. \par }{\b\f7\uldb htons()}{\v\f8 WinSock_HtoNS}{\f7 \tab Convert a 16-bit quantity from host byte order to network byte order. \par }{\b\f7\uldb inet_addr()}{\v\f8 WinSock_InetAddr}{\f7 \tab Converts a character string representing a number in the Internet standard ".'' notation to an Internet address value. \par }{\b\f7\uldb inet_ntoa()}{\v\f7 Wi}{\v\f8 nSock_InetNtoA}{\f7 \tab Converts an Internet address value to an ASCII string in ".'' notation i.e. "a.b.c.d''. \par }{\b\f7\uldb ioctlsocket()}{\v\f7 Win}{\v\f8 Sock_IOCTLSocket}{\f7 \tab Provide control for descriptors. \par }{\b\f7\uldb listen()}{\v\f7 Wi}{\v\f8 nSock_Listen}{\f7 \tab Listen for incoming connections on a specified socket. \par }{\b\f7\uldb ntohl()}{\v\f7 Wi}{\v\f8 nSock_NtoHL}{\f7 \tab Convert a 32-bit quantity from network byte order to host byte order. \par }{\b\f7\uldb ntohs()}{\v\f8 WinSock_NtoHS}{\f7 \tab Convert a 16-bit quantity from network byte order to host byte order. \par }{\b\f7\uldb recv()*}{\v\f8 WinSock_RECV}{\f7 \tab Receive data from a connected socket. \par }{\b\f7\uldb recvfrom()*}{\v\f8 WinSock_RecvFrom}{\f7 \tab Receive data from either a connected or unconnected socket. \par }{\b\f7\uldb select()*}{\v\f8 WinSock_Select}{\f7 \tab Perform synchronous I/O}{\f7 multiplexing. \par }{\b\f7\uldb send()*}{\v\f8 WinSock_Send}{\f7 \tab Send data to a connected socket. \par }{\b\f7\uldb sendto()*}{\v\f8 WinSock_SendTo}{\f7 \tab Send data to either a connected or unconnected socket. \par }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 \tab Store options associated with the specified socket descriptor. \par }{\b\f7\uldb shutdown()}{\v\f8 WinSock_Shutdown}{\f7 \tab Shut down part of a full-duplex connection. \par }{\b\f7\uldb socket()}{\v\f8 WinSock_Socket}{\f7 \tab Create an endpoint for communication and return a socket descriptor. \par }\pard {\f7 \par }{\f7 * The routine can block if acting on a blocking socket. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockOverview_BlockingNonBlocking}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Blocking/Non blocking & Data Volatility}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockOver:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Sockets}}} Socket Library Overview \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Blocking/Non blocking & Data Volatility \par \pard\plain \fs20\lang1033 {\f7 One major issue in porting applications from a Berkeley sockets environment to a Windows environment involves "blocking"; that is, invoking a function which does not return until the associated operation is completed. The problem arises when the operatio }{\f7 n may take an arbitrarily long time to complete: an obvious example is a }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 which may block until data has been received from the peer system. The default behavior within the Berkeley sockets model is for a s}{\f7 ocket to operate in a blocking mode unless the programmer explicitly requests that operations be treated as non-blocking.}{\revised }{\b\i\f7\revised It is strongly recommended that programmers use the nonblocking (asynchronous) operations if at all possible, as they work significantly better within the nonpreemptive Windows environment. Use blocking operations only if absolutely necessary, and carefu }{\b\i\f7\revised lly read and understand this section if you must use blocking operations.}{\b\f7\revised \par }\pard {\f7 \par }\pard {\f7 Even on a blocking socket, some operations (e.g. }{\b\f7\uldb bind()}{\v\f8 Wi}{\v\f8 nSock_Bind}{\f7 , }{\b\f7\uldb getsockopt()}{\v\f8 WinSock_GetSockOpt}{\f7 , }{\b\f7\uldb getpeername()}{\v\f8 WinSock_GetPeerName}{\f7 ) can be completed immediately. For such operations there is no difference between blocking and non-blocking operation. Other operations (e.g. }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 ) may be completed immediately or may take an arbitrary time to complete, depending on various transport conditions. When applied to a blocking socket, these operations are referred to as blocking operations. }{\f7\revised All routines which can block are listed with an asterisk in th}{\f7\revised e tables above and below.}{\f7 \par }\pard {\f7 \par }\pard {\f7 Within a Windows Sockets implementation, a blocking operation which cannot be completed immediately is handled as follows. The DLL initiates the operation, and then enters a loop in which it dispatches any Windows messages (yielding the processor to anot }{\f7 her thread if necessary) and then checks for the completion of the Windows Sockets function. If the function has completed, or if }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 has been invoked, the blocking function complet}{\f7 es with an appropriate result. Refer to }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 , for a complete description of this mechanism, including pseudocode for the various functions. \par }\pard {\f7 \par }\pard {\f7 If a Windows message is received for a process for which a blocking operation is in progress, there is a risk that the application will attempt to issue another Windows Sockets call. Because of the difficulty of managing this condition safely, the Window }{\f7 s Sockets specification does not support such application behavior. Two }{\f7 functions are provided to assist the programmer in this situation. }{\b\f7\uldb WSAIsBlocking()}{\v\f8 WinSock_IsBlocking}{\f7 may be called to determine whether or not a blocking Windows Sockets call is in progress. }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 may be called to cancel an in-progress blocking call, if any. }{\b\f7 Any other Windows Sockets function which is called in this situation will fail with the error WSAEINPROGRESS.}{\f7 It should be emphasized that this restriction applies to both blocking and non-blocking operati}{\f7 ons. \par }\pard {\f7 \par }\pard {\f7 Although this mechanism is sufficient for simple applications, it cannot support the complex message-dispatching requirements of more advanced applications (for example, those using the MDI model). For such applications, the Windows Sockets API includes }{\f7 the function }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 , which allows the programmer to define a special routine which will be called instead of the default message dispatch routine described above. \par }\pard {\f7 \par }\pard {\f7\revised The Windows Sockets DLL will call the blocking}{\f7\revised hook function }{\f7 only if all of the following are true: the routine is one which is defined as being able to block, the specified socket is a blocking socket, and the request cannot be completed immediately.}{\f7\revised (A socket is set to blocking by default, but the IOCTL FIONBIO and }{\b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 Winsock_AsyncSelect}{\f7\revised both set a socket to nonblocking mode.) If an application uses only non-blocking sockets and uses the }{ \b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 Winsock_AsyncSelect}{\f7\revised and/or the }{\b\f7\uldb\revised WSAAsyncGetXByY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7\revised }{\f7\revised routines instead of }{\b\f7\uldb\revised select()}{\v\f7 Winsock_Select}{\f7\revised and the }{\b\f7\uldb\revised getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7\revised routines, then the blocking hook will never be called and the application does not need to be concerned with the reentrancy issues the blocking hook can introduce. \par }\pard {\f7 \par }\pard {\f7 If an application invokes an asynchronous or non-blocking operation which takes a pointer to a memory object (e.g. a buffer, or a global variable) as an argument, it is the responsibility of the application to ensure that the object is available to th}{ \f7 e Windows Sockets implementation throughout the operation. The application must not invoke any Windows function which might affect the mapping or addressability of the memory involved. In a multithreaded system, the application is also responsible for c }{\f7 oordinating access to the object using appropriate synchronization mechanisms. A Windows Sockets implementation cannot, and will not, address these issues. The possible consequences of failing to observe these rules are beyond the scope of this specific }{\f7 at}{\f7 ion. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockOverview_DatabaseFunctions}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Database Functions}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 }{\f7 WinSockOver:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{ \f7 Socket Functions}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Database Functions}}} Socket Library Overview \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Database Functions \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets specification defines the following "database" routines. As noted earlier, a Windows Sockets supplier may choose to implement these in a manner which does not depend on local database files. The pointer returned by certain database r }{\f7 outines such as }{\b\f7\uldb gethostbyname()}{\v\f8 WinSock_GetHostByName}{\f7 points to a structure which is allocated by the Windows Sockets library. The data which is pointed to is volatile and is good only until the }{\f7 next Windows Sockets API call from that thread. Additionally, the application must never attempt to modify this structure or to free any of its components. Only one copy of this structure is allocated for a thread, and so the application should copy any }{\f7 information which it needs before issuing any other Windows Sockets API calls. \par }\pard {\f7 \par }{\f7 \par }\pard \fi-2160\li2880\tx2880 {\b\f7\uldb gethostbyaddr()*}{\v\f8 WinSock_GetHostByAddr}{\f7 \tab Retrieve the name(s) and address corresponding to a network address. \par }{\b\f7\uldb gethostname()}{\v\f8 WinSock_GetHostName}{\f7 \tab Retrieve the name of the local ho}{\f7 st. \par }{\b\f7\uldb gethostbyname()*}{\v\f8 WinSock_GetHostByName}{\f7 \tab Retrieve the name(s) and address corresponding to a host name. \par }{\b\f7\uldb getprotobyname()*}{\v\f8 WinSock_GetProtoByName}{\f7 \tab Retrieve the protocol name and number corresponding to a protocol name. \par }{\b\f7\uldb getprotobynumber()*}{\v\f8 WinSock_GetProtoByNumber}{\f7 \tab Retrieve the protocol name and number corresponding to a protocol number. \par }{\b\f7\uldb getservbyname()*}{\v\f8 WinSock_GetServByName}{\f7 \tab Retrieve the service name and port corresponding to a service name. \par }{\b\f7\uldb getservbyport()*}{\v\f8 WinSock_GetServByPort}{\f7 \tab Retrieve the service name an}{\f7 d port corresponding to a port. \par }\pard {\b\f7 \par }\pard {\f7 * The routine can block under some circumstances.}{\b\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockOverview_WindowsSpecific}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Microsoft Windows-specific Extension Functions}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockOver:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Socket Functions}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Socket Library Overview \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Microsoft Windows-specific Extension Functions \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets specification provides a number of extensions to the standard set of Berkeley Sockets routines. Principally, these extended APIs allow message-based, asynchronous access to network events. While use of this extended API set is not ma }{\f7 ndatory for socket-based programming (with the exception of }{\b\f7\uldb WSAStartup()}{\v\f7 Winsock_Startup}{\f7 and }{\b\f7\uldb WSACleanup()}{\v\f7 Winsock_Cleanup}{\f7 ), it is recommended for conformance with the Microsoft Windows programming paradigm. \par }\pard {\f7 \par }\pard {\b\f8\uldb Asynchronous select() Mechanism}{\v\f8 WinSockWindows_AsyncSelect}{\b\f7 \par }{\b\f8\uldb Asynchronous Support Routines}{\v\f8 WinSockWindows_AsyncSupport}{\b\f7 \par }{\b\f8\uldb Hooking Blocking Methods}{\v\f8 WinSockWindows_HookingBlocking}{\b\f7 \par }{\b\f8\uldb Error Handling}{\v\f8 WinSockWindows_ErrorHandling}{\f8 \par }{\b\f8\uldb Accessing a Windows Sockets DLL from an Intermediate DLL}{\v\f8 WinsockWindows_Intermediate}{\f8 \par }{\b\f8\uldb Internal Use of Messages by Windows Sockets Implementations}{\v\f8 WinsockWindows_InternalMessage}{\v\f8 s}{\f8 \par }{\b\f8\uldb Private API Interfaces}{\v\f8 WinsockWindows_PrivateAPIs}{\b\f7 \par }\pard \par \pard \fi-3600\li3600 {\f7 \par }\pard \fi-3600\li4320\tx4320 {\b\f7\uldb WSAAsyncGetHostByAddr()}{\v\f8 WinSock_AsyncGetHostByAddr}{\f7 \tab A set of functions which provide asynchronous \par }{\b\f7\uldb WSAAsyncGetHostByName()}{\v\f8 WinSock_AsyncGetHostByName}{\f7 \tab versions of the standard Berkeley \par }{\b\f7\uldb WSAAsyncGetProtoByName()}{\v\f8 WinSock_AsyncGetProtoByName}{\f7 \tab }{\b\f7 getXbyY()}{\f7 functions. For example, the \par }{\b\f7\uldb WSAAsyncGetProtoByNumber()}{\v\f8 WinSock_AsyncGetProtoByNumber}{\f7 \tab }{\b\f7 WSAAsyncGetHostByName()}{\f7 function provides an asynchronous message based \par }{\b\f7\uldb WSAAsyncGetServByName()}{\v\f8 WinSock_AsyncGetServByName}{\f7 \tab im}{\f7 plementation of the standard Berkeley \par }{\b\f7\uldb WSAAsyncGetServByPort()}{\v\f8 WinSock_AsyncGetServByPort}{\f7 \tab }{\b\f7 gethostbyname()}{\f7 function. \par }{\b\f7\uldb WSAAsyncSelect()}{\v\f8 WinSock_AsyncSelect}{\b\f7 \tab }{\f7 Perform asynchronous version of }{\b\f7 select()}{\f7 \par }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 \tab Cancel an outstanding instance of a }{\b\f7 WSAAsyncGetXByY()}{\f7 function. \par }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \tab Cancel an outstanding "blocking" API call \par }{\b\f7\uldb WSACleanup()}{\v\f8 WinSock_Cleanup}{\f7 \tab Sign off from the underlying Windows Sockets DLL. \par }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLas}{\v\f8 tError}{\f7 \tab Obtain details of last Windows Sockets API error \par }{\b\f7\uldb WSAIsBlocking()}{\v\f8 WinSock_IsBlocking}{\f7 \tab Determine if the underlying Windows Sockets DLL is already blocking an existing call for this thread \par }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 \tab "Hook" the blocking method used by the underlying Windows Sockets implementation \par }{\b\f7\uldb WSASetLastError()}{\v\f8 WinSock_SetLastError}{\f7 \tab Set the error to be returned by a subsequent }{\b\f7 WSAGetLastError()}{\f7 \par }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 \tab Initialize the underlying Windows Sockets DLL. \par }{\b\f7\uldb WSAUnhookBlocki}{\b\f7\uldb ngHook()}{\v\f8 WinSock_UnhookBlockingHook}{\f7 \tab Restore the original blocking function \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_AsyncSelect}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Asynchronous select() Mechanism}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Socket Functions}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Asynchronous select() Mechanism \par \pard\plain \fs20\lang1033 {\f7 The }{\b\f7\uldb WSAAsyncSelect()}{\v\f8 WinSock_AsyncSelect}{\f7 API allows an application to register an interest in one or many network events. This API is provided to supersede the need to do polled network I/O. Any situation in which }{\b\f7\uldb select()}{\v\f8 WinSock_Select}{\f7 or non-blocking I/O routines (such as }{\b\f7\uldb send()}{\v\f8 WinSock_Send}{\f7 and }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 ) are either already used or are be}{\f7 ing considered is usually a candidate for the }{\b\f7\uldb WSAAsyncSelect()}{ \v\f8 WinSock_AsyncSelect}{\f7 API. When declaring interest in such condition(s), you supply a window handle to be used for notification. The corresponding window then receives message-based notification of the conditions in which you declared an interest. \par }\pard {\f7 \par }\pard \keepn {\b\f7\uldb WSAAsyncSelect()}{\v\f8 WinSock_AsyncSelect}{\f7 allows interest to be declared in the following conditions for a particular socket: \par }\pard \keepn {\f7 \tab Socket readiness for reading \par }{\f7 \tab Socket readiness for writing \par }{\f7 \tab Out-of-band dat}{\f7 a ready for reading \par }{\f7 \tab Socket readiness for accepting incoming connection \par }\pard \keepn {\f7 \tab Completion of non-blocking }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 \par }\pard {\f7 \tab Connection closure \par }{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_AsyncSupport}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Asynchronous Support Routines}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K} {\f7 Socket Functions}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Asynchronous Support Routines \par \pard\plain \fs20\lang1033 {\f7 The asynchronous "database" functions allow applications to request information in an asynchronous manner. Some network implementations and/or configurations perform network based operations to resolve such requests. The }{\b\f7 WSAAsyncGetXByY()}{\f7 functions allow application developers }{\f7 to request services which would otherwise block the operation of the whole Windows environment if the standard Berkeley function were used. The }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 function allows an application to cancel any outstanding asynchronous request. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_HookingBlocking}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Hooking Blocking M}{\f7 ethods}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K }{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Hooking Blocking Methods \par \pard\plain \fs20\lang1033 {\f7 As noted in }{\b\f7\uldb Blocking/Non blocking & Data Volatility}{\v\f7 WinSockOverview_BlockingNonBlocking}{\f7 , Windows Sockets implements blocking operations in such a way that Windows}{\f7 message processing can continue, which may result in the application which issued the call receiving a Windows message. In certain situations an application may want to influence or change the way in which this pseudo-blocking process is implemented. T }{\f7 he }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 provides the ability to substitute a named routine which the Windows Sockets implementation is to use when relinquishing the processor during a "blocking" operation. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_ErrorHandling}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Error Handling}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Error Handling \par \pard\plain \fs20\lang1033 {\f7 For compatibility with thread-based environments, details of API errors are obtained through the }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 API. Although the accepted "Berkeley-Style" mechanism for obtaining socket-based network errors is via "errno", this mechanism cannot guarantee the integrity of an error ID in a multi-threaded environment. }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 allows you to retrieve an error code on a per thread basis. \par }\pard {\f7 \par }\pard {\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 returns}{\f7 error codes which avoid conflict with standard Microsoft C error codes. Certain error codes returned by certain Windows Sockets routines fall into the standard range of error codes as defined by Microsoft C. If you are NOT using an application developm }{\f7 ent environment which defines error codes consistent with Microsoft C, you are advised to use the Windows Sockets error codes prefixed by "WSA" to ensure accurate error code detection. \par }\pard {\f7 \par }\pard {\f7 Note that this specification defines a recommended set of error codes}{\f7 , and lists the possible errors which may be returned as a result of each function. It may be the case in some implementations that other Windows Sockets error codes will be returned in addition to those listed, and applications should be prepared to han }{\f7 dle errors other than those enumerated under each API description. However a Windows Sockets implementation must not return any value which is not enumerated in the table of legal Windows Sockets errors given in }{\f7\uldb Error Codes}{\v\f7 Winsock_ErrorCodes}{\f7 . \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_Intermediate}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Accessing from an Intermediate DLL}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised Accessing a Windows Sockets DLL from an Intermediate DLL \par }\pard\plain \fs20\lang1033 {\f7\revised A Windows Sockets DLL may be accessed both directly from an application and through an "intermediate" DLL. An example of such an intermediate DLL would be a virtual network API layer that supports generalized network functionality for applications and us }{\f7\revised es Windows Sockets. Such a DLL could be used by several applications simultaneously, and the DLL must take special precautions with respect to the }{\b\f7\revised WSAStartup() }{\f7\revised an}{\f7\revised d}{\b\f7\revised WSACleanup() }{ \f7\revised calls to ensure that these routines are called in the context of each task that will make Windows Sockets calls. This is because the Windows Sockets DLL will need a call to }{\b\f7\revised WSAStartup() }{\f7\revised for each task in order to set up task-specific data structures, and a call to }{\b\f7\revised WSACleanup() }{\f7\revised to free any resources allocated for the task. \par }\pard {\f7 \par }\pard {\f7\revised There are (at least) two ways to accomplish this. The simplest method is for the intermediate DLL to have calls similiar to }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{\f7\revised and}{\b\f7\revised }{ \b\f7\uldb\revised WSACleanup(}{\b\f7\uldb\revised )}{\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised that applications call as appropriate. The DLL would then call }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{ \f7\revised or}{\b\f7\revised }{\b\f7\uldb\revised WSACleanup()}{\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised from within these routines. Another mechanism is for the intermediate DLL to build a table of task handles, which are obtained from the }{\b\f7\revised GetCurrentTask() }{\f7\revised Windows API, and at each entry point into the intermediate DLL check whether }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{\f7\revised has been called for the current task, then call }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{\f7\revised if necessary. \par }\pard {\f7 \par }\pard {\f7\revised If a DLL makes a bl}{\f7\revised ocking call and does not install its own blocking hook, then the DLL author must be aware that control may be returned to the application either by an application-installed blocking hook or by the default blocking hook. Thus, it is possible that the appl }{\f7\revised ication will cancel the DLL's blocking operation via }{\b\f7\uldb\revised WSACancelBlockingCall()}{\v\f7 Winsock_CancelBlockingCall}{\f7\revised . If this occurs, the DLL's blocking operation will fail with the error code WSAEINTR, and the DLL must return control to the calling task as quickly as p}{\f7\revised ossible, as the used has likely pressed a cancel or close button and the task has requested control of the CPU. It is recommended that DLLs which make blocking calls install their own blocking hooks with }{\b\f7\uldb\revised WSASetBlockingHook()}{\v\f7 Winsock_SetBlockingHook}{\f7\revised to prevent unforeseen interactions between the application and the DLL.}{\i\f7\revised \par }\pard {\i\f7 \par }\pard {\f7\revised Note that this is not necessary for DLLs in Windows NT because of its different process and DLL structure. Under Windows NT, the intermediate DLL could simply call }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Sta}{\v\f7 rtup}{ \b\f7\revised }{\f7\revised in its DLL initialization routine, which is called whenever a new process which uses the DLL starts. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_InternalMessages}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Internal use of Messages}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s252\li360 \b\fs20\lang1033 {\f7\revised 3.3.6 Internal use of Messages by Windows Sockets Implementations \par }\pard\plain \fs20\lang1033 {\f7\revised In order to implement Windows Sockets purely as a DLL, it may be necessary for the DLL to post messages internally for communication and timing. This is perfectly legal; however, a Windows Sockets DLL must not post messages to a window handle opened by a }{\f7\revised client application except for th}{\f7\revised ose messages requested by the application. A Windows Sockets DLL that needs to use messages for its own purposes must open a hidden window and post any necessary messages to the handle for that window. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockWindows_PrivateAPIs}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Private API Interfaces}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWin:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Windows Extensions}}} Microsoft Windows Extension Functions \par \pard\plain \s252\li360 \b\fs20\lang1033 {\f7\revised 3.3.7 Private API Interfaces \par }\pard\plain \fs20\lang1033 {\f7\revised The }{\f7\uldb\revised winsock.def}{\v\f7 WinSockNotes_DLLOrdinals}{\f7\revised file lists the ordinals defined for the Windows Sockets APIs. In addition to the ordinal values listed, all ordinals 999 and below are reserved for future Windows Sockets use. It may be }{\f7\revised convenient for a Windows Sockets implementation to export additional, private interfaces from the Windows Sockets DLL. This is perfectly acceptable, as long as the ordinals for these exports are above 1000. Note that any application that uses a particul }{\f7\revised ar Windows Sockets DLL's private APIs will most likely not work on any other vendor's Windows Sockets implementation. Only the APIs defined in this document are guaranteed to be present in every Windows Sockets implementation.}{\f7 \par }\pard {\f7 \par }\pard {\f7\revised If an application uses pri}{\f7\revised vate interfaces of a particular vendor's Windows Sockets DLL, it is recommended that the DLL not be statically linked with the application but rather dynamically loaded with the Windows routines }{\b\f7\revised LoadLibrary()}{\f7\revised and }{\b\f7\revised GetProcAddress().}{\f7\revised This allows the application to give an informative error message if it is run on a system with a Windows Sockets DLL that does not support the same set of extended functionality. \par }\pard {\f7\revised \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SocketLibraryReference}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Socket Library Reference}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Socket Library Reference}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Socket Library Reference \par \pard\plain \fs20\lang1033 {\b\f8\uldb Socket Routines}{\v\f8 WinSockRef_SocketRoutines}{\b\f7 \par }{\b\f8\uldb Data}{\b\f8\uldb base Routines}{\v\f8 WinSockRef_DatabaseRoutines}{\b\f7 \par }{\b\f8\uldb Microsoft Windows-specific Extensions}{\v\f8 WinSockRef_WindowsExtensions}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockRef_SocketRoutines}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Socket Routines}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockRef:0010}}} Socket Library Reference \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Socket Routines \par \par \pard\plain \fs20\lang1033 {\f7 This chapter presents the socket library routines in alphabetical order, and describes each routine in detail. \par }\pard {\f7 \par }\pard {\f7 In each routine it is indicated that the header file }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 must be included. }{\f7\uldb Header Files}{\v\f7 WinSock_HeaderFiles}{\f7 lists the Berkeley-compatible header files which are supported. These are provided for compatibility p}{\f7 urposes only, and each of them will simply include }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 . The Windows header file }{\b\f7 windows.h}{\f7 is also needed, but }{\b\f7 winsock.h}{\f7 will include it if necessary. \par }\pard {\f7 \par }\pard {\b\f8\uldb accept()}{\v\f8 WinSock_Accept}{\b\f7 \par }{\b\f8\uldb bind()}{\v\f8 WinSock_Bind}{\b\f7 \par }{\b\f8\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\b\f7 \par }{\b\f8\uldb connect()}{\v\f8 WinSock_Connect}{\b\f7 \par }{\b\f8\uldb getpeername()}{\v\f8 WinSock_GetPeerName}{\b\f7 \par }{\b\f8\uldb getsockname()}{\v\f8 WinSock_GetSockName}{\b\f7 \par }{\b\f8\uldb getsockopt()}{\v\f8 WinSock_GetSockOpt}{\b\f7 \par }{\b\f8\uldb htonl()}{\v\f8 WinSock_HtoNL}{\b\f7 \par }{\b\f8\uldb htons()}{\v\f8 WinSock_HtoNS}{\b\f7 \par }{\b\f8\uldb inet_addr()}{\v\f8 WinSock_InetAddr}{\b\f7 \par }{\b\f8\uldb inet_ntoa()}{\v\f8 WinSock_InetNtoA}{\b\f7 \par }{\b\f8\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSock}{\v\f8 et}{\b\f7 \par }{\b\f8\uldb listen()}{\v\f8 WinSock_Listen}{\b\f7 \par }{\b\f8\uldb ntohl()}{\v\f8 WinSock_NtoHL}{\b\f7 \par }{\b\f8\uldb ntohs()}{\v\f8 WinSock_NtoHS}{\b\f7 \par }{\b\f8\uldb recv()}{\v\f8 WinSock_Recv}{\b\f7 \par }{\b\f8\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\b\f7 \par }{\b\f8\uldb select()}{\v\f8 WinSock_Select}{\b\f7 \par }{\b\f8\uldb send()}{\v\f8 WinSock_Send}{\b\f7 \par }{\b\f8\uldb sendto()}{\v\f8 WinSock_SendTo}{\b\f7 \par }{\b\f8\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\b\f7 \par }{\b\f8\uldb shutdown()}{\v\f8 WinSock_ShutDown}{\b\f7 \par }{\b\f8\uldb socket()}{\v\f8 WinSock_Socket}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Accept}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 accept()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 accept()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 accept() \par \pard\plain \fi-1440\li1440 \fs20\lang1033 {\b\f7 Description\tab }{\f7 Accept a connection on a socket.}{\b\f7 \par }\pard \fi-1440\li1440 {\f7 \par }\pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab SOCKET PASCAL FAR accept ( SOCKET {\plain \i\f7\fs20\lang1033 s}, struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 addr}{\i ,} int FAR * {\plain \i\f7\fs20\lang1033 addrlen}{\i }); \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor id}{\f7 entifying a socket which is listening for connections after a }{\b\f7 listen}{\f7 (). \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 addr}{\f7 \tab An optional pointer to a buffer which receives the address of the connecting entity, as known to the communications layer. The exact format of the }{\i\f7 addr}{\f7 argument is determined by the address family established when the socket was created. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 addrlen}{\f7 \tab A optional pointer to an integer which contains the length of the address }{\i\f7 addr}{\f7 . \par }\pard\plain \fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s2\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine extracts the first connection on the queue of pending connections on }{\i\f7 s}{\f7 , create}{\f7 s a new socket with the same properties as }{\i\f7 s}{\f7 and returns a handle to the new socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, }{\b\f7 accept()}{\f7 blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, }{\b\f7 accept()}{\f7 returns an error as described below. The accepted socket may not be used to accept more connections. The original socket remains open. \par }\pard\plain \fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard \li1440 {\f7 The argument }{\i\f7 addr}{\f7 is a result }{\f7 parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the }{\i\f7 addr}{\f7 parameter is determined by the address family in which the communication is occurring. The }{\i\f7 addrlen}{\f7 is a value-result parameter; it should initially contain the amount of space pointed to by }{\i\f7 addr}{\f7 ; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types such as SOCK_STREAM. If }{\i\f7 addr}{\f7 and/or }{\i\f7 addrl}{\i\f7 en}{\f7 are equal to NULL, then no information about the remote address of the accepted socket is returned. \par }\pard {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 accept}{\f7 () returns a value of type SOCKET which is a descriptor for the accepted packet. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError}{\f7\uldb ()}{\v\f8 WinSock_GetLastError }{\f7 . \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 The integer referred to by }{\i\f7 addrlen}{\f7 initially contains the amount of space pointed to by }{\i\f7 addr}{\f7 . On return it will contain the actual lengt}{\f7 h in bytes of the address returned. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 addrlen}{\f7 argument is too small (less than the sizeof a struct sockaddr). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEINPROGRESS\tab A blocking Windows Sockets call is in progress. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL}{\f7 \tab }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\f7 was not invoked prior to }{\b\f7 accept()}{\f7 . \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEMFILE\tab The queue is empty upon entry to }{\b\f7 accept()}{\f7 and there are no descriptors available. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No buffer space is available. \par }{\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab The referenced socket is not a type that supports connection-oriented service. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The socket is marked as non-blocking and no connections are present to be accepted. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb connect()}{\plain \v\f8\fs20\lang1033 WinSock_Connect}, {\uldb listen()}{\plain \v\f8\fs20\lang1033 Win}{\plain \v\f8\fs20\lang1033 Sock_Listen}, {\uldb select()}{\plain \v\f8\fs20\lang1033 WinSock_Select}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Bind}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 bind()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 bind()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 bind() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Associate a local address with a socket. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR bind ( SOCKET {\plain \i\f7\fs20\lang1033 s}{\i ,} const struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 name}, int {\plain \i\f7\fs20\lang1033 namelen}{\i }); \par \pard\plain \fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying an unbound socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab The address to assign to the socket. The sockaddr structure is defined as follows: \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 \par }{\f7 \tab struct sockaddr \{ \par }{\f7 \tab \tab u_short\tab sa_family; \par }{\f7 \tab \tab char\tab s}{\f7 a_data[14]; \par }{\f7 \tab \}; \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 namelen}{\f7 \tab The length of the }{\i\f7 name}{\f7 . \par }\pard\plain \fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine is used on an unconnected datagram or stream socket, before subsequent }{\b\f7\uldb connect}{\f7\uldb ()}{\v\f8 WinSock_Connect}{\f7 s or }{\b\f7\uldb listen}{\f7\uldb () }{\v\f8 WinSock_Listen}{\f7 s. When a socket is created with }{\b\f7\uldb socket}{\f7\uldb ()}{\v\f8 WinSock_Socket}{\f7 , it exists in a name space (address family), but it has no name assigned. }{\b\f7 bind}{\f7 () establishes the local association (host address/port number) of the socket by assigning a local name to an unnamed socket. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised In the Internet address family, a name consists o}{\f7\revised f several components. For SOCK_DGRAM and SOCK_STREAM, the name consists of three parts: a host address, the protocol number (set implicitly to UDP or TCP, respectively), and a port number which identifies the application. If an application does not care }{\f7\revised what address is assigned to it, it may specify an Internet address equal to INADDR_ANY, a port equal to 0, or both. If the Internet address is equal to INADDR_ANY, any appropriate network interface will be used; this simplifies application programming i }{\f7\revised n }{\f7\revised the presence of multi-homed hosts. If the port is specified as 0, the Windows Sockets implementation will assign a unique port to the application with a value between 1024 and 5000. The application may use }{ \b\f7\uldb\revised getsockname()}{\v\f7 Winsock_getsockname}{\f7\revised after }{\b\f7\revised bind()}{\f7\revised to learn the address that has been assigned to it, but note that }{\b\f7\revised getsockname()}{\f7\revised will not necessarily fill in the Internet address until the socket is connected, since several Internet addresses may be valid if the host is multi-homed. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised If an application des}{\f7\revised ires to bind to an arbitrary port outside of the range 1024 to 5000, such as the case of rsh which must bind to any reserved port, code similar to the following may be used: \par }\pard\plain \fs20\lang1033 {\f4 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 {\revised SOCKADDR_IN sin; \par }{\revised SOCKET s; \par }{\revised u_short alport = IPPORT_RESERVED; \par } \par {\revised sin.sin_family = AF_INET; \par }{\revised sin.sin_addr.s_addr = 0; \par }{\revised for (;;) \{ \par }{\revised sin.sin_port = htons(alport); \par }{\revised if (bind(s, (LPSOCKADDR)&sin, sizeof (sin)) == 0) \{ \par }{\revised /* it worked */ \par }{\revised \} \par }{\revised if ( GetLastError() != WSAEADDRI}{\revised NUSE) \{ \par }{\revised /* fail */ \par }{\revised \} \par }{\revised alport--; \par }{\revised if (alport == IPPORT_RESERVED/2 ) \{ \par }{\revised /* fail--all unassigned reserved ports are */ \par }{\revised /* in use. */ \par }{\revised \} \par }{\revised \} \par }\pard\plain \s12\li1440 \fs20\lang1033 \par \pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 bind()}{\f7 returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{ \v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENE}{\f7 TDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEADDRINUSE \tab The specified address is already in use. (See the SO_REUSEADDR socket option under }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 .) \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 namelen}{\f7 argument is too small (less than the size of a struct sockaddr). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEINPROGRESS\tab A blocking Windows Sockets call is in progress. \par }{\f7 \par }{\f7 WSAEAFNOSUPPORT\tab The specif}{\f7 ied address family is not supported by \par }{\f7 this protocol. \par }{\f7 \par }{\f7 WSAEINVAL\tab The socket is already bound to an address. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab Not enough buffers available, too many connections. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 See Also}{\f7 \tab }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\b\f7 ,}{\f7 }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\b\f7 , }{\b\f7\uldb getsockname()}{\v\f8 WinSock_GetSockName}{\b\f7 ,}{ \f7 }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\b\f7 ,}{\f7 }{\b\f7\uldb socket()}{\v\f8 WinSock_Socket}{\b\f7 ,}{\f7 }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\b\f7 .}{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_CloseSocket}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 closesocket()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 closesocket()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 closesocket() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Close a sock}{\plain \f7\fs20\lang1033 et.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int FAR PASCAL closesocket ( SOCKET {\plain \i\f7\fs20\lang1033 s}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function closes a socket. More precisely, it releases the socket descriptor }{\i\f7 s}{\f7 , so that further references to }{\i\f7 s}{\f7 will fail with the error WSAENOTSOCK. If this is the last reference to the underlying socket, the associated naming information and queued data are discarded. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The semantics of }{\b\f7 closesocket}{\f7 () are affected by the socket options SO_LINGER and SO_DONTLINGER as follow}{\f7 s: \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\b\f7\ulw Option\tab \tab Interval\tab Type of close\tab Wait for close?}{\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 SO_DONTLINGER\tab Don't care\tab Graceful\tab \tab No \par }{\f7 SO_LINGER\tab \tab Zero\tab \tab Hard\tab \tab \tab No \par }{\f7 SO_LINGER\tab \tab Non-zero\tab Graceful\tab \tab Yes \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If SO_LINGER is set (i.e. the }{\i\f7 l_onoff}{\f7 field of the linger structure is non-zero; see }{\f7\uldb Socket Options}{\v\f7 WinsockProg_SocketOptions}{\f7 , }{\f7\uldb getsockopt()}{\v\f7 Winsock_getsockopt}{\f7 and }{\f7\uldb setsockopt()}{\v\f7 Winsock_setsockopt}{\f7 ) with a zero timeout interval (}{\i\f7 l_linger}{\f7 is zero), }{\b\f7 closesocket()}{\f7 is not blocked even if queued data has not yet been sent or acknowledged. This is called a "hard"}{\f7 close, because the socket is closed immediately, and any unsent data is lost. Any }{\b\f7\uldb recv()}{\v\f7 WinSock_Recv}{\f7 call on the remote side of the circuit can fail with WSAECONNRESET. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If SO_LINGER is set with a non-zero timeout interval, the }{\b\f7 closesocket()}{\f7 call blocks until the remaining data has been sent or until the timeout expires. This is called a graceful disconnect. }{\f7\revised Note that if the socket is set to non-blocking and SO_LINGER is set to a non-zero timeout, the call to }{\b\f7\revised closesocket() }{\f7\revised will fail with an error of W}{\f7\revised SAEWOULDBLOCK.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If SO_DONTLINGER is set on a stream socket (i.e. the }{\i\f7 l_onoff}{\f7 field of the linger structure is zero; see }{\f7\uldb Socket Options}{\v\f7 WinsockProg_SocketOptions}{\f7 , }{\f7\uldb getsockopt()}{ \v\f7 Winsock_getsockopt}{\f7 and }{\f7\uldb setsockopt()}{\v\f7 Winsock_setsockopt}{\f7 ), the }{\b\f7 closesocket()}{\f7 call will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case the Windows Sockets implementation may not relea }{\f7 se the so}{\f7 cket and other resources for an arbitrary period, which may affect applications which expect to use all available sockets. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 closesocket()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the netw}{\f7 ork subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }{\f7 WSAEINPROGRESS\tab A blocking Windows Sockets call is in progress. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb\revised WSACancelBlockingCall()}{\v\f7 Winsock_CancelBlockingCall}{\b\f7\revised . \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\b\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEWOULDBLOCK\tab The socket is marked as nonblocking and SO_LINGER is set to a nonzero timeout value. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 \par \pard \s9\fi-1440\li1440\tx1440 See Also\tab {\uldb accept()}{\plain \v\f8\fs20\lang1033 WinSock_Accept}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb ioctlsocket()}{\plain \v\f8\fs20\lang1033 WinSock_IOCTLSocket}, {\uldb setsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_SetSockOpt}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Connect}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 connect()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 connect()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 connect() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Establish a connection to a peer.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR connect ( SOCKET {\plain \i\f7\fs20\lang1033 s}, const struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 name}, int {\plain \i\f7\fs20\lang1033 namelen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying an unconnected socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab The name of the peer to which the socket is to be connected. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 namelen}{\f7 \tab The length of the }{\i\f7 name}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is used to create a connection to the specified foreign association. The parameter }{\i\f7 s}{\f7 specifies an unconnected datag}{\f7 ram or stream socket If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound. Note that if the address field of the }{\i\f7 name}{\f7 structure is all zeroes, }{\b\f7 connect()}{ \f7 will return the error WSAEADDRNOTAVAIL. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 For stream sockets (type SOCK_STREAM), an active connection is initiated to the foreign host using }{\i\f7 name}{\f7 (an address in the name space of the socket). When the socket call completes successfully, the socket is ready to send/receive data. }{\f7 \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 For a datagram socket (type SOCK_DGRAM), a default destination is set, which will be used on subsequent }{\b\f7\uldb send}{\f7\uldb ()}{\v\f8 WinSock_Send}{\f7 and }{\b\f7\uldb recv}{\f7\uldb ()}{\v\f8 WinSock_Recv}{\f7 calls. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7\revised On a non-blocking socket, if the return value is SOCKET_ERROR an application should call }{\b\f7\uldb\revised WSAGetLastError()}{\v\f7 WinSock_GetLastError}{\b\f7\revised .}{\f7\revised If this indicates an error code of WSAEWOULDBLOCK, then your application can either: \par }\pard \s14\li1440 {\f7 \par }\pard \s14\li1440 {\f7\revised 1. Use }{\b\f7\revised select()}{\f7\revised to determine the completion of the connection request by checking if the socket is writeable, or \par }\pard \s14\li1440 {\f7 \par }\pard \s14\li1440 {\f7\revised 2. If your applicat}{\f7\revised ion is using the message-based }{\b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 WinSock_AsyncSelect}{\f7\revised to indicate interest in connection events, then your application will receive an FD_CONNECT message when the connect operation is complete. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 connect()}{\f7 returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{ \v\f8 WinSock_GetLastError}{\b\f7 . \par }\pard \s7\fi-1440\li1440 {\b\f7 \par }\pard \s7\fi-1440\li1440 {\b\f7 \tab }{\f7 On a blocking socket, the return value indicates success or failure of the connection attempt. \par }\pard \s7\fi-1440\li1440 {\f7 \par }{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Code}{\b\f7 s}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEADDRINUSE\tab The specified address is already in use. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEINPROGRESS\tab A blocking Windows Sockets call is in progress. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEADDRNOTAVAIL\tab The specified address is not available from the local machine. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEAF}{\f7 NOSUPPORT\tab Addresses in the specified family cannot be used with this socket. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAECONNREFUSED\tab The attempt to connect was forcefully rejected. \par }{\f7 \par }{\f7 WSAEDESTADDREQ\tab A destination address is required. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 namelen}{\f7 argument is incorrect. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEINVAL\tab The socket is not already bound to an address. \par }{\f7 \par }{\f7 WSAEISCONN\tab The socket is already connected. \par }{\f7 \par }{\f7 WSAEMFILE\tab No more file descriptors are available. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETUNREACH\tab The network can't be reached from this host at this time. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab No buffer space i}{\f7 s available. The socket cannot be connected. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAETIMEDOUT\tab Attempt to connect timed out without establishing a connection \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEWOULDBLOCK \tab The socket is marked as non-blocking and the connection cannot be completed immediately. It is possible to }{\b\f7\uldb\revised select()}{\v\f7 Winsock_select}{ \f7\revised the socket while it is connecting by }{\b\f7\revised select()}{\f7\revised ing it for writing. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb accept()}{\plain \v\f8\fs20\lang1033 WinSock_Accept}, {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb getsockname()}{\plain \v\f8\fs20\lang1033 WinSock_GetSockName}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Select}{\plain \f8\fs20\lang1033 , and }{\uldb WSAAsyn}{\uldb cSelect}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetPeerName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 getpeername()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getpeername()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getpeername() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get the address of the peer to which a socket is connected.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR getpeername(SOCKET {\plain \i\f7\fs20\lang1033 s}, struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 name}, int FAR * {\plain \i\f7\fs20\lang1033 namelen}); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880\tx3960 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a connected socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab The structure which is to receive the name of the peer. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 namelen}{\f7 \tab A pointer to the size of the }{\i\f7 name}{\f7 structure. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getpeername()}{\f7 retrieves the name of the peer connecte}{\f7 d to the socket }{\i\f7 s}{\f7 and stores it in the struct sockaddr identified by }{\i\f7 name}{\f7 . It is used on a connected datagram or stream socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 On return, the }{\i\f7 namelen}{\f7 argument contains the actual size of the name returned in bytes. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getpeername()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur be}{\f7 fore using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEFAULT\tab The namelen argument is not large enough. \par }{\f7 \par }{\f7 WSAEINPROGRESS\tab A blocking Windows Sockets call is in progress. \par }{\f7 \par }{\f7 WSAENOTCONN\tab The socket is not connected. \par }{\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb getsockname()}{\plain \v\f8\fs20\lang1033 WinSock_GetSockName}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetSockName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 getsockname()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getsockname()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getsockname() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get the local n}{\plain \f7\fs20\lang1033 ame for a socket.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR getsockname(SOCKET {\plain \f7\fs20\lang1033 s}, struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 name}, int FAR * {\plain \i\f7\fs20\lang1033 namelen}); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a bound socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab Receives the address (name) of the socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 namelen}{\f7 \tab }{\b\f7 }{\f7 The size of the }{\i\f7 name}{\f7 buffer. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getsockname()}{\f7 retrieves the current name for the specified socket descriptor in }{\i\f7 name}{\f7 . It is used on a bound and/or connected socket specified by the }{ \i\f7 s}{\f7 parameter. The local association is returned. This call is especially use}{\f7 ful when a }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 call has been made without doing a }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 first; this call provides the only means by which you can determine the local association which has been set by the system. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard \s5\fi-1440\li1440 {\f7 \tab On return, the }{\i\f7 namelen}{\f7 argument contains the actual size of the name returned in bytes. \par }\pard\plain \s12\li1440 \fs20\lang1033 \par \pard \s12\li1440 {\f7\revised If a socket was bound to INADDR_ANY, indicating that any of the host's IP addresses should be used for the socket, }{\b\f7\revised getsockname()}{\f7\revised will not necessarily return information about the host IP address, unless }{\f7\revised the socket has been connected with }{\b\f7\uldb\revised connect()}{\v\f7 Winsock_connect}{\f7 or }{\b\f7\uldb accept()}{\v\f7 WinSock_accept}{\b\f7\revised .}{ \f7\revised A Windows Sockets application must not assume that the IP address will be changed from INADDR_ANY unless the socket is connected. This is because for a multi-homed host the IP address that will be used for the socket is unknown unless the socket is con }{\f7\revised nected. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getsockname()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calli}{\f7 ng }{ \b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 namelen}{\f7 argument is not large enough. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEINVAL\tab The socket has not been bound to an address with }{\b\f7\uldb\revised bind()}{\v\f7 Winsock_bind}{\b\f7\revised .}{\revised \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb getpeername()}{\plain \v\f8\fs20\lang1033 WinSock_GetPeerName}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetSockOpt}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 getsockopt()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getsockopt()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getsockopt() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Retrieve a socket option.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR getsockopt ( SOCKET {\plain \i\f7\fs20\lang1033 s}, int {\plain \i\f7\fs20\lang1033 level}, int {\plain \i\f7\fs20\lang1033 optname}, char FAR * {\plain \i\f7\fs20\lang1033 optval} , int FAR * {\plain \i\f7\fs20\lang1033 optlen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 level}{\f7 \tab The level at which the option is defined; the only supported }{\i\f7 levels}{\f7 are SOL_SOCKET and IPPROTO_TCP. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optname}{\f7 \tab The socket option for which the valu}{\f7 e is to be retrieved. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optval}{\f7 \tab A pointer to the buffer in which the value for the requested option is to be returned. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optlen}{\f7 \tab A pointer to the size of the }{\i\f7 optval}{\f7 buffer. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getsockopt()}{\f7 retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in }{\i\f7 optval}{\f7 . Options may exist at multiple protocol levels, but they are always present at the uppermost "socket'' level. Options affect socket operations, such as whether an operation blocks o}{\f7 r not, the routing of packets, out-of-band data transfer, etc. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The value associated with the selected option is returned in the buffer }{\i\f7 optval}{\f7 . The integer pointed to by }{\i\f7 optlen}{\f7 should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a struct linger; for all other options it will be the size of an integer. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If the option was never set with }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\b\f7 ,}{\f7 then }{\b\f7 getsockopt()}{\f7 returns the defa}{\f7 ult value for the option. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The following options are supported for }{\b\f7 getsockopt()}{\f7 . The }{\b\f7 Type}{\f7 identifies the type of data addressed by }{\i\f7 optval}{\f7 . The TCP_NODELAY option uses level IPPROTO_TCP, all other options use level SOL_SOCKET. \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\b\f7\ulw Value\tab Type\tab Meaning}{\f7 \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_ACCEPTCONN\tab BOOL\tab Socket is }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\f7 ing. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_BROADCAST\tab BOOL\tab Socket is configured for the transmission of broadcast messages. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_DEBUG\tab BOOL\tab Debugging is enabled. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_DONTLINGER\tab BOOL\tab If true, the SO_LINGER option is disabled.. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_DONTROUTE\tab BO}{\f7 OL\tab Routing is disabled. \par }{\f7 SO_ERROR\tab int\tab Retrieve error status and clear. \par }{\f7 SO_KEEPALIVE\tab BOOL\tab Keepalives are being sent. \par }{\f7 SO_LINGER\tab struct linger FAR *\tab Returns the current linger options. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_OOBINLINE\tab BOOL\tab Out-of-band data is being received in the normal data stream. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_RCVBUF\tab int\tab Buffer size for receives \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_REUSEADDR\tab BOOL\tab The socket may be bound to an address which is already in use. \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_SNDBUF\tab int\tab Buffer size for sends \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_TYPE\tab int\tab The type of the socket (e.g. SOCK_STREAM). \par }{\f7 TCP_NODELAY\tab BOOL\tab Disables t}{\f7 he Nagle algorithm for send coalescing. \par }\pard\plain \li2160 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 BSD options not supported for }{\b\f7 getsockopt()}{\f7 are: \par }\pard\plain \li2160 \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-4320\li5040\tx2880\tx5040 \fs20\lang1033 {\b\f7\ulw Value\tab Type\tab Meaning}{\f7 \par }\pard \s10\fi-4320\li5040\tx2880\tx5040 {\f7 SO_RCVLOWAT\tab int\tab Receive low water mark \par }{\f7 SO_RCVTIMEO\tab int\tab Receive timeout \par }{\f7 SO_SNDLOWAT\tab int\tab Send low water mark \par }{\f7 SO_SNDTIMEO\tab int\tab Send timeout \par }{\f7 IP_OPTIONS\tab \tab Get options in IP header. \par }{\f7 TCP_MAXSEG\tab int\tab Get TCP maximum segment size. \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 Calling }{\b\f7 getsockopt()}{\f7 with an unsupported option will result in an error code of WSAENOPROTOOPT being returned from }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return V}{\b\f7 alue}{\f7 \tab If no error occurs, }{\b\f7 getsockopt()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{ \b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 optlen}{\f7 argument was invalid. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in prog}{\f7 ress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOPROTOOPT\tab The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCON, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\tx1440\tx4320\tx5040 {\f7\revised WSAENOPROTOOPT\tab The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCONN, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type}{\f7\revised SOCK_DGRAM. }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \par \pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb setsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_SetSockOpt}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_HtoNL}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 htonl()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0080}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 htonl()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 htonl() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a }u_long {\plain \f7\fs20\lang1033 from host to network byte order.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 {\plain \f7\fs20\lang1033 }\tab u_long PASCAL FAR htonl ( u_long {\plain \i\f7\fs20\lang1033 hostlong}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hostlong}{\f7 \tab A 32-bit number in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine takes a 32-bit number in host byte order and returns a 32-bit number in network b}{\f7 yte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab }{\b\f7 htonl()}{\f7 returns the value in network byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb htons()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNS}, {\uldb ntohl()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHL}, {\uldb ntohs()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHS}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_HtoNS}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 htons()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0090}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 htons()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 htons() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a }u_short {\plain \f7\fs20\lang1033 from host to network byte order.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab u_short PASCAL FAR htons ( u_short {\plain \i\f7\fs20\lang1033 hostshort }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hostshort}{\f7 \tab A 16-bit number in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine takes a 16-bit number in host byte order and returns a 16-bit number in network byte }{\f7 order. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab }{\b\f7 htons()}{\f7 returns the value in network byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb htonl()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNL}, {\uldb ntohl()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHL}, {\uldb ntohs()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHS}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_InetAddr}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 inet_addr()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0100}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 inet_addr()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 inet_addr() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a string containing a dotted address into an }in_addr{\plain \f7\fs20\lang1033 .} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab unsigned long PASCAL FAR inet_addr ( const char FAR * {\plain \i\f7\fs20\lang1033 cp}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 cp}{\f7 \tab A character string representing a number expressed in the Internet standard ".'' notation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function interprets th}{\f7 e character string specified by the }{\i\f7 cp}{\f7 parameter. This string represents a numeric Internet address expressed in the Internet standard ".'' notation. The value returned is a number suitable for use as an Internet address. All Internet addresses are returned in network order (bytes ordered }{\f7 from left to right). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\ul Internet Addresses \par }{\f7 \par }{\f7 Values specified using the ".'' notation take one of the following forms: \par }{\f7 \par }{\f7 a.b.c.d\tab a.b.c\tab a.b\tab a \par }{\f7 \par }\pard \s12\li1440 {\f7 When four parts are specified, each is interpreted as a byte of data and }{\f7 assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on the Intel architecture, the bytes referred to above appear as "d.c.b.a''. That is, the bytes on an Intel }{\f7 processor are ordered from right to left. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note: The following notations are only used by Berkeley, and nowhere else on the Internet. In the interests of compatibility with their software, they are supported as specified. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 When a three part address is}{\f7 specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as "128.net.host''. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 When a two part address is specified, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.ho }{\f7 st''. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 When o}{\f7 nly one part is given, the value is stored directly in the network address without any byte rearrangement. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 inet_addr()}{\f7 returns an unsigned long containing a suitable binary representation of the Internet address given. }{\f7\revised If the passed-in string does not contain a legitimate Internet address, for example if a portion of an "a.b.c.d" address exceeds 255, }{\b\f7\revised inet_addr() }{\f7\revised returns the value INADDR_NONE.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb inet_ntoa()}{\plain \v\f8\fs20\lang1033 WinSock_InetNtoA}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_InetNtoA}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 inet_ntoa()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0110}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 inet_ntoa()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 inet_ntoa() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a network address into a string in dotted format.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab char FAR * PASCAL FAR inet_ntoa ( struct in_addr {\plain \i\f7\fs20\lang1033 in}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 in}{\f7 \tab A structure which represents an Internet host address. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function takes an Internet address structure specified by the }{\i\f7 in}{\f7 parameter. It returns an ASCII string representing the address in ".'' notation as "a.b.c.d''. Note that the string returned by }{\b\f7 inet_ntoa()}{\f7 resides in memory which is allocated by the Win}{\f7 dows Sockets implementation. The application should not make any assumptions about the way in which the memory is allocated. The data is guaranteed to be valid until the next Windows Sockets API call within the same thread, but no longer. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 inet_ntoa()}{\f7 returns a char pointer to a static buffer containing the text address in standard ".'' notation. Otherwise, it returns NULL. The data should be copied before another Windows Sockets call is made. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb inet_addr()}{\plain \v\f8\fs20\lang1033 WinSock_InetAddr}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_IOCTLSocket}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 ioctlsocket()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0120}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 ioctlsocket()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 ioctlsocket() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Control the mode of a socket.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR ioctlsocket ( SOCKET {\plain \i\f7\fs20\lang1033 s}, long {\plain \i\f7\fs20\lang1033 cmd}, u_long FAR * {\plain \i\f7\fs20\lang1033 argp}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 cmd}{\f7 \tab The command to perform on the socket }{\i\f7 s}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 argp}{\f7 \tab A pointer to a parameter for }{\i\f7 cmd}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine may be used on any socket in any state. It is used to get or retrieve operating parameters associated with the socket, independent of t}{\f7 he protocol and communications subsystem. The following commands are supported: \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\b\f7\ulw Command\tab Semantics \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 FIONBIO\tab Enable or disable non-blocking mode on the socket }{\i\f7 s}{\f7 . }{\i\f7 argp}{\f7 points at an }{\b\f7 unsigned long}{\f7 , which is non-zero if non-blocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (i.e. non-blocking mode is disabled). This is consistent with BSD sockets. \par }\pard \s10\fi-1440\li2880 {\f7\revised \tab The }{\b\f7\uldb\revised WSAAsyncSelect()}{\v\f7 Winsock_AsyncSelect}{\b\f7\revised }{\f7\revised routine automatically sets a socket to nonblocking}{\f7\revised mode. If }{\b\f7\revised WSAAsyncSelect() }{ \f7\revised has been issued on a socket, then any attempt to use }{\b\f7\revised ioctlsocket() }{\f7\revised to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable }{ \b\f7\revised WSAAsyncSelect() }{\f7\revised by calling }{\b\f7\revised WSAAsyncSelect() }{\f7\revised with the }{\i\f7\revised lEvent}{\f7\revised parameter equal to 0.}{\f7 \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 FIONREAD\tab Determine the amount of data which can be read atomically from socket }{\i\f7 s}{\f7 . }{\i\f7 argp}{\f7 points at an }{\b\f7 unsigned long}{\f7 in which }{\b\f7 ioctlsocket()}{\f7 stores the result. If }{ \i\f7 s}{\f7 is of type SOCK_STREAM, FI}{\f7 ONREAD returns the total amount of data which may be read in a single }{\b\f7 recv()}{\f7 ; this is normally the same as the total amount of data queued on the socket. If }{\i\f7 s}{\f7 is of type SOCK_DGRAM, FIONREAD returns the size of the first datagram queued on the socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 SIOCATMARK\tab Determine whether or not all out-of-band data has been read. This applies only to a socket of type SOCK_STREAM which has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be rea}{\f7 d}{ \f7 , the operation returns TRUE. Otherwise it returns FALSE, and the next }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 or }{\b\f7\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\f7 performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be r }{\f7 eceived in order. (Note that a }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 or }{\b\f7\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\f7 will never mix out-of-band and normal data in the same }{\f7 call.) }{\i\f7 argp}{\f7 points at a }{\b\f7 BOOL}{ \f7 in which }{\b\f7 ioctlsocket()}{\f7 stores the result. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard \fi-1440\li1440 {\b\f7 Compatibility}{\f7 \tab This function is a subset of }{\b\f7 ioctl()}{\f7 as used in Berkeley sockets. In particular, there is no command which is equivalent to FIOASYNC, while SIOCATMARK is the only socket-level command which is supported. \par }\pard {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab Upon successful completion, the }{\b\f7 ioctlsocket()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{ \b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab }{\i\f7 cmd}{\f7 is not a valid command, or }{\i\f7 argp}{\f7 is not an acceptable parameter for }{\i\f7 cmd}{\f7 , or the command is not applicable to the type of socket supplied \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENOTSOCK\tab The descriptor }{\i\f7 s}{\f7 is not a socket. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_}{\plain \v\f8\fs20\lang1033 Socket}, {\uldb setsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_SetSockOpt}, {\uldb getsockopt()} {\plain \v\f8\fs20\lang1033 WinSock_GetSockOpt}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 Winsock_AsyncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Listen}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 listen()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0130}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 listen()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 listen() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Establish a socket to listen for incoming connection.} \par \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR listen(SOCKET {\plain \i\f7\fs20\lang1033 s}, int {\plain \i\f7\fs20\lang1033 backlog}{\i }); \par \pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 \par }{\i\f7 s}{\f7 \tab A descriptor identifying a bound, unconnected socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 backlog}{\f7 \tab The maximum length to which the queue of pending connections may grow. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab To accept connections, a socket is first created wit}{\f7 h }{\b\f7\uldb socket}{\f7\uldb ()}{\v\f8 WinSock_Socket}{\f7 , a backlog for incoming connections is specified with }{\b\f7 listen}{\f7 (), and then the connections are accepted with }{\b\f7\uldb accept}{\f7\uldb ()}{\v\f8 WinSock_Accept}{\f7 . }{\b\f7 listen}{\f7 () applies only to sockets that support connections, i.e. those of type SOCK_STREAM. The socket }{\i\f7 s}{\f7 is put into "passive'' mode where incoming connections are acknowledged and queued pending acceptance by the process. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 This function is typically used by servers that could have more than one connection request at a time: if a connection request ar}{\f7 rives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\b\f7 listen}{\f7 () attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to }{ \b\f7 listen}{\f7 () or }{\b\f7\uldb accept}{\f7\uldb ()}{\v\f8 WinSock_Accept}{\f7 will re-fill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Compatibility}{\f7 \tab }{\i\f7 backlog}{\f7 is currently limited (sil}{\f7 ently) to 5. As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest legal value. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 listen()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem }{\f7 has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEADDRINUSE\tab An attempt has been made to }{\b\f7 listen()}{\f7 on an address in use. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEFAULT\tab An invalid argument was given. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab The socket has not been bound with }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 or is already connected. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEISCONN\tab The socket is already connected. \par }{\f7 \par }{\f7 WSAEMFILE\tab No more file descriptors are available. \par }{\f7 \par }{\f7 WSAENOBUFS\tab No buffer space is available. \par }{\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab The refer}{\f7 enced socket is not of a type that supports the }{\b\f7 listen()}{\f7 operation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb accept()}{\plain \v\f8\fs20\lang1033 WinSock_Accept}, {\uldb connect()}{\plain \v\f8\fs20\lang1033 WinSock_Connect}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket }. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_NtoHL}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 ntohl()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0140}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 ntohl}{\f7 ()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 ntohl() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a }u_long{\plain \f7\fs20\lang1033 from network to host byte order.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab u_long PASCAL FAR ntohl ( u_long {\plain \i\f7\fs20\lang1033 netlong}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 netlong}{\f7 \tab A 32-bit number in network byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine takes a 32-bit number in network byte order and returns a 32-bit number in host byte order}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab }{\b\f7 ntohl()}{\f7 returns the value in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb htonl()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNL}, {\uldb htons()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNS}, {\uldb ntohs()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHS}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_NtoHS}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 ntohs()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0150}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 ntohs()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 ntohs() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Convert a }u_short {\plain \f7\fs20\lang1033 from network to host byte order.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab u_short PASCAL FAR ntohs ( u_short {\plain \i\f7\fs20\lang1033 netshort }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 netshort}{\f7 \tab A 16-bit number in network byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This routine takes a 16-bit number in network byte order and returns a 16-bit number in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab }{\b\f7 ntohs()}{\f7 returns the value in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb htonl()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNL}, {\uldb htons()}{\plain \v\f8\fs20\lang1033 WinSock_HtoNS}, {\uldb ntohl()}{\plain \v\f8\fs20\lang1033 WinSock_NtoHL}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Recv}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 recv()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0160}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 recv()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 recv() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Receive data from a socket.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR recv ( int {\plain \i\f7\fs20\lang1033 s}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 flags}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a connected socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A buffer for the incoming data. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 len}{\f7 \tab The length of }{\i\f7 buf}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 flags}{\f7 \tab Specifies the way in which the call is made. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab T}{\f7 his function is used on connected datagram or stream sockets specified by the }{\i\f7 s}{\f7 parameter and is used to read incoming data. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band dat }{\f7 a is unread, only out-of-band data will be returned. The application may use the }{\b\f7\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSocket}{\f7 SIOCATMARK to }{\f7 determine whether any more out-of-band data remains to be read. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the buffer supplied. If the datagram is larger than the buffer supplied, the excess data is lost, and }{\b\f7 recv()}{\f7 returns the error WSAEMSGSIZE. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If no incoming data is available at the socket, the }{\b\f7 recv()}{\f7 call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set}{\f7 to WSAEWOULDBLOCK. The }{\b\f7\uldb select}{\f7\uldb ()}{\v\f8 WinSock_Select}{\f7 or }{\b\f7\uldb WSAAsyncSelect}{\f7\uldb ()}{\v\f8 WinSock_AsyncSelect}{\f7 calls may be used to determine when more data arrives. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a }{\b\f7\revised recv()}{\f7\revised will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a }{\b\f7\revised recv() }{\f7\revised will fail with the error WSAECONN}{\f7 RESET}{\f7\revised . \par }\pard \s12\li1440 {\i\f7 \par }\pard \s12\li1440 {\i\f7 Flags}{\f7 may be used to influence the behavior of the function invocation beyond the options specified for th}{\f7 e associated socket. That is, the semantics of this function are determined by the socket options and the }{ \i\f7 flags}{\f7 parameter. The latter is constructed by or-ing any of the following values: \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\b\f7\ulw Value\tab Meaning}{\f7\ul \par }\pard \s10\fi-1440\li2880 {\f7 MSG_PEEK\tab Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 MSG_OOB\tab Process out-of-band data (See }{\f7\uldb Out of Band Data}{\v\f7 WinsockSockets_OutOfBand}{\f7 for a discussion of this topic.) \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 recv()}{\f7 returns the number of bytes r}{\f7 eceived. If the connection has been closed, it returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTCONN\tab The socket is not connected. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACance}{\b\f7\uldb lBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab MSG_OOB was specified, but the socket is not of type SOCK_STREAM. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAESHUTDOWN\tab The socket has been shutdown; it is not possible to }{\b\f7 recv()}{\f7 on a socket after }{\b\f7\uldb shutdown()}{\v\f8 WinSock_Shutdown}{\f7 has been invoked with }{\i\f7 how}{ \f7 set to 0 or 2. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The socket is marked as non-blocking and the receive operation would block. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEMSGSIZE}{\f7\revised \tab The datagram was too large to fit into the specified buffer and was truncated. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab The socket has not been bound with }{\b\f7 bind(). \par }{\b\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAECONNABORTED\tab The virtual circuit was abort}{\f7 ed due to timeout or other failure}{\f7\revised .}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAECONNRESET\tab The virtual circuit was reset by the remote side.}{\f7\revised \par }{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb recvfrom()}{\plain \v\f8\fs20\lang1033 WinSock_RecvFrom}, {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send}, {\uldb select()}{\plain \v\f8\fs20\lang1033 WinSock_Select}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Select}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_RecvFrom}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 recvfrom()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0170}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 recvfrom()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 recvfrom() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Receive a}{\plain \f7\fs20\lang1033 datagram and store the source address.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR recvfrom ( int {\plain \i\f7\fs20\lang1033 s}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 flags} , struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 from}, int FAR * {\plain \i\f7\fs20\lang1033 fromlen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a bound socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A buffer for the incoming data. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 len}{\f7 \tab The length of }{\i\f7 buf}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 flags}{\f7 \tab Specifies the way in which the call is made. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 from}{\f7 \tab An optional pointer to a buffer which will hold the source address upon return. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 fromlen}{\f7 \tab An optional pointer to the size of the }{\i\f7 from}{\f7 buffer. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Re}{\b\f7 marks}{\f7 \tab This function is used to read incoming data on a (possibly connected) socket and capture the address from which the data was sent. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band dat }{\f7 a is unread, only out-of-band data will be returned. The application may use the }{\b\f7\uldb ioctlsocket()}{\v\f8 WinSock_IOCTLSocket}{\f7 SI}{\f7 OCATMARK to determine whether any more out-of-band data remains to be read.}{\revised }{ \f7\revised The }{\i\f7\revised from }{\f7\revised and }{\i\f7\revised fromlen }{\f7\revised parameters are ignored for SOCK_STREAM sockets.}{\f7 \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the buffer supplied. }{\f7\revised If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and }{\b\f7\revised recvfrom() }{\f7\revised returns the error code WSAEMSGSIZE.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If }{\i\f7 from}{\f7 is non-zero, and the socket is of type SO}{\f7 CK_DGRAM, the network address of the peer which sent the data is copied to the corresponding struct sockaddr. The value pointed to by }{ \i\f7 fromlen}{\f7 is initialized to the size of this structure, and is modified on return to indicate the actual size of the address stored there. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If no incoming data is available at the socket, the }{\b\f7 recvfrom()}{\f7 call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The }{\b\f7\uldb select}{\f7\uldb ()}{\v\f8 Win}{\v\f8 Sock_Select}{\f7 or }{\b\f7\uldb WSAAsyncSelect}{\f7\uldb ()}{\v\f8 WinSock_AsyncSelect}{\f7 calls may be used to determine when more data arrives. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a }{\b\f7\revised recv}{\b\f7 from}{\b\f7\revised ()}{\f7\revised will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a }{\b\f7\revised recv}{\b\f7 from}{\b\f7\revised () }{\f7\revised will fail with the error WSAECONN}{\f7 RESET}{\f7\revised .}{\f7 \par }\pard \s12\li1440 {\i\f7 \par }\pard \s12\li1440 {\i\f7 Flags}{\f7 may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That i}{\f7 s, the semantics of this function are determined by the socket options and the }{ \i\f7 flags}{\f7 parameter. The latter is constructed by or-ing any of the following values: \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880\keepn \fs20\lang1033 {\b\f7\ulw Value\tab Meaning}{\f7\ul \par }\pard \s10\fi-1440\li2880 {\f7 MSG_PEEK\tab Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 MSG_OOB\tab Process out-of-band data (See }{\f7\uldb Out of Band Data}{\v\f7 WinsockSockets_OutOfBand}{\f7 for a discussion of this topic.) \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 recvfrom()}{\f7 returns the number of bytes received. If the connect}{\f7 ion has been closed, it returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab The }{\i\f7 fromlen}{\f7 argument was invalid: the }{\i\f7 from}{\f7 buffer was too small to accommodate the peer address. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The}{\f7 (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEINVAL\tab The socket has not been bound with }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 . \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOTCONN\tab The socket is not connected (SOCK_STREAM only). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab MSG_OOB was specified, but the socket is not of type SOCK_STREAM. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAESHUTDOWN\tab The socket has been shutdown; it is not possible to }{\b\f7 recvfrom()}{\f7 on a socket after}{\f7 }{\b\f7\uldb shutdown()}{\v\f8 WinSock_Shutdown}{\f7 has been invoked with }{ \i\f7 how}{\f7 set to 0 or 2. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The socket is marked as non-blocking and the }{\b\f7 recvfrom()}{\f7 operation would block. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAEMSGSIZE\tab The datagram was too large to fit into the specified buffer and was truncated. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\b\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAECONNABORTED\tab The virtual circuit was abort}{\f7 ed due to timeout or other failure}{\f7\revised .}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSCONNRESET\tab The virtual circuit was reset by the remote side. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb recv()}{\plain \v\f8\fs20\lang1033 WinSock_Recv}, {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_Asy}{\plain \v\f8\fs20\lang1033 ncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Select}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 select()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0180}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 select()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 select() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Determine the status of one or more sockets, waiting if necessary.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab long PASCAL FAR select ( int {\plain \i\f7\fs20\lang1033 nfds}, fd_set FAR * {\plain \i\f7\fs20\lang1033 readfds}, fd_set FAR * {\plain \i\f7\fs20\lang1033 writefds}, fd_set FAR * {\plain \i\f7\fs20\lang1033 exceptfds}, const struct timeval FAR * {\plain \i\f7\fs20\lang1033 timeout}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 nfds}{\f7 \tab This argument is ignored and included only for the sake of compatibility. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 readfds}{\f7 \tab An optional pointer to a set of sockets to be checked for readability. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 writefds}{\f7 \tab An optional point}{\f7 er to a set of sockets to be checked for writeability \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 exceptfds}{\f7 \tab An optional pointer to a set of sockets to be checked for errors. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 timeout}{\f7 \tab The maximum time for }{\b\f7 select()}{\f7 to wait, or NULL for blocking operation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is used to determine the status of one or more sockets. For each socket, the caller may request information on read, write or error status. The set of sockets for which a given status is requested is indicated by an fd_set structure. Upo} {\f7 n return, the structure is updat}{\f7 ed to reflect the subset of these sockets which meet the specified condition, and }{\b\f7 select()}{\f7 returns the number of sockets meeting the conditions. A set of macros is provided for manipulating an fd_set. These macros are compatible with those used in the Berkeley software, but the underlying representation is completely different. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The parameter }{\i\f7 readfds}{\f7 identifies those sockets which are to be checked for readability. If the socket is currently }{\b\f7\uldb listen()}{\v\f8 WinSock_Listen}{\f7 ing, it will be marked as readable if}{\f7 an incoming connection request has been received, so that an }{\b\f7\uldb accept()}{\v\f8 WinSock_Accept}{\f8 i}{\f7 s guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading or, }{ \revised }{\f7\revised for sockets of type SOCK_STREAM, that the virtual socket corresponding to the socket has been closed, }{\f7 so that a }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 or }{\b\f7\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\f7 is guaranteed to complete without blocking.}{\f7\revised If the virtual circuit was closed gracefully, then a }{\b\f7\uldb\revised recv()}{\v\f7 Winsock_recv}{\b\f7\revised }{\f7\revised will return immediat}{\f7\revised ely with 0 bytes read; if the virtual circuit was closed abortively, then a }{\b\f7\uldb\revised recv()}{\v\f7 Winsock_recv}{\b\f7\revised }{\f7\revised will complete immediately with the error code WSAECONN}{\f7 RESET}{\f7\revised .}{\f7 The presence of out-of-band data will be checked if the socket option SO_OOBINLINE has been enabled (see }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The parameter }{\i\f7 writefds}{\f7 identifies those sockets which are to be checked for writeability. If a socket is }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 ing (non-blocking), writeability means that the connection establishment is complete}{\f7 . For other sockets, writeability means that a }{\b\f7\ul send()}{\v\f8 WinSock_Send}{\f7 or }{\b\f7\uldb sendto()}{\v\f8 WinSock_SendTo}{\f7 will complete without blocking. [It is not specified how long this guarantee can be assumed to be valid, particularly in a multithreaded environment.] \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The parameter }{\i\f7 exceptfds}{\f7 identifies those sockets which are to be checked for the presence of out-of-band data or any exceptional error conditions. Note that out-of-band data will only be reported in this way if the option SO_OOBINLINE is FALSE. For a SOCK_STREAM}{\f7 , the breaking of the connection by the peer or due to KEEPALIVE failure will be indicated as an exception. This specification does not define which other errors will be included.}{\revised }{\f7\revised If a socket is }{\b\f7\revised connect()}{ \f7\revised ing (non-blocking), failure of the connect attempt is indicated in }{\i\f7\revised exceptfds.}{\revised \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Any of }{\i\f7 readfds}{\f7 , }{\i\f7 writefds}{\f7 , or }{\i\f7 exceptfds}{\f7 may be given as NULL if no descriptors are of interest. \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Four macros are defined in the header file }{\b\f7 winsock.h}{\f7 for manipulating the descriptor sets. The variable FD_SETSIZE determines }{\f7 the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which may be modified by #defining FD_SETSIZE to another value before #including }{\b\f7 winsock.h}{\f7 .) Internally, an fd_set is represented as an array of SOCKETs; the last valid entry is followed by an element set to INVALID_SOCKET. The macros are: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\b\f7 FD_CLR(}{\i\f7 s}{\b\f7 , *}{\i\f7 set}{\b\f7 )}{\f7 \tab Removes the descriptor }{\i\f7 s}{\f7 from }{\i\f7 set}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\b\f7 FD_ISSET(}{\i\f7 s}{\b\f7 , *}{\i\f7 set}{\b\f7 )}{\f7 \tab Nonzero if }{\i\f7 s}{\f7 is a member of the }{\i\f7 set}{\f7 , zero otherwise. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\b\f7 FD_SET(}{\i\f7 s}{\b\f7 , *}{\i\f7 set}{\b\f7 )}{\f7 \tab \tab Adds descriptor }{\i\f7 s}{\f7 to }{\i\f7 set}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\b\f7 FD_ZERO(}{\b\f7 *}{\i\f7 set}{\b\f7 )}{\f7 \tab \tab Initializes the }{\i\f7 set}{\f7 to the NULL set. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The parameter }{\i\f7 timeout}{\f7 controls how long the }{\b\f7 select()}{\f7 may take to complete. If }{\i\f7 timeout}{\f7 is a null pointer, }{\b\f7 select()}{\f7 will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, }{\i\f7 timeout}{\f7 points to a struct timeval which specifies the maximum time that }{\b\f7 select()}{\f7 should wait before returning. If the timeval is initialized to \{0, 0\}, }{\b\f7 select()}{\f7 will return immediately; this is used to "poll" the state of the selected sockets.}{\revised }{\f7\revised If this}{\f7\revised is the case, then the }{ \b\f7\revised select() }{\f7\revised call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook must not be called, and the Windows Sockets implementation must not yield.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab }{\b\f7 select()}{\f7 returns the total number of descriptors which are ready and contained in the fd_set structures, or 0 if the time limit expired}{\revised , or SOCKET_ERROR if an error occurred. If the return value is SOCKET_ERROR, }{\b\uldb\revised WSAGetLastError()}{\v Winsock_GetLastError}{\revised may be used to }{\revised retrieve a specific error code.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab The }{\i\f7 timeout}{\f7 value is not valid. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENOTSOCK\tab One of the descriptor sets contains an e}{\f7 ntry which is not a socket. \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 \par \pard \s9\fi-1440\li1440\tx1440 See Also\tab {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}, {\uldb accept()}{\plain \v\f8\fs20\lang1033 WinSock_Accept}, {\uldb connect()}{\plain \v\f8\fs20\lang1033 WinSock_Connect}, {\uldb recv()}{\plain \v\f8\fs20\lang1033 WinSock_Recv}, {\uldb recvfrom()}{\plain \v\f8\fs20\lang1033 WinSock_RecvFrom}, {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Send}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 send()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0190}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 send()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 send() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Send data on a connected socket.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR send ( SOCKET {\plain \i\f7\fs20\lang1033 s}, const char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 flags}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a connected socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A buffer containing the data to be transmitted. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 le}{\i\f7 n}{\f7 \tab The length of the data in }{\i\f7 buf}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 flags}{\f7 \tab Specifies the way in which the call is made. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 send}{\f7 () is used on connected datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the }{\i\f7 iMaxUdpDg}{\f7 element in the WSAData structure returned by }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 . If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSI}{\f7 ZE is returned, and no data is transmitted. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Note that the successful completion of a }{\b\f7 send()}{\f7 does not indicate that the data was successfully delivered. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If no buffer space is available within the transport system to hold the data to be transmitted, }{\b\f7 send}{\f7 () will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts.} {\f7 The }{\b\f7\uldb select}{\f7\uldb ()}{\v\f8 WinSock_Select}{\f7 call may be used to determine when it is possible to send more data. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\i\f7 Flags}{\f7 may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the }{\i\f7 flags}{\f7 parameter. The latter is constructed by or-ing any of the following values: \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7\ulw Value\tab Meaning \par }\pard \s10\fi-1440\li2880 {\f7 MSG_DONTROUTE\line Specifies that the data should not be subject to routing. A Windows Sockets suppli}{\f7 er may choose to ignore this flag; see also the discussion of the SO_DONTROUTE option in }{\f7\uldb Socket Options} {\v\f7 WinsockProg_SocketOptions}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 MSG_OOB\tab Send out-of-band data (SOCK_STREAM only; see also }{\f7\uldb Out of Band Data}{\v\f7 WinsockSockets_OutOfBand}{\f7 ) \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 send()}{\f7 returns the total number of characters sent. (Note that this may be less than the number indicated by }{\i\f7 len}{\f7 .) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSoc}{\v\f8 k_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEACCES\tab The requested address is a broadcast address, but the appropriate flag was not set. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEFAULT\tab The }{\i\f7 bu}{\i\f7 f}{\f7 is not in a valid part of the user address space. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETRESET\tab The connection must be reset because the Windows Sockets implementation dropped it. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab The Windows Sockets implementation reports a buffer deadlock. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTCONN\tab The socket is not connected. \par }{\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab MSG_OOB was specified, but the socket is not of type SOCK_STREAM. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAESHUTDOWN\tab The socket has been shutdown; it is not possible to }{\b\f7 send()}{\f7 on a socket after }{\b\f7\uldb shutdown()}{\v\f8 WinSock}{\v\f8 _Shutdown}{\f7 has been invoked with how set to 1 or 2. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The socket is marked as non-blocking and the requested operation would block. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEMSGSIZE\tab The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab The socket has not been bound with }{\b\f7\uldb bind()}{\v\f7 WinSock_Bind}{\b\f7 . \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\b\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAECONNABORTED\tab The virtual circuit was aborted due to timeout or other failure. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7\revised WSAECONNRESET\tab The virtual circuit was reset by the remote side. \par }{\f7 \par }\pard\plain \fs20\lang1033 {\f7 }{\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb recv()}{\plain \v\f8\fs20\lang1033 WinSock_Recv}, {\uldb recvfrom()}{\plain \v\f8\fs20\lang1033 WinSock_RecvFrom}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb sendto()}{\plain \v\f8\fs20\lang1033 WinSock_SendTo}, {\uldb WSAStartup()}{\plain \v\f8\fs20\lang1033 WinSock_Startup}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SendTo}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 sendto()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0200}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 sendto()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 sendto() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Send data to a specific destination.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR sendto ( SOCKET {\plain \i\f7\fs20\lang1033 s}, const char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 flags} , const struct sockaddr FAR * {\plain \i\f7\fs20\lang1033 to}, int {\plain \i\f7\fs20\lang1033 tolen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A buffer containing the data to be transmitted. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 len}{\f7 \tab The length of the}{\f7 data in }{\i\f7 buf}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 flags}{\f7 \tab Specifies the way in which the call is made. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 to}{\f7 \tab A optional pointer to the address of the target socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 tolen}{\f7 \tab The size of the address in }{\i\f7 to}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 sendto}{\f7 () is used on datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the }{\i\f7 iMaxUdpDg}{\f7 element in the WSAData structure returned by }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 . If the data is too }{\f7 long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Note that the successful completion of a }{\b\f7 sendto()}{\f7 does not indicate that the data was successfully delivered. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\b\f7 sendto()}{\f7 is normally used on a SOCK_DGRAM socket to send a datagram to a specific peer socket identified by the }{\i\f7 to}{\f7 parameter. On a SOCK_STREAM socket, the }{\i\f7 to}{\f7 and }{\i\f7 tolen }{\f7 parameters are ignored; in this case the }{\b\f7 sendto()}{\f7 is equivalent to }{\b\f7\uldb send}{\f7\uldb ()}{\v\f8 WinSock_Send}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 To send a broadcas}{\f7 t (on a SOCK_DGRAM only), the address in the }{\i\f7 to}{\f7 parameter should be constructed using the special IP address INADDR_BROADCAST (defined in }{\b\f7 winsock.h}{\f7 ) together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation may occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If no buffer space is available within the transport system to hold the data to be transmitted, }{\b\f7 sendto}{\f7 () will bl}{\f7 ock unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The }{ \b\f7\uldb select}{\f7\uldb ()}{\v\f8 WinSock_Select}{\f7 call may be used to determine when it is possible to send more data. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\i\f7 Flags}{\f7 may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function}{\f7 are determined by the socket options and the }{ \i\f7 flags}{\f7 parameter. The latter is constructed by or-ing any of the following values: \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\b\f7\ulw Value\tab Meaning}{\f7\ul \par }\pard \s10\fi-1440\li2880 {\f7 MSG_DONTROUTE\line Specifies that the data should not be subject to routing. A Windows Sockets supplier may choose to ignore this flag; see also the discussion of the SO_DONTROUTE option in }{\f7\uldb Socket Options}{ \v\f7 WinsockProg_SocketOptions}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 MSG_OOB\tab Send out-of-band data (SOCK_STREAM only; see also }{\f7\uldb Out of Band Data}{\v\f7 WinsockSockets_OutOfBand}{\f7 ) \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occur}{\f7 s, }{\b\f7 sendto()}{\f7 returns the total number of characters sent. (Note that this may be less than the number indicated by }{\i\f7 len}{\f7 .) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEACCES\tab The requested address is a }{\f7 broadcast address, but the appropriate flag was not set. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEFAULT\tab The }{\i\f7 buf}{\f7 or }{\i\f7 to}{\f7 are not in a valid part of the user address space, or the to argument is too small (less than the sizeof a struct sockaddr). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETRESET\tab The connection must be reset because the Windows Sockets implementation dropped it. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab The Windows Sockets}{\f7 implementation reports a buffer deadlock. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOTCONN\tab The socket is not connected (SOCK_STREAM only). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEOPNOTSUPP\tab MSG_OOB was specified, but the socket is not of type SOCK_STREAM. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAESHUTDOWN\tab The socket has been shutdown; it is not possible to }{\b\f7 sendto()}{\f7 on a socket after }{\b\f7\uldb shutdown()}{\v\f8 WinSock_Shutdown}{\f7 has been invoked with how set to 1 or 2. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The socket is marked as non-blocking and the requested operation would block. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEMSGSIZE\tab Th}{\f7 e socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7\revised WSAECONNABORTED\tab The virtual circuit was aborted due to timeout or other failure. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7\revised WSAECONNRESET\tab The virtual circuit was reset by the remote side. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEADDRNOTAVAIL\tab The specified address is not available from the local machine. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEAFNOSUPPORT\tab Addresses in the specified family cannot be used with this socket. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEDESTADDRREQ\tab A destination address is required. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETUNR}{\f7 EACH\tab The network can't be reached from this host at this time. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb recv()}{\plain \v\f8\fs20\lang1033 WinSock_Recv}, {\uldb recvfrom()}{\plain \v\f8\fs20\lang1033 WinSock_RecvFrom}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send}, {\uldb WSAStartup()}{\plain \v\f8\fs20\lang1033 WinSock_Startup}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SetSockOpt}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 setsockopt()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0210}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 setsockopt()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 setsockopt() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Set a socket option.} \par \par \tab #include \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR setsockopt ( SOCKET {\plain \i\f7\fs20\lang1033 s}, int {\plain \i\f7\fs20\lang1033 level}, int {\plain \i\f7\fs20\lang1033 optname}, const char FAR * {\plain \i\f7\fs20\lang1033 optval}, int {\plain \i\f7\fs20\lang1033 optlen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 level}{\f7 \tab The level at which the option is defined;}{\f7 the only supported }{\i\f7 levels}{\f7 are SOL_SOCKET and IPPROTO_TCP. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optname}{\f7 \tab The socket option for which the value is to be set. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optval}{\f7 \tab A pointer to the buffer in which the value for the requested option is supplied. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 optlen}{\f7 \tab The size of the }{\i\f7 optval}{\f7 buffer. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 setsockopt()}{\f7 sets the current value for a socket option associated with a socket of any type, in any state. Although options may exist at multiple protocol levels, this specification only defines options that exist at the uppermost "socket'' leve}{\f7 l. Options affect socket operations, such as whether expedited data is received in the normal data stream, whether broadcast messages may be sent on the socket, etc. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 There are two types of socket options: Boolean options that enable or disable a feature or behavior, and options which require an integer value or structure. To enable a Boolean option, }{\i\f7 optval}{\f7 points to a nonzero integer. To disable the option }{\i\f7 optval}{\f7 points to an integer equal to zero. }{\i\f7 optlen}{\f7 should be equal to sizeof(int) for Boolean }{\f7 options. For other options, }{\i\f7 optval}{\f7 points to the an integer or structure that contains the desired value for the option, and }{\i\f7 optlen}{\f7 is the length of the integer or structure. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 SO_LINGER controls the action taken when unsent data is queued on a socket and a }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 is performed. See }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 for a description of the way in which the SO_LINGER settings affect the semantics of }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 . The application sets the desired behavior by cr}{\f7 eating a }{\i\f7 struct linger}{\f7 (pointed to by the }{\i\f7 optval}{\f7 argument) with the following elements: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 struct linger \{ \par \tab int\tab l_onoff; \par \tab int\tab l_linger; \par \} \par \pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 To enable SO_LINGER, the application should set }{\i\f7 l_onoff}{\f7 to a non-zero value, set }{\i\f7 l_linger}{\f7 to 0 or the desired timeout (in seconds), and call }{\b\f7 setsockopt()}{\f7 . To enable SO_DONTLINGER (i.e. disable SO_LINGER) }{\i\f7 l_onoff}{\f7 should be set to zero and }{\b\f7 setsockopt()}{\f7 should be called. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 By default, a socket may not be bound (see }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 ) to a local address which is alre}{\f7 ady in use. On occasions, however, it may be desirable to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same loca }{\f7 l address as long as the remote addresses are different. To inform the Windows Sockets implementation that a }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 on a socket should not be disallowed because the desired address is already in use by another socket, the application should set}{\f7 the SO_REUSEADDR socket option for the socket before issuing the }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 . Note that the option is interpreted only at the time of the }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 : it is therefore unnecessary (but harmless) to set the option on a socket which is not to be bound to an existing address, and setting or resetting the option after the }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 has no effect on this or any other socket.. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 An application may request that the Windows Sockets implementation enable the use of "keep-alive" packets on TC}{\f7 P connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets implementation need not support the use of keep-alives: if it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: }{ \i\f7 Requirements for Internet Hosts -- Communication Layers}{\f7 . If a connection is dropped as the result of "keep-alives" the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised The TCP_NO}{\f7\revised DELAY option disables the Nagle algorithm. The Nagle algorithm is used to reduce the number of small packets sent by a host by buffering unacknowledged send data until a full-size packet can be sent. However, for some applications this algorithm can imp }{\f7\revised ede performance, and TCP_NODELAY may be used to turn it off. Application writers should not set TCP_NODELAY unless the impact of doing so is well-understood and desired, since setting TCP_NODELAY can have a significant negative impact of network performa }{\f7\revised nc}{\f7\revised e. TCP_NODELAY is the only supported socket option which uses }{\i\f7\revised level}{\f7\revised IPPROTO_TCP; all other options use level SOL_SOCKET. \par }\pard \s12\li1440 \par \pard \s12\li1440 {\f7\revised Windows Sockets suppliers are encouraged (but not required) to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this specific }{\f7\revised ation.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The following options are supported for }{\b\f7 setsockopt()}{\f7 . The }{\f7\ul Type}{\f7 identifies the type of data addressed by }{\i\f7 optval}{\f7 . \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\b\f7\ulw Value\tab }{\b\f7\ulw Type\tab Meaning \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_BROADCAST\tab BOOL\tab Allow transmission of broadcast messages on the socket. \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_DEBUG\tab BOOL\tab Record debugging information. \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_DONTLINGER\tab BOOL\tab Don't block close waiting for unsent data to be sent. Setting this option is equivalent to setting SO_LINGER with }{\i\f7 l_onoff}{\f7 set to zero. \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_DONTROUTE\tab BOOL\tab Don't route: send directly to interface. \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_KEEPALIVE\tab BOOL\tab Send keepalives \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_LINGER\tab struct linger FAR *\tab Linger on close if unsent data is present \par }{\f7 SO_OOBINLINE\tab BOOL\tab Receive out-of-band data in the no}{\f7 rmal data stream. \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_RCVBUF\tab int\tab Specify buffer size for receives \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_REUSEADDR\tab BOOL\tab Allow the socket to be bound to an address which is already in use. (See }{\b\f7\uldb bind()}{\v\f8 WinSock_Bind}{\f7 .) \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_SNDBUF\tab int\tab Specify buffer size for sends \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 TCP_NODELAY\tab BOOL\tab Disables the Nagle algorithm for send coalascing. \par }\pard\plain \li2160 \fs20\lang1033 {\f7 \par }\pard \li2160 {\f7 BSD options not supported for }{\b\f7 setsockopt()}{\f7 are: \par }\pard \li2160 {\f7 \par }\pard\plain \s10\fi-3960\li5400\tx1440\tx3600\tx5400 \fs20\lang1033 {\b\f7\ulw Value\tab Type\tab Meaning \par }\pard \s10\fi-3960\li5400\tx1440\tx3600\tx5400 {\f7 SO_ACCEPTCON\tab BOOL\tab Socket is listening \par }{\f7 SO_ERROR\tab int\tab Get error status and clear \par }{\f7 SO_RCVLOWAT\tab int\tab Receive low water mark \par }{\f7 SO_RCVTIMEO\tab int\tab Receiv}{\f7 e timeout \par }{\f7 SO_SNDLOWAT\tab int\tab Send low water mark \par }{\f7 SO_SNDTIMEO\tab int\tab Send timeout \par }{\f7 SO_TYPE\tab int\tab Type of the socket \par }{\f7 IP_OPTIONS\tab \tab Set options field in IP header. \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard \s7\fi-1440\li1440 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 setsockopt()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementatio}{\f7 n has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEFAULT\tab }{\i\f7 optval}{\f7 is not in a valid part of the process address space. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEINVAL\tab }{\i\f7 level}{\f7 is not valid, or the information in optval is not valid. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETRESET\tab Connection has timed out when SO_KEEPALIVE is set. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOPROTOOPT\tab The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_DONTLINGER, SO_KEEPALIVE, S}{\f7 O_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOTCONN\tab Connection has been reset when SO_KEEPALIVE is set. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb getsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_GetSockOpt}, {\uldb ioctlsocket()}{\plain \v\f8\fs20\lang1033 WinSock_IOCTLSocket}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}, {\uldb WSAAsyncSelect()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncSelect}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_ShutDown}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 shutdown()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0220}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 shutdown()}}} Windows Sockets - Socket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 shutdown() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Disable sends and/or receives on a socket.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR shutdown ( SOCKET {\plain \i\f7\fs20\lang1033 s}, int {\plain \i\f7\fs20\lang1033 how}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying a socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 how}{\f7 \tab A flag that describes what types of operation will no longer be allowed. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 shutdown}{\f7 () is used on all types of sockets to disable reception, transmission, or both. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If }{\i\f7 how}{\f7 is 0, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incom }{\f7 i}{\f7 ng datagrams are accepted and queued. In no case will an ICMP error packet be generated. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 If }{\i\f7 how}{\f7 is 1, subsequent sends are disallowed. For TCP sockets, a FIN will be sent. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Setting }{\i\f7 how}{\f7 to 2 disables both sends and receives as described above. \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Note that }{\b\f7 shutdown()}{\f7 does not close the socket, and resources attached to the socket will not be freed until }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 is invoked. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab }{\b\f7 shutdown()}{\f7 does not block regardless of the SO_LINGER setting on the socket. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 An applicat}{\f7 ion should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets implementation is not required to support the use of }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect }{\f7 on such a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 shutdown()}{\f7 returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using th}{\f7 is API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEINVAL\tab how is not valid. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOTCONN\tab The socket is not connected (SOCK_STREAM only). \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is not a socket. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb connect()}{\plain \v\f8\fs20\lang1033 WinSock_Connect}, {\uldb socket()}{\plain \v\f8\fs20\lang1033 WinSock_Socket}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Socket}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 socket()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockSR:0230}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 socket()}}} Windows Sockets - S ocket Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 socket() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Create a socket.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab SOCKET PASCAL FAR socket ( int {\plain \i\f7\fs20\lang1033 af}, int {\plain \i\f7\fs20\lang1033 type}, int {\plain \i\f7\fs20\lang1033 protocol}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 af}{\f7 \tab An address format specification. The only format currently supported is PF_INET, which is the ARPA Internet address format. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 type}{\f7 \tab A type specification for the new socket. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 protocol}{\f7 \tab A particular protocol to be used with the socket, or 0 if the caller does not wish to specify a protocol. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 socket()}{\f7 allocates a socket descriptor of the specifie}{\f7 d address family, data type and protocol, as well as related resources. If a protocol is not specified (i.e. equal to 0), the default for the specified connection mode is used. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Only a single protocol exists to support a particular socket type using a given address format. However, the address family may be given as AF_UNSPEC (unspecified), in which case the }{\i\f7 protocol}{\f7 parameter must be specified. The protocol number to use is particular to the "communication domain'' in which communication is to take pl}{\f7 ace. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The following }{\i\f7 type}{\f7 specifications are supported: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s16\fi-2160\li4320 \fs20\ul\lang1033 {\b\f7\ulw Type\tab Explanation \par }\pard\plain \s17\fi-2160\li4320 \fs20\lang1033 {\f7 SOCK_STREAM\tab Provides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family. \par }\pard \s17\fi-2160\li4320 {\f7 \par }\pard \s17\fi-2160\li4320 {\f7 SOCK_DGRAM\tab Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses UDP for the Internet address family. \par }\pard \s17\fi-2160\li4320 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 Sockets of type SOCK_STREAM are full-duplex byte streams. A stream socket must be in a c}{\f7 onnected state before any data may be sent or received on it. A connection to another socket is created with a }{\b\f7\uldb connect}{ \f7\uldb ()}{\v\f8 WinSock_Connect}{\f7 call. Once connected, data may be transferred using }{\b\f7\uldb send}{\f7\uldb ()}{\v\f8 WinSock_Send}{\f7 and }{\b\f7\uldb recv}{\f7\uldb ()}{\v\f8 WinSock_Recv}{\f7 calls. When a session has been completed, a }{\b\f7\uldb closesocket}{\f7\uldb ()}{\v\f8 WinSock_CloseSocket}{\f7 must be performed. Out-of-band data may also be transmitted as described in }{\b\f7\uldb send}{\f7\uldb ()}{\v\f8 WinSock_Send}{\f7 and received as described in }{\b\f7\uldb recv}{\f7\uldb ()}{\v\f8 WinSock_Recv}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The communications protocols used to implement a SOCK_}{\f7 STREAM ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the er }{\f7 ror code set to WSAETIMEDOUT. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 SOCK_DGRAM sockets allow sending and receiving of datagrams to and from arbitrary peers using }{\b\f7\uldb sendto()}{\v\f8 WinSock_SendTo}{\f7 and }{\b\f7\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\f7 . If such a socket is }{ \b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 ed to a specific peer, datagra}{\f7 ms may be send to that peer }{\b\f7\uldb send}{\f7\uldb ()}{\v\f8 WinSock_Send}{\f7 and may be received from (only) this peer using }{\b\f7\uldb recv}{\f7\uldb ()}{ \v\f8 WinSock_Recv}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 socket()}{\f7 returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation}{\f7 has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEAFNOSUPPORT\tab The specified address family is not supported.. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEMFILE\tab No more file descriptors are available. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab No buffer space is available. The socket cannot be created. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAEPROTONOSUPPORT\tab The specified protocol is not supported. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEPROTOTYPE\tab The specified protocol is the wrong type for this socket. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAESOCKTNOSUPPORT\tab The specified socket type is not }{\f7 supported in this address family. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb accept()}{\plain \v\f8\fs20\lang1033 WinSock_Accept}, {\uldb bind()}{\plain \v\f8\fs20\lang1033 WinSock_Bind}, {\uldb connect()}{\plain \v\f8\fs20\lang1033 WinSock_Connect}, { \uldb getsockname()}{\plain \v\f8\fs20\lang1033 WinSock_GetSockName}, {\uldb getsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_GetSockOpt}, {\uldb setsockopt()}{\plain \v\f8\fs20\lang1033 WinSock_SetSockOpt}, {\uldb listen()}{\plain \v\f8\fs20\lang1033 WinSock_Listen}, {\uldb recv()}{\plain \v\f8\fs20\lang1033 WinSock_Recv}, {\uldb recvfrom()}{\plain \v\f8\fs20\lang1033 WinSock_RecvFrom}, {\uldb select()}{\plain \v\f8\fs20\lang1033 WinSock_Select}, {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send} , {\uldb sendto()}{\plain \v\f8\fs20\lang1033 WinSock_SendTo}, {\uldb shutdown()}{\plain \v\f8\fs20\lang1033 WinSock_Shutdown}, {\uldb ioctlsocket()}{\plain \v\f8\fs20\lang1033 WinSock_IOCTLSocket}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockRef_DatabaseRoutines}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Database Routines}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockRef:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Database Functions}}} Socket Library Reference \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Database Routines \par \pard\plain \fs20\lang1033 {\b\f8\uldb gethostbyaddr()}{\v\f8 WinSock_GetHostByAddr}{\b\f7 \par }{\b\f8\uldb get}{\b\f8\uldb hostbyname()}{\v\f8 WinSock_GetHostByName}{\b\f7 \par }{\b\f8\uldb gethostname()}{\v\f8 Winsock_GetHostName}{\b\f7 \par }{\b\f8\uldb getprotobyname()}{\v\f8 WinSock_GetProtoByName}{\b\f7 \par }{\b\f8\uldb getprotobynumber()}{\v\f8 WinSock_GetProtoByNumber}{\b\f7 \par }{\b\f8\uldb getservbyname()}{\v\f8 WinSock_GetServByName}{\b\f7 \par }{\b\f8\uldb getservbyport()}{\v\f8 WinSock_GetServByPort}{\f8 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetHostByAddr}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $ }{\f7 gethostbyaddr()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 gethostbyaddr()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 gethostbyaddr() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get host information corresponding to an address.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct hostent FAR * PASCAL FAR gethostbyaddr ( const char FAR * {\plain \i\f7\fs20\lang1033 addr}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 type}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 addr}{\f7 \tab A pointer to an address in network byte order.}{\f7 \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 len}{\f7 \tab The length of the address, which must be 4 for PF_INET addresses. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 type}{\f7 \tab The type of the address, which must be PF_INET. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 gethostbyaddr}{\f7 () returns a pointer to the following structure which contains the name(s) and address which correspond to the given address. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 struct hostent \{ \par \tab char FAR *\tab h_name; \par \tab char FAR * FAR *\tab h_aliases; \par \tab short\tab h_addrtype; \par \tab short\tab h_length; \par \tab char FAR * FAR *\tab h_addr_list; \par \}; \par \pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s19\fi-2160\li3600\tx3600 \fs20\lang1033 {\f7 The members of this structure are: \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\b\f7\ulw Element\tab Usage}{\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 h_name\tab Official name of the host (PC). \par }{\f7 h_alia}{\f7 ses\tab A NULL-terminated array of alternate names. \par }\pard \s10\fi-1440\li2880 {\f7 h_addrtype\tab The type of address being returned; for Windows Sockets this is always PF_INET. \par }{\f7 h_length\tab The length, in bytes, of each address; for PF_INET, this is always 4. \par }{\f7 h_addr_list\tab A NULL-terminated list of addresses for the host. Addresses are returned in network byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The macro h_addr is defined to be h_addr_list[0] for compatibility with older software. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets i}{\f7 mplementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before i }{\f7 ssuing any other Windows Sockets API calls. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 gethostbyaddr()}{\f7 returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLa}{\b\f7\uldb stError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A block}{\f7 ing Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGetHostByAddr()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetHostByAddr}, {\uldb gethostbyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetHostByName}, \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetHostByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $ }{\f7 gethostbyname()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 gethostbyname()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 gethostbyname() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get host information corresponding to a hostname.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct hostent FAR * PASCAL FAR gethostbyname ( const char FAR * {\plain \i\f7\fs20\lang1033 name}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 name}{\f7 \tab A pointer to the name of the host. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 gethostb}{\b\f7 yname}{\f7 () returns a pointer to a hostent structure as described under }{\b\f7\uldb gethostbyaddr}{\f7\uldb ()}{\v\f8 WinSock_GetHostByAddr}{\f7 . The contents of this structure correspond to the hostname }{\i\f7 name}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is a }{\f7 llocated per thread, and so the application should copy any information which it nee}{\f7 ds before issuing any other Windows Sockets API calls. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised A }{\b\f7\revised gethostbyname() }{\f7\revised implementation must not resolve IP address strings passed to it. }{\f7 Such a request should be treated exactly as if an unknown host name were passed. }{\f7\revised An application with an IP address string to resolve should use }{\b\f7\uldb\revised inet_addr()}{\b\v\f7 Winsock_InetAddr}{\b\f7\revised }{\f7\revised to convert the string to an IP address, then }{\b\f7\uldb\revised gethostbyaddr()}{\v\f7 Winsock_gethostbyaddr}{\b\f7\revised }{\f7\revised to obtain the hostent structure. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 gethostbyname()}{\f7 returns a pointer to the host}{\f7 ent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab No}{\f7 n recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGetHostByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetHostByName}, {\uldb gethostbyaddr()}{\plain \v\f8\fs20\lang1033 WinSock_GetHostByAddr} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetHostName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 gethostname()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0025}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 gethostname()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised gethostname() \par }\pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 {\revised Description\tab }{\plain \f7\fs20\revised\lang1033 Return the standard host name for the local machine.}{\revised \par } \par {\revised \tab #include \par }\pard \s3\fi-1080\li1080 {\plain \f7\fs20\lang1033 \par }\pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 {\revised \tab int PASCAL FAR gethostname ( char FAR * }{\plain \i\f7\fs20\revised\lang1033 name}{\revised , int }{\plain \i\f7\fs20\revised\lang1033 namelen}{\revised ); \par } \par \pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7\revised name\tab }{\f7\revised A pointer to a buffer that will receive the host name. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7\revised namelen}{\f7\revised \tab The length of the buffer. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7\revised Remarks}{\f7\revised \tab This routine returns the name of the local host into the buffer specified by the }{\i\f7\revised name }{\f7\revised parameter. The host name is returned as a null-terminated string. The form of the host name is dependent on the Windows Sockets implementation--it may be a simple host name, or it may be a fully qualified domain name. However, it is guaranteed that t}{ \f7\revised he name returned will be successfully parsed by }{\b\f7\revised gethostbyname() }{\f7\revised and }{\b\f7\revised WSAAsyncGetHostByName().}{\f7\revised \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7\revised Return Value}{\f7\revised \tab If no error occurs, }{\b\f7\revised gethostname() }{\f7\revised reutrns 0, otherwise it returns SOCKET_ERROR and a specific error code may be retrieved by calling }{\b\f7\uldb\revised WSAGetLastError()}{\v\f7 WinSock_GetLastError}{\f7\revised . \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7\revised Error Codes}{\f7\revised \tab WSAEFAULT\tab The }{\i\f7\revised namelen }{\f7\revised parameter is too small \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7 \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7\revised \tab WSANOTINITIALISED\tab A successful }{\b\f7\revised WSAStartup() }{\f7\revised must occur before using this API. \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7 \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7\revised \tab WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsyste}{\f7\revised m has failed. \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7 \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7\revised \tab WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 {\revised See Also\tab }{\uldb\revised gethostbyname()}{\plain \v\f8\fs20\lang1033 Winsock_gethostbyname}{\revised , }{\uldb\revised WSAAsyncGetHostByName()}{\plain \v\f8\fs20\lang1033 Winsock_AsyncGetHostByName}{\revised . \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetProtoByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 getprotobyname()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getprotobyname()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getprotobyname() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get protocol information corresponding to a protocol name.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct protoent FAR * PASCAL FAR getprotobyname ( const char FAR * {\plain \i\f7\fs20\lang1033 name}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 name}{\f7 \tab A pointer to a protocol name. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getprotobyname}{\f7 () returns a pointer to the following struct}{\f7 ure which contains the name(s) and protocol number which correspond to the given protocol }{\i\f7 name}{ \f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 struct protoent \{ \par \tab char FAR *\tab p_name; \par \tab char FAR * FAR *\tab p_aliases; \par \tab short\tab p_proto; \par \}; \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s19\fi-2160\li3600\tx3600 \fs20\lang1033 {\f7 The members of this structure are: \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\b\f7\ulw Element\tab Usage}{\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 p_name\tab Official name of the protocol. \par }{\f7 p_aliases\tab A NULL-terminated array of alternate names. \par }{\f7 p_proto\tab The protocol number, in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never at}{\f7 tempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getprotobyname()}{\f7 returns a pointer to the protoent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab }{\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGe}{\uldb tProtoByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetProtoByName}, {\uldb getprotobynumber()}{\plain \v\f8\fs20\lang1033 WinSock_GetProtoByNumber}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetProtoByNumber}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 getprotobynumber()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSo}{\f7 ckDB:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getprotobynumber()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getprotobynumber() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get protocol information corresponding to a protocol number.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct protoent FAR * PASCAL FAR getprotobynumber ( int {\plain \i\f7\fs20\lang1033 number}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 number}{\f7 \tab A protocol number, in host byte order. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function returns a pointer to a protoent structure as described above in }{\b\f7 getprotobyname()}{\f7 . The contents of the structure correspond to the given p}{\f7 rotocol number. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is a }{\f7 llocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getprotobynumber()}{\f7 returns a pointer to the protoent structure }{\f7 described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking W}{\f7 indows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGetProtoByNumber()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetProtoByNumber}, {\uldb getprotobyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetProtoByName} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetServByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $ }{\f7 getservbyname()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getservbyname()}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getservbyname() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get service information corresponding to a service name and protocol.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct servent FAR * PASCAL FAR getservbyname ( const char FAR * {\plain \i\f7\fs20\lang1033 name}, const char FAR * {\plain \i\f7\fs20\lang1033 proto}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 name}{\f7 \tab A poi}{\f7 nter to a service name. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 proto}{\f7 \tab An optional pointer to a protocol name. If this is NULL, }{\b\f7 getservbyname()}{\f7 returns the first service entry for which the }{\i\f7 name}{\f7 matches the s_name or one of the s_aliases. Otherwise }{\b\f7 getservbyname()}{\f7 matches both the }{\i\f7 name }{\f7 and the }{\i\f7 proto}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getservbyname()}{\f7 returns a pointer to the following structure which contains the name(s) and service number which correspond to the given service }{\i\f7 name}{\f7 . \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 struct servent \{ \par \tab char FAR *\tab s_name; \par \tab char FAR * FAR *\tab s_aliases; \par \tab short\tab s_port; \par \tab char FAR *\tab s_proto; \par \}; \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s19\fi-2160\li3600\tx3600 \fs20\lang1033 {\f7 The members of this structure are: \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\b\f7\ulw Element\tab Usage \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 s_name\tab Official name of the service. \par }{\f7 s_aliases\tab A NULL-terminated array of alternate names. \par }\pard \s10\fi-1440\li2880 {\f7 s_port\tab The port number at which the service may be contacted. Port numbers are returned in network byte order. \par }\pard \s10\fi-1440\li2880 {\f7 s_proto\tab The name of the protocol to use when contacting the service. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure o}{\f7 r to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getservbyname()}{\f7 returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7 WSA}{\b\f7 Startup()}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard \fi-1440\li1440\tx1440 {\b\f7 See Also}{\f7 \tab }{\b\f7\uldb WSAAsyncGetServByName()}{\v\f7 WinSock_AsyncGetServByName}{\f7 , }{\b\f7\uldb getservb}{\b\f7\uldb yport()}{\v\f7 WinSock_GetServByPort}{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetServByPort}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 getservbyport()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockDB:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 getservbyport}}} Database Routines \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 getservbyport() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get service information corresponding to a port and protocol.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab struct servent FAR * PASCAL FAR getservbyport ( int {\plain \i\f7\fs20\lang1033 port}, const char FAR * {\plain \i\f7\fs20\lang1033 proto}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 port}{\f7 \tab The port for a service, in network byte order. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 proto}{\f7 \tab An optional pointer to a protocol name. If this is NULL, }{\b\f7 getservbyport()}{\f7 returns the first service entry for which the }{\i\f7 port }{\f7 matches the s_port. Otherwise }{\b\f7 getservbyport()}{\f7 matches both the }{\i\f7 port}{\f7 and the }{\i\f7 proto}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab }{\b\f7 getservbyport()}{\f7 returns a pointer a servent structure as described above for }{\b\f7\uldb getservbyname()}{\v\f8 WinSock_GetServByName}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is a }{\f7 llocated per thread, and so the application should copy any information which it needs before issuing any other}{\f7 Windows Sockets API calls. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab If no error occurs, }{\b\f7 getservbyport()}{\f7 returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 .}{\f7 \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverab}{\f7 le errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINTR\tab The (blocking) call was canceled via }{\b\f7 WSACancelBlockingCall()}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGetServByPort()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetServByPort}, {\uldb getservbyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetServByName} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockRef_WindowsExtensions}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Microsoft Windows-specific Extensions}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockRef:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Windows Extensions}}} Socket Library Reference \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Microsoft Windows-specific Extensions \par \pard\plain \fs20\lang1033 {\b\f8\uldb WSAAsyncGetHostByAddr()}{\v\f8 WinSock_AsyncGetHostByAddr}{\b\f7 \par }{\b\f8\uldb WSAAsyncGetHostByName()}{\v\f8 WinSock_AsyncGetHostByName}{\b\f7 \par }{\b\f8\uldb WSAAsyncGetProtoByName()}{\v\f8 WinSock_AsyncGetProtoByName}{\b\f7 \par }{\b\f8\uldb WSAAsyncGetProtoByNumber()}{\v\f8 WinSock_AsyncGetProtoByNumber}{\b\f7 \par }{\b\f8\uldb WSAAsyncGetServByName()}{\v\f8 WinSock_AsyncGetServByName}{\b\f7 \par }{\b\f8\uldb WSAAsyncGetServByPort()}{\v\f8 WinSock_AsyncGetServByPort}{\b\f7 \par }{\b\f8\uldb WSAAsyncSelect()}{\v\f8 WinSock_AsyncSelect}{\b\f7 \par }{\b\f8\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\b\f7 \par }{\b\f8\uldb WSACancelBlockingCall()}{\v\f8 WinSock_CancelBlockingCall}{\b\f7 \par }{\b\f8\uldb WSACleanup()}{\v\f8 WinSock_Cleanup}{\b\f7 \par }{\b\f8\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\b\f7 \par }{\b\f8\uldb WSAIsBlocking()}{\v\f8 WinSock_IsBlocking}{\b\f7 \par }{\b\f8\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\b\f7 \par }{\b\f8\uldb WSASetLastE}{\b\f8\uldb rror()}{\v\f8 WinSock_SetLastError}{\b\f7 \par }{\b\f8\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\b\f7 \par }{\b\f8\uldb WSAUnhookBlockingHook()}{\v\f8 WinSock_UnhookBlockingHook}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetHostByAddr}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetHostByAddr()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncGetHostByAddr()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetHostByAddr() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get host information corresponding to an address - asynchronous version.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetHostByAddr ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, const char FAR * {\plain \i\f7\fs20\lang1033 addr}, int {\plain \i\f7\fs20\lang1033 len}, int {\plain \i\f7\fs20\lang1033 type}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should receive a message whe}{\f7 n the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 addr}{\f7 \tab A}{\b\f7 }{\f7 pointer to the network address for the host. Host addresses are stored in network byte order. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 len}{\f7 \tab The length of the address, which must be 4 for PF_INET. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 type}{\f7 \tab The type of the address, which must be PF_INET. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is}{\f7 used by the Windows Sockets implementation to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is an asynchronous version of }{\b\f7\uldb gethostbyaddr()}{\v\f8 WinSock_GetHostByAddr}{\f7 , and is used to retrieve host name and address information corresponding to a network address. The Windows Sockets implementation initia}{\f7 tes the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When the asynchronous operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchronous task handle as returned by the original function call.}{\f7 The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buff }{\f7 er address should be cast to a hostent structure pointer and accessed as appropriate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates tha}{\f7 t the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{\i\f7 lParam}{\f7 contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the }{\b\f7 WSAAsyncGetHostByAddr() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer len}{\f7 gth should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the application. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does }{\f7\ul not}{\f7 imply success or failure of the }{\f7 operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetHostByAddr()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 . It can also be used to match up asynchronous operations and completion messages, by examining the }{\i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetHo}{\b\f7 stByAddr()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{ \v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, } {\f7 the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Wi}{\b\f7 ndows Sockets}{\f7 \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may be set when an application window receives a message. As described ab}{\f7 ove, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insufficient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The f}{\f7 ollowing errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operation cannot be scheduled at this time due to resource or other constraints}{\f7 within the Windows Sockets implementation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb gethostbyaddr()}{\plain \v\f8\fs20\lang1033 WinSock_GetHostByAddr}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetHostByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetHostByName()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncGetHostByName()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetHostByName() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description{\plain \f7\fs20\lang1033 \tab Get host information corresponding to a hostname - asynchronous version.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetHostByName ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, const char FAR * {\plain \i\f7\fs20\lang1033 name}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should recei}{\f7 ve a message when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab A}{\b\f7 }{\f7 pointer to the name of the host. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a hostent structure but} {\f7 any and all of the data which is referenced by members of the hostent structu}{\f7 re. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is an asynchronous version of }{\b\f7 gethostbyname()}{\f7 , and is used to retrieve host name and address information corresponding to a hostname. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the }{\f7 results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When the asynchronous operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operati}{\f7 on. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate }{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{ \i\f7 lParam}{\f7 contain the size of buffer req}{\f7 uired to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the }{\b\f7 WSAAsyncGetHostByName() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer length should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define }{\f7 WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the application. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does }{\f7\ul not}{\f7 imply success or failure of the operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetHostByName()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This va}{\f7 lue can be used in two ways. It can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 . It can also be used to match up asynchronous operations and completion messages, by examining the }{ \i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetHostByName()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the }{\f7 Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least M }{\f7 AXGETHOSTSTRUCT bytes (as defined in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implemen}{\plain \f7\fs20 tation}{\f7 to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails,}{\f7 the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may be set when an application window receives a message. As described above, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has }{\f7 failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insufficient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 m}{\f7 ust occur before using this API. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb gethostbyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetHostByName}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetProtoByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetProtoByName()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncGetProtoByName()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetProtoByName() \par \pard\plain \s3\fi-1440\li1440 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get protocol information corresponding to a protocol name - asynchronous version.} \par \pard \s3\fi-1080\li1080 \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetProtoByName ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, const char FAR * {\plain \i\f7\fs20\lang1033 name}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should receive a message when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab A}{\b\f7 }{\f7 pointer to the protocol name to be resolv}{\f7 ed. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure } {\f7 but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is an asynchronous ver}{\f7 sion of }{\b\f7\uldb getprotobyname()}{\v\f8 WinSock_GetProtoByName}{\f7 , and is used to retrieve the protocol name and number corresponding to a protocol name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When the asynchronous}{\f7 operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of thi}{\f7 s structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{ \i\f7 lParam}{\f7 contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the }{\b\f7 WSAAsyncG}{\b\f7 etProtoByName() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer length should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the app}{\f7 lication. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does }{\f7\ul not}{\f7 imply success or failure of the operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetProtoByName()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 . It can als}{\f7 o be used to match up asynchronous operations and completion messages, by examining the }{\i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetProtoByName()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the s}{\f7 ame protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use th}{\f7 e WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may be set when an application window receives a message. As described above, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insufficient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGA}{\f7 IN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed.}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb getprotobyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetProtoByName}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetProtoByNumber}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetProtoByNumber()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{ \f7 WSAAsyncGetProtoByNumber()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetProtoByNumber() \par \pard\plain \s3\fi-1440\li1440 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get protocol information corresponding to a protocol number - asynchronous version. \par }\pard \s3\fi-1080\li1080 \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetProtoByNumber ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, int {\plain \i\f7\fs20\lang1033 number}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should receive a message when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 number}{\f7 \tab The protocol number to be resolved, in host byte order. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent}{\f7 structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you su }{\f7 pply a buffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is an asynchronous version of }{\b\f7\uldb getprotobynumber()}{\v\f8 WinSock_GetProtoByNumber}{\f7 , and is used to retrieve the protocol name and number corresponding to a pr}{\f7 otocol number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When the asynchronous operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchrono}{\f7 us task handle as returned by the original function call. The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buf }{\f7 fer address should be cast to a protoent structure pointer and accessed as appropriate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{ \i\f7 lParam}{\f7 contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the }{\b\f7 WSAAsyncGetProtoByNumber() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than}{\f7 the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer length should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the application. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully ini}{\f7 tiated. Note that it does }{\f7\ul not}{\f7 imply success or failure of the operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetProtoByNumber()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 . It can also be used to match up asynchronous operations and completion messages, by examining the }{\i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 I}{\f7 f the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetProtoByNumber()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()} {\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above} {\f7 , the application should provide a buffer of at l}{\f7 east MAXGETHOSTSTRUCT bytes (as defined in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may}{\f7 be set when an application window receives a message. As described above, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insufficient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTI}{\f7 MP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operatio}{\f7 n cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation. \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb getprotobynumber()}{\plain \v\f8\fs20\lang1033 WinSock_GetProtoByNumber}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetServByName}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetServByName()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncGetServByName()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetServByName() \par \pard\plain \s3\fi-1440\li1440 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get service information corresponding to a service name and port - asynchronous version. \par }\pard \s3\fi-1080\li1080 \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetServByName ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, const char FAR * {\plain \i\f7\fs20\lang1033 name} , const char FAR * {\plain \i\f7\fs20\lang1033 proto}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should receive a message when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 name}{\f7 \tab A pointer to a service name. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 proto}{\f7 \tab A pointer to a protocol name. This may be NULL, in which case }{\b\f7 WSAAsyncGetServByName()}{\f7 will search for the first service entry for which }{\i\f7 s_name}{\f7 or one of the }{\i\f7 s_aliases}{ \f7 matches the given }{\i\f7 name}{\f7 . Otherwise }{\b\f7 WSAAsyncGetServByN}{\b\f7 ame()}{\f7 matches both }{\i\f7 name}{\f7 and }{\i\f7 proto}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but} {\f7 any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This func}{\f7 tion is an asynchronous version of }{\b\f7\uldb getservbyname()}{\v\f8 WinSock_GetServByName}{\f7 , and is used to retrieve service information corresponding to a service name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When t}{\f7 he asynchronous operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the e}{\f7 lements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{ \i\f7 lParam}{\f7 contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue }{\f7 the }{\b\f7 WSAAsyncGetServByName() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer length should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code }{\f7 for the application. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does }{\b\f7 not}{\f7 imply success or failure of the operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetServByName()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest}{\f7 . }{\f7 It can also be used to match up asynchronous operations and completion messages, by examining the }{\i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetHostByAddr()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f7 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440\tx1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members }{\f7 of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should}{\f7 use the WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may be set when an application window receives a message. As described above, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insufficient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSA}{\f7 TRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has }{\f7 failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation. \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 \par \pard \s9\fi-1440\li1440\tx1440 See Also\tab {\uldb getservbyname()}{\plain \v\f8\fs20\lang1033 WinSock_GetServByName}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncGetServByPort}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAAsyncGetServByPort()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncGetServByPort()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncGetServByPort() \par \pard\plain \s3\fi-1440\li1440 \b\f7\fs20\lang1033 Description{\plain \f7\fs20\lang1033 \tab Get service information corresponding to a port and protocol - asynchronous version. \par }\pard \s3\fi-1080\li1080 \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab HANDLE PASCAL FAR WSAAsyncGetServByPort ( HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, int {\plain \i\f7\fs20\lang1033 port}, const char FAR * {\plain \i\f7\fs20\lang1033 proto}, char FAR * {\plain \i\f7\fs20\lang1033 buf}, int {\plain \i\f7\fs20\lang1033 buflen}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hWnd}{\f7 \tab The handle of the window which should receive a message when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when the asynchronous request completes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 port}{\f7 \tab The port for the service, in network byte order. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 proto}{\f7 \tab A pointer to a protocol name. This may be NULL, in which case }{\b\f7 WSAAsyncGetServByPort()}{\f7 will search f}{\f7 or the first service entry for which }{\i\f7 s_port}{\f7 match the given }{\i\f7 port}{\f7 . Otherwise }{\b\f7 WSAAsyncGetServByPort()}{\f7 matches both }{\i\f7 port}{\f7 and }{\i\f7 proto}{\f7 . \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buf}{\f7 \tab A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but} {\f7 any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a bu}{\f7 ffer of MAXGETHOSTSTRUCT bytes. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 buflen}{\f7 \tab The size of data area }{\i\f7 buf}{\f7 above. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is an asynchronous version of }{\b\f7\uldb getservbyport()}{\v\f8 WinSock_GetServByPort}{\f7 , and is used to retrieve service information corresponding to a port number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an }{\b\f7 asynchronous task handle}{\f7 which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into }{\f7 the buffer provided by the caller and a message is sent to the application's window. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When the asynchronous operation is complete the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of }{\i\f7 lParam}{\f7 contain any error code. The error code may be any error as defined in }{\b\f7 winsock.h}{\f7 . An error code of zero indicates successful completion of the asynchronous operation. On successful completion, th}{\f7 e buffer supplied to the original function call contains a servent structure. To access the elements of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by }{\i\f7 buflen}{\f7 in the original call was too small to contain all the resultant information. In this case, the low 16 bits of }{ \i\f7 lParam}{\f7 contain the size of buffer required to supply ALL the requisite}{\f7 information. If the application decides that the partial data is inadequate, it may reissue the }{\b\f7 WSAAsyncGetServByPort() }{\f7 function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of }{\i\f7 lParam}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error code and buffer length should be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETASYNCBUFLEN(lParam) }{\f7 LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the application. \par }\pard\plain \fs20\lang1033 {\f7 \par }{\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does }{\b\f7 not}{\f7 imply success or failure of the operation itself. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s14\li1440 \fs20\lang1033 {\f7 If the operation was successfully initiated, }{\b\f7 WSAAsyncGetServByPort()}{\f7 returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It }{\f7 can be used to cancel the operation using }{\b\f7\uldb WSACancelAsyncRequest()}{\v\f8 WinSock_CancelAsyncRequest} {\f7 . It can also be used to match up asynchronous operations and completion messages, by examining the }{\i\f7 wParam}{\f7 message argument. \par }\pard \s14\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 If the asynchronous operation could not be initiated, }{\b\f7 WSAAsyncGetServByPort()}{\f7 returns a zero value, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab The buffer supplied to this function is used by the Windows Sockets implementation to}{\f7 construct a servent structure together with the contents of data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined }{\f7 in }{\b\f7 winsock.h}{\f7 ). \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementati}{\f7 on }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab The following error codes may be set when an application window receives a message. As described above, they may be extracted from the }{\i\f7 lParam}{\f7 in the reply message using the WSAGETASYNCERROR macro. \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOBUFS\tab No/insuffic}{\f7 ient buffer space is available \par }{\f7 \par }{\f7 WSAHOST_NOT_FOUND\tab Authoritative Answer Host not found. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSATRY_AGAIN\tab Non-Authoritative Host not found, or SERVERFAIL. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANO_RECOVERY\tab Non recoverable errors, FORMERR, REFUSED, NOTIMP. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSANO_DATA\tab Valid name, no data record of requested type. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API.}{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEWOULDBLOCK\tab The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation. \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb getservbyport()}{\plain \v\f8\fs20\lang1033 WinSock_GetServByPort}, {\uldb WSACancelAsyncRequest()}{\plain \v\f8\fs20\lang1033 WinSock_CancelAsyncRequest} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_AsyncSelect}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 WSAAsyncSelect()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAAsyncSelect()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAAsyncSelect() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Re}{\plain \f7\fs20\lang1033 quest event notification for a socket. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSAAsyncSelect ( SOCKET {\plain \i\f7\fs20\lang1033 s}, HWND {\plain \i\f7\fs20\lang1033 hWnd}, unsigned int {\plain \i\f7\fs20\lang1033 wMsg}, long {\plain \i\f7\fs20\lang1033 lEvent}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 s}{\f7 \tab A descriptor identifying the socket for which event notification is required. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 hWnd}{\f7 \tab A handle identifying the window which should receive a message when a network event occurs. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 wMsg}{\f7 \tab The message to be received when a network event occurs. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard \s10\fi-1440\li2880 {\i\f7 lEvent}{\f7 \tab A bitmask which specifies a combination of network events in which the application is intereste}{\f7 d. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function is used to request that the Windows Sockets DLL should send a message to the window }{\i\f7 hWnd}{\f7 whenever it detects any of the network events specified by the }{ \i\f7 lEvent}{\f7 parameter. The message which should be sent is specified by the }{\i\f7 wMsg}{\f7 parameter. The socket for which notification is required is identified by }{\i\f7 s}{\f7 . \par }\pard\plain \fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 The }{\i\f7 lEvent}{\f7 parameter is constructed by or'ing any of the values specified in the following list. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s20\fi-1440\li3600 \fs20\ul\lang1033 {\b\f7\ulw Value\tab Meaning \par }\pard\plain \s21\fi-1440\li3600 \fs20\lang1033 {\f7 FD_READ\tab Want to receive notification of readiness for readi}{\f7 ng \par }{\f7 FD_WRITE\tab Want to receive notification of readiness for writing \par }\pard \s21\fi-1440\li3600 {\f7 FD_OOB\tab Want to receive notification of the arrival of out-of-band data \par }\pard \s21\fi-1440\li3600 {\f7 FD_ACCEPT\tab Want to receive notification of incoming connections \par }{\f7 FD_CONNECT\tab Want to receive notification of completed connection \par }{\f7 FD_CLOSE\tab Want to receive notification of socket closure \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Issuing a }{\b\f7 WSAAsyncSelect()}{\f7 for a socket cancels any previous }{\b\f7 WSAAsyncSelect()}{\f7 for the same socket. For example, to receive notification for both reading and writing, the application m}{\f7 ust call }{\b\f7 WSAAsyncSelect()}{\f7 with both FD_READ and FD_WRITE, as follows: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 rc = WSAAsyncSelect(s, hWnd, wMsg, FD_READ|FD_WRITE); \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 It is not possible to specify different messages for different events. The following code will }{\b\f7 not}{\f7 work; the second call will cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 rc = WSAAsyncSelect(s, hWnd, wMsg1, FD_READ); \par }{\f7 rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE); \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 To cancel all notification - i.e., to indicate that the Wind}{\f7 ows Sockets implementation should send no further messages related to network events on the socket - }{\i\f7 lEvent}{\f7 should be set to zero. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 rc = WSAAsyncSelect(s, hWnd, 0, 0); \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7\revised Although in this instance }{\b\f7\revised WSAAsyncSelect()}{\f7\revised immediately disables event message posting for the socket, it is possible that messages may be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a s }{\f7\revised ocket with }{\b\f7\uldb\revised closesocket()}{\v\f7 Winsock_closesoc}{\v\f7 ket}{\b\f7\revised }{\f7\revised also cancels }{\b\f7 WSAAsyncSelect()}{\f7\revised message sending, but the same caveat about messages in the queue prior to the }{\b\f7\uldb\revised closesocket()}{\v\f7 Winsock_closesocket}{\b\f7\revised }{\f7\revised still applies. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised Since an }{\b\f7\uldb\revised accept()}{\v\f7 Winsock_accept}{\b\f7\revised '}{\f7\revised ed socket has the same properties as the listening socket used to accept it, any }{\b\f7\revised WSAAsyncSelect() }{\f7\revised events set for the listening socket apply to the accepted socket. For example, if a listening socket has }{\b\f7\revised WSAAsyncSelect() }{\f7\revised events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will }{ \f7\revised also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same }{\i\f7\revised wMsg}{\f7\revised value used for messages. If a different }{\i\f7\revised wMsg}{\f7\revised or events are desired, the application should call }{\b\f7\revised WSAAsyncSelect()}{\f7\revised , passing the accepted socket and the desired new information.}{\f7 \par }\pard \s12\li1440 {\f7 \par }\pard\plain \li1800 \fs20\lang1033 {\f7 [Note: There is a timing window between the }{\b\f7\uldb accept()}{\v\f7 WinSock_accept}{\b\f7 }{\f7 call and the call to }{\b\f7 WSAAsyncSelect() }{\f7 to change the events or }{\i\f7 wMsg}{\f7 . An application which desires a different }{\i\f7 wMsg}{\f7 for the listening and }{\b\f7\uldb accept()}{\v\f7 WinSock_accept}{\f7 'ed sockets should ask for only FD_ACC}{\f7 EPT events on the listening socket, then set appropriate events after the }{ \b\f7\uldb accept()}{\v\f7 WinSock_accept}{\f7 . Since FD_ACCEPT is never sent for a connected socket and FD_READ, FD_WRITE, FD_OOB, and FD_CLOSE are never sent for listening sockets, this will not impose difficulties.] \par }\pard \li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 When one of the nominated network events occurs on the specified socket }{\i\f7 s}{\f7 , the application's window }{\i\f7 hWnd}{\f7 receives message }{\i\f7 wMsg}{\f7 . The }{\i\f7 wParam}{\f7 argument identifies the socket on which a network event has occurred. The low word of }{\i\f7 lParam}{\f7 speci}{\f7 fies the network event that has occurred. The high word of }{\i\f7 lParam}{\f7 contains any error code. The error code be any error as defined in }{\b\f7 winsock.h}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 The error and event codes may be extracted from the }{\i\f7 lParam}{\f7 using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in }{\b\f7 winsock.h}{\f7 as: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 #define WSAGETSELECTERROR(lParam) HIWORD(lParam) \par }{\f7 #define WSAGETSELECTEVENT(lParam) LOWORD(lParam) \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The use of these macros will maximize the portability of the source code for the application. }{\f7 \par }\pard \s12\li1440 {\f7 \par }{\f7 The possible network event codes which may be returned are as follows: \par }{\f7 \par }\pard\plain \s20\fi-1440\li3600 \fs20\ul\lang1033 {\b\f7\ulw Value\tab Meaning \par }\pard\plain \s21\fi-1440\li3600 \fs20\lang1033 {\f7 FD_READ\tab Socket }{\i\f7 s}{\f7 ready for reading \par }{\f7 FD_WRITE\tab Socket }{\i\f7 s}{\f7 ready for writing \par }{\f7 FD_OOB\tab Out-of-band data ready for reading on socket }{\i\f7 s}{\f7 . \par }{\f7 FD_ACCEPT\tab Socket }{\i\f7 s}{\f7 ready for accepting a new incoming connection \par }{\f7 FD_CONNECT\tab Connection on socket }{\i\f7 s}{\f7 completed \par }{\f7 FD_CLOSE\tab Connection identified by socket }{\i\f7 s}{\f7 has been closed \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value is 0 if the application's declaration of interest in the network event set was succe}{\f7 ssful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling }{\b\f7 WSAGetLastError()}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab Although }{\b\f7 WSAAsyncSelect()}{\f7 can be called with interest in multiple events, the application window will receive a single message for each network event. \par }\pard\plain \li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 As in the case of the }{\b\f7 select()}{\f7 function, }{\b\f7 WSAAsyncSelect()}{\f7 will frequently be used to determine when a data transfer operation (}{\b\f7 send()}{\f7 or }{\b\f7 recv()}{\f7 ) can be issued with the expectation of immediate success. Nevertheless, }{\f7 a robust application must be prepared for the possibility that it may receive a message and issue a Windows Sockets API call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible: \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard \s10\fi-1440\li2880 {\f7 (i)\tab data arrives on socket }{\b\f7 s}{\f7 ; Windows Sockets posts }{\b\f7 WSAAsyncSelect}{\f7 message \par }\pard \s10\fi-1440\li2880 {\f7 (ii)\tab application processes some other message \par }\pard \s10\fi-1440\li2880 {\f7 (iii)\tab while processing, application issues an }{\b\f7\uldb ioctlsocket(s, FIONREAD...)}{\v\f8 WinSock_IOCTLSocket}{\f7 and notices that there is data ready to be read \par }{\f7 (iv)\tab application }{\f7 issues a }{\b\f7\uldb recv(s,...)}{\v\f8 WinSock_Recv}{\f7 to read the data \par }\pard \s10\fi-1440\li2880 {\f7 (v)\tab application loops to process next message, eventually reaching the }{\b\f7 WSAAsyncSelect}{\f7 message indicating that data is ready to read \par }\pard \s10\fi-1440\li2880 {\f7 (vi)\tab application issues }{\b\f7\uldb recv(s,...)}{\v\f8 WinSock_Recv}{\f7 , which fails with the error WSAEWOULDBLOCK. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }{\f7 Other sequences are possible. \par }{\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application wind}{\f7 ow, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly re-enables notification of that network event. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s24\fi-2160\li3600 \fs20\ul\lang1033 {\b\f7\ulw Event\tab Re-enabling function \par }\pard\plain \s25\fi-2160\li3600\tx4320 \fs20\lang1033 {\f7 FD_READ\tab }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 or }{\b\f7\uldb recvfrom()}{\v\f8 WinSock_RecvFrom}{\f7 \par }{\f7 FD_WRITE\tab }{\b\f7\uldb send()}{\v\f8 WinSock_Send}{\f7 or }{\b\f7\uldb sendto()}{\v\f8 WinSock_SendTo}{\f7 \par }{\f7 FD_OOB\tab }{\b\f7\uldb recv()}{\v\f8 WinSock_Recv}{\f7 \par }{\f7 FD_ACCEPT\tab }{\b\f7\uldb accept()}{\v\f8 WinSock_Accept}{\f7 \par }\pard \s25\fi-2160\li3600\tx4320 {\f7 FD_CONNECT\tab NONE \par }{\f7 FD_CLOSE\tab NONE \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7\revised Any call to the reenabling routine, even one which fails, results in reen}{\f7\revised abling of message posting for the relevent event. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggerred." This means that if the reenabling routine is called and the relevent event is still valid after the call, a }{\b\f7\revised WSAAsyncSelect() }{\f7\revised message is posted to the application. This allows an application to be event-driven and not concern itself with the amount of data that arrives at any one time. Consider the following sequence:}{\revised \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7\revised (i)\tab Windows Sockets DLL receives 100 bytes of data o}{\f7\revised n socket }{\b\f7\revised s }{\f7\revised and posts an FD_READ message. \par }\pard \s10\fi-1440\li2880 {\f7\revised (ii)\tab The application issues }{\b\f7\revised recv( s, buffptr, 50, 0)}{\f7\revised to read 50 bytes. \par }\pard \s10\fi-1440\li2880 {\f7\revised (iii)\tab The Windows Sockets DLL posts another FD_READ message since there is still data to be read. \par }\pard \s10\fi-1440\li2880 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised With these semantics, an application need not read all available data in response to an FD_READ message--a single }{\b\f7\uldb\revised recv()}{\v\f7 Winsock_recv}{\b\f7\revised }{\f7\revised in response to each FD_READ message is appropriate. If an application issues multiple }{\b\f7\uldb\revised recv()}{\v\f7 Winsock_recv}{\b\f7\revised }{\f7\revised calls in response to a single FD_READ, it may receive mult}{\f7\revised iple FD_READ messages. Such an application may wish to disable FD_READ messages before starting the }{\b\f7\uldb\revised recv()}{\v\f7 Winsock_recv}{\b\f7\revised }{\f7\revised calls by calling }{\b\f7\revised WSAAsyncSelect() }{\f7\revised with the FD_READ event not set. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised If an event is true when the application initially calls }{\b\f7\revised WSAAsyncSelect()}{\f7\revised or when the reenabling function is called, then a message is posted as appropriate. For example, if an application calls }{\b\f7\uldb\revised listen()}{\v\f7 Winsock_listen}{\f7\revised , a connect attempt is made, then the application calls }{ \b\f7\revised WSAAsyncSelect() }{\f7\revised specifying that it wants to rece}{\f7\revised ive FD_ACCEPT messages for the socket, the Windows Sockets implementation posts an FD_ACCEPT message immediately.}{\f7 \par }\pard \s12\li1440 {\f7\revised \par }\pard \s12\li1440 {\f7\revised The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected}{\f7 with }{\b\f7\uldb connect()}{\v\f7 WinSock_connect}{\f7 or accepted with }{\b\f7\uldb accept()}{ \v\f7 WinSock_accept}{\f7\revised , and then after a }{\b\f7\uldb\revised send()}{\v\f7 Winsock_send}{\b\f7\revised }{\f7\revised or }{\b\f7\uldb\revised sendto()}{\v\f7 Winsock_sendto}{\b\f7\revised }{\f7\revised fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible }{\f7 starting from the firs}{\f7 t FD_WRITE message and lasting until a send returns}{\f7\revised WSAEWOULDBLOCK. After such a failure the application will be notified that sends are again possible with an FD_WRITE message. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \li1440 \fs20\lang1033 {\f7 The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should regis }{\f7 ter an interest in, and will receive, FD_READ events, }{\f7\ul not}{\f7 FD_OOB events. }{\f7 An application may set or inspect the way in which out-of-band data is to be handled by using }{\b\f7\uldb setsockopt()}{\v\f8 WinSock_SetSockOpt}{\f7 or }{\b\f7\uldb getsockopt}{\v\f7 WinSock_GetSockOpt}{\f7 for the SO_OOBINLINE option. \par }\pard \li1440 {\f7 \par }\pard \li1440 {\f7\revised The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is 0, then the close was graceful; if the error code is WSAECONN}{\f7 RESET}{\f7\revised , then the socket's virtual socket was abortively disconnected. This only applies to sockets of type SOCK_STREAM. \par }\pard \li1440 {\f7 \par }\pard \li1440 {\f7\revised The FD_CLOSE mes}{\f7\revised sage is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the FIN WAIT or CLOSE WAIT states.}{\f7 This results from the remote end performing a }{\b\f7\uldb shutdown()}{\v\f7 WinSock_shutdown}{\f7 on the send side or a }{\b\f7\uldb closesocket()}{\v\f7 WinSock_closesocket}{\f7 . \par }\pard \li1440 {\f7 \par }\pard \li1440 {\f7\revised Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit. It will NOT receive an FD_READ message to indic}{\f7\revised ate this condition. \par }\pard {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab Indicates that one of the specified parameters was invalid \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s28\li1440 \fs20\lang1033 {\f7 Additional error codes may be set when an application window receives a message. This error code is extracted from the }{\i\f7 lParam}{\f7 in the re}{\f7 ply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are: \par }\pard\plain \li1440 \fs20\lang1033 {\b\f7 Event: FD_CONNECT \par }\pard\plain \s27\fi-2160\li3600\tx4320\tx5760 \fs20\ul\lang1033 {\b\f7\ulw Error Code\tab \tab Meaning \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEADDRINUSE\tab The specified address is already in use. \par }\pard\plain \s27\fi-2160\li3600\tx4140\tx5760 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAEADDRNOTAVAIL\tab The specified address is not available from the local machine. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEAFNOSUPPORT\tab Addresses in the specified family cannot be used with this socket. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAECONNREFUSED\tab The attempt to connect was forcefully rejected. \par }{\f7 \par }{\f7 WSAEDESTADDRREQ\tab A destination address is required. \par }{\f7 \par }{\f7 WSAEFAULT\tab The namelen argu}{\f7 ment is incorrect. \par }{\f7 \par }{\f7 WSAEINVAL\tab The socket is already bound to an address. \par }{\f7 \par }{\f7 WSAEISCONN\tab The socket is already connected. \par }{\f7 \par }{\f7 WSAEMFILE\tab No more file descriptors are available. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETUNREACH\tab The network can't be reached from this host at this time. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENOBUFS\tab No buffer space is available. The socket cannot be connected. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAENOTCONN\tab The socket is not connected. \par }{\f7 \par }{\f7 WSAENOTSOCK\tab The descriptor is a file, not a socket. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAETIMEDOUT\tab Attempt to connect timed out without establishing a connection \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard \li1440 {\b\f7 Eve}{\b\f7 nt: FD_CLOSE \par }\pard\plain \s27\fi-2160\li3600\tx4320\tx5760 \fs20\ul\lang1033 {\b\f7\ulw Error Code\tab \tab Meaning \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }{\f7 WSAECONNRESET\tab The connection is reset by the remote side. \par }{\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAECONNABORTED\tab The connection was aborted due to timeout or other failure. \par }\pard\plain \li1440 \fs20\lang1033 {\b\f7 \par }\pard \fi-1440\li2880\tx2880 {\b\f7 Event: FD_READ \par }{\b\f7 Event: FD_WRITE \par }{\b\f7 Event: FD_OOB \par }{\b\f7 Event: FD_ACCEPT \par }\pard\plain \s27\fi-2160\li3600\tx4320\tx5760 \fs20\ul\lang1033 {\b\f7\ulw Error Code\tab \tab Meaning \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab It is th}{\f7 e responsibility of the Windows Sockets Supplier to ensure that messages are successfully posted to the application. If a }{\b\f7 PostMessage()}{\f7 operation fails, the Windows Sockets implementation }{\b\f7 must}{\f7 re-post that message as long as the window exists. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Windows Sockets suppliers should use the WSAMAKESELECTREPLY macro when constructing the }{\i\f7 lParam}{\f7 in the message. \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 When a socket is closed, the Windows Sockets Supplier should purge any messages remaining for posting to the application window. However the applicat}{\f7 ion must be prepared to receive, and discard, any messages which may have been posted prior to the }{\b\f7\uldb closesocket()}{\v\f8 WinSock_CloseSocket}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb select()}{\plain \v\f8\fs20\lang1033 WinSock_Select} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 {\*\bkmkstart lastedit}{\*\bkmkend lastedit}#{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Win}{\f7 Sock_CancelAsyncRequest}}} {\plain \fs16\up6\lang1033 $ {\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 WSACancelAsyncRequest()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0080}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSACancelAsyncRequest()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSACancelAsyncRequest() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Cancel an incomplete asynchronous operation. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSACancelAsyncRequest ( HANDLE {\plain \i\f7\fs20\lang1033 hAsyncTaskHandle}{\i }); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 hAsyncTaskHandle}{\f7 \tab Specifies the asynchronous operation to be canceled. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab The }{\b\f7 WSACancelAsyncRequest()}{\f7 fun}{\f7 ction is used to cancel an asynchronous operation which was initiated by one of the }{\b\f7 WSAAsyncGetXByY()}{\f7 functions such as }{\b\f7\uldb WSAAsyncGetHostByName()}{\v\f8 WinSock_AsyncGetHostByName}{\f7 . The operation to be canceled is identified by the }{\i\f7 hAsyncTaskHandle}{\f7 parameter, which should be set to the asynchronous task handle as returned by the initiating function. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The value returned by }{\b\f7 WSACancelAsyncRequest()}{\f7 is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a spec}{\f7 ific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab An attempt to cancel an existing asynchronous }{\b\f7 WSAAsyncGetXByY()}{\f7 operation can fail with an error code of WSAEALREADY for two reasons. Firstly, the original operation has already completed and the application has dealt with the resultant message. Secondly, the original operation has already completed but the resulta }{\f7 nt message is still waiting in the application window queue. \par }\pard \s26\fi-1440\li1440 {\f7 \par }\pard \s26\fi-1440\li1440 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s26\fi-1440\li1440 {\b\f7 Suppl}{\b\f7 iers}{\f7 \tab It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. [Trivial exception: 0 is always an i} {\f7 nvalid asynchronous task handle.] The Windows Sockets specification does not prescribe how a conformant Windows Sockets implementation should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the tw}{ \f7 o errors as equivalent. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab Indicates that the specified asynchronous task handle was invalid \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEALREADY\tab The asynchronous routine being canceled has already completed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAAsyncGetHostByAddr()}{\plain \v\f8\fs20\lang1033 WinSock_Async}{\plain \v\f8\fs20\lang1033 GetHostByAddr}, {\uldb WSAAsyncGetHostByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetHostByName}, {\uldb WSAAsyncGetProtoByNumber()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetProtoByNumber}, {\uldb WSAAsyncGetProtoByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetProtoByName}, {\uldb WSAAsyncGetHostByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetHostByName}, {\uldb WSAAsyncGetServByPort()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetServByPort}, {\uldb WSAAsyncGetServByName()}{\plain \v\f8\fs20\lang1033 WinSock_AsyncGetServByName}. \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_CancelBlockingCall}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSACancelBlockingCall()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0090}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSACancelBlockingCall()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSACancelBlockingCall() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Cancel a blocking call which is currently in progress. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSACancelBlockingCall ( void ); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function cancels any outstanding blocking operation for this task. It is normally used in two situations: \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 (1) An application is processing a message which has been received while a blocking call is in progress. In this case, }{\b\f7\uldb WSAIsBlocking()}{\v\f8 WinSock_IsBlocking}{\f7 will be true. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 (2) A blocking call is in progress, and Windows Sockets has called back to the application's "blocking hook" function (as established by }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHoo}{\v\f8 k}{\f7 ). \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in Windows Sockets. I }{\f7 n (2), the blocking call will be terminated as soon as the blocking hook function completes.) \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 In the case of a blocking }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 operation, the Windows Sockets implementation will terminate the blocking call as soon as possible, bu}{\f7 t it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are avai }{\f7 lable), or to }{\b\f7\uldb connect()}{\v\f8 WinSock_Connect}{\f7 to the same peer. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised Cancelling an }{\b\f7\uldb\revised accept()}{\v\f7 Winsock_accept}{\b\f7\revised }{\f7\revised or a }{\b\f7\uldb\revised select()}{\v\f7 Winsock_select}{\b\f7\revised }{\f7\revised call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal befo}{\f7\revised re the cancel is legal after the cancel, and the state of the socket is not affected in any way. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised Cancelling any operation other than }{\b\f7\uldb\revised accept()}{\v\f7 Winsock_accept}{\b\f7\revised }{\f7\revised and }{\b\f7\uldb\revised select()}{\v\f7 Winsock_select}{\b\f7\revised }{\f7\revised can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to }{\b\f7\uldb\revised closesocket()}{\v\f7 Winsock_closesocket}{\f7\revised , although other operations may work on some Windows Sockets implementations. If }{\f7\revised an application desires maximum portability, it must be careful not to depend on performing operations after a cancel. An application may reset the connection by setting the timeout on SO_LINGER to 0. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised If a cancel operation comprimised the integrity of a SOCK_STREAM's data stream in any way, the Windows Sockets implementation must reset the connection and fail all future operations other than }{\b\f7\uldb\revised closesocket()}{\v\f7 Winsock_closesocket}{\b\f7\revised }{\f7\revised with WSAECONNABORTED. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The value returned by }{\b\f7 WSACancelBlockingCall}{\b\f7 ()}{\f7 is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f2\revised Comments\tab }{\f7\revised Note that it is possible that the network operation completes before the }{\b\f7\revised WSACancelBlockingCall() }{\f7\revised is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if }{\b\f7\revised WSACancel}{\b\f7\revised BlockingCall() }{\f7\revised had never been called. Note that the }{\b\f7\revised WSACancelBlockingCall() }{\f7\revised still succeeds in this case; the only way to know with certainty that an operation was actually cancelled is to check for a return code of WSAEINTR from the blocking call. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab Indicates that there is no outstanding b}{\f7 locking call. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Cleanup}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 WSACleanup()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0100}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSACleanup()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSACleanup() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Terminate use of the Windows Sockets DLL.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSACleanup ( void ); \par \pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard \s5\fi-1440\li1440 {\b\f7 Remarks}{\f7 \tab }{\f7\revised An application is required to perform a (successful) }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\f7\revised call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application must call }{\b\f7\revised WSACleanup()}{\f7\revised to deregister itself from a Windows Sockets implementation and allow the implementa}{ \f7\revised tion to free any resources allocated on behalf of the application}{\f7 or DLL}{\f7\revised . Any open SOCK_STREAM sockets that are connected when }{\b\f7\revised WSACleanup() }{\f7\revised is called are }{\f7 reset}{\f7\revised ; sockets which have been closed with }{\b\f7\uldb\revised closesocket()}{\v\f7 Winsock_closesocket}{\b\f7\revised }{\f7\revised but which still have pending data to be sent are not affected--the pending data is still sent. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \tab }{\f7\revised There must be a call to }{\b\f7\revised WSACleanup() }{\f7\revised for every call to }{\b\f7\uldb\revised WSAStartup()}{\v\f7 Winsock_Startup}{\b\f7\revised }{\f7\revised made by a task. Only the final }{\b\f7\revised WSACleanup() }{\f7\revised does the actual cleanup; the preceding calls simply de}{\f7\revised crement an internal reference count in the Windows Sockets DLL. A naive application may ensure that }{ \b\f7\revised WSACleanup() }{\f7\revised was called enough times by calling }{\b\f7\revised WSACleanup() }{\f7\revised in a loop until it returns WSANOTINITIALISED.}{\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard \s7\fi-1440\li1440 {\b\f7\revised Comments\tab }{\f7\revised Attempting to call }{\b\f7\revised WSACleanup()}{\f7\revised from within a blocking hook and then failing to}{\f7\revised check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with }{\b\f7\uldb\revised WSACancelBlockingCall()}{\v\f7 Winsock_CancelBlockingCall}{\f7\revised then issue the }{\b\f7\revised WSACleanup() }{\f7\revised call once control has been returned to the application.}{\b\f7\revised \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab Well-behaved Windows Sockets applications will make a }{\b\f7 WSACleanup()}{\f7 call to indicate deregistration from a Windows Sockets implementation. }{\f7 This function can thus, for example, be utilized to free up resources allocated to the specific application. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 A Windows Sockets implementation must be prepared to deal with an application which terminates without invoking }{\b\f7 WSACleanup()}{\f7 - for example, as a result of an error. \par }\pard \s23\li1440 {\f7 \par }\pard \s23\li1440 {\f7 In a multithreaded environment, }{\b\f7 WSACleanup()}{\f7 terminates Windows Sockets operations for all threads. \par }\pard \s23\li1440 {\f7 \par }\pard \s23\li1440 {\f7 A Windows Sockets implementation must ensure that }{\b\f7 WSACleanup()}{\f7 leaves things in a state in which the application can invoke }{\b\f7 WSAS}{\b\f7 tartup()}{\f7 to re-establish Windows Sockets usage. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAStartup()}{\plain \v\f8\fs20\lang1033 WinSock_Startup} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_GetLastError}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 WSAGetLastError()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0110}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAGetLastError()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAGetLastError() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Get the error status for the last operation which failed.} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSAGetLastError ( void ); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function returns the last network error that occurred. When a particular Windows Sockets API function indicates that an error has occurred, this function should be called to retrieve the appropriate error code. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value indicates the error code for the last Windows Sockets API routine performed by this thread. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab The use of the }{\b\f7 WSAGetLastError()}{\f7 function to retrie}{\f7 ve the last error code, rather than relying on a global error variable (cf. }{\i\f7 errno}{\f7 ), is required in order to provide compatibility with future multi-threaded environments. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Note that in a Win16 environment }{\b\f7 WSAGetLastError()}{\f7 is used to retrieve only Windows Sockets API errors. In a Win32 environment, }{\b\f7 WSAGetLastError()}{\f7 will invoke }{\b\f7 GetLastError()}{\f7 , which is used to retrieve the error status for all Win32 API functions on a per-thread basis. For portability, an application should use }{\b\f7 WSAGetLastError()}{\f7 }{\b\f7 immed}{\b\f7 iately}{\f7 after the Windows Sockets API function which failed. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSASetLastError()}{\plain \v\f8\fs20\lang1033 WinSock_SetLastError} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_IsBlocking}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 WSAIsBlocking()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0120}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAIsBlcoking()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAIsBlocking() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab {\plain \f7\fs20\lang1033 Determine if a blocking call is in progress. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab BOOL PASCAL FAR WSAIsBlocking ( void ); \par \pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard \s5\fi-1440\li1440 {\b\f7 Remarks}{\f7 \tab This function allows a task to determine if it is executing while waiting for a previous blocking call to complete. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value is TRUE if there is an outstanding blocking func}{\f7 tion awaiting completion. Otherwise, it is FALSE. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s26\fi-1440\li1440 \fs20\lang1033 {\b\f7 Comments}{\f7 \tab Although a call issued on a blocking socket appears to an application program as though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application which iss} {\f7 ued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, the }{\b\f7 WSAIsBlocking()}{\f7 function can be used to ascertain whether the task has been re-entered whil}{\f7 e waiting for an outstanding blocking call to complete. Note that Windows Sockets prohibits more than one outstanding call per thread. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab A Windows Sockets implementation must prohibit more than one outstanding blocking call per thread. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SetBlockingHook}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSASetBlockingHook()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0125}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSASe}{\f7 tBlockingHook()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSASetBlockingHook() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description{\plain \f7\fs20\lang1033 \tab Establish an application-specific blocking hook function. \par } \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \tab {\b #include } \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 {\b }\tab {\b FARPROC PASCAL FAR WSASetBlockingHook ( FARPROC} {\i lpBlockFunc }{\b );} \par \pard\plain \fs20\lang1033 {\f7 }{\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 lpBlockFunc}{\f7 \tab A pointer to the procedure instance address of the blocking function to be installed. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function installs a new function which a Windows Sockets implementation should use to implement blocking socket function calls. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 A Windows Sockets implementation includes a default mechanism by which blocking socket functions are implemented. The function }{\b\f7 WSASetBlockingHook()}{\f7 gives the application the ability to execute its own function at "blocking" time in place of the default function.}{\f7 \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7 When an application invokes a blocking Windows Sockets API operation, the Windows Sockets implementation initiates the operation and then enters a loop which is equivalent to the following pseudocode: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 for(;;) \{ \par /* flush messages for good user response */ \par while(BlockingHook()) \par ; \par /* check for WSACancelBlockingCall() */ \par if(operation_cancelled()) \par break; \par /* check to see if operation completed */ \par if(operation_complete()) \par break; /* normal completion */ \par \} \par \pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7\revised Note that Windows Sockets implementations may perform the above steps in a different order; for example, the check for operation complete may occur before calling the blocking hook. The default }{\b\f7\revised BlockingHook()}{\f7\revised function is equivalent to: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 BOOL DefaultBlockingHook(void) \{ \par MSG msg; \par BOOL ret; \par /* get the next message if any */ \par ret = (BOOL)PeekMessage(&msg,NULL,0,0,PM_REMOVE); \par /* if we got one, process it */ \par if (ret) \{ \par TranslateMessage(&msg); \par DispatchMessage(&msg); \par \} \par /* TRUE if we got a message */ \par return ret; \par \}{\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 The }{\b\f7 WSASetBlockingHook()}{\f7 function is provided to support those applications which require more complex message processing - for example, those employing the MDI (multiple document interface) model. It is }{\f7\ul not }{\f7 intended as a mechanism for performing general applications functions. In particular, the only Windows Sockets API function which may be issued from a custom blocking hook function is }{\b\f7\uldb WSACancelBlock}{\b\f7\uldb ingCall()}{\v\f8 WinSock_CancelBlockingCall}{\f7 , which will cause the blocking loop to terminate. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised This function must be implemented on a per-task basis for non-multithreaded versions of Windows and on a per-thread basis for multithreaded versions of Windows such as Windows NT. It thus provides for a particular task or thread to replace the blocking m }{\f7\revised echanism without affecting other tasks or threads. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised In multithreaded versions of Windows, there is no default blocking hook--blocking calls block the thread that make}{\f7\revised s the call. However, an application may install a specific blocking hook by calling }{ \b\f7\revised WSASetBlockingHook(). \par }\pard \s12\li1440 {\f7\revised This allows easy portability of applications that depend on the blocking hook behavior. \par }\pard \s12\li1440 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value is a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the }{\b\f7 WSASetBlockingHook()}{ \f7 function should save this return value so that it can be restored if necessary. (If "nesting" is not important, the application }{\f7 may simply discard the value returned by }{\b\f7 WSASetBlockingHook()}{\f7 and eventually use }{\b\f7\uldb WSAUnhookBlockingHook()}{\v\f8 WinSock_UnhookBlockingHook}{\f7 to restore the default mechanism.) If the operation fails, a NULL pointer is returned, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab This function must be implemented on a per-thread basis. It thus provides for a particular thread to replace the blocking mechanism without affecting other }{\f7 threads. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAENETDOWN\tab The Windows Sockets implementation has detected that the network subsystem has failed. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINPROGRESS\tab A blocking Windows Sockets operation is in progress. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAUnhookBlockingHook()}{\plain \v\f8\fs20\lang1033 WinSock_UnhookBlockingHook} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_SetLastError}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 WSASetLastError()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0130}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSASetLastError()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSASetLastError() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description{\plain \f7\fs20\lang1033 \tab Set the error code which can be retrieved by }WSAGetLastError(){\plain \f7\fs20\lang1033 .} \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab void PASCAL FAR WSASetLastError ( int {\plain \i\f7\fs20\lang1033 iError}{\i }); \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function allows an application to set the error code to be returned by a subsequent }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error code as set by this routine. \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s6\fi-1440\li2880 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-1440\li2880 \fs20\lang1033 {\i\f7 iError}{\f7 \tab Specifies the error code to be returned by a subsequent }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 call. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard\plain \fs20\lang1033 {\b\f7 Suppliers}{\f7 \tab I}{\f7 n a Win32 environment, this function will invoke }{\b\f7 SetLastError()}{\f7 . \par }\pard {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab None. \par }\pard \s7\fi-1440\li1440 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSAGetLastError()}{\plain \v\f8\fs20\lang1033 WinSock_GetLastError} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_Startup}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 WSAStartup()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0140}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAStartup()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAStartup() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description\tab \par \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSAStartup ( WORD {\plain \i\f7\fs20\lang1033 wVersionRequired}, LPWSADATA {\plain \i\f7\fs20\lang1033 lpWSAData} ); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s6\fi-2160\li3600 \fs20\ul\lang1033 {\f7 \par }\pard\plain \s10\fi-2160\li3600 \fs20\lang1033 {\i\f7 wVersionRequired}{\f7 \tab The highest version of Windows Sockets API support that the call}{\f7 er can use. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number. \par }\pard \s10\fi-2160\li3600 {\f7 \par }\pard \s10\fi-2160\li3600 {\i\f7 lpWSAData}{\f7 \tab A pointer to the }{\b\f7 WSADATA}{\f7 data structure that is to receive details of the Windows Sockets implementation. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function }{\b\f7 must}{\f7 be the first Windows Sockets function called by an application or DLL. It allows an application to specify the version of Windows Sockets API required and to retrieve details of the specific Windows Sockets implementation. The}{\f7 application may only issue further Windows Sockets API functions after a successful }{\b\f7 WSAStartup()}{\f7 invocation. \par }\pard \s5\fi-1440\li1440 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised In order to support future Windows Sockets implementations and applications which may have functionality differences from Windows Sockets 1.1, a negotiation takes place in }{\b\f7\revised WSAStartup()}{ \f7\revised . The caller of }{\b\f7\revised WSAStartup()}{\f7\revised and the Windows Sockets DLL indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to }{ \b\f7\revised WSAStartup}{\b\f7\revised ()}{\f7\revised , the Windows Sockets DLL examines the version requested by the application. If this version is higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in }{ \i\f7\revised wHighVersion }{\f7\revised the highest version it supports and in }{\i\f7\revised wVersion}{\f7\revised the minimum of its high version and }{\i\f7\revised wVersionRequested. }{\f7\revised The Windows Sockets DLL then assumes that the application will use }{\i\f7\revised wVersion.}{\f7\revised If the }{\i\f7\revised wVersion}{\f7\revised field of the }{\b\f7\revised WSADATA}{\f7\revised structure is unacceptable to the caller, it should call }{\b\f7\uldb\revised WSACleanup()}{\v\f7 WinSock_Cleanup}{\b\f7\revised }{\f7\revised and}{\f7\revised either search for another Windows Sockets DLL or fail to initialize. \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised This negotiation allows both a Windows Sockets DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can successfully utilize a Windows Sockets DLL if there is any overlap in the version ranges. The followi }{\f7\revised ng chart gives examples of how }{\b\f7\revised WSAStartup()}{\f7\revised works in conjunction with different application and Windows Sockets DLL versions: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \tx1440\tx2880\tx5040\tx6120\tx7560 \fs20\lang1033 {\b\ulw App versions\tab DLL Versions\tab }{\b\i\ulw\revised wVersionRequested}{\b\ulw\revised \tab }{\b\i\ulw\revised wVersion}{\b\ulw\revised \tab }{\b\i\ulw wHighVersion\tab }{ \b\ulw\revised End Result }{\fs16\revised \par }\pard \li360\tx1890\tx3600\tx5400\tx6660\tx7560 {\f7\revised 1.1\tab 1.1\tab 1.1\tab 1.1\tab 1.1\tab use 1.1 \par }{\f7\revised 1.0 1.1\tab }{\f7 1.0\tab }{\f7\revised 1.1\tab }{\f7 1.0\tab 1.0\tab use 1.0 \par }\pard\plain \s2\fi-1440\li360\tx1890\tx3600\tx5400\tx6660\tx7560 \fs20\lang1033 {\f7 1.0\tab }{\f7\revised 1.0 1.1\tab }{\f7 1.0\tab 1.0\tab }{\f7\revised 1.1\tab }{\f7 \tab use 1.0 \par }\pard\plain \li360\tx1890\tx3600\tx5400\tx6660\tx7560 \fs20\lang1033 {\f7\revised 1.1\tab 1.0 1.1\tab 1.1\tab 1.1\tab 1.1\tab use 1.1 \par }{\f7\revised 1.1\tab }{\f7 1.0\tab }{\f7\revised 1.1\tab }{\f7 1.0\tab 1.0\tab }{\f7\revised App fails \par }{\f7 1.0\tab }{\f7\revised 1.1\tab }{\f7 1.0\tab }{\f7\revised ---\tab ---}{\f7 \tab NotSupp \par }{\f7\revised 1.0 1.1\tab 1.0 1.1\tab 1.1\tab 1.1\tab 1.1\tab use 1.1 \par }{\f7\revised 1.1 2.0\tab 1.1\tab }{\f7 2.0\tab }{\f7\revised 1.1\tab 1.1\tab use 1.1 \par }\pard\plain \s2\fi-1440\li360\tx1890\tx3600\tx5400\tx6660\tx7560 \fs20\lang1033 {\f7 2.0\tab }{\f7\revised 1.1\tab }{\f7 2.0\tab }{\f7\revised 1.1\tab 1.1\tab }{\f7 \tab }{\f7\revised App fails \par }\pard\plain \s12\li1440 \fs20\lang1033 \par \pard \s12\li1440 {\f7\revised The following code fragment demonstrates how an application which supports only version 1.1 of Windows Sockets makes a }{\b\f7\revised WSAStartup()}{\f7\revised call: \par }\pard \s12\li1440 \par \pard\plain \s29\li1440 \f5\fs20\lang1033 {\revised WORD wVersionRequested; \par }{\revised WSADATA wsaData; \par }{\revised int err;}{\revised \par } \par {\revised wVersionRequested = MAKEWORD( 1, 1 ); \par } \par {\revised err = WSAStartup( wVersionRequested, &wsaData ); \par }{\revised if ( err != 0 ) \{ \par }{\revised /* Tell the user that we couldn't find a useable */ \par }{\revised /* winsock.dll. */ \par }{\revised return; \par }\} \par \par {\revised /* Confirm that the Windows Sockets DLL supports 1.1.*/ \par }{\revised /* Note that if the DLL supports versions greater */ \par }{\revised /* than 1.1 in addition to 1.1, it will still return */ \par }{\revised /* 1.1 in wVersion since that is the version we */ \par }{\revised /* requested. }{\revised */ \par } \par {\revised if ( LOBYTE( wsaData.wVersion ) != 1 || \par }{\revised HIBYTE( wsaData.wVersion ) != 1 ) \{ \par }{\revised /* Tell the user that we couldn't find a useable */ \par }{\revised /* winsock.dll. */ \par }{\revised WSACleanup( ); \par }{\revised return; \par }\} \par \par {\revised /* The Windows Sockets DLL is acceptable. Proceed. */ \par } \par \pard \s29\li1440 {\revised And this code fragment demonstrates how a Windows Sockets DLL which supports only version 1.1 performs the }{\b\revised WSAStartup() }{\revised negotiation: \par }\pard \s29\li1440 \par {\revised /* Make sure that the version requested is >= 1.1. *}{\revised / \par }{\revised /* The low byte is the major version and the high */ \par }{\revised /* byte is the minor version. */ \par } \par {\revised if ( LOBYTE( wVersionRequested ) < 1 || \par }{\revised ( LOBYTE( wVersionRequested ) == 1 && \par }{\revised HIBYTE( wVersionRequested ) < 1 ) \{ \par }{\revised return WSAVERNOTSUPPORTED; \par }\} \par \par {\revised /* Since we only support 1.1, set both wVersion and */ \par }{\revised /* wHighVersion to 1.1. */ \par } \par {\revised lpWsaData->wVersion = MAKEWORD( 1, 1 ); \par }\tab \tab {\revised lpWsaData->wHighVersion = MAKEWORD( 1, 1 );}{\f7 \par }\pard\plain \s12\li720 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\f7 Once an application h}{\f7 as made a successful }{\b\f7 WSAStartup()}{\f7 call, it may proceed to make other Windows Sockets API calls as needed. When it has finished using the services of the Windows Sockets DLL, the application must call }{\b\f7\uldb WSACleanup()}{\v\f8 WinSock_Cleanup}{\f7 in order to allow the DLL to free any resources allocated by the Windows Sockets DLL for the application. \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 Details of the actual Windows Sockets implementation are described in the WSAData structure defined as follows: \par }\pard \s12\li1440 {\f7 \par }\pard\plain \s29\li1440 \f5\fs20\lang1033 struct WSAData \{ \par \tab WORD\tab \tab \tab wVersion; \par \tab WORD\tab \tab \tab wHighVersion; \par \tab char \tab \tab \tab szDescription[WSADESCRIPTION_LEN+1]; \par \tab char\tab \tab \tab szSystemStatus[WSASYSSTATUS_LEN+1]; \par \tab unsigned short\tab iMaxSockets; \par \tab unsigned short\tab iMaxUdpDg; \par \tab char FAR *\tab \tab lpVendorInfo \par \}; \par \pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s19\fi-2160\li3600\tx3600 \fs20\lang1033 {\f7 The members of this structure are: \par }\pard\plain \s6\fi-1620\li3060\tx3060 \fs20\ul\lang1033 {\b\f7\ulw Element\tab Usage \par }\pard\plain \s10\fi-1620\li3060\tx3060 \fs20\lang1033 {\f7 wVersion\tab The version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use. \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 wHighVersion\tab The highest version of the Windows Sockets specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion. \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 s}{\f7 zDescription\tab A null-terminated ASCII string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation, including vendor identification. The text (up to 256 characters in length) may contain any characters, but vendors }{\f7 are cautioned against including control and formatting characters: the most likely use that an application will put this to is to display it (possibly truncated) in a status message. \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 szSystemStatus\tab A null-terminated ASCII string into which the Windows Sock}{\f7 ets DLL copies relevant status or configuration information. The Windows Sockets DLL should use this field only if the information might be useful to the user or support staff: it should not be considered as an extension of the szDescription field. \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 iMaxSockets\tab The maximum number of sockets which a single process can potentially open. A Windows Sockets implementation may provide a global pool of sockets for allocation to any process; alternatively it may allocate per-process resources for sockets. }{\f7 The n} {\f7 umber may well reflect the way in which the Windows Sockets DLL or the networking software was configured. Application writers may use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For exam }{\f7 ple, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text m }{\f7 ig}{\f7 ht be used.) Obviously there is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there may be other Windows Sockets applications in use. \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 iMaxUdpDg\tab The size in bytes of the largest UDP datagram that can be sent or received by a Windows Sockets application. If the implementation imposes no limit, iMaxUdpDg is zero. In many implementations of Berkeley sockets, there is an implicit limit of }{\f7 8192 bytes on UDP datagrams (which are fragmented if necessary). A Windows}{\f7 Sockets implementation may impose a limit based, for instance, on the allocation of fragment reassembly buffers. The minimum value of iMaxUdpDg for a compliant Windows Sockets implementation is 512. Note that regardless of the value of iMaxUdpDg, it is }{\f7 inadvisable to attempt to send a }{\f7\ul broadcast}{\f7 datagram which is larger than the Maximum Transmission Unit (MTU) for the network. (The Windows Sockets API does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.) \par }\pard \s10\fi-1620\li3060\tx3060 {\f7 lpVendorInfo\tab }{\f7 A far pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of this specification. \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\f7 \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7\revised An application may call }{\b\f7\revised WSAStartup() }{\f7\revised more than once if it needs to obtain the WSAData structure information more than once. However, the }{\i\f7\revised wVersionRequired } {\f7\revised parameter is assumed to be the same on all calls to }{\b\f7\revised WSAStartup()}{\f7\revised ; that is, an application cannot change the version of Windows Sockets it expects after the initial call to }{\b\f7\revised WSAStartup(). \par }\pard \s12\li1440 {\b\f7 \par }\pard \s12\li1440 {\f7\revised There must be one }{\b\f7\uldb\revised WSAC}{\b\f7\uldb\revised leanup()}{\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised call corresponding to every }{\b\f7\revised WSAStartup() }{\f7\revised call to allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an application. This means, for example, that if an application calls }{\b\f7\revised WSAStartup() }{\f7\revised three times, it must call }{\b\f7\uldb\revised WSACleanup()} {\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised three times. The first two calls to }{\b\f7\uldb\revised WSACleanup()}{\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised do nothing except decrement an internal counter; the final }{ \b\f7\uldb\revised WSACleanup()}{\v\f7 Winsock_Cleanup}{\b\f7\revised }{\f7\revised call does all necessary resource deallocation for the task.}{\b\revised \par }\pard \s12\li1440 \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Valu}{\b\f7 e}{\f7 \tab }{\b\f7 WSAStartup()}{\f7 returns zero if successful. Otherwise it returns one of the error codes listed below. Note that the normal mechanism whereby the application calls }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 to determine the error code cannot be used, since the Windows Sockets DLL may not have established the client data area where the "last error" information is stored. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\b\f7 Notes For \par }{\b\f7 Windows Sockets \par }\pard \s22\fi-1440\li1440 {\b\f7 Suppliers}{\f7 \tab Each Windows Sockets application }{\b\f7 must}{\f7 make a }{\b\f7 WSAStartup()}{\f7 call before issuing any other Windows Sockets}{\f7 API calls. This function can thus be utilized for initialization purposes. \par }\pard\plain \s23\li1440 \fs20\lang1033 {\f7 \par }\pard \s23\li1440 {\f7 Further issues are discussed in the notes for }{\b\f7\uldb WSACleanup()}{\v\f8 WinSock_Cleanup}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSASYSNOTREADY\tab Indicates that the underlying network subsystem is not ready for network communication. \par }\pard \s8\fi-4320\li4320\keep\tx1440\tx4320 {\f7 \par }\pard\plain \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 \fs20\lang1033 {\f7 WSAVERNOTSUPPORTED\line The version of Windows Sockets API support requested is not provided by this particular Windows Sockets implementation. \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 \par }\pard \s11\fi-2880\li4320\keep\tx1440\tx4320\tx5040 {\f7 WSAEINVAL\tab The Windows Sockets version specified by the application is not supported by this DL}{\f7 L. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb send()}{\plain \v\f8\fs20\lang1033 WinSock_Send}, {\uldb sendto()}{\plain \v\f8\fs20\lang1033 WinSock_SendTo}, {\uldb WSACleanup()}{\plain \v\f8\fs20\lang1033 WinSock_Cleanup} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_UnhookBlockingHook}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 WSAUnhookBlockingHook()}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockWSE:0150}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 WSAUnhookBlockingHook()}}} Microsoft Windows Specific Extensions \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 WSAUnhookBlockingHook() \par \pard\plain \s3\fi-1080\li1080 \b\f7\fs20\lang1033 Description{\plain \f7\fs20\lang1033 \tab Restore the default blocking hook function. \par } \par \tab #include \par \pard\plain \s36\fi-1080\li1080\tx1080 \f7\fs20\lang1033 \par \pard\plain \s4\fi-1080\li1080 \b\f7\fs20\lang1033 \tab int PASCAL FAR WSAUnhookBlockingHook ( void ); \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s5\fi-1440\li1440 \fs20\lang1033 {\b\f7 Remarks}{\f7 \tab This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism. \par }\pard\plain \s12\li1440 \fs20\lang1033 {\f7 \par }\pard \s12\li1440 {\b\f7 WSAUnhookBlockingHook()}{\f7 will always install the }{\b\f7 default}{\f7 mechanism, not the }{\b\f7 previou}{\b\f7 s}{\f7 mechanism. If an application wish to nest blocking hooks - i.e. to establish a temporary blocking hook function and then revert to the previous mechanism (whether the default or one established by an earlier }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 ) - it must save and restore the value returned by }{\b\f7\uldb WSASetBlockingHook()}{\v\f8 WinSock_SetBlockingHook}{\f7 ; it cannot use }{\b\f7 WSAUnhookBlockingHook()}{\f7 . \par }\pard \s12\li1440 {\f7 \par }\pard \s12\li1440 {\f7\revised In multithreaded versions of Windows such as Windows NT, there is no default blocking hook. Calling }{\b\f7\revised WSAUnhookBlockingHo}{\b\f7\revised ok() }{\f7\revised disables any blocking hook installed by the application and any blocking calls made block the thread which made the call. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s7\fi-1440\li1440 \fs20\lang1033 {\b\f7 Return Value}{\f7 \tab The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 . \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s8\fi-4320\li4320\keep\tx1440\tx4320 \fs20\lang1033 {\b\f7 Error Codes}{\f7 \tab WSANOTINITIALISED\tab A successful }{\b\f7\uldb WSAStartup()}{\v\f8 WinSock_Startup}{\f7 must occur before using this API. \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s9\fi-1440\li1440\tx1440 \b\f8\fs20\lang1033 See Also\tab {\uldb WSASetBlockingHook()}{\plain \v\f8\fs20\lang1033 WinSock_SetBlockingHook} \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 {\ul \page }{\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_ErrorCodes}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Error Codes}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Error Codes}}} Windows Sockets{\ul \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 Error Codes \par \pard\plain \fs20\lang1033 {\f7 The following is a list of possible error codes returned by the }{\b\f7\uldb WSAGetLastError()}{\v\f8 WinSock_GetLastError}{\f7 call, along with their explanations. The error numbers are consistently set across all Windows Sockets-compliant implementations. \par }\pard\plain \s31\fi-5400\li6840\keep\keepn\tx1440\tx3600\tx5760\tx7200 \f5\fs16\lang1033 {\f7 \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\b\f7\ulw Windows Sockets code\tab Berkeley equivalent\tab Error\tab Interpretation \par }{\f7 WSAEINTR\tab EINTR\tab 10004\tab As in standard C \par }{\f7 WSAEBADF\tab EBADF\tab 10009\tab As in standard C \par }{\f7 WSEACCES\tab EACCES\tab 10013\tab As in standard C \par }{\f7 WSAEFAULT\tab EFAULT\tab 10014\tab As in standard C \par }{\f7 WSAEINVAL\tab EINVAL\tab 10022}{\f7 \tab As in standard C \par }{\f7 WSAEMFILE\tab EMFILE\tab 10024\tab As in standard C \par }{\f7 WSAEWOULDBLOCK\tab EWOULDBLOCK\tab 10035\tab As in BSD \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSAEINPROGRESS\tab EINPROGRESS\tab 10036\tab This error is returned if anyWindows Sockets API function is called while a blocking function is in progress. \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSAEALREADY\tab EALREADY\tab 10037\tab As in BSD \par }{\f7 WSAENOTSOCK\tab ENOTSOCK\tab 10038\tab As in BSD \par }{\f7 WSAEDESTADDRREQ\tab EDESTADDRREQ\tab 10039\tab As in BSD \par }{\f7 WSAEMSGSIZE\tab EMSGSIZE\tab 10040\tab As in BSD \par }{\f7 WSAEPROTOTYPE\tab EPROTOTYPE\tab 10041\tab As in BSD \par }{\f7 WSAENOPROTOOPT\tab ENOPROTOOPT\tab 10042\tab As in BSD \par }{\f7 WSAEPROTONOSUPPORT}{\f7 \tab EPROTONOSUPPORT\tab 10043\tab As in BSD \par }{\f7 WSAESOCKTNOSUPPORT\tab ESOCKTNOSUPPORT\tab 10044\tab As in BSD \par }{\f7 WSAEOPNOTSUPP\tab EOPNOTSUPP\tab 10045\tab As in BSD \par }{\f7 WSAEPFNOSUPPORT\tab EPFNOSUPPORT\tab 10046\tab As in BSD \par }{\f7 WSAEAFNOSUPPORT\tab EAFNOSUPPORT\tab 10047\tab As in BSD \par }{\f7 WSAEADDRINUSE\tab EADDRINUSE\tab 10048\tab As in BSD \par }{\f7 WSAEADDRNOTAVAIL\tab EADDRNOTAVAIL\tab 10049\tab As in BSD \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSAENETDOWN\tab ENETDOWN\tab 10050\tab As in BSD. This error may be reported at any time if the Windows Sockets implementation detects an underlying failure. \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSAENETUNREACH\tab ENETUNREACH\tab 10051\tab As in BSD \par }{\f7 WSAENETRES}{\f7 ET\tab ENETRESET\tab 10052\tab As in BSD \par }{\f7 WSAECONNABORTED\tab ECONNABORTED\tab 10053\tab As in BSD \par }{\f7 WSAECONNRESET\tab ECONNRESET\tab 10054\tab As in BSD \par }{\f7 WSAENOBUFS\tab ENOBUFS\tab 10055\tab As in BSD \par }{\f7 WSAEISCONN\tab EISCONN\tab 10056\tab As in BSD \par }{\f7 WSAENOTCONN\tab ENOTCONN\tab 10057\tab As in BSD \par }{\f7 WSAESHUTDOWN\tab ESHUTDOWN\tab 10058\tab As in BSD \par }{\f7 WSAETOOMANYREFS\tab ETOOMANYREFS\tab 10059\tab As in BSD \par }{\f7 WSAETIMEDOUT\tab ETIMEDOUT\tab 10060\tab As in BSD \par }{\f7 WSAECONNREFUSED\tab ECONNREFUSED\tab 10061\tab As in BSD \par }{\f7 WSAELOOP\tab ELOOP\tab 10062\tab As in BSD \par }{\f7 WSAENAMETOOLONG\tab ENAMETOOLONG\tab 10063\tab As in BSD \par }{\f7 WSAEHOSTDOWN\tab EHOSTDOWN\tab 10064\tab As in}{\f7 BSD \par }{\f7 WSAEHOSTUNREACH\tab EHOSTUNREACH\tab 10065\tab As in BSD \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSASYSNOTREADY\tab \tab 10091\tab Returned by }{\b\f7\uldb WSAStartup()}{\v\f8\fs20 WinSock_Startup}{\f7 \line indicating that the network subsystem is unusable. \par }{\f7 WSAVERNOTSUPPORTED\tab \tab 10092\tab Returned by }{\b\f7\uldb WSAStartup()}{\v\f8\fs20 WinSock_Startup}{\f7 \line indicating that the Windows Sockets\line DLL cannot support this app. \par }{\f7 WSANOTINITIALISED\tab \tab 10093\tab Returned by any function except }{\b\f7\uldb WSAStartup()}{\v\f8\fs20 WinSock_Startup}{\f7 indicating that a successful }{\b\f7\uldb WSAStartup()}{\v\f8\fs20 WinSock_Startup}{\f7 has not yet been performed. \par }\pard \s31\fi-5040\li5760\tx720\tx2880\tx4770\tx5760 {\f7 WSAHOST_NOT_FOUND\tab HOST_NOT_FOUND\tab 11001\tab As}{\f7 in BSD. \par }{\f7 WSATRY_AGAIN\tab TRY_AGAIN\tab 11002\tab As in BSD \par }{\f7 WSANO_RECOVERY\tab NO_RECOVERY\tab 11003\tab As in BSD \par }{\f7 WSANO_DATA\tab NO_DATA\tab 11004\tab As in BSD \par }\pard\plain \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7 The first set of definitions is present to resolve contentions between standard C error codes which may be defined inconsistently between various C compilers. \par }\pard {\f7 \par }\pard {\f7 The second set of definitions provides Windows Sockets versions of regular Berkeley Sockets error codes. \par }\pard {\f7 \par }{\f7 The third set of definitions consists of extended Windows Sockets-specific error codes. \par }{\f7 \par }\pard {\f7 The fourth set of}{\f7 errors are returned by Windows Sockets }{\b\f7\uldb getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 and }{\b\f7 WSAAsyncGetXByY()}{\f7 functions, and correspond to the errors which in Berkeley software would be returned in the }{\i\f7 h_errno}{\f7 variable. They correspond to various failures which may be returned by the Domain Name Service. If the Windows Sockets implementation does not use the DNS, it will use the most appropriate code. In general, a Windows Sockets application should interp }{\f7 ret WSAHOST_NOT_FOUND and WSANO_DATA as indicating th}{\f7 at the key (name, address, etc.) was not found,, while WSATRY_AGAIN and WSANO_RECOVERY suggest that the name service itself is non-operational. \par }\pard {\f7 \par }\pard {\f7 The error numbers are derived from the }{\b\f7\uldb winsock.h}{\v\f8 WinSock_WinSockH}{\f7 header file, and are based on the fact that Windows Sockets error numbers are computed by adding 10000 to the "normal" Berkeley error number. \par }\pard {\f7 \par }\pard {\f7 Note that this table does not include all of the error codes defined in }{\b\f7 winsock.h}{\f7 . This is because it includes only errors which might reasonably be retur}{\f7 ned by a Windows Sockets implementation: }{\b\f7 winsock.h}{\f7 , on the other hand, includes a full set of BSD definitions to ensure compatibility with ported software. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_HeaderFiles}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 Header Files}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Header Files}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Header Files \par \pard\plain \li720 \fs20\lang1033 {\b\f8\uldb Berkeley Header Files}{\v\f8 Winsock_BerkeleyHeaders}{\b\f7 \par }{\b\f8\uldb Windows Sockets Header File - winsock.h}{\v\f8 Winsock_WinsockH}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_BerkeleyHeaders}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Berkeley Header Files}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinsockH:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Header Files}}} Windows Sockets Header Files \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Berkeley Header Files \par \pard\plain \fs20\lang1033 {\f7 A Windows Sockets supplier who provides a development kit to support the development of Windows Sockets applications must supply a set of vestigial }{\f7 header files with names that match a number of the header files in the Berkeley software distribution. These files are provided for source code compatibility only, and each consists of three lines: \par }\pard {\f7 \par }\pard\plain \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 #ifndef _WINSOCKAPI_ \par #include \par #endif \par \pard\plain \fs20\lang1033 {\f7 \par }{\f7 The header files provided for compatibility are: \par }\pard \li360 {\b\f7 netdb.h \par }{\b\f7 arpa/inet.h \par }{\b\f7 sys/time.h \par }{\b\f7 sys/socket.h \par }{\b\f7 netinet/in.h \par }\pard {\f7 \par }\pard {\f7 The file }{\b\f7\uldb winsock.h}{\v\f7 Winsock_WinsockH}{\f7 contains all of the type and structure definitions, constants, macros, and function prototypes used by the W}{\f7 indows Sockets specification. An application writer may choose to ignore the compatibility headers and include }{\b\f7 winsock.h}{\f7 in each source file. \par }\pard {\f7 \par }{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_Win}{\f7 sockH}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Windows Sockets Header File - winsock.h}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinsockH:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Header Files}}} Windows Sockets Header Files \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Windows Sockets Header File - winsock.h \par \pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7 The }{\b\f7 winsock.h}{\f7 header file includes a number of types and definitions from the standard Windows header file }{\b\f7 windows.h}{\f7 . The }{\b\f7 windows.h}{\f7 in the Windows 3.0 SDK (Software Developer's Kit) lacks a #include guard, so if you need to include }{\b\f7 windows.h}{\f7 as well as }{\b\f7 winsock.h}{\f7 , you should define}{\f7 the symbol _INC_WINDOWS before #including }{\b\f7 winsock.h}{\f7 , as follows: \par }\pard\plain \s30\li1440\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 #include \par #define _INC_WINDOWS \par #include \par \pard\plain \s32\fi-1440\li2880 \f5\fs20\lang1033 {\f7 \par }\pard\plain \fs20\lang1033 {\f7 Users of the SDK for Windows 3.1 and later need not do this. \par }{\f7 \par }\pard {\f7\revised A Windows Sockets DLL vendor }{\b\f7\revised MUST NOT}{\f7\revised make any modifications to this header file which could impact binary compatibility of Windows Sockets applications. The constant values, function parameters and return codes, and the like must remain consistent across all Windows Sockets DLL vendors. \par }\pard {\f7 \par }\pard\plain \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 {\f7 \par }\pard \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 /* WINSOCK.H--definitions to be used with the WINSOCK.DLL \par * \par * This header file corresponds to version 1.1 of the Windows Sockets specification. \par * \par * This file includes parts which are Copyright (c) 1982-1986 Regents \par * of the University of California. All rights reserved. The \par * Berkeley Software License Agreement specifies the terms and \par * conditions for redistribution. \par */ \par \par #ifndef _WINSOCKAPI_ \par #define _WINSOCKAPI_ \par \par /* \par * Pull in WINDOWS.H if necessary \par */ \par #ifndef _INC_WINDOWS \par #include \par #endif /* _INC_WINDOWS */ \par \par /* \par * Basic system type definitions, taken from the BSD file sys/types.h. \par */ \par typedef unsigned char u_char; \par typedef unsigned short u_short; \par typedef unsigned int u_int; \par typedef unsigned long u_long; \par \par /* \par * The new type to be used in all \par * instances which refer to sockets. \par */ \par typedef u_int SOCKET; \par \par /* \par * Select uses arrays of SOCKETs. These macros manipulate such \par * arrays. FD_SETSIZE may be defined by the user before including \par * this file, but the default here should be >= 64. \par * \par * CAVEAT IMPLEMENTOR and USER: THESE MACROS AND TYPES MUST BE \par * INCLUDED IN WINSOCK.H EXACTLY AS SHOWN HERE. \par */ \par #ifndef FD_SETSIZE \par #define FD_SETSIZE 64 \par #endif /* FD_SETSIZE */ \par \par typedef struct fd_set \{ \par u_short fd_count; /* how many are SET? */ \par SOCKET fd_array[FD_SETSIZE]; /* an array of SOCKETs */ \par \} fd_set; \par \par extern int PASCAL FAR __WSAFDIsSet(SOCKET, fd_set FAR *); \par \par {\revised #define FD_CLR(fd, set) do \{ \\ \par } u_int __i; \\ \par for (__i = 0; __i < ((fd_set FAR *)(set))->fd_count ; __i++) \{ \\ \par if (((fd_set FAR *)(set))->fd_array[__i] == fd) \{ \\ \par while (__i < ((fd_set FAR *)(set))->fd_count-1) \{ \\ \par ((fd_set FAR *)(set))->fd_array[__i] = \\ \par ((fd_set FAR *)(set))->fd_array[__i+1]; \\ \par __i++; \\ \par \} \\ \par ((fd_set FAR *)(set))->fd_count--; \\ \par break; \\ \par \} \\ \par \} \\ \par {\revised \} while(0) \par } \par {\revised #define FD_SET(fd, set) do \{ \\ \par } if (((fd_set FAR *)(set))->fd_count < FD_SETSIZE) \\ \par ((fd_set FAR *)(set))->fd_array[((fd_set FAR *)(set))->fd_count++]=fd;\\ \par {\revised \} while(0) \par } \par {\revised #define FD_ZERO(set) (((fd_set FAR *)(set))->fd_count=0) \par } \par #define FD_ISSET(fd, set) __WSAFDIsSet((SOCKET)fd, (fd_set FAR *)set) \par \par /* \par * Structure used in select() call, taken from the BSD file sys/time.h. \par */ \par struct timeval \{ \par long tv_sec; /* seconds */ \par long tv_usec; /* and microseconds */ \par \}; \par \par /* \par * Operations on timevals. \par * \par * NB: timercmp does not work for >= or <=. \par */ \par #define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) \par #define timercmp(tvp, uvp, cmp) \\ \par ((tvp)->tv_sec cmp (uvp)->tv_sec || \\ \par (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec) \par #define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0 \par \par /* \par * Commands for ioctlsocket(), taken from the BSD file fcntl.h. \par * \par * \par * Ioctl's have the command encoded in the lower word, \par * and the size of any in or out parameters in the upper \par * word. The high 2 bits of the upper word are used \par * to encode the in/out status of the parameter; for now \par * we restrict parameters to at most 128 bytes. \par */ \par #define IOCPARM_MASK 0x7f /* parameters must be < 128 bytes */ \par #define IOC_VOID 0x20000000 /* no parameters */ \par #define IOC_OUT 0x40000000 /* copy out parameters */ \par #define IOC_IN 0x80000000 /* copy in parameters */ \par #define IOC_INOUT (IOC_IN|IOC_OUT) \par /* 0x20000000 distinguishes new & \par old ioctl's */ \par #define _IO(x,y) (IOC_VOID|(x<<8)|y) \par \par #define _IOR(x,y,t) (IOC_OUT|(((long)sizeof(t)&IOCPARM_MASK)<<16)|(x<<8)|y) \par \par #define _IOW(x,y,t) (IOC_IN|(((long)sizeof(t)&IOCPARM_MASK)<<16)|(x<<8)|y) \par \par #define FIONREAD _IOR('f', 127, u_long) /* get # bytes to read */ \par #define FIONBIO _IOW('f', 126, u_long) /* set/clear non-blocking i/o */ \par #define FIOASYNC _IOW('f', 125, u_long) /* set/clear async i/o */ \par \par /* Socket I/O Controls */ \par #define SIOCSHIWAT _IOW('s', 0, u_long) /* set high watermark */ \par #define SIOCGHIWAT _IOR('s', 1, u_long) /* get high watermark */ \par #define SIOCSLOWAT _IOW('s', 2, u_long) /* set low watermark */ \par #define SIOCGLOWAT _IOR('s', 3, u_long) /* get low watermark */ \par #define SIOCATMARK _IOR('s', 7, u_long) /* at oob mark? */ \par \par /* \par * Structures returned by network data base library, taken from the \par * BSD file netdb.h. All addresses are supplied in host order, and \par * returned in network order (suitable for use in system calls). \par */ \par \par struct hostent \{ \par char FAR * h_name; /* official name of host */ \par char FAR * FAR * h_aliases; /* alias list */ \par short h_addrtype; /* host address type */ \par short h_length; /* length of address */ \par char FAR * FAR * h_addr_list; /* list of addresses */ \par #define h_addr h_addr_list[0] /* address, for backward compat */ \par \}; \par \par /* \par * It is assumed here that a network number \par * fits in 32 bits. \par */ \par struct netent \{ \par char FAR * n_name; /* official name of net */ \par char FAR * FAR * n_aliases; /* alias list */ \par short n_addrtype; /* net address type */ \par u_long n_net; /* network # */ \par \}; \par \par struct servent \{ \par char FAR * s_name; /* official service name */ \par char FAR * FAR * s_aliases; /* alias list */ \par short s_port; /* port # */ \par char FAR * s_proto; /* protocol to use */ \par \}; \par \par struct protoent \{ \par char FAR * p_name; /* official protocol name */ \par char FAR * FAR * p_aliases; /* alias list */ \par short p_proto; /* protocol # */ \par \}; \par \par /* \par * Constants and structures defined by the internet system, \par * Per RFC 790, September 1981, taken from the BSD file netinet/in.h. \par */ \par \par /* \par * Protocols \par */ \par #define IPPROTO_IP 0 /* dummy for IP */ \par #define IPPROTO_ICMP 1 /* control message protocol */ \par #define IPPROTO_GGP 2 /* gateway^2 (deprecated) */ \par #define IPPROTO_TCP 6 /* tcp */ \par #define IPPROTO_PUP 12 /* pup */ \par #define IPPROTO_UDP 17 /* user datagram protocol */ \par #define IPPROTO_IDP 22 /* xns idp */ \par #define IPPROTO_ND 77 /* UNOFFICIAL net disk proto */ \par \par #define IPPROTO_RAW 255 /* raw IP packet */ \par #define IPPROTO_MAX 256 \par \par /* \par * Port/socket numbers: network standard functions \par */ \par #define IPPORT_ECHO 7 \par #define IPPORT_DISCARD 9 \par #define IPPORT_SYSTAT 11 \par #define IPPORT_DAYTIME 13 \par #define IPPORT_NETSTAT 15 \par #define IPPORT_FTP 21 \par #define IPPORT_TELNET 23 \par #define IPPORT_SMTP 25 \par #define IPPORT_TIMESERVER 37 \par #define IPPORT_NAMESERVER 42 \par #define IPPORT_WHOIS 43 \par #define IPPORT_MTP 57 \par \par /* \par * Port/socket numbers: host specific functions \par */ \par #define IPPORT_TFTP 69 \par #define IPPORT_RJE 77 \par #define IPPORT_FINGER 79 \par #define IPPORT_TTYLINK 87 \par #define IPPORT_SUPDUP 95 \par \par /* \par * UNIX TCP sockets \par */ \par #define IPPORT_EXECSERVER 512 \par #define IPPORT_LOGINSERVER 513 \par #define IPPORT_CMDSERVER 514 \par #define IPPORT_EFSSERVER 520 \par \par /* \par * UNIX UDP sockets \par */ \par #define IPPORT_BIFFUDP 512 \par #define IPPORT_WHOSERVER 513 \par #define IPPORT_ROUTESERVER 520 \par /* 520+1 also used */ \par \par /* \par * Ports < IPPORT_RESERVED are reserved for \par * privileged processes (e.g. root). \par */ \par #define IPPORT_RESERVED 1024 \par \par /* \par * Link numbers \par */ \par #define IMPLINK_IP 155 \par #define IMPLINK_LOWEXPER 156 \par #define IMPLINK_HIGHEXPER 158 \par \par /* \par * Internet address (old style... should be updated) \par */ \par struct in_addr \{ \par union \{ \par struct \{ u_char s_b1,s_b2,s_b3,s_b4; \} S_un_b; \par struct \{ u_short s_w1,s_w2; \} S_un_w; \par u_long S_addr; \par \} S_un; \par #define s_addr S_un.S_addr \par /* can be used for most tcp & ip code */ \par #define s_host S_un.S_un_b.s_b2 \par /* host on imp */ \par #define s_net S_un.S_un_b.s_b1 \par /* network */ \par #define s_imp S_un.S_un_w.s_w2 \par /* imp */ \par #define s_impno S_un.S_un_b.s_b4 \par /* imp # */ \par #define s_lh S_un.S_un_b.s_b3 \par /* logical host */ \par \}; \par \par /* \par * Definitions of bits in internet address integers. \par * On subnets, the decomposition of addresses to host and net parts \par * is done according to subnet mask, not the masks here. \par */ \par #define IN_CLASSA(i) (((long)(i) & 0x80000000) == 0) \par #define IN_CLASSA_NET 0xff000000 \par #define IN_CLASSA_NSHIFT 24 \par #define IN_CLASSA_HOST 0x00ffffff \par #define IN_CLASSA_MAX 128 \par \par #define IN_CLASSB(i) (((long)(i) & 0xc0000000) == 0x80000000) \par #define IN_CLASSB_NET 0xffff0000 \par #define IN_CLASSB_NSHIFT 16 \par #define IN_CLASSB_HOST 0x0000ffff \par #define IN_CLASSB_MAX 65536 \par \par #define IN_CLASSC(i) (((long)(i) & 0xc0000000) == 0xc0000000) \par #define IN_CLASSC_NET 0xffffff00 \par #define IN_CLASSC_NSHIFT 8 \par #define IN_CLASSC_HOST 0x000000ff \par \par #define INADDR_ANY (u_long)0x00000000 \par #define INADDR_LOOPBACK 0x7f000001 \par #define INADDR_BROADCAST (u_long)0xffffffff \par #define INADDR_NONE 0xffffffff \par \par /* \par * Socket address, internet style. \par */ \par struct sockaddr_in \{ \par short sin_family; \par u_short sin_port; \par struct in_addr sin_addr; \par char sin_zero[8]; \par \}; \par \par #define WSADESCRIPTION_LEN 256 \par #define WSASYS_STATUS_LEN 128 \par \par typedef struct WSAData \{ \par WORD wVersion; \par WORD wHighVersion; \par char szDescription[WSADESCRIPTION_LEN+1]; \par char szSystemStatus[WSASYS_STATUS_LEN+1]; \par {\revised unsigned short iMaxSockets; \par }{\revised unsigned short iMaxUdpDg; \par } char FAR * lpVendorInfo; \par \} WSADATA; \par \par typedef WSADATA FAR *LPWSADATA; \par \par /* \par * Options for use with [gs]etsockopt at the IP level. \par */ \par #define IP_OPTIONS 1 /* set/get IP per-packet options */ \par \par /* \par * Definitions related to sockets: types, address families, options, \par * taken from the BSD file sys/socket.h. \par */ \par \par /* \par * This is used instead of -1, since the \par * SOCKET type is unsigned. \par */ \par #define INVALID_SOCKET (SOCKET)(~0) \par #define SOCKET_ERROR (-1) \par \par /* \par * Types \par */ \par #define SOCK_STREAM 1 /* stream socket */ \par #define SOCK_DGRAM 2 /* datagram socket */ \par #define SOCK_RAW 3 /* raw-protocol interface */ \par #define SOCK_RDM 4 /* reliably-delivered message */ \par #define SOCK_SEQPACKET 5 /* sequenced packet stream */ \par \par /* \par * Option flags per-socket. \par */ \par #define SO_DEBUG 0x0001 /* turn on debugging info recording */ \par #define SO_ACCEPTCONN 0x0002 /* socket has had listen() */ \par #define SO_REUSEADDR 0x0004 /* allow local address reuse */ \par #define SO_KEEPALIVE 0x0008 /* keep connections alive */ \par #define SO_DONTROUTE 0x0010 /* just use interface addresses */ \par #define SO_BROADCAST 0x0020 /* permit sending of broadcast msgs */ \par #define SO_USELOOPBACK 0x0040 /* bypass hardware when possible */ \par #define SO_LINGER 0x0080 /* linger on close if data present */ \par #define SO_OOBINLINE 0x0100 /* leave received OOB data in line */ \par \par #define SO_DONTLINGER (u_int)(~SO_LINGER) \par \par /* \par * Additional options. \par */ \par #define SO_SNDBUF 0x1001 /* send buffer size */ \par #define SO_RCVBUF 0x1002 /* receive buffer size */ \par #define SO_SNDLOWAT 0x1003 /* send low-water mark */ \par #define SO_RCVLOWAT 0x1004 /* receive low-water mark */ \par #define SO_SNDTIMEO 0x1005 /* send timeout */ \par #define SO_RCVTIMEO 0x1006 /* receive timeout */ \par #define SO_ERROR 0x1007 /* get error status and clear */ \par #define SO_TYPE 0x1008 /* get socket type */ \par \par /* \par {\revised * TCP options. \par } */ \par {\revised #define TCP_NODELAY 0x0001 \par } \par /* \par * Address families. \par */ \par #define AF_UNSPEC 0 /* unspecified */ \par #define AF_UNIX 1 /* local to host (pipes, portals) */ \par #define AF_INET 2 /* internetwork: UDP, TCP, etc. */ \par #define AF_IMPLINK 3 /* arpanet imp addresses */ \par #define AF_PUP 4 /* pup protocols: e.g. BSP */ \par #define AF_CHAOS 5 /* mit CHAOS protocols */ \par #define AF_NS 6 /* XEROX NS protocols */ \par {\revised #define AF_ISO 7 /* ISO protocols */ \par }{\revised #define AF_OSI AF_ISO /* OSI is ISO */ \par }#define AF_ECMA 8 /* european computer manufacturers */ \par #define AF_DATAKIT 9 /* datakit protocols */ \par #define AF_CCITT 10 /* CCITT protocols, X.25 etc */ \par #define AF_SNA 11 /* IBM SNA */ \par #define AF_DECnet 12 /* DECnet */ \par #define AF_DLI 13 /* Direct data link interface */ \par #define AF_LAT 14 /* LAT */ \par #define AF_HYLINK 15 /* NSC Hyperchannel */ \par #define AF_APPLETALK 16 /* AppleTalk */ \par #define AF_NETBIOS 17 /* NetBios-style addresses */ \par \par #define AF_MAX 18 \par \par /* \par * Structure used by kernel to store most \par * addresses. \par */ \par struct sockaddr \{ \par u_short sa_family; /* address family */ \par char sa_data[14]; /* up to 14 bytes of direct address */ \par \}; \par \par /* \par * Structure used by kernel to pass protocol \par * information in raw sockets. \par */ \par struct sockproto \{ \par u_short sp_family; /* address family */ \par u_short sp_protocol; /* protocol */ \par \}; \par \par /* \par * Protocol families, same as address families for now. \par */ \par #define PF_UNSPEC AF_UNSPEC \par #define PF_UNIX AF_UNIX \par #define PF_INET AF_INET \par #define PF_IMPLINK AF_IMPLINK \par #define PF_PUP AF_PUP \par #define PF_CHAOS AF_CHAOS \par #define PF_NS AF_NS \par {\revised #define PF_ISO AF_ISO \par }{\revised #define PF_OSI AF_OSI \par }#define PF_ECMA AF_ECMA \par #define PF_DATAKIT AF_DATAKIT \par #define PF_CCITT AF_CCITT \par #define PF_SNA AF_SNA \par #define PF_DECnet AF_DECnet \par #define PF_DLI AF_DLI \par #define PF_LAT AF_LAT \par #define PF_HYLINK AF_HYLINK \par #define PF_APPLETALK AF_APPLETALK \par \par #define PF_MAX AF_MAX \par \par /* \par * Structure used for manipulating linger option. \par */ \par struct linger \{ \par u_short l_onoff; /* option on/off */ \par u_short l_linger; /* linger time */ \par \}; \par \par /* \par * Level number for (get/set)sockopt() to apply to socket itself. \par */ \par #define SOL_SOCKET 0xffff /* options for socket level */ \par \par /* \par * Maximum queue length specifiable by listen. \par */ \par #define SOMAXCONN 5 \par \par #define MSG_OOB 0x1 /* process out-of-band data */ \par #define MSG_PEEK 0x2 /* peek at incoming message */ \par #define MSG_DONTROUTE 0x4 /* send without using routing tables */ \par \par #define MSG_MAXIOVLEN 16 \par \par /* \par * Define constant based on rfc883, used by gethostbyxxxx() calls. \par */ \par #define MAXGETHOSTSTRUCT 1024 \par \par /* \par * Define flags to be used with the WSAAsyncSelect() call. \par */ \par #define FD_READ 0x01 \par #define FD_WRITE 0x02 \par #define FD_OOB 0x04 \par #define FD_ACCEPT 0x08 \par #define FD_CONNECT 0x10 \par #define FD_CLOSE 0x20 \par \par /* \par * All Windows Sockets error constants are biased by WSABASEERR from \par * the "normal" \par */ \par #define WSABASEERR 10000 \par /* \par * Windows Sockets definitions of regular Microsoft C error constants \par */ \par #define WSAEINTR (WSABASEERR+4) \par #define WSAEBADF (WSABASEERR+9) \par #define WSAEACCES (WSABASEERR+13) \par #define WSAEFAULT (WSABASEERR+14) \par #define WSAEINVAL (WSABASEERR+22) \par #define WSAEMFILE (WSABASEERR+24) \par \par /* \par * Windows Sockets definitions of regular Berkeley error constants \par */ \par #define WSAEWOULDBLOCK (WSABASEERR+35) \par #define WSAEINPROGRESS (WSABASEERR+36) \par #define WSAEALREADY (WSABASEERR+37) \par #define WSAENOTSOCK (WSABASEERR+38) \par #define WSAEDESTADDRREQ (WSABASEERR+39) \par #define WSAEMSGSIZE (WSABASEERR+40) \par #define WSAEPROTOTYPE (WSABASEERR+41) \par #define WSAENOPROTOOPT (WSABASEERR+42) \par #define WSAEPROTONOSUPPORT (WSABASEERR+43) \par #define WSAESOCKTNOSUPPORT (WSABASEERR+44) \par #define WSAEOPNOTSUPP (WSABASEERR+45) \par #define WSAEPFNOSUPPORT (WSABASEERR+46) \par #define WSAEAFNOSUPPORT (WSABASEERR+47) \par #define WSAEADDRINUSE (WSABASEERR+48) \par #define WSAEADDRNOTAVAIL (WSABASEERR+49) \par #define WSAENETDOWN (WSABASEERR+50) \par #define WSAENETUNREACH (WSABASEERR+51) \par #define WSAENETRESET (WSABASEERR+52) \par #define WSAECONNABORTED (WSABASEERR+53) \par #define WSAECONNRESET (WSABASEERR+54) \par #define WSAENOBUFS (WSABASEERR+55) \par #define WSAEISCONN (WSABASEERR+56) \par #define WSAENOTCONN (WSABASEERR+57) \par #define WSAESHUTDOWN (WSABASEERR+58) \par #define WSAETOOMANYREFS (WSABASEERR+59) \par #define WSAETIMEDOUT (WSABASEERR+60) \par #define WSAECONNREFUSED (WSABASEERR+61) \par #define WSAELOOP (WSABASEERR+62) \par #define WSAENAMETOOLONG (WSABASEERR+63) \par #define WSAEHOSTDOWN (WSABASEERR+64) \par #define WSAEHOSTUNREACH (WSABASEERR+65) \par #define WSAENOTEMPTY (WSABASEERR+66) \par #define WSAEPROCLIM (WSABASEERR+67) \par #define WSAEUSERS (WSABASEERR+68) \par #define WSAEDQUOT (WSABASEERR+69) \par #define WSAESTALE (WSABASEERR+70) \par #define WSAEREMOTE (WSABASEERR+71) \par \par /* \par * Extended Windows Sockets error constant definitions \par */ \par #define WSASYSNOTREADY (WSABASEERR+91) \par #define WSAVERNOTSUPPORTED (WSABASEERR+92) \par #define WSANOTINITIALISED (WSABASEERR+93) \par \par /* \par * Error return codes from gethostbyname() and gethostbyaddr() \par * (when using the resolver). Note that these errors are \par * retrieved via WSAGetLastError() and must therefore follow \par * the rules for avoiding clashes with error numbers from \par * specific implementations or language run-time systems. \par * For this reason the codes are based at WSABASEERR+1001. \par * Note also that [WSA]NO_ADDRESS is defined only for \par * compatibility purposes. \par */ \par \par #define h_errno WSAGetLastError() \par \par /* Authoritative Answer: Host not found */ \par #define WSAHOST_NOT_FOUND (WSABASEERR+1001) \par #define HOST_NOT_FOUND WSAHOST_NOT_FOUND \par \par /* Non-Authoritative: Host not found, or SERVERFAIL */ \par #define WSATRY_AGAIN (WSABASEERR+1002) \par #define TRY_AGAIN WSATRY_AGAIN \par \par /* Non recoverable errors, FORMERR, REFUSED, NOTIMP */ \par #define WSANO_RECOVERY (WSABASEERR+1003) \par #define NO_RECOVERY WSANO_RECOVERY \par \par /* Valid name, no data record of requested type */ \par #define WSANO_DATA (WSABASEERR+1004) \par #define NO_DATA WSANO_DATA \par \par /* no address, look for MX record */ \par #define WSANO_ADDRESS WSANO_DATA \par #define NO_ADDRESS WSANO_ADDRESS \par \par /* \par * Windows Sockets errors redefined as regular Berkeley error constants \par */ \par #define EWOULDBLOCK WSAEWOULDBLOCK \par #define EINPROGRESS WSAEINPROGRESS \par #define EALREADY WSAEALREADY \par #define ENOTSOCK WSAENOTSOCK \par #define EDESTADDRREQ WSAEDESTADDRREQ \par #define EMSGSIZE WSAEMSGSIZE \par #define EPROTOTYPE WSAEPROTOTYPE \par #define ENOPROTOOPT WSAENOPROTOOPT \par #define EPROTONOSUPPORT WSAEPROTONOSUPPORT \par #define ESOCKTNOSUPPORT WSAESOCKTNOSUPPORT \par #define EOPNOTSUPP WSAEOPNOTSUPP \par #define EPFNOSUPPORT WSAEPFNOSUPPORT \par #define EAFNOSUPPORT WSAEAFNOSUPPORT \par #define EADDRINUSE WSAEADDRINUSE \par #define EADDRNOTAVAIL WSAEADDRNOTAVAIL \par #define ENETDOWN WSAENETDOWN \par #define ENETUNREACH WSAENETUNREACH \par #define ENETRESET WSAENETRESET \par #define ECONNABORTED WSAECONNABORTED \par #define ECONNRESET WSAECONNRESET \par #define ENOBUFS WSAENOBUFS \par #define EISCONN WSAEISCONN \par #define ENOTCONN WSAENOTCONN \par #define ESHUTDOWN WSAESHUTDOWN \par #define ETOOMANYREFS WSAETOOMANYREFS \par #define ETIMEDOUT WSAETIMEDOUT \par #define ECONNREFUSED WSAECONNREFUSED \par #define ELOOP WSAELOOP \par #define ENAMETOOLONG WSAENAMETOOLONG \par #define EHOSTDOWN WSAEHOSTDOWN \par #define EHOSTUNREACH WSAEHOSTUNREACH \par #define ENOTEMPTY WSAENOTEMPTY \par #define EPROCLIM WSAEPROCLIM \par #define EUSERS WSAEUSERS \par #define EDQUOT WSAEDQUOT \par #define ESTALE WSAESTALE \par #define EREMOTE WSAEREMOTE \par \par /* Socket function prototypes */ \par \par {\revised #ifdef __cplusplus \par }{\revised extern "C" \{ \par }#endif \par \par SOCKET PASCAL FAR accept (SOCKET s, struct sockaddr FAR *addr, \par int FAR *addrlen); \par \par {\revised int PASCAL FAR bind (SOCKET s, const struct sockaddr FAR *addr, int namelen); \par } \par int PASCAL FAR closesocket (SOCKET s); \par \par {\revised int PASCAL FAR connect (SOCKET s, const struct so}{\revised ckaddr FAR *name, int namelen); \par } \par int PASCAL FAR ioctlsocket (SOCKET s, long cmd, u_long FAR *argp); \par \par int PASCAL FAR getpeername (SOCKET s, struct sockaddr FAR *name, \par int FAR * namelen); \par \par int PASCAL FAR getsockname (SOCKET s, struct sockaddr FAR *name, \par int FAR * namelen); \par \par int PASCAL FAR getsockopt (SOCKET s, int level, int optname, \par char FAR * optval, int FAR *optlen); \par \par u_long PASCAL FAR htonl (u_long hostlong); \par \par u_short PASCAL FAR htons (u_short hostshort); \par \par {\revised unsigned long PASCAL FAR inet_addr (const char FAR * cp); \par } \par char FAR * PASCAL FAR inet_ntoa (struct in_addr in); \par \par int PASCAL FAR listen (SOCKET s, int backlog); \par \par u_long PASCAL FAR ntohl (u_long netlong); \par \par u_short PASCAL FAR ntohs (u_short netshort); \par \par int PASCAL FAR recv (SOCKET s, char FAR * buf, int len, int flags); \par \par int PASCAL FAR recvfrom (SOCKET s, char FAR * buf, int len, int flags, \par struct sockaddr FAR *from, int FAR * fromlen); \par \par int PASCAL FAR select (int nfds, fd_set FAR *readfds, fd_set FAR *writefds, \par {\revised fd_set FAR *exceptfds, const struct timeval FAR *timeout); \par } \par {\revised int PASCAL FAR send (SOCKET s, const char FAR * buf, int len, int flags); \par } \par {\revised int PASCAL FAR sendto (SOCKET s, const char FAR * buf, int len, int flags, \par }{\revised const struct sockaddr FAR *to, int tolen); \par } \par int PASCAL FAR setsockopt (SOCKET s, int level, int optname, \par {\revised const char FAR * optva}{\revised l, int optlen); \par } \par int PASCAL FAR shutdown (SOCKET s, int how); \par \par SOCKET PASCAL FAR socket (int af, int type, int protocol); \par \par /* Database function prototypes */ \par \par {\revised struct hostent FAR * PASCAL FAR gethostbyaddr(const char FAR * addr, \par } int len, int type); \par \par {\revised struct hostent FAR * PASCAL FAR gethostbyname(const char FAR * name); \par } \par int PASCAL FAR gethostname (char FAR * name, int namelen); \par \par {\revised struct servent FAR * PASCAL FAR getservbyport(int port, const char FAR }{\revised * proto); \par } \par {\revised struct servent FAR * PASCAL FAR getservbyname(const char FAR * name, \par }{\revised const char FAR * proto); \par } \par struct protoent FAR * PASCAL FAR getprotobynumber(int proto); \par \par {\revised struct protoent FAR * PASCAL FAR getprotobyname(const char FAR * name); \par } \par /* Microsoft Windows Extension function prototypes */ \par \par int PASCAL FAR WSAStartup(WORD wVersionRequired, LPWSADATA lpWSAData); \par \par int PASCAL FAR WSACleanup(void); \par \par void PASCAL FAR WSASetLastError(int iError); \par \par int PASCAL FAR WSAGetLastError(void); \par \par BOOL PASCAL FAR WSAIsBlocking(void); \par \par int PASCAL FAR WSAUnhookBlockingHook(void); \par \par FARPROC PASCAL FAR WSASetBlockingHook(FARPROC lpBlockFunc); \par \par int PASCAL FAR WSACancelBlockingCall(void); \par \par HANDLE PASCAL FAR WSAAsyncGetServByName(HWND hWnd, u_int wMsg, \par {\revised const char FAR * name, \par }{\revised const char FAR * proto, \par } char FAR * buf, int buflen); \par \par HANDLE PASCAL FAR WSAAsyncGetServByPort(HWND hWnd, u_int wMsg, int port, \par {\revised const char FAR * proto, char FAR * buf, \par } int buflen); \par \par HANDLE PASCAL FAR WSAAsyncGetProtoByName(HWND hWnd, u_int wMsg, \par {\revised const char FAR * name, char FAR * buf, \par } int buflen); \par \par HANDLE PASCAL FAR WSAAsyncGetProtoByNumber(HWND hWnd, u_int wMsg, \par int number, char FAR * buf, \par int buflen); \par \par HANDLE PASCAL FAR WSAAsyncGetHostByName(HWND hWnd, u_int wMsg, \par {\revised const char FAR * name, char FAR * buf, \par } int buflen); \par \par HANDLE PASCAL FAR WSAAsyncGetHostByAddr(HWND hWnd, u_int wMsg, \par {\revised const char FAR * addr, int len, int type, \par }{\revised const char FAR * buf, int buflen)}{\revised ; \par } \par int PASCAL FAR WSACancelAsyncRequest(HANDLE hAsyncTaskHandle); \par \par int PASCAL FAR WSAAsyncSelect(SOCKET s, HWND hWnd, u_int wMsg, \par long lEvent); \par \par {\revised #ifdef __cplusplus \par }\} \par #endif \par \par /* Microsoft Windows Extended data types */ \par typedef struct sockaddr SOCKADDR; \par typedef struct sockaddr *PSOCKADDR; \par typedef struct sockaddr FAR *LPSOCKADDR; \par \par typedef struct sockaddr_in SOCKADDR_IN; \par typedef struct sockaddr_in *PSOCKADDR_IN; \par typedef struct sockaddr_in FAR *LPSOCKADDR_IN; \par \par typedef struct linger LINGER; \par typedef struct linger *PLINGER; \par typedef struct linger FAR *LPLINGER; \par \par typedef struct in_addr IN_ADDR; \par typedef struct in_addr *PIN_ADDR; \par typedef struct in_addr FAR *LPIN_ADDR; \par \par typedef struct fd_set FD_SET; \par typedef struct fd_set *PFD_SET; \par typedef struct fd_set FAR *LPFD_SET; \par \par typedef struct hostent HOSTENT; \par typedef struct hostent *PHOSTENT; \par typedef struct hostent FAR *LPHOSTENT; \par \par typedef struct servent SERVENT; \par typedef struct servent *PSERVENT; \par typedef struct servent FAR *LPSERVENT; \par \par typedef struct protoent PROTOENT; \par typedef struct protoent *PPROTOENT; \par typedef struct protoent FAR *LPPROTOENT; \par \par typedef struct timeval TIMEVAL; \par typedef struct timeval *PTIMEVAL; \par typedef struct timeval FAR *LPTIMEVAL; \par \par /* \par * Windows message parameter composition and decomposition \par * macros. \par * \par * WSAMAKEASYNCREPLY is intended for use by the Windows Sockets implementation \par * when constructing the response to a WSAAsyncGetXByY() routine. \par */ \par #define WSAMAKEASYNCREPLY(buflen,error) MAKELONG(buflen,error) \par /* \par * WSAMAKESELECTREPLY is intended for use by the Windows Sockets implementation \par * when constructing the response to WSAAsyncSelect(). \par */ \par #define WSAMAKESELECTREPLY(event,error) MAKELONG(event,error) \par /* \par * WSAGETASYNCBUFLEN is intended for use by the Windows Sockets application \par * to extract the buffer length from the lParam in the response \par * to a WSAGetXByY(). \par */ \par #define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) \par /* \par * WSAGETASYNCERROR is intended for use by the Windows Sockets application \par * to extract the error code from the lParam in the response \par * to a WSAGetXByY(). \par */ \par #define WSAGETASYNCERROR(lParam) HIWORD(lParam) \par /* \par * WSAGETSELECTEVENT is intended for use by the Windows Sockets application \par * to extract the event code from the lParam in the response \par * to a WSAAsyncSelect(). \par */ \par #define WSAGETSELECTEVENT(lParam) LOWORD(lParam) \par /* \par * WSAGETSELECTERROR is intended for use by the Windows Sockets application \par * to extract the error code from the lParam in the response \par * to a WSAAsyncSelect(). \par */ \par #define WSAGETSELECTERROR(lParam) HIWORD(lParam) \par \par #endif /* _WINSOCKAPI_ */ \par \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers}}} {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 #}{\f7 Winsock_NotesForSuppliers}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Windows Sockets \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Notes for Windows Sockets Suppliers{\ul \par }\pard\plain \fs20\lang1033 {\b\f8\uldb Introduction}{\v\f8 WinSockNotes_Introduction}{\b\f7 \par }{\b\f8\uldb Windows Sockets Components}{\v\f8 WinSockNotes_WindowsComponents}{\b\f7 \par }{\b\f8\uldb Multithreadedness and blocking routines.}{\v\f8 WinSockNotes_Multithreadedness}{\b\f7 \par }{\b\f8\uldb Database Files}{\v\f8 WinSockNotes_DatabaseFiles}{\b\f7 \par }{\b\f8\uldb FD_ISSET}{\v\f8 WinSockNotes_FDISSET}{\b\f7 \par }{\b\f8\uldb Error Codes}{\v\f8 Win}{\v\f8 SockNotes_ErrorCodes}{\b\f7 \par }{\b\f8\uldb DLL Ordinal Numbers}{\v\f8 WinSockNotes_DLLOrdinals}{\b\f7 \par }{\b\f8\uldb Validation Suite}{\v\f8 WinSockNotes_Validation}{\b\f7 \par }\pard \par \pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_Introduction}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - Introduction}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0010}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Introduction \par \pard\plain \fs20\lang1033 {\f7 A Windows Sockets implementation must implement ALL the functionality described in the Windows Sockets documentation. Validation of compliance is discussed in }{\f7\uldb Validation Suite}{\v\f7 WinsockNotes_Validation}{ \f7 . \par }\pard {\b\f7 \par }\pard {\f7 Windows Sockets Version 1.1 implementations must support both TCP and UDP type sockets. An implementation may support raw sockets (of typ}{\f7 e SOCK_RAW), but their use is deprecated. \par }\pard {\f7 \par }\pard {\f7 Certain APIs documented above have special notes for Windows Sockets implementors. A Windows Sockets implementation should pay special attention to conforming to the API as documented. The Special Notes are provided for assistance and clarification. \par }\pard {\b\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_WindowsComponents}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - Components}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0020}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Windows Sockets Components \par \pard\plain \fs20\lang1033 {\b\f7 Development Components \par }\pard {\f7 The Windows Sockets development components for use by Windows Sockets application developers will be provided by e}{\f7 ach Windows Sockets supplier. These Windows Sockets development components are: \par }\pard \fi-2880\li2880 {\f7 \par }\pard \fi-3600\li4320\tx4320 {\b\f7\ulw Component\tab Description \par }\pard \fi-3600\li4320\tx4320 {\f7 Windows Sockets Documentation\tab This document \par }{\f7 WINSOCK.LIB file\tab Windows Sockets API Import Library \par }{\f7 WINSOCK.H file\tab Windows Sockets Header File \par }{\f7 NETDB.H file\tab Berkeley Compatible Header File \par }{\f7 ARPA/INET.H file\tab Berkeley Compatible Header File \par }{\f7 SYS/TIME.H file\tab Berkeley Compatible Header File \par }{\f7 SYS/SOCKET.H file\tab Berkeley Compatible Header File \par }{\f7 NETINET/IN.H file\tab Berkeley Compatible Header File \par }\pard \fi-2880\li2880 {\f7 \par }\pard {\b\f7 Run Time Compo}{\b\f7 nents \par }\pard \fi-2880\li2880 {\f7 The run time component provided by each Windows Sockets supplier is: \par }{\f7 \par }\pard \fi-3600\li4320\tx4320 {\b\f7\ulw Component\tab Description \par }\pard \fi-3600\li4320\tx4320 {\f7 WINSOCK.DLL\tab The Windows Sockets API implementation DLL \par }\pard \fi-2880\li2880 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_Multithreadedness}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Multithreadedness and blocking routin}{\f7 es.}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0030}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Multithreadedness and blocking routines. \par \pard\plain \fs20\lang1033 {\f7 Data areas returned by, for example, the }{\f7\uldb getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 routines MUST be on a per thread basis. \par }\pard {\f7 \par }\pard {\f7 Note that an application MUST be prevented from making multiple nested Windows Sockets function calls. Only one outstanding function cal}{\f7 l will be allowed for a particular task. Any Windows Sockets call performed when an existing blocking call is already outstanding will fail with an error code of WSAEINPROGRESS. There are two exceptions to this restriction: }{\f7\uldb WSACancelBlockingCall()}{\v\f7 Winsock_CancelBlockingCall}{\f7 and }{\f7\uldb WSAIsBlocking()}{\v\f7 Winsock_IsBlocking}{\f7 may be called at any time. Windows Sockets suppliers should note that although preliminary drafts of this specification indicated that the restriction only applied to blocking function calls, and t}{\f7 hat it would be permissible to make non-blocking calls while a blocking call was in progress, this is no longer true. \par }\pard {\b\f7 \par }\pard {\f7 Regarding the implementation of blocking routines, the solution in Windows Sockets is to simulate the blocking mechanism by having each routine call PeekMessage() as it waits for the completion of its operation. In anticipation of this, the function }{ \f7\uldb WSASetBlockingHook()}{\v\f7 Winsock_SetBlockingHook}{\f7 is provided to allow the programmer to define a special routine to be called instead of the defa}{\f7 ult PeekMessage() loop. The blocking hook functions are discussed in more detail in } {\f7\uldb WSASetBlockingHook()}{\v\f7 Winsock_SetBlockingHook}{\f7 . \par }\pard {\b\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_DatabaseFiles}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - Database Files}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0040}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Database Files \par \pard\plain \fs20\lang1033 {\f7 The database routines in the }{\b\f7\uldb getXbyY()}{\v\f7 WinsockOverview_DatabaseFunctions}{\f7 family (}{\b\f7 gethostbyaddr()}{\f7 , etc.) were originally designed (in the first Berkeley UNIX releases) as mechanisms for looking up information in text databases. A Windows Sockets supplier may choose to employ local files OR a name service to provide s}{\f7 ome or all of this information. If local files exist, the format of the files must be identical to that used in BSD UNIX, allowing for the differences in text file formats. \par }\pard {\b\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_FDISSET}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $ }{\f7 Notes for Windows Sockets Suppliers - FD_ISSET}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0050}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K }{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 FD_ISSET \par \pard\plain \fs20\lang1033 {\f7 It is necessary to implement the FD_ISSET Berkeley macro using a supporting function: }{\b\f7 __WSAFDIsSet()}{\f7 . It is the responsibility of a Windows Sockets implementation to make this available as part of the Windows Sockets API. Unlike the other functions exported by a Windows Sock}{\f7 ets DLL, however, this function is not intended to be invoked directly by Windows Sockets applications: it should be used only to support the FD_ISSET macro. The source code for this function is listed below: \par }\pard {\f7 \par }\pard\plain \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 int FAR \par __WSAFDIsSet(SOCKET fd, fd_set FAR *set) \par \{ \par int i = set->count; \par \par while (i--) \par \tab if (set->fd_array[i] == fd) \par \tab return 1; \par \par return 0; \par \} \par \pard\plain \fs20\lang1033 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_ErrorCodes}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - Error Codes}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0060}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Error Codes \par \pard\plain \fs20\lang1033 {\f7 In order to avoid conflict between various compiler environments Windows Sockets impl}{\f7 ementations MUST return the error codes listed in the API specification, using the manifest constants beginning with "WSA". The Berkeley-compatible error code definitions are provided solely for compatibility purposes for applications which are being por }{\f7 ted from other platforms. \par }\pard {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_DLLOrdinals}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - DLL Ordinals}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0070}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes }{\f7 for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 DLL Ordinal Numbers \par \pard\plain \fs20\lang1033 {\f7\revised The }{\b\f7\revised winsock.def }{\f7\revised file for use by every Windows Sockets implementation is as follows. Ordinal values starting at 1000 are reserved for Windows Sockets implementor}{\f7\revised s to use for exporting private interfaces to their DLLs. A Windows Sockets implementation must not use any ordinals 999 and below except for those APIs listed below. An application which wishes to work with any Windows Sockets DLL must use only those ro }{\f7\revised utines listed below; using a private export makes an application dependent on a particular Windows Sockets implementation. \par }\pard {\f7 \par }\pard\plain \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 \f5\fs16\lang1033 ; \par ; File: winsock.def \par ; System: MS-Windows 3.x \par ; Summary: Module definition file for Windows Sockets DLL. \par ; \par \par LIBRARY WINSOCK ; Application's module name \par \par DESCRIPTION 'BSD Socket API for Windows' \par \par EXETYPE WINDOWS ; required for all windows applications \par \par STUB 'WINSTUB.EXE' ; generates error message if application \par ; is run without Windows \par \par ;CODE can be FIXED in memory because of potential upcalls \par CODE PRELOAD FIXED \par \par ;DATA must be SINGLE and at a FIXED location since this is a DLL \par DATA PRELOAD FIXED SINGLE \par \par HEAPSIZE 1024 \par STACKSIZE 16384 \par \par ; All functions that will be called by any Windows routine \par ; must be exported. Any additional exports beyond those defined \par ; here must have ordinal numbers 1000 or above. \par \par EXPORTS \par accept @1 \par bind @2 \par closesocket @3 \par connect @4 \par getpeername @5 \par getsockname @6 \par getsockopt @7 \par htonl @8 \par htons @9 \par inet_addr @10 \par inet_ntoa @11 \par ioctlsocket @12 \par listen @13 \par ntohl @14 \par ntohs @15 \par recv @16 \par recvfrom @17 \par select @18 \par send @19 \par sendto @20 \par setsockopt @21 \par shutdown @22 \par socket @23 \par \par gethostbyaddr @51 \par gethostbyname @52 \par getprotobyname @53 \par getprotobynumber @54 \par getservbyname @55 \par getservbyport @56 \par gethostname @57 \par \par WSAAsyncSelect @101 \par WSAAsyncGetHostByAddr @102 \par WSAAsyncGetHostByName @103 \par WSAAsyncGetProtoByNumber @104 \par WSAAsyncGetProtoByName @105 \par WSAAsyncGetServByPort @106 \par WSAAsyncGetServByName @107 \par WSACancelAsyncRequest @108 \par WSASetBlockingHook @109 \par WSAUnhookBlockingHook @110 \par WSAGetLastError @111 \par WSASetLastError @112 \par WSACancelBlockingCall @113 \par WSAIsBlocking @114 \par WSAStartup @115 \par WSACleanup @116 \par \par __WSAFDIsSet @151 \par \par WEP @500 RESIDENTNAME \par \par ;eof \par \pard \s30\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760 {\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSockNotes_Validation}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Notes for Windows Sockets Suppliers - Validation Suite}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSockN:0080}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Notes for Suppliers}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Validation Suite \par \pard\plain \sb240 \fs20\lang1033 {\f7\revised The }{\f7\revised Windows Sockets API Tester (WSAT) to ensure Windows Sockets compatibility between Windows Sockets DLL implementations is currently in beta test. This beta version includes functionality testing of the Windows Sockets interface and is supported by a compr }{\f7\revised ehensive scripting language. The final version of WSAT will be available in Spring 1993. If you wish to receive the tester or more information on the beta, send email to wsat@microsoft.com. }{\f7 \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 WinSock_FurtherReference}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 For Further Reference}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0065}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 References}}} Notes for Windows Sockets Suppliers \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised For Further Refer}{\revised ence \par }\pard\plain \fs20\lang1033 {\f7 \par }\pard {\f7\revised This specification is intended to cover the Windows Sockets interface to TCP/IP in detail. Many details of TCP/IP and Windows, however, are intentionally omitted in the interest of brevity, and this specification often assumes background knowledge of the }{\f7\revised se topics. For more information, the following references may be helpful: \par }\pard {\f7 \par }\pard\plain \s22\fi-1440\li1440 \fs20\lang1033 {\f7\revised Braden, R.[1989], }{\i\f7\revised RFC 1122, Requirements for Internet Hosts--Communication Layers}{\f7\revised , Internet Engineering Task Force. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard \s22\fi-1440\li1440 {\f7\revised Comer, D. [1991], }{\i\f7\revised Internetworking with TCP/IP Volume}{\i\f7\revised I: Principles, Protocols, and Architecture, }{\f7\revised Prentice Hall, Englewood Cliffs, New Jersey. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard \s22\fi-1440\li1440 {\f7\revised Comer, D. and Stevens, D. [1991], }{\i\f7\revised Internetworking with TCP/IP Volume II: Design, Implementation, and Internals, }{\f7\revised Prentice Hall, Englewood Cliffs, New Jersey. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard \s22\fi-1440\li1440 {\f7\revised Comer, D. and Stevens, D. [1991], }{\i\f7\revised Internetworking with TCP/IP Volume III: Client-Server Programming and Applications, }{\f7\revised Prentice Hall, Englewood Cliffs, New Jersey. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard \s22\fi-1440\li1440 {\f7\revised Leffler, S. et al., }{\i\f7\revised An Advanced 4.3BSD Interprocess Communication Tutorial.}{\f7\revised \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard \s22\fi-1440\li1440 {\f7\revised Petzold, C. [1}{\f7\revised 992], }{\i\f7\revised Programming Windows 3.1, }{\f7\revised Microsoft Press, Redmond, Washington. \par }\pard \s22\fi-1440\li1440 {\f7 \par }\pard\plain \sb240 \fs20\lang1033 {\f7\revised Stevens, W.R. [1990], }{\i\f7\revised Unix Network Programming, }{\f7\revised Prentice Hall, Englewood Cliffs, New Jersey. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 {\ulw \page }{\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_Origins}}}{\ulw }{\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 $}{\f7 Origins of Windows Sockets}}}{\ulw }{\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0070}}}{\ulw }{\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 { \f7\fs16\up6 K}{\f7 Background Information}}}{\ulw }Background Information{\ulw \par }\pard\plain \s34\qc\sa240 \b\f7\lang1033 Origins of Windows Sockets \par \pard\plain \fs20\lang1033 {\f7 The Windows Sockets project had its origins in a Birds Of A Feather session held at Interop '91 in San Jose on October 10, 1991. A committee was established, and an intensive debate via email resulted in the creation of a first draft specification, which }{\f7 was largely based on submissi}{\f7 ons from JSB and NetManage. This draft, and issues arising from it, were debated at a committee meeting hosted by Microsoft in Redmond, WA on December 9, 1991. Following further email discussions, a working group was established to develop the specifica }{\f7 tion into its current form. \par }\pard {\f7 \par }\pard {\f7 The following people participated in the process as committee members, in working meetings, or in email review. The authors would like to thank everyone who participated in any way, and apologize in advance if we have omitted}{\f7 anyone. \par }\pard {\f7 \par }\pard \tx2880\tx5760\tx8640 {\f7 Martin Hall (Moderator)\tab JSB Corporation\tab martinh@jsbus.com \par }{\f7 Mark Towfiq (Coordinator)\tab Microdyne Corporation\tab towfiq@microdyne.com \par }{\f7 Geoff Arnold\tab Sun Microsystems, Inc.\tab geoff@east.sun.com \par }{\f7 Alistair Banks\tab Microsoft\tab alistair@microsoft.com \par }{\f7 Carl Beame\tab Beame & Whiteside\tab beame@mcmaster,ca \par }{\f7 David Beaver\tab Microsoft\tab dbeaver@microsoft.com \par }{\f7 Amatzia BenArtzi\tab NetManage, Inc.\tab amatzia@netmanage.com \par }{\f7 Mark Beyer\tab Ungermann-Bass\tab mbeyer@ub.com \par }{\f7 James Van Bokkelen\tab FTP Software\tab jbvb@ftp.com \par }{\f7 Nelson Bolyard\tab Silicon Graphi}{\f7 cs, Inc.\tab nelson@sgi.com \par }{\f7 Pat Bonner\tab Hewlett-Packard\tab p_bonner@cnd.hp.com \par }{\f7 Isaac Chan\tab Microsoft\tab isaacc@microsoft.com \par }{\f7 Nestor Fesas\tab Hughes LAN Systems\tab nestor@hls.com \par }{\f7 Gary Gere\tab Gupta\tab ggere@gupta.com \par }{\f7 Bill Hayes\tab Hewlett-Packard\tab billh@hpchdpc.cnd.hp.com \par }{\f7 Hoek Law\tab Citicorp\tab law@dcc.tti.com \par }{\f7 Paul Hill\tab MIT\tab pbh@athena.mit.edu \par }{\f7 Graeme Le Roux\tab Moresdawn P/L\tab - \par }{\f7 Terry Lister\tab Hewlett-Packard\tab tel@cnd.hp.com \par }{\f7 Lee Murach\tab Network Research\tab lee@nrc.com \par }{\f7 David Pool\tab Spry, Inc.\tab dave@spry.com \par }{\f7 Brad Rice\tab Age\tab rice@age.com \par }{\f7 Allen Roch}{\f7 kind\tab 3Com\tab - \par }{\f7 Henry Sanders\tab Microsoft\tab henrysa@microsoft.com \par }{\f7 David Treadwell\tab Microsoft\tab davidtr@microsoft.com \par }{\f7 Miles Wu\tab Wollongong\tab wu@twg.com \par }{\f7 Boris Yanovsky\tab NetManage, Inc.\tab boris@netmanage.com \par }{\f7 J Allard\tab Microsoft Corporation\tab jallard@microsoft.com \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_LegalStatus}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $} {\f7 Legal Status of Windows Sockets}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0080}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Background Information}}} Background Information \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 Legal Status of Windows Sockets \par \pard\plain \fs20\lang1033 {\f7\revised The copyright for the Windows Sockets specification is owned by the specification authors listed on the title page. Permission is granted to redistribute this specification in any form, provided tha}{\f7\revised t the contents of the specification are not modified. Windows Sockets implementors are encouraged to include this specification with their product documentation. \par }\pard {\f7 \par }\pard {\f7\revised The Windows Sockets logo on the title page of this document is meant for use on both Windows Sockets implementations and for applications that use the Windows Sockets interface. Use of the logo is encouraged on packaging, documentation, collateral, and a }{\f7\revised dvertising. The logo is \par }\pard {\f7\revised available on microdyne.com in pub/winsock as winsock.bmp. The s}{\f7\revised uggested color for the logo's title bar is blue, the electrical socket grey, and the text and outline black. \par }\pard\plain \s35\sa240 \b\f7\fs20\lang1033 \page {\plain \fs16\up6\lang1033 #{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 #}{\f7 Winsock_IconStory}}} {\plain \fs16\up6\lang1033 ${\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 $}{ \f7 The Story Behind the Icon}}} {\plain \fs16\up6\lang1033 +{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 +}{\f7 WinSock:0090}}} {\plain \fs16\up6\lang1033 K{\footnote \pard\plain \s245 \fs20\lang1033 {\f7\fs16\up6 K}{\f7 Background Information}}} Background Information \par \pard\plain \s34\qc\sa240 \b\f7\lang1033 {\revised The Story Behind the Windows Sockets Icon \par }\pard\plain \fs20\lang1033 {\f7\revised (by Alistair Banks, Microsoft Corporation) \par }{\f7 \par }\pard {\f7\revised We thought we'd do a "Wind Sock" at one stage--but you try to get that into 32x32 bits! It would have had to look wavy and colorful, and... well, it just didn't work. Also, our graphics designers have "opinions"}{\f7 }{\f7\revised about the icons truly representing what they are--people would hav}{\f7\revised e thought this was "The colorful wavy tube specification 1.0!" \par }\pard {\f7 \par }\pard {\f7\revised I tried to explain "API" "Programming Interface" to the artist--we ended up with toolbox icons with little flying windows \par }\pard {\f7 \par }\pard {\f7\revised Then we came to realise that we should be going after the shortened form of the name, rather the name in full... Windows Sockets... And so we went for that - so she drew (now remember I'm English and you're}{\f7 }{\f7\revised probably American) "Windows Spanner", a.k.a. a socket wrench. In the U.S. you'd have been talking about the "Wind}{\f7\revised ows Socket spec" OK, but in England that would have been translatated as "Windows Spanner Spec 1.0" - so we went to Electrical sockets - well the first ones came out looking like "Windows Pignose Spec 1.0"!!!! \par }\pard {\f7 \par }\pard {\f7\revised So how do you use 32x32, get an international electrical socket! You take the square type (American & English OK, Europe & Australia are too rounded)--you choose the American one, because it's on the wall in front of you (and it's more compact (but less s }{\f7\revised afe, IMHO) and then you turn it upside down,}{\f7\revised thereby compromising its nationality! \par }\pard {\f7 \par }{\f7\revised [IMHO = "In My Humble Opinion"--ed.] \par }{\f7 \par }{\f7 \{bmc winsock.bmp\} \par }{\f7 \par }}